@daiso-tech/core
Version:
The library offers flexible, framework-agnostic solutions for modern web applications, built on adaptable components that integrate seamlessly with popular frameworks like Next Js.
60 lines (59 loc) • 2.66 kB
TypeScript
/**
* @module ExecutionContext
*/
import { type InvokableFn } from "../../utilities/_module.js";
/**
* IMPORT_PATH: `"@daiso-tech/core/execution-context/contracts"`
*
* Adapter contract for managing execution context storage and lifecycle.
*
* This contract defines the contract for storing and retrieving context values
* in different execution environments (e.g., AsyncLocalStorage for Node.js, thread-local storage).
* It allows different adapters to implement context tracking differently based on the runtime.
*
* The adapter provides context isolation, ensuring each execution path has its own context:
* - In async environments: context persists across await boundaries within the same execution chain
* - In threaded environments: context is thread-local, preventing cross-thread interference
* - In browser environments: context persists within the same call stack
*
* Common use cases:
* - Audit logging: track request ID across nested function calls
* - User identification: access current user without passing as parameter
* - Per-request configuration: tenant ID, feature flags, localization
*
* @template TValue - The type of the context value being stored
*
* @group Contracts
*/
export type IExecutionContextAdapter<TValue> = {
/**
* Retrieves the current execution context value.
* Returns null if no context is set in the current execution scope.
*
* Called frequently, should be performant (usually O(1) - direct lookup).
*
* @returns The current context value, or null if no context is active
*/
get(): TValue | null;
/**
* Executes the given function within the specified context.
*
* This method ensures the provided context is active during function execution,
* making it accessible to `get()` calls within the function and any nested function calls.
* When the function completes, the previous context (if any) is restored.
*
* Useful for:
* - Maintaining context across async boundaries
* - Isolating context between concurrent executions
* - Implementing per-request or per-task metadata propagation
*
* Note: This method is used for both asynchronous and synchronous execution.
*
* @template TReturn - The return type of the function
* @param context - The context value to set for the duration of the function execution
* @param fn - The function to execute within the context
* @returns The return value of the executed function
* @throws Error propagated from the executed function
*/
run<TReturn>(context: TValue, fn: InvokableFn<[], TReturn>): TReturn;
};