@darksheep/logger 1.0.0

package/src/utilities/colour.js

@@ -0,0 +1,152 @@
+const colours = Object.freeze({
+  black: '0',
+  red: '1',
+  green: '2',
+  yellow: '3',
+  blue: '4',
+  magenta: '5',
+  cyan: '6',
+  white: '7',
+});
+
+const effects = Object.freeze({
+  bold: [ 1, 2 ],
+  faint: [ 2, 2 ],
+  italic: [ 3, 3 ],
+  underline: [ 4, 4 ],
+  // blink: [ 5, 5 ],
+});
+
+const FOREGROUND = 3;
+const BACKGROUND = 4;
+
+/**
+ * @typedef {keyof typeof colours} ColourNames
+ * @typedef {'bright' | 'dim'} ColourMode
+ * @typedef {keyof typeof effects} ColourEffects
+ */
+
+/**
+ * @typedef {Object} ColourOptions
+ * @property {ColourNames} [foreground] The foreground colour name
+ * @property {ColourMode} [foregroundMode] The foreground colour mode
+ * @property {ColourNames} [background] The background colour name
+ * @property {ColourMode} [backgroundMode] The background colour mode
+ * @property {ColourEffects[]} [effects] The string effents
+ * @property {boolean | Omit<ColourOptions, 'reset'>} [reset] How to handle the string termination
+ */
+
+/**
+ * @param {ColourNames} colour  [description]
+ * @param {typeof FOREGROUND | typeof BACKGROUND} base  [description]
+ * @param {ColourMode} [mode]  [description]
+ * @returns {{ colour: typeof colours[ColourNames], mode: number }}
+ */
+function getColour(colour, base, mode) {
+  const colourCode = colours[colour];
+
+  if (mode === 'bright') {
+    return {
+      colour: colourCode,
+      mode: base + 6,
+    };
+  }
+
+  return {
+    colour: colourCode,
+    mode: base,
+  };
+}
+
+/**
+ * @param {ColourOptions} options How to colour the string
+ * @returns {{ prefix: string[], suffix: string[] }}
+ */
+function computeColours(options) {
+  const prefix = new Set();
+  const suffix = new Set();
+
+  if (options?.foreground != null) {
+    const { colour, mode } = getColour(
+      options.foreground,
+      FOREGROUND,
+      options.foregroundMode,
+    );
+
+    if (colour != null) {
+      prefix.add(`\x1B[${mode}${colour}m`);
+      suffix.add(`\x1B[${FOREGROUND}9m`);
+    }
+  }
+
+  if (options?.background != null) {
+    const { colour, mode } = getColour(
+      options.background,
+      BACKGROUND,
+      options.backgroundMode,
+    );
+
+    if (colour != null) {
+      prefix.add(`\x1B[${mode}${colour}m`);
+      suffix.add(`\x1B[${BACKGROUND}9m`);
+    }
+  }
+
+  if (options?.effects instanceof Array) {
+    for (const effect of options.effects) {
+      if (Object.hasOwn(effects, effect)) {
+        const [ start, end ] = effects[effect];
+        prefix.add(`\x1B[${start}m`);
+        suffix.add(`\x1B[2${end}m`);
+      }
+    }
+  }
+
+  return {
+    prefix: [ ...prefix ],
+    suffix: [ ...suffix ],
+  };
+}
+
+/**
+ * Should colours be used in the output
+ * @returns {boolean}
+ */
+export function shouldColour() {
+  if (
+    process?.stdout?.isTTY === false ||
+    typeof process?.stdout?.hasColors !== 'function'
+  ) {
+    return false;
+  }
+
+  return process.stdout.hasColors();
+}
+
+/**
+ * Colour a string
+ * @param {string} string The string to colour
+ * @param {ColourOptions} options The options to use to colour the string
+ * @returns {string}
+ */
+export function colourString(string, options) {
+  if (shouldColour() === false) {
+    return string;
+  }
+
+  const { prefix, suffix } = computeColours(options);
+
+  if (options?.reset === false) {
+    return `${prefix.join('')}${string}`;
+  }
+
+  if (
+    typeof options?.reset === 'string' ||
+    options?.reset instanceof Object
+  ) {
+    const { prefix: reset } = computeColours(options.reset);
+    return [ ...prefix, string, ...suffix, ...reset ].join('');
+  }
+
+  return [ ...prefix, string, ...suffix ].join('');
+}

package/src/utilities/environment.js

@@ -0,0 +1,61 @@
+import { parseLogLevel } from './parse-log-level.js';
+import { parseFilters } from './parse-filters.js';
+
+/**
+ * @param {undefined | string} input The env var to check for booleaness
+ * @param {boolean} fallback The fallback bool
+ * @returns {boolean}
+ */
+function parseBoolean(input, fallback) {
+  if (input === 'true' || input === '1') {
+    return true;
+  }
+
+  if (input === 'false' || input === '0') {
+    return false;
+  }
+
+  return fallback;
+}
+
+/**
+ * @param {undefined | string} input The env var to check to see if its an int
+ * @param {number} fallback The fallback number
+ * @returns {number}
+ */
+function parseInt(input, fallback) {
+  if (typeof input === 'string') {
+    const number = Number.parseInt(input, 10);
+
+    if (Number.isNaN(number) === false) {
+      return number;
+    }
+  }
+
+  return fallback;
+}
+
+const isDevelopment = process.env.NODE_ENV === 'development';
+const isTesting = process.env.NODE_ENV === 'test';
+const isProduction = process.env.NODE_ENV === 'production';
+
+const logLevel = parseLogLevel(
+  process.env.LOG_LEVEL,
+  process.env.NODE_ENV,
+);
+const logFilters = parseFilters(process.env.LOG_FILTERS, [ /.*/ ]);
+const secretFilters = parseFilters(process.env.LOG_SECRETS);
+const includeCallsite = parseBoolean(process.env.LOG_CALLSITES, false);
+const stringMaxLength = parseInt(process.env.LOG_MAX_LENGTH, 1024);
+
+export const environment = {
+  isDevelopment,
+  isTesting,
+  isProduction,
+
+  logLevel,
+  logFilters,
+  secretFilters,
+  includeCallsite,
+  stringMaxLength,
+};

package/src/utilities/json-path.js

@@ -0,0 +1,17 @@
+/**
+ * @param {string} path The json path component to escape
+ * @returns {string}
+ */
+function jsonPathEscape(path) {
+  return path
+    .replace(/\b~/g, '~0')
+    .replace(/\//g, '~1');
+}
+
+/**
+ * @param {string[]} nodes The nodes to the element
+ * @returns {string}
+ */
+export function nodesToPath(nodes) {
+  return `#/${nodes.map(jsonPathEscape).join('/')}`;
+}

package/src/utilities/last-callsite.js

@@ -0,0 +1,11 @@
+import { parseStack } from './stacktrace.js';
+
+/**
+ * Get the callsite that we think is outside the package
+ * @returns {{ file: string, line: number, column: number } | void}
+ */
+export function getLastCallsite() {
+  const { stack } = new Error('stacktrace');
+
+  return parseStack(stack).at(3);
+}

package/src/utilities/log-filters.js

@@ -0,0 +1,22 @@
+import { environment } from './environment.js';
+
+/**
+ * Check to see if {loggerLevel} should get logged
+ * @param {import('./log-types.js').LogLevel} level The log level to check
+ * @returns {boolean}
+ */
+export function checkLogLevel(level) {
+  return level <= environment.logLevel;
+}
+
+/**
+ * Check to see if a message with {channel} should get logged
+ * @param {string} [channel] The channel to check
+ * @returns {boolean}
+ */
+export function checkLogFilters(channel = '') {
+  return (
+    environment.logFilters.allowed.some((filter) => filter.test(channel)) === true &&
+    environment.logFilters.blocked.some((filter) => filter.test(channel)) === false
+  );
+}

package/src/utilities/log-types.js

@@ -0,0 +1,46 @@
+/**
+ * @typedef {Object} LogLevels
+ * @property {0} critical A crucial part of the application is not working
+ * @property {1} error A non critical operation fails
+ * @property {2} warning An operation might fail in the future
+ * @property {3} notice Information about events that may be unusual
+ * @property {4} info Information about successful operations
+ * @property {5} debug Information that is unlikely to help in production
+ * @property {6} silly Information to help resolve complex logic issues
+ */
+/** @type {LogLevels} */
+export const LogLevels = {
+  critical: 0,
+  error: 1,
+  warning: 2,
+  notice: 3,
+  info: 4,
+  debug: 5,
+  silly: 6,
+};
+
+export const LogNames = Object.fromEntries(
+  Object.entries(LogLevels).map(([ k, v ]) => [ v, k ]),
+);
+
+/** @typedef {keyof LogLevels} LogLevelNames */
+/** @typedef {LogLevels[LogLevelNames]} LogLevel */
+
+/** @typedef {import('./stacktrace.js').Callsite} Callsite */
+/** @typedef {import('../replacers/error.js').NormalisedError} NormalisedError */
+
+/**
+ * @typedef {Object} LogInternal
+ * @property {Date} [timestamp] A timestamp for the log message
+ * @property {string} [channel] A channel to bind to the log
+ * @property {LogLevel} [level] The log level
+ * @property {string} [message] A message to use
+ * @property {string | Callsite[]} [stack] The stack trace bound to the log
+ * @property {NormalisedError | Error} [cause] A child error for the core error
+ * @property {string} [trail] The trail id bound to the callsite
+ */
+
+/**
+ * @typedef {LogInternal & Record<string, unknown>} LogContext
+ * @typedef {{ level: LogLevel, message: string } & LogInternal & Record<string, unknown>} LogEntry
+ */

package/src/utilities/parse-filters.js

@@ -0,0 +1,47 @@
+const matcher = /^(-?)(?!-)(.+)$/;
+const oneLevelWildcard = /(?:(?!\.).)*/;
+const multiLevelWildcard = /.*/;
+
+/**
+ * @param {string} [filter] The filter string
+ * @param {RegExp[]} [fallback] Fallback to the following allowed regexp
+ * @returns {{ allowed: RegExp[], blocked: RegExp[] }}
+ */
+export function parseFilters(filter = '', fallback = []) {
+  const filters = filter.split(',');
+
+  const allowed = [];
+  const blocked = [];
+
+  for (const filter of filters) {
+    const [ , type, channel ] = filter.match(matcher) ?? [];
+
+    if (channel == null || channel === '') {
+      continue;
+    }
+
+    let regex = channel
+      .replace(/[\s#$()*+,.?[\\\]^{|}-]/g, '\\$&')
+      .replace(/\\\*/g, multiLevelWildcard.source)
+      .replace(/\\\+/g, oneLevelWildcard.source);
+
+    // Allow for multi level wildcards at the start of a filter
+    if (regex.startsWith('.*\\.')) {
+      regex = `(?:.*\\.)?${regex.slice(4)}`;
+    }
+
+    const pattern = new RegExp(`^${regex}$`);
+
+    if (type === '-') {
+      blocked.push(pattern);
+    } else {
+      allowed.push(pattern);
+    }
+  }
+
+  if (allowed.length === 0) {
+    allowed.push(...fallback);
+  }
+
+  return { allowed, blocked };
+}

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

@@ -0,0 +1,32 @@
+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}
+ */
+export function parseLogLevel(input, node) {
+  switch (input) {
+    case 'crit': return LogLevels.critical;
+    case 'critical': return LogLevels.critical;
+    case 'error': return LogLevels.error;
+    case 'warn': return LogLevels.warning;
+    case 'warning': return LogLevels.warning;
+    case 'notice': return LogLevels.notice;
+    case 'info': return LogLevels.info;
+    case 'debug': return LogLevels.debug;
+    case 'verbose': return LogLevels.debug;
+    case 'silly': return LogLevels.silly;
+  }
+
+  if (node === 'development') {
+    return LogLevels.debug;
+  }
+
+  if (node === 'test') {
+    return LogLevels.warning;
+  }
+
+  return LogLevels.info;
+}

package/src/utilities/stacktrace.js

@@ -0,0 +1,57 @@
+import { resolve, relative } from 'node:path';
+import { parse } from 'stacktrace-parser';
+
+/**
+ * @typedef {Object} Callsite
+ * @property {string} file The file name for the callsite
+ * @property {string} [relativePath] The relative path for the callsite.file
+ * @property {string} [absolutePath] The absolute path for the callsite.file
+ * @property {string} methodName The methodName from the callsite
+ * @property {number} line The line number in the file
+ * @property {number} column The column number in the file
+ */
+
+/**
+ * Get the callsite that we think is outside the package
+ * @param {string} [stack] The stacktrace to parse
+ * @returns {Callsite[]}
+ */
+export function parseStack(stack) {
+  /** @type {Callsite[]} */
+  const callsites = [];
+
+  if (stack == null) {
+    return callsites;
+  }
+
+  for (const callsite of parse(stack)) {
+    if (callsite.file == null) {
+      continue;
+    }
+
+    /** @type {Callsite} */
+    const site = {
+      file: callsite.file,
+      methodName: callsite.methodName,
+      line: callsite.lineNumber ?? 0,
+      column: (callsite.column ?? 1) - 1,
+    };
+
+    if (site.file.startsWith('file:')) {
+      site.file = site.file.slice(5);
+    }
+
+    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;
+    }
+
+    callsites.push(site);
+  }
+
+  return callsites;
+}

package/types/assert.zod.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @param {unknown} input  The input to convert to a zod schema
+ * @returns {ZodType}
+ */
+export function convertToZod(input: unknown): ZodType;
+/**
+ * @param {unknown} input The input object test with
+ * @returns {ZodType}
+ */
+export function objectContaining(input: unknown): ZodType;
+/**
+ * @param {unknown} actual The value we're testing
+ * @param {unknown} expected The schema we're testing against
+ * @returns {void}
+ */
+export function assertSchema(actual: unknown, expected: unknown): void;
+export * from "zod";
+import { ZodType } from 'zod';

package/types/create-logger.d.ts

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

package/types/formatter.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @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;

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

@@ -0,0 +1,9 @@
+/**
+ * @param {LogEntry} logEntry the Log entry which we're going to convert to a splatted string
+ * @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;

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

@@ -0,0 +1,5 @@
+/**
+ * @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;

package/types/index.d.ts

@@ -0,0 +1,11 @@
+export { Logger } from "./logger.js";
+export const logger: import("./logger.js").Logger;
+export { environment } from "./utilities/environment.js";
+export { createLogger } from "./create-logger.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 { SecretDelete, SecretObscure, BufferReplacer, ErrorReplacer, HttpClientRequestReplacer, HttpIncomingMessageReplacer, HttpServerResponseReplacer, LongStringReplacer, NetSocketReplacer } from "./replacers/index.js";