tutuca 0.9.39 → 0.9.41

package/skill/immutable-js/references/deep-updates.md

@@ -0,0 +1,172 @@
+When you have nested data, these helpers update by path without writing the boilerplate yourself. Each returns a new structure with structural sharing for the unchanged parts. Available both as top-level functions imported from `immutable` (which also accept plain JS objects/arrays) and as instance methods on every Immutable collection. The instance forms (`map.setIn(...)`, `list.updateIn(...)`, etc.) have identical semantics on Immutable inputs.
+
+## Paths
+
+- A path is any iterable of keys/indices — most code uses an `Array`, but any `Iterable` works.
+- Use numeric indices for `List`/`Array` segments and string keys for `Map`/`Record`/object segments. Keys are matched exactly (no negative-index resolution like `List.get(-1)` does).
+- For `setIn`/`updateIn`/`mergeIn`, missing intermediate keys are auto-created as empty `Map`s to fill out the path. If you want a `List` at some level, initialize it explicitly first.
+- `getIn`/`hasIn` never mutate or extend — a missing intermediate just yields `notSetValue` / `false`.
+- All functions return the same identity (`===`) when no change occurs (e.g. `setIn` to the existing value).
+
+## getIn
+
+```ts
+getIn(collection, keyPath, notSetValue?): any
+```
+
+Walks `keyPath` from `collection` and returns the value found, or `notSetValue` (default `undefined`) if any segment is missing.
+
+```js
+getIn({ x: { y: { z: 123 } } }, ['x', 'y', 'z']);          // => 123
+getIn({ x: { y: { z: 123 } } }, ['x', 'q', 'p'], 'fallback'); // => 'fallback'
+```
+
+## hasIn
+
+```ts
+hasIn(collection, keyPath): boolean
+```
+
+Returns `true` iff every segment of `keyPath` resolves. Distinguishes "key absent" from "key present but `undefined`", unlike `getIn(...) !== undefined`.
+
+```js
+hasIn({ x: { y: { z: 123 } } }, ['x', 'y', 'z']); // => true
+hasIn({ x: { y: { z: 123 } } }, ['x', 'q', 'p']); // => false
+```
+
+## setIn
+
+```ts
+setIn(collection: C, keyPath: Iterable, value: any): C
+```
+
+Returns a copy of `collection` with the value at `keyPath` replaced by `value`. Missing intermediate keys are filled in as empty `Map`s.
+
+```js
+setIn({ x: { y: { z: 123 } } }, ['x', 'y', 'z'], 456);
+// => { x: { y: { z: 456 } } }
+
+setIn(Map(), ['a', 'b', 'c'], 1);
+// => Map { "a": Map { "b": Map { "c": 1 } } }
+```
+
+## updateIn
+
+```ts
+updateIn(collection, keyPath, updater)
+updateIn(collection, keyPath, notSetValue, updater)
+```
+
+Returns a copy where the value at `keyPath` is replaced by `updater(currentValue)`. With four arguments, `notSetValue` is passed to `updater` when the path is missing (otherwise `updater` receives `undefined`). Like `setIn`, missing intermediates become empty `Map`s.
+
+```js
+// 3-arg: updater receives undefined when path is missing
+updateIn(Map(), ['hits'], n => (n || 0) + 1);
+// => Map { "hits": 1 }
+
+// 4-arg: notSetValue is passed in when path is missing
+updateIn(Map({ x: { y: 10 } }), ['x', 'y'], 0, n => n + 1);
+// => Map { "x": { "y": 11 } }
+updateIn(Map(), ['x', 'y'], 0, n => n + 1);
+// => Map { "x": Map { "y": 1 } }
+```
+
+## removeIn (alias deleteIn)
+
+```ts
+removeIn(collection: C, keyPath: Iterable): C
+```
+
+Returns a copy with the entry at `keyPath` removed. Intermediate containers are left in place even if they become empty.
+
+```js
+removeIn({ x: { y: { z: 123 } } }, ['x', 'y', 'z']);
+// => { x: { y: {} } }
+```
+
+## merge
+
+```ts
+merge<C>(collection: C, ...sources): C
+```
+
+Shallow non-mutating merge: each source's keys overwrite `collection`'s at the top level only. For plain objects this behaves like `Object.assign({}, target, ...sources)` but never mutates; for `Map`-like targets it merges entries.
+
+```js
+merge({ x: 123, y: 456 }, { y: 789 });
+// => { x: 123, y: 789 }
+```
+
+## mergeWith
+
+```ts
+mergeWith<C>(
+  merger: (oldVal, newVal, key) => any,
+  collection: C,
+  ...sources
+): C
+```
+
+Like `merge`, but `merger(oldVal, newVal, key)` resolves every collision (called only when both sides have the key).
+
+```js
+mergeWith(
+  (oldVal, newVal) => oldVal + newVal,
+  { x: 123, y: 456 },
+  { y: 789, z: 'abc' }
+);
+// => { x: 123, y: 1245, z: 'abc' }
+```
+
+## mergeDeep
+
+```ts
+mergeDeep<C>(collection: C, ...sources): C
+```
+
+Recursive merge. At each key: if both old and new values are "compatible" collections in the same category (keyed: `Map`/`Record`/object, indexed: `List`/`Array`, set-like: `Set`), they are merged together; otherwise the new value replaces the old. Indexed and set-like values are merged via `concat()`/`union()` — they do NOT recurse element-wise. Mixing categories at a key (e.g. `List` vs `Map`) replaces.
+
+```js
+mergeDeep({ x: { y: 123 } }, { x: { z: 456 } });
+// => { x: { y: 123, z: 456 } }
+
+mergeDeep({ xs: [1, 2] }, { xs: [3, 4] });
+// => { xs: [1, 2, 3, 4] }   // concat, NOT element-wise merge
+```
+
+## mergeDeepWith
+
+```ts
+mergeDeepWith<C>(
+  merger: (oldVal, newVal, key) => any,
+  collection: C,
+  ...sources
+): C
+```
+
+Like `mergeDeep`, but at any leaf collision (or when the two sides are in incompatible categories), `merger(oldVal, newVal, key)` decides the resulting value.
+
+```js
+mergeDeepWith(
+  (oldVal, newVal) => oldVal + newVal,
+  { x: { y: 123 } },
+  { x: { y: 456 } }
+);
+// => { x: { y: 579 } }
+```
+
+## Gotchas
+
+- `setIn`/`updateIn`/`mergeIn` create missing intermediates as empty `Map`s. If a layer should be a `List`, build it yourself (e.g. `setIn(state, ['items'], List())` first) — paths cannot signal which container type to materialize.
+- `mergeDeep` does NOT element-merge `List`s/`Array`s — same-key indexed values are concatenated, and `Set`s are unioned. To deep-merge by index, write a custom `mergeDeepWith` merger.
+- A category mismatch at a key (e.g. existing `List`, incoming `Map`) replaces under `mergeDeep`; only `mergeDeepWith` lets you intervene.
+- Top-level functional forms accept plain JS as the target and return the same kind back (object in / object out, `Map` in / `Map` out). The instance methods are only on Immutable collections.
+- All operations are identity-preserving on no-op: `setIn(c, path, c.getIn(path)) === c`, `merge(c) === c` when nothing changes.
+- `getIn`/`hasIn` perform exact key lookups. `getIn(list, [-1])` does not return the last element — use `list.last()`.
+
+## See also
+
+- `list.md`, `map.md` — instance variants and additional `*In` methods (`mergeIn`, `mergeDeepIn`).
+- `record.md` — path access on `Record` respects declared fields.
+- `conversions.md` — when mixing JS and Immutable inputs across these helpers.
+- `shallow-functional.md` — single-level versions (`get`, `set`, `update`, `remove`, `has`).

package/skill/immutable-js/references/equality.md

@@ -0,0 +1,95 @@
+Immutable.js treats collections as VALUES, not references: two distinct `Map({a: 1})` instances are equal even though `===` says otherwise. This is implemented via two protocols, `equals(other): boolean` and `hashCode(): number`, together forming the `ValueObject` interface. The top-level `is(a, b)` function dispatches to the appropriate comparison. Anything that implements both methods becomes a `ValueObject` and can be used as a `Map`/`OrderedMap` key or a `Set`/`OrderedSet` member with value-equality semantics — so two structurally equal custom objects collapse to a single entry, and lookup works with any equivalent instance.
+
+## is
+
+### is
+
+```ts
+is(first: unknown, second: unknown): boolean
+```
+
+Value-equality check. Returns `true` for SameValue semantics (handles `NaN === NaN` as true), but unlike `Object.is` treats `0` and `-0` as equal (matching ES6 `Map` key equality). For `ValueObject` arguments dispatches to `first.equals(second)`. For primitives and non-`ValueObject` objects falls back to `Object.is`-style comparison.
+
+```js
+import { Map, is } from 'immutable';
+const a = Map({ x: 1, y: 2 });
+const b = Map({ x: 1, y: 2 });
+a !== b;             // true — distinct instances
+Object.is(a, b);     // false
+is(a, b);            // true — value-equal
+a.equals(b);         // true — same as is(a, b)
+```
+
+Used internally throughout Immutable.js for `Map` key equality, `Set` membership, `.includes()`, `.indexOf()`, etc.
+
+## hash
+
+### hash
+
+```ts
+hash(value: unknown): number
+```
+
+Returns a 31-bit integer hash for any value. For `ValueObject`s, calls `value.hashCode()`. For primitives (strings, numbers, booleans, `null`, `undefined`), produces a deterministic per-value hash. For plain objects, plain arrays, `Date`, etc. that don't implement `hashCode`, generates a unique per-instance hash and memoizes it on the object — so the hash represents referential identity (stable across mutations), not value equality.
+
+Used internally by `Map`/`Set` for hash bucketing. Balances speed and collision avoidance; not cryptographically secure. _New in v4.0._
+
+## ValueObject
+
+### ValueObject
+
+```ts
+interface ValueObject {
+  equals(other: unknown): boolean;
+  hashCode(): number;
+}
+```
+
+The interface to implement so a custom class behaves as a value: usable as a `Map`/`OrderedMap` key, in a `Set`/`OrderedSet`, and comparable via `is()`. All Immutable collections (`List`, `Map`, `Set`, `Record`, etc.) already implement it.
+
+Contract:
+
+- `a.equals(b) === true` MUST imply `a.hashCode() === b.hashCode()` (the converse is not required — hash collisions are allowed).
+- `hashCode()` MUST return a Uint32. Idiomatic guard: `return myHash | 0`.
+- `hashCode()` is not guaranteed to be called before `equals()`; lookups always verify via `equals()`.
+
+```js
+import { Set, hash } from 'immutable';
+
+class Point {
+  constructor(x, y) { this.x = x; this.y = y; }
+  equals(other) {
+    return other instanceof Point && other.x === this.x && other.y === this.y;
+  }
+  hashCode() {
+    return (hash(this.x) * 31 + hash(this.y)) | 0;
+  }
+}
+
+const s = Set([new Point(1, 2)]);
+s.has(new Point(1, 2)); // true — different instance, value-equal
+```
+
+## isValueObject
+
+### isValueObject
+
+```ts
+isValueObject(maybeValue: unknown): maybeValue is ValueObject
+```
+
+Returns `true` iff `maybeValue` is a JavaScript object that has BOTH `equals` and `hashCode` methods. Any two value objects can be compared with `is()` and used as `Map` keys or `Set` members.
+
+## Reference identity vs value equality
+
+- All Immutable collections implement `ValueObject`, so `is(a, b)` and `a.equals(b)` give value-equality.
+- Persistent operations that don't change content return the SAME identity: `map.set('k', v)` where `map.get('k') === v` returns `map` itself (`===`). This makes `===` a valid fast-path for "definitely unchanged" — useful for `React.memo`, `shouldComponentUpdate`, and memoization.
+- JavaScript's `===` between two distinct Immutable collections with equal content is `false`. This is intentional: cheap reference checks remain cheap, and value-equality is opt-in via `is()` / `.equals()`.
+- Rule of thumb: use `===` to detect "this reference changed"; use `is()` / `.equals()` to ask "is the content the same?".
+
+## See also
+
+- `map.md`, `set.md` — collections whose key/member identity is governed by `is`/`hashCode`.
+- `record.md` — `Record` instances are `ValueObject`s, equal when their fields are value-equal.
+- `predicates.md` — `isImmutable`, `isCollection`, etc. for runtime type checks.
+- `conversions.md` — `fromJS`/`toJS` boundary where value identity is created/lost.

package/skill/immutable-js/references/list.md

@@ -0,0 +1,266 @@
+`List` is an ordered, indexed, dense, immutable collection — the Immutable.js analogue of a JavaScript Array. It is fully persistent with `O(log32 N)` `get`/`set` and `O(1)` `push`/`pop`, and it implements Deque (efficient `unshift`/`shift` as well). Reach for `List` when you need an ordered sequence keyed by integer index; prefer `Map` for keyed data, `Set`/`OrderedSet` for uniqueness, and `Stack` when you only push/pop one end and want amortised `O(1)` random access via head. Unlike a JS Array, `List` does not distinguish "unset" from `undefined`: `forEach` visits every index from `0` to `size`.
+
+## Construction
+
+```ts
+import { List } from 'immutable';
+```
+
+### List / List.of / List.isList
+
+```ts
+function List<T>(collection?: Iterable<T> | ArrayLike<T>): List<T>;
+function List.of<T>(...values: Array<T>): List<T>;
+function List.isList(maybeList: unknown): maybeList is List<unknown>;
+```
+
+Factory function (no `new`). `List.of` is variadic; values are not converted. See also `predicates.md`.
+
+```js
+List();                  // => List []
+List([1, 2, 3, 4]);      // => List [ 1, 2, 3, 4 ]
+List.of('a', 'b');       // => List [ "a", "b" ]
+```
+
+## Reading
+
+### size / get / has / includes (alias `contains`) / first / last / indexOf / lastIndexOf
+
+```ts
+readonly size: number;
+get(index: number): T | undefined;
+get<NSV>(index: number, notSetValue: NSV): T | NSV;
+has(index: number): boolean;
+includes(value: T): boolean;
+first<NSV = undefined>(notSetValue?: NSV): T | NSV;
+last<NSV = undefined>(notSetValue?: NSV): T | NSV;
+indexOf(value: T): number;
+lastIndexOf(value: T): number;
+```
+
+Negative indices on `get` count from the end (`get(-1)` is the last item). `includes` uses `Immutable.is` for equality. `indexOf`/`lastIndexOf` return `-1` if not found.
+
+### find / findLast / findIndex / findLastIndex / findEntry / findLastEntry / findKey / findLastKey
+
+```ts
+find(predicate, context?, notSetValue?): T | undefined;
+findLast(predicate, context?, notSetValue?): T | undefined;
+findIndex(predicate, context?): number;
+findLastIndex(predicate, context?): number;
+findEntry(predicate, context?): [number, T] | undefined;
+findLastEntry(predicate, context?): [number, T] | undefined;
+findKey(predicate, context?): number | undefined;
+findLastKey(predicate, context?): number | undefined;
+```
+
+`predicate: (value: T, index: number, iter: this) => boolean`. `*Last` variants iterate in reverse.
+
+### keyOf / lastKeyOf / max / min / maxBy / minBy
+
+```ts
+keyOf(searchValue: T): number | undefined;
+lastKeyOf(searchValue: T): number | undefined;
+max(comparator?: (a: T, b: T) => number): T | undefined;
+min(comparator?: (a: T, b: T) => number): T | undefined;
+maxBy<C>(mapper: (value: T, key: number, iter: this) => C, comparator?: (a: C, b: C) => number): T | undefined;
+minBy<C>(mapper: (value: T, key: number, iter: this) => C, comparator?: (a: C, b: C) => number): T | undefined;
+```
+
+## Persistent changes
+
+### set
+
+```ts
+set(index: number, value: T): List<T>;
+```
+
+Negative `index` is allowed. Setting beyond `size` grows the List (gaps become `undefined`). `List().set(50000, 'v').size === 50001`.
+
+### delete (alias `remove`)
+
+```ts
+delete(index: number): List<T>;
+remove(index: number): List<T>;
+```
+
+Re-indexes successors; `O(N)`. Cannot be used in `withMutations`.
+
+### insert
+
+```ts
+insert(index: number, value: T): List<T>;
+```
+
+Equivalent to `splice(index, 0, value)`. `O(N)`. Cannot be used in `withMutations`.
+
+### clear
+
+```ts
+clear(): List<T>;
+```
+
+### push / pop / unshift / shift
+
+```ts
+push(...values: Array<T>): List<T>;
+pop(): List<T>;
+unshift(...values: Array<T>): List<T>;
+shift(): List<T>;
+```
+
+`pop`/`shift` return the trimmed List, not the removed value (use `last()`/`first()`).
+
+### update
+
+```ts
+update(index: number, notSetValue: T, updater: (value: T) => T): this;
+update(index: number, updater: (value: T | undefined) => T | undefined): this;
+update<R>(updater: (value: this) => R): R;
+```
+
+The single-argument form is a "thru" / pipe: `list.update(sum)` calls `sum(list)`. See `shallow-functional.md`.
+
+### setSize
+
+```ts
+setSize(size: number): List<T>;
+```
+
+Truncates or pads with `undefined`. Pair with `withMutations` when the final size is known up front for faster construction.
+
+## Deep persistent changes
+
+See `deep-updates.md` for full semantics, key-path conventions, and interaction with nested plain JS objects/arrays.
+
+### setIn / deleteIn (alias `removeIn`) / updateIn / mergeIn / mergeDeepIn
+
+```ts
+setIn(keyPath: Iterable<unknown>, value: unknown): this;
+deleteIn(keyPath: Iterable<unknown>): this;
+removeIn(keyPath: Iterable<unknown>): this;
+updateIn(keyPath: Iterable<unknown>, notSetValue: unknown, updater: (value: unknown) => unknown): this;
+updateIn(keyPath: Iterable<unknown>, updater: (value: unknown) => unknown): this;
+mergeIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this;
+mergeDeepIn(keyPath: Iterable<unknown>, ...collections: Array<unknown>): this;
+```
+
+Numeric keys index into the List; string keys traverse nested Maps/objects. `deleteIn` cannot be used in `withMutations`; the others can.
+
+## Sequence algorithms
+
+### concat (alias `merge`) / map / flatMap
+
+```ts
+concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): List<T | C>;
+map<M>(mapper: (value: T, key: number, iter: this) => M, context?: unknown): List<M>;
+flatMap<M>(mapper: (value: T, key: number, iter: this) => Iterable<M>, context?: unknown): List<M>;
+```
+
+`flatMap` is equivalent to `list.map(...).flatten(true)`.
+
+### filter / filterNot / partition
+
+```ts
+filter<F extends T>(predicate: (value: T, index: number, iter: this) => value is F, context?: unknown): List<F>;
+filter(predicate: (value: T, index: number, iter: this) => unknown, context?: unknown): this;
+filterNot(predicate: (value: T, index: number, iter: this) => boolean, context?: unknown): this;
+partition<F extends T, C>(predicate: (this: C, value: T, index: number, iter: this) => value is F, context?: C): [List<T>, List<F>];
+partition<C>(predicate: (this: C, value: T, index: number, iter: this) => unknown, context?: C): [this, this];
+```
+
+`filter`/`filterNot` always return a new instance. `partition` returns `[falses, trues]`.
+
+### zip / zipAll / zipWith
+
+```ts
+zip<U>(other: Collection<unknown, U>): List<[T, U]>;
+zipAll<U>(other: Collection<unknown, U>): List<[T, U]>;
+zipWith<U, Z>(zipper: (value: T, otherValue: U) => Z, otherCollection: Collection<unknown, U>): List<Z>;
+```
+
+`zip` stops at the shortest input; `zipAll` pads shorter inputs with `undefined`.
+
+### slice / reverse / sort / sortBy / groupBy
+
+```ts
+slice(begin?: number, end?: number): this;
+reverse(): this;
+sort(comparator?: (a: T, b: T) => PairSorting | number): this;
+sortBy<C>(mapper: (value: T, key: number, iter: this) => C, comparator?: (a: C, b: C) => number): this;
+groupBy<G>(grouper: (value: T, index: number, iter: this) => G, context?: unknown): Map<G, this>;
+```
+
+`slice` accepts negative indices (inherited from `Collection.Indexed`). `sort`/`sortBy` are stable, eager, and always return a new instance. `groupBy` is also eager.
+
+### Other (inherited from `Collection.Indexed`)
+
+`interpose(separator)`, `interleave(...collections)`, `splice(index, removeNum, ...values)`, `flatten(depth?)`, `shuffle(random?)`, `mapKeys`, `mapEntries`.
+
+## Conversion
+
+See `conversions.md` for `toJS` deep-conversion rules and the relationship with `toJSON` / `JSON.stringify`.
+
+### toArray / toJS / toJSON
+
+```ts
+toArray(): Array<T>;          // shallow
+toJS(): Array<DeepCopy<T>>;   // deep — recursively unwraps nested Immutable collections
+toJSON(): Array<T>;           // shallow; called by JSON.stringify
+```
+
+### toSeq / toIndexedSeq / toKeyedSeq / toSetSeq
+
+```ts
+toSeq(): Seq.Indexed<T>;
+toIndexedSeq(): Seq.Indexed<T>;
+toKeyedSeq(): Seq.Keyed<number, T>;
+toSetSeq(): Seq.Set<T>;
+```
+
+`toKeyedSeq` preserves `[index, value]` pairs through later filter/map.
+
+### asImmutable / asMutable
+
+```ts
+asImmutable(): this;
+asMutable(): this;
+```
+
+See "Mutation batching".
+
+## Mutation batching
+
+`withMutations` returns a transient mutable copy; once the callback returns, the result is frozen back into a regular persistent `List`. Useful when chaining many updates to avoid intermediate allocations.
+
+### withMutations
+
+```ts
+withMutations(mutator: (mutable: this) => unknown): this;
+```
+
+Not every method is safe inside the mutator — methods that re-index (`delete`, `insert`, `splice`, `interleave`, `deleteIn`) are unsafe. Each method's signature in this file notes whether it is safe.
+
+### asMutable / asImmutable
+
+```ts
+asMutable(): this;
+asImmutable(): this;
+```
+
+Alternative to `withMutations` when you want explicit begin/end calls.
+
+### wasAltered
+
+```ts
+wasAltered(): boolean;
+```
+
+True if a transient mutation actually changed the collection.
+
+## See also
+
+- `Collection.Indexed` for inherited iteration, search, and reduction methods (`forEach`, `reduce`, `every`, `some`, `count`, `keys`, `values`, `entries`, etc.)
+- `deep-updates.md` for `setIn` / `updateIn` / `mergeIn` / `mergeDeepIn` semantics
+- `shallow-functional.md` for `update`-as-pipe and other functional patterns
+- `conversions.md` for `toJS` vs `toJSON` vs `toArray`
+- `predicates.md` for `List.isList` and other type guards