syntropylog/dist/types/serialization/SerializerRegistry.d.ts

An instance manager with observability for Node.js applications

/**
 * @file src/serialization/SerializerRegistry.ts
 * @description Manages and safely applies custom log object serializers.
 */
import { ILogger } from '../logger/ILogger';
/**
 * @type SerializerMap
 * @description A map where the key is the field name to look for in a log object,
 * and the value is the function that will transform its value into a string.
 */
type SerializerMap = Record<string, (value: unknown) => string>;
/**
 * @interface SerializerRegistryOptions
 * @description Defines the configuration for the SerializerRegistry.
 */
export interface SerializerRegistryOptions {
    /** A map of custom serializer functions provided by the user. */
    serializers?: SerializerMap;
    /** The maximum time in milliseconds a serializer can run before being timed out. @default 50 */
    timeoutMs?: number;
}
/**
 * @class SerializerRegistry
 * @description Manages and applies custom serializer functions to log metadata.
 * It ensures that serializers are executed safely, with timeouts and error handling,
 * to prevent them from destabilizing the logging pipeline.
 */
export declare class SerializerRegistry {
    /** @private A map of field names to their corresponding serializer functions. */
    private readonly serializers;
    /** @private The timeout in milliseconds for each serializer execution. */
    private readonly timeoutMs;
    /**
     * @constructor
     * @param {SerializerRegistryOptions} [options] - Configuration options for the registry.
     */
    constructor(options?: SerializerRegistryOptions);
    /**
     * Processes a metadata object, applying any matching serializers.
     * @param {Record<string, unknown>} meta - The metadata object from a log call.
     * @param {ILogger} logger - A logger instance to report errors from the serialization process itself.
     * @returns {Promise<Record<string, unknown>>} A new metadata object with serialized values.
     */
    process(meta: Record<string, unknown>, logger: ILogger): Promise<Record<string, unknown>>;
    /**
     * @private
     * Safely executes a serializer function with a timeout.
     * @param {(value: unknown) => string} serializerFn - The serializer function to execute.
     * @param {unknown} value - The value to pass to the function.
     * @returns {Promise<string>} A promise that resolves with the serialized string.
     * @throws An error if the serializer throws an exception or times out.
     */
    private secureExecute;
    /**
     * @private
     * The default serializer for Error objects. It creates a JSON string representation
     * of the error, explicitly including common properties like name, message, and stack.
     * @param {unknown} err - The value to serialize, expected to be an Error.
     * @returns {string} A JSON string representing the error.
     */
    private defaultErrorSerializer;
}
export {};