core-services-sdk 1.3.56 → 1.3.59

package/types/util/context.d.ts

@@ -1,55 +1,124 @@
-export namespace Context {
+/**
+ * Represents the data stored in the async context for a single execution flow.
+ *
+ * This object is propagated automatically across async boundaries
+ * using Node.js AsyncLocalStorage.
+ *
+ * It defines the contract between producers (who set values)
+ * and consumers (who read values) of the context.
+ *
+ * @typedef {Object} ContextStore
+ *
+ * @property {string} [correlationId] - Unique identifier for request or operation tracing.
+ * @property {string} [ip] - Client IP address.
+ * @property {string} [userAgent] - Client user agent string.
+ * @property {string} [tenantId] - Active tenant identifier.
+ * @property {string} [userId] - Authenticated user identifier.
+ */
+/**
+ * Async execution context manager built on top of Node.js AsyncLocalStorage.
+ *
+ * This class provides a thin, static API for storing and accessing
+ * request-scoped (or async-chain-scoped) metadata such as correlation IDs,
+ * user information, tenant identifiers, and similar data.
+ *
+ * The context is bound to the current async execution chain using
+ * AsyncLocalStorage and is automatically propagated across `await` boundaries.
+ *
+ * This class is intentionally static and acts as a singleton wrapper
+ * around AsyncLocalStorage.
+ */
+export class Context {
   /**
-   * Run a callback within a given context store.
-   * Everything `await`ed or invoked inside this callback will have access
-   * to the provided store via {@link Context.get}, {@link Context.set}, or {@link Context.all}.
+   * Run a callback within a given async context store.
+   *
+   * All asynchronous operations spawned inside the callback
+   * will have access to the provided store via {@link Context.get},
+   * {@link Context.set}, or {@link Context.all}.
    *
    * @template T
-   * @param {Record<string, any>} store
+   * @param {ContextStore} store - Initial context store for this execution.
    * @param {() => T} callback - Function to execute inside the context.
    * @returns {T} The return value of the callback (sync or async).
    *
    * @example
    * Context.run(
-   *   { correlationId: 'abc123' },
+   *   { correlationId: 'abc123', userId: 'usr_1' },
    *   async () => {
    *     console.log(Context.get('correlationId')) // "abc123"
    *   }
    * )
    */
-  function run<T>(store: Record<string, any>, callback: () => T): T
+  static run<T>(store: ContextStore, callback: () => T): T
   /**
    * Retrieve a single value from the current async context store.
    *
-   * @template T
-   * @param {string} key - The key of the value to retrieve.
-   * @returns {T|undefined} The stored value, or `undefined` if no store exists or key not found.
+   * If called outside of an active {@link Context.run},
+   * this method returns `undefined`.
+   *
+   * @template {keyof ContextStore} K
+   * @param {K} key - Context property name.
+   * @returns {ContextStore[K] | undefined} The stored value, if present.
    *
    * @example
-   * const userId = Context.get('userId')
+   * const tenantId = Context.get('tenantId')
    */
-  function get<T>(key: string): T | undefined
+  static get<K extends keyof ContextStore>(key: K): ContextStore[K] | undefined
   /**
-   * Set a single key-value pair in the current async context store.
-   * If there is no active store (i.e. outside of a {@link Context.run}),
-   * this function does nothing.
+   * Set a single key-value pair on the current async context store.
+   *
+   * If called outside of an active {@link Context.run},
+   * this method is a no-op.
    *
-   * @param {string} key - The key under which to store the value.
-   * @param {any} value - The value to store.
+   * @template {keyof ContextStore} K
+   * @param {K} key - Context property name.
+   * @param {ContextStore[K]} value - Value to store.
    *
    * @example
    * Context.set('tenantId', 'tnt_1234')
    */
-  function set(key: string, value: any): void
+  static set<K extends keyof ContextStore>(key: K, value: ContextStore[K]): void
   /**
-   * Get the entire store object for the current async context.
+   * Get the full context store for the current async execution.
    *
-   * @returns {Record<string, any>} The current store object,
-   * or an empty object if no store exists.
+   * If no context is active, an empty object is returned.
+   *
+   * @returns {ContextStore}
    *
    * @example
-   * const all = Context.all()
-   * console.log(all) // { correlationId: 'abc123', userId: 'usr_789' }
+   * const ctx = Context.all()
+   * console.log(ctx.correlationId)
+   */
+  static all(): ContextStore
+}
+/**
+ * Represents the data stored in the async context for a single execution flow.
+ *
+ * This object is propagated automatically across async boundaries
+ * using Node.js AsyncLocalStorage.
+ *
+ * It defines the contract between producers (who set values)
+ * and consumers (who read values) of the context.
+ */
+export type ContextStore = {
+  /**
+   * - Unique identifier for request or operation tracing.
+   */
+  correlationId?: string
+  /**
+   * - Client IP address.
+   */
+  ip?: string
+  /**
+   * - Client user agent string.
+   */
+  userAgent?: string
+  /**
+   * - Active tenant identifier.
+   */
+  tenantId?: string
+  /**
+   * - Authenticated user identifier.
    */
-  function all(): Record<string, any>
+  userId?: string
 }