mutts 1.0.7 → 1.0.9

package/docs/reactive/describe.md

@@ -0,0 +1,85 @@
+# 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/error-handling.md

@@ -0,0 +1,121 @@
+# Effect Error Handling
+
+The `onEffectThrow` function allows you to catch and handle errors within reactive effects.
+
+## Basic Usage
+
+Register an error handler inside an effect using `onEffectThrow`:
+
+```typescript
+import { effect, onEffectThrow, reactive } from 'mutts'
+
+const state = reactive({ value: 0 })
+
+effect(() => {
+  onEffectThrow((error) => {
+    console.error('Effect failed:', error)
+  })
+
+  // Your effect logic that might throw
+  if (state.value < 0) throw new Error('Negative value not allowed')
+})
+```
+
+## Multiple Handlers
+
+You can register multiple handlers. They are tried in order until one succeeds:
+
+```typescript
+effect(() => {
+  // First handler - try to recover
+  onEffectThrow((error) => {
+    if (error.message === 'Retryable') {
+      retryOperation()
+      return  // Success - stops here
+    }
+    throw error  // Re-throw to try next handler
+  })
+
+  // Second handler - log and continue
+  onEffectThrow((error) => {
+    console.log('Operation failed:', error)
+  })
+})
+```
+
+## Parent-Child Error Propagation
+
+Errors in child effects propagate to parent effects:
+
+```typescript
+effect(() => {
+  // Parent catches child's error
+  onEffectThrow((error) => {
+    console.log('Child failed:', error.message)
+  })
+
+  effect(() => {
+    // This error propagates to parent, even if a reactive re-evaluation
+    throw new Error('Child error')
+  })
+})
+```
+
+If no handler catches the error, it propagates up the effect chain until caught or thrown at the root.
+
+## Cleanup from Handler
+
+Handlers can return cleanup functions:
+
+```typescript
+effect(() => {
+  onEffectThrow((error) => {
+    console.log('Handling error:', error)
+    
+    return () => {
+      // Cleanup when effect is destroyed
+      cleanupResources()
+    }
+  })
+})
+```
+
+## API
+
+### `onEffectThrow(handler)`
+
+Registers an error handler for the current effect.
+
+**Parameters:**
+- `handler: (error: any) => (() => void) | undefined | void` - Function called when an error occurs in the effect
+
+**Returns:** Nothing
+
+**Throws:** Error if called outside of an effect
+
+**Handler behavior:**
+- Returns without throwing → error is considered handled
+- Throws → next handler is tried
+- Returns a function → used as cleanup when effect stops
+
+## Error Propagation Flow
+
+```
+Effect throws
+    ↓
+Try handlers in order
+    ↓
+Handler succeeds → effect continues
+    ↓
+All handlers fail → propagate to parent
+    ↓
+Parent's handlers try
+    ↓
+...continue until caught or root reached
+```
+
+## Notes
+
+- Handlers must be registered **before** the code that might throw
+- Handlers are cleared on each effect re-run (re-register if needed)
+- Errors in async effects (Promises) are not caught by `onEffectThrow` - use `.catch()` on the Promise

package/docs/reactive/project.md

@@ -87,7 +87,7 @@ project.array(
 
 **Related Files:**
 - `src/reactive/project.ts` - Main implementation
-- `src/reactive/mapped.ts` - Reference for `ReactiveReadOnlyArray` pattern
+- `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

@@ -76,3 +76,218 @@ result[cleanup]()
 | **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

package/docs/reactive.md

@@ -12,6 +12,8 @@ The Mutts Reactive System documentation has been split into focused sections for
 *   **[Reactive Arrays](./reactive/collections.md#reactivearray)**: Full array method support
 *   **[Register](./reactive/collections.md#register)**: ID-keyed ordered collections
 *   **[Projections](./reactive/collections.md#projection)**: `project`, `organized`
+*   **[Attend](./reactive/attend.md)**: Reactive enumeration (`attend`)
+*   **[Describe](./reactive/describe.md)**: Reactive property definition (`describe`)
 *   **[Scan](./reactive/scan.md)**: Reactive scan and accumulation
 
 ## [Advanced Topics](./reactive/advanced.md)