@darksheep/logger 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [1.3.0](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.2.0...logger-v1.3.0) (2025-10-09)
+
+
+### 🌟 Features
+
+* Support node 24 ([#761](https://github.com/DarkSheepSoftware/node-packages/issues/761)) ([f13caae](https://github.com/DarkSheepSoftware/node-packages/commit/f13caaef978c7a657e4599f775e0a62d1738f475))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @darksheep/environment bumped from 3.1.0 to 3.2.0
+
+## [1.2.0](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.1.0...logger-v1.2.0) (2025-04-19)
+
+
+### 🌟 Features
+
+* Improve stacktrace rendering and add resource usage options ([#621](https://github.com/DarkSheepSoftware/node-packages/issues/621)) ([2998c6d](https://github.com/DarkSheepSoftware/node-packages/commit/2998c6da2271673120e0673c6350555e2cfa7817))
+
 ## [1.1.0](https://github.com/DarkSheepSoftware/node-packages/compare/logger-v1.0.10...logger-v1.1.0) (2025-03-25)
 
 

package/README.md

@@ -188,4 +188,44 @@ const output = {
 
 #### `LOG_CALLSITES`
 
-This is simply a boolean to indicate whether or not the location of the place calling the log should be added to the context
+This is a boolean to indicate whether or not the location of the place calling the log should be added to the context. (Caution may not work if you're using a bundler).
+
+This is added to the context in the `source` property and has the form:
+
+```js
+{
+  file: 'logger/example.js',
+  methodName: '<unknown>',
+  line: 54,
+  column: 4
+}
+```
+
+#### `LOG_CPU`, `LOG_MEMORY`
+
+These are booleans to indicate whether to log current [memory usage](https://nodejs.org/api/process.html#processmemoryusage) and [cpu usage](https://nodejs.org/api/process.html#processcpuusagepreviousvalue).
+
+Cpu usage is added to the context in the `cpuUsage` property and has the following form:
+```js
+{
+  // Time between `cpuUsage` calls (microseconds)
+  elapsed: 735,
+  // Time spent in both `system` and `user` code (microseconds)
+  total: 237099,
+  // Time spent in `system` code (microseconds)
+  system: 37937,
+  // Time spent in `user` code (microseconds)
+  user: 199162
+}
+```
+
+Memory usage is added to the context in the `memoryUsage` property and has the following form, please see the [nodejs documentation (process.memoryUsage())](https://nodejs.org/api/process.html#processmemoryusage) for more information on properties
+```js
+{
+  arrayBuffers: 0.104148,
+  external: 3.523992,
+  heapTotal: 19.533824,
+  heapUsed: 11.618472,
+  rss: 79.192064
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksheep/logger",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Logging your stuff to where ever you want it",
   "license": "UNLICENCED",
   "type": "module",
@@ -21,7 +21,7 @@
     "test:watch": "node --watch --test src/**/*.test.js"
   },
   "dependencies": {
-    "@darksheep/environment": "3.1.0",
+    "@darksheep/environment": "3.2.0",
     "deepmerge-ts": "7.1.5",
     "stacktrace-parser": "0.1.11",
     "traverse": "0.6.11"
@@ -31,6 +31,6 @@
     "nock": "~14.0.0"
   },
   "engines": {
-    "node": "^20.13.1 || ^22.2.0"
+    "node": "^20.13.1 || >=22.2.0"
   }
 }

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

@@ -0,0 +1,183 @@
+/**
+ * @import { ColourOptions } from '../../utilities/colour.js';
+ * @import { Callsite } from '../../utilities/log-types.js';
+ */
+
+import { colourString } from '../../utilities/colour.js';
+
+/**
+ * @typedef {{ hide?: boolean }} HideOption
+ * @typedef {(
+ *   & HideOption
+ *   & {
+ *     Line?: Omit<ColourOptions, 'reset'>;
+ *     FunctionName?: Omit<ColourOptions, 'reset'> & HideOption;
+ *     FilePath?: Omit<ColourOptions, 'reset'>;
+ *     LineNumber?: Omit<ColourOptions, 'reset'> & HideOption;
+ *     ColumnNumber?: Omit<ColourOptions, 'reset'> & HideOption;
+ *   }
+ * )} LineOptions
+ */
+/**
+ * @type {{
+ *   moduleName?: Omit<ColourOptions, 'reset'>;
+ *   internalName?: Omit<ColourOptions, 'reset'>;
+ *   app?: LineOptions;
+ *   module?: LineOptions;
+ *   internal?: LineOptions;
+ * }}
+ */
+const Colours = {
+  moduleName: { effects: [ 'bold', 'underline' ] },
+
+  app: {
+    FunctionName: { foreground: 'white' },
+    FilePath: { foreground: 'blue', foregroundMode: 'bright' },
+    ColumnNumber: { hide: true },
+  },
+
+  module: {
+    Line: { foreground: 'yellow' },
+    FunctionName: { foreground: 'yellow', effects: [ 'bold' ] },
+    ColumnNumber: { hide: true },
+  },
+
+  internal: {
+    // hide: true,
+    Line: { foreground: 'black', foregroundMode: 'bright' },
+    ColumnNumber: { hide: true },
+  },
+};
+
+const internalNameMatch = /(?<=^(?:node:)?internal\/)[^/]+/gu;
+const nodeNameMatch = /(?<=^\w+:)[a-z]\w+$/gu;
+const moduleNameMatch = /(?<=node_modules\/)(?:@[-0-9a-z~][-.0-9_a-z~]*\/)?[-0-9a-z~][-.0-9_a-z~]*(?=\/|$)/gu;
+const modulePnpmMatch = /(?<=node_modules\/\.store\/)(?:@[-0-9a-z~][-.0-9_a-z~]*\/)?[-0-9a-z~][-.0-9_a-z~]*(?=-\w+-\d+\.\d+\.\d+-[0-9a-f]+\/)/gu;
+
+/**
+ * @param {Callsite} callsite - The callsite to underline.
+ * @param {ColourOptions} [lineColour] - The colour of the main string.
+ * @returns {string}
+ */
+function highlightFilePath(callsite, lineColour) {
+  const reset = lineColour ?? true;
+
+  const moduleOptions = { ...Colours.moduleName, reset };
+  const internalOptions = { ...Colours.moduleName, ...Colours.internalName, reset };
+
+  const file = callsite.file
+    .replaceAll(internalNameMatch, (string) => colourString(string, internalOptions))
+    .replaceAll(nodeNameMatch, (string) => colourString(string, internalOptions))
+    .replaceAll(moduleNameMatch, (string) => colourString(string, moduleOptions))
+    .replaceAll(modulePnpmMatch, (string) => colourString(string, moduleOptions));
+
+  return colourString(file, lineColour);
+}
+
+/**
+ * @param {number | undefined} [number] - The line or column number.
+ * @param {(ColourOptions & HideOption) | undefined} [options] - The formatting options.
+ * @param {string | undefined} [colon] - The formatting options.
+ * @returns {string}
+ */
+function highlightNumber(number, options, colon = ':') {
+  if (number == null || options?.hide === true) {
+    return '';
+  }
+
+  return `${colon}${colourString(`${number}`, options)}`;
+}
+
+/**
+ * @param {Callsite} callsite - The callsite to format.
+ * @param {LineOptions | undefined} options - The options and colours to use in the formatting.
+ * @returns {string | null}
+ */
+function formatStackLine(callsite, options) {
+  if (options?.hide === true) {
+    return null;
+  }
+
+  const colon = colourString(':', options?.Line);
+
+  const filePath = highlightFilePath(callsite, options?.FilePath ?? options?.Line);
+  const line = highlightNumber(
+    callsite.line,
+    options?.LineNumber ??
+    options?.FilePath ??
+    options?.Line,
+    colon,
+  );
+  const column = highlightNumber(
+    callsite.column,
+    options?.ColumnNumber ??
+    options?.LineNumber ??
+    options?.FilePath ??
+    options?.Line,
+    colon,
+  );
+
+  const at = colourString('at', options?.Line);
+
+  if (
+    options?.FunctionName?.hide === true ||
+    callsite.methodName == null
+  ) {
+    return `${at} ${filePath}${line}${column}`;
+  }
+
+  const ob = colourString('(', options?.Line);
+  const cb = colourString(')', options?.Line);
+
+  const methodName = colourString(callsite.methodName, options?.FunctionName ?? options?.Line);
+  return `${at} ${methodName} ${ob}${filePath}${line}${column}${cb}`;
+}
+
+/**
+ * @param {Callsite} callsite - The callsite to format.
+ * @returns {string | null}
+ */
+function stackLine(callsite) {
+  if (
+    callsite.file === '<anonymous>' ||
+    callsite.file.startsWith('node:') ||
+    callsite.file.startsWith('internal')
+  ) {
+    return formatStackLine(callsite, Colours.internal);
+  }
+
+  if (callsite.file.includes('node_modules')) {
+    return formatStackLine(callsite, Colours.module);
+  }
+
+  return formatStackLine(callsite, Colours.app);
+}
+
+/**
+ * @param {unknown} input - The possible string.
+ * @returns {input is string}
+ */
+function isString(input) {
+  return typeof input === 'string';
+}
+
+/**
+ * @param {Callsite[] | string | undefined} stack - The stack trace to format.
+ * @param {number} indent - The indent to render from.
+ * @returns {string}
+ */
+export function formatStack(stack, indent) {
+  const pad = ' '.repeat(indent + 2);
+  if (Array.isArray(stack)) {
+    return stack
+      .map(stackLine)
+      .filter(isString)
+      .map((line) => `${pad}${line.trim()}`)
+      .join('\n');
+  }
+
+  return (stack ?? '')
+    .split(/\r?\n|\r/u)
+    .map((line) => `${pad}${line.trim()}`)
+    .join('\n');
+}

package/src/formatters/formatter-console.js

@@ -1,12 +1,11 @@
+/**
+ * @import { LogContext, LogEntry, LogLevel } from '../utilities/log-types.js';
+ */
 import { inspect } from 'node:util';
 
 import { colourString, shouldColour } from '../utilities/colour.js';
 import { LogNames } from '../utilities/log-types.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('../utilities/log-types.js').Callsite} Callsite */
+import { formatStack } from './formatter-console/stack.js';
 
 /**
  * @param {string} [channel] - The channel string.
@@ -37,102 +36,6 @@ function flattenChannelLevel(channel, level) {
   return output;
 }
 
-/**
- * @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) {
-  const moduleName = colourString(name, { effects: [ 'underline' ] });
-
-  return `${type}${moduleName}`;
-}
-
-/**
- * @param {Callsite} callsite - The callsite to underline.
- * @returns {string}
- */
-function formatFileSegment(callsite) {
-  let { file } = callsite;
-
-  file = file
-    .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}`;
-  }
-
-  if (typeof callsite.column === 'number') {
-    file += `:${callsite.column}`;
-  }
-
-  return file;
-}
-
-/**
- * @param {Callsite} callsite - The node module callsite to format.
- * @returns {string}
- */
-function stackLineModule(callsite) {
-  const file = colourString(
-    formatFileSegment(callsite),
-    { effects: [ 'faint' ] },
-  );
-
-  return colourString(
-    `at ${callsite.methodName} (${file})`,
-    { foreground: 'yellow' },
-  );
-}
-
-/**
- * @param {Callsite} callsite - The internal callsite to format.
- * @returns {string}
- */
-function stackLineInternal(callsite) {
-  const file = formatFileSegment(callsite);
-  return colourString(
-    `at ${callsite.methodName} (${file})`,
-    { foreground: 'black', foregroundMode: 'bright' },
-  );
-}
-
-/**
- * @param {Callsite} callsite - The callsite to format.
- * @returns {string}
- */
-function stackLine(callsite) {
-  if (callsite.file.startsWith('node_modules')) {
-    return stackLineModule(callsite);
-  }
-
-  if (
-    callsite.file === '<anonymous>' ||
-    callsite.file.startsWith('node:') ||
-    callsite.file.startsWith('internal')
-  ) {
-    return stackLineInternal(callsite);
-  }
-
-  let file = colourString(callsite.file, {
-    foreground: 'green',
-    foregroundMode: 'bright',
-  });
-
-  file += `:${callsite.line}`;
-  if (typeof callsite.column === 'number') {
-    file += colourString(
-      `:${callsite.column}`,
-      { foreground: 'black', foregroundMode: 'bright' },
-    );
-  }
-
-  return `at ${callsite.methodName} (${file})`;
-}
-
 const fixEmpties = /^\{\s*\}$/u;
 
 /**
@@ -159,26 +62,6 @@ function splatify(entry) {
     .trim();
 }
 
-/**
- * @param {Callsite[] | string | undefined} stack - The stack trace to format.
- * @param {number} indent - The indent to render from.
- * @returns {string}
- */
-function formatStack(stack, indent) {
-  const pad = ' '.repeat(indent + 2);
-  if (Array.isArray(stack)) {
-    return stack
-      .map(stackLine)
-      .map((line) => `${pad}${line.trim()}`)
-      .join('\n');
-  }
-
-  return (stack ?? '')
-    .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.

package/src/logger.js

@@ -8,6 +8,7 @@ import { ErrorReplacer } from './replacers/error.js';
 import { stdoutWrite } from './stdout-write.js';
 import { environment } from './utilities/environment.js';
 import { getLastCallsite } from './utilities/last-callsite.js';
+import { getMemoryUsage, getCPUUsage } from './utilities/resource-usage.js';
 import { checkLogFilters, checkLogLevel } from './utilities/log-filters.js';
 import { LogLevels } from './utilities/log-types.js';
 
@@ -364,6 +365,14 @@ export class Logger {
       entry.source = getLastCallsite();
     }
 
+    if (environment.includeMemoryUsage === true) {
+      entry.memoryUsage = getMemoryUsage();
+    }
+
+    if (environment.includeCpuUsage === true) {
+      entry.cpuUsage = getCPUUsage();
+    }
+
     const normalised =
       /** @type {import('./utilities/log-types.js').LogEntry} */
       (this.#replace(entry, this.replacers));

package/src/utilities/colour.js

@@ -126,11 +126,11 @@ export function shouldColour() {
 /**
  * Colour a string.
  * @param {string} string - The string to colour.
- * @param {ColourOptions} options - The options to use to colour the string.
+ * @param {ColourOptions | undefined} [options] - The options to use to colour the string.
  * @returns {string}
  */
 export function colourString(string, options) {
-  if (shouldColour() === false) {
+  if (shouldColour() === false || options == null) {
     return string;
   }
 

package/src/utilities/environment.js

@@ -4,29 +4,37 @@ import { parseFilters } from './parse-filters.js';
 import { parseLogLevel } from './parse-log-level.js';
 
 const {
-  NODE_ENV = 'production',
-  LOG_LEVEL,
-  LOG_FILTERS,
-  LOG_SECRETS,
   LOG_CALLSITES = false,
+  LOG_CPU = false,
+  LOG_FILTERS,
+  LOG_LEVEL,
   LOG_MAX_LENGTH = 1024,
+  LOG_MEMORY = false,
+  LOG_SECRETS,
+  LOG_RELATIVE_TO,
+  NODE_ENV = 'production',
 } = getTypedEnv({
-  NODE_ENV: '?string',
-  LOG_LEVEL: '?string',
-  LOG_FILTERS: '?string',
-  LOG_SECRETS: '?string',
   LOG_CALLSITES: '?boolean',
+  LOG_CPU: '?boolean',
+  LOG_FILTERS: '?string',
+  LOG_LEVEL: '?string',
   LOG_MAX_LENGTH: '?number',
+  LOG_MEMORY: '?boolean',
+  LOG_SECRETS: '?string',
+  LOG_RELATIVE_TO: '?string',
+  NODE_ENV: '?string',
 });
 
 export const environment = {
+  includeCallsite: LOG_CALLSITES,
+  includeCpuUsage: LOG_CPU,
+  includeMemoryUsage: LOG_MEMORY,
   isDevelopment: NODE_ENV === 'development',
-  isTesting: NODE_ENV === 'test',
   isProduction: NODE_ENV === 'production',
-
-  logLevel: parseLogLevel(LOG_LEVEL, NODE_ENV),
+  isTesting: NODE_ENV === 'test',
   logFilters: parseFilters(LOG_FILTERS, [ /.*/u ]),
+  logLevel: parseLogLevel(LOG_LEVEL, NODE_ENV),
   secretFilters: parseFilters(LOG_SECRETS),
-  includeCallsite: LOG_CALLSITES,
+  relativeTo: LOG_RELATIVE_TO,
   stringMaxLength: LOG_MAX_LENGTH,
 };

package/src/utilities/resource-usage.js

@@ -0,0 +1,42 @@
+/**
+ * Get the current memory consumption.
+ * @returns {NodeJS.MemoryUsage}
+ */
+export function getMemoryUsage() {
+  const usage = process.memoryUsage();
+
+  return {
+    arrayBuffers: usage.arrayBuffers / 1_000_000,
+    external: usage.external / 1_000_000,
+    heapTotal: usage.heapTotal / 1_000_000,
+    heapUsed: usage.heapUsed / 1_000_000,
+    rss: usage.rss / 1_000_000,
+  };
+}
+
+let lastCalled = performance.now();
+let lastValue = process.cpuUsage();
+
+/**
+ * Get the callsite that we think is outside the package.
+ * @returns {Record<'elapsed'|'total'|'system'|'user', number> | void}
+ */
+export function getCPUUsage() {
+  /**
+   * Time since start in milliseconds with microseconds precision.
+   */
+  const currentCalled = performance.now();
+
+  /**
+   * Time difference in microseconds.
+   */
+  const elapsed = Math.floor(1000 * (currentCalled - lastCalled));
+
+  lastCalled = currentCalled;
+  lastValue = process.cpuUsage(lastValue);
+
+  const { system, user } = lastValue;
+  const total = system + user;
+
+  return { elapsed, total, system, user };
+}

package/src/utilities/stacktrace.js

@@ -1,6 +1,7 @@
 import { relative, resolve } from 'node:path';
 
 import { parse } from 'stacktrace-parser';
+import { environment } from './environment.js';
 
 /**
  * @typedef {Object} Callsite
@@ -43,12 +44,9 @@ export function parseStack(stack) {
     }
 
     if (site.file.startsWith('/')) {
-      site.relativePath = relative(process.cwd(), site.file);
-      site.absolutePath = resolve(site.file);
-
-      site.file = site.relativePath[0] === '.'
-        ? site.absolutePath
-        : site.relativePath;
+      site.file = typeof environment.relativeTo === 'string'
+        ? relative(resolve(environment.relativeTo), site.file)
+        : resolve(site.file);
     }
 
     callsites.push(site);

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

@@ -0,0 +1,18 @@
+/**
+ * @param {Callsite[] | string | undefined} stack - The stack trace to format.
+ * @param {number} indent - The indent to render from.
+ * @returns {string}
+ */
+export function formatStack(stack: Callsite[] | string | undefined, indent: number): string;
+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;
+});
+import type { Callsite } from '../../utilities/log-types.js';
+import type { ColourOptions } from '../../utilities/colour.js';

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

@@ -3,7 +3,4 @@
  * @returns {string}
  */
 export function formatterConsole(logEntry: LogEntry): string;
-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 Callsite = import("../utilities/log-types.js").Callsite;
+import type { LogEntry } from '../utilities/log-types.js';

package/types/utilities/colour.d.ts

@@ -6,10 +6,10 @@ export function shouldColour(): boolean;
 /**
  * Colour a string.
  * @param {string} string - The string to colour.
- * @param {ColourOptions} options - The options to use to colour the string.
+ * @param {ColourOptions | undefined} [options] - The options to use to colour the string.
  * @returns {string}
  */
-export function colourString(string: string, options: ColourOptions): string;
+export function colourString(string: string, options?: ColourOptions | undefined): string;
 export type ColourNames = keyof typeof colours;
 export type ColourMode = "bright" | "dim";
 export type ColourEffects = keyof typeof effects;

package/types/utilities/environment.d.ts

@@ -1,19 +1,25 @@
 export namespace environment {
+    export { LOG_CALLSITES as includeCallsite };
+    export { LOG_CPU as includeCpuUsage };
+    export { LOG_MEMORY as includeMemoryUsage };
     export let isDevelopment: boolean;
-    export let isTesting: boolean;
     export let isProduction: boolean;
-    export let logLevel: import("./log-types.js").LogLevel;
+    export let isTesting: boolean;
     export let logFilters: {
         allowed: RegExp[];
         blocked: RegExp[];
     };
+    export let logLevel: import("./log-types.js").LogLevel;
     export let secretFilters: {
         allowed: RegExp[];
         blocked: RegExp[];
     };
-    export { LOG_CALLSITES as includeCallsite };
+    export { LOG_RELATIVE_TO as relativeTo };
     export { LOG_MAX_LENGTH as stringMaxLength };
 }
 declare const LOG_CALLSITES: boolean;
+declare const LOG_CPU: boolean;
+declare const LOG_MEMORY: boolean;
+declare const LOG_RELATIVE_TO: string | undefined;
 declare const LOG_MAX_LENGTH: number;
 export {};

package/types/utilities/resource-usage.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Get the current memory consumption.
+ * @returns {NodeJS.MemoryUsage}
+ */
+export function getMemoryUsage(): NodeJS.MemoryUsage;
+/**
+ * Get the callsite that we think is outside the package.
+ * @returns {Record<'elapsed'|'total'|'system'|'user', number> | void}
+ */
+export function getCPUUsage(): Record<"elapsed" | "total" | "system" | "user", number> | void;