mutts 1.0.10 → 1.0.12

package/docs/reactive/core.md

@@ -4,23 +4,22 @@
 
 - [Introduction](#introduction)
 - [Getting Started](#getting-started)
-  - [5-Minute Quick Start](#5-minute-quick-start)
+- [5-Minute Quick Start](#5-minute-quick-start)
 - [Core API](#core-api)
 - [Effect System](#effect-system)
-  - [Error Handling](./error-handling.md)
+- [Error Handling](./error-handling.md)
 - [Atomic Operations](./advanced.md#atomic-operations)
 - [Advanced Effects](./advanced.md#advanced-effects)
 - [Evolution Tracking](./advanced.md#evolution-tracking)
 - [Prototype Chains and Pure Objects](./advanced.md#prototype-chains-and-pure-objects)
 - [Recursive Touching](./advanced.md#recursive-touching)
 - [Collections](./collections.md)
-  - [Register](./collections.md#register)
 - [Class Reactivity](#class-reactivity)
 - [Non-Reactive System](#non-reactive-system)
 - [Morphing](./advanced.md#morph)
 - [Memoization](./advanced.md#memoization)
 - [Debugging and Development](./advanced.md#debugging-and-development)
-  - [Cycle Detection](./advanced.md#cycle-detection)
+- [Cycle Detection](./advanced.md#cycle-detection)
 
 ## Introduction
 
@@ -40,10 +39,13 @@ Reactivity is a programming paradigm where the system automatically tracks depen
 ### Basic Example
 
 ```typescript
-import { reactive, effect } from 'mutts/reactive'
+import { reactive, effect } from 'mutts'
 
 // Create a reactive object
-const user = reactive({ name: "John", age: 30 })
+const user = reactive({
+    name: "John",
+    age: 30
+})
 
 // Create an effect that depends on user properties
 effect(() => {
@@ -51,8 +53,8 @@ effect(() => {
 })
 
 // When properties change, the effect automatically re-runs
-user.name = "Jane"  // Triggers effect
-user.age = 25       // Triggers effect
+user.name = "Jane" // Triggers effect
+user.age = 25 // Triggers effect
 ```
 
 ## Getting Started
@@ -62,38 +64,45 @@ user.age = 25       // Triggers effect
 Learn the essentials in 5 minutes:
 
 **1. Make state reactive:**
+
 ```typescript
-import { reactive, effect } from 'mutts/reactive'
+import { reactive, effect } from 'mutts'
 
-const state = reactive({ count: 0, name: "John" })
+const state = reactive({
+    count: 0,
+    name: "John"
+})
 ```
 
 **2. React to changes:**
+
 ```typescript
 // Effects automatically re-run when dependencies change
 effect(() => {
-  console.log(`Hello ${state.name}, count is ${state.count}`)
+    console.log(`Hello ${state.name}, count is ${state.count}`)
 })
 
-state.count++       // Triggers effect
-state.name = "Jane"  // Triggers effect
+state.count++ // Triggers effect
+state.name = "Jane" // Triggers effect
 ```
 
 **3. Work with arrays:**
+
 ```typescript
 const items = reactive([1, 2, 3])
 
 effect(() => {
-  console.log(`Array length: ${items.length}`)
+    console.log(`Array length: ${items.length}`)
 })
 
-items.push(4)  // Triggers effect
+items.push(4) // Triggers effect
 ```
 
 **4. Use memoization:**
+
 ```typescript
 const memoized = memoize((user: User) => {
-  return expensiveComputation(user)
+    return expensiveComputation(user)
 })
 
 // Only recomputes when user changes
@@ -101,12 +110,12 @@ const result = memoized(user)
 ```
 
 **5. Map over arrays:**
+
 ```typescript
 const source = reactive([1, 2, 3])
-const doubled = morph(source, ({ value }) => value * 2)
-// [2, 4, 6]
+const doubled = morph(source, value => value * 2) // [2, 4, 6]
 
-source.push(4)  // doubled automatically becomes [2, 4, 6, 8]
+source.push(4) // doubled automatically becomes [2, 4, 6, 8]
 ```
 
 **Ready to go!** Continue reading for advanced features.
@@ -122,7 +131,7 @@ npm install mutts
 ### Basic Usage
 
 ```typescript
-import { reactive, effect } from 'mutts/reactive'
+import { reactive, effect } from 'mutts'
 
 // Make an object reactive
 const state = reactive({
@@ -140,17 +149,19 @@ effect(() => {
 })
 
 // Changes trigger effects automatically
-state.count++        // Triggers first effect
+state.count++ // Triggers first effect
 state.message = "Hi" // Triggers second effect
 ```
 
 ### Hello World Example
 
 ```typescript
-import { reactive, effect } from 'mutts/reactive'
+import { reactive, effect } from 'mutts'
 
 // Simple counter
-const counter = reactive({ value: 0 })
+const counter = reactive({
+    value: 0
+})
 
 effect(() => {
     document.body.innerHTML = `Count: ${counter.value}`
@@ -178,11 +189,14 @@ function reactive<T extends Record<PropertyKey, any>>(target: T): T
 **Returns:** A reactive proxy of the original object
 
 **Example:**
+
 ```typescript
-const obj = { count: 0 }
-const reactiveObj = reactive(obj)
+const obj = {
+    count: 0
+}
+
+const reactiveObj = reactive(obj) // reactiveObj is now reactive
 
-// reactiveObj is now reactive
 effect(() => {
     console.log(reactiveObj.count) // Tracks dependency
 })
@@ -192,9 +206,7 @@ reactiveObj.count = 5 // Triggers effect
 
 **Note:** The same object will always return the same proxy instance.
 
-**Pure Objects and Prototypes:**
-
-`reactive()` works with any object type, including:
+**Pure Objects and Prototypes:** `reactive()` works with any object type, including:
 - Normal objects: `reactive({ x: 1 })`
 - Pure objects: `reactive(Object.create(null))`
 - Objects with prototypes: `reactive(Object.create(parent))`
@@ -208,9 +220,9 @@ Creates a reactive effect that automatically re-runs when dependencies change.
 
 ```typescript
 interface DependencyAccess {
-    tracked: DependencyFunction  // Track dependencies in the current effect
-    ascend: DependencyFunction    // Track dependencies in the parent effect
-    reaction: boolean             // true after the first run
+    tracked: DependencyFunction // Track dependencies in the current effect
+    ascend: DependencyFunction // Track dependencies in the parent effect
+    reaction: boolean // true after the first run
 }
 
 function effect(
@@ -231,16 +243,21 @@ function effect(
 **Returns:** A cleanup function to stop the effect
 
 **Example:**
+
 ```typescript
-const state = reactive({ count: 0, mood: 'happy' })
+const state = reactive({
+    count: 0,
+    mood: 'happy'
+})
 
 const cleanup = effect(() => {
     console.log(`Count is: ${state.count}`)
+    
     // Optional cleanup called before next run
     return () => console.log('Cleaning up...')
 })
 
-state.count++   // Does trigger: 1- the cleaning, 2- the effect
+state.count++ // Does trigger: 1- the cleaning, 2- the effect
 state.mood = 'surprised' // Does not trigger the effect
 
 // Later...
@@ -260,8 +277,13 @@ effect(({ reaction }) => {
 ```
 
 **Using effect with arguments (useful in loops):**
+
 ```typescript
-const items = reactive([{ id: 1 }, { id: 2 }, { id: 3 }])
+const items = reactive([
+    { id: 1 },
+    { id: 2 },
+    { id: 3 }
+])
 
 // Create effects in a loop, passing loop variables
 for (let i = 0; i < items.length; i++) {
@@ -280,8 +302,12 @@ function unwrap<T>(proxy: T): T
 ```
 
 **Example:**
+
 ```typescript
-const original = { count: 0 }
+const original = {
+    count: 0
+}
+
 const reactive = reactive(original)
 const unwrapped = unwrap(reactive)
 
@@ -312,7 +338,10 @@ function isNonReactive(obj: any): boolean
 Effects are the core of the reactive system. They automatically track dependencies and re-run when those dependencies change.
 
 ```typescript
-const state = reactive({ count: 0, name: "John" })
+const state = reactive({
+    count: 0,
+    name: "John"
+})
 
 effect(() => {
     // This effect depends on state.count
@@ -320,7 +349,7 @@ effect(() => {
 })
 
 // Only changing count triggers the effect
-state.count = 5     // Triggers effect
+state.count = 5 // Triggers effect
 state.name = "Jane" // Does NOT trigger effect
 ```
 
@@ -329,7 +358,9 @@ state.name = "Jane" // Does NOT trigger effect
 Effects return cleanup functions that you can call to stop tracking dependencies.
 
 ```typescript
-const state = reactive({ count: 0 })
+const state = reactive({
+    count: 0
+})
 
 const stopEffect = effect(() => {
     console.log(`Count: ${state.count}`)
@@ -349,13 +380,17 @@ The reactive system provides **automatic cleanup** for effects, making memory ma
 
 1. **Parent-Child Cleanup**: When an effect is created inside another effect, it becomes a "child" of the parent effect. When the parent effect is cleaned up, it also cleans up its child effects.
 
-2. **Garbage Collection Cleanup**: For top-level effects (not created inside other effects), the system uses JavaScript's garbage collection to automatically clean them up when their cleanup function no longer referenced.
+2. **Garbage Collection Cleanup**: For top-level effects (not created inside other effects), the system uses JavaScript's garbage collection to automatically clean them up when their cleanup function is no longer referenced.
 
 #### Examples
 
 **Parent-Child Cleanup:**
+
 ```typescript
-const state = reactive({ a: 1, b: 2 })
+const state = reactive({
+    a: 1,
+    b: 2
+})
 
 const stopParent = effect(() => {
     state.a
@@ -374,8 +409,11 @@ stopParent() // Logs (order may vary): "Child cleanup", then "Parent cleanup"
 ```
 
 **Garbage Collection Cleanup:**
+
 ```typescript
-const state = reactive({ value: 1 })
+const state = reactive({
+    value: 1
+})
 
 // Top-level effect - automatically cleaned up via garbage collection
 effect(() => {
@@ -391,7 +429,10 @@ effect(() => {
 While cleanup can be automatic via GC, you should **store and remember** cleanup functions both to prevent the effect from being garbage-collected (keeping it alive) and to perform immediate cleanup when needed. If you don't hold a reference to the cleanup (or to the effect), the effect can be collected and its cleanup called automatically by GC; storing a reference keeps it active under your control:
 
 ```typescript
-const state = reactive({ value: 1 })
+const state = reactive({
+    value: 1
+})
+
 const activeEffects: (() => void)[] = []
 
 // Store cleanup functions for effects with side effects
@@ -417,19 +458,79 @@ activeEffects.forEach(stop => stop())
 ```
 
 **Key Points:**
-
 - **You do not have to call cleanup** - GC may clean up effects when no references remain
 - **You may want to call cleanup** - especially for effects with side effects
 - **Store cleanup references to keep effects alive** - holding a reference prevents GC cleanup and gives you explicit stop control
 - **Parent cleanup cleans child effects** - stopping a parent also stops its child effects
 - **Child effects are referenced by parent effects** - and therefore are not subject to GC cleanups
 
+### Object Lifecycle with `link` / `unlink`
+
+While effects handle their own cleanup automatically, **derived reactive objects** (morph results, lifted arrays, processed children, etc.) often need explicit lifecycle management. `link` and `unlink` solve this by forming a **cleanup tree** — an ownership graph independent of the effect hierarchy.
+
+```typescript
+import { link, unlink } from 'mutts'
+```
+
+#### Attaching cleanup dependencies
+
+`link(owner, ...deps)` attaches dependencies to an owner object. Dependencies can be:
+- **Functions** — called with an optional `CleanupReason` on disposal
+- **Objects** — recursively `unlink`ed on disposal
+
+```typescript
+const parent = reactive({
+    items: []
+})
+
+// Attach a cleanup callback
+link(parent, () => console.log('parent disposed'))
+
+// Attach child objects — they will be recursively unlinked
+const childA = morph(parent.items, ({ value }) => value * 2)
+const childB = morph(parent.items, ({ value }) => value + 1)
+
+link(parent, childA, childB)
+
+// Mixed: objects and functions together
+link(parent, childA, () => timer.clear())
+```
+
+#### Disposing an object
+
+`unlink(obj)` disposes all dependencies attached to `obj`:
+
+```typescript
+unlink(parent)
+
+// 1. childA is recursively unlinked (its own deps disposed)
+// 2. childB is recursively unlinked
+// 3. the callback runs: "parent disposed"
+```
+
+Calling `unlink` twice is safe — the second call is a no-op. Not calling `unlink` is also fine — the object will be cleaned up when garbage is collected.
+
+#### When to use `link`/`unlink` vs effects
+
+| Scenario | Use |
+|---|---|
+| Reacting to state changes | `effect` |
+| Tying a derived object's lifetime to its owner | `link` / `unlink` |
+| Cleaning up timers, listeners, DOM nodes | `effect` return or `link` callback |
+| Building a cleanup tree across multiple reactive objects | `link` / `unlink` |
+
+**Rule of thumb**: if the thing you're cleaning up is a *reactive object* (not a function), prefer `link`. If it's a *side effect* (timer, listener), prefer an `effect` return or a `link` callback.
+
 ### Effect Dependencies
 
 Effects automatically track which reactive properties they access.
 
 ```typescript
-const state = reactive({ a: 1, b: 2, c: 3 })
+const state = reactive({
+    a: 1,
+    b: 2,
+    c: 3
+})
 
 effect(() => {
     // Only tracks state.a and state.b
@@ -444,13 +545,11 @@ state.c = 15 // Does NOT trigger effect
 
 ### Async Effects and the `access` Parameter
 
-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 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 `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 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
 
-Traditionally, in JavaScript, async functions lose their context when they yield control. 
+Traditionally, in JavaScript, async functions lose their context when they yield control.
 
 #### Understanding the active effect context
 
@@ -467,36 +566,28 @@ effect(() => {
 // Async effect WITHOUT zone registration - context is lost after await
 effect(async () => {
     const value = state.count // ✅ Tracked
-    
-    await someAsyncOperation() 
-    
-    // context is lost!
+    await someAsyncOperation() // context is lost!
     const another = state.name // ❌ NOT tracked
 })
 
 // Async effect WITH zone registration - context is preserved
 effect(async () => {
     const value = state.count // ✅ Tracked
-    
-    await someAsyncOperation() 
-    
-    // context is automatically restored!
+    await someAsyncOperation() // context is automatically restored!
     const another = state.name // ✅ Tracked
 })
 
 // Using access.tracked() for manual restoration
 effect(async ({ tracked }) => {
-    await someAsyncOperation() 
-    
-    // Useful for non-patched APIs or explicit scoping
+    await someAsyncOperation() // Useful for non-patched APIs or explicit scoping
     const another = tracked(() => state.name) // ✅ Tracked
 })
 ```
 
 #### Key Benefits of the Zone System
 
-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.
+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
 
@@ -532,18 +623,21 @@ effect(({ ascend }) => {
 Effects can be created inside other effects and will have separate effect scopes:
 
 ```typescript
-import { effect, reactive } from 'mutts/reactive'
+import { effect, reactive } from 'mutts'
 
-const state = reactive({ a: 0, b: 0 })
+const state = reactive({
+    a: 0,
+    b: 0
+})
 
 const stopOuter = effect(() => {
     state.a
-
+    
     // Create an inner effect with its own scope
     const stopInner = effect(() => {
         state.b
     })
-
+    
     // Return cleanup function for the inner effect
     return stopInner
 })
@@ -554,21 +648,25 @@ const stopOuter = effect(() => {
 The `untracked()` function allows you to run code without tracking dependencies, which can be useful for creating effects or performing operations that shouldn't be part of the current effect's dependency graph.
 
 ```typescript
-import { effect, untracked, reactive } from 'mutts/reactive'
+import { effect, untracked, reactive } from 'mutts'
 
-const state = reactive({ a: 0, b: 0 })
+const state = reactive({
+    a: 0,
+    b: 0
+})
 
 effect(() => {
     state.a
-
+    
     // Create an inner effect without tracking the creation under the outer effect
     let stopInner: (() => void) | undefined
+    
     untracked(() => {
         stopInner = effect(() => {
             state.b
         })
     })
-
+    
     // Optionally stop it immediately to avoid accumulating watchers
     stopInner && stopInner()
 })
@@ -584,7 +682,7 @@ effect(() => {
 Configure the reactive system behavior:
 
 ```typescript
-import { options as reactiveOptions } from 'mutts/reactive'
+import { options as reactiveOptions } from 'mutts'
 
 // Set maximum effect chain depth
 reactiveOptions.maxEffectChain = 50
@@ -610,9 +708,14 @@ The `effect` function provides convenient shortcut modifiers for common options.
 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'
+import { effect, reactive } from 'mutts'
 
-const item = reactive({ id: 1, data: { value: 10 } })
+const item = reactive({
+    id: 1,
+    data: {
+        value: 10
+    }
+})
 
 // Regular effect - triggers on any property change
 effect(() => {
@@ -624,8 +727,9 @@ 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
+item.data.value = 20 // Triggers regular effect, NOT opaque effect
+
+item.data = { value: 30 } // Triggers BOTH effects
 ```
 
 **Use cases for opaque effects:**
@@ -638,9 +742,11 @@ item.data = { value: 30 }  // Triggers BOTH effects
 Creates a named effect for easier debugging and profiling. The name appears in DevTools and debug logs.
 
 ```typescript
-import { effect, reactive } from 'mutts/reactive'
+import { effect, reactive } from 'mutts'
 
-const state = reactive({ count: 0 })
+const state = reactive({
+    count: 0
+})
 
 // Create a named effect
 effect.named('counter-effect')(() => {
@@ -689,13 +795,14 @@ createDataEffect(() => {
 })
 ```
 
+## Class Reactivity
 
 ### `@reactive` Decorator
 
 The `@reactive` decorator makes class instances automatically reactive. This is the recommended approach for adding reactivity to classes.
 
 ```typescript
-import { reactive } from 'mutts/reactive'
+import { reactive } from 'mutts'
 
 @reactive
 class User {
@@ -727,7 +834,7 @@ user.name = "Jane" // Triggers effect
 You can also use the functional syntax for making classes reactive:
 
 ```typescript
-import { reactive } from 'mutts/reactive'
+import { reactive } from 'mutts'
 
 class User {
     name: string
@@ -759,11 +866,14 @@ user.name = "Jane" // Triggers effect
 For complex inheritance trees, especially when you need to solve constructor reactivity issues, extend `ReactiveBase`:
 
 ```typescript
-import { ReactiveBase, reactive } from 'mutts/reactive'
+import { ReactiveBase, reactive } from 'mutts'
 
 class GameObject extends ReactiveBase {
     id = 'game-object'
-    position = { x: 0, y: 0 }
+    position = {
+        x: 0,
+        y: 0
+    }
 }
 
 class Entity extends GameObject {
@@ -783,11 +893,10 @@ effect(() => {
 })
 
 player.position.x = 10 // Triggers effect
-player.health = 80     // Triggers effect
+player.health = 80 // Triggers effect
 ```
 
 **Advantages of `ReactiveBase`:**
-
 1. **Constructor Reactivity**: Solves the issue where `this` in the constructor is not yet reactive
 2. **Inheritance Safety**: Prevents reactivity from being added to prototype chains in complex inheritance trees
 3. **No Side Effects**: The base class itself has no effect - it only enables proper reactivity when combined with `@reactive`
@@ -799,7 +908,7 @@ player.health = 80     // Triggers effect
 - You want the cleanest, most modern syntax
 - You don't need to modify or use `this` in the constructor
 
-**Use `ReactiveBase` + `@reactive` when:**
+**Use `ReactiveBase`+`@reactive` when:**
 - You have complex inheritance trees (like game objects, UI components)
 - You need to modify or use `this` in the constructor
 - You want to prevent reactivity from being added to prototype chains
@@ -854,7 +963,7 @@ effect(() => {
     console.log('Cart items:', cart.items)
 })
 
-cart.addItem('Apple')  // Triggers effect
+cart.addItem('Apple') // Triggers effect
 cart.removeItem('Apple') // Triggers effect
 ```
 
@@ -907,15 +1016,23 @@ function unreactive(target: Constructor<T>): Constructor<T>
 
 ```typescript
 // Mark individual object as non-reactive
-const obj = { count: 0 }
+const obj = {
+    count: 0
+}
+
 unreactive(obj)
+
 const reactiveObj = reactive(obj) // Returns obj unchanged
 
 // Mark entire class as non-reactive
 class Utility {
-    static helper() { return 'help' }
+    static helper() {
+        return 'help'
+    }
 }
+
 unreactive(Utility)
+
 const instance = new Utility()
 const reactiveInstance = reactive(instance) // Returns instance unchanged
 ```
@@ -929,7 +1046,6 @@ Mark class properties as non-reactive using class-level syntax.
 @unreactive('id')
 class User {
     id: string = 'user-123'
-    
     name: string = 'John'
     age: number = 30
 }
@@ -938,7 +1054,7 @@ const user = new User()
 
 effect(() => {
     console.log(user.name, user.age) // Tracks these
-    console.log(user.id)             // Does NOT track this
+    console.log(user.id) // Does NOT track this
 })
 
 user.name = 'Jane' // Triggers effect
@@ -1040,23 +1156,29 @@ Non-reactive objects can improve performance:
 ```typescript
 // Good: Mark large, rarely-changing objects as non-reactive
 const config = unreactive({
-    apiEndpoints: { /* large config object */ },
-    featureFlags: { /* many flags */ }
+    apiEndpoints: {
+        /* large config object */
+    },
+    featureFlags: {
+        /* many flags */
+    }
 })
 
 // Good: Mark utility classes as non-reactive
 class MathUtils {
     static PI = 3.14159
-    static square(x: number) { return x * x }
+    
+    static square(x: number) {
+        return x * x
+    }
 }
+
 unreactive(MathUtils)
 
 // Good: Mark properties that don't need reactivity
 class User {
-    @unreactive
-    metadata: any = {} // Large metadata object
+    @unreactive metadata: any = {} // Large metadata object
     
     name: string = 'John' // This should be reactive
 }
-```
-
+```