@arkv/logger 0.1.1

package/dist/cjs/test-utils.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultTestConfig = void 0;
+exports.parseLogOutput = parseLogOutput;
+const colors_1 = require("@arkv/colors");
+const types_js_1 = require("./types.js");
+function parseLogOutput(logCall) {
+    const cleanLog = (0, colors_1.strip)(logCall);
+    return JSON.parse(cleanLog);
+}
+exports.defaultTestConfig = {
+    name: 'test-app',
+    version: '1.0.0',
+    env: 'local',
+    isDevelopment: true,
+    level: types_js_1.LogLevel.DEBUG,
+    maskFields: [
+        'password',
+        'token',
+        'apiKey',
+        'apiSecret',
+        'apiPass',
+    ],
+    filterEvents: ['/health'],
+    maxArrayLength: 1,
+};

package/dist/cjs/types.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MASK_FIELDS = exports.LOG_LEVELS = exports.LogLevel = void 0;
+var LogLevel;
+(function (LogLevel) {
+    LogLevel["VERBOSE"] = "verbose";
+    LogLevel["DEBUG"] = "debug";
+    LogLevel["LOG"] = "log";
+    LogLevel["WARN"] = "warn";
+    LogLevel["ERROR"] = "error";
+    LogLevel["FATAL"] = "fatal";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+exports.LOG_LEVELS = [
+    LogLevel.VERBOSE,
+    LogLevel.DEBUG,
+    LogLevel.LOG,
+    LogLevel.WARN,
+    LogLevel.ERROR,
+    LogLevel.FATAL,
+];
+exports.DEFAULT_MASK_FIELDS = [
+    'password',
+    'secret',
+    'token',
+    'authorization',
+    'cookie',
+    'apiKey',
+    'apiSecret',
+    'apiPass',
+];

package/dist/esm/context.js

@@ -0,0 +1,20 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export class ContextStore {
+    asyncLocalStorage = new AsyncLocalStorage();
+    getContext() {
+        const context = this.asyncLocalStorage.getStore();
+        if (!context) {
+            return {};
+        }
+        return { ...context };
+    }
+    updateContext(obj) {
+        const context = this.asyncLocalStorage.getStore();
+        if (context) {
+            Object.assign(context, obj);
+        }
+    }
+    runWithContext(context, callback) {
+        return this.asyncLocalStorage.run(context, callback);
+    }
+}

package/dist/esm/format.js

@@ -0,0 +1,29 @@
+import { brightBlue, brightCyan, brightGreen, brightMagenta, brightYellow, cyan, getLevelColorFn, getValueColor, gray, green, magenta, red, yellow, } from '@arkv/colors';
+import { safeStringify } from '@arkv/shared';
+export function formatColoredJson(obj, level) {
+    const jsonString = safeStringify(obj);
+    const colorMap = {
+        level: getLevelColorFn(level),
+        message: green,
+        timestamp: magenta,
+        requestId: brightGreen,
+        userId: brightBlue,
+        context: brightCyan,
+        duration: yellow,
+        event: brightMagenta,
+        error: red,
+        exception: red,
+        flow: brightGreen,
+        method: brightBlue,
+        stack: gray,
+        status: brightYellow,
+        elapsed: brightYellow,
+    };
+    return jsonString.replace(/(".*?":\s*)(.*?)(?=,|\n|$)/g, (_, key, value) => {
+        const keyWithoutQuotes = key
+            .replace(/"/g, '')
+            .slice(0, -1);
+        const colorizer = colorMap[keyWithoutQuotes] || getValueColor(value);
+        return `${cyan(key)}${colorizer(value)}`;
+    });
+}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { ContextStore } from './context.js';
+export { Logger } from './logger.js';
+export { DEFAULT_MASK_FIELDS, LOG_LEVELS, LogLevel, } from './types.js';

package/dist/esm/logger.js

@@ -0,0 +1,216 @@
+import { isPlainObject, safeStringify } from '@arkv/shared';
+import { formatColoredJson } from './format.js';
+import { findNestedError, sanitizeLogEntry, } from './sanitize.js';
+import { DEFAULT_MASK_FIELDS, LOG_LEVELS, LogLevel, } from './types.js';
+export class Logger {
+    logLevel;
+    #isDevelopment;
+    #maskFields;
+    #maxArrayLength;
+    #filterEvents;
+    #context;
+    #appName;
+    #appVersion;
+    #appEnv;
+    constructor(config, context) {
+        const cfg = config ?? {};
+        this.logLevel = cfg.level ?? LogLevel.DEBUG;
+        this.#isDevelopment =
+            cfg.isDevelopment ??
+                process.env.NODE_ENV !== 'production';
+        this.#maskFields =
+            cfg.maskFields && cfg.maskFields.length > 0
+                ? Array.from(new Set([
+                    ...DEFAULT_MASK_FIELDS,
+                    ...cfg.maskFields,
+                ]))
+                : [...DEFAULT_MASK_FIELDS];
+        this.#maxArrayLength = cfg.maxArrayLength ?? 100;
+        this.#filterEvents = cfg.filterEvents ?? [];
+        this.#context = context;
+        this.#appName = cfg.name;
+        this.#appVersion = cfg.version;
+        this.#appEnv = cfg.env;
+    }
+    get appId() {
+        if (this.#appName && this.#appVersion && this.#appEnv) {
+            return `${this.#appName}-${this.#appVersion}-${this.#appEnv}`;
+        }
+        return undefined;
+    }
+    log(message, ...optionalParams) {
+        this.#writeLog(LogLevel.LOG, message, optionalParams);
+    }
+    error(message, ...optionalParams) {
+        this.#writeLog(LogLevel.ERROR, message, optionalParams);
+    }
+    warn(message, ...optionalParams) {
+        this.#writeLog(LogLevel.WARN, message, optionalParams);
+    }
+    debug(message, ...optionalParams) {
+        this.#writeLog(LogLevel.DEBUG, message, optionalParams);
+    }
+    verbose(message, ...optionalParams) {
+        this.#writeLog(LogLevel.VERBOSE, message, optionalParams);
+    }
+    fatal(message, ...optionalParams) {
+        this.#writeLog(LogLevel.FATAL, message, optionalParams);
+    }
+    #writeLog(level, message, optionalParams) {
+        if (!this.#shouldLog(level)) {
+            return;
+        }
+        const { preparedMessage, invalidMessageInfo, messageError, messageExtra, } = this.#prepareMessage(message);
+        const { error, extra } = this.#extractErrorAndExtra(optionalParams, level);
+        const finalError = messageError || error;
+        const finalExtra = {
+            ...messageExtra,
+            ...extra,
+        };
+        const logEntry = this.#createLogEntry(level, preparedMessage, finalExtra, finalError, invalidMessageInfo);
+        const sanitizedLogEntry = sanitizeLogEntry(logEntry, {
+            maskFields: this.#maskFields,
+            maxArrayLength: this.#maxArrayLength,
+        });
+        const output = this.#isDevelopment
+            ? formatColoredJson(sanitizedLogEntry, level)
+            : safeStringify(sanitizedLogEntry);
+        console.log(output);
+    }
+    #prepareMessage(message) {
+        if (typeof message === 'string') {
+            return { preparedMessage: message };
+        }
+        if (message instanceof Error) {
+            return {
+                preparedMessage: message.message,
+                messageError: message,
+            };
+        }
+        if (isPlainObject(message)) {
+            const foundError = findNestedError(message);
+            if (foundError) {
+                return {
+                    preparedMessage: foundError.message,
+                    messageError: foundError,
+                    messageExtra: message,
+                };
+            }
+            return {
+                preparedMessage: 'Object logged',
+                messageExtra: message,
+            };
+        }
+        const stack = new Error().stack
+            ?.split('\n')
+            .slice(2, 7)
+            .join('\n');
+        const preparedMessage = message === null || message === undefined
+            ? `[${String(message)}]`
+            : `[OBJECT]: ${safeStringify(message)}`;
+        const invalidMessageInfo = {
+            invalidMessageWarning: 'Logger called with non-string message parameter',
+            invalidMessageCallstack: stack,
+            originalMessageType: typeof message,
+            originalMessage: safeStringify(message),
+        };
+        return {
+            preparedMessage,
+            invalidMessageInfo,
+        };
+    }
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: handles multiple error extraction patterns
+    #extractErrorAndExtra(params, level) {
+        let error = null;
+        const extra = {};
+        for (const param of params) {
+            if (param instanceof Error) {
+                error = param;
+            }
+            else if (typeof param === 'string') {
+                const isErrorLevel = level === LogLevel.WARN ||
+                    level === LogLevel.ERROR ||
+                    level === LogLevel.FATAL;
+                if (isErrorLevel) {
+                    error = new Error(param);
+                }
+                else {
+                    extra.context = param;
+                }
+            }
+            else if (isPlainObject(param)) {
+                const isErrorLevel = level === LogLevel.WARN ||
+                    level === LogLevel.ERROR ||
+                    level === LogLevel.FATAL;
+                if (param.err instanceof Error) {
+                    error = param.err;
+                    const { err: _, ...rest } = param;
+                    Object.assign(extra, rest);
+                }
+                else if (param.error instanceof Error) {
+                    error = param.error;
+                    const { error: _, ...rest } = param;
+                    Object.assign(extra, rest);
+                }
+                else if (isErrorLevel &&
+                    typeof param.err === 'string') {
+                    error = new Error(param.err);
+                    const { err: _, ...rest } = param;
+                    Object.assign(extra, rest);
+                }
+                else if (isErrorLevel &&
+                    typeof param.error === 'string') {
+                    error = new Error(param.error);
+                    const { error: _, ...rest } = param;
+                    Object.assign(extra, rest);
+                }
+                else {
+                    const foundError = findNestedError(param);
+                    if (foundError) {
+                        error = foundError;
+                    }
+                    Object.assign(extra, param);
+                }
+            }
+        }
+        return { error, extra };
+    }
+    #createLogEntry(level, message, extra, error, invalidMessageInfo) {
+        const ctx = this.#context
+            ? this.#context.getContext()
+            : {};
+        const logEntry = {
+            level,
+            timestamp: new Date().toISOString(),
+            pid: process.pid,
+            message,
+            ...(this.appId ? { appId: this.appId } : {}),
+            ...ctx,
+            ...extra,
+            ...(invalidMessageInfo || {}),
+        };
+        if (error) {
+            logEntry.error = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack?.replace(/\n(\s+)?/g, ','),
+            };
+        }
+        return logEntry;
+    }
+    #shouldLog(level) {
+        const configuredIdx = LOG_LEVELS.indexOf(this.logLevel);
+        const messageIdx = LOG_LEVELS.indexOf(level);
+        if (messageIdx < configuredIdx) {
+            return false;
+        }
+        if (this.#context) {
+            const ctx = this.#context.getContext();
+            if (ctx.event &&
+                this.#filterEvents.includes(ctx.event)) {
+                return false;
+            }
+        }
+        return true;
+    }
+}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/esm/sanitize.js

@@ -0,0 +1,183 @@
+import { isPlainObject } from '@arkv/shared';
+export function sanitizeLogEntry(obj, options, visited = new WeakSet()) {
+    if (visited.has(obj)) {
+        return {
+            '[Circular]': 'circular reference detected',
+        };
+    }
+    visited.add(obj);
+    const cleaned = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const shouldMask = options.maskFields.some(field => key.toLowerCase().includes(field.toLowerCase()));
+        if (shouldMask) {
+            cleaned[key] = '[MASKED]';
+        }
+        else {
+            const safeValue = makeSafeForJson(value, options);
+            if (safeValue !== undefined) {
+                if (Array.isArray(safeValue)) {
+                    cleaned[key] = sanitizeArray(safeValue, options, visited);
+                }
+                else if (isPlainObject(safeValue)) {
+                    cleaned[key] = sanitizeLogEntry(safeValue, options, visited);
+                }
+                else {
+                    cleaned[key] = safeValue;
+                }
+            }
+        }
+    }
+    return cleaned;
+}
+function sanitizeArray(array, options, visited) {
+    return array.map(item => {
+        if (isPlainObject(item)) {
+            return sanitizeLogEntry(item, options, visited);
+        }
+        if (Array.isArray(item)) {
+            return sanitizeArray(item, options, visited);
+        }
+        return makeSafeForJson(item, options);
+    });
+}
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: recursive error search
+export function findNestedError(obj, visited = new WeakSet()) {
+    if (!obj || typeof obj !== 'object') {
+        return null;
+    }
+    if (visited.has(obj)) {
+        return null;
+    }
+    visited.add(obj);
+    for (const value of Object.values(obj)) {
+        if (value instanceof Error) {
+            return value;
+        }
+        if (isPlainObject(value)) {
+            const nestedError = findNestedError(value, visited);
+            if (nestedError) {
+                return nestedError;
+            }
+        }
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item instanceof Error) {
+                    return item;
+                }
+                if (isPlainObject(item)) {
+                    const nestedError = findNestedError(item, visited);
+                    if (nestedError) {
+                        return nestedError;
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: handles many type serialization cases
+function makeSafeForJson(value, options) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const valueType = typeof value;
+    if (valueType === 'function') {
+        return `[Function: ${value.name || 'anonymous'}]`;
+    }
+    if (valueType === 'symbol') {
+        return `[Symbol: ${value.toString()}]`;
+    }
+    if (valueType === 'bigint') {
+        return `[BigInt: ${value.toString()}]`;
+    }
+    if (valueType !== 'object') {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (value instanceof RegExp) {
+        return `[RegExp: ${value.toString()}]`;
+    }
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: value.message,
+            stack: value.stack?.replace(/\n(\s+)?/g, ','),
+        };
+    }
+    if (typeof FormData !== 'undefined' &&
+        value instanceof FormData) {
+        const entries = {};
+        try {
+            for (const [key, val] of value.entries()) {
+                if (val &&
+                    typeof val === 'object' &&
+                    'name' in val &&
+                    'size' in val &&
+                    'type' in val) {
+                    const file = val;
+                    entries[key] =
+                        `[File: ${file.name} (${file.size} bytes, ${file.type})]`;
+                }
+                else {
+                    entries[key] = val;
+                }
+            }
+            return { '[FormData]': entries };
+        }
+        catch {
+            return '[FormData: unable to read entries]';
+        }
+    }
+    if (value &&
+        typeof value === 'object' &&
+        'name' in value &&
+        'size' in value &&
+        'type' in value &&
+        typeof value
+            .arrayBuffer === 'function') {
+        const file = value;
+        return `[File: ${file.name} (${file.size} bytes, ${file.type})]`;
+    }
+    if (typeof Blob !== 'undefined' &&
+        value instanceof Blob) {
+        return `[Blob: ${value.size} bytes, ${value.type}]`;
+    }
+    if (typeof ArrayBuffer !== 'undefined' &&
+        value instanceof ArrayBuffer) {
+        return `[ArrayBuffer: ${value.byteLength} bytes]`;
+    }
+    if (Array.isArray(value)) {
+        return sliceArray(value, options);
+    }
+    if (isPlainObject(value)) {
+        return value;
+    }
+    try {
+        JSON.stringify(value);
+        return value;
+    }
+    catch {
+        if (value
+            .constructor?.name) {
+            return `[${value.constructor.name}: object not serializable]`;
+        }
+        return '[Object: not serializable]';
+    }
+}
+function sliceArray(array, options) {
+    if (array.length <= options.maxArrayLength) {
+        return array.map(item => makeSafeForJson(item, options));
+    }
+    const slicedArray = array
+        .slice(0, options.maxArrayLength)
+        .map(item => makeSafeForJson(item, options));
+    return [
+        ...slicedArray,
+        `[TRUNCATED: ${array.length - options.maxArrayLength} more items]`,
+    ];
+}

package/dist/esm/test-utils.js

@@ -0,0 +1,22 @@
+import { strip } from '@arkv/colors';
+import { LogLevel } from './types.js';
+export function parseLogOutput(logCall) {
+    const cleanLog = strip(logCall);
+    return JSON.parse(cleanLog);
+}
+export const defaultTestConfig = {
+    name: 'test-app',
+    version: '1.0.0',
+    env: 'local',
+    isDevelopment: true,
+    level: LogLevel.DEBUG,
+    maskFields: [
+        'password',
+        'token',
+        'apiKey',
+        'apiSecret',
+        'apiPass',
+    ],
+    filterEvents: ['/health'],
+    maxArrayLength: 1,
+};

package/dist/esm/types.js

@@ -0,0 +1,27 @@
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["VERBOSE"] = "verbose";
+    LogLevel["DEBUG"] = "debug";
+    LogLevel["LOG"] = "log";
+    LogLevel["WARN"] = "warn";
+    LogLevel["ERROR"] = "error";
+    LogLevel["FATAL"] = "fatal";
+})(LogLevel || (LogLevel = {}));
+export const LOG_LEVELS = [
+    LogLevel.VERBOSE,
+    LogLevel.DEBUG,
+    LogLevel.LOG,
+    LogLevel.WARN,
+    LogLevel.ERROR,
+    LogLevel.FATAL,
+];
+export const DEFAULT_MASK_FIELDS = [
+    'password',
+    'secret',
+    'token',
+    'authorization',
+    'cookie',
+    'apiKey',
+    'apiSecret',
+    'apiPass',
+];

package/dist/types/context.d.ts

@@ -0,0 +1,7 @@
+import type { AsyncContext } from './types.js';
+export declare class ContextStore {
+    private readonly asyncLocalStorage;
+    getContext(): AsyncContext;
+    updateContext(obj: Partial<AsyncContext>): void;
+    runWithContext<T>(context: AsyncContext, callback: () => T): T;
+}

package/dist/types/format.d.ts

@@ -0,0 +1,2 @@
+import type { LogEntry, LogLevel } from './types.js';
+export declare function formatColoredJson(obj: LogEntry, level: LogLevel): string;

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { ContextStore } from './context.js';
+export { Logger } from './logger.js';
+export { type AsyncContext, DEFAULT_MASK_FIELDS, LOG_LEVELS, type LogEntry, type LoggerConfig, LogLevel, } from './types.js';

package/dist/types/logger.d.ts

@@ -0,0 +1,26 @@
+import type { ContextStore } from './context.js';
+import { type LoggerConfig, LogLevel } from './types.js';
+export declare class Logger {
+    #private;
+    readonly logLevel: LogLevel;
+    constructor(config?: LoggerConfig, context?: ContextStore);
+    get appId(): string | undefined;
+    log(message: string, ...optionalParams: unknown[]): void;
+    log(message: Record<string, unknown>): void;
+    log(message: Error): void;
+    error(message: string, ...optionalParams: unknown[]): void;
+    error(message: Record<string, unknown>): void;
+    error(message: Error): void;
+    warn(message: string, ...optionalParams: unknown[]): void;
+    warn(message: Record<string, unknown>): void;
+    warn(message: Error): void;
+    debug(message: string, ...optionalParams: unknown[]): void;
+    debug(message: Record<string, unknown>): void;
+    debug(message: Error): void;
+    verbose(message: string, ...optionalParams: unknown[]): void;
+    verbose(message: Record<string, unknown>): void;
+    verbose(message: Error): void;
+    fatal(message: string, ...optionalParams: unknown[]): void;
+    fatal(message: Record<string, unknown>): void;
+    fatal(message: Error): void;
+}

package/dist/types/sanitize.d.ts

@@ -0,0 +1,8 @@
+import type { LogEntry } from './types.js';
+interface SanitizeOptions {
+    maskFields: string[];
+    maxArrayLength: number;
+}
+export declare function sanitizeLogEntry(obj: LogEntry, options: SanitizeOptions, visited?: WeakSet<WeakKey>): LogEntry;
+export declare function findNestedError(obj: Record<string, unknown>, visited?: WeakSet<WeakKey>): Error | null;
+export {};

package/dist/types/test-utils.d.ts

@@ -0,0 +1,3 @@
+import type { LoggerConfig } from './types.js';
+export declare function parseLogOutput(logCall: string): any;
+export declare const defaultTestConfig: LoggerConfig;

package/dist/types/types.d.ts

@@ -0,0 +1,37 @@
+export declare enum LogLevel {
+    VERBOSE = "verbose",
+    DEBUG = "debug",
+    LOG = "log",
+    WARN = "warn",
+    ERROR = "error",
+    FATAL = "fatal"
+}
+export declare const LOG_LEVELS: LogLevel[];
+export interface AsyncContext {
+    requestId?: string;
+    userId?: string;
+    orgId?: string;
+    method?: string;
+    event?: string;
+    context?: string;
+    flow?: string;
+    [key: string]: unknown;
+}
+export interface LoggerConfig {
+    name?: string;
+    version?: string;
+    env?: string;
+    level?: LogLevel;
+    /** Defaults to `process.env.NODE_ENV !== 'production'` */
+    isDevelopment?: boolean;
+    /** Merged with DEFAULT_MASK_FIELDS */
+    maskFields?: string[];
+    /** Events to skip logging for */
+    filterEvents?: string[];
+    /** Truncate arrays beyond this length */
+    maxArrayLength?: number;
+}
+export type LogEntry = Record<string, unknown> & {
+    error?: Error;
+};
+export declare const DEFAULT_MASK_FIELDS: string[];