@reliverse/relinka/bin/impl.d.ts

@reliverse/relinka is a modern, minimal logging library that actually feels right. It's not just pretty output — it's a system: smart formatting, file-safe logging, runtime config support, and a fatal mode built for developers who care about correctness.

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" | "internal" | "null";
/**
 * 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 resolved once the user's config (if any) is merged. */
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>;