syntropylog/dist/types/context/ContextManager.d.ts

An instance manager with observability for Node.js applications

import { IContextManager } from './IContextManager';
import { LogLevel } from '../logger/levels';
import { ContextValue, ContextData, ContextConfig, ContextCallback, ContextHeaders, FilteredContext, LoggingMatrix } from '../types';
/**
 * Manages asynchronous context using Node.js `AsyncLocalStorage`.
 * This is the core component for propagating context-specific data
 * (like correlation IDs) without passing them through function arguments.
 * @implements {IContextManager}
 */
export declare class ContextManager implements IContextManager {
    private storage;
    private correlationIdHeader;
    private transactionIdHeader;
    private loggingMatrix;
    constructor(loggingMatrix?: LoggingMatrix);
    configure(options: ContextConfig): void;
    /**
     * Reconfigures the logging matrix dynamically.
     * This method allows changing which context fields are included in logs
     * without affecting security configurations like masking or log levels.
     * @param newMatrix The new logging matrix configuration
     */
    reconfigureLoggingMatrix(newMatrix: LoggingMatrix): void;
    /**
     * Executes a function within a new, isolated asynchronous context.
     * Any data set via `set()` inside the callback will only be available
     * within that callback's asynchronous execution path. The new context
     * inherits values from the parent context, if one exists.
     * @template T The return type of the callback.
     * @param callback The function to execute within the new context.
     * @returns {T} The result of the callback function.
     */
    run(fn: ContextCallback): Promise<void>;
    /**
     * Gets a value from the current asynchronous context by its key.
     * @template T The expected type of the value.
     * @param key The key of the value to retrieve.
     * @returns The value, or `undefined` if not found or if outside a context.
     */
    get<T = ContextValue>(key: string): T | undefined;
    /**
     * Gets the entire key-value store from the current asynchronous context.
     * @returns {ContextData} An object containing all context data, or an empty object if outside a context.
     */
    getAll(): ContextData;
    /**
     * Sets a key-value pair in the current asynchronous context. This will have
     * no effect if called outside of a context created by `run()`.
     * This will only work if called within a context created by `run()`.
     * @param key The key for the value.
     * @param value The value to store.
     * @returns {void}
     */
    set(key: string, value: ContextValue): void;
    /**
     * Gets the correlation ID from the current context.
     * If no correlation ID exists, generates one automatically to ensure tracing continuity.
     * @returns {string} The correlation ID (never undefined).
     */
    getCorrelationId(): string;
    /**
     * Sets the correlation ID in the current context.
     * This sets the value in the configured header name.
     * @param correlationId The correlation ID to set.
     */
    setCorrelationId(correlationId: string): void;
    /**
     * Gets the transaction ID from the current context.
     * @returns {string | undefined} The transaction ID, or undefined if not set.
     */
    getTransactionId(): string | undefined;
    /**
     * Sets the transaction ID in the current context.
     * @param transactionId The transaction ID to set.
     */
    setTransactionId(transactionId: string): void;
    /**
     * Gets the configured HTTP header name for the correlation ID.
     * @returns {string} The header name.
     */
    getCorrelationIdHeaderName(): string;
    getTransactionIdHeaderName(): string;
    /**
     * Gets the tracing headers to propagate the context (e.g., W3C Trace Context).
     * This base implementation does not support trace context propagation.
     * @returns `undefined` as this feature is not implemented by default.
     */
    getTraceContextHeaders(): ContextHeaders;
    getFilteredContext(level: LogLevel): FilteredContext;
}