mutts 1.0.9 → 1.0.11

package/docs/reactive/advanced.md

@@ -5,7 +5,7 @@
 The `atomic` function wraps a function to batch all reactive effects triggered within it, ensuring effects run only once after the function completes. It can be used both as a function wrapper and as a decorator.
 
 ```typescript
-import { atomic, reactive, effect } from 'mutts/reactive'
+import { atomic, reactive, effect } from 'mutts'
 
 const state = reactive({ a: 0, b: 0 })
 
@@ -43,14 +43,51 @@ service.updateMultiple(5)  // Effect runs only once with final values
 
 The wrapped function preserves its signature (parameters and return value), and all effects triggered by reactive changes inside it are automatically batched.
 
+### `atom()` - Immediate Atomic Execution
+
+While `atomic()` **wraps** a function for later calls, `atom()` **runs** a function immediately and atomically. It always executes right away, even inside a nested batch.
+
+```typescript
+import { atom, reactive, effect } from 'mutts'
+
+const state = reactive({ a: 0, b: 0 })
+
+effect(() => {
+  console.log('Values:', state.a, state.b)
+})
+
+// Execute multiple mutations atomically — effect fires only once
+atom(() => {
+  state.a = 10
+  state.b = 20
+})
+```
+
+**`atom` vs `atomic`:**
+
+| | `atom(fn)` | `atomic(fn)` |
+|---|---|---|
+| **When it runs** | Immediately | Returns a wrapped function for later calls |
+| **Arguments** | `() => T` | `(...args) => T` (preserves signature) |
+| **Use case** | One-shot batch of mutations | Reusable batched function / decorator |
+
+```typescript
+// atom — runs now
+atom(() => { state.a = 1; state.b = 2 })
+
+// atomic — creates wrapper for later
+const update = atomic((a, b) => { state.a = a; state.b = b })
+update(1, 2)  // runs when called
+```
+
 ### `addBatchCleanup()` / `defer()` - Deferring Work to Avoid Cycles
 
 When an effect needs to perform an action that would modify state the effect depends on, this can create a reactive cycle. The `addBatchCleanup` function (also exported as `defer` for semantic clarity) allows you to defer such work until after the current batch of effects completes.
 
 ```typescript
-import { addBatchCleanup, effect, reactive } from 'mutts/reactive'
+import { addBatchCleanup, effect, reactive } from 'mutts'
 // or use the semantic alias:
-// import { defer } from 'mutts/reactive'
+// import { defer } from 'mutts'
 
 const state = reactive({ 
   items: [],
@@ -261,7 +298,7 @@ effect(() => {
 Creates a bidirectional binding between a reactive value and a non-reactive external value (like DOM elements), automatically preventing infinite loops.
 
 ```typescript
-import { biDi, reactive } from 'mutts/reactive'
+import { biDi, reactive } from 'mutts'
 
 const model = reactive({ value: '' })
 
@@ -469,6 +506,31 @@ user.age = 31      // Triggers the callback
 user.email = 'jane@example.com' // Triggers the callback
 ```
 
+#### Flavored Watch
+
+The `watch` function is **flavored**, meaning it provides chainable properties for common options like `immediate` and `deep`:
+
+```typescript
+const state = reactive({ count: 0, nested: { a: 1 } })
+
+// Watch with immediate execution
+watch.immediate(() => state.count, (v) => console.log(v))
+// Prints: 0 immediately, then 1, 2...
+
+// Deep watch
+watch.deep(() => state.nested, (v) => console.log('Nested changed'))
+
+// Combined flavors
+watch.immediate.deep(() => state.nested, (v) => {
+    console.log('Immediate nested:', v)
+})
+```
+
+These flavors are a shorthand for passing options:
+- `watch.immediate(...)` is equivalent to `watch(..., { immediate: true })`
+- `watch.deep(...)` is equivalent to `watch(..., { deep: true })`
+- `watch.immediate.deep(...)` is equivalent to `watch(..., { immediate: true, deep: true })`
+
 #### Use Cases
 
 **Object-level watching** is particularly useful for:
@@ -995,7 +1057,8 @@ state.user = fetchUser()  // Only notifies if actual values changed
 
 // Or explicitly track what you need
 effect(() => {
-  console.log(state.user.profile.name)  // Only tracks this specific path
+  // Only tracks this specific path: Even if the `user` object changes, this effect will run only if the `profile.name` property has a different value
+  console.log(state.user.profile.name)
 })
 ```
 
@@ -1064,6 +1127,224 @@ effect(() => {
 
 **Bottom line:** Recursive touching gives you the granular control you need without deep watching's overhead, making it ideal for modern reactive applications.
 
+## Choosing the Right Reactive Primitive
+
+Mutts provides several ways to derive values from reactive state. They differ in **when** they recompute (eager vs lazy), **what** they return (raw value vs reactive proxy), and **how** downstream consumers track changes.
+
+### Comparison Table
+
+| Primitive | Evaluation | Output | Trackable | Identity stable | Cleanup | Best for |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| `effect(() => ...)` | Eager | Side-effect (void) | N/A | N/A | Auto (parent/GC) + Returned cleanup | Side effects, DOM updates |
+| `memoize(() => expr)` | **Lazy** | Raw value | Yes (return) | No (new value each call) | Auto (WeakMap GC) | Cached scalars, computed getters |
+| `memoize(fn)(args)` | **Lazy** | Raw value | Yes (return) | No | Auto (WeakMap GC) | Parameterized caching |
+| `lift(() => [...])` | Eager | Reactive array proxy | Yes (per-index) | **Yes** | `result[cleanup]()` | Derived collections (filter, map) |
+| `lift(() => ({...}))` | Eager | Reactive object proxy | Yes (per-prop) | **Yes** | `result[cleanup]()` | Derived objects, computed shapes |
+| `morph(source, fn)` | **Lazy** | Reactive proxy | Yes (per-key) | **Yes** | `cleanedBy` | Lazy per-element map with identity tracking |
+| `morph.pure(source, fn)` | **Lazy** | Reactive proxy | Yes (per-key) | **Yes** | `cleanedBy` | Same, but skips per-item dependency tracking |
+| `when(() => cond)` | Eager | Promise\<T\> | N/A | N/A | Auto (on resolve/timeout) | Awaiting a reactive condition |
+| `watch(source, cb)` | Eager | Callback (old/new) | N/A | N/A | Auto (parent/GC) + Returned cleanup | Observing specific changes |
+
+### Key distinctions
+
+- **Lazy vs Eager**: `memoize` only recomputes when the result is read. Everything else recomputes immediately when dependencies change — even if nobody is consuming the output.
+- **Trackable**: Can downstream effects depend on the result? `memoize`'s return value is trackable because calling it runs inside an effect context. `lift`/`morph` return reactive proxies where each property/index is independently trackable.
+- **Identity stable**: `lift` and `morph` return the **same proxy** across recomputations — only changed slots are updated. This is critical for downstream transformations or DOM reconciliation that relies on reference identity.
+
+### Common patterns
+
+**Lazy computed scalar** (like Vue/Solid `computed`):
+```typescript
+const total = memoize(() => state.price * state.quantity)
+effect(() => console.log(total())) // recomputes only when read
+```
+
+**Eager computed object** (trackable reactive proxy):
+```typescript
+const profile = lift(() => ({
+  displayName: user.name.toUpperCase(),
+  isAdult: user.age >= 18,
+}))
+effect(() => console.log(profile.displayName)) // tracks .displayName only
+```
+
+**Derived filtered collection**:
+```typescript
+const active = lift(() => items.filter(x => x.active))
+// active is a reactive array — project() or effects on active[i] work fine
+```
+
+**Per-element transform**:
+```typescript
+const doubled = morph(numbers, ({ value }) => value * 2)
+// Each index has its own effect — changing numbers[3] only recomputes doubled[3]
+```
+
+### `lift` vs `morph` — choosing the right primitive
+
+Both `lift` and `morph` produce a stable reactive object from reactive inputs, but they differ fundamentally in **effect topology**:
+
+| | `lift` | `morph` |
+|---|---|---|
+| **Effects** | 1 (single callback) | N+1 (1 outer + 1 per non-pure key) |
+| **Input** | Callback returning a plain object/array | Reactive source (array/record/Map) |
+| **Granularity** | Re-runs entire callback, diffs result | Per-key effect, only changed keys re-run |
+| **Key lifecycle** | Automatic (diff adds/removes keys) | Automatic (arrayDiff handles updates) |
+| **Execution** | Eager (recomputes immediately) | **Lazy** (recomputes on access) |
+| **Best for** | Computed shapes, small derived objects | Large collections with independent per-item logic |
+
+**Rule of thumb**: if the source has **stable keys** and the mapping is **cheap**, prefer `lift` — one effect is far cheaper than N+1. Reserve `morph` for cases where per-key lifecycle matters (e.g. each key spawns side-effects, or the collection is large and only individual items change).
+
+```typescript
+// lift: 1 effect, diffs ~5 properties — ideal for derived shapes
+const profile = lift(() => ({
+  displayName: user.name.toUpperCase(),
+  isAdult: user.age >= 18,
+  label: `${user.name} (${user.role})`,
+}))
+
+// morph: 1000 items, only item[42] changes — only item[42]'s effect re-runs
+const results = morph(numbers, (val) => val * 2)
+```
+
+**Performance note**: each `morph` key creates a full reactive effect with its own dependency tracking. For a page with many small mappings (e.g. HTML element props), this compounds quickly. Converting small `morph` calls to `lift` can dramatically reduce total effect count.
+
+### When deep touching makes `lift` unnecessary
+
+If you're simply **replacing** a reactive property with a new value of the same shape, deep touching already diffs element-by-element:
+
+```typescript
+state.items = fetchedItems // deep touch diffs old vs new per-index — no lift needed
+```
+
+`lift` is for **derived** data where there's no single property to assign to — the output is computed from scratch each time.
+
+## Morph
+
+### `morph(source, fn)`
+
+`morph` creates a **lazy, identity-stable** reactive array by mapping each element of a source array through a callback. Unlike `lift` (which re-runs the entire callback and diffs the result), `morph` only computes an element when it is accessed, and tracks the source array via `arrayDiff` to efficiently handle insertions, removals, and moves.
+
+**Signature**
+
+```typescript
+import { morph } from 'mutts'
+
+function morph<I, O>(
+  source: readonly I[] | (() => readonly I[]),
+  fn: (arg: I) => O,
+  options?: { pure?: boolean | ((i: I) => boolean) }
+): O[]
+```
+
+**Parameters**
+
+- `source`: a reactive array or a function returning one. Array mutations are tracked via `arrayDiff`.
+- `fn`: mapping callback. In the default (non-pure) mode, each element's computation runs inside its own effect, so reactive reads inside `fn` are tracked and will invalidate that element's cache when they change.
+- `options.pure`: controls per-item effect creation. `true` skips effects for all items (same as `morph.pure`). A **predicate function** `(i: I) => boolean` decides per-item: return `true` to skip the effect (pure), `false` to create one (reactive). The predicate receives the input item and is evaluated once per cache slot on first access.
+
+**Behaviour**
+
+- **Lazy**: elements are only computed when accessed (e.g. `result[0]`). Unaccessed indices remain `undefined` in the cache.
+- **Identity stable**: the returned reactive array proxy is the same object across source mutations. Only affected indices are invalidated.
+- **Per-item effects** (default): each accessed element gets its own effect. If `fn` reads reactive values beyond its argument, changes to those values invalidate and recompute only the affected elements.
+- **Cleanup**: the returned array is `cleanedBy` the internal morph effect. When the parent effect is disposed, the morph effect and all per-item effects are cleaned up.
+
+**Basic usage**
+
+```typescript
+import { morph, reactive, effect } from 'mutts'
+
+const items = reactive(['alice', 'bob', 'charlie'])
+const upper = morph(items, name => name.toUpperCase())
+
+effect(() => {
+  console.log(upper[0]) // "ALICE" — only element 0 is computed
+})
+
+items.push('dave')
+console.log(upper[3]) // "DAVE"
+
+items.splice(1, 1) // Remove 'bob' — indices shift, cache invalidated for affected positions
+```
+
+**With reactive callback dependencies**
+
+```typescript
+const source = reactive([1, 2, 3])
+const multiplier = reactive({ value: 2 })
+
+const scaled = morph(source, x => x * multiplier.value)
+
+console.log(scaled[0]) // 2
+multiplier.value = 10
+console.log(scaled[0]) // 10 — per-item effect re-ran
+```
+
+### `morph.pure`
+
+A flavored variant that skips per-item effects. Use when the callback is a **pure function** of its argument with no external reactive dependencies.
+
+```typescript
+const doubled = morph.pure(source, x => x * 2)
+```
+
+**Differences from default `morph`:**
+
+| | `morph` | `morph.pure` |
+|---|---|---|
+| **Per-item effects** | Yes — tracks `fn`'s reactive reads | No — `fn` runs once, result is cached |
+| **Callback dependency invalidation** | Automatic | None — stale if `fn` reads reactive values |
+| **Non-reactive source optimization** | Returns reactive proxy | Returns plain `source.map(fn)` |
+| **Best for** | Callbacks that read reactive state | Pure transforms (`x => x * 2`, `e => e.render()`) |
+
+### `pure` predicate — selective per-item mode
+
+When `pure` is a function, each item is individually classified as pure or reactive on first access:
+
+```typescript
+const result = morph(source, x => x * factor.value, {
+  pure: (x: number) => x > 2
+})
+```
+
+Items where the predicate returns `true` are computed once (no effect, no dependency tracking). Items where it returns `false` get a per-item effect that reacts to external dependency changes.
+
+```typescript
+const source = reactive(['static', 'dynamic', 'static'])
+const suffix = reactive({ value: '!' })
+
+const result = morph(source, s => s + suffix.value, {
+  pure: (s: string) => s === 'static'
+})
+
+result[0] // 'static!'  — pure, no effect
+result[1] // 'dynamic!' — reactive, tracks suffix.value
+
+suffix.value = '?'
+result[0] // 'static!'  — stale (pure)
+result[1] // 'dynamic?' — updated (reactive)
+```
+
+New items added to the source are classified by the predicate at first access. This is useful when some items are known to be static while others depend on external reactive state.
+
+**Example: pure vs reactive**
+
+```typescript
+const source = reactive([1, 2])
+const factor = reactive({ value: 10 })
+
+// Reactive: tracks factor.value per element
+const reactive = morph(source, x => x * factor.value)
+
+// Pure: ignores factor.value changes
+const pure = morph.pure(source, x => x * factor.value)
+
+factor.value = 20
+reactive[0] // 20 — recomputed
+pure[0]     // 10 — stale, no per-item effect to invalidate
+```
+
 ## Memoization
 
 ### `memoize()`
@@ -1073,7 +1354,7 @@ effect(() => {
 **Signature**
 
 ```typescript
-import { memoize } from 'mutts/reactive'
+import { memoize } from 'mutts'
 
 type Memoizable = object | any[] | symbol
 
@@ -1098,7 +1379,7 @@ function memoize<Result>(
 **Basic usage**
 
 ```typescript
-import { effect, memoize, reactive } from 'mutts/reactive'
+import { effect, memoize, reactive } from 'mutts'
 
 const source = reactive({ value: 1 })
 const args = { node: source }
@@ -1139,12 +1420,33 @@ describe({ id: 'x' } as any, { language: 'en' }) // locale is ignored, only the
 
 Use `maxArgs` when the memoized function should only consider the first _n_ arguments. Subsequent arguments are ignored and not forwarded to `fn`.
 
+### `memoize.lenient`
+
+A flavored variant that gracefully handles non-WeakKey arguments (primitives, `null`, `undefined`). Instead of throwing, it falls back to recomputing the function without caching.
+
+```typescript
+import { memoize } from 'mutts'
+
+const process = memoize.lenient((value: string | { data: string }) => {
+  return typeof value === 'string' ? value.toUpperCase() : value.data
+})
+
+const obj = { data: 'hello' }
+process(obj)     // Cached (object is a WeakKey)
+process(obj)     // Returns cached result
+
+process('world') // Recomputed each time (string is not a WeakKey)
+process('world') // Recomputed again — no caching for primitives
+```
+
+This is useful when a memoized function may receive both objects and primitives, and you want caching where possible without errors for the rest.
+
 ### Decorator usage
 
-Apply `@memoize` to class getters or methods to share the same cache semantics. Getters cache per instance; methods cache per instance and argument tuple.
+Apply `@memoize` (or `@memoize.lenient`) to class getters or methods to share the same cache semantics. Getters cache per instance; methods cache per instance and argument tuple.
 
 ```typescript
-import { memoize, reactive } from 'mutts/reactive'
+import { memoize, reactive } from 'mutts'
 
 class Example {
   state = reactive({ count: 0 })
@@ -1159,6 +1461,13 @@ class Example {
     return a.value + b.value + this.state.count
   }
 }
+
+class Flexible {
+  @memoize.lenient
+  process(value: string) {
+    return value.toUpperCase() // No throw — recomputes each time
+  }
+}
 ```
 
 ## Debugging and Development

package/docs/reactive/attend.md

@@ -10,7 +10,7 @@ The `attend` utility reactively iterates over the entries of a collection, runni
 - **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.
+This is the foundational lifecycle primitive that `organized` is built on.
 
 ## API
 
@@ -135,9 +135,7 @@ attend(
 | 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.
+`project` has additional concerns (target management) that go beyond `attend`'s independent-key lifecycle model.