als-browser 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test)",
+      "Bash(npm test:*)",
+      "Bash(npm run lint:*)",
+      "Bash(npm run typecheck:*)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,257 @@
+# als-browser
+
+Browser-compatible polyfill for Node.js's `AsyncLocalStorage` API. This package
+enables async context propagation in browser environments by patching common
+async browser APIs.
+
+## Features
+
+- Full `AsyncLocalStorage` API compatibility
+- Automatic patching of browser async APIs
+- Zero dependencies (dev dependencies only)
+- TypeScript support with full type definitions
+- ESM and CommonJS builds
+- Comprehensive test coverage
+
+## Installation
+
+```bash
+npm install als-browser
+# or
+pnpm add als-browser
+# or
+yarn add als-browser
+```
+
+## Usage
+
+```typescript
+import { AsyncLocalStorage } from 'als-browser';
+
+// Create a storage instance
+const requestContext = new AsyncLocalStorage<{ userId: string }>();
+
+// Use run() to execute code in a context
+requestContext.run({ userId: '123' }, () => {
+  console.log(requestContext.getStore()); // { userId: '123' }
+
+  // Context is preserved through setTimeout
+  setTimeout(() => {
+    console.log(requestContext.getStore()); // { userId: '123' }
+  }, 100);
+});
+```
+
+## API
+
+### `AsyncLocalStorage<T>`
+
+#### `constructor(options?)`
+
+```typescript
+const store = new AsyncLocalStorage<T>({
+  defaultValue?: T,  // Optional default value
+  name?: string      // Optional name for debugging
+});
+```
+
+#### `run(data, callback, ...args)`
+
+Run a function in a new async context with the given data.
+
+```typescript
+const result = store.run(myData, () => {
+  // Your code here
+  return store.getStore(); // Returns myData
+});
+```
+
+#### `getStore()`
+
+Get the current value from this store.
+
+```typescript
+const currentValue = store.getStore();
+```
+
+#### `enterWith(data)`
+
+Enter a new async context with the given data (no callback).
+
+```typescript
+store.enterWith(myData);
+console.log(store.getStore()); // myData
+```
+
+#### `exit(callback, ...args)`
+
+Run a function with the store value set to undefined.
+
+```typescript
+store.exit(() => {
+  console.log(store.getStore()); // undefined
+});
+```
+
+#### `disable()`
+
+Remove this store from the current async context.
+
+```typescript
+store.disable();
+```
+
+#### Static: `bind(fn)`
+
+Bind a function to the current async context.
+
+```typescript
+const boundFn = AsyncLocalStorage.bind(() => {
+  return store.getStore();
+});
+```
+
+#### Static: `snapshot()`
+
+Capture the current async context and return a function that can restore it.
+
+```typescript
+const snapshot = AsyncLocalStorage.snapshot();
+snapshot(() => {
+  // Runs in captured context
+});
+```
+
+### Manual Context Propagation
+
+For advanced use cases like code transformers or custom async instrumentation, you can manually capture and restore async context around `await` points.
+
+#### `capture(container, promise)`
+
+Capture the current async context frame before an await and store it in a container object.
+
+```typescript
+import { capture, restore, SnapshotContainer } from 'als-browser';
+
+const container: SnapshotContainer = {};
+const result = restore(container, await capture(container, promise));
+```
+
+#### `restore(container, value)`
+
+Restore the async context frame after an await from the container object.
+
+```typescript
+// Transform: await foo()
+// Into: restore(container, await capture(container, foo()))
+
+const container: SnapshotContainer = {};
+store.run(myData, async () => {
+  // Manually preserve context across await
+  restore(container, await capture(container, asyncOperation()));
+  console.log(store.getStore()); // myData is preserved
+});
+```
+
+These functions are primarily useful for:
+- Code transformers/compilers that automatically instrument async functions
+- Custom async context tracking systems
+- Debugging and understanding async context flow
+
+**Note**: For normal application code, prefer using the automatic patches or `AsyncLocalStorage.bind()`/`snapshot()`.
+
+## Patched Browser APIs
+
+The following browser APIs are automatically patched to preserve async context:
+
+### Timers
+- `setTimeout`
+- `setInterval`
+- `setImmediate` (if available)
+
+### Animation
+- `requestAnimationFrame`
+- `requestIdleCallback`
+
+### Network
+- `XMLHttpRequest` event handlers (addEventListener and on* properties)
+
+## How It Works
+
+This package implements Node.js's `AsyncContextFrame` model adapted for browsers:
+
+1. **AsyncContextFrame**: A Map-based storage for async context, stored in a module-level variable
+2. **AsyncLocalStorage**: The main API that stores and retrieves values from the current frame
+3. **Browser API Patches**: Automatically wraps callbacks to preserve context across async boundaries
+
+The implementation replaces Node.js's V8 embedder data APIs with a simple module-level variable, making it work in any JavaScript environment.
+
+## Limitations
+
+- **Promise-based APIs**: This package does not automatically patch promise-based APIs like `fetch()`. For those, you need to manually propagate context using `AsyncLocalStorage.bind()` or `AsyncLocalStorage.snapshot()`.
+- **EventTarget.addEventListener**: Only `XMLHttpRequest` is patched. Other event targets may need manual context propagation.
+- **Module-level state**: The context is stored in a module-level variable, which means it's shared across all code in the same JavaScript realm.
+
+## Example: Request Tracing
+
+```typescript
+import { AsyncLocalStorage } from 'als-browser';
+
+const requestId = new AsyncLocalStorage<string>();
+
+function generateId() {
+  return Math.random().toString(36).slice(2);
+}
+
+function log(message: string) {
+  const id = requestId.getStore() || 'no-context';
+  console.log(`[${id}] ${message}`);
+}
+
+// Start a request
+requestId.run(generateId(), async () => {
+  log('Request started');
+
+  // Context preserved through setTimeout
+  setTimeout(() => {
+    log('Async operation 1');
+  }, 100);
+
+  // Context preserved through requestAnimationFrame
+  requestAnimationFrame(() => {
+    log('Animation frame');
+  });
+
+  // For fetch, manually bind
+  const boundHandler = AsyncLocalStorage.bind(async () => {
+    const response = await fetch('/api/data');
+    log('Fetch completed');
+    return response.json();
+  });
+
+  await boundHandler();
+});
+```
+
+## Testing
+
+```bash
+# Run tests
+pnpm test
+
+# Build
+pnpm build
+
+# Type check
+pnpm typecheck
+```
+
+## License
+
+MIT
+
+## Credits
+
+This implementation is based on Node.js's `AsyncLocalStorage` and `AsyncContextFrame` APIs:
+- `lib/internal/async_context_frame.js`
+- `lib/internal/async_local_storage/async_context_frame.js`

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "als-browser",
+  "version": "1.0.0",
+  "description": "Browser polyfill for Node.js AsyncLocalStorage",
+  "author": "Stephen Belanger <admin@stephenbelanger.com>",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "module": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "happy-dom": "^12.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "async-local-storage",
+    "context",
+    "async-context",
+    "browser",
+    "polyfill"
+  ]
+}

package/src/async-context-frame.ts

@@ -0,0 +1,53 @@
+import type { AsyncLocalStorage } from "./async-local-storage";
+
+// Use a global Symbol to coordinate between ESM and CJS builds
+const CURRENT_FRAME_SYMBOL = Symbol.for("als-browser:currentFrame");
+
+/**
+ * AsyncContextFrame is a Map-based storage for async context.
+ * In Node.js, this uses V8's continuation preserved embedder data.
+ * In the browser, we use a global Symbol to coordinate between ESM/CJS builds.
+ */
+export class AsyncContextFrame extends Map<AsyncLocalStorage<any>, any> {
+  constructor(store: AsyncLocalStorage<any>, data: any) {
+    super(AsyncContextFrame.current());
+    this.set(store, data);
+  }
+
+  disable(store:  AsyncLocalStorage<any>) {
+    this.delete(store);
+  }
+
+  /**
+   * Get the current async context frame.
+   */
+  static current(): AsyncContextFrame | undefined {
+    return (globalThis as any)[CURRENT_FRAME_SYMBOL];
+  }
+
+  /**
+   * Set the current async context frame.
+   */
+  static set(frame: AsyncContextFrame | undefined): void {
+    (globalThis as any)[CURRENT_FRAME_SYMBOL] = frame;
+  }
+
+  /**
+   * Exchange the current frame with a new one, returning the previous frame.
+   */
+  static exchange(
+    frame: AsyncContextFrame | undefined
+  ): AsyncContextFrame | undefined {
+    const prior = this.current();
+    this.set(frame);
+    return prior;
+  }
+
+  /**
+   * Disable (remove) a specific store from the current frame.
+   */
+  static disable(store: AsyncLocalStorage<any>): void {
+    const frame = this.current();
+    frame?.disable(store);
+  }
+}

package/src/async-local-storage.test.ts

@@ -0,0 +1,264 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { AsyncLocalStorage } from "./index";
+import { AsyncContextFrame } from "./async-context-frame";
+
+describe("AsyncLocalStorage", () => {
+  let als: AsyncLocalStorage<number>;
+
+  beforeEach(() => {
+    // Reset the global context frame before each test
+    AsyncContextFrame.set(undefined);
+    als = new AsyncLocalStorage<number>();
+  });
+
+  describe("Basic API", () => {
+    it("should return undefined when no store is set", () => {
+      expect(als.getStore()).toBeUndefined();
+    });
+
+    it("should return default value when configured", () => {
+      const alsWithDefault = new AsyncLocalStorage<number>({
+        defaultValue: 42,
+      });
+      expect(alsWithDefault.getStore()).toBe(42);
+    });
+
+    it("should support name option", () => {
+      const namedAls = new AsyncLocalStorage<number>({ name: "test-store" });
+      expect(namedAls.name).toBe("test-store");
+    });
+
+    it("should preserve context in run()", () => {
+      const result = als.run(123, () => {
+        return als.getStore();
+      });
+      expect(result).toBe(123);
+    });
+
+    it("should restore context after run() completes", () => {
+      expect(als.getStore()).toBeUndefined();
+      als.run(123, () => {
+        expect(als.getStore()).toBe(123);
+      });
+      expect(als.getStore()).toBeUndefined();
+    });
+
+    it("should handle nested run() calls", () => {
+      als.run(1, () => {
+        expect(als.getStore()).toBe(1);
+        als.run(2, () => {
+          expect(als.getStore()).toBe(2);
+          als.run(3, () => {
+            expect(als.getStore()).toBe(3);
+          });
+          expect(als.getStore()).toBe(2);
+        });
+        expect(als.getStore()).toBe(1);
+      });
+      expect(als.getStore()).toBeUndefined();
+    });
+
+    it("should support enterWith()", () => {
+      expect(als.getStore()).toBeUndefined();
+      als.enterWith(456);
+      expect(als.getStore()).toBe(456);
+      als.enterWith(789);
+      expect(als.getStore()).toBe(789);
+    });
+
+    it("should support exit()", () => {
+      als.enterWith(100);
+      expect(als.getStore()).toBe(100);
+      const result = als.exit(() => {
+        expect(als.getStore()).toBeUndefined();
+        return "exited";
+      });
+      expect(result).toBe("exited");
+      expect(als.getStore()).toBe(100);
+    });
+
+    it("should support disable()", () => {
+      als.enterWith(200);
+      expect(als.getStore()).toBe(200);
+      als.disable();
+      expect(als.getStore()).toBeUndefined();
+    });
+  });
+
+  describe("Static methods", () => {
+    it("should bind function to current context", () => {
+      let capturedValue: number | undefined;
+
+      als.run(999, () => {
+        const bound = AsyncLocalStorage.bind(() => {
+          capturedValue = als.getStore();
+        });
+
+        // Call bound function outside of run context
+        AsyncContextFrame.set(undefined);
+        bound();
+      });
+
+      expect(capturedValue).toBe(999);
+    });
+
+    it("should preserve 'this' context in bound functions", () => {
+      const obj = {
+        value: 42,
+        getValue(this: { value: number }) {
+          return this.value;
+        },
+      };
+
+      const bound = AsyncLocalStorage.bind(obj.getValue);
+      expect(bound.call(obj)).toBe(42);
+    });
+
+    it("should support snapshot()", () => {
+      const snapshot = als.run(555, () => {
+        return AsyncLocalStorage.snapshot();
+      });
+
+      // Run snapshot outside of original context
+      AsyncContextFrame.set(undefined);
+      const result = snapshot(() => {
+        return als.getStore();
+      });
+
+      expect(result).toBe(555);
+    });
+  });
+
+
+  describe("Multiple stores", () => {
+    it("should isolate different AsyncLocalStorage instances", () => {
+      const als1 = new AsyncLocalStorage<string>();
+      const als2 = new AsyncLocalStorage<number>();
+
+      als1.run("hello", () => {
+        als2.run(42, () => {
+          expect(als1.getStore()).toBe("hello");
+          expect(als2.getStore()).toBe(42);
+        });
+      });
+    });
+
+    it("should handle nested runs with multiple stores", () => {
+      const als1 = new AsyncLocalStorage<string>();
+      const als2 = new AsyncLocalStorage<number>();
+
+      als1.run("outer", () => {
+        als2.run(1, () => {
+          expect(als1.getStore()).toBe("outer");
+          expect(als2.getStore()).toBe(1);
+
+          als1.run("inner", () => {
+            als2.run(2, () => {
+              expect(als1.getStore()).toBe("inner");
+              expect(als2.getStore()).toBe(2);
+            });
+            expect(als1.getStore()).toBe("inner");
+            expect(als2.getStore()).toBe(1);
+          });
+
+          expect(als1.getStore()).toBe("outer");
+          expect(als2.getStore()).toBe(1);
+        });
+      });
+    });
+  });
+
+  describe("Edge cases", () => {
+    it("should handle run() with same value as current", () => {
+      als.enterWith(777);
+      const callCount = { count: 0 };
+
+      als.run(777, () => {
+        callCount.count++;
+        expect(als.getStore()).toBe(777);
+      });
+
+      expect(callCount.count).toBe(1);
+    });
+
+    it("should pass arguments to run() callback", () => {
+      const result = als.run(
+        100,
+        (a: number, b: string, c: boolean) => {
+          return { a, b, c, store: als.getStore() };
+        },
+        1,
+        "test",
+        true
+      );
+
+      expect(result).toEqual({ a: 1, b: "test", c: true, store: 100 });
+    });
+
+    it("should pass arguments to exit() callback", () => {
+      const result = als.exit(
+        (x: number, y: number) => {
+          return x + y;
+        },
+        5,
+        10
+      );
+
+      expect(result).toBe(15);
+    });
+
+    it("should handle undefined as a valid store value", () => {
+      als.run(undefined as any, () => {
+        expect(als.getStore()).toBeUndefined();
+      });
+    });
+
+    it("should handle null as a valid store value", () => {
+      const alsNull = new AsyncLocalStorage<string | null>();
+      alsNull.run(null, () => {
+        expect(alsNull.getStore()).toBeNull();
+      });
+    });
+  });
+
+  describe("Context propagation", () => {
+    it("should propagate through chained setTimeout calls", async () => {
+      const sequence: number[] = [];
+
+      const promise = new Promise<void>((resolve) => {
+        als.run(1, () => {
+          sequence.push(als.getStore()!);
+          setTimeout(() => {
+            sequence.push(als.getStore()!);
+            setTimeout(() => {
+              sequence.push(als.getStore()!);
+              resolve();
+            }, 10);
+          }, 10);
+        });
+      });
+
+      await promise;
+      expect(sequence).toEqual([1, 1, 1]);
+    });
+
+    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]);
+    });
+  });
+
+});