mutts 1.0.7 → 1.0.8

package/dist/zone.d.ts

@@ -0,0 +1,40 @@
+export declare abstract class AZone<T> {
+    abstract active?: T;
+    protected enter(value?: T): unknown;
+    protected leave(entered: unknown): void;
+    with<R>(value: T, fn: () => R): R;
+    root<R>(fn: () => R): R;
+    get zoned(): FunctionWrapper;
+}
+export type FunctionWrapper = <R>(fn?: () => R) => R;
+export declare class Zone<T> extends AZone<T> {
+    active: T | undefined;
+}
+type HistoryValue<T> = {
+    present: T | undefined;
+    history: Set<T>;
+};
+export declare class ZoneHistory<T> extends AZone<HistoryValue<T>> {
+    private controlled;
+    private history;
+    readonly present: AZone<T>;
+    has(value: T): boolean;
+    some(predicate: (value: T) => boolean): boolean;
+    constructor(controlled?: AZone<T>);
+    get active(): HistoryValue<T> | undefined;
+    set active(value: HistoryValue<T> | undefined);
+}
+export declare class ZoneAggregator extends AZone<Map<AZone<unknown>, unknown>> {
+    #private;
+    constructor(...zones: AZone<unknown>[]);
+    get active(): Map<AZone<unknown>, unknown> | undefined;
+    set active(value: Map<AZone<unknown>, unknown> | undefined);
+    enter(value?: Map<AZone<unknown>, unknown> | undefined): Map<AZone<unknown>, unknown>;
+    leave(entered: Map<AZone<unknown>, unknown>): void;
+    add(z: AZone<unknown>): void;
+    delete(z: AZone<unknown>): void;
+    clear(): void;
+}
+export declare const asyncZone: ZoneAggregator;
+export {};
+//# sourceMappingURL=zone.d.ts.map

package/dist/zone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone.d.ts","sourceRoot":"","sources":["../src/zone.ts"],"names":[],"mappings":"AAUA,8BAAsB,KAAK,CAAC,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACnB,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,OAAO;IAKnC,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAGvC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAYjC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAQvB,IAAI,KAAK,IAAI,eAAe,CAG3B;CACD;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;AAEpD,qBAAa,IAAI,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IACpC,MAAM,EAAE,CAAC,GAAG,SAAS,CAAA;CACrB;AACD,KAAK,YAAY,CAAC,CAAC,IAAI;IAAC,OAAO,EAAE,CAAC,GAAG,SAAS,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAA;CAAC,CAAA;AAChE,qBAAa,WAAW,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAU7C,OAAO,CAAC,UAAU;IAT9B,OAAO,CAAC,OAAO,CAAe;IAC9B,SAAgB,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;IAC1B,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO;IAGtB,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO;gBAIlC,UAAU,GAAE,KAAK,CAAC,CAAC,CAAiB;IAqBxD,IAAI,MAAM,IAGQ,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAD5C;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,EAG5C;CACD;AAED,qBAAa,cAAe,SAAQ,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;;gBAE1D,GAAG,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE;IAItC,IAAI,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,GAAG,SAAS,CAKrD;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,GAAG,SAAS,EAEzD;IACD,KAAK,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,GAAG,SAAS;IAQtD,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,GAAG,IAAI;IAGlD,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC;IAGrB,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC;IAGxB,KAAK;CAGL;AAED,eAAO,MAAM,SAAS,gBAAqC,CAAA"}

package/docs/std-decorators.md

@@ -1,4 +1,4 @@
-TODO: redo the doc here
+
 # Standard decorators
 
 A TypeScript library that provides standard decorators that should stop being re-implemented for the 50th time
@@ -551,6 +551,74 @@ deprecated.warn = (target, propertyKey, message?) => {
 4. **Document migration paths**: Provide clear upgrade instructions
 5. **Monitor usage**: Track which deprecated features are still being used
 
+## Debounce
+
+The `debounce` decorator delays the execution of a method until a specified amount of time has passed since the last time it was called. This is useful for handling rapid events like keystrokes or window resizing.
+
+## API Reference
+
+### `@debounce(delay: number)`
+
+A decorator that debounces a method.
+
+**Parameters:**
+- `delay`: The delay in milliseconds to wait before executing the method.
+
+**Returns:** A method decorator.
+
+## Usage Example
+
+```typescript
+import { debounce } from 'mutts/std-decorators'
+
+class SearchComponent {
+  @debounce(300)
+  onSearch(query: string) {
+    // This will only run after 300ms of inactivity
+    console.log(`Searching for: ${query}`)
+    this.performApiCall(query)
+  }
+
+  performApiCall(query: string) {
+    // ...
+  }
+}
+```
+
+## Throttle
+
+The `throttle` decorator limits the execution of a method to at most once every specified amount of time. This is useful for rate-limiting expensive operations like scroll handlers or animations.
+
+## API Reference
+
+### `@throttle(delay: number)`
+
+A decorator that throttles a method.
+
+**Parameters:**
+- `delay`: The time interval in milliseconds.
+
+**Returns:** A method decorator.
+
+## Usage Example
+
+```typescript
+import { throttle } from 'mutts/std-decorators'
+
+class ScrollHandler {
+  @throttle(100)
+  onScroll(event: Event) {
+    // This will run at most once every 100ms
+    console.log('Scroll event processed')
+    this.updateUI()
+  }
+
+  updateUI() {
+    // ...
+  }
+}
+```
+
 ## Related
 
 - [JavaScript Decorators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Decorators)

package/docs/zone.md

@@ -42,6 +42,13 @@ requestId.with("req-123", async () => {
 });
 ```
 
+> [!WARNING]
+> TODO
+> **Browser Limitations**: In browser environments (where `AsyncLocalStorage` is unavailable), `mutts` relies on monkey-patching global async primitives (Promise, setTimeout, etc.) to propagate zones. This is generally less robust than Node.js's `async_hooks` and may fail to track context across:
+> *   Native `async/await` boundaries in some modern browsers if not transpiled.
+> *   Concurrent modifications to global prototypes by other libraries.
+
+
 ## Core API
 
 ### `AZone<T>` (Abstract)

package/package.json

@@ -1,50 +1,56 @@
 {
   "name": "mutts",
   "description": "Modern UTility TS: A collection of TypeScript utilities",
-  "version": "1.0.7",
-  "main": "dist/browser.js",
+  "version": "1.0.8",
+  "main": "dist/browser.cjs",
   "module": "dist/browser.esm.js",
   "types": "dist/browser.d.ts",
   "exports": {
     ".": {
+      "test-node": {
+        "import": "./src/entry-node.ts"
+      },
+      "test-browser": {
+        "import": "./src/entry-browser.ts"
+      },
       "node": {
         "types": "./dist/node.d.ts",
         "import": "./dist/node.esm.js",
-        "require": "./dist/node.js"
+        "require": "./dist/node.cjs"
       },
       "default": {
         "types": "./dist/browser.d.ts",
         "import": "./dist/browser.esm.js",
-        "require": "./dist/browser.js"
+        "require": "./dist/browser.cjs"
       }
     },
     "./browser": {
       "types": "./dist/browser.d.ts",
       "import": "./dist/browser.esm.js",
-      "require": "./dist/browser.js"
+      "require": "./dist/browser.cjs"
     },
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.esm.js",
-      "require": "./dist/node.js"
+      "require": "./dist/node.cjs"
     },
     "./src": {
       "node": {
-        "types": "./src/async/node.ts",
-        "import": "./src/async/node.ts"
+        "types": "./src/entry-node.ts",
+        "import": "./src/entry-node.ts"
       },
       "default": {
-        "types": "./src/async/browser.ts",
-        "import": "./src/async/browser.ts"
+        "types": "./src/entry-browser.ts",
+        "import": "./src/entry-browser.ts"
       }
     },
     "./src/browser": {
-      "types": "./src/async/browser.ts",
-      "import": "./src/async/browser.ts"
+      "types": "./src/entry-browser.ts",
+      "import": "./src/entry-browser.ts"
     },
     "./src/node": {
-      "types": "./src/async/node.ts",
-      "import": "./src/async/node.ts"
+      "types": "./src/entry-node.ts",
+      "import": "./src/entry-node.ts"
     }
   },
   "files": [
@@ -59,14 +65,20 @@
     "build": "npm run build:js && npm run build:devtools",
     "build:watch": "rollup -c --watch",
     "prepublishOnly": "npm run build",
-    "test": "NODE_OPTIONS=--expose-gc jest",
-    "test:coverage": "NODE_OPTIONS=--expose-gc jest --coverage",
-    "test:coverage:watch": "NODE_OPTIONS=--expose-gc jest --coverage --watch",
-    "test:legacy": "TSCONFIG=tsconfig.legacy.json jest --detectOpenHandles --testPathPatterns=decorator",
-    "test:modern": "TSCONFIG=tsconfig.modern.json jest --detectOpenHandles --testPathPatterns=decorator",
-    "test:profile": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc jest --testPathPatterns=profiling",
-    "test:profile:benchmark": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc jest --testPathPatterns=profiling --testNamePattern=benchmark",
-    "test:profile:detailed": "RUN_PROFILING=1 node --prof node_modules/jest/bin/jest.js --testPathPatterns=profiling --no-coverage",
+    "test": "npm run test:node && npm run test:browser",
+    "test:node": "TEST_ENV=node NODE_OPTIONS='--expose-gc' vitest run",
+    "test:browser": "TEST_ENV=browser vitest run --browser",
+    "test:zone:node": "TEST_ENV=node vitest run tests/zone.test.ts",
+    "test:zone:browser": "TEST_ENV=browser vitest run tests/zone.test.ts",
+    "test:async:node": "TEST_ENV=node vitest run tests/async-hook.test.ts",
+    "test:async:browser": "TEST_ENV=browser vitest run tests/async-hook.test.ts",
+    "test:coverage": "TEST_ENV=node vitest run --coverage",
+    "test:coverage:watch": "TEST_ENV=node vitest run --coverage --watch",
+    "test:legacy": "TEST_ENV=node TSCONFIG=tsconfig.legacy.json vitest run --detectOpenHandles",
+    "test:modern": "TEST_ENV=node TSCONFIG=tsconfig.modern.json vitest run --detectOpenHandles",
+    "test:profile": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc vitest run",
+    "test:profile:benchmark": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc vitest run -t benchmark",
+    "test:profile:detailed": "RUN_PROFILING=1 node --prof node_modules/vitest/vitest.mjs --no-coverage",
     "benchmark:save": "tsx tests/profiling/benchmark.ts save",
     "benchmark:compare": "tsx tests/profiling/benchmark.ts compare",
     "benchmark:list": "tsx tests/profiling/benchmark.ts list",
@@ -102,25 +114,25 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.6",
-    "@jest/globals": "^30.2.0",
     "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.4",
-    "@types/jest": "^30.0.0",
     "@types/node": "^22.10.10",
-    "jest": "^30.0.4",
+    "@vitest/browser": "^4.0.18",
+    "@vitest/browser-playwright": "^4.0.18",
+    "playwright": "^1.58.1",
     "rollup": "^4.52.2",
     "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-dts": "^6.2.3",
     "rollup-plugin-typescript2": "^0.36.0",
-    "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
     "tsx": "^4.20.4",
     "typescript": "^5.8.3",
-    "vis-network": "^9.1.9"
+    "vis-network": "^9.1.9",
+    "vitest": "^4.0.18"
   },
   "packageManager": "pnpm@10.7.1+sha512.2d92c86b7928dc8284f53494fb4201f983da65f0fb4f0d40baafa5cf628fa31dae3e5968f12466f17df7e97310e30f343a648baea1b9b350685dafafffdf5808"
 }

package/src/async/browser.ts

@@ -1,6 +1,7 @@
 import { Hook, Restorer, asyncHooks } from '.'
 
 const hooks = new Set<Hook>()
+const promiseContexts = new WeakMap<Promise<any>, Set<Restorer>>()
 
 asyncHooks.addHook = function (hook: Hook) {
 	hooks.add(hook)
@@ -9,57 +10,288 @@ asyncHooks.addHook = function (hook: Hook) {
 	}
 }
 
-export * from '../index'
+// [HACK]: Sanitization
+// If a Promise is created inside the zone, it carries the "Sticky" zone context.
+// If returned to the outer scope, that context leaks. We wrap it in a new Promise
+// created here (in the outer scope) to break the chain and sanitize the return value.
+// See BROWSER_ASYNC_POLYFILL.md for full details.
+asyncHooks.sanitizePromise = (res: any) => {
+    if (res && typeof (res as any).then === 'function') {
+        return new Promise((resolve, reject) => {
+            setTimeout(() => {
+                (res as any).then(resolve, reject)
+            }, 0)
+        })
+    }
+    return res
+}
 
-function wrap<Args extends any[], R>(fn: ((...args: Args) => R) | null | undefined) {
-	if (typeof fn !== 'function') return fn
+function captureRestorers() {
 	const restorers = new Set<Restorer>()
-	for (const hook of hooks) restorers.add(hook())
+	for (const hook of hooks) {
+		const restorer = hook()
+		if (restorer) restorers.add(restorer)
+	}
+	return restorers
+}
 
+function wrap<Args extends any[], R>(fn: ((...args: Args) => R) | null | undefined, capturedRestorers?: Set<Restorer>) {
+	if (typeof fn !== 'function') return fn
+	const restorers = capturedRestorers || captureRestorers()
 	return function (this: any, ...args: Args) {
-		const undoers = new Set<() => void>()
-		for (const restore of restorers) undoers.add(restore())
+		const undoers: (() => void)[] = []
+		for (const restore of restorers) undoers.push(restore())
 		try {
 			return fn.apply(this, args)
 		} finally {
-			for (const undo of undoers) undo()
+			if (originals.queueMicrotask) {
+				// Double microtask ensures we run after the first await resumption microtask
+				originals.queueMicrotask.call(globalThis, () => {
+					originals.queueMicrotask.call(globalThis, () => {
+						originals.queueMicrotask.call(globalThis, () => {
+							for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
+						})
+					})
+				})
+			} else {
+				for (let i = undoers.length - 1; i >= 0; i--) undoers[i]()
+			}
 		}
 	}
 }
 
-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,
+const targetWrappers = new WeakMap<any, Map<string, WeakMap<Function, Function>>>()
+
+function patchEventTarget(proto: any) {
+	if (!proto || !proto.addEventListener || !proto.removeEventListener) return
+	const nativeAdd = proto.addEventListener
+	const nativeRemove = proto.removeEventListener
+
+	proto.addEventListener = function (this: any, type: string, listener: any, options: any) {
+		if (typeof listener !== 'function') {
+			return nativeAdd.call(this, type, listener, options)
+		}
+
+		let types = targetWrappers.get(this)
+		if (!types) {
+			types = new Map()
+			targetWrappers.set(this, types)
+		}
+		let listeners = types.get(type)
+		if (!listeners) {
+			listeners = new WeakMap()
+			types.set(type, listeners)
+		}
+
+		let wrapped = listeners.get(listener)
+		if (!wrapped) {
+			wrapped = wrap(listener)
+			listeners.set(listener, wrapped)
+		}
+		
+		return nativeAdd.call(this, type, wrapped, options)
+	}
+
+	proto.removeEventListener = function (this: any, type: string, listener: any, options: any) {
+		if (typeof listener !== 'function') {
+			return nativeRemove.call(this, type, listener, options)
+		}
+
+		const types = targetWrappers.get(this)
+		if (types) {
+			const listeners = types.get(type)
+			if (listeners) {
+				const wrapped = listeners.get(listener)
+				if (wrapped) {
+					return nativeRemove.call(this, type, wrapped, options)
+				}
+			}
+		}
+		
+		return nativeRemove.call(this, type, listener, options)
+	}
 }
 
-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))
+function patchOnProperties(proto: any) {
+	if (!proto) return
+	for (const prop of Object.getOwnPropertyNames(proto)) {
+		if (prop.startsWith('on')) {
+			const desc = Object.getOwnPropertyDescriptor(proto, prop)
+			if (desc && desc.set && desc.configurable) {
+				const nativeSet = desc.set
+				Object.defineProperty(proto, prop, {
+					...desc,
+					set: function (this: any, fn: any) {
+						nativeSet.call(this, wrap(fn))
+					}
+				})
+			}
+		}
+	}
 }
 
-Promise.prototype.catch = function <T>(
-	this: Promise<T>,
-	onRejected?: ((reason: any) => T | PromiseLike<T>) | null
-): Promise<T> {
-	return originals.catch.call(this, wrap(onRejected))
+if (typeof EventTarget !== 'undefined') {
+	patchEventTarget(EventTarget.prototype)
 }
 
-Promise.prototype.finally = function <T>(
-	this: Promise<T>,
-	onFinally?: (() => void) | null
-): Promise<T> {
-	return originals.finally.call(this, wrap(onFinally))
+const prototypesToPatch = [
+	typeof EventTarget !== 'undefined' && EventTarget.prototype,
+	typeof HTMLElement !== 'undefined' && HTMLElement.prototype,
+	typeof Window !== 'undefined' && Window.prototype,
+	typeof Document !== 'undefined' && Document.prototype,
+	typeof MessagePort !== 'undefined' && MessagePort.prototype,
+	typeof XMLHttpRequest !== 'undefined' && XMLHttpRequest.prototype,
+	typeof IDBRequest !== 'undefined' && IDBRequest.prototype,
+	typeof IDBTransaction !== 'undefined' && IDBTransaction.prototype,
+	typeof IDBDatabase !== 'undefined' && IDBDatabase.prototype,
+	typeof FileReader !== 'undefined' && FileReader.prototype,
+	typeof AbortSignal !== 'undefined' && AbortSignal.prototype,
+]
+
+for (const proto of prototypesToPatch) {
+	if (proto) {
+		patchOnProperties(proto)
+	}
 }
 
+const GLOBAL_ORIGINALS = Symbol.for('mutts.originals');
+const GLOBAL_PROMISE = Symbol.for('mutts.OriginalPromise');
+
+let originals: any;
+let OriginalPromise: any;
+
+if ((globalThis as any)[GLOBAL_ORIGINALS]) {
+    originals = (globalThis as any)[GLOBAL_ORIGINALS];
+    OriginalPromise = (globalThis as any)[GLOBAL_PROMISE];
+} else {
+    OriginalPromise = globalThis.Promise;
+    originals = {
+        then: OriginalPromise.prototype.then,
+        catch: OriginalPromise.prototype.catch,
+        finally: OriginalPromise.prototype.finally,
+        resolve: OriginalPromise.resolve,
+        reject: OriginalPromise.reject,
+        all: OriginalPromise.all,
+        allSettled: (OriginalPromise as any).allSettled,
+        race: OriginalPromise.race,
+        any: (OriginalPromise as any).any,
+        setTimeout: globalThis.setTimeout,
+        setInterval: globalThis.setInterval,
+        setImmediate: (globalThis as any).setImmediate,
+        requestAnimationFrame: (globalThis as any).requestAnimationFrame,
+        queueMicrotask: globalThis.queueMicrotask,
+    };
+    (globalThis as any)[GLOBAL_ORIGINALS] = originals;
+    (globalThis as any)[GLOBAL_PROMISE] = OriginalPromise;
+}
+
+// Ensure modern statics are captured even if originals was cached from an older version
+if (!originals.allSettled) originals.allSettled = (OriginalPromise as any).allSettled
+if (!originals.any) originals.any = (OriginalPromise as any).any
+if (!originals.race) originals.race = OriginalPromise.race
+
+function patchedThen(this: any, onFulfilled: any, onRejected: any) {
+	const context = promiseContexts.get(this) || captureRestorers()
+	const nextPromise = originals.then.call(this, wrap(onFulfilled, context), wrap(onRejected, context))
+	if (context.size > 0) promiseContexts.set(nextPromise, context)
+	return nextPromise
+}
+
+function patchedCatch(this: any, onRejected: any) {
+	const context = promiseContexts.get(this) || captureRestorers()
+	const nextPromise = originals.catch.call(this, wrap(onRejected, context))
+	if (context.size > 0) promiseContexts.set(nextPromise, context)
+	return nextPromise
+}
+
+function patchedFinally(this: any, onFinally: any) {
+	const context = promiseContexts.get(this) || captureRestorers()
+	const nextPromise = originals.finally.call(this, wrap(onFinally, context))
+	if (context.size > 0) promiseContexts.set(nextPromise, context)
+	return nextPromise
+}
+
+function PatchedPromise<T>(this: any, executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void) {
+    if (typeof executor === 'function') {
+        const p = new OriginalPromise((resolve, reject) => {
+            const wrappedResolve = wrap(resolve)
+            const wrappedReject = wrap(reject)
+            executor(wrappedResolve, wrappedReject)
+        })
+        const context = captureRestorers()
+        promiseContexts.set(p, context) // Always set, even if empty (Sticky Root)
+        return p
+    }
+    return new OriginalPromise(executor)
+}
+
+// Copy statics
+Object.assign(PatchedPromise, (OriginalPromise as any))
+
+// Inherit prototype for instanceof checks
+PatchedPromise.prototype = OriginalPromise.prototype
+
+PatchedPromise.resolve = function<T>(value?: T | PromiseLike<T>): Promise<T> {
+    const p = originals.resolve.call(OriginalPromise, value) as Promise<T>
+    const context = captureRestorers()
+    // Ensure we don't overwrite if it already has context (e.g. from constructor)
+    if (context.size > 0 && !promiseContexts.has(p)) promiseContexts.set(p, context)
+    return p
+} as any
+
+PatchedPromise.reject = function<T = never>(reason?: any): Promise<T> {
+    const p = originals.reject.call(OriginalPromise, reason) as Promise<T>
+    const context = captureRestorers()
+    if (context.size > 0) promiseContexts.set(p, context)
+    return p
+} as any
+
+PatchedPromise.all = function<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>[]> {
+    const p = originals.all.call(OriginalPromise, values) as Promise<Awaited<T>[]>
+    const context = captureRestorers()
+    if (context.size > 0) promiseContexts.set(p, context)
+    return p
+} as any
+
+PatchedPromise.allSettled = function<T>(values: Iterable<T | PromiseLike<T>>): Promise<PromiseSettledResult<Awaited<T>>[]> {
+    const p = (originals.allSettled as any).call(OriginalPromise, values)
+    const context = captureRestorers()
+    if (context.size > 0) promiseContexts.set(p, context)
+    return p
+} as any
+
+PatchedPromise.race = function<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>> {
+    const p = originals.race.call(OriginalPromise, values) as Promise<Awaited<T>>
+    const context = captureRestorers()
+    if (context.size > 0) promiseContexts.set(p, context)
+    return p
+} as any
+
+PatchedPromise.any = function<T>(values: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>> {
+    const p = (originals.any as any).call(OriginalPromise, values)
+    const context = captureRestorers()
+    if (context.size > 0) promiseContexts.set(p, context)
+    return p
+} as any
+
+// Only apply patches if not already applied (or re-apply safely)
+// Note: OriginalPromise.prototype might be shared if we used the global one.
+// We must ensure we don't patch it twice if it's the SAME object.
+if (OriginalPromise.prototype.then !== patchedThen) {
+    OriginalPromise.prototype.then = patchedThen as any
+    OriginalPromise.prototype.catch = patchedCatch as any
+    OriginalPromise.prototype.finally = patchedFinally as any
+}
+
+try {
+	Object.defineProperty(OriginalPromise, Symbol.species, {
+		get: () => PatchedPromise,
+		configurable: true
+	})
+} catch (e) {}
+
+;(globalThis as any).Promise = PatchedPromise
+
 globalThis.setTimeout = ((callback: Function, ...args: any[]) => {
 	return originals.setTimeout.call(globalThis, wrap(callback as any), ...args)
 }) as any
@@ -69,7 +301,7 @@ globalThis.setInterval = ((callback: Function, ...args: any[]) => {
 }) as any
 
 if (originals.setImmediate) {
-	globalThis.setImmediate = ((callback: Function, ...args: any[]) => {
+	;(globalThis as any).setImmediate = ((callback: Function, ...args: any[]) => {
 		return originals.setImmediate.call(globalThis, wrap(callback as any), ...args)
 	}) as any
 }
@@ -84,4 +316,4 @@ if (originals.queueMicrotask) {
 	globalThis.queueMicrotask = (callback: VoidFunction): void => {
 		originals.queueMicrotask.call(globalThis, wrap(callback))
 	}
-}
+}

package/src/async/index.ts

@@ -4,5 +4,20 @@ export type Hook = () => Restorer
 export const asyncHooks = {
 	addHook(_hook: Hook): () => void {
 		throw 'One must import the library from the server or the client side'
-	}
-}
+	},
+    /** 
+     * [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 {
+        return p
+    }
+}
+
+/**
+ * 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 const asyncHook = (hook: Hook) => asyncHooks.addHook(hook)