@darksheep/logger 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [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)
+
+
+### 📚 Documentation
+
+* Update the READMEs ([#824](https://github.com/DarkSheepSoftware/node-packages/issues/824)) ([9d282b7](https://github.com/DarkSheepSoftware/node-packages/commit/9d282b724fe056ec275578088bf495985e22c25f))
+
 ## [1.3.0](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.2.0...logger-v1.3.0) (2025-10-09)
 
 

package/README.md

@@ -1,9 +1,7 @@
 # @darksheep/logger
 Log configuration for NodeJS repos
 
-This repo contains environment aware logging configurations for our NodeJS modules that use Winston.
-
-This can be added using `yarn add @darksheep/logger` how ever you require a valid npm token for github packages!
+This can be added using `yarn add @darksheep/logger`
 
 ### Quick start
 #### Get something logging:
@@ -58,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`
@@ -110,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',
 };
 
@@ -131,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 = {
@@ -163,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.0",
+  "version": "1.4.0",
   "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,21 +7,21 @@ import {
   HttpServerResponseReplacer,
   LongStringReplacer,
   NetSocketReplacer,
-  SecretDelete,
-  SecretObscure,
+  SecretRedact,
+  SecretRemove,
 } from './replacers/index.js';
 
 /**
  * @param {string} [channel] - The logging channel.
- * @returns {import('./logger.js').Logger}
+ * @returns {Logger}
  */
 export function createLogger(channel) {
   return new Logger(
     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

@@ -1,10 +1,20 @@
 import { createLogger } from './create-logger.js';
 
-/** @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 */
+/**
+ * @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 const logger = createLogger();
@@ -18,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/logger.js

@@ -1,3 +1,8 @@
+/**
+ * @import { LogLevel, LogContext, LogEntry} from './utilities/log-types.js'
+ * @import { Replacer } from './replacer.js';
+ */
+
 import { AsyncLocalStorage } from 'node:async_hooks';
 
 import { deepmerge } from 'deepmerge-ts';
@@ -15,16 +20,16 @@ import { LogLevels } from './utilities/log-types.js';
 /**
  * @typedef {Object} Options
  * @property {typeof replace} [replace] - The replacer function to use.
- * @property {import('./replacer.js').Replacer<any, any>[]} [replacers] - The replacers to use in the replacer.
+ * @property {Replacer[]} [replacers] - The replacers to use in the replacer.
  * @property {typeof formatter} [format] - The formatter function to use (eg console or json formatter).
  * @property {typeof stdoutWrite} [write] - The place to write the log to.
  */
 
 export class Logger {
-  /** @type {AsyncLocalStorage<import('./utilities/log-types.js').LogContext[]>} */
+  /** @type {AsyncLocalStorage<LogContext[]>} */
   static storage = new AsyncLocalStorage();
 
-  /** @type {import('./utilities/log-types.js').LogContext} */
+  /** @type {LogContext} */
   #context;
 
   /** @type {typeof formatter} */
@@ -36,10 +41,10 @@ export class Logger {
   /** @type {typeof stdoutWrite} */
   #write = stdoutWrite;
 
-  /** @type {import('./replacer.js').Replacer[]} */
+  /** @type {Replacer[]} */
   replacers = [];
   /**
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Context to add to the logger.
+   * @param {LogContext} [context] - Context to add to the logger.
    * @param {Options} [options] - Options for the loggers output.
    */
   constructor(context, options) {
@@ -59,7 +64,7 @@ export class Logger {
   }
 
   /**
-   * @param {import('./utilities/log-types.js').LogContext} context - Context to bind ot the async context.
+   * @param {LogContext} context - Context to bind ot the async context.
    * @returns {void}
    */
   static addAsyncContext(context) {
@@ -81,7 +86,7 @@ export class Logger {
   /**
    * @template [R=unknown]
    * @overload
-   * @param {import('./utilities/log-types.js').LogContext} context - Context to bind ot the async context.
+   * @param {LogContext} context - Context to bind ot the async context.
    * @param {() => R} callback - The function to wrap the context in.
    * @returns {R}
    */
@@ -103,14 +108,14 @@ export class Logger {
     }
 
     return Logger.storage.run(
-      [ ...store, /** @type {import('./utilities/log-types.js').LogContext} */ (context) ],
+      [ ...store, /** @type {LogContext} */ (context) ],
       /** @type {() => R} */ (callback),
     );
   }
 
   /**
-   * @param {import('./utilities/log-types.js').LogContext} context - The new context.
-   * @param {import('./utilities/log-types.js').LogLevel} [level] - The log level at which we allow this context.
+   * @param {LogContext} context - The new context.
+   * @param {LogLevel} [level] - The log level at which we allow this context.
    * @returns {Logger}
    */
   #overrideContext(context, level) {
@@ -150,27 +155,27 @@ export class Logger {
   /**
    * Creating a new logger with {context, ...this.context}.
    * @overload
-   * @param {import('./utilities/log-types.js').LogContext} context - The new context.
+   * @param {LogContext} context - The new context.
    * @returns {Logger}
    */
   /**
    * Creating a new logger with {context, ...this.context}.
    * @overload
-   * @param {import('./utilities/log-types.js').LogContext} context - The new context.
-   * @param {import('./utilities/log-types.js').LogLevel} level - The log level at which we allow this context.
+   * @param {LogContext} context - The new context.
+   * @param {LogLevel} level - The log level at which we allow this context.
    * @returns {Logger}
    */
   /**
    * Creating a new logger with {context, ...this.context}.
    * @overload
-   * @param {import('./utilities/log-types.js').LogLevel} level - The log level at which we allow this context.
-   * @param {import('./utilities/log-types.js').LogContext} context - The new context.
+   * @param {LogLevel} level - The log level at which we allow this context.
+   * @param {LogContext} context - The new context.
    * @returns {Logger}
    */
   /**
    * Creating a new logger with {context, ...this.context}.
-   * @param {import('./utilities/log-types.js').LogContext | import('./utilities/log-types.js').LogLevel} contextOrLevel - The log level at which we allow this context.
-   * @param {import('./utilities/log-types.js').LogLevel | import('./utilities/log-types.js').LogContext} [levelOrContext] - The new context.
+   * @param {LogContext | LogLevel} contextOrLevel - The log level at which we allow this context.
+   * @param {LogLevel | LogContext} [levelOrContext] - The new context.
    * @returns {Logger}
    */
   context(contextOrLevel, levelOrContext) {
@@ -207,31 +212,31 @@ export class Logger {
    * Write a log with the level 'critical' - A crucial part of the application is not working.
    *
    * @param {Error | string} message - The message to log.
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Additional context.
+   * @param {LogContext} [context] - Additional context.
    * @returns {void}
    */
   critical(message, context) {
-    return this.write(LogLevels.critical, message, context);
+    this.write(LogLevels.critical, message, context);
   }
 
   /**
    * Write a log with the level 'debug' - Information that is unlikely to help in production.
    * @param {Error | string} message - The message to log.
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Additional context.
+   * @param {LogContext} [context] - Additional context.
    * @returns {void}
    */
   debug(message, context) {
-    return this.write(LogLevels.debug, message, context);
+    this.write(LogLevels.debug, message, context);
   }
 
   /**
    * Write a log with the level 'error' - A non critical operation fails.
    * @param {Error | string} message - The message to log.
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Additional context.
+   * @param {LogContext} [context] - Additional context.
    * @returns {void}
    */
   error(message, context) {
-    return this.write(LogLevels.error, message, context);
+    this.write(LogLevels.error, message, context);
   }
 
   /**
@@ -246,21 +251,21 @@ export class Logger {
   /**
    * Write a log with the level 'info' - Information about successful operations.
    * @param {Error | string} message - The message to log.
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Additional context.
+   * @param {LogContext} [context] - Additional context.
    * @returns {void}
    */
   info(message, context) {
-    return this.write(LogLevels.info, message, context);
+    this.write(LogLevels.info, message, context);
   }
 
   /**
    * Write a log with the level 'notice' - Information about events that may be unusual.
    * @param {Error | string} message - The message to log.
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Additional context.
+   * @param {LogContext} [context] - Additional context.
    * @returns {void}
    */
   notice(message, context) {
-    return this.write(LogLevels.notice, message, context);
+    this.write(LogLevels.notice, message, context);
   }
 
   /*
@@ -282,11 +287,11 @@ export class Logger {
   /**
    * Write a log with the level 'silly' - Information to help resolve complex logic issues.
    * @param {Error | string} message - The message to log.
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Additional context.
+   * @param {LogContext} [context] - Additional context.
    * @returns {void}
    */
   silly(message, context) {
-    return this.write(LogLevels.silly, message, context);
+    this.write(LogLevels.silly, message, context);
   }
 
   /**
@@ -306,11 +311,11 @@ export class Logger {
   /**
    * Write a log with the level 'warning' - An operation might fail in the future.
    * @param {Error | string} message - The message to log.
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Additional context.
+   * @param {LogContext} [context] - Additional context.
    * @returns {void}
    */
   warning(message, context) {
-    return this.write(LogLevels.warning, message, context);
+    this.write(LogLevels.warning, message, context);
   }
 
   /**
@@ -324,13 +329,13 @@ export class Logger {
 
   /**
    * Write a new log entry.
-   * @param {import('./utilities/log-types.js').LogLevel} level - The log level of the message to log.
+   * @param {LogLevel} level - The log level of the message to log.
    * @param {Error | string} message - The message to log.
-   * @param {import('./utilities/log-types.js').LogContext} [context] - Context to add to the log (merged with this.context, and Logger.contexts).
+   * @param {LogContext} [context] - Context to add to the log (merged with this.context, and Logger.contexts).
    * @returns {void}
    */
   write(level, message, context) {
-    /** @type {import('./utilities/log-types.js').LogContext[]} */
+    /** @type {LogContext[]} */
     const contexts = [];
 
     const asyncContexts = Logger.storage.getStore();
@@ -344,7 +349,7 @@ export class Logger {
     }
 
     const fullContext =
-      /** @type {import('./utilities/log-types.js').LogContext} */
+      /** @type {LogContext} */
       (deepmerge(...contexts));
 
     if (
@@ -354,7 +359,7 @@ export class Logger {
       return;
     }
 
-    /** @type {import('./utilities/log-types.js').LogEntry} */
+    /** @type {LogEntry} */
     const entry = (
       typeof message === 'string'
         ? { ...fullContext, message, level }
@@ -374,11 +379,11 @@ export class Logger {
     }
 
     const normalised =
-      /** @type {import('./utilities/log-types.js').LogEntry} */
+      /** @type {LogEntry} */
       (this.#replace(entry, this.replacers));
 
     const formatted = this.#format(normalised);
 
-    return this.#write(formatted);
+    this.#write(formatted);
   }
 }

package/src/replacer.js

@@ -1,9 +1,9 @@
-import Traverse from 'traverse';
+import { createTraverse } from '@darksheep/traverse';
 
 import { nodesToPath } from './utilities/json-path.js';
 
 /**
- * @template [T=unknown]
+ * @template [T=any]
  * @template [O=unknown]
  * @typedef {Object} Replacer
  * @property {string} name - The name of the replacer.
@@ -18,31 +18,31 @@ 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 {import('traverse').TraverseContext}
-     */
-    function (value) {
+  const walk = createTraverse(
+    (context) => {
+      const value = context.node;
+
       if (value == null) {
-        return this.remove();
+        context.remove();
+        return;
       }
 
-      if (this.circular != null) {
-        return 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) {
-            return this.remove(replacer.stopHere);
+            context.remove();
+            return;
           }
 
-          return this.update(replaced, replacer.stopHere);
+          context.update(replaced, replacer.stopHere);
+          return;
         }
       }
 
@@ -52,7 +52,8 @@ export function replace(object, replacers = []) {
         typeof value.toJSON === 'function'
       ) {
         try {
-          return this.update(value.toJSON());
+          context.update(value.toJSON());
+          return;
         } catch { }
       }
 
@@ -61,19 +62,22 @@ export function replace(object, replacers = []) {
         Object.getPrototypeOf(value) !== Object.getPrototypeOf({}) &&
         Object.getPrototypeOf(value) !== Object.getPrototypeOf([])
       ) {
-        return 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/buffers.js

@@ -1,3 +1,7 @@
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
+
 /**
  * @param {Buffer} buffer - The buffer to convert to a string.
  * @returns {string}
@@ -6,7 +10,7 @@ function stringBuffer(buffer) {
   return buffer.toString('utf8');
 }
 
-/** @type {import('../replacer.js').Replacer<Buffer>} */
+/** @type {Replacer<Buffer>} */
 export const BufferReplacer = {
   name: 'Buffer',
   stopHere: true,

package/src/replacers/error.js

@@ -1,3 +1,6 @@
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
 import { parseStack } from '../utilities/stacktrace.js';
 
 /**
@@ -11,7 +14,7 @@ import { parseStack } from '../utilities/stacktrace.js';
  * @typedef {BaseError & { [k: string]: unknown }} NormalisedError
  */
 
-/** @type {import('../replacer.js').Replacer<Error, NormalisedError>} */
+/** @type {Replacer<Error, NormalisedError>} */
 export const ErrorReplacer = {
   name: 'Error',
   shouldReplace: (input) => input instanceof Error,
@@ -21,7 +24,7 @@ export const ErrorReplacer = {
 
     for (const key of Object.getOwnPropertyNames(value)) {
       if (Object.hasOwn(value, key)) {
-        // @ts-ignore - This is always going to be defined
+        // @ts-expect-error - This is always going to be defined
         error[key] = value[key];
       }
     }

package/src/replacers/http-client-request.js

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

package/src/replacers/http-incoming-message.js

@@ -1,11 +1,16 @@
+/**
+ * @import { ClientRequest } from 'node:http'
+ * @import { Replacer } from '../replacer.js'
+ */
+
 import { IncomingMessage } from 'node:http';
 
 /**
- * @type {import('../replacer.js').Replacer<
+ * @type {Replacer<
  *    IncomingMessage & {
  *      hostname?: string,
  *      originalUrl?: string,
- *      req?: import('node:http').ClientRequest
+ *      req?: ClientRequest
  *    }
  * >}
  */