mutts 1.0.9 → 1.0.11

package/docs/reactive/collections.md

@@ -259,169 +259,22 @@ effect(() => {
 })
 ```
 
-### `Register`
-
-`Register` is an ordered, array-like collection that keeps a stable mapping between keys and values. It is useful when you need array semantics (indexable access, ordering, iteration) but also require identity preservation by key—ideal for UI lists keyed by IDs or when you want to memoise entries across reorders.
-
-```typescript
-import { Register } from 'mutts/reactive'
-
-// Create a register where the key comes from the `id` field
-const list = new Register(({id}: { id: number }) => id, [
-    { id: 1, label: 'Alpha' },
-    { id: 2, label: 'Bravo' },
-])
-
-effect(() => {
-    console.log('Length:', list.length)
-    console.log('First label:', list[0]?.label)
-})
-
-// Push uses the key function to keep identities stable
-list.push({ id: 3, label: 'Charlie' })
-
-// Replacing with the same key updates watchers without creating a new identity
-list[0] = { id: 1, label: 'Alpha (updated)' }
-
-// Access by key
-const second = list.get(2) // { id: 2, label: 'Bravo' }
-
-// Duplicate keys share value identity
-list.push({ id: 2, label: 'Bravo (new data)' })
-console.log(list[1] === list[2]) // true
-```
-
-**Highlights:**
-
-- Fully indexable (`list[0]`, `list.at(-1)`, `list.length`, iteration, etc.) thanks to the shared `Indexable` infrastructure.
-- Complete array surface forwarding (`map`, `filter`, `reduce`, `concat`, `reverse`, `sort`, `fill`, `copyWithin`, and more) with reactivity preserved.
-- Stable key/value map under the hood allows quick lookups via `get()`, `hasKey()`, and `indexOfKey()`.
-- When the same key appears multiple times, all slots reference the same underlying value instance, making deduplication and memoisation straightforward.
-- Reordering operations emit index-level touches so list reactivity remains predictable in rendered UIs.
-
-### Register-specific API (beyond Array)
-
-The `Register` exposes additional methods and behaviors that standard arrays do not have:
-
-- `get(key)` / `set(key, value)`
-  - `get(key: K): T | undefined` returns the latest value for a key.
-  - `set(key: K, value: T): void` updates the value for an existing key (no-op if key absent).
-  - Example:
-  ```typescript
-  list.set(2, { id: 2, label: 'Bravo (updated)' })
-  const v = list.get(2)
-  ```
-
-- `hasKey(key)` / `indexOfKey(key)`
-  - `hasKey(key: K): boolean` whether the key is present in any slot.
-  - `indexOfKey(key: K): number` first index at which the key appears, or `-1`.
-
-- `remove(key)` / `removeAt(index)`
-  - `remove(key: K): void` removes all occurrences of `key` from the register.
-  - `removeAt(index: number): T | undefined` removes a single slot by index and returns its value.
-
-- `keep(predicate)`
-  - `keep(predicate: (value: T) => boolean): void` keeps only items for which the predicate returns `true`; items for which it returns `false` are removed. The predicate is evaluated once per distinct key; duplicate keys follow the same decision.
-
-- `update(...values)`
-  - `update(...values: T[]): void` updates existing entries by their key; ignores values whose key is not yet present.
-
-- `upsert(insert, ...values)`
-  - `upsert(insert: (value: T) => void, ...values: T[]): void` updates by key when present, otherwise calls `insert(value)` so you can decide how to insert (e.g. `push`, `unshift`, or `splice`).
-  - Example:
-  ```typescript
-  list.upsert(v => list.push(v), { id: 4, label: 'Delta' }, { id: 2, label: 'Bravo (again)' })
-  ```
-
-- `entries()`
-  - Iterates `[number, value]` pairs in index order: `IterableIterator<[number, T | undefined]>`.
-
-- `keys` / `values`
-  - `keys: ArrayIterator<number>` provides the index iterator (mirrors `Array#keys()`).
-  - `values: IterableIterator<T>` provides an iterator of values (same as default iteration).
-
-- `clear()`
-  - Removes all entries and disposes internal key-tracking effects.
-
-- `toArray()` / `toString()`
-  - `toArray(): T[]` materializes the current values into a plain array.
-  - `toString(): string` returns a concise description like `[Register length=3]`.
-
-### Register CRUD Events
-
-`Register` emits lifecycle events for add, delete, update, and rekey operations. This enables side effects like logging, syncing with external systems, or triggering derived updates.
-
-```typescript
-const list = register(({id}: { id: number }) => id)
-
-// Listen to individual events
-list.on('add', (item, key, index) => {
-    console.log(`Added ${key} at index ${index}:`, item)
-})
-
-list.on('delete', (item, key, index) => {
-    console.log(`Removed ${key} from index ${index}:`, item)
-})
-
-list.on('update', (oldItem, newItem, key, index) => {
-    console.log(`Updated ${key} at index ${index}`)
-})
-
-list.on('rekey', (item, oldKey, newKey, index) => {
-    console.log(`Key changed from ${oldKey} to ${newKey}`)
-})
-
-// Bulk event registration
-list.on({
-    add: (item) => console.log('Added:', item),
-    delete: (item) => console.log('Deleted:', item),
-})
-
-// Global hook - receive all events
-const unhook = list.hook((event, ...args) => {
-    console.log(`Event: ${String(event)}`, args)
-})
-
-// Unsubscribe
-const unsubscribe = list.on('add', handler)
-unsubscribe()
-```
-
-**Event Types:**
-
-| Event | Arguments | Description |
-|-------|-----------|-------------|
-| `add` | `(item, key, index)` | New item added to register |
-| `delete` | `(item, key, index)` | Item removed from register |
-| `update` | `(oldItem, newItem, key, index)` | Item value updated (same key) |
-| `rekey` | `(item, oldKey, newKey, index)` | Item's key changed |
-
-**Use Cases:**
-- Audit logging
-- Syncing with databases
-- Triggering notifications
-- Cascading updates to dependent systems
-
-Notes:
-- Direct length modification via `list.length = n` is not supported; use `splice` instead.
-- Assigning to an index (`list[i] = value`) uses the key function to bind that slot to `value`’s key.
-
 ## Class Reactivity
 
-## Projection
+## Morphing
 
-### `project()`
+### `morph()`
 
-`project()` provides a unified API for transforming reactive collections (arrays, records, and maps) into new reactive collections. Each source entry gets its own reactive effect that recomputes only when that specific entry changes, enabling granular updates perfect for rendering pipelines.
+`morph()` provides a unified API for transforming reactive collections (arrays, records, and maps) into new reactive collections. Each source entry gets its own reactive effect that recomputes only when that specific entry changes, enabling granular updates perfect for rendering pipelines.
 
 #### Basic Usage
 
 ```typescript
-import { cleanup, project, reactive } from 'mutts/reactive'
+import { cleanup, morph, reactive } from 'mutts'
 
 // Arrays
 const users = reactive([{ name: 'John', age: 30 }, { name: 'Jane', age: 25 }])
-const names = project.array(users, ({ get }) => get()?.name.toUpperCase() ?? '')
+const names = morph(users, (user) => user.name.toUpperCase())
 
 console.log(names) // ['JOHN', 'JANE']
 
@@ -430,8 +283,7 @@ console.log(names[0]) // 'JOHNNY' - only index 0 recomputed
 
 // Records
 const scores = reactive({ math: 90, science: 85 })
-const grades = project.record(scores, ({ get }) => {
-  const score = get()
+const grades = morph(scores, (score) => {
   return score >= 90 ? 'A' : score >= 80 ? 'B' : 'C'
 })
 
@@ -444,7 +296,7 @@ const inventory = reactive(new Map([
   ['apples', { count: 10 }],
   ['oranges', { count: 5 }]
 ]))
-const totals = project.map(inventory, ({ get }) => get()?.count ?? 0)
+const totals = morph(inventory, (item) => item.count)
 
 console.log(totals.get('apples')) // 10
 inventory.get('apples')!.count = 15
@@ -453,41 +305,25 @@ console.log(totals.get('apples')) // 15 - only 'apples' key recomputed
 
 #### Automatic Type Selection
 
-You can use `project()` directly and it will automatically select the appropriate helper based on the source type:
+The `morph()` function automatically selects the appropriate helper based on the source type:
 
 ```typescript
-// Automatically uses project.array
-const doubled = project([1, 2, 3], ({ get }) => get() * 2)
+// Arrays
+const doubled = morph([1, 2, 3], (x) => x * 2)
 
-// Automatically uses project.record
-const upper = project({ a: 'hello', b: 'world' }, ({ get }) => get()?.toUpperCase() ?? '')
+// Records
+const upper = morph({ a: 'hello', b: 'world' }, (s) => s.toUpperCase())
 
-// Automatically uses project.map
-const counts = project(new Map([['x', 1], ['y', 2]]), ({ get }) => get() * 2)
+// Maps
+const counts = morph(new Map([['x', 1], ['y', 2]]), (v) => v * 2)
 ```
 
-#### Access Object
-
-The callback receives a `ProjectAccess` object with:
+#### Callback Signature
 
-- **`get()`**: Function that returns the current source value for this key/index
-- **`set(value)`**: Function to update the source value (if the source is mutable)
-- **`key`**: The current key or index
-- **`source`**: Reference to the original source collection
-- **`old`**: Previously computed result for this entry (undefined on first run)
-- **`value`**: Computed property that mirrors `get()` (for convenience)
+The callback function receives the current value of the entry being processed:
 
 ```typescript
-const transformed = project.array(items, (access) => {
-  // Access the source value
-  const item = access.get()
-  
-  // Access the key/index
-  console.log(`Processing index ${access.key}`)
-
-  // Leverage previous result
-  console.log(`Previous result: ${access.old}`)
-  
+const transformed = morph(items, (item) => {
   // Transform and return
   return item.value * 2
 })
@@ -505,9 +341,8 @@ const users = reactive([
 ])
 
 let computeCount = 0
-const summaries = project.array(users, ({ get }) => {
+const summaries = morph(users, (user) => {
   computeCount++
-  const user = get()
   return `${user.name}: ${user.score}`
 })
 
@@ -525,11 +360,11 @@ console.log(computeCount) // 5 (only new index 3 computed)
 
 #### Key Addition and Removal
 
-`project()` automatically handles keys being added or removed from the source:
+`morph()` automatically handles keys being added or removed from the source:
 
 ```typescript
 const source = reactive({ a: 1, b: 2 })
-const doubled = project.record(source, ({ get }) => get() * 2)
+const doubled = morph(source, (val) => val * 2)
 
 console.log(doubled.a) // 2
 console.log(doubled.b) // 4
@@ -548,7 +383,7 @@ console.log('a' in doubled) // false (automatically removed)
 The returned object includes a `cleanup` symbol that stops all reactive effects:
 
 ```typescript
-const result = project.array(items, ({ get }) => get() * 2)
+const result = morph(items, (item) => item * 2)
 
 // Later, when done
 result[cleanup]() // Stops all effects and cleans up
@@ -566,7 +401,7 @@ result[cleanup]() // Stops all effects and cleans up
 ### `organized()`
 
 ```typescript
-import { cleanup, organized, reactive } from 'mutts/reactive'
+import { cleanup, organized, reactive } from 'mutts'
 
 const source = reactive<Record<string, number>>({ apples: 1, oranges: 2 })