mutts 1.0.8 → 1.0.10

package/docs/reactive/debugging.md

@@ -25,7 +25,7 @@ These hooks are called during the execution of effects and computed values.
 
 - **`beginChain(targets: Function[]) / endChain()`**: Called when a batch of effects starts and ends its execution.
 - **`maxEffectChain`**: (Default: `100`) Limits the depth of synchronous effect triggering to prevent stack overflows.
-- **`maxTriggerPerBatch`**: (Default: `10`) Limits how many times a single effect can be triggered within the same batch. Useful for detecting aggressive re-computation or infinite cycles in `cycleHandling: 'none'` mode.
+- **`maxTriggerPerBatch`**: (Default: `10`) Limits how many times a single effect can be triggered within the same batch. Useful for detecting aggressive re-computation or infinite cycles in `cycleHandling: 'production'` mode.
 
 ## Cycle Detection
 
@@ -35,22 +35,45 @@ These hooks are called during the execution of effects and computed values.
 
 You can control how cycles are handled via `reactiveOptions.cycleHandling`:
 
-- **`'none'`** (Default): High-performance FIFO mode. Disables the dependency graph and topological sorting.
-- **`'throw'`**: Throws a `ReactiveError` with a detailed path.
-- **`'warn'`**: Logs a warning but breaks the cycle to allow the application to continue.
-- **`'break'`**: Silently breaks the cycle.
-- **`'strict'`**: Performs a graph check *before* execution to prevent cycles from even starting. This has the highest overhead.
+- **`'production'`**: High-performance FIFO mode. Disables the dependency graph and topological sorting. Uses heuristic detection via `maxEffectChain`.
+- **`'development'`** (Default): Maintains direct dependency graph for early cycle detection during edge creation. Throws immediately with basic path information.
+- **`'debug'`**: Full diagnostic mode with transitive closures and topological sorting. Provides detailed cycle path reporting.
 
 ### Topological vs. Flat Mode Detection
+- **Detection**: Cycles are detected when the execution depth exceeds `maxEffectChain` (default 100).
+- **Diagnostics**: The resulting `ReactiveError` includes a `trace` property (the recent execution sequence) and attempts to identify a repeating `cycle`.
+- **Recommendation**: Use this mode only for production to minimize performance overhead.
 
-| Mode | `cycleHandling` | Detection Method | Error Code |
-| :--- | :--- | :--- | :--- |
-| **Topological** | `'throw'` (or other) | **Mathematical**: Analyzes the dependency graph. | `CYCLE_DETECTED` |
-| **Flat Mode** | `'none'` (Default) | **Heuristic**: Counts executions per batch. | `MAX_REACTION_EXCEEDED` |
+### Cycle Handling Modes
 
-In **Topological mode**, the system maintains a transitive closure of all effects, allowing it to know instantly if an effect is its own cause. In **Flat mode**, the system is "blind" to the graph and relies on the execution threshold (`maxTriggerPerBatch`) to interrupt infinite loops.
+You can configure how the system handles cycles via `reactiveOptions.cycleHandling`:
 
-## Memoization Discrepancy Detection
+| Mode | Detection Timing | Cycle Information | Performance |
+|------|-----------------|-------------------|-------------|
+| `'production'` | Late (Heuristic) | Trace of last N effects | Fastest |
+| `'development'` | Eager (On edge) | Exact path (DFS) | Moderate |
+| `'debug'` | Structural | Transitive closures | Slowest |
+
+#### Finding Cycle Information
+
+When a cycle is detected, a `ReactiveError` is thrown. You can find detailed path information in the error object:
+
+```typescript
+try {
+    atom(() => { /* cycle logic */ });
+} catch (error) {
+    if (error.code === 'Cycle detected') {
+        console.log('Cycle Path:', error.cycle.join(' → '));
+        console.log('Trigger Chain:', error.causalChain);
+    }
+}
+```
+
+- **`error.cycle`**: An array of effect names forming the cycle.
+- **`error.causalChain`**: The sequence of triggers that led to the current effect.
+- **`error.lineage`**: The creation stack of the effect (available in `development` or `debug` modes).
+
+### Memoization Discrepancy Detection
 
 The most powerful debugging tool in `mutts` is the **Discrepancy Detector**. It helps identify "missing dependencies"—reactive values used inside a computation that the system isn't tracking.
 
@@ -127,10 +150,12 @@ When the reactive system encounters a critical failure (like a cycle or max dept
 ### `ReactiveErrorCode`
 
 Always check `error.debugInfo.code` to identify the failure type:
-- `CYCLE_DETECTED`: A circular dependency was found.
-- `MAX_DEPTH_EXCEEDED`: The synchronous effect chain reached `maxEffectChain`.
-- `MAX_REACTION_EXCEEDED`: An effect was triggered too many times in a single batch.
-- `WRITE_IN_COMPUTED`: An attempt was made to modify reactive state inside a `memoize` or `derived` function.
+- `Cycle detected`: A circular dependency was found.
+- `Max depth exceeded`: The synchronous effect chain reached `maxEffectChain`.
+- `Max reaction exceeded`: An effect was triggered too many times in a single batch.
+- `Write in computed`: An attempt was made to modify reactive state inside a `memoize` function.
+- `Tracking error`: Internal inconsistency detected in the active dependency stack.
+- `Broken effects`: The system has entered an unrecoverable "broken" state after a root-level panic. Call `reset()` to recover.
 
 ### Rich Debug Info
 
@@ -138,6 +163,7 @@ The `debugInfo` property on `ReactiveError` includes:
 - **`causalChain`**: A string array describing the logical path of modifications leading to the error.
 - **`creationStack`**: The stack trace of where the effect was originally created, helping you locate the source in your code.
 - **`cycle`**: (For `CYCLE_DETECTED`) The names of the effects that form the loop.
+- **`lineage`**: Detailed source-to-sink dependency traces for debugging (requires `lineages` introspection).
 
 ## Best Practices for Debugging
 
@@ -149,20 +175,99 @@ Always provide a name for your effects to make debug logs and error messages rea
 effect(() => {
     // ...
 }, { name: 'UpdateSidebarCounter' });
+
+// Or
+
+effect.named('UpdateSidebarCounter')(() => {
+    // ...
+});
 ```
 
+
 ### Activation & Deactivation
 
 Since these are runtime options, you can toggle them based on your environment:
 
 ```typescript
 if (process.env.NODE_ENV === 'development') {
-    reactiveOptions.cycleHandling = 'throw';
+    reactiveOptions.cycleHandling = 'debug';
     reactiveOptions.onMemoizationDiscrepancy = myHandler;
     enableIntrospection();
 } else {
     // Ensure they are off in production for performance
     reactiveOptions.onMemoizationDiscrepancy = undefined;
-    reactiveOptions.cycleHandling = 'break';
+    reactiveOptions.cycleHandling = 'production';
 }
 ```
+
+## Advanced Debugging (`mutts/debug`)
+
+For a deeper look into the reactivity graph and execution flow, you can import the `mutts/debug` module. Simply importing it enables several background tracking features.
+
+```typescript
+import 'mutts/debug';
+```
+
+### Reaction Reasons (`CleanupReason`)
+
+When an effect or watcher re-runs, it receives a `reaction` property (in `EffectAccess`) that describes *why* it was triggered. This is also passed to the `cleanup` function.
+
+```typescript
+effect(({ reaction }) => {
+    if (reaction && typeof reaction === 'object') {
+        if (reaction.type === 'propChange') {
+            console.log('Triggered by:', reaction.triggers.map(t => t.evolution.prop));
+        }
+    }
+    
+    return (reason) => {
+        // reason is also a CleanupReason
+        if (reason?.type === 'stopped') console.log('Effect manually stopped');
+    };
+});
+```
+
+#### `formatCleanupReason`
+
+A built-in utility to turn a `CleanupReason` into an inspectable console log array.
+
+```typescript
+import { formatCleanupReason } from 'mutts';
+
+effect(()=> {
+    ...
+    return (reason)=> {
+        if (reason) console.log(...formatCleanupReason(reason));
+    }
+});
+```
+
+### Lineage Tracking
+
+Lineage tracking allows you to see the "causal path" of an effect—not just the current stack trace, but the stack traces of all parent effects that created the current execution.
+
+When an effect is created, it is assigned a `lineage` property that contains the stack traces of all parent effects that lead to its creation.
+
+- **`logLineage()`**: Prints a formatted, interactive tree of the current effect's lineage to the console.
+- **`captureLineage()`**: Captures the current lineage as a structured object.
+
+#### Lineage Options
+
+You can control how lineages are captured via `reactiveOptions.introspection.gatherReasons.lineages`:
+- `'none'`: Disable lineage capture.
+- `'touch'`: Capture lineage when a property is accessed (default).
+- `'dependency'`: Capture lineage when a dependency is recorded.
+- `'both'`: Capture both.
+
+### The `__MUTTS_DEBUG__` Global
+
+When `mutts/debug` is active (or after calling `enableDevTools()`), a global `__MUTTS_DEBUG__` object is exposed in the environment (Node.js `global` or Browser `window`).
+
+This object provides low-level access to the graph, lineage capture, and renaming utilities:
+- `__MUTTS_DEBUG__.getGraph()`: Returns the full reactivity graph.
+- `__MUTTS_DEBUG__.logLineage()`: logs the current lineage.
+- `__MUTTS_DEBUG__.browserLineage`: captures lineage for the DevTools panel.
+
+### Custom DevTools Formatters
+
+`mutts/debug` automatically registers [Custom Formatters](https://bit.ly/chrome-extension-custom-formatters) in Chrome. This makes lineage objects and reactive proxies appear as clean, structured trees in the console instead of opaque Proxy objects.

package/docs/reactive/error-handling.md

@@ -0,0 +1,121 @@
+# Effect Error Handling
+
+The `caught` function allows you to catch and handle errors within reactive effects.
+
+## Basic Usage
+
+Register an error handler inside an effect using `caught`:
+
+```typescript
+import { effect, caught, reactive } from 'mutts'
+
+const state = reactive({ value: 0 })
+
+effect(() => {
+  caught((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
+  caught((error) => {
+    if (error.message === 'Retryable') {
+      retryOperation()
+      return  // Success - stops here
+    }
+    throw error  // Re-throw to try next handler
+  })
+
+  // Second handler - log and continue
+  caught((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
+  caught((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(() => {
+  caught((error) => {
+    console.log('Handling error:', error)
+    
+    return () => {
+      // Cleanup when effect is destroyed
+      cleanupResources()
+    }
+  })
+})
+```
+
+## API
+
+### `caught(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 `caught` - use `.catch()` on the Promise

package/docs/reactive/resource.md

@@ -0,0 +1,125 @@
+# Reactive Resource (`resource`)
+
+The `resource` utility creates a reactive object that automatically tracks the state of an asynchronous operation (loading, value, error). It is designed to simplify data fetching and async state management in a reactive environment.
+
+## Overview
+
+`resource` wraps an async function (the "fetcher") and returns a reactive object that:
+-   **Tracks dependencies**: Automatically re-runs the fetcher when reactive dependencies accessed within it change.
+-   **Manages state**: Provides `loading`, `value`, `error`, and `latest` properties that update automatically.
+-   **Handles race conditions**: Ensures that only the result of the latest fetch is applied, discarding results from stale requests.
+-   **Supports manual reload**: Exposes a `reload()` method to force a refresh.
+
+## API
+
+```typescript
+function resource<T>(
+    fetcher: (dep: EffectAccess) => Promise<T> | T,
+    options?: { initialValue?: T }
+): Resource<T>
+
+interface Resource<T> {
+    value: T | undefined  // The current successful value
+    loading: boolean      // True if a fetch is in progress
+    error: any            // Error from the last failed fetch
+    latest: T | undefined // The latest successful value (preserved during loading)
+    reload: () => void    // Function to manually trigger a re-fetch
+}
+```
+
+### Parameters
+
+-   **`fetcher`**: A function that returns a value `T` or a `Promise<T>`. It receives an `EffectAccess` object, allowing for dependency tracking control (e.g., `dep.tracked()`). Reactive properties accessed synchronously or within tracked scopes are dependencies.
+-   **`options`**: Optional configuration object.
+    -   `initialValue`: Initial value for `value` and `latest` before the first fetch completes (or if the first fetch is async).
+
+### Returns
+
+A reactive object implementing the `Resource<T>` interface.
+
+## Usage
+
+### Basic Async Fetch
+
+```typescript
+import { reactive, resource } from 'mutts/reactive'
+
+// ID usually comes from another reactive source
+const state = reactive({ userId: 1 })
+
+// Create a resource that fetches user data based on state.userId
+const user = resource(async () => {
+    const response = await fetch(`/api/users/${state.userId}`)
+    return response.json()
+})
+
+// Use the resource in your view
+effect(() => {
+    if (user.loading) {
+        console.log('Loading...')
+    } else if (user.error) {
+        console.error('Error:', user.error)
+    } else {
+        console.log('User:', user.value)
+    }
+})
+
+// Changing state.userId automatically triggers a new fetch
+state.userId = 2
+```
+
+### Handling Race Conditions
+
+`resource` automatically handles race conditions. If `state.userId` changes quickly from 1 to 2, and the request for user 1 takes longer than user 2, the result for user 1 will be ignored when it arrives, preventing inconsistent state.
+
+### Using `latest` for Smooth Transitions
+
+The `value` property becomes `undefined` (or `initialValue`) when a new fetch starts if the previous value is not preserved (current implementation resets `value` only on success? No, `value` is kept from previous success? - *Clarification: In the implementation, `value` is NOT reset to undefined on new fetch start, it retains the old value until new value arrives, unless `initialValue` was used? Let's check implementation behavior.*)
+
+*Correction based on implementation:*
+The current implementation:
+```typescript
+state.loading = true
+state.error = undefined
+// ... fetcher executes ...
+// on success:
+state.value = val
+state.latest = val
+state.loading = false
+```
+It does **NOT** reset `value` to `undefined` when a new fetch starts. So `value` acts like `latest`. The distinction is primarily semantic or for future behavior where `value` might be reset. Currently `value` and `latest` behave similarly regarding preservation of old data during loading.
+
+```typescript
+effect(() => {
+    // Show old data while loading new data
+    if (user.loading) {
+        console.log('Reloading... showing cached version:', user.latest)
+    } else {
+        console.log('Current:', user.value)
+    }
+})
+```
+
+### Manual Reload
+
+You can trigger a re-fetch without changing dependencies:
+
+```typescript
+// Refresh the data (e.g., user clicked a "Refresh" button)
+user.reload()
+```
+
+### Synchronous Resources
+
+`resource` can also wrap synchronous calculations, essentially behaving like a computed property but with the `Resource` interface structure.
+
+```typescript
+const count = reactive({ value: 1 })
+
+const doubled = resource(() => {
+    return count.value * 2
+})
+
+console.log(doubled.value) // 2
+console.log(doubled.loading) // false
+```