mutts 1.0.6 → 1.0.7

package/docs/zone.md

@@ -0,0 +1,88 @@
+# Zones (`mutts/zone`)
+
+Zones provide a high-performance **context management system** that follows the execution flow, ensuring your variables "stay put" even across asynchronous boundaries like `Promises`, `setTimeout`, or `queueMicrotask`.
+
+## Basic Usage
+
+A `Zone` represents a piece of storage that is scoped to the current execution block.
+
+```typescript
+import { Zone } from 'mutts/zone';
+
+const myZone = new Zone<string>();
+
+myZone.with("context-value", () => {
+    // Inside this function, the zone is active
+    console.log(myZone.active); // "context-value"
+});
+
+console.log(myZone.active); // undefined
+```
+
+## Async Propagation
+
+By default, zones are lost when an async operation yields control (e.g., after `await`). To fix this, `mutts` provides `configureAsyncZone()`.
+
+```typescript
+import { configureAsyncZone, asyncZone, Zone } from 'mutts/zone';
+
+const requestId = new Zone<string>();
+
+// 1. Tell the global aggregator to track this zone
+asyncZone.add(requestId);
+
+// 2. Patch global async primitives (once per app)
+configureAsyncZone();
+
+// 3. Usage
+requestId.with("req-123", async () => {
+    await somePromise();
+    // Context is automatically preserved across await!
+    console.log(requestId.active); // "req-123"
+});
+```
+
+## Core API
+
+### `AZone<T>` (Abstract)
+The base class for all zone implementations.
+- `active: T | undefined`: The current value in the zone.
+- `with<R>(value: T, fn: () => R): R`: Executes `fn` with `value` set as active.
+- `root<R>(fn: () => R): R`: Executes `fn` with the zone cleared (undefined).
+- `zoned: FunctionWrapper`: A getter that returns a function which, when called, restores the zone to its **current** state.
+
+### `Zone<T>`
+Simple stack-based storage.
+
+### `ZoneHistory<T>`
+A zone wrapper that maintains a `history` of previously active values in the current stack. 
+- Useful for **Cycle Detection**.
+- Prevents re-entering the same value if already in the history.
+- `present: AZone<T>`: Access the current value without the history overhead.
+
+### `ZoneAggregator`
+Combines multiple zones into one.
+- Entering an aggregator (with `.with()`) enters all its member zones.
+- `asyncZone` is a global aggregator used for the async patches.
+
+## Manual Context Bridging
+
+If you are using an API that `mutts` doesn't automatically patch, you can use the `.zoned` capture mechanism:
+
+```typescript
+const wrap = myZone.zoned; // Snapshot the current context
+
+// Pass the wrapper to an unmanaged callback
+externalLib.on('event', () => {
+    wrap(() => {
+        console.log("Context is back:", myZone.active);
+    });
+});
+```
+
+## Integration with Reactivity
+
+The `mutts` reactivity system uses zones internally to track the `activeEffect`. 
+- Every `effect()` execution runs inside the `effectHistory` zone.
+- Circular dependency detection is powered by `ZoneHistory`.
+- Async effects survive `await` because `effectHistory` is a member of the global `asyncZone`.

package/package.json

@@ -1,19 +1,51 @@
 {
   "name": "mutts",
   "description": "Modern UTility TS: A collection of TypeScript utilities",
-  "version": "1.0.6",
-  "main": "src/index.ts",
-  "module": "src/index.ts",
-  "types": "src/index.ts",
+  "version": "1.0.7",
+  "main": "dist/browser.js",
+  "module": "dist/browser.esm.js",
+  "types": "dist/browser.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "source": "./src/index.ts",
-      "import": "./dist/index.esm.js",
-      "require": "./dist/index.js",
-      "script": "./dist/mutts.umd.min.js"
+      "node": {
+        "types": "./dist/node.d.ts",
+        "import": "./dist/node.esm.js",
+        "require": "./dist/node.js"
+      },
+      "default": {
+        "types": "./dist/browser.d.ts",
+        "import": "./dist/browser.esm.js",
+        "require": "./dist/browser.js"
+      }
     },
-    "./src/*": "./src/*"
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.esm.js",
+      "require": "./dist/browser.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.esm.js",
+      "require": "./dist/node.js"
+    },
+    "./src": {
+      "node": {
+        "types": "./src/async/node.ts",
+        "import": "./src/async/node.ts"
+      },
+      "default": {
+        "types": "./src/async/browser.ts",
+        "import": "./src/async/browser.ts"
+      }
+    },
+    "./src/browser": {
+      "types": "./src/async/browser.ts",
+      "import": "./src/async/browser.ts"
+    },
+    "./src/node": {
+      "types": "./src/async/node.ts",
+      "import": "./src/async/node.ts"
+    }
   },
   "files": [
     "dist",

package/src/async/browser.ts

@@ -0,0 +1,87 @@
+import { Hook, Restorer, asyncHooks } from '.'
+
+const hooks = new Set<Hook>()
+
+asyncHooks.addHook = function (hook: Hook) {
+	hooks.add(hook)
+	return () => {
+		hooks.delete(hook)
+	}
+}
+
+export * from '../index'
+
+function wrap<Args extends any[], R>(fn: ((...args: Args) => R) | null | undefined) {
+	if (typeof fn !== 'function') return fn
+	const restorers = new Set<Restorer>()
+	for (const hook of hooks) restorers.add(hook())
+
+	return function (this: any, ...args: Args) {
+		const undoers = new Set<() => void>()
+		for (const restore of restorers) undoers.add(restore())
+		try {
+			return fn.apply(this, args)
+		} finally {
+			for (const undo of undoers) undo()
+		}
+	}
+}
+
+const originals = {
+	then: Promise.prototype.then,
+	catch: Promise.prototype.catch,
+	finally: Promise.prototype.finally,
+	setTimeout: globalThis.setTimeout,
+	setInterval: globalThis.setInterval,
+	setImmediate: globalThis.setImmediate,
+	requestAnimationFrame: globalThis.requestAnimationFrame,
+	queueMicrotask: globalThis.queueMicrotask,
+}
+
+Promise.prototype.then = function <T, R1, R2>(
+	this: Promise<T>,
+	onFulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null,
+	onRejected?: ((reason: any) => R2 | PromiseLike<R2>) | null
+): Promise<R1 | R2> {
+	return originals.then.call(this, wrap(onFulfilled), wrap(onRejected))
+}
+
+Promise.prototype.catch = function <T>(
+	this: Promise<T>,
+	onRejected?: ((reason: any) => T | PromiseLike<T>) | null
+): Promise<T> {
+	return originals.catch.call(this, wrap(onRejected))
+}
+
+Promise.prototype.finally = function <T>(
+	this: Promise<T>,
+	onFinally?: (() => void) | null
+): Promise<T> {
+	return originals.finally.call(this, wrap(onFinally))
+}
+
+globalThis.setTimeout = ((callback: Function, ...args: any[]) => {
+	return originals.setTimeout.call(globalThis, wrap(callback as any), ...args)
+}) as any
+
+globalThis.setInterval = ((callback: Function, ...args: any[]) => {
+	return originals.setInterval.call(globalThis, wrap(callback as any), ...args)
+}) as any
+
+if (originals.setImmediate) {
+	globalThis.setImmediate = ((callback: Function, ...args: any[]) => {
+		return originals.setImmediate.call(globalThis, wrap(callback as any), ...args)
+	}) as any
+}
+
+if (originals.requestAnimationFrame) {
+	globalThis.requestAnimationFrame = (callback: FrameRequestCallback) => {
+		return originals.requestAnimationFrame.call(globalThis, wrap(callback))
+	}
+}
+
+if (originals.queueMicrotask) {
+	globalThis.queueMicrotask = (callback: VoidFunction): void => {
+		originals.queueMicrotask.call(globalThis, wrap(callback))
+	}
+}

package/src/async/index.ts

@@ -0,0 +1,8 @@
+export type Restorer = () => () => void
+export type Hook = () => Restorer
+
+export const asyncHooks = {
+	addHook(_hook: Hook): () => void {
+		throw 'One must import the library from the server or the client side'
+	}
+}

package/src/async/node.ts

@@ -0,0 +1,46 @@
+import { createHook } from 'node:async_hooks'
+import { Hook, Restorer, asyncHooks } from '.'
+
+const hooks = new Set<Hook>()
+const restorersPerAsyncId = new Map<number, Set<Restorer>>()
+const undoersPerAsyncId = new Map<number, Set<() => void>>()
+
+createHook({
+	init(asyncId) {
+		const restorers = new Set<Restorer>()
+		for (const hook of hooks) {
+			restorers.add(hook())
+		}
+		restorersPerAsyncId.set(asyncId, restorers)
+	},
+	before(asyncId) {
+		const restorers = restorersPerAsyncId.get(asyncId)
+		if (restorers) {
+			const undoers = new Set<() => void>()
+			for (const restore of restorers) {
+				undoers.add(restore())
+			}
+			undoersPerAsyncId.set(asyncId, undoers)
+		}
+	},
+	after(asyncId) {
+		const undoers = undoersPerAsyncId.get(asyncId)
+		if (undoers) {
+			for (const undo of undoers) undo()
+			undoersPerAsyncId.delete(asyncId)
+		}
+	},
+	destroy(asyncId) {
+		restorersPerAsyncId.delete(asyncId)
+		undoersPerAsyncId.delete(asyncId)
+	}
+}).enable()
+
+asyncHooks.addHook = function (hook: Hook) {
+	hooks.add(hook)
+	return () => {
+		hooks.delete(hook)
+	}
+}
+
+export * from '../index'

package/src/decorator.ts

@@ -62,7 +62,11 @@ type DDMethod<T> = (
 	name: PropertyKey
 ) => ((this: T, ...args: any[]) => any) | void
 
-type DDGetter<T> = (original: (this: T) => any, target: any, name: PropertyKey) => ((this: T) => any) | void
+type DDGetter<T> = (
+	original: (this: T) => any,
+	target: any,
+	name: PropertyKey
+) => ((this: T) => any) | void
 
 type DDSetter<T> = (
 	original: (this: T, value: any) => void,

package/src/destroyable.ts

@@ -117,7 +117,7 @@ export function Destroyable<
 		base = undefined
 	}
 	if (!base) {
-		base = class { } as T
+		base = class {} as T
 	}
 
 	return class Destroyable extends (base as T) {

package/src/index.ts

@@ -4,29 +4,37 @@ export * from './eventful'
 export * from './indexable'
 export * from './iterableWeak'
 export * from './mixins'
+export * from './promiseChain'
 export * from './reactive'
 export * from './std-decorators'
 export * from './utils'
+export * from './zone'
 
 import pkg from '../package.json'
+
 const { version } = pkg
 
 // Singleton verification
 const GLOBAL_MUTTS_KEY = '__MUTTS_INSTANCE__'
-const globalScope = 
-	(typeof globalThis !== 'undefined' ? globalThis : 
-	(typeof window !== 'undefined' ? window : 
-	(typeof global !== 'undefined' ? global : false))) as any
-if(globalScope) {
+const globalScope = (
+	typeof globalThis !== 'undefined'
+		? globalThis
+		: typeof window !== 'undefined'
+			? window
+			: typeof global !== 'undefined'
+				? global
+				: false
+) as any
+if (globalScope) {
 	// Detect the source of this instance safely across different environments
 	let source = 'mutts/index'
+	const viteEval = eval
 	try {
 		// @ts-ignore
 		if (typeof __filename !== 'undefined') source = __filename
-		// @ts-ignore
 		else {
 			// Using eval to avoid SyntaxError in CJS environments where import.meta is not allowed
-			const meta = eval('import.meta')
+			const meta = viteEval('import.meta')
 			if (meta && meta.url) source = meta.url
 		}
 	} catch (e) {
@@ -36,18 +44,18 @@ if(globalScope) {
 	const currentSourceInfo = {
 		version,
 		source,
-		timestamp: Date.now()
+		timestamp: Date.now(),
 	}
 
 	if (globalScope[GLOBAL_MUTTS_KEY]) {
 		const existing = globalScope[GLOBAL_MUTTS_KEY]
 		throw new Error(
-			`[Mutts] Multiple instances detected!\n` + 
-			`Existing instance: ${JSON.stringify(existing, null, 2)}\n` +
-			`New instance: ${JSON.stringify(currentSourceInfo, null, 2)}\n` +
-			`This usually happens when 'mutts' is both installed as a dependency and bundled, ` +
-			`or when different versions are loaded. ` +
-			`Please check your build configuration (aliases, externals) to ensure a single source of truth.`
+			`[Mutts] Multiple instances detected!\n` +
+				`Existing instance: ${JSON.stringify(existing, null, 2)}\n` +
+				`New instance: ${JSON.stringify(currentSourceInfo, null, 2)}\n` +
+				`This usually happens when 'mutts' is both installed as a dependency and bundled, ` +
+				`or when different versions are loaded. ` +
+				`Please check your build configuration (aliases, externals) to ensure a single source of truth.`
 		)
 	}
 

package/src/indexable.ts

@@ -140,6 +140,48 @@ export function Indexable<Items, Base extends abstract new (...args: any[]) => a
 				})
 				return true
 			},
+			has(target, prop) {
+				if (prop in target) return true
+				if (typeof prop === 'string') {
+					if (prop === 'length' && accessor.getLength) return true
+					const numProp = Number(prop)
+					if (!Number.isNaN(numProp)) return true
+				}
+				return false
+			},
+			ownKeys(target) {
+				const keys = Reflect.ownKeys(target)
+				if (accessor.getLength) {
+					keys.push('length')
+					const len = accessor.getLength.call(this as any)
+					for (let i = 0; i < len; i++) keys.push(String(i))
+				}
+				return keys
+			},
+			getOwnPropertyDescriptor(target, prop) {
+				if (prop in target) return Object.getOwnPropertyDescriptor(target, prop)
+				if (typeof prop === 'string') {
+					if (prop === 'length' && accessor.getLength) {
+						return {
+							enumerable: false,
+							configurable: true,
+							get: () => accessor.getLength!.call(this as any),
+						}
+					}
+					const numProp = Number(prop)
+					if (!Number.isNaN(numProp)) {
+						return {
+							enumerable: true,
+							configurable: true,
+							get: () => accessor.get!.call(this as any, numProp),
+							set: accessor.set
+								? (v: any) => accessor.set!.call(this as any, numProp, v)
+								: undefined,
+						}
+					}
+				}
+				return undefined
+			},
 		})
 	)
 	return Indexable

package/src/mixins.ts

@@ -1,4 +1,4 @@
-import { isConstructor, ReflectGet } from './utils'
+import { FoolProof, isConstructor } from './utils'
 
 /**
  * A mixin function that takes a base class and returns a new class with mixed-in functionality
@@ -85,7 +85,7 @@ export function mixin<MixinFn extends (base: any) => new (...args: any[]) => any
 				const originalPrototype = baseClass.prototype
 				const proxiedPrototype = new Proxy(originalPrototype, {
 					get(target, prop, receiver) {
-						const value = ReflectGet(target, prop, receiver)
+						const value = FoolProof.get(target, prop, receiver)
 
 						// Only wrap methods that are likely to access private fields
 						// Skip symbols and special properties that the reactive system needs