@warlock.js/context 4.0.39

package/README.md

@@ -0,0 +1,343 @@
+# @warlock.js/context
+
+A lightweight, type-safe context management library built on Node.js's `AsyncLocalStorage`. Provides a simple and unified way to share context across async operations in your applications.
+
+Part of the [Warlock.js](https://github.com/warlockjs) ecosystem.
+
+## Features
+
+- 🚀 **Simple API** - Intuitive methods for context management
+- 🔒 **Type-safe** - Full TypeScript support with generics
+- 🔗 **Chainable** - Fluent API for registering multiple contexts
+- 🎯 **Extensible** - Abstract base class for custom context implementations
+- 📦 **Zero dependencies** - Only uses Node.js built-in `AsyncLocalStorage`
+- 🔄 **Multi-context support** - Orchestrate multiple contexts together
+
+## Installation
+
+```bash
+npm install @warlock.js/context
+```
+
+```bash
+yarn add @warlock.js/context
+```
+
+```bash
+pnpm add @warlock.js/context
+```
+
+## Quick Start
+
+### Creating a Custom Context
+
+Extend the `Context` abstract class to create your own typed context:
+
+```typescript
+import { Context, contextManager } from "@warlock.js/context";
+
+// Define your store type
+interface UserContextStore {
+  userId: string;
+  role: "admin" | "user";
+  tenantId: string;
+}
+
+// Create your context class
+class UserContext extends Context<UserContextStore> {
+  /**
+   * Called when contextManager executese buildStores()
+   */
+  public buildStore(payload?: Record<string, any>): UserContextStore {
+    // Initialize from payload or defaults
+    return {
+      userId: payload?.userId ?? "",
+      role: payload?.role ?? "user",
+      tenantId: payload?.tenantId ?? "",
+    };
+  }
+}
+
+// Create a singleton instance
+export const userContext = new UserContext();
+// register it in the context manager
+contextManager.register("user", userContext);
+```
+
+### Using the Context
+
+#### With `run()` - Scoped execution
+
+```typescript
+await userContext.run(
+  { userId: "123", role: "admin", tenantId: "acme" },
+  async () => {
+    // Context is available throughout this async scope
+    const userId = userContext.get("userId"); // '123'
+    const role = userContext.get("role"); // 'admin'
+
+    await someAsyncOperation(); // Context propagates through async calls
+  }
+);
+```
+
+#### With `enter()` - Middleware-style
+
+```typescript
+// In your middleware
+function authMiddleware(req, res, next) {
+  userContext.enter({
+    userId: req.user.id,
+    role: req.user.role,
+    tenantId: req.headers["x-tenant-id"],
+  });
+
+  next(); // Context is available for the rest of the request
+}
+```
+
+### Managing Multiple Contexts
+
+Use the global `contextManager` to orchestrate multiple contexts together:
+
+```typescript
+import { Context, contextManager } from "@warlock.js/context";
+
+// Define your contexts
+class RequestContext extends Context<{ requestId: string; path: string }> {
+  /**
+   * Called when contextManager executese buildStores()
+   */
+  public buildStore(payload?: Record<string, any>) {
+    return { requestId: payload?.requestId ?? "", path: payload?.path ?? "" };
+  }
+}
+
+class DatabaseContext extends Context<{ dataSource: string }> {
+  /**
+   * Called when contextManager executese buildStores()
+   */
+  public buildStore(payload?: Record<string, any>) {
+    return { dataSource: payload?.dataSource ?? "primary" };
+  }
+}
+
+// Create instances and register them immediately
+export const requestContext = new RequestContext();
+contextManager.register("request", requestContext);
+
+export const databaseContext = new DatabaseContext();
+contextManager.register("database", databaseContext);
+
+// Build stores first - each context's buildStore() is called with the payload
+const stores = contextManager.buildStores({
+  requestId: "req-123",
+  path: "/api/users",
+  dataSource: "replica",
+});
+
+// Run all contexts together
+await contextManager.runAll(stores, async () => {
+  // All contexts are active!
+  const reqId = requestContext.get("requestId"); // 'req-123'
+  const ds = databaseContext.get("dataSource"); // 'replica'
+});
+```
+
+## API Reference
+
+### `Context<TStore>` (Abstract Class)
+
+The base class for all context implementations.
+
+#### Methods
+
+| Method                                                          | Description                                              |
+| --------------------------------------------------------------- | -------------------------------------------------------- |
+| `run<T>(store: TStore, callback: () => Promise<T>): Promise<T>` | Execute a callback within a new context scope            |
+| `enter(store: TStore): void`                                    | Enter a context without a callback (middleware-style)    |
+| `update(updates: Partial<TStore>): void`                        | Merge new data into the current context                  |
+| `getStore(): TStore \| undefined`                               | Get the entire current context store                     |
+| `get<K extends keyof TStore>(key: K): TStore[K] \| undefined`   | Get a specific value from context                        |
+| `set<K extends keyof TStore>(key: K, value: TStore[K]): void`   | Set a specific value in context                          |
+| `clear(): void`                                                 | Clear the current context                                |
+| `hasContext(): boolean`                                         | Check if currently within a context                      |
+| `buildStore(payload?: Record<string, any>): TStore`             | **Abstract** - Override to provide custom initialization |
+
+### `ContextManager`
+
+Orchestrates multiple contexts together.
+
+#### Methods
+
+| Method                                                                           | Description                                                      |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `register(name: string, context: Context<any>): this`                            | Register a context with a unique name                            |
+| `unregister(name: string): boolean`                                              | Remove a registered context                                      |
+| `runAll<T>(stores: Record<string, any>, callback: () => Promise<T>): Promise<T>` | Run all contexts together                                        |
+| `enterAll(stores: Record<string, any>): void`                                    | Enter all contexts at once                                       |
+| `clearAll(): void`                                                               | Clear all contexts                                               |
+| `buildStores(payload?: Record<string, any>): Record<string, any>`                | Build stores for all contexts using their `buildStore()` methods |
+| `getContext<T>(name: string): T \| undefined`                                    | Get a registered context by name                                 |
+| `hasContext(name: string): boolean`                                              | Check if a context is registered                                 |
+
+### Global Context Manager
+
+A pre-configured singleton is exported for convenience:
+
+```typescript
+import { contextManager } from "@warlock.js/context";
+
+contextManager.register("myContext", myContextInstance);
+```
+
+## Real-World Examples
+
+### Multi-Tenant Application
+
+```typescript
+import { Context, contextManager } from "@warlock.js/context";
+
+interface TenantStore {
+  tenantId: string;
+  tenantName: string;
+  config: Record<string, any>;
+}
+
+class TenantContext extends Context<TenantStore> {
+  /**
+   * Called when contextManager executese buildStores()
+   */
+  public buildStore(payload?: Record<string, any>): TenantStore {
+    return {
+      tenantId: payload?.tenantId ?? "",
+      tenantName: payload?.tenantName ?? "",
+      config: payload?.config ?? {},
+    };
+  }
+
+  // Convenience getters
+  public get tenantId() {
+    return this.get("tenantId");
+  }
+
+  public get config() {
+    return this.get("config");
+  }
+}
+
+export const tenantContext = new TenantContext();
+
+// In your middleware
+app.use(async (req, res, next) => {
+  const tenant = await getTenantFromRequest(req);
+
+  tenantContext.enter({
+    tenantId: tenant.id,
+    tenantName: tenant.name,
+    config: tenant.config,
+  });
+
+  next();
+});
+
+// Anywhere in your application
+function getDatabaseConnection() {
+  const tenantId = tenantContext.tenantId;
+  return getConnectionForTenant(tenantId);
+}
+```
+
+### Request Tracing
+
+```typescript
+import { Context } from "@warlock.js/context";
+import { randomUUID } from "crypto";
+
+interface TraceStore {
+  traceId: string;
+  spanId: string;
+  startTime: number;
+}
+
+class TraceContext extends Context<TraceStore> {
+  /**
+   * Called when contextManager executese buildStores()
+   */
+  public buildStore(): TraceStore {
+    return {
+      traceId: randomUUID(),
+      spanId: randomUUID(),
+      startTime: Date.now(),
+    };
+  }
+
+  public get traceId() {
+    return this.get("traceId");
+  }
+
+  public log(message: string) {
+    const store = this.getStore();
+    console.log(`[${store?.traceId}] ${message}`);
+  }
+}
+
+export const traceContext = new TraceContext();
+
+// Usage
+app.use((req, res, next) => {
+  const stores = { trace: traceContext.buildStore() };
+
+  traceContext.run(stores.trace, async () => {
+    traceContext.log(`Request started: ${req.path}`);
+    await next();
+    traceContext.log(
+      `Request completed in ${Date.now() - stores.trace.startTime}ms`
+    );
+  });
+});
+```
+
+### Combining with ContextManager
+
+```typescript
+import { contextManager } from "@warlock.js/context";
+import { requestContext } from "./request-context";
+import { traceContext } from "./trace-context";
+import { tenantContext } from "./tenant-context";
+
+// Register all contexts at app startup
+contextManager
+  .register("request", requestContext)
+  .register("trace", traceContext)
+  .register("tenant", tenantContext);
+
+// In your request handler
+app.use(async (req, res, next) => {
+  // Build all stores from the request payload
+  const stores = contextManager.buildStores({
+    request: req,
+    response: res,
+    tenantId: req.headers["x-tenant-id"],
+  });
+
+  // Run all contexts together
+  await contextManager.runAll(stores, async () => {
+    await next();
+  });
+});
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0 (for development)
+
+## License
+
+MIT © [hassanzohdy](https://github.com/hassanzohdy)
+
+## Related Packages
+
+- [@warlock.js/core](https://github.com/warlockjs/core) - Core Warlock.js framework
+- [Warlock.js](https://github.com/warlockjs) - Full-featured Node.js framework

package/cjs/index.js

@@ -0,0 +1,2 @@
+'use strict';var async_hooks=require('async_hooks');var s=class{storage=new async_hooks.AsyncLocalStorage;run(t,e){return this.storage.run(t,e)}enter(t){this.storage.enterWith(t);}update(t){let e=this.storage.getStore();e?Object.assign(e,t):this.enter(t);}getStore(){return this.storage.getStore()}get(t){return this.storage.getStore()?.[t]}set(t,e){this.update({[t]:e});}clear(){this.storage.enterWith({});}hasContext(){return this.storage.getStore()!==void 0}};var n=class{contexts=new Map;register(t,e){return this.contexts.set(t,e),this}async runAll(t,e){return Array.from(this.contexts.entries()).reduceRight((c,[a,u])=>()=>u.run(t[a]||{},c),e)()}enterAll(t){for(let[e,r]of this.contexts.entries())t[e]&&r.enter(t[e]);}clearAll(){for(let t of this.contexts.values())t.clear();}getContext(t){return this.contexts.get(t)}hasContext(t){return this.contexts.has(t)}buildStores(t){let e={};for(let[r,o]of this.contexts.entries())e[r]=o.buildStore(t)??{};return e}unregister(t){return this.contexts.delete(t)}},p=new n;exports.Context=s;exports.ContextManager=n;exports.contextManager=p;//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../warlock.js/context/src/base-context.ts","../../../../../../../warlock.js/context/src/context-manager.ts"],"names":["Context","AsyncLocalStorage","store","callback","updates","current","key","value","ContextManager","name","context","stores","next","payload","contextManager"],"mappings":"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","file":"index.js","sourcesContent":["import { AsyncLocalStorage } from \"async_hooks\";\n\n/**\n * Base class for all AsyncLocalStorage-based contexts\n *\n * Provides a consistent API for managing context across async operations.\n * All framework contexts (request, storage, database) extend this class.\n *\n * @template TStore - The type of data stored in context\n *\n * @example\n * ```typescript\n * interface MyContextStore {\n *   userId: string;\n *   tenant: string;\n * }\n *\n * class MyContext extends Context<MyContextStore> {}\n * const myContext = new MyContext();\n *\n * // Use it\n * await myContext.run({ userId: '123', tenant: 'acme' }, async () => {\n *   const userId = myContext.get('userId'); // '123'\n * });\n * ```\n */\nexport abstract class Context<TStore extends Record<string, any>> {\n  protected readonly storage: AsyncLocalStorage<TStore> = new AsyncLocalStorage<TStore>();\n\n  /**\n   * Run a callback within a new context\n   *\n   * Creates a new async context with the provided store data.\n   * All operations within the callback will have access to this context.\n   *\n   * @param store - Initial context data\n   * @param callback - Async function to execute\n   * @returns Result of the callback\n   */\n  public run<T>(store: TStore, callback: () => Promise<T>): Promise<T> {\n    return this.storage.run(store, callback);\n  }\n\n  /**\n   * Enter a new context without a callback\n   *\n   * Useful for middleware where you want to set context for the rest of the request.\n   * Unlike `run()`, this doesn't require a callback.\n   *\n   * @param store - Context data to set\n   */\n  public enter(store: TStore): void {\n    this.storage.enterWith(store);\n  }\n\n  /**\n   * Update the current context\n   *\n   * Merges new data into existing context, or enters new context if none exists.\n   *\n   * @param updates - Partial context data to merge\n   */\n  public update(updates: Partial<TStore>): void {\n    const current = this.storage.getStore();\n\n    if (current) {\n      Object.assign(current, updates);\n    } else {\n      this.enter(updates as TStore);\n    }\n  }\n\n  /**\n   * Get the current context store\n   *\n   * @returns Current context or undefined if not in context\n   */\n  public getStore(): TStore | undefined {\n    return this.storage.getStore();\n  }\n\n  /**\n   * Get a specific value from context\n   *\n   * @param key - Key to retrieve\n   * @returns Value or undefined\n   */\n  public get<K extends keyof TStore>(key: K): TStore[K] | undefined {\n    return this.storage.getStore()?.[key];\n  }\n\n  /**\n   * Set a specific value in context\n   *\n   * @param key - Key to set\n   * @param value - Value to store\n   */\n  public set<K extends keyof TStore>(key: K, value: TStore[K]): void {\n    this.update({ [key]: value } as any);\n  }\n\n  /**\n   * Clear the context\n   */\n  public clear(): void {\n    this.storage.enterWith({} as TStore);\n  }\n\n  /**\n   * Check if currently in a context\n   */\n  public hasContext(): boolean {\n    return this.storage.getStore() !== undefined;\n  }\n\n  /**\n   * Build the initial store for this context\n   *\n   * Override this method to provide custom initialization logic.\n   * Called by ContextManager.buildStores() for each registered context.\n   *\n   * @param payload - Generic payload (e.g., { request, response } for HTTP contexts)\n   * @returns Initial store data\n   */\n  public abstract buildStore(payload?: Record<string, any>): TStore;\n}\n","import type { Context } from \"./base-context\";\n\n/**\n * Context Manager - Orchestrates multiple contexts together\n *\n * Allows running multiple AsyncLocalStorage contexts in a single operation,\n * making it easy to link request, storage, database, and other contexts.\n *\n * @example\n * ```typescript\n * // Register contexts\n * contextManager\n *   .register('request', requestContext)\n *   .register('storage', storageDriverContext)\n *   .register('database', databaseDataSourceContext);\n *\n * // Run all contexts together\n * await contextManager.runAll({\n *   request: { request, response, user },\n *   storage: { driver, metadata: { tenantId: '123' } },\n *   database: { dataSource: 'primary' },\n * }, async () => {\n *   // All contexts active!\n *   await handleRequest();\n * });\n * ```\n */\nexport class ContextManager {\n  private contexts = new Map<string, Context<any>>();\n\n  /**\n   * Register a context\n   *\n   * @param name - Unique context name\n   * @param context - Context instance\n   * @returns This instance for chaining\n   */\n  public register(name: string, context: Context<any>): this {\n    this.contexts.set(name, context);\n    return this;\n  }\n\n  /**\n   * Run all registered contexts together\n   *\n   * Nests all context.run() calls, ensuring all contexts are active\n   * for the duration of the callback.\n   *\n   * @param stores - Context stores keyed by context name\n   * @param callback - Async function to execute\n   * @returns Result of the callback\n   */\n  public async runAll<T>(stores: Record<string, any>, callback: () => Promise<T>): Promise<T> {\n    const entries = Array.from(this.contexts.entries());\n\n    // Build nested context runners\n    const runner = entries.reduceRight((next, [name, context]) => {\n      return () => context.run(stores[name] || {}, next);\n    }, callback);\n\n    return runner();\n  }\n\n  /**\n   * Enter all contexts at once (for middleware)\n   *\n   * @param stores - Context stores keyed by context name\n   */\n  public enterAll(stores: Record<string, any>): void {\n    for (const [name, context] of this.contexts.entries()) {\n      if (stores[name]) {\n        context.enter(stores[name]);\n      }\n    }\n  }\n\n  /**\n   * Clear all contexts\n   */\n  public clearAll(): void {\n    for (const context of this.contexts.values()) {\n      context.clear();\n    }\n  }\n\n  /**\n   * Get a specific registered context\n   *\n   * @param name - Context name\n   * @returns Context instance or undefined\n   */\n  public getContext<T extends Context<any>>(name: string): T | undefined {\n    return this.contexts.get(name) as T | undefined;\n  }\n\n  /**\n   * Check if a context is registered\n   *\n   * @param name - Context name\n   * @returns True if context is registered\n   */\n  public hasContext(name: string): boolean {\n    return this.contexts.has(name);\n  }\n\n  /**\n   * Build all context stores by calling each context's buildStore() method\n   *\n   * This is the immutable pattern - returns a new record of stores.\n   * Each context defines its own initialization logic.\n   *\n   * @param payload - Payload passed to each buildStore() (e.g., { request, response })\n   * @returns Record of context name -> store data\n   *\n   * @example\n   * ```typescript\n   * const httpContextStore = contextManager.buildStores({ request, response });\n   * await contextManager.runAll(httpContextStore, async () => { ... });\n   * ```\n   */\n  public buildStores(payload?: Record<string, any>): Record<string, any> {\n    const stores: Record<string, any> = {};\n\n    for (const [name, context] of this.contexts.entries()) {\n      stores[name] = context.buildStore(payload) ?? {};\n    }\n\n    return stores;\n  }\n\n  /**\n   * Unregister a context\n   *\n   * @param name - Context name to remove\n   * @returns True if context was removed\n   */\n  public unregister(name: string): boolean {\n    return this.contexts.delete(name);\n  }\n}\n\n/**\n * Global context manager instance\n *\n * Use this singleton to register and manage all framework contexts.\n */\nexport const contextManager = new ContextManager();\n"]}

package/esm/index.js

@@ -0,0 +1,2 @@
+import {AsyncLocalStorage}from'async_hooks';var s=class{storage=new AsyncLocalStorage;run(t,e){return this.storage.run(t,e)}enter(t){this.storage.enterWith(t);}update(t){let e=this.storage.getStore();e?Object.assign(e,t):this.enter(t);}getStore(){return this.storage.getStore()}get(t){return this.storage.getStore()?.[t]}set(t,e){this.update({[t]:e});}clear(){this.storage.enterWith({});}hasContext(){return this.storage.getStore()!==void 0}};var n=class{contexts=new Map;register(t,e){return this.contexts.set(t,e),this}async runAll(t,e){return Array.from(this.contexts.entries()).reduceRight((c,[a,u])=>()=>u.run(t[a]||{},c),e)()}enterAll(t){for(let[e,r]of this.contexts.entries())t[e]&&r.enter(t[e]);}clearAll(){for(let t of this.contexts.values())t.clear();}getContext(t){return this.contexts.get(t)}hasContext(t){return this.contexts.has(t)}buildStores(t){let e={};for(let[r,o]of this.contexts.entries())e[r]=o.buildStore(t)??{};return e}unregister(t){return this.contexts.delete(t)}},p=new n;export{s as Context,n as ContextManager,p as contextManager};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../warlock.js/context/src/base-context.ts","../../../../../../../warlock.js/context/src/context-manager.ts"],"names":["Context","AsyncLocalStorage","store","callback","updates","current","key","value","ContextManager","name","context","stores","next","payload","contextManager"],"mappings":"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","file":"index.js","sourcesContent":["import { AsyncLocalStorage } from \"async_hooks\";\n\n/**\n * Base class for all AsyncLocalStorage-based contexts\n *\n * Provides a consistent API for managing context across async operations.\n * All framework contexts (request, storage, database) extend this class.\n *\n * @template TStore - The type of data stored in context\n *\n * @example\n * ```typescript\n * interface MyContextStore {\n *   userId: string;\n *   tenant: string;\n * }\n *\n * class MyContext extends Context<MyContextStore> {}\n * const myContext = new MyContext();\n *\n * // Use it\n * await myContext.run({ userId: '123', tenant: 'acme' }, async () => {\n *   const userId = myContext.get('userId'); // '123'\n * });\n * ```\n */\nexport abstract class Context<TStore extends Record<string, any>> {\n  protected readonly storage: AsyncLocalStorage<TStore> = new AsyncLocalStorage<TStore>();\n\n  /**\n   * Run a callback within a new context\n   *\n   * Creates a new async context with the provided store data.\n   * All operations within the callback will have access to this context.\n   *\n   * @param store - Initial context data\n   * @param callback - Async function to execute\n   * @returns Result of the callback\n   */\n  public run<T>(store: TStore, callback: () => Promise<T>): Promise<T> {\n    return this.storage.run(store, callback);\n  }\n\n  /**\n   * Enter a new context without a callback\n   *\n   * Useful for middleware where you want to set context for the rest of the request.\n   * Unlike `run()`, this doesn't require a callback.\n   *\n   * @param store - Context data to set\n   */\n  public enter(store: TStore): void {\n    this.storage.enterWith(store);\n  }\n\n  /**\n   * Update the current context\n   *\n   * Merges new data into existing context, or enters new context if none exists.\n   *\n   * @param updates - Partial context data to merge\n   */\n  public update(updates: Partial<TStore>): void {\n    const current = this.storage.getStore();\n\n    if (current) {\n      Object.assign(current, updates);\n    } else {\n      this.enter(updates as TStore);\n    }\n  }\n\n  /**\n   * Get the current context store\n   *\n   * @returns Current context or undefined if not in context\n   */\n  public getStore(): TStore | undefined {\n    return this.storage.getStore();\n  }\n\n  /**\n   * Get a specific value from context\n   *\n   * @param key - Key to retrieve\n   * @returns Value or undefined\n   */\n  public get<K extends keyof TStore>(key: K): TStore[K] | undefined {\n    return this.storage.getStore()?.[key];\n  }\n\n  /**\n   * Set a specific value in context\n   *\n   * @param key - Key to set\n   * @param value - Value to store\n   */\n  public set<K extends keyof TStore>(key: K, value: TStore[K]): void {\n    this.update({ [key]: value } as any);\n  }\n\n  /**\n   * Clear the context\n   */\n  public clear(): void {\n    this.storage.enterWith({} as TStore);\n  }\n\n  /**\n   * Check if currently in a context\n   */\n  public hasContext(): boolean {\n    return this.storage.getStore() !== undefined;\n  }\n\n  /**\n   * Build the initial store for this context\n   *\n   * Override this method to provide custom initialization logic.\n   * Called by ContextManager.buildStores() for each registered context.\n   *\n   * @param payload - Generic payload (e.g., { request, response } for HTTP contexts)\n   * @returns Initial store data\n   */\n  public abstract buildStore(payload?: Record<string, any>): TStore;\n}\n","import type { Context } from \"./base-context\";\n\n/**\n * Context Manager - Orchestrates multiple contexts together\n *\n * Allows running multiple AsyncLocalStorage contexts in a single operation,\n * making it easy to link request, storage, database, and other contexts.\n *\n * @example\n * ```typescript\n * // Register contexts\n * contextManager\n *   .register('request', requestContext)\n *   .register('storage', storageDriverContext)\n *   .register('database', databaseDataSourceContext);\n *\n * // Run all contexts together\n * await contextManager.runAll({\n *   request: { request, response, user },\n *   storage: { driver, metadata: { tenantId: '123' } },\n *   database: { dataSource: 'primary' },\n * }, async () => {\n *   // All contexts active!\n *   await handleRequest();\n * });\n * ```\n */\nexport class ContextManager {\n  private contexts = new Map<string, Context<any>>();\n\n  /**\n   * Register a context\n   *\n   * @param name - Unique context name\n   * @param context - Context instance\n   * @returns This instance for chaining\n   */\n  public register(name: string, context: Context<any>): this {\n    this.contexts.set(name, context);\n    return this;\n  }\n\n  /**\n   * Run all registered contexts together\n   *\n   * Nests all context.run() calls, ensuring all contexts are active\n   * for the duration of the callback.\n   *\n   * @param stores - Context stores keyed by context name\n   * @param callback - Async function to execute\n   * @returns Result of the callback\n   */\n  public async runAll<T>(stores: Record<string, any>, callback: () => Promise<T>): Promise<T> {\n    const entries = Array.from(this.contexts.entries());\n\n    // Build nested context runners\n    const runner = entries.reduceRight((next, [name, context]) => {\n      return () => context.run(stores[name] || {}, next);\n    }, callback);\n\n    return runner();\n  }\n\n  /**\n   * Enter all contexts at once (for middleware)\n   *\n   * @param stores - Context stores keyed by context name\n   */\n  public enterAll(stores: Record<string, any>): void {\n    for (const [name, context] of this.contexts.entries()) {\n      if (stores[name]) {\n        context.enter(stores[name]);\n      }\n    }\n  }\n\n  /**\n   * Clear all contexts\n   */\n  public clearAll(): void {\n    for (const context of this.contexts.values()) {\n      context.clear();\n    }\n  }\n\n  /**\n   * Get a specific registered context\n   *\n   * @param name - Context name\n   * @returns Context instance or undefined\n   */\n  public getContext<T extends Context<any>>(name: string): T | undefined {\n    return this.contexts.get(name) as T | undefined;\n  }\n\n  /**\n   * Check if a context is registered\n   *\n   * @param name - Context name\n   * @returns True if context is registered\n   */\n  public hasContext(name: string): boolean {\n    return this.contexts.has(name);\n  }\n\n  /**\n   * Build all context stores by calling each context's buildStore() method\n   *\n   * This is the immutable pattern - returns a new record of stores.\n   * Each context defines its own initialization logic.\n   *\n   * @param payload - Payload passed to each buildStore() (e.g., { request, response })\n   * @returns Record of context name -> store data\n   *\n   * @example\n   * ```typescript\n   * const httpContextStore = contextManager.buildStores({ request, response });\n   * await contextManager.runAll(httpContextStore, async () => { ... });\n   * ```\n   */\n  public buildStores(payload?: Record<string, any>): Record<string, any> {\n    const stores: Record<string, any> = {};\n\n    for (const [name, context] of this.contexts.entries()) {\n      stores[name] = context.buildStore(payload) ?? {};\n    }\n\n    return stores;\n  }\n\n  /**\n   * Unregister a context\n   *\n   * @param name - Context name to remove\n   * @returns True if context was removed\n   */\n  public unregister(name: string): boolean {\n    return this.contexts.delete(name);\n  }\n}\n\n/**\n * Global context manager instance\n *\n * Use this singleton to register and manage all framework contexts.\n */\nexport const contextManager = new ContextManager();\n"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@warlock.js/context",
+  "version": "4.0.39",
+  "description": "A simple and unified way to share context using AsyncLocalStorage for the Warlock.js framework",
+  "keywords": [
+    "warlock",
+    "warlockjs",
+    "context",
+    "async-local-storage",
+    "asynclocalstorage",
+    "async-context",
+    "request-context",
+    "nodejs"
+  ],
+  "author": "hassanzohdy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/warlockjs/context.git"
+  },
+  "homepage": "https://github.com/warlockjs/context#readme",
+  "bugs": {
+    "url": "https://github.com/warlockjs/context/issues"
+  },
+  "main": "./cjs/index.js",
+  "module": "./esm/index.js",
+  "types": "./esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.ts",
+        "default": "./esm/index.js"
+      },
+      "require": {
+        "types": "./cjs/index.d.ts",
+        "default": "./cjs/index.js"
+      }
+    }
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}