mutts 1.0.8 → 1.0.9

package/docs/flavored.md

@@ -0,0 +1,210 @@
+# Flavored Functions
+
+The `flavored` utility creates extensible functions with chainable property modifiers. It enables a fluent API where properties return specialized variants of the base function.
+
+## Overview
+
+Flavored functions allow you to:
+- Create property-based modifiers that transform how the function is called
+- Chain multiple modifiers together
+- Use either automatic option merging (`flavorOptions`) or custom argument transformation (`createFlavor`)
+- Return hand-made functions for complete control (the generic case)
+
+## Basic Usage
+
+### Creating a Flavored Function
+
+```typescript
+import { flavored, flavorOptions } from 'mutts'
+
+const greet = flavored(
+  (name: string, options?: { loud?: boolean }) => {
+    const greeting = `Hello, ${name}!`
+    return options?.loud ? greeting.toUpperCase() : greeting
+  },
+  {
+    get loud() {
+      return flavorOptions(this, { loud: true })
+    }
+  }
+)
+
+greet('World')          // "Hello, World!"
+greet.loud('World')     // "HELLO, WORLD!"
+```
+
+## API Reference
+
+### `flavored(fn, flavors)`
+
+Creates a flavored function with chainable property modifiers.
+
+**Parameters:**
+- `fn` - The base function to flavor
+- `flavors` - Object defining the flavor properties (getters or methods)
+
+**Returns:** A proxy of the function with the flavor properties attached.
+
+**Example:**
+```typescript
+const effect = flavored(baseEffect, {
+  get opaque() {
+    return flavorOptions(this, { opaque: true })
+  },
+  named(name: string) {
+    return flavorOptions(this, { name })
+  }
+})
+
+effect(fn)              // Basic usage
+effect.opaque(fn)       // With opaque option
+effect.named('myEffect')(fn)  // With name option
+effect.opaque.named('x')(fn)  // Chained
+```
+
+### `flavorOptions(fn, defaultOptions)`
+
+Creates a flavored variant that merges options with the last argument.
+
+**Use when:** The last argument is an options object that should be merged.
+
+**Parameters:**
+- `fn` - The base flavored function
+- `defaultOptions` - Options to merge with provided options
+
+**Example:**
+```typescript
+const loudGreet = flavorOptions(greet, { loud: true })
+loudGreet('World')                    // Uses { loud: true }
+loudGreet('World', { prefix: 'Hi' })  // Merges both options
+```
+
+### `createFlavor(fn, transform)`
+
+Creates a flavored variant with custom argument transformation.
+
+**Use when:** You need to transform arguments before calling the base function.
+
+**Parameters:**
+- `fn` - The base flavored function
+- `transform` - Function that receives and returns the arguments tuple
+
+**Example:**
+```typescript
+const doubleArgs = createFlavor(add, (a: number, b: number): [number, number] => {
+  return [a * 2, b * 2]
+})
+doubleArgs(3, 4)  // Returns 14 (6 + 8)
+```
+
+## The Generic Case: Hand-Made Functions
+
+When `flavorOptions` or `createFlavor` don't fit your needs, you can return a **hand-made function** directly. This gives you complete control over the behavior.
+
+### Basic Hand-Made Function
+
+```typescript
+const fetch = flavored(fetchData, {
+  // Returns a completely custom function
+  withTimeout(timeout: number) {
+    return (url: string, options?: { retries?: number }) => {
+      return fetchData(url, { ...options, timeout })
+    }
+  }
+})
+
+// Usage
+const fetchWith500ms = fetch.withTimeout(500)
+fetchWith500ms('api.com')  // Uses timeout: 500
+```
+
+### Re-Flavoring Hand-Made Functions
+
+Hand-made functions can be re-flavored to enable further chaining:
+
+```typescript
+const process = flavored(baseProcess, {
+  presetMultiplier(multiplier: number) {
+    // Create the preset function
+    const presetFn = (value: number, options?: { offset?: number }) => {
+      return baseProcess(value, { ...options, multiplier })
+    }
+    // Re-flavor it to enable chaining
+    return flavored(presetFn, {
+      get withOffset() {
+        return flavorOptions(this, { offset: 10 })
+      }
+    })
+  }
+})
+
+// Usage
+const times3 = process.presetMultiplier(3)
+times3(5)              // 15 (5 * 3)
+times3.withOffset(5)   // 20 (5 * 3 + 5)
+```
+
+### When to Use Each Approach
+
+| Approach | Use When |
+|----------|----------|
+| `flavorOptions` | You have an options object as the last argument |
+| `createFlavor` | You need to transform arguments structurally |
+| **Hand-made function** | You need complete control, different signature, or side effects |
+
+## Advanced Patterns
+
+### Chaining Multiple Modifiers
+
+```typescript
+const createUser = flavored(createUserBase, {
+  get admin() {
+    return flavorOptions(this, { admin: true })
+  },
+  get verified() {
+    return flavorOptions(this, { verified: true })
+  }
+})
+
+createUser.admin.verified('Alice')  // Both options applied
+```
+
+### Combining Approaches
+
+```typescript
+const calculator = flavored(
+  (a: number, b: number, opts?: { multiply?: boolean }) => {
+    return opts?.multiply ? a * b : a + b
+  },
+  {
+    get multiply() {
+      return flavorOptions(this, { multiply: true })
+    },
+    double() {
+      return createFlavor(this, (a, b, opts?): [number, number, typeof opts] => {
+        return [a * 2, b * 2, opts]
+      })
+    }
+  }
+)
+
+calculator.multiply(3, 4)     // 12
+calculator.double()(3, 4)     // 14 (6 + 8)
+```
+
+## TypeScript Considerations
+
+Flavored functions use proxies and require type assertions for complex chaining scenarios:
+
+```typescript
+const effectWithModifiers = flavored(effect, {
+  get opaque(): EffectWithModifiers {
+    return flavorOptions(this, { opaque: true }) as EffectWithModifiers
+  },
+  named(name: string): EffectWithModifiers {
+    return flavorOptions(this, { name }) as EffectWithModifiers
+  }
+})
+```
+
+The `as EffectWithModifiers` cast enables proper type inference for chained modifiers.

package/docs/reactive/advanced.md

@@ -1169,8 +1169,7 @@ For a full guide on debugging, including cycle detection and memoization discrep
 
 ### Quick Summary
 
-- **Cycle Detection**: Automatically catch circular dependencies via `reactiveOptions.cycleHandling`. Note: Instant mathematical detection requires choosing a mode other than `'none'`.
-- **Flat Mode**: The default `reactiveOptions.cycleHandling = 'none'` provides maximum performance in high-frequency update scenarios by disabling graph maintenance.
+- **Cycle Detection**: Automatically catch circular dependencies via `reactiveOptions.cycleHandling`. Note: Instant mathematical detection requires choosing `'development'` or `'debug'` mode.
+- **Production Mode**: The default `reactiveOptions.cycleHandling` is set to `'production'`, providing maximum performance in high-frequency update scenarios by disabling graph maintenance.
 - **Memoization Discrepancy**: Detect "missing dependencies" by running computations twice during development using `reactiveOptions.onMemoizationDiscrepancy`.
 - **Global Hooks**: Use `reactiveOptions.touched`, `enter`, and `leave` to observe system activity.
-

package/docs/reactive/attend.md

@@ -0,0 +1,143 @@
+# 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 `describe` and `organized` are 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 |
+| `describe` | ✅ | Reactive `Object.defineProperty` 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,6 +347,61 @@ 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.

package/docs/reactive/core.md

@@ -7,6 +7,7 @@
   - [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)
@@ -19,6 +20,7 @@
 - [Non-Reactive System](./advanced.md#non-reactive-system)
 - [Array Mapping](./advanced.md#array-mapping)
 - [Projection](./advanced.md#projection)
+- [Reactive Property Description](./describe.md)
 - [Record Organization](./advanced.md#record-organization)
 - [Memoization](./advanced.md#memoization)
 - [Debugging and Development](./advanced.md#debugging-and-development)
@@ -111,6 +113,19 @@ const doubled = project(source, ({ value }) => value * 2)
 source.push(4)  // doubled automatically becomes [2, 4, 6, 8]
 ```
 
+**6. Define properties reactively:**
+```typescript
+const target = {}
+const descriptors = reactive({
+  foo: { value: 1, enumerable: true }
+})
+describe(descriptors, target)
+// target.foo is 1
+
+descriptors.bar = { value: 2, enumerable: true }
+// target.bar is 2 automatically
+```
+
 **Ready to go!** Continue reading for advanced features.
 
 ---
@@ -204,6 +219,19 @@ reactiveObj.count = 5 // Triggers effect
 
 See [Prototype Chains and Pure Objects](#prototype-chains-and-pure-objects) for detailed information about prototype chain handling.
 
+### `describe()`
+
+Reactively defines properties on a target object based on a descriptors record.
+
+```typescript
+function describe<T extends object>(
+    descriptors: Record<PropertyKey, PropertyDescriptor>,
+    target: T = Object.create(null) as T
+): T
+```
+
+See the [Reactive Property Description](./describe.md) guide for details.
+
 ### `effect()`
 
 Creates a reactive effect that automatically re-runs when dependencies change.
@@ -448,7 +476,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 +494,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 +504,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 +525,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 +631,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
 

package/docs/reactive/debugging.md

@@ -25,7 +25,7 @@ These hooks are called during the execution of effects and computed values.
 
 - **`beginChain(targets: Function[]) / endChain()`**: Called when a batch of effects starts and ends its execution.
 - **`maxEffectChain`**: (Default: `100`) Limits the depth of synchronous effect triggering to prevent stack overflows.
-- **`maxTriggerPerBatch`**: (Default: `10`) Limits how many times a single effect can be triggered within the same batch. Useful for detecting aggressive re-computation or infinite cycles in `cycleHandling: 'none'` mode.
+- **`maxTriggerPerBatch`**: (Default: `10`) Limits how many times a single effect can be triggered within the same batch. Useful for detecting aggressive re-computation or infinite cycles in `cycleHandling: 'production'` mode.
 
 ## Cycle Detection
 
@@ -35,18 +35,16 @@ These hooks are called during the execution of effects and computed values.
 
 You can control how cycles are handled via `reactiveOptions.cycleHandling`:
 
-- **`'none'`** (Default): High-performance FIFO mode. Disables the dependency graph and topological sorting.
-- **`'throw'`**: Throws a `ReactiveError` with a detailed path.
-- **`'warn'`**: Logs a warning but breaks the cycle to allow the application to continue.
-- **`'break'`**: Silently breaks the cycle.
-- **`'strict'`**: Performs a graph check *before* execution to prevent cycles from even starting. This has the highest overhead.
+- **`'production'`**: High-performance FIFO mode. Disables the dependency graph and topological sorting. Uses heuristic detection via `maxEffectChain`.
+- **`'development'`** (Default): Maintains direct dependency graph for early cycle detection during edge creation. Throws immediately with basic path information.
+- **`'debug'`**: Full diagnostic mode with transitive closures and topological sorting. Provides detailed cycle path reporting.
 
 ### Topological vs. Flat Mode Detection
 
 | Mode | `cycleHandling` | Detection Method | Error Code |
 | :--- | :--- | :--- | :--- |
-| **Topological** | `'throw'` (or other) | **Mathematical**: Analyzes the dependency graph. | `CYCLE_DETECTED` |
-| **Flat Mode** | `'none'` (Default) | **Heuristic**: Counts executions per batch. | `MAX_REACTION_EXCEEDED` |
+| **Debug** | `'debug'` or `'development'` | **Mathematical**: Analyzes the dependency graph. | `CYCLE_DETECTED` |
+| **Production** | `'production'` (Default) | **Heuristic**: Counts executions per batch. | `MAX_REACTION_EXCEEDED` |
 
 In **Topological mode**, the system maintains a transitive closure of all effects, allowing it to know instantly if an effect is its own cause. In **Flat mode**, the system is "blind" to the graph and relies on the execution threshold (`maxTriggerPerBatch`) to interrupt infinite loops.
 
@@ -157,12 +155,12 @@ Since these are runtime options, you can toggle them based on your environment:
 
 ```typescript
 if (process.env.NODE_ENV === 'development') {
-    reactiveOptions.cycleHandling = 'throw';
+    reactiveOptions.cycleHandling = 'debug';
     reactiveOptions.onMemoizationDiscrepancy = myHandler;
     enableIntrospection();
 } else {
     // Ensure they are off in production for performance
     reactiveOptions.onMemoizationDiscrepancy = undefined;
-    reactiveOptions.cycleHandling = 'break';
+    reactiveOptions.cycleHandling = 'production';
 }
 ```