@darksheep/logger 1.3.1 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [1.4.1](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.4.0...logger-v1.4.1) (2026-09-21)
+
+
+### 🔨 Code Refactoring
+
+* JSDoc for resolveSecretFilters parameters ([#1009](https://github.com/DarkSheepSoftware/node-packages/issues/1009)) ([3be00f0](https://github.com/DarkSheepSoftware/node-packages/commit/3be00f02249831795518b436e6a874744654825e))
+
+## [1.4.0](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.3.1...logger-v1.4.0) (2026-09-20)
+
+
+### 🌟 Features
+
+* split logger secrets into redact and remove ([#845](https://github.com/DarkSheepSoftware/node-packages/issues/845)) ([924c6d5](https://github.com/DarkSheepSoftware/node-packages/commit/924c6d589e105c22048d3f05fd7151f03a2513dd))
+* **traverse:** add @darksheep/traverse deep object traversal package ([#874](https://github.com/DarkSheepSoftware/node-packages/issues/874)) ([981bea0](https://github.com/DarkSheepSoftware/node-packages/commit/981bea0a3fa08c78152713108feb02dc0ccbdc37))
+
+
+### 📦 Dependencies
+
+* **pkg:** update dependency deepmerge-ts to v7.1.6 ([#938](https://github.com/DarkSheepSoftware/node-packages/issues/938)) ([194912b](https://github.com/DarkSheepSoftware/node-packages/commit/194912bd6af5f4a83c101080c4d5ea76047511c5))
+* **pkg:** update dependency deepmerge-ts to v8 [security] ([ca3b39a](https://github.com/DarkSheepSoftware/node-packages/commit/ca3b39a53603b522d6f89a3230fa2836e02d532c))
+* **pkg:** update dependency deepmerge-ts to v8.0.1 ([#949](https://github.com/DarkSheepSoftware/node-packages/issues/949)) ([0099631](https://github.com/DarkSheepSoftware/node-packages/commit/0099631ca6a8a6f437f75d83d63bb45c8383cead))
+* **pkg:** update dependency deepmerge-ts to v8.0.2 ([#957](https://github.com/DarkSheepSoftware/node-packages/issues/957)) ([4c78b29](https://github.com/DarkSheepSoftware/node-packages/commit/4c78b296fee9d8d73abec141eb2151e6e4903fcf))
+
 ## [1.3.1](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.3.0...logger-v1.3.1) (2026-04-17)
 
 

package/README.md

@@ -56,7 +56,8 @@ app.get('/', (request, response) => {
 | `NODE_ENV` | The deployment location |
 | `LOG_LEVEL` | Overrides the log level set by the detected environment |
 | `LOG_FILTERS` | This allows you to allow/block specific channels |
-| `LOG_SECRETS` | This allows you to hide or remove secrets in an object |
+| `LOG_SECRET_REDACT` | This allows you to obscure secrets in an object |
+| `LOG_SECRET_REMOVE` | This allows you to remove secrets from an object |
 | `LOG_CALLSITES` | Include the callsite of the log |
 
 #### `NODE_ENV`
@@ -108,18 +109,17 @@ The following filter means that ONLY `router` gets logged, except for the `route
 LOG_FILTERS="router,-router.ok"
 ```
 
-#### `LOG_SECRETS`
+#### `LOG_SECRET_REDACT`
 
-Secrets also use a filter, if you use a standard filter the secret key is displayed, if you use a negate the key and value are deleted.
+Comma-separated list of key patterns. Matched keys have their values replaced with `[secret ...]`. Prefix a pattern with `-` to exempt it from redacting.
 
-The following means that `password` is deleted, and `token` is obscured.
+Wild cards are permitted.
 
 ```js
-// LOG_SECRETS="-password,token"
+// LOG_SECRET_REDACT="token"
 
 // Given the following context
 const context = {
-  password: '1234',
   token: 'asdf',
 };
 
@@ -129,12 +129,8 @@ const output = {
 };
 ```
 
-Wild cards are also permitted.
-
-For example, using a positive (obscure) wildcard
-
 ```js
-// LOG_SECRETS="*.token"
+// LOG_SECRET_REDACT="*.token"
 
 // Given the following context
 const context = {
@@ -161,9 +157,35 @@ const output = {
 };
 ```
 
-For example, using a negative (delete) wildcard:
+#### `LOG_SECRET_REMOVE`
+
+Comma-separated list of key patterns. Matched keys and their values are deleted entirely. Prefix a pattern with `-` to exempt a specific path from removal.
+
+Wild cards are permitted.
+
+```js
+// LOG_SECRET_REMOVE="response,-response.statusMessage"
+
+// Given the following context
+const context = {
+  status: 200,
+  response: {
+    statusMessage: 'OK',
+    body: '...',
+  },
+};
+
+// Then the following will be logged
+const output = {
+  status: 200,
+  response: {
+    statusMessage: 'OK',
+  },
+};
+```
+
 ```js
-// LOG_SECRETS="-*.token"
+// LOG_SECRET_REMOVE="*.token"
 
 // Given the following context
 const context = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksheep/logger",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Logging your stuff to where ever you want it",
   "license": "UNLICENCED",
   "type": "module",
@@ -22,15 +22,17 @@
   },
   "dependencies": {
     "@darksheep/environment": "3.2.0",
-    "deepmerge-ts": "7.1.5",
-    "stacktrace-parser": "0.1.11",
-    "traverse": "0.6.11"
+    "@darksheep/traverse": "1.0.0",
+    "deepmerge-ts": "8.0.2",
+    "stacktrace-parser": "0.1.11"
   },
   "devDependencies": {
-    "@types/traverse": "~0.6.33",
     "nock": "~14.0.0"
   },
   "engines": {
     "node": "^20.13.1 || >=22.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/create-logger.js

@@ -7,8 +7,8 @@ import {
   HttpServerResponseReplacer,
   LongStringReplacer,
   NetSocketReplacer,
-  SecretDelete,
-  SecretObscure,
+  SecretRedact,
+  SecretRemove,
 } from './replacers/index.js';
 
 /**
@@ -20,8 +20,8 @@ export function createLogger(channel) {
     typeof channel === 'string' ? { channel } : {},
     { replacers: [
       // Always run the secret replacer first.
-      SecretDelete,
-      SecretObscure,
+      SecretRemove,
+      SecretRedact,
 
       ErrorReplacer,
       HttpClientRequestReplacer,

package/src/formatters/formatter-console/stack.js

@@ -85,7 +85,7 @@ function highlightNumber(number, options, colon = ':') {
     return '';
   }
 
-  return `${colon}${colourString(`${number}`, options)}`;
+  return `${colon}${colourString(String(number), options)}`;
 }
 
 /**

package/src/formatters/formatter-console.js

@@ -28,7 +28,7 @@ function flattenChannelLevel(channel, level) {
   }
 
   if (level != null && LogNames[level] != null) {
-    output += `${LogNames[level].toUpperCase()}`;
+    output += LogNames[level].toUpperCase();
   }
 
   output += ': ';
@@ -77,7 +77,7 @@ function formatError(error, indent = 0) {
         error.message,
         { foreground: 'red', effects: [ 'bold' ] },
       )
-      : `${error.message}`;
+      : error.message;
 
   const stack = formatStack(error.stack, indent);
   if (stack.trim().length > 0) {

package/src/index.js

@@ -28,8 +28,8 @@ export {
   HttpServerResponseReplacer,
   LongStringReplacer,
   NetSocketReplacer,
-  SecretDelete,
-  SecretObscure,
+  SecretRedact,
+  SecretRemove,
 } from './replacers/index.js';
 export { environment } from './utilities/environment.js';
 export { LogLevels } from './utilities/log-types.js';

package/src/replacer.js

@@ -1,7 +1,4 @@
-/**
- * @import { TraverseContext } from 'traverse';
- */
-import Traverse from 'traverse';
+import { createTraverse } from '@darksheep/traverse';
 
 import { nodesToPath } from './utilities/json-path.js';
 
@@ -21,34 +18,30 @@ import { nodesToPath } from './utilities/json-path.js';
  * @returns {unknown}
  */
 export function replace(object, replacers = []) {
-  // eslint-disable-next-line unicorn/no-array-for-each -- This is not an array
-  return Traverse(object).forEach(
-    /**
-     * @param {unknown} value - Current property in the traversed object.
-     * @returns {void}
-     * @this {TraverseContext}
-     */
-    function (value) {
+  const walk = createTraverse(
+    (context) => {
+      const value = context.node;
+
       if (value == null) {
-        this.remove();
+        context.remove();
         return;
       }
 
-      if (this.circular != null) {
-        this.update({ $ref: nodesToPath(this.circular.path) });
+      if (context.circular != null) {
+        context.update({ $ref: nodesToPath(context.circular.path) });
         return;
       }
 
       for (const replacer of replacers) {
-        if (replacer.shouldReplace(value, this.path)) {
-          const replaced = replacer.replace(value, this.path);
+        if (replacer.shouldReplace(value, context.path)) {
+          const replaced = replacer.replace(value, context.path);
 
           if (replaced == null) {
-            this.remove(replacer.stopHere);
+            context.remove();
             return;
           }
 
-          this.update(replaced, replacer.stopHere);
+          context.update(replaced, replacer.stopHere);
           return;
         }
       }
@@ -59,7 +52,7 @@ export function replace(object, replacers = []) {
         typeof value.toJSON === 'function'
       ) {
         try {
-          this.update(value.toJSON());
+          context.update(value.toJSON());
           return;
         } catch { }
       }
@@ -69,20 +62,22 @@ export function replace(object, replacers = []) {
         Object.getPrototypeOf(value) !== Object.getPrototypeOf({}) &&
         Object.getPrototypeOf(value) !== Object.getPrototypeOf([])
       ) {
-        this.update({ $class: value.constructor.name });
+        context.update({ $class: value.constructor.name });
         return;
       }
 
       if (Object.getPrototypeOf(value)?.constructor === Object) {
-        this.update({ ...value });
+        context.update({ ...value });
       }
 
       if (
         Array.isArray(value) &&
         Object.getPrototypeOf(value).constructor === Array
       ) {
-        this.update([ ...value ]);
+        context.update([ ...value ]);
       }
     },
   );
+
+  return walk(object);
 }

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/secrets.js

@@ -5,30 +5,106 @@
 import { environment } from '../utilities/environment.js';
 import { nodesToPath } from '../utilities/json-path.js';
 
+/**
+ * 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 SecretDelete = {
-  name: 'SecretDelete',
+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 {Replacer} */
-export const SecretObscure = {
-  name: 'SecretObscure',
+export const SecretRedact = {
+  name: 'SecretRedact',
   stopHere: true,
   shouldReplace: (_, original) => {
     if (original == null) {
@@ -36,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/parse-filters.js

@@ -29,8 +29,8 @@ 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`.*\.`)) {

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,6 +1,6 @@
+import { Logger } from './logger.js';
 /**
  * @param {string} [channel] - The logging channel.
  * @returns {Logger}
  */
-export function createLogger(channel?: string): Logger;
-import { Logger } from './logger.js';
+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;