@egi/smart-log 1.0.0

package/smart-log.d.ts

@@ -0,0 +1,362 @@
+import { DateTime } from "luxon";
+export declare enum SmartSeverityLevel {
+    None = 0,
+    Fatal = 1,
+    Error = 2,
+    Warning = 3,
+    Info = 4,
+    Verbose = 5,
+    Debug = 6,
+    All = 9
+}
+export declare enum SmartLocation {
+    App = "APP",
+    Frontend = "FRONTEND",
+    Backend = "BACKEND",
+    Database = "DATABASE",
+    UpgradeManager = "UPGRADE-MANAGER"
+}
+export declare enum SmartLogFormatElement {
+    Severity = 0,
+    Type = 1,
+    Timestamp = 2,
+    Message = 3,
+    Location = 4
+}
+/**
+ * Represents a single log entry. Passed to `ISmartLogDbWriter.write()`, `outputHook`, and `formatHook`.
+ */
+export interface LogMessage {
+    /** Additional data associated with the log entry (e.g. an Error object or debug metadata). */
+    data: unknown;
+    /** Caller location string, e.g. `"src/app.ts:42 (doSomething)"`. */
+    location: string;
+    /** The main log message text. */
+    message: string;
+    /** Severity level of the entry. */
+    severityLevel: SmartSeverityLevel;
+    /** Timestamp of the entry. */
+    timestamp: string | number | Date | DateTime;
+    /** Location type / category of the entry. */
+    type: SmartLocation;
+    /** User identifier stamped on the entry, taken from `SmartLogOptions.user`. */
+    user?: string | number;
+    /** When `true`, console output is suppressed for this entry. */
+    skipConsole?: boolean;
+    /** When `true`, the db writer is skipped for this entry. */
+    skipDatabase?: boolean;
+}
+/**
+ * Defines the format and structure of log messages for a `SmartLog` instance.
+ */
+export interface SmartLogFormat {
+    /**
+     * A string prepended to every log message. Example: `"[APP]"`.
+     */
+    leading: string;
+    /**
+     * When `true`, the caller's location is included in the log message.
+     */
+    location: boolean;
+    /**
+     * When `true`, severity codes and type characters are lowercased. Defaults to `false`.
+     */
+    lowerCase: boolean;
+    /**
+     * Separator string placed between format elements (except before the message). Example: `" | "`.
+     */
+    separator: string;
+    /**
+     * Ordered list of elements that make up the log line. Elements may be:
+     * - `SmartLogFormatElement` enum values
+     * - Fixed strings
+     * - `() => string` functions evaluated at log time
+     */
+    sequence: (string | SmartLogFormatElement | (() => string))[];
+}
+/**
+ * Per-message options passed to logging methods such as `info()`, `error()`, etc.
+ */
+export interface SmartMessageOptions {
+    /** Additional data to attach to the log entry. */
+    data?: unknown;
+    /**
+     * Overrides the auto-detected caller location for this message.
+     * Example: `"api.ts:42"`.
+     */
+    location?: string;
+    /** When `true`, suppresses console output for this message only. */
+    skipConsole?: boolean;
+    /** When `true`, skips the db writer for this message only. */
+    skipDatabase?: boolean;
+    /** Overrides the current timestamp for this entry. */
+    timestamp?: string | number | Date | DateTime;
+    /**
+     * Location type for this message. Accepts a `SmartLocation` value or a custom string.
+     * Defaults to `SmartLocation.App`.
+     */
+    type?: string;
+}
+/**
+ * Implement this interface to persist log entries to a store (e.g. a database table).
+ * Pass an instance via `SmartLogOptions.dbWriter` or `SmartLog.setDbWriter()`.
+ * Both sync and async implementations are supported.
+ */
+export interface ISmartLogDbWriter {
+    write(entry: LogMessage): Promise<void> | void;
+}
+/**
+ * Configuration options for a `SmartLog` instance.
+ */
+export interface SmartLogOptions extends Partial<SmartLogFormat> {
+    /**
+     * Persists log entries to a store. Both sync and async writers are supported.
+     * Pass `null` or omit to disable db logging.
+     */
+    dbWriter?: ISmartLogDbWriter;
+    /**
+     * When `true`, routes console output to `console.error`, `console.warn`,
+     * `console.info`, or `console.debug` based on severity level.
+     * Defaults to `false` (all output goes through `console.log`).
+     */
+    logChannels?: boolean;
+    /**
+     * Minimum severity level for processing log messages. Messages above this level are
+     * silently dropped. Defaults to `SmartSeverityLevel.Info`.
+     */
+    logLevel?: SmartSeverityLevel;
+    /**
+     * A hook called after formatting, before console output. Use this for side effects
+     * such as writing to a file, sending to a webhook, or emitting events.
+     *
+     * - Receives the formatted text and the raw `LogMessage`.
+     * - Return `false` (sync or async) to suppress console output for this entry.
+     * - Use `formatHook` instead if you only need to transform the text.
+     */
+    outputHook?: (text: string, message: LogMessage) => false | void | Promise<false | void>;
+    /**
+     * A custom function that provides an `Error` for stack trace inspection.
+     * Useful when the automatic caller detection resolves to the wrong frame,
+     * e.g. inside a wrapper class.
+     */
+    stackProvider?: () => Error;
+    /**
+     * User ID or username stamped on every log entry. Defaults to the OS username.
+     */
+    user?: string | number;
+    /**
+     * Transforms the formatted log text before it is written to the console.
+     * Must return the (modified) string. Called after `outputHook`.
+     * Use `outputHook` instead if you need side effects or want to suppress output.
+     */
+    formatHook?: (text: string, message: LogMessage) => string;
+}
+/**
+ * A logging utility with severity-level control, flexible formatting, stack trace
+ * integration, and optional persistence via `ISmartLogDbWriter`.
+ *
+ * A default singleton `smartLog` is exported for convenience. Create additional
+ * instances for separate concerns (e.g. per-module loggers with different levels).
+ *
+ * ```typescript
+ * import { smartLog, SmartLog, SmartSeverityLevel } from "@egi/smart-log";
+ *
+ * smartLog.info("Application started");
+ *
+ * const verbose = new SmartLog({ logLevel: SmartSeverityLevel.Debug });
+ * verbose.debug("detailed trace");
+ * ```
+ */
+export declare class SmartLog {
+    private static severityLevelToCode;
+    private dbWriter;
+    private includeLocation;
+    private isLogging;
+    private logFifo;
+    private logFormat;
+    private logLevel;
+    private outputHook;
+    private readonly projectRoot;
+    private stackProvider;
+    private timezone;
+    private useLogChannels;
+    private userId;
+    private formatHook;
+    constructor();
+    constructor(options: SmartLogOptions);
+    /**
+     * Overrides the stack provider used for automatic caller location detection.
+     * Useful when `SmartLog` is wrapped in another class and the default stack
+     * resolution points to the wrapper instead of the actual call site.
+     *
+     * @param stackProvider - A function that returns a fresh `Error` at the call site.
+     */
+    setStackProvider(stackProvider: () => Error): void;
+    /**
+     * Sets a text transformation hook. Called with the fully formatted log line before
+     * console output; must return the (modified) string.
+     *
+     * Use `setOutputHook()` instead if you need side effects or want to suppress output.
+     *
+     * @param hook - Function receiving `(text, message)` and returning the transformed text.
+     */
+    setFormatHook(hook: (text: string, message: LogMessage) => string): void;
+    /**
+     * Sets a general-purpose output hook. Called after formatting and before console output.
+     * Use this for side effects such as writing to a file, calling a webhook, or emitting events.
+     *
+     * Return `false` (or resolve a Promise to `false`) to suppress console output for the entry.
+     * Any other return value (including `void`) leaves console output enabled.
+     *
+     * @param hook - Function receiving `(text, message)`. May return `false | void`
+     *   or a `Promise` of the same.
+     */
+    setOutputHook(hook: (text: string, message: LogMessage) => false | void | Promise<false | void>): void;
+    /**
+     * Configures the log format. Any property omitted in `format` retains its current value.
+     * The default sequence is: `Severity - Type - Timestamp: Message [Location]`.
+     *
+     * @param format - Partial `SmartLogFormat` to merge into the current format.
+     */
+    setLogFormat(format?: Partial<SmartLogFormat>): void;
+    /**
+     * Returns the current minimum log severity level.
+     */
+    getLogLevel(): SmartSeverityLevel;
+    /**
+     * Sets the minimum log severity level. Messages with a higher level number are dropped.
+     *
+     * @param level - The new minimum level.
+     */
+    setLogLevel(level: SmartSeverityLevel): void;
+    /**
+     * Returns `true` if a db writer is currently set.
+     */
+    hasDbWriter(): boolean;
+    /**
+     * Sets or replaces the db writer. Pass `null` to disable db logging.
+     *
+     * @param dbWriter - An `ISmartLogDbWriter` implementation, or `null` to clear.
+     */
+    setDbWriter(dbWriter: ISmartLogDbWriter | null): void;
+    /**
+     * Sets the timezone used when formatting timestamps in log output.
+     * Accepts any IANA timezone identifier (e.g. `"UTC"`, `"Europe/Berlin"`).
+     *
+     * @param timezone - IANA timezone string.
+     */
+    setTimezone(timezone: string): void;
+    /**
+     * Controls whether the caller's source location is appended to each log line.
+     *
+     * @param includeLocation - `true` to include location, `false` to omit.
+     */
+    setIncludeLocation(includeLocation: boolean): void;
+    /**
+     * Returns `true` if caller location is currently included in log output.
+     */
+    getIncludeLocation(): boolean;
+    /**
+     * Sets the user identifier stamped on every subsequent log entry.
+     *
+     * @param userId - A string or numeric user identifier.
+     */
+    setUserId(userId: string | number): void;
+    /**
+     * Logs a message at `Debug` level.
+     * Accepts a string, an `Error`, or a string with `SmartMessageOptions`.
+     */
+    debug(error: Error): void;
+    debug(message: string): void;
+    debug(message: string, error: Error): void;
+    debug(message: string | Error, options: SmartMessageOptions): void;
+    /**
+     * Logs a message at `Error` level.
+     * Accepts a string, an `Error`, or a string with `SmartMessageOptions`.
+     */
+    error(error: Error): void;
+    error(message: string): void;
+    error(message: string, error: Error): void;
+    error(message: string | Error, options: SmartMessageOptions): void;
+    /**
+     * Logs a message at `Fatal` level.
+     * Accepts a string, an `Error`, or a string with `SmartMessageOptions`.
+     */
+    fatal(error: Error): void;
+    fatal(message: string): void;
+    fatal(message: string, error: Error): void;
+    fatal(message: string | Error, options: SmartMessageOptions): void;
+    /**
+     * Logs a message at `Info` level.
+     * Accepts a string, an `Error`, or a string with `SmartMessageOptions`.
+     */
+    info(error: Error): void;
+    info(message: string): void;
+    info(message: string, error: Error): void;
+    info(message: string | Error, options: SmartMessageOptions): void;
+    /**
+     * Logs a message at `Verbose` level.
+     * Accepts a string, an `Error`, or a string with `SmartMessageOptions`.
+     */
+    verbose(error: Error): void;
+    verbose(message: string): void;
+    verbose(message: string, error: Error): void;
+    verbose(message: string | Error, options: SmartMessageOptions): void;
+    /**
+     * Logs a message at `Warning` level.
+     * Accepts a string, an `Error`, or a string with `SmartMessageOptions`.
+     */
+    warning(error: Error): void;
+    warning(message: string): void;
+    warning(message: string, error: Error): void;
+    warning(message: string | Error, options: SmartMessageOptions): void;
+    /**
+     * Writes a message with no severity level (always output regardless of `logLevel`).
+     * Accepts a string, an `Error`, or a string with `SmartMessageOptions`.
+     */
+    write(error: Error): void;
+    write(message: string): void;
+    write(message: string, error: Error): void;
+    write(message: string | Error, options: SmartMessageOptions): void;
+    /**
+     * Core logging method. Normalises the arguments, resolves the caller location,
+     * and dispatches to `log()`.
+     *
+     * @param severityLevel - Severity of the message, or `null` for unseveritied `write()` calls.
+     * @param messageOrError - The message string or an `Error` whose `.message` is used.
+     * @param optionsOrError - Per-message options, or an `Error` stored as `data`.
+     */
+    writeLog(severityLevel: SmartSeverityLevel, messageOrError: string | Error, optionsOrError: SmartMessageOptions | Error): void;
+    /**
+     * Dispatches a fully-formed `LogMessage`. Filters by `logLevel`, formats the text,
+     * runs `outputHook` and `formatHook`, writes to the console (unless suppressed),
+     * and forwards to the db writer.
+     *
+     * Calls during an in-progress async db write are queued and replayed in order.
+     *
+     * @param messageObj - The complete log entry to process.
+     */
+    log(messageObj: LogMessage): void;
+    /**
+     * Formats a `LogMessage` into a string using the current log format sequence.
+     * Optionally accepts a custom `sequence` to override the instance format for this call.
+     *
+     * @param message - The log entry to format.
+     * @param sequence - Optional sequence override; uses the instance format when omitted.
+     * @returns The formatted log line string.
+     */
+    formatMessage(message: LogMessage, sequence?: (string | SmartLogFormatElement | (() => string))[]): string;
+    /**
+     * Returns the single-letter severity code for a given `SmartSeverityLevel`.
+     * Unknown levels fall back to the `Info` code.
+     *
+     * @param level - The severity level to look up.
+     * @returns A single uppercase letter: `F`, `E`, `W`, `I`, `D`, etc.
+     */
+    severityCodeFromLevel(level: SmartSeverityLevel): string;
+    private writeToConsole;
+    private printToConsole;
+    private stringifyData;
+    private nextStackEntry;
+}
+export declare const smartLog: SmartLog;