tutuca 0.9.39 → 0.9.41

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

@@ -0,0 +1,248 @@
+`Seq` is a lazy, immutable sequence. Operations such as `map`, `filter`, `take`, and `flatMap` build up a description of computation that is not executed until values are pulled out of the sequence. Use `Seq` for chaining transforms without allocating intermediate concrete collections, for representing infinite or potentially-infinite sequences, and for cheap lazy views over existing collections (arrays, objects, other `Collection`s). Once a `Seq` is consumed via a strict (terminating) operation, the chain may cache its result internally if `cacheResult()` was called; otherwise re-iteration re-runs the upstream chain.
+
+`Seq` is a conversion function, not a class — never use `new`. The `Seq` constructor inspects its argument and returns `Seq.Keyed`, `Seq.Indexed`, or (when given a `Collection.Set`) `Seq.Set`.
+
+## Laziness — what to expect
+
+- `seq.map(...).filter(...).take(10)` performs zero work until something pulls values
+- Terminating ops that materialize / iterate: `toArray`, `toJS`, `toJSON`, `toList`, `toMap`, `toOrderedMap`, `toSet`, `toOrderedSet`, `toStack`, `toObject`, `forEach`, `reduce`, `reduceRight`, `every`, `some`, `find`, `findEntry`, `findLast`, `count`, `countBy`, `join`, `get`, `first`, `last`, and `for..of` iteration
+- `toSeq()` is a no-op on a `Seq` and stays lazy
+- Infinite sequences (e.g., from `Range(1, Infinity)`, `Repeat('x')`) are fine as long as a downstream operation bounds them via `take`, `slice`, `takeWhile`, `takeUntil`, or a short-circuiting op like `find`/`some`
+- Side effects placed inside `map`/`filter` callbacks do NOT run at chain-build time — they run when (and as many times as) values are pulled. Each terminating call re-runs the chain unless `cacheResult()` was inserted
+- Short-circuit consumers (`find`, `some`, `every`, `get(i)`) only iterate as far as needed: `Seq([1,2,3,4]).filter(odd).map(square).get(1)` calls the filter three times and the map exactly once
+
+## The three Seq variants
+
+- `Seq.Keyed<K, V>` — key/value pairs; iteration yields `[K, V]` entries. Adds `flip`, `mapKeys`, `mapEntries`. Constructed from objects, `[K, V]` iterables, or other keyed collections.
+- `Seq.Indexed<T>` — ordered values with numeric indices; iteration yields `T`. Adds `interpose`, `interleave`, `splice`, `zip`, `zipAll`, `zipWith`. Constructed from arrays, array-likes, or non-keyed iterables.
+- `Seq.Set<T>` — values where keys equal values; iteration yields `T`. Inherits `Collection.Set` ops (`union`, `intersect`, `subtract`, `isSubset`, `isSuperset`). Because `Seq` is lazy, `Seq.Set` does NOT enforce uniqueness eagerly — duplicates may flow through until a strict `Set`/`OrderedSet` materialization deduplicates.
+
+## Construction
+
+```ts
+import { Seq, Range, Repeat } from 'immutable';
+
+Seq();                                     // empty, untyped
+Seq(iterable);                             // dispatched: Indexed/Keyed/Set
+Seq.Keyed<K, V>(entries?: Iterable<[K,V]>);
+Seq.Keyed<V>(obj: { [k: string]: V });
+Seq.Indexed<T>(collection?: Iterable<T> | ArrayLike<T>);
+Seq.Indexed.of<T>(...values: T[]);
+Seq.Set<T>(collection?: Iterable<T> | ArrayLike<T>);
+Seq.Set.of<T>(...values: T[]);
+```
+
+`Range(start?, end?, step?)` and `Repeat(value, times?)` produce `Seq.Indexed` instances and are the canonical way to create infinite indexed sequences (see range-repeat.md).
+
+## Construction examples
+
+```ts
+import { Seq, Range, Map } from 'immutable';
+
+// Array → Seq.Indexed
+Seq([1, 2, 3]);                            // Seq.Indexed [ 1, 2, 3 ]
+
+// Object → Seq.Keyed
+Seq({ a: 1, b: 2 });                       // Seq.Keyed { "a": 1, "b": 2 }
+
+// Wrapping an existing concrete collection preserves variant
+Seq(Map({ a: 1, b: 2 }));                  // Seq.Keyed
+Seq.Indexed.of(1, 2, 3);                   // Seq.Indexed [ 1, 2, 3 ]
+Seq.Set.of('a', 'b', 'a');                 // Seq.Set (duplicates not yet collapsed)
+
+// Lazy chain — map/filter run only on toArray()
+Seq([1, 2, 3, 4])
+  .map(x => x * x)
+  .filter(x => x > 4)
+  .toArray();                              // [ 9, 16 ]
+
+// Infinite sequence, bounded by take
+Range(1, Infinity)                         // 1, 2, 3, ...
+  .map(x => x * x)
+  .take(5)
+  .toList();                               // List [ 1, 4, 9, 16, 25 ]
+
+// Short-circuit: only iterates until first match
+Range(1, Infinity).find(n => n * n > 100); // 11
+```
+
+## Methods unique-or-emphasized for Seq
+
+Most behavior is inherited from `Collection`, `Collection.Keyed`, `Collection.Indexed`, and `Collection.Set` (see collection.md). The methods below are either unique to `Seq` or behave differently because of laziness.
+
+### cacheResult
+
+```ts
+cacheResult(): this
+```
+
+Forces the current chain to evaluate once, caches results in memory, and returns a new `Seq` whose downstream ops iterate the cache. After `cacheResult()` the `Seq` always has a defined `size`. Use when a `Seq` will be iterated multiple times and the upstream chain is expensive — without it, each terminating op re-runs the whole chain.
+
+```ts
+const squares = Seq([1, 2, 3]).map(x => x * x).cacheResult();
+squares.join() + squares.join();           // map runs 3 times total, not 6
+```
+
+### toSeq
+
+```ts
+toSeq(): this
+```
+
+Returns the same `Seq` (no-op). Each variant declares this so that chains stay typed at the same variant.
+
+### map / filter / flatMap / partition / concat
+
+Lazy on `Seq` — these do not allocate any concrete collection. The variant-typed overloads (`Seq.Keyed`, `Seq.Indexed`, `Seq.Set`) preserve the variant in the return type. Behavior matches the inherited `Collection` versions; see collection.md for full signatures.
+
+### size
+
+```ts
+readonly size: number | undefined;
+```
+
+May be `undefined` when the size cannot be determined without iterating. Operations that change cardinality unpredictably — notably `filter` — yield a `Seq` with `size === undefined`. `Seq`s built from arrays, objects, `Range`, `Repeat`, and `cacheResult()` always have a numeric `size` (which is `Infinity` for unbounded ranges/repeats).
+
+### Materialization helpers
+
+`toList`, `toMap`, `toOrderedMap`, `toSet`, `toOrderedSet`, `toStack`, `toArray`, `toObject`, `toJS`, `toJSON` all force evaluation. On infinite sequences they will hang — bound the sequence with `take`/`slice` first. The variant of the resulting concrete collection follows the destination, not the source: a `Seq.Indexed` consumed via `toMap()` becomes a `Map<number, T>` keyed by index.
+
+### Seq.isSeq
+
+```ts
+Seq.isSeq(maybeSeq: unknown): maybeSeq is Seq.Indexed<unknown> | Seq.Keyed<unknown, unknown> | Seq.Set<unknown>
+```
+
+True only for actual `Seq` instances (not for backing concrete collections like `List`/`Map`/`Set`). Prefer the broader `isIndexed`, `isKeyed`, `isAssociative` predicates from predicates.md when the only thing you care about is shape.
+
+## Variant-specific highlights
+
+Each variant inherits everything from the matching `Collection.X` (see collection.md). Below are the methods you will reach for on a `Seq` that are specific to that shape.
+
+### Seq.Keyed
+
+```ts
+flip(): Seq.Keyed<V, K>
+mapKeys<M>(mapper: (key: K, value: V, iter: this) => M, context?: unknown): Seq.Keyed<M, V>
+mapEntries<KM, VM>(
+  mapper: (entry: [K, V], index: number, iter: this) => [KM, VM] | undefined,
+  context?: unknown
+): Seq.Keyed<KM, VM>
+concat<KC, VC>(...colls: Array<Iterable<[KC, VC]>>): Seq.Keyed<K | KC, V | VC>
+toArray(): Array<[K, V]>
+toJS(): { [key in PropertyKey]: DeepCopy<V> }
+```
+
+`flip` swaps keys and values lazily. `mapKeys` rewrites only the keys. `mapEntries` rewrites both as a tuple, and returning `undefined` from the mapper drops the entry (a lazy filter+map combined).
+
+### Seq.Indexed
+
+```ts
+zip<U>(other: Collection<unknown, U>): Seq.Indexed<[T, U]>
+zipAll<U>(other: Collection<unknown, U>): Seq.Indexed<[T, U]>     // pads with undefined
+zipWith<U, Z>(zipper: (a: T, b: U) => Z, other: Collection<unknown, U>): Seq.Indexed<Z>
+concat<C>(...valuesOrCollections: Array<Iterable<C> | C>): Seq.Indexed<T | C>
+toArray(): Array<T>
+toJS(): Array<DeepCopy<T>>
+```
+
+Inherits `interpose`, `interleave`, `splice`, `flatten`, `findIndex`, `indexOf`, etc. from `Collection.Indexed` (see collection.md). All remain lazy.
+
+```ts
+Seq([1, 2, 3]).zip(Seq(['a', 'b', 'c']));  // Seq [ [1,'a'], [2,'b'], [3,'c'] ]
+Seq([1, 2, 3]).interpose(0).toArray();     // [ 1, 0, 2, 0, 3 ]
+```
+
+### Seq.Set
+
+```ts
+concat<U>(...collections: Array<Iterable<U>>): Seq.Set<T | U>
+toArray(): Array<T>
+toJS(): Array<DeepCopy<T>>
+```
+
+Inherits `union`, `intersect`, `subtract`, `isSubset`, `isSuperset` from `Collection.Set` (see collection.md). Note: because evaluation is deferred, duplicate values produced by `union`/`concat` only get deduplicated when materialized into a real `Set` or `OrderedSet`.
+
+```ts
+Seq.Set.of(1, 2, 3)
+  .union([3, 4, 5])
+  .toSet();                                // Set { 1, 2, 3, 4, 5 } — dedup at toSet
+```
+
+## Gotchas
+
+- Side effects in `map`/`filter`/`flatMap` callbacks fire on consumption, not at chain-build time, and re-fire on every iteration unless `cacheResult()` was called
+- Re-iterating a `Seq` re-runs the entire upstream chain — use `cacheResult()` if you will iterate twice or more, but be aware it must fully evaluate (so do not call it on an infinite `Seq`)
+- `.size` may be `undefined` after `filter` (and similar shape-changing ops) and `Infinity` for unbounded `Range`/`Repeat`; never assume `.size` returns a finite number
+- Strict materializers (`toList`, `toArray`, `toJS`, `toMap`, `toSet`, `forEach`, `reduce`, `every`, `count`, `join`) will hang on an unbounded `Seq` — bound it with `take`/`slice`/`takeWhile` or use a short-circuiting op like `find`/`some`
+- An iterator object (one without `Symbol.iterator` returning `this`) passed to `Seq()` is treated as a plain object and becomes a `Seq.Keyed` over its enumerable keys, which is rarely what you want — wrap it in an iterable first or use `Seq.Indexed(Array.from(iter))`
+- `Seq.Set` does not enforce value uniqueness; only the eager `Set`/`OrderedSet` collections do
+- `Seq.Keyed` allows duplicate keys to flow through the chain — they are only collapsed when converted to a `Map`/`OrderedMap` (last write wins)
+- `Seq` is NOT `Collection` — `isCollection(seq)` is true, but `isList(seq)`/`isMap(seq)`/`isSet(seq)` are all false. Use `isSeq` plus `isIndexed`/`isKeyed` for runtime checks
+- `Seq` does not have a single canonical "empty" instance — `Seq()` returns a fresh empty seq with `K`/`V` defaulted to `unknown`; provide type parameters when needed
+
+## Common patterns
+
+### Lazy view over a concrete collection
+
+Calling `.toSeq()` on a `List`, `Map`, `Set`, etc. returns the matching `Seq` variant, letting you chain transforms without allocating an intermediate `List`/`Map`/`Set` per step:
+
+```ts
+import { List } from 'immutable';
+
+const list = List([1, 2, 3, 4, 5]);
+const result = list
+  .toSeq()                                 // Seq.Indexed view
+  .map(x => x * 2)
+  .filter(x => x > 4)
+  .reduce((sum, x) => sum + x, 0);         // 24
+```
+
+### Caching a chain used twice
+
+```ts
+const expensive = Seq(rows)
+  .map(parseRow)
+  .filter(isValid)
+  .cacheResult();                          // run parseRow/isValid exactly once
+
+const count = expensive.count();
+const first = expensive.first();           // does NOT re-parse
+```
+
+### Bounded infinite sequence
+
+```ts
+import { Range } from 'immutable';
+
+// First 10 primes — Range is infinite, take bounds it
+Range(2, Infinity)
+  .filter(isPrime)
+  .take(10)
+  .toArray();
+```
+
+### Object → keyed transform → object
+
+```ts
+Seq({ a: 1, b: 2, c: 3 })
+  .filter(v => v > 1)
+  .mapKeys(k => k.toUpperCase())
+  .toObject();                             // { B: 2, C: 3 }
+```
+
+### Building from generators
+
+A generator function returns an iterator. Wrap it in `Seq.Indexed` (don't pass the iterator directly to `Seq()`, which would treat it as a keyed object):
+
+```ts
+function* nats() { let n = 0; while (true) yield n++; }
+Seq.Indexed(nats()).take(5).toArray();     // [ 0, 1, 2, 3, 4 ]
+```
+
+## See also
+
+- collection.md — parent classes (`Collection`, `Collection.Keyed`, `Collection.Indexed`, `Collection.Set`) supply the bulk of the inherited API: `take`, `skip`, `slice`, `reverse`, `sort`, `sortBy`, `groupBy`, `count`, `find`, `every`, `some`, `reduce`, `flatten`, `interpose`, `interleave`, `splice`, `union`, `intersect`, `subtract`, etc.
+- range-repeat.md — `Range()` and `Repeat()` produce `Seq.Indexed` and are the idiomatic way to build infinite indexed sequences
+- list.md, map.md, set.md — eager equivalents; convert with `toList()`, `toMap()`, `toSet()` once a chain should be materialized
+- predicates.md — `isSeq`, `isIndexed`, `isKeyed`, `isAssociative` for runtime type checks

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

@@ -0,0 +1,270 @@
+`Set` is an unordered collection of unique values with `O(log32 N)` `add` and `has`. Uniqueness is determined by `Immutable.is` value-equality, not reference identity, so `Set([Map({a: 1}), Map({a: 1})]).size` is `1` (a native `Set` would yield `2`). Iteration order is undefined but stable across iterations of the same instance. `OrderedSet` is a variant that preserves insertion order at the cost of more memory and slower (amortized, non-stable) `add`. Both are factory functions — call them without `new`.
+
+```js
+import { Set, OrderedSet } from 'immutable';
+```
+
+## Construction
+
+### Set
+
+```ts
+Set<T>(collection?: Iterable<T> | ArrayLike<T>): Set<T>
+```
+
+Empty when called with no argument; otherwise dedupes the input.
+
+### Set.of
+
+```ts
+Set.of<T>(...values: Array<T>): Set<T>
+```
+
+Variadic equivalent of `Set([...])`.
+
+### Set.fromKeys
+
+```ts
+Set.fromKeys<T>(iter: Collection.Keyed<T, unknown>): Set<T>
+Set.fromKeys<T>(iter: Collection<T, unknown>): Set<T>
+Set.fromKeys(obj: { [key: string]: unknown }): Set<string>
+```
+
+Builds a Set from the keys of a Keyed collection or plain object.
+
+```js
+Set.fromKeys({ a: 1, b: 2 }); // => Set { "a", "b" }
+```
+
+### Set.intersect / Set.union (static)
+
+```ts
+Set.intersect<T>(sets: Iterable<Iterable<T>>): Set<T>
+Set.union<T>(sets: Iterable<Iterable<T>>): Set<T>
+```
+
+Static set-algebra over an iterable of iterables (note: a single argument, unlike the instance methods).
+
+## Reading
+
+### has / includes
+
+```ts
+has(value: T): boolean
+includes(value: T): boolean   // alias: contains
+```
+
+Membership test using `Immutable.is`.
+
+### size
+
+```ts
+readonly size: number
+```
+
+### first / last
+
+```ts
+first<NSV>(notSetValue: NSV): T | NSV
+first(): T | undefined
+last<NSV>(notSetValue: NSV): T | NSV
+last(): T | undefined
+```
+
+For a plain `Set`, "first"/"last" follow the stable but undefined iteration order; for `OrderedSet`, they follow insertion order.
+
+### find
+
+```ts
+find(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown, notSetValue?: T): T | undefined
+```
+
+First value for which `predicate` returns truthy. Companions: `findLast`, `findEntry`, `findKey`, `keyOf` (note: in a Set, key === value).
+
+## Persistent changes
+
+### add
+
+```ts
+add(value: T): this
+```
+
+Returns a Set including `value`. No-op (returns same instance) if already present. Safe in `withMutations`.
+
+### delete / remove
+
+```ts
+delete(value: T): this
+remove(value: T): this   // alias of delete
+```
+
+Returns a Set without `value`. Safe in `withMutations`. Prefer `remove` if targeting IE8.
+
+### clear
+
+```ts
+clear(): this
+```
+
+Returns an empty Set of the same type.
+
+### union / merge / concat
+
+```ts
+union<C>(...collections: Array<Iterable<C>>): Set<T | C>
+```
+
+Adds every value from each provided iterable. Variadic — accepts multiple iterables in one call. `merge` and `concat` are aliases.
+
+### intersect
+
+```ts
+intersect(...collections: Array<Iterable<T>>): this
+```
+
+Keeps only values present in this Set AND every provided iterable. Variadic.
+
+### subtract
+
+```ts
+subtract(...collections: Array<Iterable<T>>): this
+```
+
+Removes every value contained in any of the provided iterables. Variadic.
+
+```js
+Set([1, 2, 3]).subtract([1, 3]); // => Set { 2 }
+```
+
+All four set-algebra instance methods are safe in `withMutations`.
+
+## Sequence algorithms
+
+### map
+
+```ts
+map<M>(mapper: (value: T, key: T, iter: this) => M, context?: unknown): Set<M>
+```
+
+In a Set, `key === value` for every callback.
+
+### flatMap
+
+```ts
+flatMap<M>(mapper: (value: T, key: T, iter: this) => Iterable<M>, context?: unknown): Set<M>
+```
+
+### filter / filterNot
+
+```ts
+filter<F extends T>(predicate: (value: T, key: T, iter: this) => value is F, context?: unknown): Set<F>
+filter(predicate: (value: T, key: T, iter: this) => unknown, context?: unknown): this
+filterNot(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): this
+```
+
+Always return a new instance. The type-guard overload of `filter` narrows the element type.
+
+### sort / sortBy
+
+```ts
+sort(comparator?: Comparator<T>): this & OrderedSet<T>
+sortBy<C>(comparatorValueMapper: (value: T, key: T, iter: this) => C, comparator?: (a: C, b: C) => number): this & OrderedSet<T>
+```
+
+Eager. Returns an `OrderedSet`. Default comparator uses `<`/`>`. The comparator may return a `PairSorting` enum value.
+
+### groupBy
+
+```ts
+groupBy<G>(grouper: (value: T, key: T, iter: this) => G, context?: unknown): Map<G, Set<T>>
+```
+
+Eager. Buckets values into a `Map` of `Set`s.
+
+### partition
+
+```ts
+partition(predicate: (value: T, key: T, iter: this) => boolean, context?: unknown): [this, this]
+```
+
+Returns `[falseValues, trueValues]`.
+
+## Conversion
+
+### toArray / toJS / toJSON
+
+```ts
+toArray(): Array<T>
+toJS(): Array<DeepCopy<T>>
+toJSON(): Array<T>
+```
+
+`toJS` recurses into nested Immutable collections; `toJSON`/`toArray` are shallow.
+
+### toSeq / toIndexedSeq / toSetSeq / toKeyedSeq
+
+```ts
+toSeq(): Seq.Set<T>
+toIndexedSeq(): Seq.Indexed<T>
+toSetSeq(): Seq.Set<T>
+toKeyedSeq(): Seq.Keyed<T, T>
+```
+
+### toMap / toOrderedMap / toOrderedSet / toList / toStack
+
+Convert to other Immutable collections; in a Set, `toMap()` produces `Map<T, T>` of `[value, value]` pairs.
+
+### asImmutable / asMutable
+
+```ts
+asMutable(): this
+asImmutable(): this
+```
+
+See conversions.md for the full conversion matrix and `toJS` deep-conversion rules.
+
+## Mutation batching
+
+### withMutations
+
+```ts
+withMutations(mutator: (mutable: this) => unknown): this
+```
+
+Apply a batch of mutations to a transient mutable copy and get back an immutable result. Only `add`, `delete`/`remove`, `clear`, `union`, `intersect`, `subtract` are safe inside.
+
+```js
+Set([1, 2, 3]).withMutations(s => {
+  s.add(4).add(5).delete(1);
+}); // => Set { 2, 3, 4, 5 }
+```
+
+### wasAltered
+
+```ts
+wasAltered(): boolean
+```
+
+True only on a mutable copy (from `asMutable`) that has been modified.
+
+## OrderedSet
+
+Same factory shape and full API as `Set`, plus `OrderedSet.isOrderedSet`. Iteration follows insertion order, matching native ES6 `Set`.
+
+```ts
+OrderedSet<T>(collection?: Iterable<T> | ArrayLike<T>): OrderedSet<T>
+OrderedSet.of<T>(...values: Array<T>): OrderedSet<T>
+OrderedSet.fromKeys<T>(iter: Collection<T, unknown>): OrderedSet<T>
+OrderedSet.isOrderedSet(maybeOrderedSet: unknown): boolean
+```
+
+Adding a value that is already present does NOT move it to the end — original position is retained. `OrderedSet#add` is amortized `O(log32 N)` but not stable, and uses more memory than `Set`. Use it only when iteration order matters; otherwise prefer `Set`.
+
+`union`, `merge`, `concat` on an `OrderedSet` return `OrderedSet<T | C>` (preserving the ordered type).
+
+## See also
+
+- `collection.md` — `Collection.Set` shared interface (all the inherited iteration/search/reduce methods: `forEach`, `reduce`, `every`, `some`, `count`, `countBy`, `max`/`maxBy`, `min`/`minBy`, `isSubset`, `isSuperset`, `slice`, `take`/`skip` family).
+- `equality.md` — `Immutable.is`, which defines Set uniqueness and `has`/`includes` behavior, plus `hashCode` semantics.
+- `predicates.md` — `Set.isSet`, `OrderedSet.isOrderedSet`.
+- `conversions.md` — `toJS` deep conversion and round-tripping with native types.

package/skill/immutable-js/references/shallow-functional.md

@@ -0,0 +1,99 @@
+These are JS-friendly top-level helpers exported from `immutable`: `get`, `set`, `has`, `update`, `remove`. They act on a single key/index (no path traversal). Use when interop with plain JS objects/arrays is needed, or when writing functions that accept either Immutable or plain inputs. For Immutable inputs, the instance methods (`map.set`, `list.get`) are equivalent and return the same result.
+
+## Common signature shape
+
+- First arg is the collection — an Immutable `Collection`, a plain object, or an `Array`.
+- Second arg is the key (string/symbol for objects/Maps, number index for arrays/Lists).
+- `set` / `update` / `remove` return a NEW collection of the same kind; the input is never mutated.
+- `get` returns the value (or `notSetValue` / `undefined`); `has` returns a boolean.
+- Plain objects are treated as keyed; arrays are treated as indexed.
+- For Immutable inputs, structural sharing applies; for plain JS inputs, a shallow clone is produced.
+
+## get
+
+```ts
+get<K, V>(collection, key, notSetValue?): V | undefined
+```
+
+Returns the value at `key`, or `notSetValue` (or `undefined`) if absent. Functional alternative to `collection.get(key)` / `collection[key]`.
+
+```js
+get(['dog', 'frog', 'cat'], 2);          // => 'cat'
+get({ x: 123, y: 456 }, 'x');            // => 123
+get({ x: 123, y: 456 }, 'z', 'fallback'); // => 'fallback'
+get(List([1, 2, 3]), 0);                  // => 1
+```
+
+## has
+
+```ts
+has(collection: object, key: unknown): boolean
+```
+
+Returns `true` if `key` is defined in the collection. For plain objects this is equivalent to `hasOwnProperty`.
+
+```js
+has(['dog', 'frog', 'cat'], 2); // => true
+has(['dog', 'frog', 'cat'], 5); // => false
+has({ x: 123, y: 456 }, 'x');   // => true
+has({ x: 123, y: 456 }, 'z');   // => false
+```
+
+## set
+
+```ts
+set<C>(collection: C, key, value): C
+```
+
+Returns a copy of the collection with `key` set to `value`. For plain JS, returns a new shallow-cloned object/array; the original is not mutated.
+
+```js
+set(List(['dog', 'frog', 'cat']), 1, 'cow'); // => List ['dog', 'cow', 'cat']
+set({ x: 123, y: 456 }, 'x', 789);            // => { x: 789, y: 456 }
+```
+
+## update
+
+```ts
+update<C>(collection: C, key, updater): C
+update<C>(collection: C, key, notSetValue, updater): C
+```
+
+Returns a copy with `key` set to `updater(currentValue)`. If `notSetValue` is supplied and the key is absent, the updater receives `notSetValue` instead of `undefined`.
+
+```js
+update(List(['dog', 'frog', 'cat']), 1, v => v.toUpperCase());
+// => List ['dog', 'FROG', 'cat']
+
+update({ x: 123, y: 456 }, 'x', v => v * 6);
+// => { x: 738, y: 456 }
+```
+
+## remove
+
+```ts
+remove<C>(collection: C, key): C
+```
+
+Alias: `delete`. Returns a copy of the collection with `key` removed. For plain objects, returns a new shallow-cloned object without that key. For arrays and `List`, removes the element at that index and shifts following elements down by one.
+
+```js
+remove(List(['dog', 'frog', 'cat']), 1); // => List ['dog', 'cat']
+remove({ x: 123, y: 456 }, 'x');         // => { y: 456 }
+remove([10, 20, 30], 1);                  // => [10, 30]
+```
+
+## Gotchas
+
+- These are NOT path-based — for nested paths, use the `*In` variants (`getIn`, `setIn`, `updateIn`, `removeIn`, `hasIn`); see `deep-updates.md`.
+- On plain JS arrays and on `List`, `remove(arr, i)` shifts later elements down (like `Array.prototype.splice`); it does not produce a sparse/hole result.
+- For Immutable inputs, returns the same identity (`===`) when no change occurs; this short-circuit does not apply to plain JS inputs (which always shallow-clone on write).
+- For plain JS, the prototype chain is preserved by spreading; class instances are shallow-copied as plain objects of the same shape.
+- `update` with no `notSetValue` passes `undefined` to the updater for missing keys — guard against this in your updater.
+
+## See also
+
+- `deep-updates.md` — path-based variants (`getIn`, `setIn`, `updateIn`, `removeIn`, `hasIn`, `mergeIn`, `mergeDeepIn`).
+- `list.md` — indexed Immutable collection.
+- `map.md` — keyed Immutable collection.
+- `conversions.md` — moving between plain JS and Immutable.