mutts 1.0.6 → 1.0.8

package/README.md

@@ -44,6 +44,66 @@ import { Destroyable, allocated } from 'mutts/destroyable'
 
 **Note:** When importing from source files, you'll need to configure your build system (TypeScript, Vite, Webpack, etc.) to handle TypeScript compilation and module resolution. The source files are published alongside the built modules, so you can import directly from the `src` directory.
 
+### Environment Setup (Node vs Browser)
+
+`mutts` has two distinct entry points to handle environment-specific behaviors (like `async_hooks` in Node vs `wrap` in Browser).
+
+*   **Automatic Resolution**: Bundlers (Vite, Rollup, Webpack) and Node.js will automatically pick the correct entry point (`mutts/node` or `mutts/browser`) based on the `exports` field in `package.json`.
+*   **Manual Selection**: You can force a specific environment if needed:
+    ```typescript
+    import 'mutts/node' // Side-effect import to polyfill async hooks in tests
+    import { ... } from 'mutts/node' // Explicit Node entry
+    import { ... } from 'mutts/browser' // Explicit Browser entry
+    ```
+
+## [Reactive](./docs/reactive.md)
+
+A comprehensive reactivity system. See the **[Introduction](./docs/reactive/core.md)** or browse the **[Table of Contents](./docs/reactive.md)**.
+
+**Key Features:**
+- **Core Reactivity**: Proxy-based property access tracking with `reactive()`, `effect()`, `memoize()`, `project()`, and `scan()`
+- **Deep Watching**: Automatic tracking of nested object changes with `deepWatch()`
+- **Reactive Collections**: Specialized reactive versions of Array, Map, Set, WeakMap, and WeakSet
+- **Class Reactivity**: `@reactive` decorator and `ReactiveBase` for class-based reactivity
+- **Reactive Mixin**: Always-reactive classes with mixin support (`Reactive`)
+- **Back-Reference System**: Efficient change propagation through object hierarchies
+- **Type Safety**: Full TypeScript support with proper type inference
+- **Performance Optimized**: Lazy back-reference creation and efficient dependency tracking
+- **Debugging & Development**: Built-in tools like cycle detection and memoization discrepancy check
+
+**Use Cases:**
+- State management systems
+- UI framework reactivity
+- Data synchronization
+- Real-time applications
+- Form validation and processing
+
+## [Zones & Async Context](./docs/zone.md)
+
+A powerful context propagation system that maintains state across asynchronous boundaries (Promises, timeouts, listeners).
+
+**Key Features:**
+- **Universal Context**: Works reliably in both Node.js (via `async_hooks`) and Browser/Edge environments.
+- **Zone**: A simple value container that propagates with execution flow.
+- **ZoneHistory**: A zone that tracks the history of values it has held in the current execution path.
+- **ZoneAggregator**: Combines multiple zones into a single propagatable context.
+- **Async Hooks**: Low-level hooks to capture, restore, and undo context changes across async boundaries.
+
+```typescript
+import { Zone, asyncZone } from 'mutts'
+
+const userZone = new Zone<User>()
+// Register for async propagation
+asyncZone.add(userZone)
+
+userZone.with(currentUser, async () => {
+  // Context is available here
+  await someAsyncWork()
+  // Context is STILL available here, magically!
+  console.log(userZone.active) // currentUser
+})
+```
+
 ## [Indexable](./docs/indexable.md)
 
 A way to write classes that allow numeric indexes managed by a custom function - either given in the class by the symbols [getAt] and [setAt] either by a specification if the Indexable class.
@@ -156,26 +216,4 @@ A comprehensive resource management system that provides automatic cleanup for o
 - Network resource management
 - Memory management for large objects
 - Plugin systems with proper cleanup
-- Temporary resource management
-
-## [Reactive](./docs/reactive.md)
-
-A comprehensive reactivity system. See the **[Introduction](./docs/reactive/core.md)** or browse the **[Table of Contents](./docs/reactive.md)**.
-
-**Key Features:**
-- **Core Reactivity**: Proxy-based property access tracking with `reactive()`, `effect()`, and `memoize()`
-- **Deep Watching**: Automatic tracking of nested object changes with `deepWatch()`
-- **Reactive Collections**: Specialized reactive versions of Array, Map, Set, WeakMap, and WeakSet
-- **Class Reactivity**: `@reactive` decorator and `ReactiveBase` for class-based reactivity
-- **Reactive Mixin**: Always-reactive classes with mixin support (`Reactive`)
-- **Back-Reference System**: Efficient change propagation through object hierarchies
-- **Type Safety**: Full TypeScript support with proper type inference
-- **Performance Optimized**: Lazy back-reference creation and efficient dependency tracking
-- **Debugging & Development**: Built-in tools like cycle detection and memoization discrepancy check
-
-**Use Cases:**
-- State management systems
-- UI framework reactivity
-- Data synchronization
-- Real-time applications
-- Form validation and processing
+- Temporary resource management

package/dist/async/browser.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser.d.ts.map

package/dist/async/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/async/browser.ts"],"names":[],"mappings":""}

package/dist/async/index.d.ts

@@ -0,0 +1,18 @@
+export type Restorer = () => () => void;
+export type Hook = () => Restorer;
+export declare const asyncHooks: {
+    addHook(_hook: Hook): () => void;
+    /**
+     * [Hack] Sanitize a promise (or value) to prevent context leaks.
+     * Default: Identity function.
+     * Browser: Uses Macrotask wrapping to break microtask chains.
+     */
+    sanitizePromise(p: any): any;
+};
+/**
+ * Register a hook that will be called whenever an asynchronous operation is initiated.
+ * The hook should return a restorer function which will be called just before the async callback runs.
+ * That restorer should in turn return an undoer function which will be called just after the async callback finishes.
+ */
+export declare const asyncHook: (hook: Hook) => () => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/async/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,MAAM,IAAI,CAAA;AACvC,MAAM,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAA;AAEjC,eAAO,MAAM,UAAU;mBACP,IAAI,GAAG,MAAM,IAAI;IAG7B;;;;OAIG;uBACgB,GAAG,GAAG,GAAG;CAG/B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,IAAI,WAlBP,IAkBoC,CAAA"}

package/dist/async/node.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=node.d.ts.map

package/dist/async/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/async/node.ts"],"names":[],"mappings":""}