@warlock.js/context 5.23.2 → 5.25.0

package/README.md

@@ -1,343 +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
+# @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