@jaypie/logger 1.2.17 → 1.2.19

package/dist/cjs/src/limits.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Caller-facing limit options. `false` explicitly disables a limit;
+ * `undefined` resolves from env vars, then defaults.
+ */
+export interface SerializationLimitOptions {
+    maxDepth?: number | false;
+    maxEntryBytes?: number | false;
+    maxStringLength?: number | false;
+}
+/**
+ * Resolved limits. `undefined` means the limit is off.
+ */
+export interface SerializationLimits {
+    maxDepth?: number;
+    maxEntryBytes?: number;
+    maxStringLength?: number;
+}
+/** Characters preserved when an oversized entry truncates an attribute */
+export declare const ENTRY_PREVIEW_LENGTH = 72;
+/**
+ * Resolve limits from explicit options, env vars, then defaults.
+ * `maxEntryBytes` defaults on (payloads must fit the log pipeline);
+ * `maxDepth` and `maxStringLength` default off.
+ */
+export declare function resolveSerializationLimits(options?: SerializationLimitOptions): SerializationLimits;
+export declare function hasValueLimits(limits: SerializationLimits): boolean;
+export declare function byteLength(value: unknown): number;
+/**
+ * Keep the first `maxLength` characters and append a visible marker
+ * preserving the dropped size
+ */
+export declare function truncateString(value: string, maxLength: number): string;
+/**
+ * Fit a string to a byte budget, reserving room for the marker and
+ * never cutting below the preview length
+ */
+export declare function truncateToBudget(value: string, budgetBytes: number): string;
+/**
+ * Walk a value applying maxStringLength and maxDepth. Returns a new value;
+ * never mutates the input. Only plain objects and arrays are traversed so
+ * class instances (Error, Date, ...) keep their serialization behavior.
+ */
+export declare function applyValueLimits(value: unknown, limits: SerializationLimits, depth?: number, seen?: WeakSet<object>): unknown;
+/**
+ * Fit a serialized log entry under maxEntryBytes. Truncates the top-level
+ * attributes of `data` largest-first to short previews until the entry fits,
+ * collapsing `data` to a byte-count marker only as a last resort. When
+ * `syncMessageToData` is set (var entries and single-object messages, where
+ * `message` mirrors `data`), the message is rebuilt from the truncated data.
+ * Returns a new entry; never mutates the input.
+ */
+export declare function enforceEntryLimit(entry: Record<string, unknown>, { maxEntryBytes, syncMessageToData, }: {
+    maxEntryBytes: number;
+    syncMessageToData?: boolean;
+}): Record<string, unknown>;

package/dist/esm/index.d.ts

@@ -1,8 +1,142 @@
-import Logger from "./Logger";
-import { createLogger } from "./JaypieLogger";
-import { FORMAT, LEVEL } from "./constants";
-import { _resetDatadogTransport, getDatadogTransport, isDatadogForwardingEnabled } from "./datadogTransport";
-import { redactAuth, sanitizeAuth } from "./sanitizeAuth";
-export { FORMAT, LEVEL, Logger, _resetDatadogTransport, createLogger, getDatadogTransport, isDatadogForwardingEnabled, redactAuth, sanitizeAuth, };
-export declare const log: import("./JaypieLogger").default;
-export default log;
+/**
+ * Caller-facing limit options. `false` explicitly disables a limit;
+ * `undefined` resolves from env vars, then defaults.
+ */
+interface SerializationLimitOptions {
+    maxDepth?: number | false;
+    maxEntryBytes?: number | false;
+    maxStringLength?: number | false;
+}
+/**
+ * Resolved limits. `undefined` means the limit is off.
+ */
+interface SerializationLimits {
+    maxDepth?: number;
+    maxEntryBytes?: number;
+    maxStringLength?: number;
+}
+
+type LogLevel = string;
+type LogFormat = "json" | "text";
+type Tags = Record<string, string>;
+interface LoggerOptions extends SerializationLimitOptions {
+    format?: LogFormat;
+    level?: LogLevel;
+    levelField?: boolean | string;
+    tags?: Tags;
+    varLevel?: LogLevel;
+}
+type LogMethod = {
+    (...messages: unknown[]): void;
+    var: (messageObject: unknown, messageValue?: unknown) => void;
+};
+declare class Logger {
+    debug: LogMethod;
+    error: LogMethod;
+    fatal: LogMethod;
+    info: LogMethod;
+    options: LoggerOptions;
+    tags: Tags;
+    trace: LogMethod;
+    var: (messageObject: unknown, messageValue?: unknown) => void;
+    warn: LogMethod;
+    private levelField;
+    private limits;
+    constructor({ format, level, levelField, maxDepth, maxEntryBytes, maxStringLength, tags, varLevel, }?: LoggerOptions);
+    private createLogMethod;
+    /**
+     * Update serialization limits at runtime. Pass a number to set a limit,
+     * `false` to disable one; omitted keys are unchanged.
+     */
+    config(options?: SerializationLimitOptions): void;
+    tag(key: unknown, value?: unknown): void;
+    untag(key: unknown): void;
+    with(key: unknown, value?: unknown): Logger;
+}
+
+interface JaypieLoggerOptions extends SerializationLimitOptions {
+    level?: string;
+    tags?: Record<string, string>;
+}
+declare class JaypieLogger {
+    debug: Logger["debug"];
+    error: Logger["error"];
+    fatal: Logger["fatal"];
+    info: Logger["info"];
+    level: string;
+    trace: Logger["trace"];
+    var: Logger["var"];
+    warn: Logger["warn"];
+    private _errorCount;
+    private _logger;
+    private _loggers;
+    private _params;
+    private _report;
+    private _sessionActive;
+    private _tags;
+    private _warnCount;
+    private _withLoggers;
+    constructor({ level, maxDepth, maxEntryBytes, maxStringLength, tags, }?: JaypieLoggerOptions);
+    /**
+     * Update serialization limits at runtime for this logger and all loggers
+     * derived from it (lib, with, flag). Pass a number to set a limit,
+     * `false` to disable one; omitted keys are unchanged. Persists across
+     * init().
+     */
+    config(options?: SerializationLimitOptions): void;
+    flag(flag?: string): JaypieLogger;
+    init(): void;
+    lib({ level, lib, tags, }?: {
+        level?: string;
+        lib?: string;
+        tags?: Record<string, string>;
+    }): JaypieLogger;
+    report(data: Record<string, unknown>): void;
+    setup(tags?: Record<string, unknown>): void;
+    tag(tags: Record<string, unknown>): void;
+    teardown(): void;
+    untag(key: unknown): void;
+    with(key: unknown, value?: unknown): JaypieLogger;
+}
+declare function createLogger(tags?: Record<string, string>): JaypieLogger;
+
+declare const FORMAT: {
+    readonly JSON: "json";
+    readonly TEXT: "text";
+};
+declare const LEVEL: {
+    readonly ALL: "all";
+    readonly DEBUG: "debug";
+    readonly ERROR: "error";
+    readonly FATAL: "fatal";
+    readonly INFO: "info";
+    readonly SILENT: "silent";
+    readonly TRACE: "trace";
+    readonly WARN: "warn";
+};
+
+declare function isDatadogForwardingEnabled(): boolean;
+declare class DatadogLogTransport {
+    private _beforeExitHandler;
+    private _buffer;
+    private _flushTimer;
+    private _ddsource;
+    private _env;
+    private _hostname;
+    private _service;
+    private _site;
+    constructor();
+    send(line: string, level: string): void;
+    flush(): void;
+    destroy(): void;
+}
+declare function getDatadogTransport(): DatadogLogTransport | null;
+declare function _resetDatadogTransport(): void;
+
+declare function redactAuth(value: unknown): string;
+declare function sanitizeAuth(value: unknown): unknown;
+
+declare const log: JaypieLogger;
+
+export { FORMAT, LEVEL, Logger, _resetDatadogTransport, createLogger, log as default, getDatadogTransport, isDatadogForwardingEnabled, log, redactAuth, sanitizeAuth };
+export type { SerializationLimitOptions, SerializationLimits };

package/dist/esm/index.js

@@ -4,8 +4,16 @@ import { request } from 'node:https';
 
 const DEFAULT = {
     LEVEL: "debug",
+    // CloudWatch Logs caps events at 256KB and fronts Datadog in Lambda;
+    // Datadog's own per-log cap is 1MB. Truncate deliberately below both.
+    MAX_ENTRY_BYTES: 262144,
     VAR_LEVEL: "debug",
 };
+const LIMIT_ENV = {
+    MAX_DEPTH: "LOG_MAX_DEPTH",
+    MAX_ENTRY_BYTES: "LOG_MAX_ENTRY_BYTES",
+    MAX_STRING: "LOG_MAX_STRING",
+};
 const ERROR_PREFIX = "[logger]";
 const ERROR = {
     VAR: {
@@ -59,6 +67,207 @@ const DATADOG_TRANSPORT = {
     MAX_BATCH_SIZE: 100,
 };
 
+//
+//
+// Constants
+//
+const CIRCULAR_PLACEHOLDER = "[Circular]";
+const DISABLED_ENV_VALUES = ["", "0", "false", "none", "off"];
+const ELLIPSIS = "…";
+// Reserve headroom for the truncation marker when fitting a string to a
+// byte budget
+const MARKER_RESERVE_BYTES = 64;
+/** Characters preserved when an oversized entry truncates an attribute */
+const ENTRY_PREVIEW_LENGTH = 72;
+//
+//
+// Helpers
+//
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function normalizeLimit(option) {
+    if (option === false)
+        return undefined;
+    if (typeof option === "number" && Number.isFinite(option) && option > 0) {
+        return Math.floor(option);
+    }
+    return undefined;
+}
+function resolveLimit(option, envKey, defaultValue) {
+    if (option !== undefined) {
+        return normalizeLimit(option);
+    }
+    const raw = process.env[envKey];
+    if (raw !== undefined) {
+        if (DISABLED_ENV_VALUES.includes(raw.toLowerCase()))
+            return undefined;
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return defaultValue;
+}
+function truncationMarker(droppedChars) {
+    return `${ELLIPSIS} [truncated ${droppedChars.toLocaleString("en-US")} chars]`;
+}
+//
+//
+// Main
+//
+/**
+ * Resolve limits from explicit options, env vars, then defaults.
+ * `maxEntryBytes` defaults on (payloads must fit the log pipeline);
+ * `maxDepth` and `maxStringLength` default off.
+ */
+function resolveSerializationLimits(options = {}) {
+    return {
+        maxDepth: resolveLimit(options.maxDepth, LIMIT_ENV.MAX_DEPTH),
+        maxEntryBytes: resolveLimit(options.maxEntryBytes, LIMIT_ENV.MAX_ENTRY_BYTES, DEFAULT.MAX_ENTRY_BYTES),
+        maxStringLength: resolveLimit(options.maxStringLength, LIMIT_ENV.MAX_STRING),
+    };
+}
+function hasValueLimits(limits) {
+    return limits.maxDepth !== undefined || limits.maxStringLength !== undefined;
+}
+function byteLength(value) {
+    try {
+        const str = typeof value === "string" ? value : JSON.stringify(value);
+        return Buffer.byteLength(str ?? "", "utf8");
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Keep the first `maxLength` characters and append a visible marker
+ * preserving the dropped size
+ */
+function truncateString(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    return value.slice(0, maxLength) + truncationMarker(value.length - maxLength);
+}
+/**
+ * Fit a string to a byte budget, reserving room for the marker and
+ * never cutting below the preview length
+ */
+function truncateToBudget(value, budgetBytes) {
+    if (Buffer.byteLength(value, "utf8") <= budgetBytes)
+        return value;
+    const maxLength = Math.max(ENTRY_PREVIEW_LENGTH, budgetBytes - MARKER_RESERVE_BYTES);
+    return truncateString(value, maxLength);
+}
+/**
+ * Walk a value applying maxStringLength and maxDepth. Returns a new value;
+ * never mutates the input. Only plain objects and arrays are traversed so
+ * class instances (Error, Date, ...) keep their serialization behavior.
+ */
+function applyValueLimits(value, limits, depth = 0, seen = new WeakSet()) {
+    const { maxDepth, maxStringLength } = limits;
+    if (typeof value === "string") {
+        return maxStringLength !== undefined
+            ? truncateString(value, maxStringLength)
+            : value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return CIRCULAR_PLACEHOLDER;
+        if (maxDepth !== undefined && depth > maxDepth) {
+            return `[Array(${value.length})]`;
+        }
+        seen.add(value);
+        const result = value.map((item) => applyValueLimits(item, limits, depth + 1, seen));
+        seen.delete(value);
+        return result;
+    }
+    if (isPlainObject(value)) {
+        if (seen.has(value))
+            return CIRCULAR_PLACEHOLDER;
+        if (maxDepth !== undefined && depth > maxDepth) {
+            return "[Object]";
+        }
+        seen.add(value);
+        const result = {};
+        for (const key of Object.keys(value)) {
+            result[key] = applyValueLimits(value[key], limits, depth + 1, seen);
+        }
+        seen.delete(value);
+        return result;
+    }
+    return value;
+}
+function truncateToPreview(value) {
+    const str = typeof value === "string"
+        ? value
+        : (JSON.stringify(value) ?? String(value));
+    if (str.length <= ENTRY_PREVIEW_LENGTH)
+        return value;
+    return truncateString(str, ENTRY_PREVIEW_LENGTH);
+}
+/**
+ * Fit a serialized log entry under maxEntryBytes. Truncates the top-level
+ * attributes of `data` largest-first to short previews until the entry fits,
+ * collapsing `data` to a byte-count marker only as a last resort. When
+ * `syncMessageToData` is set (var entries and single-object messages, where
+ * `message` mirrors `data`), the message is rebuilt from the truncated data.
+ * Returns a new entry; never mutates the input.
+ */
+function enforceEntryLimit(entry, { maxEntryBytes, syncMessageToData = false, }) {
+    const originalBytes = byteLength(entry);
+    if (originalBytes <= maxEntryBytes)
+        return entry;
+    const result = { ...entry };
+    const sync = () => {
+        if (syncMessageToData) {
+            result.message =
+                typeof result.data === "string"
+                    ? result.data
+                    : (JSON.stringify(result.data) ?? String(result.data));
+        }
+    };
+    const data = result.data;
+    if (typeof data === "string") {
+        result.data = truncateToPreview(data);
+        sync();
+    }
+    else if (Array.isArray(data) || isPlainObject(data)) {
+        const container = Array.isArray(data)
+            ? [...data]
+            : { ...data };
+        result.data = container;
+        const keys = Object.keys(container).sort((a, b) => byteLength(container[b]) - byteLength(container[a]));
+        for (const key of keys) {
+            container[key] = truncateToPreview(container[key]);
+            sync();
+            if (byteLength(result) <= maxEntryBytes)
+                return result;
+        }
+    }
+    else if (typeof result.message === "string") {
+        // No structured data: the message itself is oversized
+        const overhead = originalBytes - byteLength(result.message);
+        result.message = truncateToBudget(result.message, Math.max(ENTRY_PREVIEW_LENGTH, maxEntryBytes - overhead));
+    }
+    if (byteLength(result) <= maxEntryBytes)
+        return result;
+    // Last resort: entry is still oversized after attribute-level truncation
+    const marker = `[truncated ${originalBytes.toLocaleString("en-US")} bytes]`;
+    if ("data" in result) {
+        result.data = marker;
+        if (syncMessageToData)
+            result.message = marker;
+    }
+    else if (typeof result.message === "string") {
+        result.message = marker;
+    }
+    return result;
+}
+
 //
 // Key-based pipelines (match on var key name)
 //
@@ -650,12 +859,22 @@ function resolveLevelField(value) {
     return value;
 }
 class Logger {
-    constructor({ format = process.env.LOG_FORMAT || DEFAULT.LEVEL, level = process.env.LOG_LEVEL || DEFAULT.LEVEL, levelField, tags = {}, varLevel = process.env.LOG_VAR_LEVEL || DEFAULT.VAR_LEVEL, } = {}) {
+    constructor({ format = process.env.LOG_FORMAT || DEFAULT.LEVEL, level = process.env.LOG_LEVEL || DEFAULT.LEVEL, levelField, maxDepth, maxEntryBytes, maxStringLength, tags = {}, varLevel = process.env.LOG_VAR_LEVEL || DEFAULT.VAR_LEVEL, } = {}) {
         this.levelField = resolveLevelField(levelField);
+        this.limits = resolveSerializationLimits({
+            maxDepth,
+            maxEntryBytes,
+            maxStringLength,
+        });
         this.options = {
             format,
             level,
             levelField: this.levelField || undefined,
+            // Pin resolved limits (false = explicitly off) so child loggers
+            // created via with() inherit this config instead of re-resolving
+            maxDepth: this.limits.maxDepth ?? false,
+            maxEntryBytes: this.limits.maxEntryBytes ?? false,
+            maxStringLength: this.limits.maxStringLength ?? false,
             varLevel,
         };
         this.tags = {};
@@ -674,10 +893,16 @@ class Logger {
     createLogMethod(logLevel, format, checkLevel) {
         const logFn = (...messages) => {
             if (LEVEL_VALUES[logLevel] <= LEVEL_VALUES[checkLevel]) {
-                const sanitized = messages.map(sanitizeAuth);
+                let sanitized = messages.map(sanitizeAuth);
+                if (hasValueLimits(this.limits)) {
+                    sanitized = sanitized.map((item) => applyValueLimits(item, this.limits));
+                }
                 if (format === FORMAT.JSON) {
                     let message = stringify(...sanitized);
                     let parses = parsesTo(message);
+                    // When data comes from the full message they mirror each other;
+                    // entry-limit truncation must keep them in sync
+                    let syncMessageToData = parses.parses;
                     const last = sanitized[sanitized.length - 1];
                     if (sanitized.length > 1 &&
                         typeof last === "object" &&
@@ -689,6 +914,7 @@ class Logger {
                         if (lastParses.parses) {
                             message = stringify(...sanitized.slice(0, -1));
                             parses = lastParses;
+                            syncMessageToData = false;
                         }
                     }
                     const json = {
@@ -701,10 +927,20 @@ class Logger {
                     if (this.levelField) {
                         json[this.levelField] = logLevel;
                     }
-                    out(json, { level: logLevel });
+                    let entry = json;
+                    if (this.limits.maxEntryBytes !== undefined) {
+                        entry = enforceEntryLimit(json, {
+                            maxEntryBytes: this.limits.maxEntryBytes,
+                            syncMessageToData,
+                        });
+                    }
+                    out(entry, { level: logLevel });
                 }
                 else {
-                    const message = stringify(...sanitized);
+                    let message = stringify(...sanitized);
+                    if (this.limits.maxEntryBytes !== undefined) {
+                        message = truncateToBudget(message, this.limits.maxEntryBytes);
+                    }
                     out(message, { level: logLevel });
                 }
             }
@@ -746,6 +982,9 @@ class Logger {
                     }
                 }
                 messageVal = filterByType(messageVal);
+                if (hasValueLimits(this.limits)) {
+                    messageVal = applyValueLimits(messageVal, this.limits);
+                }
                 const json = {
                     data: parse(messageVal),
                     dataType: typeof messageVal,
@@ -757,7 +996,14 @@ class Logger {
                     json[this.levelField] = logLevel;
                 }
                 if (LEVEL_VALUES[logLevel] <= LEVEL_VALUES[checkLevel]) {
-                    out(json, { level: logLevel });
+                    let entry = json;
+                    if (this.limits.maxEntryBytes !== undefined) {
+                        entry = enforceEntryLimit(json, {
+                            maxEntryBytes: this.limits.maxEntryBytes,
+                            syncMessageToData: true,
+                        });
+                    }
+                    out(entry, { level: logLevel });
                 }
             }
             else {
@@ -766,6 +1012,20 @@ class Logger {
         };
         return logFn;
     }
+    /**
+     * Update serialization limits at runtime. Pass a number to set a limit,
+     * `false` to disable one; omitted keys are unchanged.
+     */
+    config(options = {}) {
+        this.limits = resolveSerializationLimits({
+            maxDepth: options.maxDepth ?? this.limits.maxDepth ?? false,
+            maxEntryBytes: options.maxEntryBytes ?? this.limits.maxEntryBytes ?? false,
+            maxStringLength: options.maxStringLength ?? this.limits.maxStringLength ?? false,
+        });
+        this.options.maxDepth = this.limits.maxDepth ?? false;
+        this.options.maxEntryBytes = this.limits.maxEntryBytes ?? false;
+        this.options.maxStringLength = this.limits.maxStringLength ?? false;
+    }
     tag(key, value) {
         if (value) {
             this.tags[forceString(key)] = forceString(value);
@@ -895,12 +1155,12 @@ function envBoolean(key, { defaultValue }) {
         lower === "no");
 }
 class JaypieLogger {
-    constructor({ level = process.env.LOG_LEVEL, tags = {}, } = {}) {
+    constructor({ level = process.env.LOG_LEVEL, maxDepth, maxEntryBytes, maxStringLength, tags = {}, } = {}) {
         this._errorCount = 0;
         this._report = {};
         this._sessionActive = false;
         this._warnCount = 0;
-        this._params = { level, tags };
+        this._params = { level, maxDepth, maxEntryBytes, maxStringLength, tags };
         this._loggers = [];
         this._tags = {};
         this._withLoggers = {};
@@ -909,6 +1169,9 @@ class JaypieLogger {
         this._logger = new Logger({
             format: FORMAT.JSON,
             level: this.level,
+            maxDepth,
+            maxEntryBytes,
+            maxStringLength,
             tags: this._tags,
         });
         this._loggers = [this._logger];
@@ -950,6 +1213,29 @@ class JaypieLogger {
         };
         this.var = (messageObject, messageValue) => this._logger.var(logVar(messageObject, messageValue));
     }
+    /**
+     * Update serialization limits at runtime for this logger and all loggers
+     * derived from it (lib, with, flag). Pass a number to set a limit,
+     * `false` to disable one; omitted keys are unchanged. Persists across
+     * init().
+     */
+    config(options = {}) {
+        if (options.maxDepth !== undefined) {
+            this._params.maxDepth = options.maxDepth;
+        }
+        if (options.maxEntryBytes !== undefined) {
+            this._params.maxEntryBytes = options.maxEntryBytes;
+        }
+        if (options.maxStringLength !== undefined) {
+            this._params.maxStringLength = options.maxStringLength;
+        }
+        for (const logger of this._loggers) {
+            logger.config(options);
+        }
+        for (const key of Object.keys(this._withLoggers)) {
+            this._withLoggers[key].config(options);
+        }
+    }
     flag(flag) {
         if (typeof flag !== "string" || flag === "") {
             return this;
@@ -970,6 +1256,9 @@ class JaypieLogger {
         this._logger = new Logger({
             format: FORMAT.JSON,
             level: this.level,
+            maxDepth: this._params.maxDepth,
+            maxEntryBytes: this._params.maxEntryBytes,
+            maxStringLength: this._params.maxStringLength,
             tags: this._tags,
         });
         this._loggers = [this._logger];
@@ -1052,6 +1341,9 @@ class JaypieLogger {
                 }
                 return LEVEL.SILENT;
             })(),
+            maxDepth: this._params.maxDepth,
+            maxEntryBytes: this._params.maxEntryBytes,
+            maxStringLength: this._params.maxStringLength,
             tags: newTags,
         });
         this._loggers.push(logger._logger);
@@ -1134,6 +1426,9 @@ class JaypieLogger {
         }
         const logger = new JaypieLogger({
             level: this.level,
+            maxDepth: this._params.maxDepth,
+            maxEntryBytes: this._params.maxEntryBytes,
+            maxStringLength: this._params.maxStringLength,
             tags: { ...this._tags },
         });
         logger._logger = this._logger.with(key, value);