@arkv/logger 0.1.1

package/README.md

@@ -0,0 +1,200 @@
+# @arkv/logger
+
+Framework-agnostic structured logger with async context, sanitization, and colored output.
+
+## Install
+
+```bash
+bun add @arkv/logger
+# or
+npm install @arkv/logger
+```
+
+## Usage
+
+### Basic Logging
+
+```typescript
+import { Logger } from '@arkv/logger';
+
+const logger = new Logger({
+  name: 'my-app',
+  version: '1.0.0',
+  env: 'production',
+});
+
+logger.log('Server started');
+logger.debug('Loading config', { path: '/etc/app' });
+logger.warn('Disk usage high', { usage: 92 });
+logger.error('Request failed', new Error('timeout'));
+```
+
+### Log Levels
+
+Six levels in ascending severity:
+
+```typescript
+import { Logger, LogLevel } from '@arkv/logger';
+
+const logger = new Logger({ level: LogLevel.WARN });
+
+logger.debug('skipped');  // below WARN, not logged
+logger.warn('logged');    // WARN and above are logged
+logger.error('logged');
+logger.fatal('logged');
+```
+
+| Level | Value |
+|-------|-------|
+| `LogLevel.VERBOSE` | `'verbose'` |
+| `LogLevel.DEBUG` | `'debug'` |
+| `LogLevel.LOG` | `'log'` |
+| `LogLevel.WARN` | `'warn'` |
+| `LogLevel.ERROR` | `'error'` |
+| `LogLevel.FATAL` | `'fatal'` |
+
+### Async Context
+
+Track request-scoped data across async boundaries using `ContextStore` (backed by `AsyncLocalStorage`):
+
+```typescript
+import { Logger, ContextStore } from '@arkv/logger';
+
+const context = new ContextStore();
+const logger = new Logger({ name: 'api' }, context);
+
+function handleRequest(req) {
+  context.runWithContext(
+    { requestId: req.id, userId: req.user },
+    () => {
+      // requestId and userId are automatically
+      // included in every log entry
+      logger.log('Processing request');
+      doWork();
+    },
+  );
+}
+```
+
+### Sensitive Field Masking
+
+Fields matching known sensitive names are automatically replaced with `[MASKED]`:
+
+```typescript
+logger.log('User login', {
+  username: 'alice',
+  password: 'secret',    // → [MASKED]
+  token: 'jwt-abc',      // → [MASKED]
+  apiKey: 'key-123',     // → [MASKED]
+});
+```
+
+Default masked fields: `password`, `secret`, `token`, `authorization`, `cookie`, `apiKey`, `apiSecret`, `apiPass`. Add custom fields via config:
+
+```typescript
+const logger = new Logger({
+  maskFields: ['ssn', 'creditCard'],
+});
+```
+
+### Error Handling
+
+Errors are automatically extracted and serialized from multiple patterns:
+
+```typescript
+// Direct Error object
+logger.error('Failed', new Error('timeout'));
+
+// Error as message
+logger.error(new Error('crash'));
+
+// Wrapped in object
+logger.error('Op failed', { err: new Error('db') });
+logger.error('Op failed', { error: new Error('db') });
+
+// String shorthand at error/warn/fatal level
+logger.error('Op failed', { error: 'connection refused' });
+
+// Deeply nested errors are found automatically
+logger.error('Op failed', {
+  metadata: { nested: { err: new Error('deep') } },
+});
+```
+
+### Development vs Production Output
+
+In development (`NODE_ENV !== 'production'`), output is colored JSON for readability. In production, output is plain JSON for log aggregators:
+
+```typescript
+// Colored dev output (default)
+const dev = new Logger({ isDevelopment: true });
+
+// Plain JSON for production
+const prod = new Logger({ isDevelopment: false });
+```
+
+### Event Filtering
+
+Suppress logs for specific events (e.g. health checks):
+
+```typescript
+const logger = new Logger(
+  { filterEvents: ['/health', '/ready'] },
+  contextStore,
+);
+```
+
+When the context's `event` field matches a filtered event, the log is silently dropped.
+
+## API
+
+### `Logger`
+
+```typescript
+new Logger(config?: LoggerConfig, context?: ContextStore)
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `logLevel` | `LogLevel` | Current log level (read-only) |
+| `appId` | `string \| undefined` | `name-version-env` or `undefined` |
+
+| Method | Description |
+|--------|-------------|
+| `log(message, ...params)` | Log at `log` level |
+| `debug(message, ...params)` | Log at `debug` level |
+| `verbose(message, ...params)` | Log at `verbose` level |
+| `warn(message, ...params)` | Log at `warn` level |
+| `error(message, ...params)` | Log at `error` level |
+| `fatal(message, ...params)` | Log at `fatal` level |
+
+Each method accepts `string`, `Record<string, unknown>`, or `Error` as the message, plus optional extra params.
+
+### `LoggerConfig`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | `string` | — | Application name |
+| `version` | `string` | — | Application version |
+| `env` | `string` | — | Environment name |
+| `level` | `LogLevel` | `DEBUG` | Minimum log level |
+| `isDevelopment` | `boolean` | `NODE_ENV !== 'production'` | Colored vs plain JSON output |
+| `maskFields` | `string[]` | `[]` | Additional fields to mask (merged with defaults) |
+| `filterEvents` | `string[]` | `[]` | Context events to suppress |
+| `maxArrayLength` | `number` | `100` | Max array items before truncation |
+
+### `ContextStore`
+
+```typescript
+new ContextStore()
+```
+
+| Method | Description |
+|--------|-------------|
+| `getContext()` | Get current async context |
+| `updateContext(partial)` | Merge partial update into current context |
+| `runWithContext(ctx, callback)` | Execute callback within a context |
+
+## License
+
+[MIT](../../LICENSE)

package/dist/cjs/context.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextStore = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
+class ContextStore {
+    asyncLocalStorage = new node_async_hooks_1.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);
+    }
+}
+exports.ContextStore = ContextStore;

package/dist/cjs/format.js

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

package/dist/cjs/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogLevel = exports.LOG_LEVELS = exports.DEFAULT_MASK_FIELDS = exports.Logger = exports.ContextStore = void 0;
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "ContextStore", { enumerable: true, get: function () { return context_js_1.ContextStore; } });
+var logger_js_1 = require("./logger.js");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_js_1.Logger; } });
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "DEFAULT_MASK_FIELDS", { enumerable: true, get: function () { return types_js_1.DEFAULT_MASK_FIELDS; } });
+Object.defineProperty(exports, "LOG_LEVELS", { enumerable: true, get: function () { return types_js_1.LOG_LEVELS; } });
+Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return types_js_1.LogLevel; } });

package/dist/cjs/logger.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const shared_1 = require("@arkv/shared");
+const format_js_1 = require("./format.js");
+const sanitize_js_1 = require("./sanitize.js");
+const types_js_1 = require("./types.js");
+class Logger {
+    logLevel;
+    #isDevelopment;
+    #maskFields;
+    #maxArrayLength;
+    #filterEvents;
+    #context;
+    #appName;
+    #appVersion;
+    #appEnv;
+    constructor(config, context) {
+        const cfg = config ?? {};
+        this.logLevel = cfg.level ?? types_js_1.LogLevel.DEBUG;
+        this.#isDevelopment =
+            cfg.isDevelopment ??
+                process.env.NODE_ENV !== 'production';
+        this.#maskFields =
+            cfg.maskFields && cfg.maskFields.length > 0
+                ? Array.from(new Set([
+                    ...types_js_1.DEFAULT_MASK_FIELDS,
+                    ...cfg.maskFields,
+                ]))
+                : [...types_js_1.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(types_js_1.LogLevel.LOG, message, optionalParams);
+    }
+    error(message, ...optionalParams) {
+        this.#writeLog(types_js_1.LogLevel.ERROR, message, optionalParams);
+    }
+    warn(message, ...optionalParams) {
+        this.#writeLog(types_js_1.LogLevel.WARN, message, optionalParams);
+    }
+    debug(message, ...optionalParams) {
+        this.#writeLog(types_js_1.LogLevel.DEBUG, message, optionalParams);
+    }
+    verbose(message, ...optionalParams) {
+        this.#writeLog(types_js_1.LogLevel.VERBOSE, message, optionalParams);
+    }
+    fatal(message, ...optionalParams) {
+        this.#writeLog(types_js_1.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 = (0, sanitize_js_1.sanitizeLogEntry)(logEntry, {
+            maskFields: this.#maskFields,
+            maxArrayLength: this.#maxArrayLength,
+        });
+        const output = this.#isDevelopment
+            ? (0, format_js_1.formatColoredJson)(sanitizedLogEntry, level)
+            : (0, shared_1.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 ((0, shared_1.isPlainObject)(message)) {
+            const foundError = (0, sanitize_js_1.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]: ${(0, shared_1.safeStringify)(message)}`;
+        const invalidMessageInfo = {
+            invalidMessageWarning: 'Logger called with non-string message parameter',
+            invalidMessageCallstack: stack,
+            originalMessageType: typeof message,
+            originalMessage: (0, shared_1.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 === types_js_1.LogLevel.WARN ||
+                    level === types_js_1.LogLevel.ERROR ||
+                    level === types_js_1.LogLevel.FATAL;
+                if (isErrorLevel) {
+                    error = new Error(param);
+                }
+                else {
+                    extra.context = param;
+                }
+            }
+            else if ((0, shared_1.isPlainObject)(param)) {
+                const isErrorLevel = level === types_js_1.LogLevel.WARN ||
+                    level === types_js_1.LogLevel.ERROR ||
+                    level === types_js_1.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 = (0, sanitize_js_1.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 = types_js_1.LOG_LEVELS.indexOf(this.logLevel);
+        const messageIdx = types_js_1.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;
+    }
+}
+exports.Logger = Logger;

package/dist/cjs/package.json

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

package/dist/cjs/sanitize.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeLogEntry = sanitizeLogEntry;
+exports.findNestedError = findNestedError;
+const shared_1 = require("@arkv/shared");
+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 ((0, shared_1.isPlainObject)(safeValue)) {
+                    cleaned[key] = sanitizeLogEntry(safeValue, options, visited);
+                }
+                else {
+                    cleaned[key] = safeValue;
+                }
+            }
+        }
+    }
+    return cleaned;
+}
+function sanitizeArray(array, options, visited) {
+    return array.map(item => {
+        if ((0, shared_1.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
+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 ((0, shared_1.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 ((0, shared_1.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 ((0, shared_1.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]`,
+    ];
+}