mutts 1.0.9 → 1.0.11

package/docs/reactive/describe.md

@@ -1,85 +0,0 @@
-# Reactive Property Description (`describe`)
-
-The `describe` utility provides a reactive way to define or update properties on an object using a record of property descriptors.
-
-## Overview
-
-Unlike `Object.defineProperties`, the reactive `describe` utility is alive:
-- It tracks the **keys** of the descriptors record.
-- When a new key is added to the descriptors record, the property is defined on the target object.
-- When a key is removed, the property is removed from the target object.
-- When a descriptor itself changes (e.g. its `value` or `get` function), the property definition is updated.
-
-This is particularly useful when projecting props or dynamically extending objects in a reactive way.
-
-Internally, `describe` is built on [`attend`](./attend.md), which provides the reactive key lifecycle.
-
-## API
-
-```typescript
-function describe<T extends object>(
-    descriptors: Record<PropertyKey, PropertyDescriptor>,
-    target: T = {} as T
-): T
-```
-
-### Parameters
-
-- `descriptors`: A reactive record where each value is a standard `PropertyDescriptor`.
-- `target` (optional): The object to define properties on. If omitted, a new plain object is created and returned.
-
-### Returns
-
-The `target` object with reactive property definitions.
-
-## Basic Usage
-
-```typescript
-import { reactive, describe, effect } from 'mutts/reactive'
-
-const target = {}
-const descriptors = reactive({
-    foo: { value: 1, enumerable: true }
-})
-
-describe(descriptors, target)
-
-console.log(target.foo) // 1
-
-// Adding a property reactively
-descriptors.bar = { get: () => 42, enumerable: true }
-console.log(target.bar) // 42
-
-// Removing a property reactively
-delete descriptors.foo
-console.log('foo' in target) // false
-```
-
-## Integration with `project`
-
-`describe` is often used in conjunction with `project` to create dynamic projections of property descriptors:
-
-```typescript
-import { project, describe, memoize } from 'mutts/reactive'
-
-function propsInto(props, into) {
-    const descriptors = project(props, ({ key, value }) => ({
-        get: memoize(() => (typeof value === 'function' ? value() : value)),
-        enumerable: true,
-        configurable: true
-    }))
-    
-    return describe(descriptors, into)
-}
-```
-
-## Renaming Conflict
-
-Previously, `mutts` had a decorator named `describe`. To avoid confusion with this utility, the decorator has been renamed to `@descriptor`.
-
-```typescript
-@descriptor({ enumerable: false })
-class MyClass {
-    internal = 'secret'
-}
-```

package/docs/reactive/project.md

@@ -1,93 +0,0 @@
-# Reactive Register Memoization Notes
-
-## Background
-
-- Register entries are stored in a reactive `Map`. Updating an entry via `Map.set` marks the entire value as changed.
-- Memoized computations that read through `map.get(key)` re-execute fully when the entry changes, even if only a nested property is touched.
-- The goal for rendering lists in a JSX/HTML engine is to avoid rebuilding DOM nodes; only the affected properties should update.
-
-## Evolution: From `organized` to `project`
-
-### Initial State
-
-- `memoize` caches results but invalidates on `Map.set`, so large effects still re-run.
-- `organized` (designed for `Record` sources) creates per-key effects so downstream work reruns only for the touched key; this matches the desired behaviour.
-- **Gap:** `organized` operates on plain objects: key enumeration relies on property iteration and `FoolProof.get/set`. Registers and other keyed collections (`Map`, `Register`, custom stores) need the same per-entry orchestration without converting to records.
-
-### Completed Evolution: `project` Implementation
-
-We implemented `project` as a generalized transformation helper that works across arrays, records, and maps:
-
-**Key Design Decisions:**
-- **Unified API:** Single `project` function with runtime dispatch to `project.array`, `project.record`, or `project.map` based on source type.
-- **Access Pattern:** Callback receives a `ProjectAccess` object with `get()`, `set()`, `key`, `source`, and `value` (computed property) - similar to `organized` but returning a value instead of an effect.
-- **Automatic Target Creation:** The function always creates its own reactive target container (array, record, or map) - no `baseTarget` parameter needed.
-- **Per-Key Effects:** Each source key/index gets its own reactive effect that recomputes only when that specific entry changes, enabling granular updates for rendering pipelines.
-
-**Current API:**
-```typescript
-project.array(source: readonly T[], apply: (access, target) => U): ProjectResult<U[]>
-project.record(source: Record<K, T>, apply: (access, target) => U): ProjectResult<Record<K, U>>
-project.map(source: Map<K, T>, apply: (access, target) => U): ProjectResult<Map<K, U>>
-```
-
-**Current Behavior:**
-- Eager computation: all entries are computed immediately when keys are present.
-- One-way transformation: callback only handles "get" (read) operations; no write-back support.
-- Mutable results: returned arrays/records/maps are fully mutable.
-- `ProjectAccess.old` exposes the previously computed result for each entry, enabling incremental updates and state preservation.
-
-## Future Evolutions
-
-### Bidirectional Transformation (Set Callback)
-
-**Goal:** Support writing back to the source through the projected object.
-
-**Implementation:**
-- Add optional second callback parameter: `set: (access, newValue, target) => void | boolean`
-- When `set` is provided, mutations to the projected object trigger the set callback.
-- The callback receives the same `ProjectAccess` object plus the new value, allowing it to update the source.
-- If `set` returns `false` or throws, the mutation is rejected.
-
-**API Impact:**
-```typescript
-project.array(
-  source: readonly T[],
-  apply: (access, target) => U,
-  set?: (access, newValue: U, target) => void | boolean
-): ProjectResult<U[]>
-```
-
-### Readonly Results When No Set Callback
-
-**Goal:** Make projected objects readonly when no write-back is supported.
-
-**Implementation:**
-- When `set` callback is not provided, wrap the result in a readonly proxy or use read-only array/record types.
-- Prevents accidental mutations that would have no effect on the source.
-- Type system should reflect readonly nature in return types.
-
-**API Impact:**
-- Return type becomes `ProjectResult<readonly U[]>` or similar when `set` is omitted.
-- Arrays use `ReactiveReadOnlyArray` (already exists in `mapped.ts`).
-- Records and maps need readonly wrappers or proxy-based protection.
-
-## Implementation Notes for AI Agents
-
-**Current State:**
-- `project` is fully functional for arrays, records, maps, and registers with eager, one-way transformation.
-- Tests cover per-key reactivity, key addition/removal, automatic helper selection, and `access.old` value propagation.
-- The implementation follows the same per-key effect pattern as `organized` but returns computed values.
-
-**Future Work:**
-- Lazy computing requires careful effect lifecycle management to avoid memory leaks.
-- Bidirectional support needs to handle edge cases (concurrent reads/writes, validation).
-- Readonly enforcement should align with existing `ReactiveReadOnlyArray` patterns where possible.
-- Consider whether these features should be opt-in via options object or separate function variants.
-
-**Related Files:**
-- `src/reactive/project.ts` - Main implementation
-- `src/reactive/array.ts` - Reference for `ReactiveReadOnlyArray` pattern
-- `src/reactive/record.ts` - Reference for `organized` pattern (different use case)
-- `tests/reactive/project.test.ts` - Test coverage
-

package/docs/reactive/scan.md

@@ -1,293 +0,0 @@
-# Reactive Scan
-
-The `scan` function perform a reactive accumulation over an array of items. Unlike a standard `Array.reduce`, it is designed to be highly efficient in a reactive system, particularly when items are moved or changed, by returning a reactive array of all intermediate results.
-
-## Overview
-
-In a typical reactive system, calling `array.reduce(...)` inside an `effect` means the entire reduction re-runs every time the array structure or a single item changes.
-
-Reactive `scan` solves this by maintaining a chain of **reactive intermediates**. Each item in the source array is linked to an intermediate that depends on the *previous* intermediate's result.
-
-## Key Features
-
-- **Fine-Grained Reactivity**: Changing a property on an item only re-computes the accumulated value for that item and its successors.
-- **Move Optimization**: If a subsequence of items moves together (e.g., sorting or splicing), their intermediates are reused. As long as an item's predecessor in the array hasn't changed, its accumulated value is hit from the cache.
-- **Duplicate Support**: Correctly handles multiple occurrences of the same object instance.
-- **Memory Safety**: Uses `WeakMap` for intermediate storage, ensuring data is cleared when source items are garbage collected.
-- **Granular Sync**: Uses per-index effects to sync results, preventing broad dependency tracking of the source array in every calculation.
-
-## Basic Usage
-
-```typescript
-import { reactive, scan } from 'mutts/reactive'
-
-const source = reactive([
-  { id: 'A', val: 1 },
-  { id: 'B', val: 2 },
-  { id: 'C', val: 3 },
-])
-
-// result is a reactive array: [1, 3, 6]
-const result = scan(source, (acc, item) => acc + item.val, 0)
-
-// Updating an item only re-computes for that position and successors
-source[1].val = 10
-// result stays [1, 11, 14]
-```
-
-## How it Works
-
-The implementation consists of:
-1. **A Main Effect**: Tracks the structure of the source array (length and item identities). It manages a list of `Intermediate` objects and stays updated on their `prev` links.
-2. **Intermediates**: Class instances that link `val` and `prev`. They expose an `acc` getter decorated with `@memoize`.
-3. **Index Sync Effects**: Granular effects (one per result index) that subscribe to `indexToIntermediate[i].acc`.
-
-This "Project-like" architecture ensures that the main loop only does structural work, while the actual logic propagation is handled by the dependency chain of the intermediates.
-
-## API Reference
-
-```typescript
-function scan<Input extends object, Output>(
-    source: readonly Input[],
-    callback: (acc: Output, val: Input) => Output,
-    initialValue: Output
-): ScanResult<Output>
-```
-
-### Parameters
-- `source`: The source array. All items must be objects (WeakKeys) to enable intermediate caching.
-- `callback`: The accumulator function `(acc, val) => nextAcc`.
-- `initialValue`: The value used as the accumulator for the first item.
-
-### Returns
-A reactive array of accumulated values. It includes a `[cleanup]` symbol that should be called to stop the reactive tracking.
-
-```typescript
-import { cleanup } from 'mutts/reactive'
-// ...
-result[cleanup]()
-```
-
-## Performance Comparison
-
-| Operation | Standard `Array.reduce` in `effect` | Reactive `scan` |
-| :--- | :--- | :--- |
-| **Initial Run** | O(N) calls | O(N) calls |
-| **Modify Item at `i`** | O(N) calls (entire reduction) | O(N-i) calls |
-| **Append Item** | O(N+1) calls | 1 call |
-| **Move Item** | O(N) calls | O(affected chain) |
-
----
-
-# Lift
-
-The `lift` function transforms a callback that returns an array or object into a reactive array/object that automatically synchronizes with the source whenever dependencies change.
-
-## Overview
-
-`lift` is useful when you have a reactive computation that produces an array or object, and you want that result to be reactive itself. It efficiently syncs only the elements that differ from the previous result, minimizing DOM updates and downstream effects.
-
-## Basic Usage
-
-### Array Example
-
-```typescript
-import { reactive, lift } from 'mutts/reactive'
-
-const items = reactive([1, 2, 3])
-const doubled = lift(() => items.map(x => x * 2))
-
-console.log([...doubled]) // [2, 4, 6]
-
-items.push(4)
-console.log([...doubled]) // [2, 4, 6, 8]
-```
-
-### Object Example
-
-```typescript
-import { reactive, lift } from 'mutts/reactive'
-
-const user = reactive({ name: 'John', age: 30 })
-const profile = lift(() => ({
-  displayName: user.name.toUpperCase(),
-  isAdult: user.age >= 18,
-  description: `${user.name} is ${user.age} years old`
-}))
-
-console.log(profile.displayName) // JOHN
-console.log(profile.isAdult) // true
-
-user.name = 'Jane'
-console.log(profile.displayName) // JANE
-console.log(profile.description) // Jane is 30 years old
-```
-
-## How it Works
-
-`lift` creates a reactive array or object and sets up an effect that:
-1. Calls the provided callback to get the source array or object
-2. Compares the source with the current reactive result
-3. Updates only the elements/properties that have changed
-4. Adjusts the structure if needed (array length or object properties)
-
-For arrays, this approach preserves references to unchanged elements and triggers minimal reactive updates. For objects, it uses `Object.assign()` to merge changes and removes properties that no longer exist in the source.
-
-## API Reference
-
-```typescript
-function lift<Output extends (any[] | object)>(
-    cb: (access: EffectAccess) => Output
-): Output & { [cleanup]: ScopedCallback }
-```
-
-### Parameters
-- `cb`: A callback function that returns an array or object. The callback is tracked reactively, so accessing reactive values inside it will cause the result to update when those values change. The callback receives an `EffectAccess` parameter for advanced use cases.
-
-### Returns
-A reactive array or object that stays synchronized with the callback's result. The result includes a `[cleanup]` symbol that can be called to stop tracking.
-
-```typescript
-import { cleanup } from 'mutts/reactive'
-// ...
-doubled[cleanup]()
-profile[cleanup]()
-```
-
-## Use Cases
-
-### Dynamic Filtering (Arrays)
-
-```typescript
-const allItems = reactive([
-  { id: 1, active: true, name: 'Item 1' },
-  { id: 2, active: false, name: 'Item 2' },
-  { id: 3, active: true, name: 'Item 3' },
-])
-
-const activeItems = lift(() => allItems.filter(item => item.active))
-
-// activeItems automatically updates when items change or active status changes
-allItems[1].active = true
-console.log(activeItems.length) // 3
-```
-
-### Computed Transformations (Arrays)
-
-```typescript
-const numbers = reactive([1, 2, 3, 4, 5])
-const multiplier = reactive({ value: 2 })
-
-const scaled = lift(() => numbers.map(n => n * multiplier.value))
-
-multiplier.value = 3
-// scaled is now [3, 6, 9, 12, 15]
-```
-
-### Conditional Array Construction
-
-```typescript
-const showExtras = reactive({ value: false })
-const baseItems = reactive(['A', 'B', 'C'])
-
-const displayItems = lift(() => 
-  showExtras.value 
-    ? [...baseItems, 'Extra 1', 'Extra 2']
-    : baseItems
-)
-
-showExtras.value = true
-// displayItems is now ['A', 'B', 'C', 'Extra 1', 'Extra 2']
-```
-
-### Computed Object Properties
-
-```typescript
-const user = reactive({ firstName: 'John', lastName: 'Doe', age: 30 })
-const settings = reactive({ theme: 'dark', language: 'en' })
-
-const userProfile = lift(() => ({
-  fullName: `${user.firstName} ${user.lastName}`,
-  isMinor: user.age < 18,
-  displayTheme: settings.theme === 'dark' ? 'Dark Mode' : 'Light Mode',
-  locale: settings.language.toUpperCase()
-}))
-
-user.firstName = 'Jane'
-// userProfile.fullName is now 'Jane Doe'
-
-settings.theme = 'light'
-// userProfile.displayTheme is now 'Light Mode'
-```
-
-### Dynamic Object Composition
-
-```typescript
-const baseConfig = reactive({ api: 'https://api.example.com', timeout: 5000 })
-const userPrefs = reactive({ retries: 3, logging: false })
-const envVars = reactive({ debug: true, version: '1.0.0' })
-
-const fullConfig = lift(() => ({
-  ...baseConfig,
-  ...userPrefs,
-  environment: envVars.debug ? 'development' : 'production',
-  version: envVars.version,
-  logging: envVars.debug || userPrefs.logging
-}))
-
-envVars.debug = false
-// fullConfig.environment becomes 'production'
-
-userPrefs.logging = true
-// fullConfig.logging becomes true
-```
-
-### Conditional Object Properties
-
-```typescript
-const user = reactive({ role: 'admin', permissions: ['read', 'write'] })
-const showAdvanced = reactive({ value: true })
-
-const userInterface = lift(() => {
-  const base = {
-    canEdit: user.permissions.includes('write'),
-    userName: user.role
-  }
-  
-  return showAdvanced.value ? {
-    ...base,
-    isAdmin: user.role === 'admin',
-    permissionCount: user.permissions.length
-  } : base
-})
-
-showAdvanced.value = false
-// userInterface no longer has isAdmin and permissionCount properties
-```
-
-## Comparison with `scan`
-
-| Feature | `lift` | `scan` |
-| :--- | :--- | :--- |
-| **Purpose** | Synchronize with computed arrays/objects | Accumulate values with intermediates |
-| **Input** | Callback returning array/object | Source array + accumulator function |
-| **Output** | Reactive array/object | Reactive array of accumulated values |
-| **Optimization** | Element-wise/property-wise sync | Intermediate caching + move optimization |
-| **Use Case** | Derived arrays/objects (map, filter, computed properties) | Cumulative operations (sum, reduce) |
-| **Data Types** | Arrays and objects | Arrays only (object items required) |
-
-## Performance Considerations
-
-### Arrays
-- **Efficient Updates**: Only changed elements are updated, not the entire array
-- **Length Adjustments**: Array length changes are handled separately from element updates
-- **Reference Stability**: Unchanged elements maintain their references
-
-### Objects
-- **Property-wise Updates**: Only changed properties are updated using `Object.assign()`
-- **Property Addition/Removal**: Properties are added or removed as needed when the source object structure changes
-- **Reference Stability**: The reactive object maintains its identity while properties are updated
-
-### General
-- **Cleanup**: Remember to call the cleanup function when the lifted array/object is no longer needed to prevent memory leaks
-- **Type Consistency**: The callback must return the same type (array or object) on subsequent calls