halua 3.0.0 → 4.0.2

package/lib/index.d.ts

@@ -1,157 +1,232 @@
-declare enum Level {
-    Trace = "TRACE",
-    Debug = "DEBUG",
-    Info = "INFO",
-    Notice = "NOTICE",
-    Warn = "WARN",
-    Error = "ERROR",
-    Fatal = "FATAL"
-}
-type LogLevel = string;
-
-interface HandlerExecuteMeta {
-    timestamp: number;
-    level: LogLevel;
-}
-interface Handler {
-    /** indicates min level to log */
-    level: LogLevel | undefined;
-    /** indicates exact levels to log */
-    exact: Array<LogLevel> | null;
-    /** indicates if objects should contain spaces and tabs */
-    spacing?: boolean;
-    printTimestamp?: boolean;
-    printLevel?: boolean;
-    execute: (meta: HandlerExecuteMeta) => Generator<YieldMessage, void, NextMessage>;
-    formatArg?: (value: any) => any;
-    formatTimestamp?: (value: number) => string;
-}
-interface BaseHandlerOptions {
-    level?: LogLevel;
-    exact?: LogLevel | Array<LogLevel>;
-    spacing?: boolean;
-    printTimestamp?: boolean;
-    printLevel?: boolean;
-}
-interface NextMessage {
-    type: NextMessageType;
-    value: any;
-    prev?: string;
-}
-interface YieldMessage {
-    type: YieldMessageType;
-}
-type YieldMessageType = "pass" | "done" | "init";
-type NextMessageType = "arg" | "done" | "init";
-
-interface HaluaLogger {
-    create: {
-        (handler: PassedHandler): HaluaLogger;
-        (options: HaluaOptions): HaluaLogger;
-        (arg1?: PassedHandler | HaluaOptions, options?: HaluaOptions): HaluaLogger;
-    };
-    child: (...args: any[]) => HaluaLogger;
-    setHandlers: (handler: PassedHandler) => void;
-    appendHandlers: (handler: PassedHandler) => void;
-    logTo: (level: LogLevel, ...args: any[]) => void;
-    trace: (...args: any[]) => void;
-    debug: (...args: any[]) => void;
-    info: (...args: any[]) => void;
-    warn: (...args: any[]) => void;
-    notice: (...args: any[]) => void;
-    error: (...args: any[]) => void;
-    fatal: (...args: any[]) => void;
-    assert: (assertion: boolean, ...args: any[]) => void;
-}
-interface HaluaOptions {
-    level?: LogLevel;
-    withArgs?: Array<any>;
-}
-type PassedHandler = (() => Handler) | Array<() => Handler>;
-
-declare class Halua implements HaluaLogger {
-    private options;
-    private readonly passedHandlers;
-    private handlers;
-    private balancer;
-    constructor(passed: PassedHandler, options?: HaluaOptions);
-    create(arg1?: PassedHandler | HaluaOptions, arg2?: HaluaOptions | undefined): HaluaLogger;
-    child(...args: any[]): HaluaLogger;
-    setHandlers(handler: PassedHandler): void;
-    appendHandlers(handler: PassedHandler): void;
-    logTo(level: LogLevel, ...args: any[]): void;
-    trace(...args: any[]): void;
-    debug(...args: any[]): void;
-    info(...args: any[]): void;
-    warn(...args: any[]): void;
-    notice(...args: any[]): void;
-    error(...args: any[]): void;
-    fatal(...args: any[]): void;
-    assert(assertion: boolean, ...args: any[]): void;
-    private updateBalancer;
-    private sendToBalancer;
-    private supposeIsHandler;
-    private buildHandlers;
-    private bindMethods;
-}
-
-type SendMethod = (data: string) => void;
-
-interface OutputConsole {
-    debug: (...args: any[]) => void;
-    info: (...args: any[]) => void;
-    warn: (...args: any[]) => void;
-    error: (...args: any[]) => void;
-}
-interface ConsoleHandlerOptions extends Omit<BaseHandlerOptions, "spacing"> {
-}
-declare function NewConsoleHandler(console: OutputConsole, options?: ConsoleHandlerOptions): () => {
-    level: LogLevel | undefined;
-    exact: Array<LogLevel> | null;
-    readonly console: OutputConsole;
-    readonly formatArg: (arg: any) => any;
-    applyOptionalOptions(options: ConsoleHandlerOptions): void;
-    execute(meta: {
-        timestamp: number;
-        level: string;
-    }): Generator<YieldMessage, void, NextMessage>;
-    sendMethod: SendMethod;
-    printTimestamp: boolean;
-    printLevel: boolean;
-    formatTimestamp(t: number): string;
-};
-
-interface JSONLogHandlerOptions extends BaseHandlerOptions {
-}
-declare function NewJSONHandler(send: (data: string) => void, options?: JSONLogHandlerOptions): () => {
-    level: LogLevel | undefined;
-    exact: Array<LogLevel> | null;
-    readonly formatArg: (arg: any) => string;
-    execute(meta: HandlerExecuteMeta): Generator<YieldMessage, void, NextMessage>;
-    formatTimestamp(t: number): string;
-    applyOptionalOptions(options: JSONLogHandlerOptions): void;
-    sendMethod: SendMethod;
-    printTimestamp: boolean;
-    printLevel: boolean;
-};
-
-interface TextLogHandlerOptions extends BaseHandlerOptions {
-}
-declare function NewTextHandler(send: (data: string) => void, options?: TextLogHandlerOptions): () => {
-    level: LogLevel | undefined;
-    exact: Array<LogLevel> | null;
-    readonly formatArg: (value: any) => string;
-    applyOptionalOptions(options: TextLogHandlerOptions): void;
-    sendMethod: SendMethod;
-    printTimestamp: boolean;
-    printLevel: boolean;
-    execute(meta: {
-        timestamp: number;
-        level: string;
-    }): Generator<YieldMessage, void, NextMessage>;
-    formatTimestamp(t: number): string;
-};
-
-declare const halua: Halua;
-
-export { type HaluaLogger, type Handler, Level, NewConsoleHandler, NewJSONHandler, NewTextHandler, halua };
+declare interface Argument {
+    type: ArgumentType;
+    value: any;
+}
+
+declare type ArgumentType = "undefined" | "null" | "boolean" | "string" | "number" | "array" | "object" | "symbol" | "typedarray" | "arraybuffer" | "bigint" | "map" | "set" | "weakmap" | "weakset" | "date" | "nan" | "infinity" | "function" | "error";
+
+declare interface BaseDispatcherOptions {
+    level?: LogLevel;
+    exact?: LogLevel | Array<LogLevel>;
+    spacing?: boolean;
+    printTimestamp?: boolean;
+    printLevel?: boolean;
+    /** RegExp for redacting sensitive data (keys in objs/maps + content matches in strings). Takes precedence over any logger-level redactDataRegExp. */
+    redactDataRegExp?: RegExp;
+}
+
+declare interface ConsoleDispatcherOptions extends Omit<BaseDispatcherOptions, "spacing"> {
+}
+
+export declare interface ConsoleLike {
+    debug: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+}
+
+/**
+ * Default RegExp for redacting sensitive data in logs.
+ * Matches common sensitive key names (e.g. password, apiKey, token, email, ssn)
+ * via substring (for camelCase/snake_case keys) and common sensitive value patterns
+ * (JWTs, emails, SSNs, credit cards, bearer tokens).
+ * Use with `redactDataRegExp` option on loggers or dispatchers.
+ */
+export declare const DefaultRedactRegExp: RegExp;
+
+export declare interface Dispatcher {
+    /** indicates min level to log */
+    level: LogLevel | undefined;
+    /** indicates exact levels to log */
+    exact: Array<LogLevel> | null;
+    /** indicates if objects should contain spaces and tabs */
+    spacing?: boolean;
+    printTimestamp?: boolean;
+    printLevel?: boolean;
+    /** RegExp for redacting sensitive data in this dispatcher's output (takes precedence over logger-level) */
+    redactDataRegExp?: RegExp;
+    /** primary dispatch: receives the execution meta, the primary log values (args), and optional errorMeta
+     *  (only populated for calls that went through .error(err, meta) or .assert(cond, err, meta)).
+     *  The errorMeta is deliberately kept separate from args so it does not pollute the "log values" list
+     *  and can be rendered specially by Text/JSON/Console dispatchers (e.g. top-level "meta" field in JSON).
+     */
+    dispatch: (meta: DispatcherExecuteMeta, args: any[], errorMeta?: Record<string, any>) => void;
+    formatArg?: (value: any) => any;
+    formatTimestamp?: (value: number) => string;
+}
+
+export declare class DispatcherBase implements Dispatcher {
+    sendMethod: SendMethod;
+    formatArg: ((value: any) => any) | undefined;
+    level: LogLevel | undefined;
+    exact: Array<LogLevel> | null;
+    printTimestamp: boolean;
+    printLevel: boolean;
+    redactDataRegExp?: RegExp;
+    _lastTimestampSec: number;
+    _lastTimestampStr: string;
+    constructor(send?: SendMethod, options?: BaseDispatcherOptions);
+    dispatch(meta: DispatcherExecuteMeta, args: any[], errorMeta?: Record<string, any>): void;
+    formatTimestamp(t: number): string;
+}
+
+declare interface DispatcherExecuteMeta {
+    timestamp: number;
+    level: LogLevel;
+    /** optional default redact regexp from the logger instance (per-dispatcher options override it) */
+    redactDataRegExp?: RegExp;
+}
+
+export declare function format(arg: Argument, spacing?: boolean): string;
+
+export declare function getType(arg: any): ArgumentType;
+
+declare class Halua<ErrorMeta = Record<string, any>> implements HaluaLogger<ErrorMeta> {
+    private options;
+    private readonly passedDispatchers;
+    private dispatchers;
+    private balancer;
+    private stamps;
+    constructor(passed: PassedDispatcher, options?: HaluaOptions);
+    create<EM = ErrorMeta>(arg1?: PassedDispatcher | HaluaOptions, arg2?: HaluaOptions | undefined): HaluaLogger<EM>;
+    child(...args: any[]): HaluaLogger<ErrorMeta>;
+    setDispatchers(dispatcher: PassedDispatcher): void;
+    appendDispatchers(dispatcher: PassedDispatcher): void;
+    logTo(level: LogLevel, ...args: any[]): void;
+    trace(...args: any[]): void;
+    debug(...args: any[]): void;
+    info(...args: any[]): void;
+    warn(...args: any[]): void;
+    notice(...args: any[]): void;
+    error(error: unknown, meta?: ErrorMeta): void;
+    fatal(...args: any[]): void;
+    assert(assertion: boolean, error: unknown, meta?: ErrorMeta): void;
+    stamp(label: string, id?: any): () => void;
+    stampEnd(id: any): void;
+    private endStamp;
+    private updateBalancer;
+    private sendToBalancer;
+    private supposeIsDispatcher;
+    private isDispatcherSpec;
+    private buildDispatchers;
+    private bindMethods;
+}
+
+export declare const halua: Halua<Record<string, any>>;
+
+export declare interface HaluaLogger<ErrorMeta = Record<string, any>> {
+    create: {
+        <EM = ErrorMeta>(dispatcher: PassedDispatcher): HaluaLogger<EM>;
+        <EM = ErrorMeta>(options: HaluaOptions): HaluaLogger<EM>;
+        <EM = ErrorMeta>(arg1?: PassedDispatcher | HaluaOptions, options?: HaluaOptions): HaluaLogger<EM>;
+    };
+    child: (...args: any[]) => HaluaLogger<ErrorMeta>;
+    setDispatchers: (dispatcher: PassedDispatcher) => void;
+    appendDispatchers: (dispatcher: PassedDispatcher) => void;
+    logTo: (level: LogLevel, ...args: any[]) => void;
+    trace: (...args: any[]) => void;
+    debug: (...args: any[]) => void;
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    notice: (...args: any[]) => void;
+    error: (error: unknown, meta?: ErrorMeta) => void;
+    fatal: (...args: any[]) => void;
+    assert: (assertion: boolean, error: unknown, meta?: ErrorMeta) => void;
+    stamp: (label: string, id?: any) => () => void;
+    stampEnd: (id: any) => void;
+}
+
+declare interface HaluaOptions {
+    level?: LogLevel;
+    withArgs?: Array<any>;
+    /** RegExp used to redact sensitive data (keys in objects/maps, content in strings). Overrides per-dispatcher if set on dispatcher. */
+    redactDataRegExp?: RegExp;
+}
+
+export declare enum Level {
+    Trace = "TRACE",
+    Debug = "DEBUG",
+    Info = "INFO",
+    Notice = "NOTICE",
+    Warn = "WARN",
+    Error = "ERROR",
+    Fatal = "FATAL"
+}
+
+declare type LogLevel = string;
+
+export declare function NewConsoleColoredDispatcher(console: ConsoleLike, options?: ConsoleDispatcherOptions): () => {
+    readonly console: ConsoleLike;
+    dispatch(meta: DispatcherExecuteMeta, rawArgs: any[], errorMeta?: Record<string, any>): void;
+    sendMethod: SendMethod;
+    formatArg: ((value: any) => any) | undefined;
+    level: LogLevel | undefined;
+    exact: Array< LogLevel> | null;
+    printTimestamp: boolean;
+    printLevel: boolean;
+    redactDataRegExp?: RegExp;
+    _lastTimestampSec: number;
+    _lastTimestampStr: string;
+    formatTimestamp(t: number): string;
+};
+
+export declare function NewConsoleDispatcher(console: ConsoleLike, options?: ConsoleDispatcherOptions): () => {
+    readonly console: ConsoleLike;
+    dispatch(meta: DispatcherExecuteMeta, rawArgs: any[], errorMeta?: Record<string, any>): void;
+    sendMethod: SendMethod;
+    formatArg: ((value: any) => any) | undefined;
+    level: LogLevel | undefined;
+    exact: Array< LogLevel> | null;
+    printTimestamp: boolean;
+    printLevel: boolean;
+    redactDataRegExp?: RegExp;
+    _lastTimestampSec: number;
+    _lastTimestampStr: string;
+    formatTimestamp(t: number): string;
+};
+
+export declare function NewJSONDispatcher(send: (data: string, errorMeta?: Record<string, any>) => void, options?: BaseDispatcherOptions): () => {
+    dispatch(meta: DispatcherExecuteMeta, rawArgs: any[], errorMeta?: Record<string, any>): void;
+    formatTimestamp(t: number): string;
+    sendMethod: SendMethod;
+    formatArg: ((value: any) => any) | undefined;
+    level: LogLevel | undefined;
+    exact: Array< LogLevel> | null;
+    printTimestamp: boolean;
+    printLevel: boolean;
+    redactDataRegExp?: RegExp;
+    _lastTimestampSec: number;
+    _lastTimestampStr: string;
+};
+
+export declare function NewTextDispatcher(send: (data: string, errorMeta?: Record<string, any>) => void, options?: BaseDispatcherOptions): () => {
+    sendMethod: SendMethod;
+    formatArg: ((value: any) => any) | undefined;
+    level: LogLevel | undefined;
+    exact: Array< LogLevel> | null;
+    printTimestamp: boolean;
+    printLevel: boolean;
+    redactDataRegExp?: RegExp;
+    _lastTimestampSec: number;
+    _lastTimestampStr: string;
+    dispatch(meta: DispatcherExecuteMeta, args: any[], errorMeta?: Record<string, any>): void;
+    formatTimestamp(t: number): string;
+};
+
+declare type PassedDispatcher = (() => Dispatcher) | Array<() => Dispatcher>;
+
+/**
+ * Recursively redacts sensitive data from a value according to regexp.
+ * - Strings (and strings inside arrays): matched substrings replaced by "^_^"
+ * - Objects/Maps: if *key* matches regexp, the corresponding value is replaced by "^_^" entirely
+ * - Handles circulars safely (returns "[Circular]")
+ * - Also redacts inside Error messages
+ * - Other types passed through
+ */
+export declare function redact(value: any, regexp?: RegExp): any;
+
+declare type SendMethod = (data: string, errorMeta?: Record<string, any>) => void;
+
+export declare function toJSONValue(value: any): any;
+
+export { }