@reliverse/relinka 1.3.8 → 1.4.1

package/bin/impl.d.ts

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