@darksheep/logger 1.3.1 → 1.4.0

package/types/index.d.ts

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

package/types/logger.d.ts

@@ -1,3 +1,31 @@
+/**
+ * @import { LogLevel, LogContext, LogEntry} from './utilities/log-types.js'
+ * @import { Replacer } from './replacer.js';
+ */
+import type { LogLevel, LogContext } from './utilities/log-types.js';
+import type { Replacer } from './replacer.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { formatter } from './formatter.js';
+import { replace } from './replacer.js';
+import { stdoutWrite } from './stdout-write.js';
+export type Options = {
+    /**
+     * - The replacer function to use.
+     */
+    replace?: typeof replace;
+    /**
+     * - The replacers to use in the replacer.
+     */
+    replacers?: Replacer[];
+    /**
+     * - The formatter function to use (eg console or json formatter).
+     */
+    format?: typeof formatter;
+    /**
+     * - The place to write the log to.
+     */
+    write?: typeof stdoutWrite;
+};
 /**
  * @typedef {Object} Options
  * @property {typeof replace} [replace] - The replacer function to use.
@@ -5,9 +33,17 @@
  * @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 {
+export declare class Logger {
+    #private;
     /** @type {AsyncLocalStorage<LogContext[]>} */
     static storage: AsyncLocalStorage<LogContext[]>;
+    /** @type {Replacer[]} */
+    replacers: Replacer[];
+    /**
+     * @param {LogContext} [context] - Context to add to the logger.
+     * @param {Options} [options] - Options for the loggers output.
+     */
+    constructor(context?: LogContext, options?: Options);
     /**
      * @param {LogContext} context - Context to bind ot the async context.
      * @returns {void}
@@ -19,7 +55,26 @@ export class Logger {
      * @param {() => R} callback - The function to wrap the context in.
      * @returns {R}
      */
+    /**
+     * @template [R=unknown]
+     * @overload
+     * @param {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.
+     * @returns {R}
+     */
     static wrap<R = unknown>(callback: () => R): R;
+    /**
+     * @template [R=unknown]
+     * @overload
+     * @param {() => R} callback - The function to wrap the context in.
+     * @returns {R}
+     */
     /**
      * @template [R=unknown]
      * @overload
@@ -27,14 +82,13 @@ export class Logger {
      * @param {() => R} callback - The function to wrap the context in.
      * @returns {R}
      */
-    static wrap<R = unknown>(context: LogContext, callback: () => R): R;
     /**
-     * @param {LogContext} [context] - Context to add to the logger.
-     * @param {Options} [options] - Options for the loggers output.
+     * @template [R=unknown]
+     * @param {unknown} context - Context to bind ot the async context.
+     * @param {unknown} [callback] - The function to wrap the context in.
+     * @returns {R}
      */
-    constructor(context?: LogContext, options?: Options);
-    /** @type {Replacer[]} */
-    replacers: Replacer[];
+    static wrap<R = unknown>(context: LogContext, callback: () => R): R;
     /**
      * Set the channel in the new logger.
      * @param {string} channel - The channel name.
@@ -47,15 +101,67 @@ export class Logger {
      * @param {LogContext} context - The new context.
      * @returns {Logger}
      */
+    /**
+     * Creating a new logger with {context, ...this.context}.
+     * @overload
+     * @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 {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 {LogContext | LogLevel} contextOrLevel - The log level at which we allow this context.
+     * @param {LogLevel | LogContext} [levelOrContext] - The new context.
+     * @returns {Logger}
+     */
     context(context: LogContext): Logger;
     /**
      * Creating a new logger with {context, ...this.context}.
      * @overload
      * @param {LogContext} context - The new context.
+     * @returns {Logger}
+     */
+    /**
+     * Creating a new logger with {context, ...this.context}.
+     * @overload
+     * @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 {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 {LogContext | LogLevel} contextOrLevel - The log level at which we allow this context.
+     * @param {LogLevel | LogContext} [levelOrContext] - The new context.
      * @returns {Logger}
      */
     context(context: LogContext, level: LogLevel): Logger;
+    /**
+     * Creating a new logger with {context, ...this.context}.
+     * @overload
+     * @param {LogContext} context - The new context.
+     * @returns {Logger}
+     */
+    /**
+     * Creating a new logger with {context, ...this.context}.
+     * @overload
+     * @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
@@ -63,6 +169,12 @@ export class Logger {
      * @param {LogContext} context - The new context.
      * @returns {Logger}
      */
+    /**
+     * Creating a new logger with {context, ...this.context}.
+     * @param {LogContext | LogLevel} contextOrLevel - The log level at which we allow this context.
+     * @param {LogLevel | LogContext} [levelOrContext] - The new context.
+     * @returns {Logger}
+     */
     context(level: LogLevel, context: LogContext): Logger;
     /**
      * Write a log with the level 'critical' - A crucial part of the application is not working.
@@ -147,30 +259,4 @@ export class Logger {
      * @returns {void}
      */
     write(level: LogLevel, message: Error | string, context?: LogContext): void;
-    #private;
 }
-export type Options = {
-    /**
-     * - The replacer function to use.
-     */
-    replace?: typeof replace;
-    /**
-     * - The replacers to use in the replacer.
-     */
-    replacers?: Replacer[];
-    /**
-     * - The formatter function to use (eg console or json formatter).
-     */
-    format?: typeof formatter;
-    /**
-     * - The place to write the log to.
-     */
-    write?: typeof stdoutWrite;
-};
-import type { Replacer } from './replacer.js';
-import type { LogContext } from './utilities/log-types.js';
-import type { LogLevel } from './utilities/log-types.js';
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { replace } from './replacer.js';
-import { formatter } from './formatter.js';
-import { stdoutWrite } from './stdout-write.js';

package/types/replacer.d.ts

@@ -1,18 +1,3 @@
-/**
- * @template [T=any]
- * @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.
- */
-/**
- * @param {unknown} object - The object we're replacing.
- * @param {Replacer[]} replacers - The Replacer array to execute.
- * @returns {unknown}
- */
-export function replace(object: unknown, replacers?: Replacer[]): unknown;
 export type Replacer<T = any, O = unknown> = {
     /**
      * - The name of the replacer.
@@ -31,3 +16,18 @@ export type Replacer<T = any, O = unknown> = {
      */
     stopHere?: boolean;
 };
+/**
+ * @template [T=any]
+ * @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.
+ */
+/**
+ * @param {unknown} object - The object we're replacing.
+ * @param {Replacer[]} replacers - The Replacer array to execute.
+ * @returns {unknown}
+ */
+export declare function replace(object: unknown, replacers?: Replacer[]): unknown;

package/types/replacers/buffers.d.ts

@@ -1,3 +1,6 @@
-/** @type {Replacer<Buffer>} */
-export const BufferReplacer: Replacer<Buffer>;
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
 import type { Replacer } from '../replacer.js';
+/** @type {Replacer<Buffer>} */
+export declare const BufferReplacer: Replacer<Buffer>;

package/types/replacers/error.d.ts

@@ -1,14 +1,4 @@
-/**
- * @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.
- */
-/**
- * @typedef {BaseError & { [k: string]: unknown }} NormalisedError
- */
-/** @type {Replacer<Error, NormalisedError>} */
-export const ErrorReplacer: Replacer<Error, NormalisedError>;
+import type { Replacer } from '../replacer.js';
 export type BaseError = {
     /**
      * - The error type or name.
@@ -21,9 +11,19 @@ export type BaseError = {
     /**
      * - The stacktrace of the error.
      */
-    stack: import("../utilities/stacktrace.js").Callsite[];
+    stack: import('../utilities/stacktrace.js').Callsite[];
 };
 export type NormalisedError = BaseError & {
     [k: string]: unknown;
 };
-import type { Replacer } from '../replacer.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.
+ */
+/**
+ * @typedef {BaseError & { [k: string]: unknown }} NormalisedError
+ */
+/** @type {Replacer<Error, NormalisedError>} */
+export declare const ErrorReplacer: Replacer<Error, NormalisedError>;

package/types/replacers/http-client-request.d.ts

@@ -1,4 +1,7 @@
-/** @type {Replacer<ClientRequest>} */
-export const HttpClientRequestReplacer: Replacer<ClientRequest>;
-import { ClientRequest } from 'node:http';
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
 import type { Replacer } from '../replacer.js';
+import { ClientRequest } from 'node:http';
+/** @type {Replacer<ClientRequest>} */
+export declare const HttpClientRequestReplacer: Replacer<ClientRequest>;

package/types/replacers/http-incoming-message.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @import { ClientRequest } from 'node:http'
+ * @import { Replacer } from '../replacer.js'
+ */
+import type { ClientRequest } from 'node:http';
+import type { Replacer } from '../replacer.js';
+import { IncomingMessage } from 'node:http';
 /**
  * @type {Replacer<
  *    IncomingMessage & {
@@ -7,11 +14,8 @@
  *    }
  * >}
  */
-export const HttpIncomingMessageReplacer: Replacer<IncomingMessage & {
+export declare const HttpIncomingMessageReplacer: Replacer<IncomingMessage & {
     hostname?: string;
     originalUrl?: string;
     req?: ClientRequest;
 }>;
-import { IncomingMessage } from 'node:http';
-import type { ClientRequest } from 'node:http';
-import type { Replacer } from '../replacer.js';

package/types/replacers/http-server-response.d.ts

@@ -1,4 +1,7 @@
-/** @type {Replacer<ServerResponse>} */
-export const HttpServerResponseReplacer: Replacer<ServerResponse>;
-import { ServerResponse } from 'node:http';
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
 import type { Replacer } from '../replacer.js';
+import { ServerResponse } from 'node:http';
+/** @type {Replacer<ServerResponse>} */
+export declare const HttpServerResponseReplacer: Replacer<ServerResponse>;

package/types/replacers/index.d.ts

@@ -1,8 +1,8 @@
-export { BufferReplacer } from "./buffers.js";
-export { ErrorReplacer } from "./error.js";
-export { HttpClientRequestReplacer } from "./http-client-request.js";
-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 { BufferReplacer } from './buffers.js';
+export { ErrorReplacer } from './error.js';
+export { HttpClientRequestReplacer } from './http-client-request.js';
+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 { SecretRedact, SecretRemove } from './secrets.js';

package/types/replacers/long-strings.d.ts

@@ -1,3 +1,6 @@
-/** @type {Replacer<string>} */
-export const LongStringReplacer: Replacer<string>;
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
 import type { Replacer } from '../replacer.js';
+/** @type {Replacer<string>} */
+export declare const LongStringReplacer: Replacer<string>;

package/types/replacers/net-socket.d.ts

@@ -1,4 +1,7 @@
-/** @type {Replacer<Socket>} */
-export const NetSocketReplacer: Replacer<Socket>;
-import { Socket } from 'node:net';
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
 import type { Replacer } from '../replacer.js';
+import { Socket } from 'node:net';
+/** @type {Replacer<Socket>} */
+export declare const NetSocketReplacer: Replacer<Socket>;

package/types/replacers/secrets.d.ts

@@ -1,5 +1,8 @@
+/**
+ * @import { Replacer } from '../replacer.js';
+ */
+import type { Replacer } from '../replacer.js';
 /** @type {Replacer} */
-export const SecretDelete: Replacer;
+export declare const SecretRemove: Replacer;
 /** @type {Replacer} */
-export const SecretObscure: Replacer;
-import type { Replacer } from '../replacer.js';
+export declare const SecretRedact: Replacer;

package/types/stdout-write.d.ts

@@ -2,4 +2,4 @@
  * @param {string} output - What should be written to stdout.
  * @returns {void}
  */
-export function stdoutWrite(output: string): void;
+export declare function stdoutWrite(output: string): void;

package/types/utilities/colour.d.ts

@@ -1,17 +1,21 @@
-/**
- * Should colours be used in the output.
- * @returns {boolean}
- */
-export function shouldColour(): boolean;
-/**
- * Colour a string.
- * @param {string} string - The string to colour.
- * @param {ColourOptions | undefined} [options] - The options to use to colour the string.
- * @returns {string}
- */
-export function colourString(string: string, options?: ColourOptions | undefined): string;
+declare const colours: Readonly<{
+    black: "0";
+    red: "1";
+    green: "2";
+    yellow: "3";
+    blue: "4";
+    magenta: "5";
+    cyan: "6";
+    white: "7";
+}>;
+declare const effects: Readonly<{
+    bold: number[];
+    faint: number[];
+    italic: number[];
+    underline: number[];
+}>;
 export type ColourNames = keyof typeof colours;
-export type ColourMode = "bright" | "dim";
+export type ColourMode = 'bright' | 'dim';
 export type ColourEffects = keyof typeof effects;
 export type ColourOptions = {
     /**
@@ -37,22 +41,18 @@ export type ColourOptions = {
     /**
      * - How to handle the string termination.
      */
-    reset?: boolean | Omit<ColourOptions, "reset">;
+    reset?: boolean | Omit<ColourOptions, 'reset'>;
 };
-declare const colours: Readonly<{
-    black: "0";
-    red: "1";
-    green: "2";
-    yellow: "3";
-    blue: "4";
-    magenta: "5";
-    cyan: "6";
-    white: "7";
-}>;
-declare const effects: Readonly<{
-    bold: number[];
-    faint: number[];
-    italic: number[];
-    underline: number[];
-}>;
+/**
+ * Should colours be used in the output.
+ * @returns {boolean}
+ */
+export declare function shouldColour(): boolean;
+/**
+ * Colour a string.
+ * @param {string} string - The string to colour.
+ * @param {ColourOptions | undefined} [options] - The options to use to colour the string.
+ * @returns {string}
+ */
+export declare function colourString(string: string, options?: ColourOptions | undefined): string;
 export {};

package/types/utilities/environment.d.ts

@@ -1,25 +1,17 @@
-export namespace environment {
-    export { LOG_CALLSITES as includeCallsite };
-    export { LOG_CPU as includeCpuUsage };
-    export { LOG_MEMORY as includeMemoryUsage };
-    export let isDevelopment: boolean;
-    export let isProduction: boolean;
-    export let isTesting: boolean;
-    export let logFilters: {
+export declare const environment: {
+    includeCallsite: boolean;
+    includeCpuUsage: boolean;
+    includeMemoryUsage: boolean;
+    isDevelopment: boolean;
+    isProduction: boolean;
+    isTesting: boolean;
+    logFilters: {
         allowed: RegExp[];
         blocked: RegExp[];
     };
-    export let logLevel: import("./log-types.js").LogLevel;
-    export let secretFilters: {
-        allowed: RegExp[];
-        blocked: RegExp[];
-    };
-    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 {};
+    logLevel: import("./log-types.js").LogLevel;
+    redactFilters: import("./legacy-secrets.js").Filters;
+    relativeTo: string | undefined;
+    removeFilters: import("./legacy-secrets.js").Filters;
+    stringMaxLength: number;
+};

package/types/utilities/json-path.d.ts

@@ -2,4 +2,4 @@
  * @param {string[]} nodes - The nodes to the element.
  * @returns {string}
  */
-export function nodesToPath(nodes: string[]): string;
+export declare function nodesToPath(nodes: string[]): string;

package/types/utilities/last-callsite.d.ts

@@ -2,7 +2,7 @@
  * Get the callsite that we think is outside the package.
  * @returns {{ file: string, line: number, column: number } | void}
  */
-export function getLastCallsite(): {
+export declare function getLastCallsite(): {
     file: string;
     line: number;
     column: number;

package/types/utilities/legacy-secrets.d.ts

@@ -0,0 +1,33 @@
+export type Filters = {
+    allowed: RegExp[];
+    blocked: RegExp[];
+};
+/**
+ * @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 declare function resolveSecretFilters({ secrets, redact, remove }: {
+    secrets?: string | undefined;
+    redact?: string | undefined;
+    remove?: string | undefined;
+}): {
+    redactFilters: Filters;
+    removeFilters: Filters;
+};

package/types/utilities/log-filters.d.ts

@@ -3,10 +3,10 @@
  * @param {import('./log-types.js').LogLevel} level - The log level to check.
  * @returns {boolean}
  */
-export function checkLogLevel(level: import("./log-types.js").LogLevel): boolean;
+export declare function checkLogLevel(level: import('./log-types.js').LogLevel): boolean;
 /**
  * Check to see if a message with {channel} should get logged.
  * @param {string} [channel] - The channel to check.
  * @returns {boolean}
  */
-export function checkLogFilters(channel?: string): boolean;
+export declare function checkLogFilters(channel?: string): boolean;