mutts 1.0.8 → 1.0.10

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

@@ -43,6 +43,43 @@ 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/reactive'
+
+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.
@@ -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,225 @@ 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 |
+| `scan(source, fn, init)` | Eager | Reactive array | Yes (per-index) | **Yes** | `result[cleanup]()` | Running accumulations (prefix sums) |
+| `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`/`scan` return reactive proxies where each property/index is independently trackable.
+- **Identity stable**: `lift`, `morph`, and `scan` 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/reactive'
+
+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/reactive'
+
+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()`
@@ -1139,9 +1421,30 @@ 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/reactive'
+
+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'
@@ -1159,6 +1462,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
@@ -1169,8 +1479,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.
-