@reliverse/relinka 1.3.7 → 1.4.0

package/bin/{relinka-impl/deprecated → deprecated}/utils/deprecatedColors.d.ts

@@ -1,69 +1,69 @@
-/**
- * Based on https://github.com/jorgebucaran/colorette
- * Read LICENSE file for more information
- * https://github.com/jorgebucaran/colorette/blob/20fc196d07d0f87c61e0256eadd7831c79b24108/index.js
- */
-declare const colorDefs: {
-    reset: (string: string) => string;
-    bold: (string: string) => string;
-    dim: (string: string) => string;
-    italic: (string: string) => string;
-    underline: (string: string) => string;
-    inverse: (string: string) => string;
-    hidden: (string: string) => string;
-    strikethrough: (string: string) => string;
-    black: (string: string) => string;
-    red: (string: string) => string;
-    green: (string: string) => string;
-    yellow: (string: string) => string;
-    blue: (string: string) => string;
-    magenta: (string: string) => string;
-    cyan: (string: string) => string;
-    white: (string: string) => string;
-    gray: (string: string) => string;
-    bgBlack: (string: string) => string;
-    bgRed: (string: string) => string;
-    bgGreen: (string: string) => string;
-    bgYellow: (string: string) => string;
-    bgBlue: (string: string) => string;
-    bgMagenta: (string: string) => string;
-    bgCyan: (string: string) => string;
-    bgWhite: (string: string) => string;
-    blackBright: (string: string) => string;
-    redBright: (string: string) => string;
-    greenBright: (string: string) => string;
-    yellowBright: (string: string) => string;
-    blueBright: (string: string) => string;
-    magentaBright: (string: string) => string;
-    cyanBright: (string: string) => string;
-    whiteBright: (string: string) => string;
-    bgBlackBright: (string: string) => string;
-    bgRedBright: (string: string) => string;
-    bgGreenBright: (string: string) => string;
-    bgYellowBright: (string: string) => string;
-    bgBlueBright: (string: string) => string;
-    bgMagentaBright: (string: string) => string;
-    bgCyanBright: (string: string) => string;
-    bgWhiteBright: (string: string) => string;
-};
-export type ColorName = keyof typeof colorDefs;
-export type ColorFunction = (text: string | number) => string;
-/**
- * An object containing functions for coloring text. Each function corresponds to a terminal color. See {@link ColorName} for available colors.
- */
-export declare const colors: Record<"bold" | "cyan" | "red" | "green" | "magenta" | "yellow" | "gray" | "bgWhite" | "white" | "reset" | "dim" | "italic" | "underline" | "inverse" | "hidden" | "strikethrough" | "black" | "blue" | "bgBlack" | "bgRed" | "bgGreen" | "bgYellow" | "bgBlue" | "bgMagenta" | "bgCyan" | "blackBright" | "redBright" | "greenBright" | "yellowBright" | "blueBright" | "magentaBright" | "cyanBright" | "whiteBright" | "bgBlackBright" | "bgRedBright" | "bgGreenBright" | "bgYellowBright" | "bgBlueBright" | "bgMagentaBright" | "bgCyanBright" | "bgWhiteBright", ColorFunction>;
-/**
- * Gets a color function by name, with an option for a fallback color if the requested color is not found.
- * @param {ColorName} color - The name of the color function to get. See {@link ColorName}.
- * @param {ColorName} [fallback="reset"] - The name of the fallback color function if the requested color is not found. See {@link ColorName}.
- * @returns {ColorFunction} The color function that corresponds to the requested color, or the fallback color function. See {@link ColorFunction}.
- */
-export declare function getColor(color: ColorName, fallback?: ColorName): ColorFunction;
-/**
- * Applies a specified color to a given text string or number.
- * @param {ColorName} color - The color to apply. See {@link ColorName}.
- * @param {string | number} text - The text to color.
- * @returns {string} The colored text.
- */
-export declare function colorize(color: ColorName, text: string | number): string;
-export {};
+/**
+ * Based on https://github.com/jorgebucaran/colorette
+ * Read LICENSE file for more information
+ * https://github.com/jorgebucaran/colorette/blob/20fc196d07d0f87c61e0256eadd7831c79b24108/index.js
+ */
+declare const colorDefs: {
+    reset: (string: string) => string;
+    bold: (string: string) => string;
+    dim: (string: string) => string;
+    italic: (string: string) => string;
+    underline: (string: string) => string;
+    inverse: (string: string) => string;
+    hidden: (string: string) => string;
+    strikethrough: (string: string) => string;
+    black: (string: string) => string;
+    red: (string: string) => string;
+    green: (string: string) => string;
+    yellow: (string: string) => string;
+    blue: (string: string) => string;
+    magenta: (string: string) => string;
+    cyan: (string: string) => string;
+    white: (string: string) => string;
+    gray: (string: string) => string;
+    bgBlack: (string: string) => string;
+    bgRed: (string: string) => string;
+    bgGreen: (string: string) => string;
+    bgYellow: (string: string) => string;
+    bgBlue: (string: string) => string;
+    bgMagenta: (string: string) => string;
+    bgCyan: (string: string) => string;
+    bgWhite: (string: string) => string;
+    blackBright: (string: string) => string;
+    redBright: (string: string) => string;
+    greenBright: (string: string) => string;
+    yellowBright: (string: string) => string;
+    blueBright: (string: string) => string;
+    magentaBright: (string: string) => string;
+    cyanBright: (string: string) => string;
+    whiteBright: (string: string) => string;
+    bgBlackBright: (string: string) => string;
+    bgRedBright: (string: string) => string;
+    bgGreenBright: (string: string) => string;
+    bgYellowBright: (string: string) => string;
+    bgBlueBright: (string: string) => string;
+    bgMagentaBright: (string: string) => string;
+    bgCyanBright: (string: string) => string;
+    bgWhiteBright: (string: string) => string;
+};
+export type ColorName = keyof typeof colorDefs;
+export type ColorFunction = (text: string | number) => string;
+/**
+ * An object containing functions for coloring text. Each function corresponds to a terminal color. See {@link ColorName} for available colors.
+ */
+export declare const colors: Record<ColorName, ColorFunction>;
+/**
+ * Gets a color function by name, with an option for a fallback color if the requested color is not found.
+ * @param {ColorName} color - The name of the color function to get. See {@link ColorName}.
+ * @param {ColorName} [fallback="reset"] - The name of the fallback color function if the requested color is not found. See {@link ColorName}.
+ * @returns {ColorFunction} The color function that corresponds to the requested color, or the fallback color function. See {@link ColorFunction}.
+ */
+export declare function getColor(color: ColorName, fallback?: ColorName): ColorFunction;
+/**
+ * Applies a specified color to a given text string or number.
+ * @param {ColorName} color - The color to apply. See {@link ColorName}.
+ * @param {string | number} text - The text to color.
+ * @returns {string} The colored text.
+ */
+export declare function colorize(color: ColorName, text: string | number): string;
+export {};

package/bin/{relinka-impl/deprecated → deprecated}/utils/error.d.ts

@@ -1,6 +1,6 @@
-/**
- * Parses a stack trace string and normalizes its paths by removing the current working directory and the "file://" protocol.
- * @param {string} stack - The stack trace string.
- * @returns {string[]} An array of stack trace lines with normalized paths.
- */
-export declare function parseStack(stack: string): string[];
+/**
+ * Parses a stack trace string and normalizes its paths by removing the current working directory and the "file://" protocol.
+ * @param {string} stack - The stack trace string.
+ * @returns {string[]} An array of stack trace lines with normalized paths.
+ */
+export declare function parseStack(stack: string): string[];

package/bin/{relinka-impl/deprecated → deprecated}/utils/format.d.ts

@@ -1,14 +1,14 @@
-/**
- * Compiles a format string by replacing placeholders with appropriate position indices.
- * Caches compiled formats for efficiency.
- * @param {string} format - The format string containing the placeholders to replace.
- * @returns {string} The compiled format string with placeholders replaced by positional indices.
- */
-export declare function compileFormat(format: string): any;
-/**
- * Formats a string according to a custom format, using vsprintf for string formatting.
- * @param {string} format - The custom format string.
- * @param {any[]} argv - The arguments to format into the string.
- * @returns {string} The formatted string.
- */
-export declare function formatString(format: string, argv: any): string;
+/**
+ * Compiles a format string by replacing placeholders with appropriate position indices.
+ * Caches compiled formats for efficiency.
+ * @param {string} format - The format string containing the placeholders to replace.
+ * @returns {string} The compiled format string with placeholders replaced by positional indices.
+ */
+export declare function compileFormat(format: string): any;
+/**
+ * Formats a string according to a custom format, using vsprintf for string formatting.
+ * @param {string} format - The custom format string.
+ * @param {any[]} argv - The arguments to format into the string.
+ * @returns {string} The formatted string.
+ */
+export declare function formatString(format: string, argv: any): string;

package/bin/{relinka-impl/deprecated → deprecated}/utils/log.d.ts

@@ -1,13 +1,13 @@
-/**
- * Checks if the given argument is a simple JavaScript object.
- * @param {any} obj - The object to test.
- * @returns {boolean} `true` if the argument is a plain object, otherwise `false`.
- */
-export declare function isPlainObject(obj: any): boolean;
-/**
- * Determines whether the given argument is a protocol object. A log object must be a simple object and
- * must contain either a 'message' or 'args' field, but not a 'stack' field.
- * @param {any} arg - The argument to check.
- * @returns {boolean} `true` if the argument is a log object according to the specified criteria, otherwise `false`.
- */
-export declare function isLogObj(arg: any): boolean;
+/**
+ * Checks if the given argument is a simple JavaScript object.
+ * @param {any} obj - The object to test.
+ * @returns {boolean} `true` if the argument is a plain object, otherwise `false`.
+ */
+export declare function isPlainObject(obj: any): boolean;
+/**
+ * Determines whether the given argument is a protocol object. A log object must be a simple object and
+ * must contain either a 'message' or 'args' field, but not a 'stack' field.
+ * @param {any} arg - The argument to check.
+ * @returns {boolean} `true` if the argument is a log object according to the specified criteria, otherwise `false`.
+ */
+export declare function isLogObj(arg: any): boolean;

package/bin/{relinka-impl/deprecated → deprecated}/utils/stream.d.ts

@@ -1,15 +1,14 @@
-/// <reference types="node" />
-/**
- * Writes data to a specified NodeJS writable stream. This function supports streams that have a custom
- * `__write' method, and will fall back to the default `write' method if `__write' is not present.
- *
- * @param {any} data - The data to write to the stream. This can be a string, a buffer, or any data type
- * supported by the stream's `write' or `__write' method.
- * @param {NodeJS.WriteStream} stream - The writable stream to write the data to. This stream
- * must implement the `write' method, and can optionally implement a custom `__write' method.
- * @returns {boolean} `true` if the data has been completely processed by the write operation,
- * indicating that further writes can be performed immediately. Returns `false` if the data is
- * buffered by the stream, indicating that the `drain` event should be waited for before writing
- * more data.
- */
-export declare function writeStream(data: any, stream: NodeJS.WriteStream): any;
+/**
+ * Writes data to a specified NodeJS writable stream. This function supports streams that have a custom
+ * `__write' method, and will fall back to the default `write' method if `__write' is not present.
+ *
+ * @param {any} data - The data to write to the stream. This can be a string, a buffer, or any data type
+ * supported by the stream's `write' or `__write' method.
+ * @param {NodeJS.WriteStream} stream - The writable stream to write the data to. This stream
+ * must implement the `write' method, and can optionally implement a custom `__write' method.
+ * @returns {boolean} `true` if the data has been completely processed by the write operation,
+ * indicating that further writes can be performed immediately. Returns `false` if the data is
+ * buffered by the stream, indicating that the `drain` event should be waited for before writing
+ * more data.
+ */
+export declare function writeStream(data: any, stream: NodeJS.WriteStream): any;

package/bin/{relinka-impl/deprecated → deprecated}/utils/string.d.ts

@@ -1,50 +1,50 @@
-/**
- * Removes ANSI escape codes from a given string. This is particularly useful for
- * processing text that contains formatting codes, such as colors or styles, so that the
- * the raw text without any visual formatting.
- *
- * @param {string} text - The text string from which to strip the ANSI escape codes.
- * @returns {string} The text without ANSI escape codes.
- */
-export declare function stripAnsi(text: string): string;
-/**
- * Centers a string within a specified total width, padding it with spaces or another specified character.
- * If the string is longer than the total width, it is returned as is.
- *
- * @param {string} str - The string to centre.
- * @param {number} len - The total width in which to centre the string.
- * @param {string} [space=" "] - The character to use for padding. Defaults to a space.
- * @returns {string} The centred string.
- */
-export declare function centerAlign(str: string, len: number, space?: string): string;
-/**
- * Right-justifies a string within a given total width, padding it with whitespace or another specified character.
- * If the string is longer than the total width, it is returned as is.
- *
- * @param {string} str - The string to right-justify.
- * @param {number} len - The total width to align the string.
- * @param {string} [space=" "] - The character to use for padding. Defaults to a space.
- * @returns {string} The right-justified string.
- */
-export declare function rightAlign(str: string, len: number, space?: string): string;
-/**
- * Left-aligns a string within a given total width, padding it with whitespace or another specified character on the right.
- * If the string is longer than the total width, it is returned as is.
- *
- * @param {string} str - The string to align left.
- * @param {number} len - The total width to align the string.
- * @param {string} [space=" "] - The character to use for padding. Defaults to a space.
- * @returns {string} The left-justified string.
- */
-export declare function leftAlign(str: string, len: number, space?: string): string;
-/**
- * Aligns a string (left, right, or centre) within a given total width, padding it with spaces or another specified character.
- * If the string is longer than the total width, it is returned as is. This function acts as a wrapper for individual alignment functions.
- *
- * @param {"left" | "right" | "centre"} alignment - The desired alignment of the string.
- * @param {string} str - The string to align.
- * @param {number} len - The total width in which to align the string.
- * @param {string} [space=" "] - The character to use for padding. Defaults to a space.
- * @returns {string} The aligned string, according to the given alignment.
- */
-export declare function align(alignment: "left" | "right" | "center", str: string, len: number, space?: string): string;
+/**
+ * Removes ANSI escape codes from a given string. This is particularly useful for
+ * processing text that contains formatting codes, such as colors or styles, so that the
+ * the raw text without any visual formatting.
+ *
+ * @param {string} text - The text string from which to strip the ANSI escape codes.
+ * @returns {string} The text without ANSI escape codes.
+ */
+export declare function stripAnsi(text: string): string;
+/**
+ * Centers a string within a specified total width, padding it with spaces or another specified character.
+ * If the string is longer than the total width, it is returned as is.
+ *
+ * @param {string} str - The string to centre.
+ * @param {number} len - The total width in which to centre the string.
+ * @param {string} [space=" "] - The character to use for padding. Defaults to a space.
+ * @returns {string} The centred string.
+ */
+export declare function centerAlign(str: string, len: number, space?: string): string;
+/**
+ * Right-justifies a string within a given total width, padding it with whitespace or another specified character.
+ * If the string is longer than the total width, it is returned as is.
+ *
+ * @param {string} str - The string to right-justify.
+ * @param {number} len - The total width to align the string.
+ * @param {string} [space=" "] - The character to use for padding. Defaults to a space.
+ * @returns {string} The right-justified string.
+ */
+export declare function rightAlign(str: string, len: number, space?: string): string;
+/**
+ * Left-aligns a string within a given total width, padding it with whitespace or another specified character on the right.
+ * If the string is longer than the total width, it is returned as is.
+ *
+ * @param {string} str - The string to align left.
+ * @param {number} len - The total width to align the string.
+ * @param {string} [space=" "] - The character to use for padding. Defaults to a space.
+ * @returns {string} The left-justified string.
+ */
+export declare function leftAlign(str: string, len: number, space?: string): string;
+/**
+ * Aligns a string (left, right, or centre) within a given total width, padding it with spaces or another specified character.
+ * If the string is longer than the total width, it is returned as is. This function acts as a wrapper for individual alignment functions.
+ *
+ * @param {"left" | "right" | "centre"} alignment - The desired alignment of the string.
+ * @param {string} str - The string to align.
+ * @param {number} len - The total width in which to align the string.
+ * @param {string} [space=" "] - The character to use for padding. Defaults to a space.
+ * @returns {string} The aligned string, according to the given alignment.
+ */
+export declare function align(alignment: "left" | "right" | "center", str: string, len: number, space?: string): string;

package/bin/{relinka-impl/deprecated → deprecated}/utils/tree.d.ts

@@ -1,41 +1,41 @@
-import { type ColorName } from "./deprecatedColors.js";
-export type TreeItemObject = {
-    /**
-     * Text of the item
-     */
-    text: string;
-    /**
-     * Children of the item
-     */
-    children?: TreeItem[];
-    /**
-     * Color of the item
-     */
-    color?: ColorName;
-};
-export type TreeItem = string | TreeItemObject;
-export type TreeOptions = {
-    /**
-     * Color of the tree
-     */
-    color?: ColorName;
-    /**
-     * Prefix of the tree
-     *
-     * @default "  "
-     */
-    prefix?: string;
-};
-/**
- * Formats a hierarchical list of items into a string representing a tree structure.
- * Each item in the tree can be a simple string or an object defining the text of the item,
- * optional children, and color. The tree structure can be customized with options
- * Specify the overall color and the prefix used for indentation and tree lines.
- *
- * @param {TreeItem[]} items - An array of items to include in the tree. Each item can be
- * either a string or an object with `text', `children' and `color' properties.
- * @param {TreeOptions} [options] - Optional settings to customize the appearance of the tree, including
- * the color of the tree text and the prefix for branches. See {@link TreeOptions}.
- * @returns {string} The formatted tree as a string, ready for printing to the console or elsewhere.
- */
-export declare function formatTree(items: TreeItem[], options?: TreeOptions): string;
+import { type ColorName } from "./deprecatedColors.js";
+export type TreeItemObject = {
+    /**
+     * Text of the item
+     */
+    text: string;
+    /**
+     * Children of the item
+     */
+    children?: TreeItem[];
+    /**
+     * Color of the item
+     */
+    color?: ColorName;
+};
+export type TreeItem = string | TreeItemObject;
+export type TreeOptions = {
+    /**
+     * Color of the tree
+     */
+    color?: ColorName;
+    /**
+     * Prefix of the tree
+     *
+     * @default "  "
+     */
+    prefix?: string;
+};
+/**
+ * Formats a hierarchical list of items into a string representing a tree structure.
+ * Each item in the tree can be a simple string or an object defining the text of the item,
+ * optional children, and color. The tree structure can be customized with options
+ * Specify the overall color and the prefix used for indentation and tree lines.
+ *
+ * @param {TreeItem[]} items - An array of items to include in the tree. Each item can be
+ * either a string or an object with `text', `children' and `color' properties.
+ * @param {TreeOptions} [options] - Optional settings to customize the appearance of the tree, including
+ * the color of the tree text and the prefix for branches. See {@link TreeOptions}.
+ * @returns {string} The formatted tree as a string, ready for printing to the console or elsewhere.
+ */
+export declare function formatTree(items: TreeItem[], options?: TreeOptions): string;

package/bin/impl.d.ts

@@ -0,0 +1,149 @@
+import type { DefaultColorKeys } from "@reliverse/relico";
+/** Configuration for special directory handling. */
+export type RelinkaSpecialDirsConfig = {
+    distDirNames?: string[];
+    useParentConfigInDist?: boolean;
+};
+/** Configuration for directory-related settings. */
+export type RelinkaDirsConfig = {
+    dailyLogs?: boolean;
+    logDir?: string;
+    maxLogFiles?: number;
+    specialDirs?: RelinkaSpecialDirsConfig;
+};
+/** Configuration for a single log level. */
+export type LogLevelConfig = {
+    /**
+     * Symbol to display for this log level.
+     * @see https://symbl.cc
+     */
+    symbol: string;
+    /**
+     * Fallback symbol to use if Unicode is not supported.
+     */
+    fallbackSymbol: string;
+    /**
+     * Color to use for this log level.
+     */
+    color: DefaultColorKeys;
+    /**
+     * Number of spaces after the symbol/fallback
+     */
+    spacing?: number;
+};
+/** Configuration for all log levels. */
+export type LogLevelsConfig = Partial<Record<LogLevel, LogLevelConfig>>;
+/** Log level types used by the logger. */
+export type LogLevel = "error" | "fatal" | "info" | "success" | "verbose" | "warn" | "log";
+/**
+ * Configuration options for the Relinka logger.
+ * All properties are optional to allow for partial configuration.
+ * Defaults will be applied during initialization.
+ */
+export type RelinkaConfig = {
+    /**
+     * Enables verbose (aka debug) mode for detailed logging.
+     *
+     * `true` here works only for end-users of CLIs/libs when theirs developers
+     * has been awaited for user's config via `@reliverse/relinka`'s `await relinkaConfig;`
+     */
+    verbose?: boolean;
+    /**
+     * Configuration for directory-related settings.
+     * - `dailyLogs`: If true, logs will be stored in a daily subdirectory.
+     * - `logDir`: The base directory for logs.
+     * - `maxLogFiles`: The maximum number of log files to keep before cleanup.
+     * - `specialDirs`: Configuration for special directory handling.
+     *   - `distDirNames`: An array of directory names to check for special handling.
+     *   - `useParentConfigInDist`: If true, use the parent config in dist directories.
+     */
+    dirs?: RelinkaDirsConfig;
+    /**
+     * Disables color output in the console.
+     */
+    disableColors?: boolean;
+    /**
+     * Path to the log file.
+     */
+    logFilePath?: string;
+    /**
+     * If true, logs will be saved to a file.
+     */
+    saveLogsToFile?: boolean;
+    /**
+     * Configuration for timestamp in log messages.
+     */
+    timestamp?: {
+        /**
+         * If true, timestamps will be added to log messages.
+         */
+        enabled: boolean;
+        /**
+         * The format for timestamps. Default is YYYY-MM-DD HH:mm:ss.SSS
+         */
+        format?: string;
+    };
+    /**
+     * Allows to customize the log levels.
+     */
+    levels?: LogLevelsConfig;
+    /**
+     * Controls how often the log cleanup runs (in milliseconds)
+     * Default: 10000 (10 seconds)
+     */
+    cleanupInterval?: number;
+    /**
+     * Maximum size of the log write buffer before flushing to disk (in bytes)
+     * Default: 4096 (4KB)
+     */
+    bufferSize?: number;
+    /**
+     * Maximum time to hold logs in buffer before flushing to disk (in milliseconds)
+     * Default: 5000 (5 seconds)
+     */
+    maxBufferAge?: number;
+};
+/** Represents information about a log file for cleanup purposes. */
+export type LogFileInfo = {
+    path: string;
+    mtime: number;
+};
+/**
+ * Promise that resolves once `reconf` loads and merges the config.
+ */
+export declare const relinkaConfig: Promise<RelinkaConfig>;
+/**
+ * Shuts down the logger, flushing all buffers and clearing timers.
+ * As Relinka user - call this at the end of your program to prevent hanging.
+ */
+export declare function relinkaShutdown(): Promise<void>;
+/**
+ * Flushes all log buffers to disk. Used before process exit or on demand.
+ */
+export declare function flushAllLogBuffers(): Promise<void>;
+/**
+ * If something truly impossible happened, log + throw.
+ */
+export declare function shouldNeverHappen(message: string, ...args: unknown[]): never;
+/**
+ * Truncates a string to a specified length, adding "…" if truncated.
+ */
+export declare function truncateString(msg: string, maxLength?: number): string;
+/**
+ * Exhaustiveness check. If we land here, we missed a union case.
+ */
+export declare function casesHandled(unexpectedCase: never): never;
+/**
+ * Logs a message synchronously using the current config.
+ * If type === "fatal", logs a fatal error and throws (never returns).
+ */
+export declare function relinka(type: LogLevel | "clear", message: string, ...args: unknown[]): undefined | never;
+/**
+ * Logs a message asynchronously, waiting for the config to be fully loaded.
+ * If type === "fatal", logs a fatal error and throws (never returns).
+ */
+export declare function relinkaAsync(type: LogLevel, message: string, ...args: unknown[]): Promise<void>;
+/**
+ * Type helper for user config files.
+ */
+export declare function defineConfig(config: Partial<RelinkaConfig>): Partial<RelinkaConfig>;