mutts 1.0.13 → 1.0.14

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: 'production'` 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, especially in `scheduler: 'raw'` mode.
 
 ## Cycle Detection
 
@@ -33,25 +33,27 @@ These hooks are called during the execution of effects and computed values.
 
 ### Configuration
 
-You can control how cycles are handled via `reactiveOptions.cycleHandling`:
+You can control how cycles are handled via `reactiveOptions.scheduler`:
 
-- **`'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.
+- **`'ordered'`** (Default): Maintains the causal effect graph for dependency ordering, parent/child lifecycle ordering, and early cycle detection. Throws immediately with basic path information.
+- **`'raw'`**: High-performance FIFO mode. Disables the dependency graph and topological sorting. Uses heuristic detection via `maxEffectChain`.
+- **`'debug'`**: Ordered scheduling plus the heaviest diagnostics. Provides detailed cycle path reporting.
+
+`reactiveOptions.cycleHandling` is still accepted as a deprecated alias: `'production'` maps to `'raw'`, and `'development'` maps to `'ordered'`.
 
 ### 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.
+- **Recommendation**: Use `raw` only when FIFO scheduling is sufficient and you want minimum overhead.
 
 ### Cycle Handling Modes
 
-You can configure how the system handles cycles via `reactiveOptions.cycleHandling`:
+You can configure how the system handles cycles via `reactiveOptions.scheduler`:
 
 | Mode | Detection Timing | Cycle Information | Performance |
 |------|-----------------|-------------------|-------------|
-| `'production'` | Late (Heuristic) | Trace of last N effects | Fastest |
-| `'development'` | Eager (On edge) | Exact path (DFS) | Moderate |
+| `'ordered'` | Eager (On edge) | Exact path (DFS) | Moderate |
+| `'raw'` | Late (Heuristic) | Trace of last N effects | Fastest |
 | `'debug'` | Structural | Transitive closures | Slowest |
 
 #### Finding Cycle Information
@@ -71,7 +73,7 @@ try {
 
 - **`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).
+- **`error.lineage`**: The creation stack of the effect (available in `ordered` or `debug` modes).
 
 ### Memoization Discrepancy Detection
 
@@ -190,13 +192,13 @@ Since these are runtime options, you can toggle them based on your environment:
 
 ```typescript
 if (process.env.NODE_ENV === 'development') {
-    reactiveOptions.cycleHandling = 'debug';
+    reactiveOptions.scheduler = 'debug';
     reactiveOptions.onMemoizationDiscrepancy = myHandler;
     enableIntrospection();
 } else {
-    // Ensure they are off in production for performance
+    // Keep heavy diagnostics off in production for performance
     reactiveOptions.onMemoizationDiscrepancy = undefined;
-    reactiveOptions.cycleHandling = 'production';
+    reactiveOptions.scheduler = 'ordered'; // or 'raw' when FIFO scheduling is enough
 }
 ```
 

package/docs/reactive.md

@@ -19,6 +19,7 @@ The Mutts Reactive System documentation has been split into focused sections for
 ## [Advanced Topics](./reactive/advanced.md)
 *   **[Choosing the Right Primitive](./reactive/advanced.md#choosing-the-right-reactive-primitive)**: Comparison table of effect-value functions (memoize, lift, project, etc.)
 *   **[Atomic Operations](./reactive/advanced.md#atomic-operations)**: Batching and Bidirectional binding
+*   **[Effect Ordering](./reactive/advanced.md#effect-ordering-with-phase-tokens)**: Use reactive phase tokens to make dependency ordering explicit
 *   **[Evolution Tracking](./reactive/advanced.md#evolution-tracking)**: History introspection
 *   **[Prototype Chains](./reactive/advanced.md#prototype-chains-and-pure-objects)**: Advanced inheritance patterns
 *   **[Memoization](./reactive/advanced.md#memoization)**: Caching strategies
@@ -30,4 +31,4 @@ The Mutts Reactive System documentation has been split into focused sections for
 *   **[Memoization Discrepancy](./reactive/debugging.md#memoization-discrepancy-detection)**: Identifying missing dependencies
 *   **[Introspection API](./reactive/debugging.md#introspection-api)**: Programmatic analysis and dependency graphs
 
-*   **[Performance](./reactive/debugging.md#performance-cost)**: Understanding the cost of debugging tools
+*   **[Performance](./reactive/debugging.md#performance-cost)**: Understanding the cost of debugging tools

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mutts",
   "description": "Modern UTility TS: A collection of TypeScript utilities",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "main": "dist/browser.cjs",
   "module": "dist/browser.esm.js",
   "exports": {
@@ -90,7 +90,8 @@
   "files": [
     "dist",
     "README.md",
-    "docs"
+    "docs",
+    "BROWSER_ASYNC_POLYFILL.md"
   ],
   "scripts": {
     "build:js": "rollup -c",
@@ -142,6 +143,8 @@
     "./src/entry-browser.dev.ts",
     "./src/entry-node.ts",
     "./src/entry-node.dev.ts",
+    "./debug/index.ts",
+    "./debug/debug.ts",
     "./dist/browser.esm.js",
     "./dist/browser.dev.esm.js",
     "./dist/browser.cjs",
@@ -149,7 +152,9 @@
     "./dist/node.esm.js",
     "./dist/node.dev.esm.js",
     "./dist/node.cjs",
-    "./dist/node.dev.cjs"
+    "./dist/node.dev.cjs",
+    "./dist/debug.esm.js",
+    "./dist/debug.cjs"
   ],
   "engines": {
     "node": ">=16.0.0"
@@ -162,8 +167,8 @@
     "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^12.1.4",
     "@types/node": "^22.10.10",
-    "@vitest/browser": "^4.0.18",
-    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/browser": "^4.1.4",
+    "@vitest/browser-playwright": "^4.1.4",
     "playwright": "^1.58.1",
     "rollup": "^4.52.2",
     "rollup-plugin-copy": "^3.5.0",
@@ -174,7 +179,7 @@
     "tsx": "^4.20.4",
     "typescript": "^5.8.3",
     "vis-network": "^9.1.9",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.4"
   },
   "packageManager": "pnpm@10.7.1+sha512.2d92c86b7928dc8284f53494fb4201f983da65f0fb4f0d40baafa5cf628fa31dae3e5968f12466f17df7e97310e30f343a648baea1b9b350685dafafffdf5808"
-}
+}