plslog 1.0.0 → 1.1.0

package/dist/index.js

@@ -8,6 +8,181 @@ function isBase64(link) {
   return link.startsWith("data:image/") && link.includes(";base64");
 }
 var Formatter = class {
+  /**
+   * Check if a field should be filtered based on configured rules
+   */
+  static shouldFilterField(key, value, path, filterFields) {
+    if (!filterFields || filterFields.length === 0) {
+      return false;
+    }
+    for (const filter of filterFields) {
+      if (typeof filter === "string" && key === filter) {
+        return true;
+      }
+      if (filter instanceof RegExp && filter.test(key)) {
+        return true;
+      }
+      if (typeof filter === "function") {
+        const shouldShow = filter(key, value, path);
+        if (shouldShow === false) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+  /**
+   * Check if a field should be included based on pick/omit rules
+   */
+  static shouldIncludeField(key, value, path, options) {
+    if (options?.pick && options.pick.length > 0) {
+      const pathWithoutIndices = path.filter((p) => !p.startsWith("["));
+      const fullPath = [...pathWithoutIndices, key].join(".");
+      const isInPickList = options.pick.some((pickPath) => {
+        if (pickPath.endsWith(".*")) {
+          const prefix = pickPath.slice(0, -2);
+          return fullPath.startsWith(prefix + ".") || fullPath === prefix;
+        }
+        if (!pickPath.includes(".") && key === pickPath) {
+          return true;
+        }
+        if (fullPath === pickPath) {
+          return true;
+        }
+        if (pickPath.startsWith(fullPath + ".")) {
+          return true;
+        }
+        if (fullPath.startsWith(pickPath + ".")) {
+          return true;
+        }
+        return false;
+      });
+      if (!isInPickList) {
+        return { include: false, filtered: false };
+      }
+    }
+    if (options?.omit && options.omit.length > 0) {
+      const shouldOmit = this.shouldFilterField(key, value, path, options.omit);
+      if (shouldOmit) {
+        return { include: true, filtered: true };
+      }
+    }
+    return { include: true, filtered: false };
+  }
+  /**
+   * Get the replacement value for a filtered field
+   */
+  static getFilteredValue(value, mode = "redact", replacement = "***REDACTED***") {
+    switch (mode) {
+      case "redact":
+        return replacement;
+      case "type":
+        if (value === null) return "[null]";
+        if (value === void 0) return "[undefined]";
+        if (Array.isArray(value)) return `[Array(${value.length})]`;
+        return `[${typeof value}]`;
+      case "length":
+        if (typeof value === "string") return `[${value.length} chars]`;
+        if (Array.isArray(value)) return `[${value.length} items]`;
+        if (typeof value === "object" && value !== null) {
+          return `[${Object.keys(value).length} keys]`;
+        }
+        return `[${typeof value}]`;
+      case "hide":
+        return void 0;
+      // Will be removed by caller
+      default:
+        return replacement;
+    }
+  }
+  /**
+   * Sanitize sensitive data from stack traces
+   */
+  static sanitizeStackTrace(stack, customPatterns) {
+    const defaultPatterns = [
+      /([?&])(token|key|secret|password|auth|api[_-]?key|access[_-]?token|client[_-]?secret)=[^&\s)#]*/gi,
+      /\/\/[^/]*:[^@]*@/g,
+      // Basic auth in URLs (user:pass@domain)
+      /(bearer\s+)[a-zA-Z0-9\-._~+/]+=*/gi
+      // Bearer tokens
+    ];
+    const allPatterns = [...defaultPatterns, ...customPatterns || []];
+    let sanitized = stack;
+    allPatterns.forEach((pattern) => {
+      sanitized = sanitized.replace(pattern, (match, p1) => {
+        if (p1) {
+          return `${p1}***REDACTED***`;
+        }
+        return "***REDACTED***";
+      });
+    });
+    return sanitized;
+  }
+  /**
+   * Serialize Error objects with all relevant properties (name, message, stack, cause)
+   */
+  static serializeError(error, config, currentDepth = 0) {
+    const maxCauseDepth = config?.maxCauseDepth ?? 10;
+    if (currentDepth > maxCauseDepth) {
+      return "[Max Cause Depth Reached]";
+    }
+    const includeStack = config?.includeStack ?? true;
+    const includeCause = config?.includeCause ?? true;
+    const stackFrameLimit = config?.stackFrameLimit;
+    const sanitizeStack = config?.sanitizeStack ?? false;
+    const serialized = {
+      name: error.name,
+      message: error.message
+    };
+    if ("code" in error) {
+      const errorWithCode = error;
+      if (typeof errorWithCode.code === "number") {
+        serialized.code = errorWithCode.code;
+      }
+    }
+    if (includeStack && error.stack) {
+      let stack = error.stack;
+      if (sanitizeStack) {
+        stack = this.sanitizeStackTrace(stack, config?.sanitizePatterns);
+      }
+      if (stackFrameLimit !== void 0 && stackFrameLimit > 0) {
+        const lines = stack.split("\n");
+        if (lines.length > stackFrameLimit) {
+          stack = lines.slice(0, stackFrameLimit).join("\n") + "\n... (truncated)";
+        }
+      }
+      serialized.stack = stack;
+    }
+    if (includeCause && error.cause !== void 0) {
+      if (error.cause instanceof Error) {
+        const serializedCause = this.serializeError(error.cause, config, currentDepth + 1);
+        serialized.cause = typeof serializedCause === "string" ? serializedCause : serializedCause;
+      } else {
+        serialized.cause = error.cause;
+      }
+    }
+    for (const key in error) {
+      if (Object.prototype.hasOwnProperty.call(error, key)) {
+        if (!["name", "message", "stack", "cause"].includes(key)) {
+          const errorWithCustomProps = error;
+          serialized[key] = errorWithCustomProps[key];
+        }
+      }
+    }
+    if (error.name === "AggregateError" && "errors" in error) {
+      const aggregateError = error;
+      if (Array.isArray(aggregateError.errors)) {
+        serialized.errors = aggregateError.errors.map((e) => {
+          if (e instanceof Error) {
+            const serializedErr = this.serializeError(e, config, currentDepth + 1);
+            return typeof serializedErr === "string" ? { name: "Error", message: serializedErr } : serializedErr;
+          }
+          return e;
+        });
+      }
+    }
+    return serialized;
+  }
   /**
    * Format base64 string for logging
    */
@@ -33,8 +208,11 @@ var Formatter = class {
   /**
    * Helper to serialize Blob and File objects for logging
    */
-  static serializeSpecialObjects(obj, maxDepth = 10, currentDepth = 0) {
+  static serializeSpecialObjects(obj, maxDepth = 10, currentDepth = 0, filterOptions, currentPath = []) {
     if (currentDepth > maxDepth) return "[Max Depth Reached]";
+    if (obj instanceof Error) {
+      return this.serializeError(obj, filterOptions?.errorConfig, 0);
+    }
     if (typeof obj === "string" && isBase64(obj)) {
       return this.formatBase64String(obj);
     }
@@ -53,13 +231,62 @@ var Formatter = class {
       };
     }
     if (Array.isArray(obj)) {
-      return obj.map((item) => this.serializeSpecialObjects(item, maxDepth, currentDepth + 1));
+      return obj.map(
+        (item, index) => this.serializeSpecialObjects(
+          item,
+          maxDepth,
+          currentDepth + 1,
+          filterOptions,
+          [...currentPath, `[${index}]`]
+        )
+      );
     }
     if (obj !== null && typeof obj === "object") {
       const serialized = {};
       for (const key in obj) {
         if (Object.prototype.hasOwnProperty.call(obj, key)) {
-          serialized[key] = this.serializeSpecialObjects(obj[key], maxDepth, currentDepth + 1);
+          const value = obj[key];
+          const newPath = [...currentPath, key];
+          const { include, filtered } = this.shouldIncludeField(
+            key,
+            value,
+            currentPath,
+            filterOptions
+          );
+          if (!include) {
+            continue;
+          }
+          let isGloballyFiltered = false;
+          if (filterOptions?.filterFields && filterOptions.filterFields.length > 0) {
+            isGloballyFiltered = this.shouldFilterField(key, value, currentPath, filterOptions.filterFields);
+          }
+          if (isGloballyFiltered) {
+            const filteredValue = this.getFilteredValue(
+              value,
+              filterOptions?.globalFilterMode,
+              filterOptions?.globalFilterReplacement
+            );
+            if (filteredValue !== void 0) {
+              serialized[key] = filteredValue;
+            }
+          } else if (filtered) {
+            const filteredValue = this.getFilteredValue(
+              value,
+              filterOptions?.filterMode,
+              filterOptions?.filterReplacement
+            );
+            if (filteredValue !== void 0) {
+              serialized[key] = filteredValue;
+            }
+          } else {
+            serialized[key] = this.serializeSpecialObjects(
+              value,
+              maxDepth,
+              currentDepth + 1,
+              filterOptions,
+              newPath
+            );
+          }
         }
       }
       return serialized;
@@ -78,10 +305,23 @@ var Formatter = class {
       const isArray = Array.isArray(arg);
       if (isObject || isArray) {
         const maxDepth = options?.maxDepth ?? 5;
-        const serialized = this.serializeSpecialObjects(arg, maxDepth);
+        const serialized = this.serializeSpecialObjects(
+          arg,
+          maxDepth,
+          0,
+          {
+            pick: options?.pick,
+            omit: options?.omit,
+            filterFields: options?.filterFields,
+            filterMode: options?.filterMode,
+            filterReplacement: options?.filterReplacement,
+            globalFilterMode: options?.globalFilterMode,
+            globalFilterReplacement: options?.globalFilterReplacement,
+            errorConfig: options?.errorConfig
+          }
+        );
         const formatted = prettyFormat.format(serialized, {
-          ...options,
-          indent: options?.indent ?? 2,
+          indent: 2,
           maxDepth,
           // Remove Object and Array labels
           printFunctionName: false,
@@ -110,6 +350,10 @@ var LOG_COLORS = {
   none: "#fff"
 };
 var DEFAULT_NAMESPACE = "app";
+var DEFAULT_DEDUP_CONFIG = {
+  enabled: false,
+  flushInterval: 100
+};
 
 // src/styler.ts
 function getColorForLevel(level) {
@@ -216,6 +460,41 @@ var NamespaceMatcher = class {
 var namespaceMatcher = new NamespaceMatcher();
 var namespace_matcher_default = namespaceMatcher;
 
+// src/dedup-hasher.ts
+var DedupHasher = class {
+  /**
+   * Default hash function - simple string concatenation
+   * For better performance, we use a simple approach rather than crypto hashing
+   */
+  static generateKey(level, message, args) {
+    const argsString = this.serializeArgs(args);
+    return `${level}:${message}:${argsString}`;
+  }
+  /**
+   * Serialize arguments to a consistent string representation
+   */
+  static serializeArgs(args) {
+    if (args.length === 0) return "";
+    try {
+      return JSON.stringify(args, (key, value) => {
+        if (typeof value === "function") {
+          return "[Function]";
+        }
+        if (typeof value === "symbol") {
+          return value.toString();
+        }
+        if (value === void 0) {
+          return "[undefined]";
+        }
+        return value;
+      });
+    } catch (error) {
+      return String(args);
+    }
+  }
+};
+var dedup_hasher_default = DedupHasher;
+
 // src/logger.ts
 var globalConfig = {};
 function configure(options) {
@@ -224,9 +503,22 @@ function configure(options) {
 var Logger = class {
   constructor(options = {}) {
     this._level = "debug";
+    this._dedupBuffer = /* @__PURE__ */ new Map();
+    // Temporary filter options that reset after each log
+    this._tempFilterOptions = {};
+    // Custom context for conditional logging
+    this._context = {};
+    // Temporary conditions that reset after each log
+    this._tempConditions = [];
     this._namespace = options.namespace ?? DEFAULT_NAMESPACE;
     this._level = options.level ?? globalConfig.level ?? "debug";
     this._maxDepth = options.maxDepth ?? globalConfig.maxDepth ?? 10;
+    this._context = options.context ?? {};
+    this._dedupConfig = {
+      ...DEFAULT_DEDUP_CONFIG,
+      ...globalConfig.dedup || {},
+      ...options.dedup || {}
+    };
   }
   debug(message, ...args) {
     this.log("debug", message, ...args);
@@ -244,13 +536,134 @@ var Logger = class {
     this.log("error", message, ...args);
     return this;
   }
+  /**
+   * Assert that a condition is truthy. Logs an error if the condition is falsy.
+   * Similar to console.assert() but integrates with plslog's features.
+   * Uses JavaScript truthiness - falsy values: false, 0, '', null, undefined, NaN
+   *
+   * @param condition - The condition to assert (uses JavaScript truthiness)
+   * @param message - Error message to log if assertion fails
+   * @param args - Additional arguments to log
+   * @returns this for chaining
+   *
+   * @example
+   * logger.assert(user !== null, 'User should not be null', user);
+   * logger.assert(count > 0, 'Count must be positive', { count });
+   * logger.assert(data, 'Data is required'); // Checks if data is truthy
+   */
+  assert(condition, message, ...args) {
+    if (!condition) {
+      this.log("error", message, ...args);
+    }
+    return this;
+  }
   setLevel(level) {
     this._level = level;
   }
+  /**
+   * Set the namespace for this logger instance
+   * Returns this for method chaining
+   *
+   * @param namespace - The namespace string (e.g., 'service:api', 'component')
+   * @returns this for chaining
+   *
+   * @example
+   * const log = logger().namespace('service:api');
+   * log.debug('Message'); // Logs with namespace 'service:api'
+   *
+   * // Can also be called after instantiation
+   * const log2 = logger();
+   * log2.namespace('component').debug('Message');
+   */
+  namespace(namespace) {
+    this._namespace = namespace;
+    return this;
+  }
   maxDepth(maxDepth) {
     this._maxDepth = maxDepth;
     return this;
   }
+  /**
+   * Pick only specific fields to log (whitelist approach)
+   * Supports dot notation for nested fields: 'user.name', 'user.email'
+   * Supports wildcards: 'user.*' matches all fields under user
+   */
+  pick(fields) {
+    this._tempFilterOptions.pick = fields;
+    return this;
+  }
+  /**
+   * Omit specific fields from logging (blacklist approach)
+   * Supports strings, regex patterns, and predicate functions
+   */
+  omit(fields) {
+    this._tempFilterOptions.omit = fields;
+    return this;
+  }
+  /**
+   * Set filter mode for per-log filtering
+   * - 'redact': Replace with custom string (default: '***REDACTED***')
+   * - 'hide': Remove field completely
+   * - 'type': Show type info like '[string]', '[Array(3)]'
+   * - 'length': Show length info like '[8 chars]', '[3 items]'
+   */
+  filterMode(mode, replacement) {
+    this._tempFilterOptions.filterMode = mode;
+    if (replacement !== void 0) {
+      this._tempFilterOptions.filterReplacement = replacement;
+    }
+    return this;
+  }
+  once(enabled = true) {
+    this._dedupConfig.enabled = enabled;
+    return this;
+  }
+  flushDedup() {
+    const keys = Array.from(this._dedupBuffer.keys());
+    keys.forEach((key) => this.flushDedupEntry(key));
+    return this;
+  }
+  /**
+   * Execute log only if condition is true
+   * Supports boolean values or predicate functions
+   * Multiple when() calls are AND-ed together
+   *
+   * @example
+   * // Boolean condition
+   * logger.when(isDev).debug('Dev only');
+   *
+   * // Predicate with context
+   * logger.when(ctx => ctx.namespace === 'auth').debug('Auth log');
+   *
+   * // Chaining (both must be true)
+   * logger
+   *   .when(ctx => ctx.level === 'debug')
+   *   .when(isDevMode)
+   *   .debug('Conditional');
+   */
+  when(condition) {
+    this._tempConditions.push(condition);
+    return this;
+  }
+  /**
+   * Execute log only if condition is false (inverse of when)
+   * Supports boolean values or predicate functions
+   *
+   * @example
+   * // Boolean condition
+   * logger.unless(isProd).debug('Not in production');
+   *
+   * // Predicate with context
+   * logger.unless(ctx => ctx.level === 'error').info('Non-error log');
+   */
+  unless(condition) {
+    if (typeof condition === "function") {
+      this._tempConditions.push((ctx) => !condition(ctx));
+    } else {
+      this._tempConditions.push(!condition);
+    }
+    return this;
+  }
   getLevelPriority(level) {
     const priorities = {
       debug: 0,
@@ -262,6 +675,21 @@ var Logger = class {
     return priorities[level];
   }
   log(level, message, ...args) {
+    if (this._tempConditions.length > 0) {
+      const ctx = {
+        namespace: this._namespace,
+        level,
+        ...this._context
+      };
+      const conditionsMet = this._tempConditions.every(
+        (condition) => typeof condition === "function" ? condition(ctx) : condition
+      );
+      this._tempConditions = [];
+      if (!conditionsMet) {
+        this._tempFilterOptions = {};
+        return;
+      }
+    }
     if (!namespace_matcher_default.matches(this._namespace, globalConfig.namespaces)) {
       return;
     }
@@ -272,8 +700,80 @@ var Logger = class {
     } else if (this.getLevelPriority(this._level) > this.getLevelPriority(level)) {
       return;
     }
+    const filterOptions = { ...this._tempFilterOptions };
+    this._tempFilterOptions = {};
+    if (this._dedupConfig.enabled) {
+      this.logWithDedup(level, message, filterOptions, ...args);
+    } else {
+      this.logImmediate(level, message, filterOptions, ...args);
+    }
+  }
+  logWithDedup(level, message, filterOptions, ...args) {
+    const key = dedup_hasher_default.generateKey(level, message, args);
+    const existing = this._dedupBuffer.get(key);
+    const now = Date.now();
+    if (existing) {
+      existing.count++;
+      existing.lastTimestamp = now;
+      existing.args = args;
+      existing.filterOptions = filterOptions;
+      if (existing.flushTimeoutId !== void 0) {
+        clearTimeout(existing.flushTimeoutId);
+      }
+      existing.flushTimeoutId = setTimeout(() => {
+        this.flushDedupEntry(key);
+      }, this._dedupConfig.flushInterval);
+    } else {
+      const entry = {
+        key,
+        level,
+        message,
+        args,
+        count: 1,
+        firstTimestamp: now,
+        lastTimestamp: now,
+        filterOptions
+      };
+      this._dedupBuffer.set(key, entry);
+      entry.flushTimeoutId = setTimeout(() => {
+        this.flushDedupEntry(key);
+      }, this._dedupConfig.flushInterval);
+    }
+  }
+  flushDedupEntry(key) {
+    const entry = this._dedupBuffer.get(key);
+    if (!entry) return;
+    let displayMessage = entry.message;
+    if (entry.count > 1) {
+      const firstTime = this.formatTimestamp(entry.firstTimestamp);
+      const lastTime = this.formatTimestamp(entry.lastTimestamp);
+      displayMessage = `${entry.message} (x${entry.count}, ${firstTime} \u2192 ${lastTime})`;
+    }
+    this.logImmediate(entry.level, displayMessage, entry.filterOptions || {}, ...entry.args);
+    this._dedupBuffer.delete(key);
+  }
+  formatTimestamp(timestamp) {
+    const date = new Date(timestamp);
+    const hours = String(date.getHours()).padStart(2, "0");
+    const minutes = String(date.getMinutes()).padStart(2, "0");
+    const seconds = String(date.getSeconds()).padStart(2, "0");
+    const milliseconds = String(date.getMilliseconds()).padStart(3, "0");
+    return `${hours}:${minutes}:${seconds}.${milliseconds}`;
+  }
+  logImmediate(level, message, filterOptions, ...args) {
     const formattedObject = Formatter.formatObj(args, {
-      maxDepth: this._maxDepth
+      maxDepth: this._maxDepth,
+      // Global filter fields (always applied for security)
+      filterFields: globalConfig.filterFields,
+      globalFilterMode: globalConfig.filterMode,
+      globalFilterReplacement: globalConfig.filterReplacement,
+      // Per-log pick/omit (contextual filtering)
+      pick: filterOptions.pick,
+      omit: filterOptions.omit,
+      filterMode: filterOptions.filterMode,
+      filterReplacement: filterOptions.filterReplacement,
+      // Error serialization config
+      errorConfig: globalConfig.errorSerialization
     });
     const formattedMessage = formattedObject ? `${message} ${formattedObject}` : message;
     const { logMessage, logStyles } = styler_default.style({
@@ -301,7 +801,8 @@ var Logger = class {
   }
 };
 var plslog = ((options = {}) => {
-  return new Logger(options);
+  const normalizedOptions = typeof options === "string" ? { namespace: options } : options;
+  return new Logger(normalizedOptions);
 });
 plslog.configure = configure;
 var logger_default = plslog;