@darksheep/logger 1.0.0

package/types/logger.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @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
+ */
+export class Logger {
+    /** @type {AsyncLocalStorage<import('./utilities/log-types.js').LogContext[]>} */
+    static storage: AsyncLocalStorage<import("./utilities/log-types.js").LogContext[]>;
+    /**
+     * @template [R=unknown]
+     * @overload
+     * @param {() => R} callback The function to wrap the context in
+     * @returns {R}
+     */
+    static wrap<R = unknown>(callback: () => R): 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
+     * @returns {R}
+     */
+    static wrap<R = unknown>(context: import("./utilities/log-types.js").LogContext, callback: () => R): R;
+    /**
+     * @param {import('./utilities/log-types.js').LogContext} context Context to bind ot the async context
+     * @returns {void}
+     */
+    static addAsyncContext(context: import("./utilities/log-types.js").LogContext): void;
+    /**
+     * @param {import('./utilities/log-types.js').LogContext} [context] Context to add to the logger
+     * @param {Options} [options] Options for the loggers output
+     */
+    constructor(context?: import("./utilities/log-types.js").LogContext | undefined, options?: Options | undefined);
+    /**
+     * @template [R=unknown]
+     * @param {() => R} callback The function to wrap the context in
+     * @returns {R}
+     */
+    wrap<R = unknown>(callback: () => R): R;
+    /** @type {import('./replacer.js').Replacer[]} */
+    replacers: import("./replacer.js").Replacer[];
+    /**
+     * 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: import("./utilities/log-types.js").LogLevel, message: Error | string, context?: import("./utilities/log-types.js").LogContext | undefined): void;
+    /**
+     * 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
+     * @returns {void}
+     */
+    critical(message: Error | string, context?: import("./utilities/log-types.js").LogContext | undefined): void;
+    /**
+     * 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: Error | string, context?: import("./utilities/log-types.js").LogContext | undefined): void;
+    /**
+     * 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: Error | string, context?: import("./utilities/log-types.js").LogContext | undefined): void;
+    /**
+     * 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: Error | string, context?: import("./utilities/log-types.js").LogContext | undefined): void;
+    /**
+     * 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: Error | string, context?: import("./utilities/log-types.js").LogContext | undefined): void;
+    /**
+     * 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: Error | string, context?: import("./utilities/log-types.js").LogContext | undefined): void;
+    /**
+     * 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: Error | string, context?: import("./utilities/log-types.js").LogContext | undefined): void;
+    /**
+     * Creating a new logger with {context, ...this.context}
+     * @overload
+     * @param {import('./utilities/log-types.js').LogContext} context The new context
+     * @returns {Logger}
+     */
+    context(context: import("./utilities/log-types.js").LogContext): 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
+     * @returns {Logger}
+     */
+    context(context: import("./utilities/log-types.js").LogContext, level: import("./utilities/log-types.js").LogLevel): 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
+     * @returns {Logger}
+     */
+    context(level: import("./utilities/log-types.js").LogLevel, context: import("./utilities/log-types.js").LogContext): Logger;
+    /**
+     * Get a value from the context by key
+     * @param {string} key The key to get from the context
+     * @returns {unknown}
+     */
+    get(key: string): unknown;
+    /**
+     * 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: string, value: unknown): Logger;
+    /**
+     * Set the channel in the new logger
+     * @param {string} channel The channel name
+     * @returns {Logger}
+     */
+    channel(channel: string): Logger;
+    /**
+     * Set the trail in the new logger
+     * @param {string} [trail] The trail id
+     * @returns {Logger}
+     */
+    trail(trail?: string | undefined): Logger;
+    #private;
+}
+export type Options = {
+    /**
+     * The replacer function to use
+     */
+    /**
+     * The replacer function to use
+     */
+    replace?: typeof replace | undefined;
+    /**
+     * The replacers to use in the replacer
+     */
+    /**
+     * The replacers to use in the replacer
+     */
+    replacers?: import("./replacer.js").Replacer<any, any>[] | undefined;
+    /**
+     * The formatter function to use (eg console or json formatter)
+     */
+    /**
+     * The formatter function to use (eg console or json formatter)
+     */
+    format?: import("./formatter.js").Formatter | undefined;
+    /**
+     * The place to write the log to
+     */
+    /**
+     * The place to write the log to
+     */
+    write?: typeof stdoutWrite | undefined;
+};
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { replace } from './replacer.js';
+import { stdoutWrite } from './stdout-write.js';

package/types/logger.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/replacer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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
+ */
+/**
+ * @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 = unknown, O = unknown> = {
+    /**
+     * The name of the replacer
+     */
+    /**
+     * The name of the replacer
+     */
+    name: string;
+    /**
+     * Check to see if input can be replaced
+     */
+    /**
+     * Check to see if input can be replaced
+     */
+    shouldReplace: (input: unknown, path?: string[]) => boolean;
+    /**
+     * The replace function if shouldReplace returns true
+     */
+    /**
+     * The replace function if shouldReplace returns true
+     */
+    replace: (input: T, path?: string[]) => O;
+    /**
+     * Should the traverse stop here
+     */
+    /**
+     * Should the traverse stop here
+     */
+    stopHere?: boolean | undefined;
+};

package/types/replacer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/replacers/buffers.d.ts

@@ -0,0 +1,2 @@
+/** @type {import('../replacer.js').Replacer<Buffer>} */
+export const BufferReplacer: import("../replacer.js").Replacer<Buffer>;

package/types/replacers/buffers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/replacers/error.d.ts

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

package/types/replacers/error.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+/** @type {import('../replacer.js').Replacer<ClientRequest>} */
+export const HttpClientRequestReplacer: import("../replacer.js").Replacer<ClientRequest>;
+import { ClientRequest } from 'node:http';

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

@@ -0,0 +1 @@
+export {};

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

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

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

@@ -0,0 +1,3 @@
+/** @type {import('../replacer.js').Replacer<ServerResponse>} */
+export const HttpServerResponseReplacer: import("../replacer.js").Replacer<ServerResponse>;
+import { ServerResponse } from 'node:http';

package/types/replacers/index.d.ts

@@ -0,0 +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";

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

@@ -0,0 +1,2 @@
+/** @type {import('../replacer.js').Replacer<string>} */
+export const LongStringReplacer: import("../replacer.js").Replacer<string>;

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

@@ -0,0 +1,3 @@
+/** @type {import('../replacer.js').Replacer<Socket>} */
+export const NetSocketReplacer: import("../replacer.js").Replacer<Socket>;
+import { Socket } from 'node:net';

package/types/replacers/secrets.d.ts

@@ -0,0 +1,4 @@
+/** @type {import('../replacer.js').Replacer} */
+export const SecretDelete: import("../replacer.js").Replacer;
+/** @type {import('../replacer.js').Replacer} */
+export const SecretObscure: import("../replacer.js").Replacer;

package/types/stdout-write.d.ts

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

package/types/utilities/colour.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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} options The options to use to colour the string
+ * @returns {string}
+ */
+export function colourString(string: string, options: ColourOptions): string;
+export type ColourNames = keyof typeof colours;
+export type ColourMode = "bright" | "dim";
+export type ColourEffects = keyof typeof effects;
+export type ColourOptions = {
+    /**
+     * The foreground colour name
+     */
+    /**
+     * The foreground colour name
+     */
+    foreground?: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | undefined;
+    /**
+     * The foreground colour mode
+     */
+    /**
+     * The foreground colour mode
+     */
+    foregroundMode?: ColourMode | undefined;
+    /**
+     * The background colour name
+     */
+    /**
+     * The background colour name
+     */
+    background?: "black" | "red" | "green" | "yellow" | "blue" | "magenta" | "cyan" | "white" | undefined;
+    /**
+     * The background colour mode
+     */
+    /**
+     * The background colour mode
+     */
+    backgroundMode?: ColourMode | undefined;
+    /**
+     * The string effents
+     */
+    /**
+     * The string effents
+     */
+    effects?: ("bold" | "faint" | "italic" | "underline")[] | undefined;
+    /**
+     * How to handle the string termination
+     */
+    /**
+     * How to handle the string termination
+     */
+    reset?: boolean | Omit<ColourOptions, "reset"> | undefined;
+};
+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 {};

package/types/utilities/environment.d.ts

@@ -0,0 +1,25 @@
+export namespace environment {
+    export { isDevelopment };
+    export { isTesting };
+    export { isProduction };
+    export { logLevel };
+    export { logFilters };
+    export { secretFilters };
+    export { includeCallsite };
+    export { stringMaxLength };
+}
+declare const isDevelopment: boolean;
+declare const isTesting: boolean;
+declare const isProduction: boolean;
+declare const logLevel: import("./log-types.js").LogLevel;
+declare const logFilters: {
+    allowed: RegExp[];
+    blocked: RegExp[];
+};
+declare const secretFilters: {
+    allowed: RegExp[];
+    blocked: RegExp[];
+};
+declare const includeCallsite: boolean;
+declare const stringMaxLength: number;
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * @param {string[]} nodes The nodes to the element
+ * @returns {string}
+ */
+export function nodesToPath(nodes: string[]): string;

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

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

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

@@ -0,0 +1,12 @@
+/**
+ * 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: 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 | undefined): boolean;

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

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

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

@@ -0,0 +1,9 @@
+/**
+ * @param {string} [filter] The filter string
+ * @param {RegExp[]} [fallback] Fallback to the following allowed regexp
+ * @returns {{ allowed: RegExp[], blocked: RegExp[] }}
+ */
+export function parseFilters(filter?: string | undefined, fallback?: RegExp[] | undefined): {
+    allowed: RegExp[];
+    blocked: RegExp[];
+};

package/types/utilities/parse-log-level.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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?: string | undefined, node?: string | undefined): import("./log-types.js").LogLevel;