@darksheep/logger 1.3.0 → 1.4.0

package/src/replacers/http-server-response.js

@@ -1,6 +1,10 @@
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
+
 import { ServerResponse, STATUS_CODES } from 'node:http';
 
-/** @type {import('../replacer.js').Replacer<ServerResponse>} */
+/** @type {Replacer<ServerResponse>} */
 export const HttpServerResponseReplacer = {
   name: 'HttpServerResponse',
   shouldReplace: (input) => input instanceof ServerResponse,

package/src/replacers/index.js

@@ -5,4 +5,4 @@ export { HttpIncomingMessageReplacer } from './http-incoming-message.js';
 export { HttpServerResponseReplacer } from './http-server-response.js';
 export { LongStringReplacer } from './long-strings.js';
 export { NetSocketReplacer } from './net-socket.js';
-export { SecretDelete, SecretObscure } from './secrets.js';
+export { SecretRedact, SecretRemove } from './secrets.js';

package/src/replacers/long-strings.js

@@ -1,6 +1,10 @@
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
+
 import { environment } from '../utilities/environment.js';
 
-/** @type {import('../replacer.js').Replacer<string>} */
+/** @type {Replacer<string>} */
 export const LongStringReplacer = {
   name: 'LongString',
   shouldReplace: (input) => (

package/src/replacers/net-socket.js

@@ -1,6 +1,10 @@
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
+
 import { Socket } from 'node:net';
 
-/** @type {import('../replacer.js').Replacer<Socket>} */
+/** @type {Replacer<Socket>} */
 export const NetSocketReplacer = {
   name: 'NetSocket',
   shouldReplace: (input) => input instanceof Socket,

package/src/replacers/secrets.js

@@ -1,30 +1,110 @@
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
+
 import { environment } from '../utilities/environment.js';
 import { nodesToPath } from '../utilities/json-path.js';
 
-/** @type {import('../replacer.js').Replacer} */
-export const SecretDelete = {
-  name: 'SecretDelete',
+/**
+ * Whether the subtree at `value` actually contains a node whose path is
+ * exempted from removal. Used to decide whether to descend into a node we
+ * would otherwise remove wholesale: we only keep the container when a real
+ * exempted descendant lives beneath it, so no empty container is left behind.
+ *
+ * Descendant paths are tested against the compiled exemption patterns, so
+ * wildcards behave exactly as they do elsewhere.
+ *
+ * @param {unknown} value - The node whose descendants to inspect.
+ * @param {string} path - The dotted path of `value`.
+ * @param {RegExp[]} blocked - The compiled exemption patterns.
+ * @param {WeakSet<object>} [seen] - Guards against circular references.
+ * @returns {boolean}
+ */
+function hasExemptedDescendant(value, path, blocked, seen = new WeakSet()) {
+  if (value === null || typeof value !== 'object' || seen.has(value)) {
+    return false;
+  }
+  seen.add(value);
+
+  const record = /** @type {Record<string, unknown>} */ (value);
+  for (const [ key, child ] of Object.entries(record)) {
+    const childPath = path === '' ? key : `${path}.${key}`;
+
+    for (const filter of blocked) {
+      if (filter.test(childPath)) {
+        return true;
+      }
+    }
+
+    if (hasExemptedDescendant(child, childPath, blocked, seen)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/** @type {Replacer} */
+export const SecretRemove = {
+  name: 'SecretRemove',
   stopHere: true,
-  shouldReplace: (_, original) => {
+  shouldReplace: (value, original) => {
     if (original == null) {
       return false;
     }
 
     const path = original.join('.');
-    for (const filter of environment.secretFilters.blocked) {
+
+    let directlyRemoved = false;
+    for (const filter of environment.removeFilters.allowed) {
       if (filter.test(path)) {
-        return true;
+        directlyRemoved = true;
+        break;
       }
     }
 
-    return false;
+    let ancestorRemoved = false;
+    if (directlyRemoved === false) {
+      for (let i = 1; i < original.length; i++) {
+        const ancestorPath = original.slice(0, i).join('.');
+        for (const filter of environment.removeFilters.allowed) {
+          if (filter.test(ancestorPath)) {
+            ancestorRemoved = true;
+            break;
+          }
+        }
+        if (ancestorRemoved === true) {
+          break;
+        }
+      }
+    }
+
+    if (directlyRemoved === false && ancestorRemoved === false) {
+      return false;
+    }
+
+    for (const filter of environment.removeFilters.blocked) {
+      if (filter.test(path)) {
+        return false;
+      }
+    }
+
+    // This node is slated for removal (directly or via an ancestor). Only keep
+    // it when a real exempted descendant lives beneath it, so traversal
+    // continues into its children; otherwise remove the whole subtree without
+    // leaving an empty container behind.
+    if (hasExemptedDescendant(value, path, environment.removeFilters.blocked)) {
+      return false;
+    }
+
+    return true;
   },
   replace: () => null,
 };
 
-/** @type {import('../replacer.js').Replacer} */
-export const SecretObscure = {
-  name: 'SecretObscure',
+/** @type {Replacer} */
+export const SecretRedact = {
+  name: 'SecretRedact',
   stopHere: true,
   shouldReplace: (_, original) => {
     if (original == null) {
@@ -32,13 +112,26 @@ export const SecretObscure = {
     }
 
     const path = original.join('.');
-    for (const filter of environment.secretFilters.allowed) {
+
+    let matched = false;
+    for (const filter of environment.redactFilters.allowed) {
       if (filter.test(path)) {
-        return true;
+        matched = true;
+        break;
       }
     }
 
-    return false;
+    if (matched === false) {
+      return false;
+    }
+
+    for (const filter of environment.redactFilters.blocked) {
+      if (filter.test(path)) {
+        return false;
+      }
+    }
+
+    return true;
   },
   replace: (_, path) => {
     if (path == null) {

package/src/utilities/environment.js

@@ -1,5 +1,6 @@
 import { getTypedEnv } from '@darksheep/environment';
 
+import { resolveSecretFilters } from './legacy-secrets.js';
 import { parseFilters } from './parse-filters.js';
 import { parseLogLevel } from './parse-log-level.js';
 
@@ -10,8 +11,10 @@ const {
   LOG_LEVEL,
   LOG_MAX_LENGTH = 1024,
   LOG_MEMORY = false,
-  LOG_SECRETS,
   LOG_RELATIVE_TO,
+  LOG_SECRETS,
+  LOG_SECRET_REDACT,
+  LOG_SECRET_REMOVE,
   NODE_ENV = 'production',
 } = getTypedEnv({
   LOG_CALLSITES: '?boolean',
@@ -20,11 +23,29 @@ const {
   LOG_LEVEL: '?string',
   LOG_MAX_LENGTH: '?number',
   LOG_MEMORY: '?boolean',
-  LOG_SECRETS: '?string',
   LOG_RELATIVE_TO: '?string',
+  LOG_SECRETS: '?string',
+  LOG_SECRET_REDACT: '?string',
+  LOG_SECRET_REMOVE: '?string',
   NODE_ENV: '?string',
 });
 
+// `LOG_SECRETS` is the pre-split control; map it onto the redact/remove vars
+// so existing configs keep working. The split vars win when set.
+if (LOG_SECRETS != null) {
+  process.emitWarning(
+    'LOG_SECRETS is deprecated; use LOG_SECRET_REDACT (obscure values) and ' +
+    'LOG_SECRET_REMOVE (delete keys) instead.',
+    { code: 'DEP_LOG_SECRETS', type: 'DeprecationWarning' },
+  );
+}
+
+const secretFilters = resolveSecretFilters({
+  secrets: LOG_SECRETS,
+  redact: LOG_SECRET_REDACT,
+  remove: LOG_SECRET_REMOVE,
+});
+
 export const environment = {
   includeCallsite: LOG_CALLSITES,
   includeCpuUsage: LOG_CPU,
@@ -34,7 +55,8 @@ export const environment = {
   isTesting: NODE_ENV === 'test',
   logFilters: parseFilters(LOG_FILTERS, [ /.*/u ]),
   logLevel: parseLogLevel(LOG_LEVEL, NODE_ENV),
-  secretFilters: parseFilters(LOG_SECRETS),
+  redactFilters: secretFilters.redactFilters,
   relativeTo: LOG_RELATIVE_TO,
+  removeFilters: secretFilters.removeFilters,
   stringMaxLength: LOG_MAX_LENGTH,
 };

package/src/utilities/legacy-secrets.js

@@ -0,0 +1,36 @@
+import { parseFilters } from './parse-filters.js';
+
+/**
+ * @typedef {{ allowed: RegExp[], blocked: RegExp[] }} Filters
+ */
+
+/**
+ * Resolves the redact and remove filters, mapping the legacy `LOG_SECRETS`
+ * control onto them when the split vars are not set.
+ *
+ * In `LOG_SECRETS` a bare pattern obscured (redacted) the value and a
+ * `-`-prefixed pattern removed the key -- which is exactly the `allowed` /
+ * `blocked` split that `parseFilters` already produces. So the legacy
+ * `allowed` patterns become the redact set and the legacy `blocked` patterns
+ * become the remove set (neither carried exemptions). Whenever the matching
+ * split var is set it wins and the legacy value is ignored for that half.
+ *
+ * @param {{
+ *   secrets?: string | undefined;
+ *   redact?: string | undefined;
+ *   remove?: string | undefined;
+ * }} options - The raw environment values.
+ * @returns {{ redactFilters: Filters, removeFilters: Filters }}
+ */
+export function resolveSecretFilters({ secrets, redact, remove }) {
+  const legacy = parseFilters(secrets);
+
+  return {
+    redactFilters: redact == null
+      ? { allowed: legacy.allowed, blocked: [] }
+      : parseFilters(redact),
+    removeFilters: remove == null
+      ? { allowed: legacy.blocked, blocked: [] }
+      : parseFilters(remove),
+  };
+}

package/src/utilities/log-types.js

@@ -23,11 +23,19 @@ export const LogNames = Object.fromEntries(
   Object.entries(LogLevels).map(([ k, v ]) => [ v, k ]),
 );
 
-/** @typedef {keyof LogLevels} LogLevelNames */
-/** @typedef {LogLevels[LogLevelNames]} LogLevel */
+/**
+ * @typedef {keyof LogLevels} LogLevelNames
+ */
+/**
+ * @typedef {LogLevels[LogLevelNames]} LogLevel
+ */
 
-/** @typedef {import('./stacktrace.js').Callsite} Callsite */
-/** @typedef {import('../replacers/error.js').NormalisedError} NormalisedError */
+/**
+ * @typedef {import('./stacktrace.js').Callsite} Callsite
+ */
+/**
+ * @typedef {import('../replacers/error.js').NormalisedError} NormalisedError
+ */
 
 /**
  * @typedef {Object} LogInternal

package/src/utilities/parse-filters.js

@@ -29,12 +29,12 @@ export function parseFilters(filter = '', fallback = []) {
 
     let regex = channel
       .replaceAll(/[\s#$()*+,\-.?[\\\]^{|}]/gu, String.raw`\$&`)
-      .replaceAll(String.raw`\*`, multiLevelWildcard.source)
-      .replaceAll(String.raw`\+`, oneLevelWildcard.source);
+      .replaceAll(String.raw`\*`, () => multiLevelWildcard.source)
+      .replaceAll(String.raw`\+`, () => oneLevelWildcard.source);
 
     // Allow for multi level wildcards at the start of a filter
     if (regex.startsWith(String.raw`.*\.`)) {
-      regex = `(?:.*\\.)?${regex.slice(4)}`;
+      regex = String.raw`(?:.*\.)?${regex.slice(4)}`;
     }
 
     const pattern = new RegExp(`^${regex}$`);

package/src/utilities/parse-log-level.js

@@ -1,10 +1,14 @@
+/**
+ * @import { LogLevel } from './log-types.js';
+ */
+
 import { LogLevels } from './log-types.js';
 
 /**
  * Convert a given string to a LogLevel.
  * @param {string} [input] - The string to convert.
  * @param {string} [node] - The current NODE_ENV.
- * @returns {import('./log-types.js').LogLevel}
+ * @returns {LogLevel}
  */
 export function parseLogLevel(input, node) {
   switch (input) {

package/src/utilities/resource-usage.js

@@ -14,8 +14,11 @@ export function getMemoryUsage() {
   };
 }
 
-let lastCalled = performance.now();
-let lastValue = process.cpuUsage();
+/** Previous sample, kept on one object so `getCPUUsage` mutates no bindings. */
+const last = {
+  called: performance.now(),
+  value: process.cpuUsage(),
+};
 
 /**
  * Get the callsite that we think is outside the package.
@@ -30,12 +33,12 @@ export function getCPUUsage() {
   /**
    * Time difference in microseconds.
    */
-  const elapsed = Math.floor(1000 * (currentCalled - lastCalled));
+  const elapsed = Math.floor(1000 * (currentCalled - last.called));
 
-  lastCalled = currentCalled;
-  lastValue = process.cpuUsage(lastValue);
+  last.called = currentCalled;
+  last.value = process.cpuUsage(last.value);
 
-  const { system, user } = lastValue;
+  const { system, user } = last.value;
   const total = system + user;
 
   return { elapsed, total, system, user };

package/types/create-logger.d.ts

@@ -1,5 +1,6 @@
+import { Logger } from './logger.js';
 /**
  * @param {string} [channel] - The logging channel.
- * @returns {import('./logger.js').Logger}
+ * @returns {Logger}
  */
-export function createLogger(channel?: string): import("./logger.js").Logger;
+export declare function createLogger(channel?: string): Logger;

package/types/formatter.d.ts

@@ -1,6 +1,6 @@
+export type Formatter = (logEntry: import('./utilities/log-types.js').LogEntry) => string;
 /**
  * @typedef {(logEntry: import('./utilities/log-types.js').LogEntry) => string} Formatter
  */
 /** @type {Formatter} */
-export const formatter: Formatter;
-export type Formatter = (logEntry: import("./utilities/log-types.js").LogEntry) => string;
+export declare const formatter: Formatter;

package/types/formatters/formatter-console/stack.d.ts

@@ -1,18 +1,22 @@
 /**
- * @param {Callsite[] | string | undefined} stack - The stack trace to format.
- * @param {number} indent - The indent to render from.
- * @returns {string}
+ * @import { ColourOptions } from '../../utilities/colour.js';
+ * @import { Callsite } from '../../utilities/log-types.js';
  */
-export function formatStack(stack: Callsite[] | string | undefined, indent: number): string;
+import type { ColourOptions } from '../../utilities/colour.js';
+import type { Callsite } from '../../utilities/log-types.js';
 export type HideOption = {
     hide?: boolean;
 };
 export type LineOptions = (HideOption & {
-    Line?: Omit<ColourOptions, "reset">;
-    FunctionName?: Omit<ColourOptions, "reset"> & HideOption;
-    FilePath?: Omit<ColourOptions, "reset">;
-    LineNumber?: Omit<ColourOptions, "reset"> & HideOption;
-    ColumnNumber?: Omit<ColourOptions, "reset"> & HideOption;
+    Line?: Omit<ColourOptions, 'reset'>;
+    FunctionName?: Omit<ColourOptions, 'reset'> & HideOption;
+    FilePath?: Omit<ColourOptions, 'reset'>;
+    LineNumber?: Omit<ColourOptions, 'reset'> & HideOption;
+    ColumnNumber?: Omit<ColourOptions, 'reset'> & HideOption;
 });
-import type { Callsite } from '../../utilities/log-types.js';
-import type { ColourOptions } from '../../utilities/colour.js';
+/**
+ * @param {Callsite[] | string | undefined} stack - The stack trace to format.
+ * @param {number} indent - The indent to render from.
+ * @returns {string}
+ */
+export declare function formatStack(stack: Callsite[] | string | undefined, indent: number): string;

package/types/formatters/formatter-console.d.ts

@@ -1,6 +1,6 @@
+import type { LogEntry } from '../utilities/log-types.js';
 /**
  * @param {LogEntry} logEntry - The Log entry which we're going to convert to a splatted string.
  * @returns {string}
  */
-export function formatterConsole(logEntry: LogEntry): string;
-import type { LogEntry } from '../utilities/log-types.js';
+export declare function formatterConsole(logEntry: LogEntry): string;

package/types/formatters/formatter-json.d.ts

@@ -2,4 +2,4 @@
  * @param {import('../utilities/log-types.js').LogEntry} logEntry - The Log entry which we're going to convert to JSON.
  * @returns {string}
  */
-export function formatterJson(logEntry: import("../utilities/log-types.js").LogEntry): string;
+export declare function formatterJson(logEntry: import('../utilities/log-types.js').LogEntry): string;

package/types/index.d.ts

@@ -1,11 +1,26 @@
-export { createLogger } from "./create-logger.js";
-export const logger: import("./logger.js").Logger;
-export { Logger } from "./logger.js";
-export { environment } from "./utilities/environment.js";
-export { LogLevels } from "./utilities/log-types.js";
-export type LogContext = import("./utilities/log-types.js").LogContext;
-export type LogEntry = import("./utilities/log-types.js").LogEntry;
-export type LogLevel = import("./utilities/log-types.js").LogLevel;
-export type Formatter = import("./formatter.js").Formatter;
-export type Replacer = import("./replacer.js").Replacer;
-export { BufferReplacer, ErrorReplacer, HttpClientRequestReplacer, HttpIncomingMessageReplacer, HttpServerResponseReplacer, LongStringReplacer, NetSocketReplacer, SecretDelete, SecretObscure } from "./replacers/index.js";
+export type LogContext = import('./utilities/log-types.js').LogContext;
+export type LogEntry = import('./utilities/log-types.js').LogEntry;
+export type LogLevel = import('./utilities/log-types.js').LogLevel;
+export type Formatter = import('./formatter.js').Formatter;
+export type Replacer = import('./replacer.js').Replacer;
+/**
+ * @typedef {import('./utilities/log-types.js').LogContext} LogContext
+ */
+/**
+ * @typedef {import('./utilities/log-types.js').LogEntry} LogEntry
+ */
+/**
+ * @typedef {import('./utilities/log-types.js').LogLevel} LogLevel
+ */
+/**
+ * @typedef {import('./formatter.js').Formatter} Formatter
+ */
+/**
+ * @typedef {import('./replacer.js').Replacer} Replacer
+ */
+export { createLogger } from './create-logger.js';
+export declare const logger: import("./logger.js").Logger;
+export { Logger } from './logger.js';
+export { BufferReplacer, ErrorReplacer, HttpClientRequestReplacer, HttpIncomingMessageReplacer, HttpServerResponseReplacer, LongStringReplacer, NetSocketReplacer, SecretRedact, SecretRemove, } from './replacers/index.js';
+export { environment } from './utilities/environment.js';
+export { LogLevels } from './utilities/log-types.js';