mutts 1.0.8 → 1.0.10

package/docs/reactive/attend.md

@@ -0,0 +1,142 @@
+# Reactive Enumeration (`attend`)
+
+The `attend` utility reactively iterates over the entries of a collection, running a per-key effect that is automatically created when a key appears and disposed when it disappears.
+
+## Overview
+
+`attend` is the reactive equivalent of `forEach`. It:
+- Tracks the **keys** (or indices, or values) of a collection inside an outer effect.
+- **Creates** an inner effect for each key, via `ascend`.
+- **Disposes** the inner effect when the key is removed from the collection.
+- Allows the callback to return a **cleanup function** (like a regular effect closer).
+
+This is the foundational lifecycle primitive that `organized` is built on.
+
+## API
+
+```typescript
+// Raw enumeration callback
+function attend<Key>(
+    enumerate: () => Iterable<Key>,
+    callback: (key: Key) => EffectCloser | void
+): ScopedCallback
+
+// Collection shorthands
+function attend<T>(source: readonly T[], callback: (index: number) => EffectCloser | void): ScopedCallback
+function attend<K, V>(source: Map<K, V>, callback: (key: K) => EffectCloser | void): ScopedCallback
+function attend<T>(source: Set<T>, callback: (value: T) => EffectCloser | void): ScopedCallback
+function attend<S extends Record<PropertyKey, any>>(source: S, callback: (key: keyof S & string) => EffectCloser | void): ScopedCallback
+```
+
+### Parameters
+
+- **`source`** or **`enumerate`**: Either a collection (array, record, Map, Set) or a callback returning an `Iterable<Key>`. The enumeration runs inside the outer effect, so reactive reads (e.g. `source.length`, `Object.keys(source)`) are tracked automatically.
+- **`callback`**: Called per key inside an inner effect. May return a cleanup function that runs when the key is removed or before the inner effect re-executes.
+
+### Returns
+
+A `ScopedCallback` that tears down all inner effects and the outer effect.
+
+## Basic Usage
+
+### Record
+
+```typescript
+import { reactive, attend } from 'mutts'
+
+const config = reactive({ theme: 'dark', lang: 'en' })
+
+const stop = attend(config, (key) => {
+    console.log(`${key} = ${config[key]}`)
+    return () => console.log(`cleanup: ${key}`)
+})
+
+// Logs: "theme = dark", "lang = en"
+
+config.debug = true
+// Logs: "debug = true"
+
+delete config.lang
+// Logs: "cleanup: lang"
+
+config.theme = 'light'
+// Logs: "cleanup: theme" then "theme = light"
+// (inner effect re-runs: previous cleanup fires, then new execution)
+
+stop()
+// Disposes everything
+```
+
+### Array
+
+```typescript
+const items = reactive([10, 20, 30])
+
+attend(items, (i) => {
+    console.log(`[${i}] = ${items[i]}`)
+})
+
+items.push(40)
+// Logs: "[3] = 40"
+```
+
+### Map
+
+```typescript
+const registry = reactive(new Map([['a', 1]]))
+
+attend(registry, (key) => {
+    console.log(`${key} -> ${registry.get(key)}`)
+    return () => console.log(`removed: ${key}`)
+})
+
+registry.set('b', 2)  // Logs: "b -> 2"
+registry.delete('a')   // Logs: "removed: a"
+```
+
+### Set
+
+```typescript
+const tags = reactive(new Set(['alpha', 'beta']))
+
+attend(tags, (value) => {
+    console.log(`tag: ${value}`)
+    return () => console.log(`untagged: ${value}`)
+})
+
+tags.add('gamma')     // Logs: "tag: gamma"
+tags.delete('alpha')  // Logs: "untagged: alpha"
+```
+
+### Raw enumeration callback
+
+For custom iteration logic or non-standard collections:
+
+```typescript
+const source = reactive({ a: 1, b: 2 })
+
+attend(
+    () => Reflect.ownKeys(source),
+    (key) => {
+        console.log(key, source[key])
+    }
+)
+```
+
+## How it Works
+
+1. An **outer effect** calls `enumerate()` (or derives it from the collection type), collecting the current keys into a `Set`.
+2. For each **new key**, `ascend` creates an inner effect that runs the callback.
+3. For each **removed key**, the corresponding inner effect is stopped (which triggers its cleanup).
+4. The **inner effect** tracks its own reactive dependencies — so if a value changes for an existing key, only that key's effect re-runs.
+
+## Relationship to Other Primitives
+
+| Primitive | Uses `attend`? | Purpose |
+|---|---|---|
+| `attend` | — | Reactive lifecycle per key |
+| `organized` | ✅ | Reactive record mapping with access objects |
+| `project` | ❌ | Reactive collection mapping (manages a target + projection context) |
+| `scan` | ❌ | Reactive accumulation (sequential key dependency) |
+
+`project` and `scan` have additional concerns (target management, sequential dependencies) that go beyond `attend`'s independent-key lifecycle model.

package/docs/reactive/collections.md

@@ -347,26 +347,81 @@ The `Register` exposes additional methods and behaviors that standard arrays do
   - `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/reactive'
 
 // 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']
 
@@ -375,8 +430,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'
 })
 
@@ -389,7 +443,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
@@ -398,41 +452,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
 })
@@ -450,9 +488,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}`
 })
 
@@ -470,11 +507,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
@@ -493,7 +530,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

package/docs/reactive/core.md

@@ -7,19 +7,17 @@
   - [5-Minute Quick Start](#5-minute-quick-start)
 - [Core API](#core-api)
 - [Effect System](#effect-system)
+  - [Error Handling](./error-handling.md)
 - [Atomic Operations](./advanced.md#atomic-operations)
 - [Advanced Effects](./advanced.md#advanced-effects)
 - [Evolution Tracking](./advanced.md#evolution-tracking)
 - [Prototype Chains and Pure Objects](./advanced.md#prototype-chains-and-pure-objects)
 - [Recursive Touching](./advanced.md#recursive-touching)
-  - [Why Not Deep Watching?](./advanced.md#why-not-deep-watching)
-- [Collections](./advanced.md#collections)
-  - [Register](./advanced.md#register)
-- [Class Reactivity](./advanced.md#class-reactivity)
-- [Non-Reactive System](./advanced.md#non-reactive-system)
-- [Array Mapping](./advanced.md#array-mapping)
-- [Projection](./advanced.md#projection)
-- [Record Organization](./advanced.md#record-organization)
+- [Collections](./collections.md)
+  - [Register](./collections.md#register)
+- [Class Reactivity](#class-reactivity)
+- [Non-Reactive System](#non-reactive-system)
+- [Morphing](./advanced.md#morph)
 - [Memoization](./advanced.md#memoization)
 - [Debugging and Development](./advanced.md#debugging-and-development)
   - [Cycle Detection](./advanced.md#cycle-detection)
@@ -105,7 +103,7 @@ const result = memoized(user)
 **5. Map over arrays:**
 ```typescript
 const source = reactive([1, 2, 3])
-const doubled = project(source, ({ value }) => value * 2)
+const doubled = morph(source, ({ value }) => value * 2)
 // [2, 4, 6]
 
 source.push(4)  // doubled automatically becomes [2, 4, 6, 8]
@@ -202,7 +200,7 @@ reactiveObj.count = 5 // Triggers effect
 - Objects with prototypes: `reactive(Object.create(parent))`
 - Class instances: `reactive(new MyClass())`
 
-See [Prototype Chains and Pure Objects](#prototype-chains-and-pure-objects) for detailed information about prototype chain handling.
+See [Prototype Chains and Pure Objects](./advanced.md#prototype-chains-and-pure-objects) for detailed information about prototype chain handling.
 
 ### `effect()`
 
@@ -448,7 +446,7 @@ state.c = 15 // Does NOT trigger effect
 
 The `effect` function provides a special `access` parameter with `tracked` and `ascend` functions that restore the active effect context for dependency tracking in asynchronous operations. 
 
-In modern `mutts`, this is powered by the **Zone system**. When you use `configureAsyncZone()`, the active effect context is automatically preserved across `await` points and timers, making manual use of `tracked` optional for these cases.
+In modern `mutts`, this is powered by the **Zone system**. When zones are registered in `asyncZone`, the active effect context is automatically preserved across `await` points and timers, making manual use of `tracked` optional for these cases.
 
 #### The Problem with Async Effects
 
@@ -466,7 +464,7 @@ effect(() => {
     const another = state.name // ✅ Tracked (active effect is still set)
 })
 
-// Async effect WITHOUT configureAsyncZone() - context is lost after await
+// Async effect WITHOUT zone registration - context is lost after await
 effect(async () => {
     const value = state.count // ✅ Tracked
     
@@ -476,7 +474,7 @@ effect(async () => {
     const another = state.name // ❌ NOT tracked
 })
 
-// Async effect WITH configureAsyncZone() - context is preserved
+// Async effect WITH zone registration - context is preserved
 effect(async () => {
     const value = state.count // ✅ Tracked
     
@@ -497,7 +495,7 @@ effect(async ({ tracked }) => {
 
 #### Key Benefits of the Zone System
 
-1.  **Automatic Restoration**: With `configureAsyncZone()`, most native async APIs (Promises, timers) automatically preserve the reactive context.
+1.  **Automatic Restoration**: With zones registered in `asyncZone`, most native async APIs (Promises, timers) automatically preserve the reactive context.
 2.  **Manual Control**: `access.tracked()` allows you to manually "passport" the context into third-party libraries or unmanaged callbacks.
 
 ### Using `ascend` for Parent Effect Tracking
@@ -603,6 +601,94 @@ reactiveOptions.leave = (effect) => console.log('Leaving effect:', effect)
 reactiveOptions.chain = (caller, target) => console.log('Chaining:', caller, '->', target)
 ```
 
+### Effect Modifiers
+
+The `effect` function provides convenient shortcut modifiers for common options. These can be chained for more concise syntax:
+
+#### `.opaque`
+
+Creates an opaque effect that tracks object references rather than deep content. This is useful when you want effects to re-run only when the object identity changes, not when its properties change.
+
+```typescript
+import { effect, reactive } from 'mutts/reactive'
+
+const item = reactive({ id: 1, data: { value: 10 } })
+
+// Regular effect - triggers on any property change
+effect(() => {
+    console.log('Item data:', item.data.value) // Triggers on item.data.value changes
+})
+
+// Opaque effect - only triggers when item.data reference changes
+effect.opaque(() => {
+    console.log('Data object:', item.data) // Only triggers when item.data is replaced
+})
+
+item.data.value = 20       // Triggers regular effect, NOT opaque effect
+item.data = { value: 30 }  // Triggers BOTH effects
+```
+
+**Use cases for opaque effects:**
+- When you only care about object identity (e.g., cache keys, memoization)
+- When deep watching would be too expensive
+- When working with external data that shouldn't trigger deep reactivity
+
+#### `.named(name)`
+
+Creates a named effect for easier debugging and profiling. The name appears in DevTools and debug logs.
+
+```typescript
+import { effect, reactive } from 'mutts/reactive'
+
+const state = reactive({ count: 0 })
+
+// Create a named effect
+effect.named('counter-effect')(() => {
+    console.log('Count:', state.count)
+})
+
+// Named effects can also be combined with other options
+effect.named('data-loader').opaque(() => {
+    console.log('Loading data...')
+})
+```
+
+**Benefits of named effects:**
+- Easier identification in DevTools
+- Better stack traces during debugging
+- Helpful for performance profiling
+
+#### Combining Modifiers
+
+Modifiers can be chained in any order:
+
+```typescript
+// Named opaque effect
+effect.named('my-effect').opaque(() => {
+    // Effect code
+})
+
+// These are equivalent - order doesn't matter for the result
+effect.opaque.named('my-effect')(() => {
+    // Effect code
+})
+```
+
+Note: The modifiers return new effect functions with the options pre-applied, so they can be stored and reused:
+
+```typescript
+// Create a reusable named effect factory
+const createDataEffect = effect.named('data-layer')
+
+createDataEffect(() => {
+    console.log('Effect 1')
+})
+
+createDataEffect(() => {
+    console.log('Effect 2')
+})
+```
+
 
 ### `@reactive` Decorator