@darksheep/logger 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [1.0.9](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.0.8...logger-v1.0.9) (2024-10-29)
+
+
+### 📚 Documentation
+
+* Better jsdoc wording ([#454](https://github.com/DarkSheepSoftware/node-packages/issues/454)) ([51c6996](https://github.com/DarkSheepSoftware/node-packages/commit/51c6996efc2e0fddd7f74c334e19fff196f02aab))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @darksheep/environment bumped from 3.0.9 to 3.1.0
+
+## [1.0.8](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.0.7...logger-v1.0.8) (2024-10-21)
+
+
+### 📦 Dependencies
+
+* **pkg:** update dependency deepmerge-ts to v7.1.3 ([0a489c4](https://github.com/DarkSheepSoftware/node-packages/commit/0a489c4d3ecf03facfa1e2b110bb219e41f50954))
+
+
+### 🧹 Chores
+
+* Apply stricter tsconfig to logger ([6be4b21](https://github.com/DarkSheepSoftware/node-packages/commit/6be4b21fda7c8975bd1344e7ae48c76156b05fa6))
+* Custom adjustments after eslint --fix ([9d9f082](https://github.com/DarkSheepSoftware/node-packages/commit/9d9f08276956c88918ac0f9e53689efe257c9017))
+
 ## [1.0.7](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.0.6...logger-v1.0.7) (2024-09-30)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksheep/logger",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Logging your stuff to where ever you want it",
   "license": "UNLICENCED",
   "type": "module",
@@ -13,25 +13,23 @@
   "files": [
     "src",
     "types",
-    "!*.test.js",
+    "!*.test.*",
     "!assert.zod.js"
   ],
   "scripts": {
-    "prepack": "tsc",
+    "prepack": "yarn dlx -q -p typescript tsc",
     "test": "node --test src/**/*.test.js",
     "test:watch": "node --watch --test src/**/*.test.js"
   },
   "dependencies": {
-    "@darksheep/environment": "3.0.9",
-    "deepmerge-ts": "7.1.0",
+    "@darksheep/environment": "3.1.0",
+    "deepmerge-ts": "7.1.3",
     "stacktrace-parser": "0.1.10",
     "traverse": "0.6.10"
   },
   "devDependencies": {
-    "@types/node": "~22.7.0",
     "@types/traverse": "~0.6.33",
     "nock": "~13.5.0",
-    "typescript": "~5.6.0",
     "zod": "~3.23.0"
   },
   "engines": {

package/src/create-logger.js

@@ -12,7 +12,7 @@ import {
 } from './replacers/index.js';
 
 /**
- * @param {string} [channel] The logging channel
+ * @param {string} [channel] - The logging channel.
  * @returns {import('./logger.js').Logger}
  */
 export function createLogger(channel) {

package/src/formatters/formatter-console.js

@@ -9,8 +9,8 @@ import { LogNames } from '../utilities/log-types.js';
 /** @typedef {import('../utilities/log-types.js').Callsite} Callsite */
 
 /**
- * @param {string} [channel] The channel string
- * @param {LogLevel} [level] The LogLevel number
+ * @param {string} [channel] - The channel string.
+ * @param {LogLevel} [level] - The LogLevel number.
  * @returns {string}
  */
 function flattenChannelLevel(channel, level) {
@@ -28,7 +28,7 @@ function flattenChannelLevel(channel, level) {
     output += '.';
   }
 
-  if (level != null) {
+  if (level != null && LogNames[level] != null) {
     output += `${LogNames[level].toUpperCase()}`;
   }
 
@@ -38,9 +38,9 @@ function flattenChannelLevel(channel, level) {
 }
 
 /**
- * @param {string} _match The whole match
- * @param {string} type The module type
- * @param {string} name The module name
+ * @param {string} _match - The whole match.
+ * @param {string} type - The module type.
+ * @param {string} name - The module name.
  * @returns {string}
  */
 function underlineName(_match, type, name) {
@@ -50,16 +50,16 @@ function underlineName(_match, type, name) {
 }
 
 /**
- * @param {Callsite} callsite The callsite to underline
+ * @param {Callsite} callsite - The callsite to underline.
  * @returns {string}
  */
 function formatFileSegment(callsite) {
   let { file } = callsite;
 
   file = file
-    .replace(/^((?:node:)?internal\/)([^/]+)/g, underlineName)
-    .replace(/^(\w+:)([a-z]\w+)$/g, underlineName)
-    .replace(/(node_modules\/)(@[^/]+\/[^/]+|[^/]+)/g, underlineName);
+    .replaceAll(/^(?:node:)?internal\/[^/]+/gu, underlineName)
+    .replaceAll(/^\w+:[a-z]\w+$/gu, underlineName)
+    .replaceAll(/node_modules\/(?:@[^/]+\/[^/]+|[^/]+)/gu, underlineName);
 
   if (typeof callsite.line === 'number') {
     file += `:${callsite.line}`;
@@ -73,7 +73,7 @@ function formatFileSegment(callsite) {
 }
 
 /**
- * @param {Callsite} callsite The node module callsite to format
+ * @param {Callsite} callsite - The node module callsite to format.
  * @returns {string}
  */
 function stackLineModule(callsite) {
@@ -89,7 +89,7 @@ function stackLineModule(callsite) {
 }
 
 /**
- * @param {Callsite} callsite The internal callsite to format
+ * @param {Callsite} callsite - The internal callsite to format.
  * @returns {string}
  */
 function stackLineInternal(callsite) {
@@ -101,7 +101,7 @@ function stackLineInternal(callsite) {
 }
 
 /**
- * @param {Callsite} callsite The callsite to format
+ * @param {Callsite} callsite - The callsite to format.
  * @returns {string}
  */
 function stackLine(callsite) {
@@ -133,10 +133,10 @@ function stackLine(callsite) {
   return `at ${callsite.methodName} (${file})`;
 }
 
-const fixEmpties = /^\{\s*\}$/;
+const fixEmpties = /^\{\s*\}$/u;
 
 /**
- * @param {LogContext} entry The entry we're going to convert
+ * @param {LogContext & { type?: unknown }} entry - The entry we're going to convert.
  * @returns {string}
  */
 function splatify(entry) {
@@ -160,8 +160,8 @@ function splatify(entry) {
 }
 
 /**
- * @param {Callsite[] | string | undefined} stack The stack trace to format
- * @param {number} indent The indent to render from
+ * @param {Callsite[] | string | undefined} stack - The stack trace to format.
+ * @param {number} indent - The indent to render from.
  * @returns {string}
  */
 function formatStack(stack, indent) {
@@ -174,14 +174,14 @@ function formatStack(stack, indent) {
   }
 
   return (stack ?? '')
-    .split(/\r?\n|\r/)
+    .split(/\r?\n|\r/u)
     .map((line) => `${pad}${line.trim()}`)
     .join('\n');
 }
 
 /**
- * @param {Error} error The error to render
- * @param {number} [indent] The indent to render from
+ * @param {Error} error - The error to render.
+ * @param {number} [indent] - The indent to render from.
  * @returns {string}
  */
 function formatError(error, indent = 0) {
@@ -213,7 +213,7 @@ function formatError(error, indent = 0) {
 }
 
 /**
- * @param {LogEntry} logEntry the Log entry which we're going to convert to a splatted string
+ * @param {LogEntry} logEntry - The Log entry which we're going to convert to a splatted string.
  * @returns {string}
  */
 export function formatterConsole(logEntry) {
@@ -238,7 +238,7 @@ export function formatterConsole(logEntry) {
   output += formatError(/** @type {Error} */ ({ message, stack, cause }));
 
   const context = splatify(entry)
-    .replace(/\r?\n|\r/g, '\n  ');
+    .replaceAll(/\r?\n|\r/gu, '\n  ');
 
   return `${output}\n  ${context}`.trim();
 }

package/src/formatters/formatter-json.js

@@ -1,5 +1,5 @@
 /**
- * @param {import('../utilities/log-types.js').LogEntry} logEntry the Log entry which we're going to convert to JSON
+ * @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) {

package/src/logger.js

@@ -13,10 +13,10 @@ 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 {typeof formatter} [format] The formatter function to use (eg console or json formatter)
- * @property {typeof stdoutWrite} [write] The place to write the log to
+ * @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 {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 {
@@ -38,8 +38,8 @@ export class Logger {
   /** @type {import('./replacer.js').Replacer[]} */
   replacers = [];
   /**
-   * @param {import('./utilities/log-types.js').LogContext} [context] Context to add to the logger
-   * @param {Options} [options] Options for the loggers output
+   * @param {import('./utilities/log-types.js').LogContext} [context] - Context to add to the logger.
+   * @param {Options} [options] - Options for the loggers output.
    */
   constructor(context, options) {
     this.#context = context ?? {};
@@ -58,7 +58,7 @@ export class Logger {
   }
 
   /**
-   * @param {import('./utilities/log-types.js').LogContext} context Context to bind ot the async context
+   * @param {import('./utilities/log-types.js').LogContext} context - Context to bind ot the async context.
    * @returns {void}
    */
   static addAsyncContext(context) {
@@ -74,20 +74,20 @@ export class Logger {
   /**
    * @template [R=unknown]
    * @overload
-   * @param {() => R} callback The function to wrap the context in
+   * @param {() => R} callback - The function to wrap the context in.
    * @returns {R}
    */
   /**
    * @template [R=unknown]
    * @overload
-   * @param {import('./utilities/log-types.js').LogContext} context Context to bind ot the async context
-   * @param {() => R} callback The function to wrap the context in
+   * @param {import('./utilities/log-types.js').LogContext} context - Context to bind ot the async context.
+   * @param {() => R} callback - The function to wrap the context in.
    * @returns {R}
    */
   /**
    * @template [R=unknown]
-   * @param {unknown} context Context to bind ot the async context
-   * @param {unknown} [callback] The function to wrap the context in
+   * @param {unknown} context - Context to bind ot the async context.
+   * @param {unknown} [callback] - The function to wrap the context in.
    * @returns {R}
    */
   static wrap(context, callback) {
@@ -108,8 +108,8 @@ export class Logger {
   }
 
   /**
-   * @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 {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.
    * @returns {Logger}
    */
   #overrideContext(context, level) {
@@ -132,42 +132,44 @@ export class Logger {
   }
 
   /**
-   * Set the channel in the new logger
-   * @param {string} channel The channel name
+   * Set the channel in the new logger.
+   * @param {string} channel - The channel name.
    * @returns {Logger}
    */
   channel(channel) {
     return this.set('channel', channel);
   }
 
-  // =========
-  //   Level
-  // =========
+  /*
+   * =========
+   *   Level
+   * =========
+   */
 
   /**
-   * Creating a new logger with {context, ...this.context}
+   * 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').LogContext} context - The new context.
    * @returns {Logger}
    */
   /**
-   * Creating a new logger with {context, ...this.context}
+   * 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 {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.
    * @returns {Logger}
    */
   /**
-   * Creating a new logger with {context, ...this.context}
+   * 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 {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.
    * @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
+   * 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.
    * @returns {Logger}
    */
   context(contextOrLevel, levelOrContext) {
@@ -201,10 +203,10 @@ export class Logger {
   }
 
   /**
-   * Write a log with the level 'critical' - A crucial part of the application is not working
+   * 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 {Error | string} message - The message to log.
+   * @param {import('./utilities/log-types.js').LogContext} [context] - Additional context.
    * @returns {void}
    */
   critical(message, context) {
@@ -212,9 +214,9 @@ export class Logger {
   }
 
   /**
-   * 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
+   * 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.
    * @returns {void}
    */
   debug(message, context) {
@@ -222,9 +224,9 @@ export class Logger {
   }
 
   /**
-   * 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
+   * 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.
    * @returns {void}
    */
   error(message, context) {
@@ -232,8 +234,8 @@ export class Logger {
   }
 
   /**
-   * Get a value from the context by key
-   * @param {string} key The key to get from the context
+   * Get a value from the context by key.
+   * @param {string} key - The key to get from the context.
    * @returns {unknown}
    */
   get(key) {
@@ -241,9 +243,9 @@ 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
+   * 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.
    * @returns {void}
    */
   info(message, context) {
@@ -251,23 +253,25 @@ export class Logger {
   }
 
   /**
-   * 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
+   * 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.
    * @returns {void}
    */
   notice(message, context) {
     return this.write(LogLevels.notice, message, context);
   }
 
-  // =========
-  //  Context
-  // =========
+  /*
+   * =========
+   *  Context
+   * =========
+   */
 
   /**
-   * Set a value into a new context by key
-   * @param {string} key The key to set
-   * @param {unknown} value The value to set
+   * Set a value into a new context by key.
+   * @param {string} key - The key to set.
+   * @param {unknown} value - The value to set.
    * @returns {Logger}
    */
   set(key, value) {
@@ -275,9 +279,9 @@ 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
+   * 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.
    * @returns {void}
    */
   silly(message, context) {
@@ -285,8 +289,8 @@ export class Logger {
   }
 
   /**
-   * Set the trail in the new logger
-   * @param {string} [trail] The trail id
+   * Set the trail in the new logger.
+   * @param {string} [trail] - The trail id.
    * @returns {Logger}
    */
   trail(trail) {
@@ -299,9 +303,9 @@ 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
+   * 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.
    * @returns {void}
    */
   warning(message, context) {
@@ -310,7 +314,7 @@ export class Logger {
 
   /**
    * @template [R=unknown]
-   * @param {() => R} callback The function to wrap the context in
+   * @param {() => R} callback - The function to wrap the context in.
    * @returns {R}
    */
   wrap(callback) {
@@ -318,10 +322,10 @@ 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 {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)
+   * Write a new log entry.
+   * @param {import('./utilities/log-types.js').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).
    * @returns {void}
    */
   write(level, message, context) {

package/src/replacer.js

@@ -6,23 +6,24 @@ import { nodesToPath } from './utilities/json-path.js';
  * @template [T=unknown]
  * @template [O=unknown]
  * @typedef {Object} Replacer
- * @property {string} name The name of the replacer
- * @property {(input: unknown, path?: string[]) => boolean} shouldReplace Check to see if input can be replaced
- * @property {(input: T, path?: string[]) => O} replace The replace function if shouldReplace returns true
- * @property {boolean} [stopHere] Should the traverse stop here
+ * @property {string} name - The name of the replacer.
+ * @property {(input: unknown, path?: string[]) => boolean} shouldReplace - Check to see if input can be replaced.
+ * @property {(input: T, path?: string[]) => O} replace - The replace function if shouldReplace returns true.
+ * @property {boolean} [stopHere] - Should the traverse stop here.
  */
 
 /**
- * @param {unknown} object The object we're replacing
- * @param {Replacer[]} replacers The Replacer array to execute
+ * @param {unknown} object - The object we're replacing.
+ * @param {Replacer[]} replacers - The Replacer array to execute.
  * @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
-     * @this {import('traverse').TraverseContext}
+     * @param {unknown} value - Current property in the traversed object.
      * @returns {void}
+     * @this {import('traverse').TraverseContext}
      */
     function (value) {
       if (value == null) {

package/src/replacers/buffers.js

@@ -1,5 +1,5 @@
 /**
- * @param {Buffer} buffer the buffer to convert to a string
+ * @param {Buffer} buffer - The buffer to convert to a string.
  * @returns {string}
  */
 function stringBuffer(buffer) {

package/src/replacers/error.js

@@ -2,9 +2,9 @@ import { parseStack } from '../utilities/stacktrace.js';
 
 /**
  * @typedef {Object} BaseError
- * @property {string} type The error type or name
- * @property {string} message The error message
- * @property {import('../utilities/stacktrace.js').Callsite[]} stack The stacktrace of the error
+ * @property {string} type - The error type or name.
+ * @property {string} message - The error message.
+ * @property {import('../utilities/stacktrace.js').Callsite[]} stack - The stacktrace of the error.
  */
 
 /**
@@ -17,11 +17,7 @@ export const ErrorReplacer = {
   shouldReplace: (input) => input instanceof Error,
   replace: (value) => {
     /** @type {Partial<NormalisedError>} */
-    const error = {
-      type: undefined,
-      message: undefined,
-      stack: undefined,
-    };
+    const error = {};
 
     for (const key of Object.getOwnPropertyNames(value)) {
       if (Object.hasOwn(value, key)) {

package/src/stdout-write.js

@@ -1,5 +1,5 @@
 /**
- * @param {string} output What should be written to stdout
+ * @param {string} output - What should be written to stdout.
  * @returns {void}
  */
 export function stdoutWrite(output) {