als-browser 1.0.0

package/src/patches/timers.test.ts

@@ -0,0 +1,321 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { AsyncLocalStorage } from "../async-local-storage";
+import { AsyncContextFrame } from "../async-context-frame";
+import { patchTimers } from "./timers";
+
+describe("Timers patch", () => {
+  let als: AsyncLocalStorage<number>;
+
+  beforeEach(() => {
+    AsyncContextFrame.set(undefined);
+    als = new AsyncLocalStorage<number>();
+    patchTimers();
+  });
+
+  describe("setTimeout", () => {
+    it("should preserve context through setTimeout", async () => {
+      const promise = new Promise<number | undefined>((resolve) => {
+        als.run(100, () => {
+          setTimeout(() => {
+            resolve(als.getStore());
+          }, 10);
+        });
+      });
+
+      const result = await promise;
+      expect(result).toBe(100);
+    });
+
+    it("should preserve context through chained setTimeout calls", async () => {
+      const sequence: number[] = [];
+
+      const promise = new Promise<void>((resolve) => {
+        als.run(200, () => {
+          sequence.push(als.getStore()!);
+          setTimeout(() => {
+            sequence.push(als.getStore()!);
+            setTimeout(() => {
+              sequence.push(als.getStore()!);
+              resolve();
+            }, 10);
+          }, 10);
+        });
+      });
+
+      await promise;
+      expect(sequence).toEqual([200, 200, 200]);
+    });
+
+    it("should isolate contexts in parallel setTimeout calls", async () => {
+      const results: number[] = [];
+
+      const promises = [1, 2, 3].map((value) => {
+        return new Promise<void>((resolve) => {
+          als.run(value, () => {
+            setTimeout(() => {
+              results.push(als.getStore()!);
+              resolve();
+            }, 10);
+          });
+        });
+      });
+
+      await Promise.all(promises);
+      expect(results.sort()).toEqual([1, 2, 3]);
+    });
+
+    it("should pass arguments to setTimeout callback", async () => {
+      const promise = new Promise<{ args: any[]; store: number | undefined }>(
+        (resolve) => {
+          als.run(300, () => {
+            setTimeout(
+              (a: number, b: string) => {
+                resolve({ args: [a, b], store: als.getStore() });
+              },
+              10,
+              42,
+              "test"
+            );
+          });
+        }
+      );
+
+      const result = await promise;
+      expect(result).toEqual({ args: [42, "test"], store: 300 });
+    });
+
+  });
+
+  describe("setInterval", () => {
+    it("should preserve context through setInterval", async () => {
+      const values: (number | undefined)[] = [];
+
+      const promise = new Promise<void>((resolve) => {
+        als.run(500, () => {
+          let count = 0;
+          const intervalId = setInterval(() => {
+            values.push(als.getStore());
+            count++;
+            if (count >= 3) {
+              clearInterval(intervalId);
+              resolve();
+            }
+          }, 10);
+        });
+      });
+
+      await promise;
+      expect(values).toEqual([500, 500, 500]);
+    });
+
+    it("should maintain same context across interval iterations", async () => {
+      const values: number[] = [];
+
+      const promise = new Promise<void>((resolve) => {
+        als.run(600, () => {
+          let count = 0;
+          const intervalId = setInterval(() => {
+            values.push(als.getStore()!);
+            count++;
+            if (count >= 5) {
+              clearInterval(intervalId);
+              resolve();
+            }
+          }, 5);
+        });
+      });
+
+      await promise;
+      expect(values).toEqual([600, 600, 600, 600, 600]);
+    });
+
+    it("should pass arguments to setInterval callback", async () => {
+      const promise = new Promise<{ args: any[]; store: number | undefined }>(
+        (resolve) => {
+          als.run(700, () => {
+            const intervalId = setInterval(
+              (a: number, b: string) => {
+                clearInterval(intervalId);
+                resolve({ args: [a, b], store: als.getStore() });
+              },
+              10,
+              99,
+              "interval"
+            );
+          });
+        }
+      );
+
+      const result = await promise;
+      expect(result).toEqual({ args: [99, "interval"], store: 700 });
+    });
+  });
+
+  describe("requestAnimationFrame", () => {
+    it("should preserve context through requestAnimationFrame", async () => {
+      if (!globalThis.requestAnimationFrame) {
+        return; // Skip if not available
+      }
+
+      const promise = new Promise<number | undefined>((resolve) => {
+        als.run(800, () => {
+          requestAnimationFrame(() => {
+            resolve(als.getStore());
+          });
+        });
+      });
+
+      const result = await promise;
+      expect(result).toBe(800);
+    });
+
+    it("should preserve context through chained requestAnimationFrame calls", async () => {
+      if (!globalThis.requestAnimationFrame) {
+        return; // Skip if not available
+      }
+
+      const sequence: number[] = [];
+
+      const promise = new Promise<void>((resolve) => {
+        als.run(900, () => {
+          sequence.push(als.getStore()!);
+          requestAnimationFrame(() => {
+            sequence.push(als.getStore()!);
+            requestAnimationFrame(() => {
+              sequence.push(als.getStore()!);
+              resolve();
+            });
+          });
+        });
+      });
+
+      await promise;
+      expect(sequence).toEqual([900, 900, 900]);
+    });
+
+    it("should receive timestamp parameter", async () => {
+      if (!globalThis.requestAnimationFrame) {
+        return; // Skip if not available
+      }
+
+      const promise = new Promise<{ timestamp: number; store: number | undefined }>(
+        (resolve) => {
+          als.run(1000, () => {
+            requestAnimationFrame((timestamp) => {
+              resolve({ timestamp, store: als.getStore() });
+            });
+          });
+        }
+      );
+
+      const result = await promise;
+      expect(result.store).toBe(1000);
+      expect(typeof result.timestamp).toBe("number");
+    });
+  });
+
+  describe("requestIdleCallback", () => {
+    it("should preserve context through requestIdleCallback", async () => {
+      if (!globalThis.requestIdleCallback) {
+        return; // Skip if not available
+      }
+
+      const promise = new Promise<number | undefined>((resolve) => {
+        als.run(1100, () => {
+          requestIdleCallback(() => {
+            resolve(als.getStore());
+          });
+        });
+      });
+
+      const result = await promise;
+      expect(result).toBe(1100);
+    });
+
+    it("should preserve context with timeout option", async () => {
+      if (!globalThis.requestIdleCallback) {
+        return; // Skip if not available
+      }
+
+      const promise = new Promise<number | undefined>((resolve) => {
+        als.run(1200, () => {
+          requestIdleCallback(
+            () => {
+              resolve(als.getStore());
+            },
+            { timeout: 100 }
+          );
+        });
+      });
+
+      const result = await promise;
+      expect(result).toBe(1200);
+    });
+
+    it("should receive deadline parameter", async () => {
+      if (!globalThis.requestIdleCallback) {
+        return; // Skip if not available
+      }
+
+      const promise = new Promise<{
+        hasDeadline: boolean;
+        store: number | undefined;
+      }>((resolve) => {
+        als.run(1300, () => {
+          requestIdleCallback((deadline) => {
+            resolve({
+              hasDeadline: deadline !== undefined,
+              store: als.getStore(),
+            });
+          });
+        });
+      });
+
+      const result = await promise;
+      expect(result.store).toBe(1300);
+      expect(result.hasDeadline).toBe(true);
+    });
+  });
+
+  describe("setImmediate", () => {
+    it("should preserve context through setImmediate if available", async () => {
+      if (!(globalThis as any).setImmediate) {
+        return; // Skip if not available
+      }
+
+      const promise = new Promise<number | undefined>((resolve) => {
+        als.run(1400, () => {
+          (globalThis as any).setImmediate(() => {
+            resolve(als.getStore());
+          });
+        });
+      });
+
+      const result = await promise;
+      expect(result).toBe(1400);
+    });
+
+    it("should pass arguments to setImmediate callback if available", async () => {
+      if (!(globalThis as any).setImmediate) {
+        return; // Skip if not available
+      }
+
+      const promise = new Promise<{ args: any[]; store: number | undefined }>(
+        (resolve) => {
+          als.run(1500, () => {
+            (globalThis as any).setImmediate(
+              (a: number, b: string) => {
+                resolve({ args: [a, b], store: als.getStore() });
+              },
+              77,
+              "immediate"
+            );
+          });
+        }
+      );
+
+      const result = await promise;
+      expect(result).toEqual({ args: [77, "immediate"], store: 1500 });
+    });
+  });
+});

package/src/patches/timers.ts

@@ -0,0 +1,109 @@
+import { AsyncLocalStorage } from "../async-local-storage";
+import { patch, unpatch } from "./patch-helper";
+
+/**
+ * Patch timer functions to preserve async context.
+ * This ensures that callbacks scheduled via setTimeout, setInterval, etc.
+ * maintain their async context when they execute.
+ */
+export function patchTimers(): void {
+  // Patch setTimeout
+  patch(
+    globalThis as any,
+    "setTimeout",
+    (original: typeof setTimeout) => {
+      return function (
+        callback: TimerHandler,
+        delay?: number,
+        ...args: any[]
+      ) {
+        const bound =
+          typeof callback === "function"
+            ? AsyncLocalStorage.bind(callback as (...args: any[]) => any)
+            : callback;
+        return original(bound, delay, ...args);
+      } as typeof setTimeout;
+    }
+  );
+
+  // Patch setInterval
+  patch(
+    globalThis as any,
+    "setInterval",
+    (original: typeof setInterval) => {
+      return function (
+        callback: TimerHandler,
+        delay?: number,
+        ...args: any[]
+      ) {
+        const bound =
+          typeof callback === "function"
+            ? AsyncLocalStorage.bind(callback as (...args: any[]) => any)
+            : callback;
+        return original(bound, delay, ...args);
+      } as typeof setInterval;
+    }
+  );
+
+  // Patch setImmediate (non-standard but available in some environments)
+  if ((globalThis as any).setImmediate) {
+    patch(
+      globalThis as any,
+      "setImmediate",
+      (original: any) => {
+        return function (callback: (...args: any[]) => void, ...args: any[]) {
+          const bound = AsyncLocalStorage.bind(callback);
+          return original(bound, ...args);
+        };
+      }
+    );
+  }
+
+  // Patch requestAnimationFrame
+  if (typeof (globalThis as any).requestAnimationFrame !== "undefined") {
+    patch(
+      globalThis as any,
+      "requestAnimationFrame",
+      (original: typeof requestAnimationFrame) => {
+        return function (callback: FrameRequestCallback) {
+          const bound = AsyncLocalStorage.bind(callback);
+          return original(bound);
+        };
+      }
+    );
+  }
+
+  // Patch requestIdleCallback
+  if (typeof (globalThis as any).requestIdleCallback !== "undefined") {
+    patch(
+      globalThis as any,
+      "requestIdleCallback",
+      (original: typeof requestIdleCallback) => {
+        return function (
+          callback: IdleRequestCallback,
+          options?: IdleRequestOptions
+        ) {
+          const bound = AsyncLocalStorage.bind(callback);
+          return original(bound, options);
+        };
+      }
+    );
+  }
+}
+
+/**
+ * Remove all timer patches, restoring original behavior.
+ */
+export function unpatchTimers(): void {
+  unpatch(globalThis as any, "setTimeout");
+  unpatch(globalThis as any, "setInterval");
+  if ((globalThis as any).setImmediate) {
+    unpatch(globalThis as any, "setImmediate");
+  }
+  if (typeof (globalThis as any).requestAnimationFrame !== "undefined") {
+    unpatch(globalThis as any, "requestAnimationFrame");
+  }
+  if (typeof (globalThis as any).requestIdleCallback !== "undefined") {
+    unpatch(globalThis as any, "requestIdleCallback");
+  }
+}

package/src/patches/xhr.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { AsyncLocalStorage } from "../async-local-storage";
+import { AsyncContextFrame } from "../async-context-frame";
+import { patchXHR } from "./xhr";
+
+describe("XMLHttpRequest patch", () => {
+  let als: AsyncLocalStorage<number>;
+
+  beforeEach(() => {
+    AsyncContextFrame.set(undefined);
+    als = new AsyncLocalStorage<number>();
+    patchXHR();
+  });
+
+  describe("on* event handler properties", () => {
+    it("should preserve context through onload property", () => {
+      if (typeof XMLHttpRequest === "undefined") {
+        return; // Skip if not available
+      }
+
+      let capturedValue: number | undefined;
+
+      als.run(100, () => {
+        const xhr = new XMLHttpRequest();
+
+        // Set onload handler inside the context
+        xhr.onload = () => {
+          capturedValue = als.getStore();
+        };
+
+        // Manually trigger the event to test context preservation
+        const event = new Event("load");
+        xhr.dispatchEvent(event);
+      });
+
+      expect(capturedValue).toBe(100);
+    });
+
+    it("should preserve context through onerror property", () => {
+      if (typeof XMLHttpRequest === "undefined") {
+        return; // Skip if not available
+      }
+
+      let capturedValue: number | undefined;
+
+      als.run(200, () => {
+        const xhr = new XMLHttpRequest();
+
+        xhr.onerror = () => {
+          capturedValue = als.getStore();
+        };
+
+        const event = new Event("error");
+        xhr.dispatchEvent(event);
+      });
+
+      expect(capturedValue).toBe(200);
+    });
+
+    it("should preserve context through onreadystatechange property", () => {
+      if (typeof XMLHttpRequest === "undefined") {
+        return; // Skip if not available
+      }
+
+      let capturedValue: number | undefined;
+
+      als.run(300, () => {
+        const xhr = new XMLHttpRequest();
+
+        xhr.onreadystatechange = () => {
+          capturedValue = als.getStore();
+        };
+
+        const event = new Event("readystatechange");
+        xhr.dispatchEvent(event);
+      });
+
+      expect(capturedValue).toBe(300);
+    });
+  });
+});

package/src/patches/xhr.ts

@@ -0,0 +1,58 @@
+import { AsyncLocalStorage } from "../async-local-storage";
+import { patch, unpatch } from "./patch-helper";
+
+const originalDescriptors = new Map<string, PropertyDescriptor>();
+
+/**
+ * Patch XMLHttpRequest to preserve async context.
+ * This ensures that XHR on* event handlers maintain their async context.
+ * Note: addEventListener is inherited from EventTarget and doesn't need patching here.
+ */
+export function patchXHR(): void {
+  if (!globalThis.XMLHttpRequest) return;
+
+  // Patch on* event handler properties
+  const eventProps = [
+    "onload",
+    "onerror",
+    "onabort",
+    "ontimeout",
+    "onprogress",
+    "onloadstart",
+    "onloadend",
+    "onreadystatechange",
+  ];
+
+  for (const prop of eventProps) {
+    const descriptor = Object.getOwnPropertyDescriptor(
+      XMLHttpRequest.prototype,
+      prop
+    );
+    if (descriptor?.set) {
+      // Store the original descriptor for unpatching
+      originalDescriptors.set(prop, descriptor);
+
+      const originalSet = descriptor.set;
+      Object.defineProperty(XMLHttpRequest.prototype, prop, {
+        ...descriptor,
+        set(handler: ((this: XMLHttpRequest, ev: any) => any) | null) {
+          const bound = handler ? AsyncLocalStorage.bind(handler) : null;
+          originalSet.call(this, bound);
+        },
+      });
+    }
+  }
+}
+
+/**
+ * Remove XMLHttpRequest patches, restoring original behavior.
+ */
+export function unpatchXHR(): void {
+  if (!globalThis.XMLHttpRequest) return;
+
+  // Restore original property descriptors for on* properties
+  originalDescriptors.forEach((descriptor, prop) => {
+    Object.defineProperty(XMLHttpRequest.prototype, prop, descriptor);
+  });
+  originalDescriptors.clear();
+}

package/src/snapshot.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { AsyncLocalStorage } from "./async-local-storage";
+import { AsyncContextFrame } from "./async-context-frame";
+import { capture, restore, SnapshotContainer } from "./snapshot";
+
+describe("snapshot (capture/restore)", () => {
+  let als: AsyncLocalStorage<number>;
+
+  beforeEach(() => {
+    // Reset the global context frame before each test
+    AsyncContextFrame.set(undefined);
+    als = new AsyncLocalStorage<number>();
+  });
+
+  it("should preserve context across simulated await", async () => {
+    const container: SnapshotContainer = {};
+
+    const promise = new Promise<number>((resolve) => {
+      als.run(777, async () => {
+        // Simulate: restore(container, await capture(container, promise))
+        const captured = capture(container, Promise.resolve(42));
+        const value = await captured;
+        const result = restore(container, value);
+
+        resolve(als.getStore()!);
+      });
+    });
+
+    const storeValue = await promise;
+    expect(storeValue).toBe(777);
+  });
+
+  it("should handle multiple sequential awaits", async () => {
+    const container: SnapshotContainer = {};
+    const results: (number | undefined)[] = [];
+
+    await als.run(888, async () => {
+      results.push(als.getStore());
+
+      // First await
+      restore(container, await capture(container, Promise.resolve()));
+      results.push(als.getStore());
+
+      // Second await
+      restore(container, await capture(container, Promise.resolve()));
+      results.push(als.getStore());
+    });
+
+    expect(results).toEqual([888, 888, 888]);
+  });
+
+  it("should work with actual async operations", async () => {
+    const container: SnapshotContainer = {};
+
+    const result = await als.run(999, async () => {
+      const delayedValue = new Promise<string>((resolve) => {
+        setTimeout(() => resolve("done"), 10);
+      });
+
+      restore(container, await capture(container, delayedValue));
+      return als.getStore();
+    });
+
+    expect(result).toBe(999);
+  });
+});

package/src/snapshot.ts

@@ -0,0 +1,38 @@
+import { AsyncContextFrame } from "./async-context-frame";
+
+/**
+ * Container object for storing async context snapshots around await points.
+ */
+export interface SnapshotContainer {
+  frame?: AsyncContextFrame;
+}
+
+/**
+ * Capture the current async context frame before an await.
+ * Stores the frame in the container and returns the promise unchanged.
+ *
+ * Usage: `restore(container, await capture(container, promise))`
+ */
+export function capture<T>(
+  container: SnapshotContainer,
+  promise: T
+): T {
+  container.frame = AsyncContextFrame.current();
+  return promise;
+}
+
+/**
+ * Restore the async context frame after an await.
+ * Retrieves the frame from the container, sets it as current, and returns the value unchanged.
+ *
+ * Usage: `restore(container, await capture(container, promise))`
+ */
+export function restore<T>(
+  container: SnapshotContainer,
+  value: T
+): T {
+  if (container.frame !== undefined) {
+    AsyncContextFrame.set(container.frame);
+  }
+  return value;
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "lib": ["es2022", "DOM"],
+    "target": "es2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["cjs", "esm"],
+  outDir: "dist",
+  dts: true,
+  platform: "browser",
+  clean: true,
+  sourcemap: true,
+  treeshake: true,
+});