@marceloraineri/async-context 1.0.0 → 1.0.1

package/README.md

@@ -1 +1,85 @@
-# SyncContext
+# AsyncContext
+
+> Request-scoped context storage backed by Node.js `AsyncLocalStorage`, with first-class Express integration.
+
+AsyncContext is a tiny utility library that standardizes how you propagate contextual data across asynchronous flows. It offers a singleton `Context` wrapper around `AsyncLocalStorage` plus helpers to enrich the active store and an Express middleware that bootstraps a fresh context for every incoming request.
+
+## Why AsyncContext?
+
+- **Consistent async context** – Create one logical context per request, job, or background task without passing parameters through every function call.
+- **Drop-in API** – Call `Context.addValue` or `Context.addObjectValue` anywhere inside the active flow to append metadata.
+- **Observability ready** – Ship correlation IDs, tenant information, user data, or tracing metadata through your stack.
+- **Framework friendly** – Includes an `AsyncContextExpresssMiddleware` that assigns a unique `instance_id` to each Express request and runs all downstream handlers inside that context.
+
+## Installation
+
+```bash
+npm i @marceloraineri/a@marceloraineri/async-context
+```
+
+When developing locally inside this repo, import from the relative `core` entry point instead.
+
+## Quick start
+
+```ts
+import { Context } from "@marceloraineri/async-context";
+  Context.addValue("user", { id: 42, name: "Ada" });
+
+  await Promise.resolve();
+
+  const store = Context.getInstance().getStore();
+  console.log(store.requestId); // 184fa9a3-f967-4a98-9d8f-57152e7cbe64
+  console.log(store.user); // { id: 42, name: "Ada" }
+```
+
+## Express middleware
+
+`AsyncContextExpresssMiddleware` (note the triple “s”) creates a new context for every Express request, seeds it with a UUID `instance_id`, and ensures the context is available throughout the request lifecycle.
+
+```ts
+import express from "express";
+import {
+  AsyncContextExpresssMiddleware,
+  Context,
+} from "@marceloraineri/async-context";
+
+const app = express();
+
+app.use(AsyncContextExpresssMiddleware);
+
+app.get("/ping", (_req, res) => {
+  const store = Context.getInstance().getStore();
+  res.json({ instanceId: store?.instance_id ?? null });
+});
+
+app.listen(3000, () => console.log("API listening on :3000"));
+```
+
+## API reference
+
+### `Context.getInstance(): AsyncLocalStorage`
+Returns (and lazily instantiates) the singleton `AsyncLocalStorage` used by the library. You typically call `run(store, callback)` on this instance to spawn a new context.
+
+### `Context.addObjectValue(values: Record<string, unknown>): Record<string, unknown>`
+Merges the provided object into the active context. Also throws if no context is active.
+
+### `AAsyncContextExpresssMiddleware(req, res, next)`
+Express middleware that:
+
+1. Generates a UUID via `crypto.randomUUID()`.
+2. Calls `Context.getInstance().run({ instance_id: uuid }, () => next())`.
+3. Makes the context (and `instance_id`) available to any downstream code.
+
+## Best practices & caveats
+
+- Avoid replacing the entire store object manually; instead mutate it through `addValue`/`addObjectValue` to keep shared references intact.
+- `AsyncLocalStorage` state is scoped to a single Node.js process. If you spawn workers or separate processes, each will maintain its own context.
+- Be mindful of long-lived contexts: if you never exit a `run` callback (e.g., forgetting to call `next()` in Express), the store will never be released.
+
+## Contributing
+
+Issues and pull requests are welcome. Please include reproduction steps or tests whenever you propose a change to the async context behavior.
+
+## License
+
+Specify the desired license (e.g., MIT) here.

package/core/context.ts

@@ -0,0 +1,76 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/**
+ * Provides an application-wide asynchronous context using Node.js AsyncLocalStorage.
+ * Allows storing and retrieving key/value data within the active async execution flow.
+ */
+export class Context {
+  /**
+   * Singleton instance of AsyncLocalStorage.
+   * @type {AsyncLocalStorage<unknown>}
+   */
+  public static asyncLocalStorageInstance: AsyncLocalStorage<unknown>;
+
+  /**
+   * Private constructor initializes the AsyncLocalStorage instance.
+   * Called automatically when the instance does not yet exist.
+   * @private
+   */
+  private constructor() {
+    Context.asyncLocalStorageInstance = new AsyncLocalStorage();
+  }
+
+  /**
+   * Returns the global AsyncLocalStorage instance, creating it if necessary.
+   *
+   * @returns {AsyncLocalStorage<unknown>} The AsyncLocalStorage singleton.
+   */
+  static getInstance(): AsyncLocalStorage<unknown> {
+    if (!Context.asyncLocalStorageInstance) {
+      new Context();
+    }
+    return Context.asyncLocalStorageInstance;
+  }
+
+  /**
+   * Adds a single key/value pair to the active asynchronous context.
+   *
+   * @param {string} key - Key to store inside the context.
+   * @param {*} value - Value to associate with the given key.
+   * @returns {Record<string, any>} The updated context object.
+   *
+   * @throws {Error} If called outside of an active `Context.getInstance().run()`.
+   */
+  static addValue(key: string, value: any) {
+    const contextObject = Context.getInstance().getStore() as Record<
+      string,
+      any
+    >;
+    if (!contextObject)
+      throw new Error(
+        "No active context found. Use Context.getInstance().run()."
+      );
+
+    contextObject[key] = value;
+    return contextObject;
+  }
+
+  /**
+   * Merges an object of values into the active asynchronous context.
+   *
+   * @param {Record<string, any>} object - Object containing key/value pairs to merge.
+   * @returns {Record<string, any>} The merged context object.
+   *
+   * @throws {Error} If called outside of an active `Context.getInstance().run()`.
+   */
+  static addObjectValue(object: Record<string, any>) {
+    const contextObject = Context.getInstance().getStore();
+    if (!contextObject)
+      throw new Error(
+        "No active context found. Use Context.getInstance().run()."
+      );
+
+    const merged = Object.assign(contextObject, object);
+    return merged;
+  }
+}

package/core/index.ts

@@ -0,0 +1,2 @@
+export { Context } from './context';
+export { AsyncContextExpresssMiddleware } from './integrations/express';

package/core/integrations/express.ts

@@ -0,0 +1,56 @@
+import type * as http from "node:http";
+import crypto from "node:crypto";
+import { Context } from "../..";
+
+/**
+ * Express middleware that initializes a new asynchronous context
+ * for each incoming request.  
+ *
+ * This middleware assigns a unique `instance_id` (UUID) to the
+ * request lifecycle and stores it inside AsyncLocalStorage,
+ * allowing the application to later retrieve per-request data
+ * without passing parameters through function calls.
+ *
+ * It is designed to simplify building request-scoped state,
+ * such as logging correlation IDs or storing metadata across
+ * asynchronous operations.
+ *
+ * @function AsyncContextExpressMiddleware
+ *
+ * @param {http.IncomingMessage} req - The current HTTP request.
+ * @param {http.ServerResponse} res - The current HTTP response.
+ * @param {Function} next - Express continuation callback.
+ *
+ * @example
+ * // Usage in an Express application
+ * import express from "express";
+ * import { AsyncContextExpressMiddleware } from "@marceloraineri/async-context";
+ *
+ * const app = express();
+ *
+ * app.use(AsyncContextExpressMiddleware);
+ *
+ * app.get("/test", (req, res) => {
+ *   const context = Context.getInstance().getStore();
+ *   console.log(context.instance_id); // Unique per request
+ *   res.send("OK");
+ * });
+ *
+ * @description
+ * A new asynchronous context is created via:
+ * `Context.getInstance().run({ instance_id: <uuid> }, ...)`
+ *
+ * This ensures that all async operations inside the request
+ * share the same context object until the request completes.
+ */
+
+export function AsyncContextExpresssMiddleware(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  next: () => void
+) {
+  const uuid = crypto.randomUUID();
+  const LocalStorageInstance = Context.getInstance();
+
+  LocalStorageInstance.run({ instance_id: uuid }, () => next());
+}

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@marceloraineri/async-context",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
-  "main": "index.js",
+  "main": "core/index.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "tsx watch --inspect core/index.ts",
+    "build": "tsc"
   },
   "repository": {
     "type": "git",
@@ -18,6 +20,10 @@
   "homepage": "https://github.com/ohraineri/AsyncContext#readme",
   "devDependencies": {
     "@types/node": "^24.10.1",
+    "eslint": "^9.39.1",
+    "ts-node": "^10.9.2",
+    "ts-node-dev": "^2.0.0",
+    "tsx": "^4.20.6",
     "typescript": "^5.9.3"
   }
 }

package/index.js

@@ -1,31 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Context = void 0;
-var node_async_hooks_1 = require("node:async_hooks");
-var Context = /** @class */ (function () {
-    function Context() {
-        Context.asyncLocalStorageInstance = new node_async_hooks_1.AsyncLocalStorage();
-    }
-    Context.getInstance = function () {
-        if (!Context.asyncLocalStorageInstance) {
-            new Context();
-        }
-        return Context.asyncLocalStorageInstance;
-    };
-    Context.addValue = function (key, value) {
-        var contextObject = Context.getInstance().getStore();
-        if (!contextObject)
-            throw new Error('Nenhum contexto ativo encontrado. Use Context.getInstance().run().');
-        contextObject[key] = value;
-        return contextObject;
-    };
-    Context.addObjectValue = function (object) {
-        var contextObject = Context.getInstance().getStore();
-        if (!contextObject)
-            throw new Error('Nenhum contexto ativo encontrado. Use Context.getInstance().run().');
-        var merged = Object.assign(contextObject, object);
-        return merged;
-    };
-    return Context;
-}());
-exports.Context = Context;

package/index.ts

@@ -1,38 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-
-type objectStorageType = {
-    [key: string] : unknown
-}
-
-export class Context {
-  static asyncLocalStorageInstance: AsyncLocalStorage<unknown>;
-
-  private constructor() {
-    Context.asyncLocalStorageInstance = new AsyncLocalStorage();
-  }
-
-  static getInstance() {
-    if (!Context.asyncLocalStorageInstance) {
-      new Context();
-    }
-    return Context.asyncLocalStorageInstance;
-  }
-
-  static addValue(key: string, value: any) {
-    const contextObject = Context.getInstance().getStore() as Record<string, any>;
-    if (!contextObject)
-      throw new Error('Nenhum contexto ativo encontrado. Use Context.getInstance().run().');
-
-    contextObject[key] = value;
-    return contextObject;
-  }
-
-  static addObjectValue(object: Record<string, any>) {
-    const contextObject = Context.getInstance().getStore();
-    if (!contextObject)
-      throw new Error('Nenhum contexto ativo encontrado. Use Context.getInstance().run().');
-
-    const merged = Object.assign(contextObject, object);
-    return merged;
-  }
-}