DEV Community: harry

Using DDD with Recoil

harry — Sun, 22 Jan 2023 11:26:19 +0000

Introduction

The following repository code is presented as an "Interactive Tutorial" on the official Recoil website.

https://github.com/SideGuide/recoil-example

I will try to rewrite this code using the design method I use in my published application. The target readers are those who have already read the Getting Started and Tutorial of Recoil. Therefore, I will not provide a basic explanation of Recoil in this article.

I designed my application with two things in mind.

Ensure domain layer independence
Concerns about rendering performance

My application has an ability to add and subtract values by holding down a button. So rendering time for a single change is less than 20ms, even in development mode.

When actually running in development mode, the screen is rendered as follows.

// Detect dark theme var iframe = document.getElementById('tweet-1606582520400973826-101'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1606582520400973826&theme=dark" }

Assumptions

Using TypeScript
Domain logic has no asynchronous processing, only pure processing

All of the artifacts in this article

https://github.com/harry0000/recoil-todo-app

original tag: Code copied from the original repository and minimally typed in TypeScript
refactored tag: Code that reflects the changes made in this article

💥 Problems with this Todo app

Let's try to run this Todo application with a new project and minimal typing in TypeScript. Then all components will be re-rendered just by changing the checkbox of an item. There is no point in using Recoil.

In addition, because it is simplified sample code, the domain logic is not cohesive and is not easy to test and maintain.

🛠 Let's refactor

1. Cohesive domain logic

Put together our domain logic in the domain directory.

The important point here is that Recoil expects immutable values to be stored, as evidenced by the fact that it freezes the values stored in development mode. Therefore, if you are building object-based domain code, implement it so that it returns a new object when the result of the logic execution changes, and if it is class-based, implement it as an immutable class.

The object-based implementation was used in the original Todo application and is probably already familiar to front-end engineers, so this time I will try a class-based implementation. I will keep the function names in the original code as much as possible, and aggregate the domain logic.

When testing these domain codes, you simply write test code similar to testing a class.

2. Implementing the Recoil state module

Now that the domain logic is implemented, all we need to do is store it in an atom, get the value with a selector, and we're done?

However, this is not the case, and the get of the selector is re-evaluated when the dependent atom is updated, which can cause unnecessary re-rendering. If the type of the value to get is of a type (e.g. object, array) whose equivalence cannot be determined by the strict equality operator (===), and where the cached value is not expected to be used by the selector, you should generally consider using selector for values that always change when the dependent atom is updated. However, it is a bit odd that the state layer always needs to know if the value has changed after the domain logic is executed. Also, as in the case of this Todo application, it seems to me that it is a rare case where all values change after a particular domain logic is executed.

My application uses objects like { value: number }, { milliValue: number }, and { microValue: number } in the domain logic, which cannot determine equivalence of values with === operators and in many cases I cannot expect the selector cache to be used.

Implementation policy

What is the policy for implementation?

Prepare separate Recoil state values to store the values referenced by each component.
Export only two types of elements from the state module.
1. RecoilValueReadOnly to reference the state
2. Callback functions to update the state
When the callback is invoked, the domain logic is executed and each value is stored in the state prepared in point 1.

In one sentence, the states referenced by each component are prepared separately, and the state update logic is hidden in the state module.

The reason for doing it like point 1 is to use the state only where it is displayed, as in the following video thumbnail. This ensures that only components that reference values that have actually changed are re-rendered.

However, if you export these RecoilState as they are, useRecoilState() can be called on any component, and the state can be changed from anywhere and in any way, and the integrity of the state cannot be guaranteed. At least for now, Recoil does not have the ability to change other atoms in response to a change in a particular atom.

So, using TypeScript, cast RecoilState to the type RecoilValueReadOnly and export it. Now any component cannot call anything on this state except useRecoilValue().

My personal practice is to give a short, free name in high context to the states that are not exported, but to export states I use a name that can be understood by external modules, and I always add the suffix State.

Example:

const _foo = atomFamily<boolean, number>({
  key: 'somestate_foo',
  default: false
});

export const fooState: (id: number) => RecoilValueReadOnly<boolean> =
  _fooState(id);

This time we need to prepare these states:

Text and completion status for each todo
Filter for todo list
List of filtered todo lists
Total number of todos
Total number of completed todos
Total number of incomplete todos
Percentage of completed todos
Text list of incomplete todos

Each state requires an initial value defined in the domain logic. The state is updated by a callback that is exported separately. Basically, it is someone (or something) outside the state module that executes the trigger that changes the state, so we provide the means to do so by exporting a callback.

Recoil provides a way to get/set the state with a callback. This callback is actually used via useRecoilCallback() in components and custom hooks, so it needs to be defined with a type like CallbackInterface => (...any[]) => any.

In this case we would define a callback of the following type:

{
  addTodoItem: (cbi: CallbackInterface) => (text: string): void;

  editTodoItemText: (cbi: CallbackInterface) => (id: TodoItemId, text: string): void;

  toggleTodoItemCompletion: (cbi: CallbackInterface) => (id: TodoItemId): void;

  deleteTodoItem: (cbi: CallbackInterface) => (id: TodoItemId): void;

  updateFilter: (cbi: CallbackInterface) => (filter: TodoListFilter): void;
}

It is possible to get the state via snapshot of CallbackInterface and update the state via set / reset.

Type definition of CallbackInterface:

type CallbackInterface = {
  snapshot: Snapshot,
  gotoSnapshot: Snapshot => void,
  set: <T>(RecoilState<T>, (T => T) | T) => void,
  reset: <T>(RecoilState<T>) => void,
  refresh: <T>(RecoilValue<T>) => void,
  transact_UNSTABLE: ((TransactionInterface) => void) => void,
};

Example of getting a value using a snapshot:

Since it is assumed that there is no asynchronous processing in the domain logic, you can get the value synchronously from the state.

import { GetRecoilValue } from 'recoil';

const get: GetRecoilValue = (recoilVal) => snapshot.getLoadable(recoilVal).getValue();

const someValue = get(someState);

Actual implementation code

There are two possible implementations of the state module: value/function-based and class-based.

value/function-based: Value and function are defined at the top level of the module
class-based: Defining a class and exporting its singleton instance

Since the original Todo application is value/function-based and there is nothing unusual about it, I want to implement it as class-based this time. In the case of class-based, since the recoil state is defined in the field of the class, only a single instance is exported since the definition of the state (key) will be duplicated if multiple instances are created.

src/state/recoil_state.ts

class TodoState {
  // ...
}

export const todoState = new TodoState();

It would be more appropriate to rename the file to TodoState.ts, but I left it as is.

If you want to implement a value/function-based module, move each field of the class to the top level of the module and export the field that was public. Note that you cannot use # as a variable prefix, you must change it to _ or something similar.

As for the state that each component refers to, just cast the defined one with RecoilValueReadOnly and export it as described above.

For the todo list, detailed information about each todo is obtained from the end components that display it, so its type is defined as atom<ReadonlyArray<TodoItemId>() and the id is passed as props in the component. Then the todo text and completion state are held in atomFamily<string, TodoItemId>() and atomFamily<boolean, TodoItemId>() respectively.

The code for the definition section is omitted here, but one point should be mentioned: code completion may be easier if state is defined in meaningful block units.

src/state/recoil_state.ts#L58-L61

  readonly #items = {
    text: atomFamily<string, TodoItemId>({ key: 'TodoState.#items.text', default: TodoItem.initialState.text}),
    completion: atomFamily<boolean, TodoItemId>({ key: 'TodoState.#items.completion', default: TodoItem.initialState.isComplete})
  };

Now let's write the process of storing a value in state when each callback is invoked. We can simplify the implementation of all callbacks by preparing an atom that stores the domain object and creating a #updateState like this:

class TodoState {

  readonly #itemContainer = atom({
    key: 'TodoState.#itemContainer',
    default: TodoItemContainer.create()
  });

  // ...

  #updateState = ({ set, reset, snapshot }: CallbackInterface) => (updater: (state: TodoItemContainer) => TodoItemContainer): void => {
    // TODO: implement
  }

  // ...

  readonly addTodoItem = (cbi: CallbackInterface) => (text: string): void => {
    this.#updateState(cbi)(state => state.addItem(text));
  };

  readonly editTodoItemText = (cbi: CallbackInterface) => (id: TodoItemId, text: string): void => {
    this.#updateState(cbi)(state => state.editItemText(id, text));
  };

  readonly toggleTodoItemCompletion = (cbi: CallbackInterface) => (id: TodoItemId): void => {
    this.#updateState(cbi)(state => state.toggleItemCompletion(id));
  };

  readonly deleteTodoItem = (cbi: CallbackInterface) => (id: TodoItemId): void => {
    this.#updateState(cbi)(state => state.deleteItem(id));
  };

  readonly updateFilter = (cbi: CallbackInterface) => (filter: TodoListFilter): void => {
    this.#updateState(cbi)(state => state.setFilter(filter));
  };
}

All that remains is to implement #updateState. Since we implemented the domain object in the immutable class, we can set the updated value without thinking about anything in particular. Also, if the type of the state can be determined to be equivalent with the === operator, it can be set as is, since update propagation and re-rendering will not be performed if it is the same as the previous value.

The problem is with arrays, objects, etc., where even if the values are equivalent, if the references are different, the comparison with the === operator will result in false and state update propagation and re-rendering will occur. So, use fast-deep-equal to compare with the previous value and set only if there is a change. Unless it is a very special case, the cost of a fast-deep-equal comparison should be less than the cost of a re-rendering without it.

In addition, when deletions may occur as a result of updates, as in this Todo application, it is necessary to reset the state by comparing it to the previous state and identifying the deleted items.

These points should be noted and implemented:

src/state/recoil_state.ts#L63-L97

  #updateState = ({ set, reset, snapshot }: CallbackInterface) => (updater: (state: TodoItemContainer) => TodoItemContainer): void => {
    const get: GetRecoilValue = (recoilVal) => snapshot.getLoadable(recoilVal).getValue();

    const prevState = get(this.#itemContainer);
    const nextState = updater(prevState);
    set(this.#itemContainer, nextState);

    set(this.#filter, nextState.filter);

    const prevFilteredIds = get(this.#filteredItemIds);
    const nextFilteredIds = nextState.filteredItems.map(({ id }) => id);
    if (!deepEqual(prevFilteredIds, nextFilteredIds)) {
      set(this.#filteredItemIds, nextFilteredIds);
    }

    set(this.#numOfTotal, nextState.numOfTotal);
    set(this.#numOfCompleted, nextState.numOfCompleted);
    set(this.#numOfUncompleted, nextState.numOfUncompleted);
    set(this.#percentCompleted, nextState.percentCompleted);

    const prevTexts = get(this.#uncompletedTexts);
    const nextTexts = nextState.uncompletedItems.map(({ text }) => text);
    if (!deepEqual(prevTexts, nextTexts)) {
      set(this.#uncompletedTexts, nextTexts);
    }

    getDeletedItemIds(prevState, nextState).forEach(id => {
      reset(this.#items.text(id));
      reset(this.#items.completion(id));
    });
    nextState.items.forEach(({ id, text, isComplete }) => {
      set(this.#items.text(id), text);
      set(this.#items.completion(id), isComplete);
    });
  }

🚨 Another thing to note is that the value you can get from a snapshot during a callback call is always the same. That is, if you get a value via snapshot after set, it will not be updated to the value you just set, but will remain the same as it was before set.

3. Implementing Components

Finally, we are ready to use the Recoil state in components.

In this example code, I will call useRecoilValue() and useRecoilCallback() directly in the component, but you can create custom hooks if you want.

Referring to the state

If you want to refer to a state like the thumbnail in the official Recoil video, refer to it in the node (component) at the end of the DOM tree as much as possible to display it.

In this Todo application, the code in TodoListStats.tsx is the simplest example:

src/component/TodoListStats.tsx

import React from 'react';
import { useRecoilValue } from 'recoil';

import { todoState } from '../state/recoil_state';

const {
  todoListTotalState,
  todoListTotalCompletedState,
  todoListTotalUncompletedState,
  todoListPercentCompletedState,
  todoListNotCompletedTextsState
} = todoState;

const Total = () => {
  const totalNum = useRecoilValue(todoListTotalState);

  return (<span>{totalNum}</span>);
};

const TotalCompleted = () => {
  const totalCompletedNum = useRecoilValue(todoListTotalCompletedState);

  return (<span>{totalCompletedNum}</span>);
};

const TotalUncompleted = () => {
  const totalUncompletedNum = useRecoilValue(todoListTotalUncompletedState);

  return (<span>{totalUncompletedNum}</span>);
};

const FormattedPercentCompleted = () => {
  const percentCompleted = useRecoilValue(todoListPercentCompletedState);
  const formattedPercentCompleted = Math.round(percentCompleted * 100);

  return (<span>{formattedPercentCompleted}</span>);
};

const UncompletedTexts = () => {
  const texts = useRecoilValue(todoListNotCompletedTextsState);

  return (<span>{texts.join(' ')}</span>);
};

const TodoListStats = () => {
  return (
    <ul>
      <li>Total items: <Total /></li>
      <li>Items completed: <TotalCompleted /></li>
      <li>Items not completed: <TotalUncompleted /></li>
      <li>Percent completed: <FormattedPercentCompleted /></li>
      <li>Text not completed: <UncompletedTexts /></li>
    </ul>
  );
};

export default TodoListStats;

Update the state

Just get the callback with useRecoilCallback() and call it when you need it.

src/component/TodoItemCreator.tsx

import React, { ChangeEventHandler, useState } from 'react';
import { useRecoilCallback } from 'recoil';

import { todoState } from '../state/recoil_state';

function TodoItemCreator() {
  const [inputValue, setInputValue] = useState('');
  const addTodoItem = useRecoilCallback(todoState.addTodoItem);

  const addItem = () => {
    addTodoItem(inputValue);
    setInputValue('');
  };

  const onChange: ChangeEventHandler<HTMLInputElement> = ({ target: { value } }) => {
    setInputValue(value);
  };

  return (
    <div>
      <input type="text" value={inputValue} onChange={onChange} />
      <button onClick={addItem}>Add</button>
    </div>
  );
}

export default TodoItemCreator;

One last push

When I check the behavior after changing all the components, I notice that each row of the todo list is re-rendered when a todo is added, for example. It seems that the TodoItemList component in TodoList.tsx updates the filtered todo list when it renders. Currently the TodoItem component only gets TodoItemId in its props, so we can suppress the re-rendering by memoization.

src/component/TodoItem.tsx#L41-L49

const TodoItem: React.FC<{ itemId: TodoItemId }> = React.memo(({ itemId }) => {
  return (
    <div>
      <TodoItemTextField itemId={itemId} />
      <TodoItemCompletionCheckbox itemId={itemId} />
      <TodoItemDeleteButton itemId={itemId} />
    </div>
  );
});

🎉 After refactoring

With all the changes made, let's see how it works. Unlike the original Todo application, only the components that reference the updated values should be re-rendered.

Conclusion

In this article, I have presented an example of a design that combines independent domain layer and Recoil so that only components that actually refer to the changed values are re-rendered. I hope this article will be helpful to anyone reading it for design ideas. And please share your own Recoil state layer design patterns with me!

Appendix

⚠ Notes on class-based state module

For example, when other singleton instances are referenced in a class, if the references are interdependent, a deadlock occurs and the creation of that singleton instance fails, resulting in a runtime error.

Therefore, if you want to use the updated values of other modules in a particular state module to perform update processing, you will have to be creative.

The other caveat is that you should always implement all members as fields. If implemented as getter or method, using a singleton instance as follows will cause an error at runtime because this in the getter or method will be undefined.

import { fooState } from './state/FooState';

const {
  oneState,
  twoState,
  // ... many other states ...
  someCallback
} = fooState;

// ...

  // If `someCallback` is a method of `fooState`,
  // then `this` in `someCallback` is `undefined`.
  someCallback();

// ...

More powerful type definitions for Object.entries()

harry — Thu, 10 Mar 2022 07:53:07 +0000

Introduction

Object.entries<T>() has the following type definition (typing) as standard in TypeScript and returns an array of type [string, T].

https://github.com/microsoft/TypeScript/blob/v4.6.2/lib/lib.es2017.object.d.ts#L34-L44

    /**
     * Returns an array of key/values of the enumerable properties of an object
     * @param o Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
     */
    entries<T>(o: { [s: string]: T } | ArrayLike<T>): [string, T][];

    /**
     * Returns an array of key/values of the enumerable properties of an object
     * @param o Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
     */
    entries(o: {}): [string, any][];

There is nothing wrong with this definition itself, but there are cases where you want to get a type like <K = keyof T> [`${K}`, T[K]][] from Object.entries() when passed an object generated by pure processing without side-effects (*1).

*1: If it is clear that there are only key-value type combinations defined by type in the object, rather than an object obtained via a side-effect such as the REST API call. (See also #Appendix of this article)

Type definitions

In such cases, the following type definitions can be defined to get the expected type.

type TupleEntry<T extends readonly unknown[], I extends unknown[] = [], R = never> =
  T extends readonly [infer Head, ...infer Tail] ?
    TupleEntry<Tail, [...I, unknown], R | [`${I['length']}`, Head]> :
    R

// eslint-disable-next-line @typescript-eslint/ban-types
type ObjectEntry<T extends {}> =
  // eslint-disable-next-line @typescript-eslint/ban-types
  T extends object ?
    { [K in keyof T]: [K, Required<T>[K]] }[keyof T] extends infer E ?
      E extends [infer K, infer V] ?
        K extends string | number ?
          [`${K}`, V] :
          never :
        never :
      never :
    never

// eslint-disable-next-line @typescript-eslint/ban-types
export type Entry<T extends {}> =
  T extends readonly [unknown, ...unknown[]] ?
    TupleEntry<T> :
    T extends ReadonlyArray<infer U> ?
      [`${number}`, U] :
      ObjectEntry<T>

// eslint-disable-next-line @typescript-eslint/ban-types
export function typedEntries<T extends {}>(object: T): ReadonlyArray<Entry<T>> {
  return Object.entries(object) as unknown as ReadonlyArray<Entry<T>>;
}

Examples of type definition usage

Calling typedEntries() function, which wraps Object.entries(), returns an array of entry types inferred according to the argument type.

TypeScript: TS Playground

type StringKeyRecordEntry = Entry<Record<string, boolean>>
// [string, boolean]

type NumberKeyRecordEntry = Entry<Record<number, boolean>>
// [`${number}`, boolean]

type UnionKeyRecordEntry = Entry<Record<'foo' | 'bar', boolean>>
// ['foo', boolean] | ['bar', boolean]

type ObjectType = {
  a: number,
  b?: string,
  c: number | undefined,
  d?: string | undefined
}

type ObjectTypeEntry = Entry<ObjectType>
// if disabled exactOptionalPropertyTypes option
//   ["a", number] | ["b", string] | ["c", number | undefined] | ["d", string]
// if enabled exactOptionalPropertyTypes option
//   ["a", number] | ["b", string] | ["c", number | undefined] | ["d", string | undefined]

const constObject = {
  a: "foo",
  b: 42,
  c: false,
  1: { type: "number" }
} as const;

type ConstObjectEntry = Entry<typeof constObject>
// ["a", "foo"] | ["b", 42] | ["c", false] | ["1", { readonly type: "number"; }]

type UnionObject = (
  { gt?: number } &
  { lt?: number }
) |
  { between: [number, number] }

type UnionObjectEntry = Entry<UnionObject>
// ["gt", number] | ["lt", number] | ["between", [number, number]]

const someSymbol = Symbol('some');

interface IPerson {
  age?: number;
  name: string;
  [someSymbol] : Date;
}

type InterfaceEntry = Entry<IPerson>
// ["age", number] | ["name", string]

type ArrayEntry = Entry<Array<number>>
// [`${number}`, number]

type ReadonlyArrayEntry = Entry<ReadonlyArray<boolean>>
// [`${number}`, boolean]

type UnionArrayEntry = Entry<Array<number | boolean>>
// [`${number}`, number | boolean]

type TupleArrayEntry = Entry<[string, number, boolean]>
// ["0", string] | ["1", number] | ["2", boolean]

const constTuple = ["foo", 42, { key: "value" }] as const;

type ConstTupleArrayEntry = Entry<typeof constTuple>
// ["0", "foo"] | ["1", 42] | ["2", { readonly key: "value"; }]

Overview of type definitions

The key-value entry type of any object can be obtained by the following type definition.

type Entry<T> = { [K in keyof T]: [K, T[K]] }[keyof T]

type FooObject = {
  a: number,
  b: string,
  c: number
}

type FooObjectEntry = Entry<FooObject>
// ["a", number] | ["b", string] | ["c", number]

However, this type definition will not return the expected type when used on an object of a union type and an object containing optional keys.

type Entry<T> = { [K in keyof T]: [K, T[K]] }[keyof T]

type UnionObject =　{ 1: number } |　{ 2: string }

type UnionObjectEntry = Entry<UnionObject>;
// never

type ContainsOptional = {
  a: number,
  b?: string,
  c: number | undefined,
  d?: string | undefined
}

type ContainsOptionalEntry = Entry<ContainsOptional>;
// ["a", number] | ["b", string | undefined] | ["c", number | undefined] | ["d", string | undefined] | undefined

So first of all, let's solve the problem that occurs with the union type.

For example, if we define a type like type SingleTuple<T> = T extends infer A ? [A] : never and pass a single type or a union type to the generic type T, what type will be returned? In particular, what is the correct type when passing a union type to the generic type T?

type SingleTuple<T> = T extends infer A ? [A] : never

type StringSingleTuple = SingleTuple<string>
// [string]

type UnionSingleTuple = SingleTuple<string | number>
// [string] | [number]

The correct answer was [A] | [B], if T was union type A | B(*2).

*2: Distributive Conditional Types

Just as an example, if a type definition T extends infer A is defined for a generic type T, and T is a union type, the following for statement is added to the type definition.

pseudo code of this type definition

type T = string | number

let ReturnType = never;

for (t of T) {
  if (t extends infer A) {
    ReturnType = ReturnType | [A];
  } else {
    ReturnType = ReturnType | never;
  }
}

return ReturnType;
// [string] | [number]

So we add extends that explicitly states that we will only consider the generic type T if it is an object type, so that even if T is a union type, it will return an entry type for each type contained in the union type.

type ObjectEntry<T extends {}> =
  T extends object ?
    { [K in keyof T]: [K, T[K]] }[keyof T] :
    never

type UnionObject =　{ 1: number } |　{ 2: string }

type UnionObjectEntry = ObjectEntry<UnionObject>
// [1, number] | [2, string]

The reason why the line added to the type definition is not T extends Record<> is because it returns never if the generic type T is an interface. In fact, interface does not satisfy the Record<> type. (See also #Appendix of this article)

Next, let's solve the problem that occurs when an optional key is included.

If the key is optional, the resulting entry type contains undefined, so we remove it using Exclude<>. And then the value type contains undefined, so T is changed to Required<T> to get the value type. However, the type obtained from the type definition changes depending on the setting of exactOptionalPropertyTypes in TS Config.

https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes

type ObjectEntry<T extends {}> =
  T extends object ?
    Exclude<{ [K in keyof T]: [K, Required<T>[K]] }[keyof T], undefined> :
    never

type ContainsOptional = {
  a: number,
  b?: string,
  c: number | undefined,
  d?: string | undefined
}

type ContainsOptionalEntry = ObjectEntry<ContainsOptional>
// if disabled exactOptionalPropertyTypes option
//   ["a", number] | ["b", string] | ["c", number | undefined] | ["d", string]

// if enabled exactOptionalPropertyTypes option
//   ["a", number] | ["b", string] | ["c", number | undefined] | ["d", string | undefined]

Finally, the Entry type we are expecting is a type whose key is String Literal, so we convert it with Template Literal Types. However, since the value of key of type symbol is not included in the return value of Object.entries() (see also #Appendix of this article), it is unnecessary and should be excluded. In fact, symbol types cannot be implicitly type-converted to string types(*3), and using them in Template Literal Types will result in a compile error.

*3: 7.1.17 ToString ( argument )

type SymbolStringLiteral<T extends symbol> = `${T}`
// TS2322: Type 'T' is not assignable to type 'string | number | bigint | boolean | null | undefined'.

Since the currently generated Entry type is a union type, once bound as infer E, only those Entries whose keys are of type string | number are extracted and converted using Template Literal Types.

The undefined in the result are excluded by E extends [infer K, infer V], so Exclude<> is no longer necessary.

type ObjectEntry<T extends {}> =
  T extends object ?
    { [K in keyof T]: [K, Required<T>[K]] }[keyof T] extends infer E ?
      E extends [infer K, infer V] ?
        K extends string | number ?
          [`${K}`, V] :
          never :
        never :
      never :
    never

In TypeScript 4.7, a new feature called "extends Constraints on infer Type Variables" will be added, so that in the future this type definition can be written a little shorter.

type ObjectEntry<T extends {}> =
  T extends object ?
    { [K in keyof T]: [K, Required<T>[K]] }[keyof T] extends infer E ?
      E extends [infer K extends string | number, infer V] ?
        [`${K}`, V] :
        never :
      never :
    never

...Oops, we forgot to consider the case where an array type is passed as a typedEntries() function argument. For a simple array type Array<T>, it is enough to return [`${number}`, T], however for Tuple, we would like to return a type like <I = 0 | 1 | 2 | ... > [`${I}`, T[I]] from type definition.

Fortunately, TypeScript allows for zero-based number generation and recursive type definition calls using Type-Level Programming, so type definitions can be defined as follows.

type TupleEntry<T extends readonly unknown[], I extends unknown[] = [], R = never> =
  T extends readonly [infer Head, ...infer Tail] ?
    TupleEntry<Tail, [...I, unknown], R | [`${I['length']}`, Head]> :
    R

export type Entry<T extends {}> =
  T extends readonly [unknown, ...unknown[]] ?
    TupleEntry<T> :
    T extends ReadonlyArray<infer U> ?
      [`${number}`, U] :
      ObjectEntry<T>

The I of TupleEntry<> starts with an empty array, and each recursive call to the type definition increments the length property by adding one element to it. As a result, a zero-based number can be generated.

When using ArrayLike<infer U> to determine if an object is an array type or not, unintended type inference will occur with object like the following, so we need to use ReadonlyArray<infer U> to determine if it is an array type (*4).

*4: Array<T> satisfies all the properties of ReadonlyArray<T>, so this type definition can determine these types together.

const arrayLikeObject = {
  length: 2,
  1: "foo",
  2: "bar"
} as const;
type ArrayLikeObject = typeof arrayLikeObject

type ArrayEntry<T extends {}> = T extends ArrayLike<infer U> ? [`${number}`, U] : never

type E = ArrayEntry<ArrayLikeObject>
// [`${number}`, "foo" | "bar"]

Object.entries(arrayLikeObject).forEach(entry => { console.log(JSON.stringify(entry)); });
// [LOG]: "["1","foo"]" 
// [LOG]: "["2","bar"]" 
// [LOG]: "["length",2]"

An empty array returns [`${number}`, never], however the result of Object.entries([]) is also [string, never][], so there is no special type definition for an empty array.

type EmptyArrayEntry = Entry<[]>
// [`${number}`, never]

const entries = Object.entries([]);
// const entries: [string, never][]

If you have a special reason to return never for an empty array, you can use type NonEmptyReadonlyArray<T> = readonly [T, ...T[]]; and then you need to change the type definition to something like NonEmptyReadonlyArray<infer U>.

This completes the type definitions for Object.entries().

Appendix

Why did not change `Object.entries()` default behavior

You can change the behavior of Object.entries() itself by defining it as follows:

declare global {
   interface ObjectConstructor {
     entries<T extends {}>(object: T): ReadonlyArray<Entry<T>>
  }
}

However, as mentioned above, objects obtained from processes with side effects or objects cast to types satisfying structural subtypes may not return the expected kay-value combination at runtime.

https://github.com/Microsoft/TypeScript/pull/12253#issuecomment-263132208

const actual = {
  key: 'foo',
  extended: true
} as const;

type Base = { key: string }

const base: Base = actual;

Object.entries(base);
// Actually returns [['key', 'foo'], ['extended', true]]

Therefore, I am motivated to use it locally only when it is obvious that the expected kay-value combination will be returned, so I define a function that wraps Object.entries().

An interface does not extend `Record<>`

interface IPerson {
  name: string;
}

type T = Extract<IPerson, Record<string | number | symbol, unknown>>
// never

Related TypeScript issues

Types declared as an "interface" do not extend Record #42825
Types fulfill an interface, but interfaces do not #41518
Index signature is missing in type (only on interfaces, not on type alias) #15300

Just to fill people in, this behavior is currently by design. Because interfaces can be augmented by additional declarations but type aliases can't, it's "safer" (heavy quotes on that one) to infer an implicit index signature for type aliases than for interfaces. But we'll consider doing it for interfaces as well if that seems to make sense

Type aliases can implicitly fulfill an index signature (which is being declared at the Record usage), but not interfaces (since they're subject to declaration merging)

Object.entries() never returns the value of symbol type keys

Keys of symbol type are non-String values, so they are not enumerated in EnumerableOwnPropertyNames and are not included in the return value of Object.entries()

20.1.2.5 Object.entries ( O )

When the entries function is called with argument O, the following steps are taken:

Let obj be ? ToObject(O).

Let nameList be ? EnumerableOwnPropertyNames(obj, key+value).

Return CreateArrayFromList(nameList).

7.3.24 EnumerableOwnPropertyNames ( O, kind )

It performs the following steps when called:

Let ownKeys be ? O.[[OwnPropertyKeys]]().

Let properties be a new empty List.

For each element key of ownKeys, do

a. If Type(key) is String, then

6.1.7 The Object Type

A property key value is either an ECMAScript String value or a Symbol value. All String and Symbol values, including the empty String, are valid as property keys. A property name is a property key that is a String value.

An integer index is a String-valued property key that is a canonical numeric String (see 7.1.21) and whose numeric value is either +0𝔽 or a positive integral Number ≤ 𝔽(253 - 1).

6.1.5 The Symbol Type

The Symbol type is the set of all non-String values that may be used as the key of an Object property (6.1.7).

Scalaの記号みたいな奴らなんなの

harry — Sun, 05 Apr 2020 07:50:52 +0000

この記事は 2016年07月03日にQiitaへ投稿した内容を転記したものです。
本記事は執筆から1年以上が経過しています。

これなんなの？

「Scalaの記号はググラビリティ低すぎて調べようがないし全くわからん…せめて定義位置とか実装がわかれば…」という自分のためのメモ、いわゆるチラシの裏です。

とりあえずScalaの記号については、ソースコードをダウンロードして下記の正規表現でgrepしました。

^[^*/]* (?:def|class|object|type|val) ([^0-9A-Za-z" \(\[]+)(?:[ \(\[]|$)

基本、わからない記号見つけたら定義元に飛んで ((IntelliJはCtrl+B、EclipseはF3))、ソースを読んでます。（読んで理解できるとは言っていない）

IDEで定義元に飛べない記号(_*など)は、言語仕様の可能性が高いので言語仕様を読みましょう。
記号の使用例がわからない場合、そのライブラリのテストコードを読むと良いケースがあります。
急に()が出てきた場合、カリー化された引数かapply()です。 apply()の場合、一時的に書き換えてショートカットキーで飛ぶか、検索してapply()の定義を確認します。

https://twitter.com/kmizu/status/724913410962558976

Language Specification

バッカス・ナウア記法

Scalaの言語仕様では、文法の定義にバッカス・ナウア記法(BNF: Backus-Naur form)が使用されています。使用されているBNFの記号と意味は下記の通りです。

記号	意味
`::=`	定義
`‘…’`	文字列
`…'	文字列
\|	OR
`( … )`	グループ化
`{ … }`	0回以上の繰り返し
`[ … ]`	オプション (0回 or 1回)
`//`	コメント (注釈)
`“…”`	コメント (注釈)

記号ではありませんが、nlとsemiの意味は下記の通りです。

nl               ::=  “newlinecharacter”
semi             ::=  ‘;’ |  nl {nl}

Arrow

Identifiers

`⇒` / `←`

http://www.scala-lang.org/files/archive/spec/2.11/01-lexical-syntax.html#identifiers

The Unicode operators \u21D2 ‘⇒’ and \u2190 ‘←’, which have the ASCII equivalents => and <-, are also reserved.

なお、2.13.xから非推奨になりました。(実務で使ってる人は皆無だと思いますが…)

Deprecate unicode arrows ⇒, ← and → by smarter · Pull Request #7540 · scala/scala
https://github.com/scala/scala/pull/7540

Import Clauses

http://www.scala-lang.org/files/archive/spec/2.11/04-basic-declarations-and-definitions.html#import-clauses

Import selectors work in the same way for type and term members. For instance, an import clause import p.{x => y} renames the term name p.x to the term name y and the type name p.x to the type name y. At least one of these two names must reference an importable member of p.

import p.{x => y}と書くと、p.xをyという名前でimportすることができます。
SessionやModule等のかぶりやすい名前のtypeを複数importする際に便利なことがあります。

java.sql.DateをSQLDateとしてimportする例

import java.util.Date
import java.sql.{Date => SQLDate}

If the target in an import selector is a wildcard, the import selector hides access to the source member. For instance, the import selector x => _ “renames” x to the wildcard symbol (which is unaccessible as a name in user programs), and thereby effectively prevents unqualified access to x. This is useful if there is a final wildcard in the same import selector list, which imports all members not mentioned in previous import selectors.

package内のすべてのtypeをimportする際はpackage._を使用しますが、特定のtypeだけ除外したい場合はpackage.{Type => _, _}と書くことで除外できます。
複数のtypeを除外することもできます。

java.util.Dateを除くjava.util._とjava.sql._をimportする例

import java.util.{Date => _, _}
import java.sql._

Scalaスケーラブルプログラミング第2版
13.3 インポート (P.238～239)

Self type

http://www.scala-lang.org/files/archive/spec/2.11/05-classes-and-objects.html#templates

ClassTemplate   ::=  [EarlyDefs] ClassParents [TemplateBody]
TraitTemplate   ::=  [EarlyDefs] TraitParents [TemplateBody]
ClassParents    ::=  Constr {`with' AnnotType}
TraitParents    ::=  AnnotType {`with' AnnotType}
TemplateBody    ::=  [nl] `{' [SelfType] TemplateStat {semi TemplateStat} `}'
SelfType        ::=  id [`:' Type] `=>'
                 |   this `:' Type `=>'

The sequence of template statements may be prefixed with a formal parameter definition and an arrow, e.g. x =>, or x:T =>. If a formal parameter is given, it can be used as an alias for the reference this throughout the body of the template.

class, object, traitの定義部(TemplateBody)の最初にid : Type =>またはthis : Type =>と書くことができます。これはSelf Type(自分型)で、基本的に自分自身のインスタンスthisと同じものを指します。つまり、thisの別名(alias)を定義することができます。

id : Typeの型注釈は省略可能で、idは慣習的にselfが使用されます。

`self =>`の使用例

Optionでの使用例です。

Option.scala#L98-L99

sealed abstract class Option[+A] extends Product with Serializable {
  self =>

Option.scala#L197-L211

  /** Necessary to keep $option from being implicitly converted to
   *  [[scala.collection.Iterable]] in `for` comprehensions.
   */
  @inline final def withFilter(p: A => Boolean): WithFilter = new WithFilter(p)

  /** We need a whole WithFilter class to honor the "doesn't create a new
   *  collection" contract even though it seems unlikely to matter much in a
   *  collection with max size 1.
   */
  class WithFilter(p: A => Boolean) {
    def map[B](f: A => B): Option[B] = self filter p map f
    def flatMap[B](f: A => Option[B]): Option[B] = self filter p flatMap f
    def foreach[U](f: A => U): Unit = self filter p foreach f
    def withFilter(q: A => Boolean): WithFilter = new WithFilter(x => p(x) && q(x))
  }

abstract class Option内で定義したclass WithFilterからOptionのインスタンスを参照する際、thisを使用するとWithFilter自身のインスタンスを指してしまいますが、自分型のselfを使用することでOptionのインスタンスを参照することができます。

`this: Type =>`の使用例

例えば特定のtraitがmixinされていることが前提のクラスに対してmixinするためのtraitを定義するとします。
その際、定義したtrait内でクラスへmixinされているはずのtraitのメンバを使用したいことがあります。

class SomeClass extends Foo with Bar

trait Foo {
  // ...
}

// Bar は Foo をmixinしているtypeにmixinすることが前提のtrait
trait Bar {
  // Fooのメンバを使用したい…
}

その場合は、自分型のTypeにそのtraitを指定することで、そのtraitのメンバが使用できます。
(thisがTypeに指定したtypeとして振舞います)

trait Bar {
  this: Foo =>

  // Fooのメンバが使用できる
}

Play Frameworkでの使用例です。
Controllerをmixinしているクラスに対してmixinするtraitで、Controllerのメンバを使用したい場合です。

import play.api.mvc._

trait FooController {
  this: Controller =>

  // `Controller` のメンバが使用できる
}

さらに、I18nSupportをmixinしていることが前提の場合は下記のようになります。

import play.api.i18n.I18nSupport
import play.api.mvc._

trait BarController {
  this: Controller with I18nSupport =>

  // `Controller` と `I18nSupport` のメンバが使用できる
}

自分型でtypeを指定した場合、指定したtypeを継承しているtrait, class, objectに対してのみ継承やmixinができます。

import play.api.mvc._

// OK
class SomeContoller extends Controller with FooController

// Compile error
// illegal inheritance; self-type SomeClass does not conform to FooController's selftype Controller
class SomeClass extends FooController

Atmark

Pattern Binders

http://www.scala-lang.org/files/archive/spec/2.11/08-pattern-matching.html#pattern-binders

A pattern binder x@p consists of a pattern variable x and a pattern p. The type of the variable x is the static type T of the pattern p. This pattern matches any value v matched by the pattern p, provided the run-time type of v is also an instance of T, and it binds the variable name to that value.

パターンマッチングでx@pと書くと、パターンpに一致した際の値を変数xとして参照(束縛)することができます。

List(1, 2, 3) match {
  // headが 1 にマッチするListを変数 x に束縛する
  case x @ 1 :: _ =>
    x // = x: List = List(1, 2, 3)
  case _ =>
    Nil
}

[Scala]パターンマッチにおけるアットマーク(@)
http://qiita.com/petitviolet/items/89843d948b6fc06eba57

Colon

Infix Operations

http://www.scala-lang.org/files/archive/spec/2.11/06-expressions.html#infix-operations

The associativity of an operator is determined by the operator's last character. Operators ending in a colon : are right-associative. All other operators are left-associative.

演算子(operator、メソッド)の最後の文字がコロン(:)の場合、その演算子は右被演算子から呼び出されます。(左被演算子は引数になります)

Seqの例

val a = Seq(1, 2, 3)

a :+ 4

a.:+(4) // = Seq(1, 2, 3, 4)

// メソッド `+:` は、右被演算子の a から呼び出される
0 +: a

a.+:(0) // = Seq(0, 1, 2, 3)

Unary

Prefix Operations

http://www.scala-lang.org/files/archive/spec/2.11/06-expressions.html#prefix-operations

A prefix operation op;e consists of a prefix operator op, which must be one of the identifiers ‘+’, ‘-’, ‘!’ or ‘~’. The expression op;e is equivalent to the postfix method application e.unary_op.

単項(unary)演算子のうち、+, -, !, ~は前置演算子として使用することができます。前置演算子として使用された場合、unary_opメソッドが呼び出されます。

Booleanの例

val b = true

// 前置演算子 `!` の場合、`unary_!` メソッドが呼び出される
!b

b.unary_! // = false

つまり、unary_opメソッドを定義すればopを前置演算子として使用することができます。
メソッド定義のunary_opと:の間にはスペースが必要です。

case object Black extends Things
case object White extends Things

sealed abstract class Things {
  def unary_! : Things = {
    this match {
      case Black => White
      case White => Black
    }
  }
}

!Black // = White

Underscore

http://stackoverflow.com/questions/8000903/what-are-all-the-uses-of-an-underscore-in-scala

`` / `_`

Repeated Parameters

http://www.scala-lang.org/files/archive/spec/2.11/04-basic-declarations-and-definitions.html#repeated-parameters

http://www.scala-lang.org/files/archive/spec/2.11/06-expressions.html#function-applications

メソッド、関数定義のType*は可変長引数
可変長引数は最後の引数でのみ使用できます

def sum(args: Int*): Int = {
  var result = 0
  for (arg <- args) result += arg
  result
}

val sum: (Int*) => Int = { args =>
  var result = 0
  for (arg <- args) result += arg
  result
}

Seq型は_*型注釈をつけることで可変長引数に渡すことができます。

sum(Seq(1, 2, 3, 4): _*)

Seq型であればよいので、Seq型に暗黙の型変換されるものでもよいです。

// Char の可変長引数を取るメソッド
def toHexString(args: Char*): String = {
  args.map(c => f"$c%#06x").mkString(",")
}

// String は WrappedString (Seq[Char]) へ暗黙の型変換されます
toHexString("str": _*)

// 0x0073,0x0074,0x0072

Pattern Sequences

http://www.scala-lang.org/files/archive/spec/2.11/08-pattern-matching.html#pattern-sequences

Pattern matching中の_*はsequence wildcard

case List(1, 2, _*) => ... // will match all lists starting with 1, 2, ...

`[]`

型パラメーター

`[A <: B]` `[A >: B]` `[+T]` `[-T]`

上限・下限境界と変位指定アノテーション

第21章：Scalaの型パラメータ
http://qiita.com/f81@github/items/7a664df8f4b87d86e5d8

共変・反変・上限境界・下限境界の関係性まとめ
http://qiita.com/mtoyoshi/items/bd0ad545935225419327

`[_]`

def f[M[_]]       // Higher kinded type parameter
def f(m: M[_])    // Existential type

`private[C]` / `protected[C]`

http://www.scala-lang.org/files/archive/spec/2.11/05-classes-and-objects.html#modifiers

A private modifier can be qualified with an identifier C (e.g. private[C]) that must denote a class or package enclosing the definition. Members labeled with such a modifier are accessible respectively only from code inside the package C or only from code inside the class C and its companion module.

A protected modifier can be qualified with an identifier C (e.g. protected[C]) that must denote a class or package enclosing the definition. Members labeled with such a modifier are also accessible respectively from all code inside the package C or from all code inside the class C and its companion module.

Scala Standard Library

Any

`==`

  final def ==(that: Any): Boolean = this equals that

`!=`

  final def != (that: Any): Boolean = !(this == that)

`##`

  /** Equivalent to `x.hashCode` except for boxed numeric types and `null`.
   *  For numerics, it returns a hash value which is consistent
   *  with value equality: if two value type instances compare
   *  as true, then ## will produce the same hash value for each
   *  of them.
   *  For `null` returns a hashcode where `null.hashCode` throws a
   *  `NullPointerException`.
   *
   *  @return   a hash value consistent with ==
   */
  final def ##(): Int = sys.error("##")

null安全なhashCodeの取得ができます。

> scala -feature

scala> val s: String = null
s: String = null

scala> s.hashCode
java.lang.NullPointerException
  ... 33 elided

scala> s##
<console>:12: warning: postfix operator ## should be enabled
by making the implicit value scala.language.postfixOps visible.
This can be achieved by adding the import clause 'import scala.language.postfixOps'
or by setting the compiler option -language:postfixOps.
See the Scala docs for value scala.language.postfixOps for a discussion
why the feature should be explicitly enabled.
       s##
        ^
res0: Int = 0

Scalaパズル 36の罠から学ぶベストプラクティス
PUZZLE28　好きな値を選んでください！――Pick a Value, AnyValue! (P.187-189)

AnyRef

`==`

  final def ==(that: Any): Boolean =
    if (this eq null) that.asInstanceOf[AnyRef] eq null
    else this equals that

null安全な等価比較ができます。

library

package.scala

  type ::[A] = scala.collection.immutable.::[A]
  val :: = scala.collection.immutable.::

  val +: = scala.collection.+:
  val :+ = scala.collection.:+

  type Stream[+A] = scala.collection.immutable.Stream[A]
  val Stream = scala.collection.immutable.Stream
  val #:: = scala.collection.immutable.Stream.#::

Numeric value types

http://www.scala-lang.org/files/archive/spec/2.11/12-the-scala-standard-library.html#numeric-value-types

Boolean

== != || && | & ^

Byte / Char / Short / Int / Long

<< >> <<< >>> == != < <= > >= | & ^ + - * / %

Float / Double

== != < <= > >= | & ^ + - * / %

Enumeration

Value

    /** Create a ValueSet which contains this value and another one */
    def + (v: Value) = ValueSet(this, v)

ValueSet

    def + (value: Value) = new ValueSet(nnIds + (value.id - bottomId))
    def - (value: Value) = new ValueSet(nnIds - (value.id - bottomId))

ValueSet.newBuilder

      def += (x: Value) = { b += (x.id - bottomId); this }

Predef.scala

http://www.scala-lang.org/files/archive/spec/2.11/12-the-scala-standard-library.html#the-predef-object

`???`

  /** `???` can be used for marking methods that remain to be implemented.
   *  @throws NotImplementedError
   */
  def ??? : Nothing = throw new NotImplementedError

ArrowAssoc

  implicit final class ArrowAssoc[A](private val self: A) extends AnyVal {
    @inline def -> [B](y: B): Tuple2[A, B] = Tuple2(self, y)
    def →[B](y: B): Tuple2[A, B] = ->(y)
  }

a -> bと書くとTuple2(a, b)に変換されて不思議に思ったことありませんか？これです。

`<:<`

An instance of A <:< B witnesses that A is a subtype of B.

<:<を使ってメソッド引数の型を限定する (例: IntもしくはBooleanもしくはString
http://qiita.com/mtoyoshi/items/fbf2c744e3c7fd69a438

続<:<を使ってメソッド引数の型を限定する（厳密に）
http://qiita.com/mtoyoshi/items/13ac0500aa23fb4fa0d4

`=:=`

An instance of A =:= B witnesses that the types A and B are equal.

collections

Traversable

TraversableLike

++ コレクションを追加した新しいコレクションを返す
++: 右辺のコレクションと左辺のコレクションを追加した新しいコレクションを返す

Seq(1, 2, 3) ++ Seq(4, 5, 6)  // = Seq(1, 2, 3, 4, 5, 6)

Seq(1, 2, 3) ++: Seq(4, 5, 6) // = Seq(1, 2, 3, 4, 5, 6)

TraversableOnce

  def /:[B](z: B)(op: (B, A) => B): B = foldLeft(z)(op)

  def :\[B](z: B)(op: (A, B) => B): B = foldRight(z)(op)

SeqLike

+: 要素にSeqを追加した新しいSeqを返す (Seqの先頭に要素を挿入した新しいSeqを返す)
:+ Seqに要素を追加した新しいSeqを返す

0 +: Seq(1, 2, 3) // = Seq(0, 1, 2, 3)

Seq(1, 2, 3) :+ 4 // = Seq(1, 2, 3, 4)

generic

Growable

http://www.scala-lang.org/api/2.11.7/index.html#scala.collection.generic.Growable

mutableなコレクションなどにmixinされているtrait
新しいコレクションを作らず、コレクションに直接要素を追加する

+= コレクションへ1つ、または複数の要素を追加する
++= 引数のコレクションにある要素を追加する

Shrinkable

http://www.scala-lang.org/api/2.11.7/index.html#scala.collection.generic.Shrinkable

mutableなコレクションなどにmixinされているtrait
新しいコレクションを作らず、コレクションから直接要素を削除する

-= コレクションから1つ、または複数の要素を削除する
--= 引数のコレクションにある要素を削除する

Subtractable

http://www.scala-lang.org/api/2.11.7/index.html#scala.collection.generic.Subtractable

- コレクションから1つ、または複数の要素を削除した新しいコレクションを返す

override def -でソースコードを検索すると、コレクション毎の実装詳細を確認することができます。

--

  def --(xs: GenTraversableOnce[A]): Repr = (repr /: xs.seq) (_ - _)

引数のコレクションにある要素を削除した新しいコレクションを返す

BitSetLike

| & &~ ^

BitSet同士のor, and, and-not, xorを取り、新しいBitSetを返す

mutable.BitSet

|= &= &~= ^=

BitSet同士のor, and, and-not, xorを取り、BitSetを更新する

GenSetLike

`+` `-`

  def +(elem: A): Repr
  def -(elem: A): Repr

Setへ要素を追加、削除する

`&`

  def &(that: GenSet[A]): Repr = this intersect that

Set同士のandを取る

`|`

  def | (that: GenSet[A]): Repr = this union that

Set同士のorを取る

`&~`

  def &~(that: GenSet[A]): Repr = this diff that

Set同士のand-notを取る ((本来、要素の順序は保証されませんが、わかりやすさのためソートして書いています))

val a = Set(1, 2, 3, 4, 5, 6)
val b = Set(1, 2, 3)

a &~ b // = Set(4, 5, 6)

b &~ a // = Set()

immutable.::

final case class ::[B](override val head: B, private[scala] var tl: List[B]) extends List[B] {
  override def tail : List[B] = tl
  override def isEmpty: Boolean = false
}

::(head, tail)となるようなListを返すクラスです。

package.scalaで::のtype aliasが定義されており、Listに対するパターンマッチ(case head :: tail)でも使用されます。

余談ですが、REPLでは:から始まる文字列がコマンドとして解釈されるため、バッククォートで囲みリテラル識別子(literal identifiers)にする必要があります。

scala> `::`(1, List(2, 3, 4))
res0: scala.collection.immutable.::[Int] = List(1, 2, 3, 4)

scala> res0.head
res1: Int = 1

scala> res0.tail
res2: List[Int] = List(2, 3, 4)

immutable.List

`::`

  def ::[B >: A] (x: B): List[B] =
    new scala.collection.immutable.::(x, this)

メソッドの最後の文字が:なので、right-associativeです。
Scaladocのexampleに書かれていますが、下記のようになります。

1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)

つまり、終端がListであればよいので、Nilも使えます。

1 :: 2 :: 3 :: Nil

1 :: 2 :: Nil.::(3)

1 :: 2 :: List(3)

1 :: List(3).::(2)

1 :: List(2, 3)

List(2, 3).::(1)

List(1, 2, 3)

`:::`

  def :::[B >: A](prefix: List[B]): List[B] =
    if (isEmpty) prefix
    else if (prefix.isEmpty) this
    else (new ListBuffer[B] ++= prefix).prependToList(this)

List同士を連結した新しいListを返す

List(1, 2, 3) ::: List(4, 5, 6) // = List(1, 2, 3, 4, 5, 6)

Stream.#::

  object #:: {
    def unapply[A](xs: Stream[A]): Option[(A, Stream[A])] =
      if (xs.isEmpty) None
      else Some((xs.head, xs.tail))
  }

Streamのパターンマッチ(case head #:: tail)のために定義されている記号(object)
package.scalaに#::のtype aliasが定義されています。

Stream.ConsWrapper

#::と#:::が定義されていて、Streamからこれらのメソッドが呼ばれるとConsWrapperに暗黙の型変換が行われます。

  /** A wrapper method that adds `#::` for cons and `#:::` for concat as operations
   *  to streams.
   */
  implicit def consWrapper[A](stream: => Stream[A]): ConsWrapper[A] =
    new ConsWrapper[A](stream)

#::

  def #::(hd: A): Stream[A] = cons(hd, tl)

簡単にいうと、head #:: tailとなるようなStreamが返ります。

実際にはobject consのapply()が実行され、final class Cons[+A](hd: A, tl: => Stream[A]) extends Stream[A]が返ります。

#:::

  def #:::(prefix: Stream[A]): Stream[A] = prefix append tl

Stream同士を連結した新しいStreamを返す

mutable.BufferLike

`++=:`

  def ++=:(xs: TraversableOnce[A]): this.type = { insertAll(0, xs.toTraversable); this }

コレクションxsを現在のBufferの前方に挿入する

val buffer = mutable.Buffer(4, 5, 6)

Seq(1, 2, 3) ++=: buffer

buffer // = mutable.Buffer(1, 2, 3, 4, 5, 6)

StringLike

`*`

  def * (n: Int): String = {
    val buf = new StringBuilder
    for (i <- 0 until n) buf append toString
    buf.toString
  }

現在の文字列を指定回数連結した文字列を返す

math

/%: 商と余りをTupleで返す
&~: and-not (this & ~that)

BigDecimal

<= >= < > + - * / /% %

BigInt

<= >= < > + - * / % /% << >> & | ^ &~

Fractional

/

Integral

/ % /%

Numeric

+ - *

Ordered

< > <= >=

Ordering

< <= > >=

PartiallyOrdered

< > <= >=

sys

SystemProperties

-= +=

package process

type =?>[-A, +B]     = PartialFunction[A, B]

ProcessBuilder (extends Source with Sink)

http://www.scala-lang.org/api/2.11.x/#scala.sys.process.ProcessBuilder

記号	機能
!!	blocks until all external commands exit, and returns a String with the output generated.
!!<	stdin + `!!`
!	blocks until all external commands exit, and returns the exit code of the last one in the chain of execution.
!<	stdin + `!`
#\|	pipe (Shellの \| )
###	コマンドが終了後、後続のコマンドを実行。
#&&	コマンドのexit codeが0の時、後続のコマンドを実行。 (Shellの && )
#\|\|	コマンドのexit codeが0以外の時、後続のコマンドを実行　(Shellの \|\| )

FileBuilder (extends Sink with Source)

#<<

Source

記号	意味
`#>`	Redirect stdout (overwrite)
`#>>`	Redirect stdout (append)

Sink

記号	意味
`#<`	Redirect stdin

AbstractBuilder (extends ProcessBuilder with Sink with Source)

!! !!< ! !< #| ### #&& #||

FileImpl (extends FileBuilder with Sink with Source)

#<<

ex-Scala Standard Library

以下のライブラリは2.11.0で標準ライブラリから分離されました。

Scala 2.11.0で標準ライブラリから分離されたライブラリのjarファイル - kmizuの日記
http://kmizu.hatenablog.com/entry/2014/04/24/005958

scala-xml

Lexical Syntax - 1.5 XML mode
http://www.scala-lang.org/files/archive/spec/2.11/01-lexical-syntax.html#xml-mode

XML Expressions and Patterns
http://www.scala-lang.org/files/archive/spec/2.11/10-xml-expressions-and-patterns.html

XML expressions

ScalaはXML(XMLリテラル)を直接扱うことができます。ただし、前述のとおりscala.xmlが標準ライブラリから外されたため、クラスパスに追加しないとコンパイルできません。 ((REPLはscala.xmlパッケージが含まれているため、そのまま使用することができます))

val a = <a>text</a> // = a: scala.xml.Elem = <a>text</a>

XML expressions may contain Scala expressions as attribute values or within nodes. In the latter case, these are embedded using a single opening brace { and ended by a closing brace }. To express a single opening braces within XML text as generated by CharData, it must be doubled. Thus, {{ represents the XML text { and does not introduce an embedded Scala expression.

XMLでScalaの変数や式を参照する場合は{}を使用します。
参照ではなく単純に波括弧を使用したい場合は{{や}}を使用します。

<a>{brace}</a>   // error: not found: value brace
<a>{{brace}}</a> // <a>{brace}</a>

val text = "text value"

<a>{text}</a>         // = <a>text value</a>
<a>{{text</a>         // = <a>{text</a>
<a>text}}</a>         // = <a>text}</a>

<a>{{{text}}}</a>     // = <a>{text value}</a>
<a>{{{{text}}}}</a>   // = <a>{{text}}</a>
<a>{{{{{text}}}}}</a> // = <a>{{text value}}</a>

単純に{{の組み合わせが、XML textの{に変換されています。

XML patterns

XMLリテラルはそのままパターンマッチングで使用することができます。
パターンマッチングの{}内ではScalaのパターンマッチが使用できます。

// 変数パターンによるマッチング
<a><b>text</b></a> match {
  case <a>{value}</a> => println(value)
  case _ => println("unmatched")
}

// <b>text</b>

<a><b>bold</b> text</a> match {
  case <a>{value}</a> => println(value)
  case _ => println("unmatched")
}

// unmatched

任意のXMLノードシーケンスにマッチさせるためには、Pattern Sequences(_*)を使用する必要があります。
(2つ目の<a>には<b>とtextの2つのノードが含まれていました)

// Pattern Sequencesによるマッチング
val list = <ul type="circle">
             <li>a</li>
             <li>b</li>
             <li>c</li>
           </ul>

list match {
  case <ul>{items @ _*}</ul> =>
    for (item <- items) {
      println(s"item: $item")
    }
}

// item: 
//                
// item: <li>a</li>
// item: 
//                
// item: <li>b</li>
// item: 
//                
// item: <li>c</li>
// item: 
//

XMLでは改行や空白もTextノードなのでパターンに一致します。
for式のGeneratorでは

Pattern `<-' Expr

でパターンマッチングが使用できるので、これで必要なノードのみ抽出できます。

val list = <ul type="circle">
             <li>a</li>
             <li>b</li>
             <li>c</li>
           </ul>

list match {
  case <ul>{items @ _*}</ul> =>
    for (item @ <li>{_*}</li> <- items) {
      println(s"item: $item")
    }
}

// item: <li>a</li>
// item: <li>b</li>
// item: <li>c</li>

Scalaスケーラブルプログラミング第2版
28.8 XMLを対象とするパターンマッチ (P.566～569)

Atom

https://github.com/scala/scala-xml/blob/v1.0.5/src/main/scala/scala/xml/Atom.scala

記号とは直接関係ありませんが、この後new Atom()や_.isAtomが出てくるため簡単に説明します。
Atomはlabelが#PCDATA ((PCDATA: Parsed Character Data)) であるTextノードです。

例えば、XML patternsのサンプルコードで一致した改行や空白のTextノードは、isAtomでtrueを返します。

Elem

`%`

  final def %(updates: MetaData): Elem =
    copy(attributes = MetaData.update(attributes, scope, updates))

指定されたattributes(MetaData)に更新した新しいElemを返す

NodeBuffer

`&+`

  def &+(o: Any): NodeBuffer = {
    o match {
      case null | _: Unit | Text("") => // ignore
      case it: Iterator[_]           => it foreach &+
      case n: Node                   => super.+=(n)
      case ns: Iterable[_]           => this &+ ns.iterator
      case ns: Array[_]              => this &+ ns.iterator
      case d                         => super.+=(new Atom(d))
    }
    this
  }

下記のような処理になっています。

IterableやArrayのようなコレクションはiterator.foreachで要素個別に処理
Nodeであればそのまま追加、それ以外はAtom(Textノード)として追加
null、Unit、空文字のTextは無視

NodeSeq

XPathに/や//がありますが、Scalaで//はコメント行として使用されるため、NodeSeqの記号ではバックスラッシュの\や\\が使用されています。
(Scalaスケーラブルプログラミング第2版 P.564より)

`\`

自身のノードを基準として条件に一致するノードを抽出します。
多機能なのでScaladocを引用すると下記のようになります。

this \ "foo" to get a list of all elements that are labelled with "foo";

\ "_" to get a list of all elements (wildcard);

ns \ "@foo" to get the unprefixed attribute "foo";

ns \ "@{uri}foo" to get the prefixed attribute "pre:foo" whose prefix "pre" is resolved to the namespace "uri".

this \ "foo"

直下の子ノードで要素名(label)に一致するノードを返します。
XPathのnode/fooに相当します。

this \ "_"

直下の子ノードでAtom以外のノードすべてを返します。(ワイルドカード)
XPathのnode/*に相当します。

ns \ "@foo"

自身のノードから一致する属性名の値を返します。
XPathのnode/@attributeに相当します。

ただし、自身が単一のノード(this.length == 1)である必要があります。
複数のノードの場合、空のNodeSeqを返します。

// 単一のノード
<a href="http://qiita.com/">Qiita</a> \ "@href" // = scala.xml.NodeSeq = http://qiita.com/

// 複数のノード
<a href="http://qiita.com/">Qiita</a>
<a href="https://teams.qiita.com/">Qiita:Team</a> \ "@href" // = scala.xml.NodeSeq = NodeSeq()

ns \ "@{uri}foo"

名前空間プレフィックスのついた属性名(prefix:attribute)の値を返します。
Mavenのpom.xmlを例にすると下記のようになります。

val project =
<project xmlns="http://maven.apache.org/POM/4.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd"></project>

// "xsi:schemaLocation"の値を取得
project \ "@{http://www.w3.org/2001/XMLSchema-instance}schemaLocation"

// = scala.xml.NodeSeq =
// http://maven.apache.org/POM/4.0.0
//                       http://maven.apache.org/xsd/maven-4.0.0.xsd

`\\`

XPathの//に相当し、すべての子孫ノードを対象に抽出を行います。

`\@`

  def \@(attributeName: String): String = (this \ ("@" + attributeName)).text

Nodeの指定した属性名の値を取得する
(\ "@attributeName"と動作は等価ですが、戻り値はString型です)

CachedFileStorage

`+=`

  /** adds a node, setting this.dirty to true as a side effect */
  def +=(e: Node): Unit

`-=`

  /** removes a tree, setting this.dirty to true as a side effect */
  def -=(e: Node): Unit

SetStorage (extends CachedFileStorage)

`+=`

  def +=(e: Node): Unit = synchronized { this.dirty = true; theSet += e }

`-=`

  def -=(e: Node): Unit = synchronized { this.dirty = true; theSet -= e }

DEV Community: harry

Using DDD with Recoil

Introduction

Assumptions

All of the artifacts in this article

💥 Problems with this Todo app

🛠 Let's refactor

1. Cohesive domain logic

2. Implementing the Recoil state module

Implementation policy

Actual implementation code

3. Implementing Components

Referring to the state

Update the state

One last push

🎉 After refactoring

Conclusion

Appendix

⚠ Notes on class-based state module

More powerful type definitions for Object.entries()

Introduction

Type definitions

Examples of type definition usage

Overview of type definitions

Appendix

Why did not change Object.entries() default behavior

An interface does not extend Record<>

Related TypeScript issues

Object.entries() never returns the value of symbol type keys

Related links

Articles for Type-Level Programming in TS

English

Japanese

Scalaの記号みたいな奴らなんなの

これなんなの？

バッカス・ナウア記法

Arrow

Identifiers

⇒ / ←

Import Clauses

Self type

self =>の使用例

this: Type =>の使用例

Atmark

Pattern Binders

Colon

Infix Operations

Unary

Prefix Operations

Underscore

* / _*

Repeated Parameters

Pattern Sequences

[]

型パラメーター

[A <: B] [A >: B] [+T] [-T]

[_]

private[C] / protected[C]

Scala Standard Library

Any

AnyRef

Numeric value types

Boolean

Byte / Char / Short / Int / Long

Float / Double

Enumeration

collections

Traversable

TraversableLike

SeqLike

generic

Growable

Shrinkable

Subtractable

BitSetLike

mutable.BitSet

GenSetLike

immutable.List

Stream.ConsWrapper

mutable.BufferLike

Why did not change `Object.entries()` default behavior

An interface does not extend `Record<>`

`⇒` / `←`

`self =>`の使用例

`this: Type =>`の使用例

`` / `_`

`[]`

`[A <: B]` `[A >: B]` `[+T]` `[-T]`

`[_]`

`private[C]` / `protected[C]`