@clipboard-health/execution-context 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# @clipboard-health/execution-context <!-- omit from toc -->
+
+`ExecutionContext` is a lightweight Node.js package built with TypeScript that leverages `AsyncLocalStorage` to create a statically available context parallel to any execution. It provides a reliable, thread-safe context for attaching and accessing metadata throughout the lifecycle of an execution, such as API requests, background jobs, or message consumers. This allows various parts of your application to communicate and share metadata without needing to explicitly pass context objects.
+
+## Features
+
+- **Scoped Contexts**: Attach data to a context that is specific to each execution scope.
+- **Static Access**: Access context data statically anywhere in the codebase within an active execution.
+- **Metadata Aggregation**: Store and retrieve metadata across the lifespan of an execution, ideal for logging, tracing, and other observability tasks.
+
+## Table of Contents <!-- omit from toc -->
+
+- [Install](#install)
+- [Usage](#usage)
+- [Local development commands](#local-development-commands)
+
+## Install
+
+```bash
+npm install @clipboard-health/execution-context
+```
+
+## Usage
+
+This example demonstrates how to create a logging context, accumulate metadata from various function calls, and then log a single message containing all the gathered metadata.
+
+```ts
+// ./examples/executionContext.ts
+
+import {
+  addMetadataToLocalContext,
+  getExecutionContext,
+  newExecutionContext,
+  runWithExecutionContext,
+} from "@clipboard-health/execution-context";
+
+export async function processRequest() {
+  // Start a context for this request
+  await runWithExecutionContext(newExecutionContext("context-name"), async () => {
+    const context = getExecutionContext();
+
+    try {
+      // Add metadata from the current function
+      addMetadataToLocalContext({ userId: "1" });
+
+      // Simulate calling other functions that add their own context metadata
+      callFunctionThatAddsContext();
+      callFunctionThatCallsAnotherFunctionThatAddsContext();
+
+      // Log the successful processing event with accumulated metadata
+      console.log("event=MessageProcessed", { ...context?.metadata });
+    } catch (error) {
+      // Capture and log error metadata if something goes wrong
+      addMetadataToLocalContext({ error });
+      console.error("event=MessageProcessed", { ...context?.metadata });
+    }
+  });
+}
+
+// Example function that adds its own metadata to the current context
+function callFunctionThatAddsContext() {
+  addMetadataToLocalContext({ operation: "dataFetch", status: "success" });
+}
+
+// Example function that calls another function, both adding their own metadata
+function callFunctionThatCallsAnotherFunctionThatAddsContext() {
+  addMetadataToLocalContext({ operation: "validate", validationStep: "pre-check" });
+  callAnotherFunctionThatAddsContext();
+}
+
+function callAnotherFunctionThatAddsContext() {
+  addMetadataToLocalContext({
+    operation: "validate",
+    validationStep: "post-check",
+    result: "passed",
+  });
+}
+```
+
+## Local development commands
+
+See [`package.json`](./package.json) `scripts` for a list of commands.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@clipboard-health/execution-context",
+  "description": "A lightweight Node.js utility for managing execution contexts and metadata aggregation using AsyncLocalStorage.",
+  "version": "0.1.0",
+  "dependencies": {
+    "tslib": "2.8.0"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "main": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "embed": "embedme README.md"
+  },
+  "type": "commonjs",
+  "typings": "./src/index.d.ts",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./lib/contextStore";
+export * from "./types/global";
+export * from "./types/types";

package/src/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/contextStore"), exports);
+tslib_1.__exportStar(require("./types/global"), exports);
+tslib_1.__exportStar(require("./types/types"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/execution-context/src/index.ts"],"names":[],"mappings":";;;AAAA,6DAAmC;AACnC,yDAA+B;AAC/B,wDAA8B"}

package/src/lib/contextStore.d.ts

@@ -0,0 +1,14 @@
+import { type ExecutionContext } from "../types/types";
+export declare function getExecutionContext(): ExecutionContext | undefined;
+export declare function runWithExecutionContext<T = void>(context: ExecutionContext, callback: () => Promise<T>): Promise<T>;
+/**
+ * This function is simply a convenience to initialize an empty context object
+ * @param source - The class/service that initializes the context
+ */
+export declare function newExecutionContext(source: string): ExecutionContext;
+/**
+ * A utility function that will add metadata to the current context
+ * @param metadata - the metadata (key-value pair), to be added to the context
+ */
+export declare function addMetadataToLocalContext(metadata: Record<string, unknown>): void;
+export declare function addToMetadataList(key: string, metadata: Record<string, unknown>): void;

package/src/lib/contextStore.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getExecutionContext = getExecutionContext;
+exports.runWithExecutionContext = runWithExecutionContext;
+exports.newExecutionContext = newExecutionContext;
+exports.addMetadataToLocalContext = addMetadataToLocalContext;
+exports.addToMetadataList = addToMetadataList;
+const node_async_hooks_1 = require("node:async_hooks");
+globalThis.threadLocalStorage ||= new node_async_hooks_1.AsyncLocalStorage();
+function getAsyncLocalStorage() {
+    return globalThis.threadLocalStorage;
+}
+function getExecutionContext() {
+    return getAsyncLocalStorage().getStore();
+}
+async function runWithExecutionContext(context, callback) {
+    return await new Promise((resolve, reject) => {
+        getAsyncLocalStorage().run(context, () => {
+            try {
+                Promise.resolve(callback()).then(resolve).catch(reject);
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+    });
+}
+/**
+ * This function is simply a convenience to initialize an empty context object
+ * @param source - The class/service that initializes the context
+ */
+function newExecutionContext(source) {
+    return {
+        source,
+        metadata: {},
+    };
+}
+/**
+ * A utility function that will add metadata to the current context
+ * @param metadata - the metadata (key-value pair), to be added to the context
+ */
+function addMetadataToLocalContext(metadata) {
+    const context = getExecutionContext();
+    if (context) {
+        context.metadata = { ...context.metadata, ...metadata };
+    }
+}
+function getMetadataListByKey(key) {
+    const context = getExecutionContext();
+    if (context?.metadata && key in context.metadata) {
+        const metadataForKey = context.metadata[key];
+        if (Array.isArray(metadataForKey)) {
+            return metadataForKey;
+        }
+    }
+    return [];
+}
+function addToMetadataList(key, metadata) {
+    const metadataList = [...getMetadataListByKey(key), metadata];
+    addMetadataToLocalContext({ [key]: metadataList });
+}
+//# sourceMappingURL=contextStore.js.map

package/src/lib/contextStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextStore.js","sourceRoot":"","sources":["../../../../../packages/execution-context/src/lib/contextStore.ts"],"names":[],"mappings":";;AAUA,kDAEC;AAED,0DAaC;AAMD,kDAKC;AAMD,8DAKC;AAcD,8CAGC;AAlED,uDAAqD;AAIrD,UAAU,CAAC,kBAAkB,KAAK,IAAI,oCAAiB,EAAE,CAAC;AAE1D,SAAS,oBAAoB;IAC3B,OAAO,UAAU,CAAC,kBAAkB,CAAC;AACvC,CAAC;AAED,SAAgB,mBAAmB;IACjC,OAAO,oBAAoB,EAAE,CAAC,QAAQ,EAAE,CAAC;AAC3C,CAAC;AAEM,KAAK,UAAU,uBAAuB,CAC3C,OAAyB,EACzB,QAA0B;IAE1B,OAAO,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,oBAAoB,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE;YACvC,IAAI,CAAC;gBACH,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC1D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,MAAc;IAChD,OAAO;QACL,MAAM;QACN,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,yBAAyB,CAAC,QAAiC;IACzE,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IACtC,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,QAAQ,GAAG,EAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,SAAS,oBAAoB,CAAC,GAAW;IACvC,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IACtC,IAAI,OAAO,EAAE,QAAQ,IAAI,GAAG,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACjD,MAAM,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;YAClC,OAAO,cAAc,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAgB,iBAAiB,CAAC,GAAW,EAAE,QAAiC;IAC9E,MAAM,YAAY,GAAG,CAAC,GAAG,oBAAoB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC9D,yBAAyB,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC;AACrD,CAAC"}

package/src/types/types.d.ts

@@ -0,0 +1,11 @@
+export type Metadata = Record<string, unknown>;
+export interface ExecutionContext {
+    /**
+     * The class/file/service that originated the thread that owns this context
+     */
+    source: string;
+    /**
+     * Additional contextual information associated with this execution context
+     */
+    metadata: Metadata;
+}

package/src/types/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/src/types/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../packages/execution-context/src/types/types.ts"],"names":[],"mappings":""}