@jaypie/logger 1.2.17 → 1.2.19

package/dist/cjs/index.cjs

@@ -8,8 +8,16 @@ var node_https = require('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: {
@@ -63,6 +71,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)
 //
@@ -654,12 +863,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 = {};
@@ -678,10 +897,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" &&
@@ -693,6 +918,7 @@ class Logger {
                         if (lastParses.parses) {
                             message = stringify(...sanitized.slice(0, -1));
                             parses = lastParses;
+                            syncMessageToData = false;
                         }
                     }
                     const json = {
@@ -705,10 +931,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 });
                 }
             }
@@ -750,6 +986,9 @@ class Logger {
                     }
                 }
                 messageVal = filterByType(messageVal);
+                if (hasValueLimits(this.limits)) {
+                    messageVal = applyValueLimits(messageVal, this.limits);
+                }
                 const json = {
                     data: parse(messageVal),
                     dataType: typeof messageVal,
@@ -761,7 +1000,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 {
@@ -770,6 +1016,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);
@@ -899,12 +1159,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 = {};
@@ -913,6 +1173,9 @@ class JaypieLogger {
         this._logger = new Logger({
             format: FORMAT.JSON,
             level: this.level,
+            maxDepth,
+            maxEntryBytes,
+            maxStringLength,
             tags: this._tags,
         });
         this._loggers = [this._logger];
@@ -954,6 +1217,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;
@@ -974,6 +1260,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];
@@ -1056,6 +1345,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);
@@ -1138,6 +1430,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);