@ix-xs/node-comfort 1.2.0 → 2.0.0

package/types/src/Logger.d.ts

@@ -1,68 +1,385 @@
 /**
- * Enables or disables timestamp in logs
- * @param {boolean} value - True to enable, false to disable
- * @returns {Logger} The same Logger instance (for chaining)
+ * Log levels, from the most verbose to the most severe. `silent` hides everything.
  */
-export function setTimestamp(value: boolean): Logger;
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
 /**
- * Changes the delimiters used for text formatting
- * @param {object} options - Delimiter options
- * @param {string} [options.open] - New opening delimiter
- * @param {string} [options.close] - New closing delimiter
- * @returns {Logger} The same Logger instance (for chaining)
+ * Where logs go: `process.stdout`, a file stream, or anything with a
+ * `write(text)` method.
  */
-export function setDelimiter(options?: {
-    open?: string | undefined;
-    close?: string | undefined;
-}): Logger;
+export type LogStream = {
+    write(text: string): unknown;
+};
 /**
- * Prints a message to the console with ANSI formatting
- * @param {*} content - Content to print (string, object, or other)
- * @returns {Logger} The same Logger instance (for chaining)
+ * Writing logs to a file.
  */
-export function log(content: any): Logger;
+export type LogFileOptions = {
+    /**
+     * The file to append to. Folders are created, colors removed.
+     */
+    path: string;
+    /**
+     * Rotate past this size, like `"10MB"`.
+     */
+    maxSize?: string | number | undefined;
+    /**
+     * How many rotated files to keep. Defaults to `5`.
+     */
+    maxFiles?: number | undefined;
+};
 /**
- * Logs an informational message, prefixed with a cyan `ℹ INFO` label.
- * @param {*} content - Content to print.
- * @returns {Logger} The same Logger instance (for chaining).
+ * Options for `createLogger()` and `configure()`.
  */
-export function info(content: any): Logger;
+export type LoggerOptions = {
+    /**
+     * Hide messages below this level. Defaults to `LOG_LEVEL`, else `"info"`.
+     */
+    level?: LogLevel | undefined;
+    /**
+     * Shown before each message, like `[db]`. Child loggers extend it (`db:pool`).
+     */
+    scope?: string | undefined;
+    /**
+     * `true` shows `[HH:mm:ss]`, `false` hides it, a string is a `time.format` pattern. Defaults to `true`.
+     */
+    timestamp?: string | boolean | undefined;
+    /**
+     * `"json"` writes one object per line, for log collectors. Defaults to `LOG_FORMAT`, else `"pretty"`.
+     */
+    format?: "pretty" | "json" | undefined;
+    /**
+     * Markup delimiters. Defaults to `<%` and `%>`.
+     */
+    delimiter?: {
+        open?: string;
+        close?: string;
+    } | undefined;
+    /**
+     * Force colors on or off. By default, it depends on the terminal.
+     */
+    colors?: boolean | undefined;
+    /**
+     * Where `trace` to `info` go. Defaults to `process.stdout`.
+     */
+    stdout?: LogStream | undefined;
+    /**
+     * Where `warn`, `error` and `fatal` go. Defaults to `process.stderr`.
+     */
+    stderr?: LogStream | undefined;
+    /**
+     * Also write every message to a file.
+     */
+    file?: string | LogFileOptions | undefined;
+    /**
+     * Added to every JSON record, like a service name.
+     */
+    fields?: Record<string, unknown> | undefined;
+};
 /**
- * Logs a success message, prefixed with a green `✔ OK` label.
- * @param {*} content - Content to print.
- * @returns {Logger} The same Logger instance (for chaining).
+ * A logger from `createLogger()`. Every method returns the logger, so calls chain.
  */
-export function success(content: any): Logger;
+export type Logger = {
+    /**
+     * A plain message, no badge. Supports markup.
+     */
+    log: (...args: unknown[]) => Logger;
+    /**
+     * Very detailed diagnostics, hidden unless the level is `trace`.
+     */
+    trace: (...args: unknown[]) => Logger;
+    /**
+     * Diagnostics, hidden unless the level is `debug` or lower.
+     */
+    debug: (...args: unknown[]) => Logger;
+    /**
+     * An `ℹ INFO` message.
+     */
+    info: (...args: unknown[]) => Logger;
+    /**
+     * A `✔ OK` message.
+     */
+    success: (...args: unknown[]) => Logger;
+    /**
+     * A `⚠ WARN` message, on stderr.
+     */
+    warn: (...args: unknown[]) => Logger;
+    /**
+     * An `✖ ERROR` message, on stderr. Errors show their stack and cause.
+     */
+    error: (...args: unknown[]) => Logger;
+    /**
+     * An `✖ FATAL` message, on stderr.
+     */
+    fatal: (...args: unknown[]) => Logger;
+    /**
+     * Prints a label and indents what follows. Groups nest.
+     */
+    group: (label?: string) => Logger;
+    /**
+     * Closes the current group.
+     */
+    groupEnd: () => Logger;
+    /**
+     * Starts a named timer.
+     */
+    timeStart: (label?: string) => Logger;
+    /**
+     * Prints how long since `timeStart(label)`.
+     */
+    timeEnd: (label?: string) => Logger;
+    /**
+     * Prints rows as a table.
+     */
+    table: (rows: Array<Record<string, unknown>> | unknown[][], options?: import("./Cli").TableOptions) => Logger;
+    /**
+     * Prints text in a box.
+     */
+    box: (text: string, options?: import("./Cli").BoxOptions) => Logger;
+    /**
+     * Prints a horizontal line.
+     */
+    divider: (title?: string) => Logger;
+    /**
+     * A logger with the same settings and a nested scope. Its `fields` are added to the parent's.
+     */
+    child: (scope: string, options?: LoggerOptions) => Logger;
+    /**
+     * Changes the minimum level.
+     */
+    setLevel: (level: LogLevel) => Logger;
+    /**
+     * The current minimum level.
+     */
+    getLevel: () => LogLevel;
+    /**
+     * Would this level be printed? Skip expensive debug output when it wouldn't.
+     */
+    isLevelEnabled: (level: LogLevel) => boolean;
+    /**
+     * Changes several settings at once.
+     */
+    configure: (options: LoggerOptions) => Logger;
+};
 /**
- * Logs a warning, prefixed with a yellow `⚠ WARN` label (writes to stderr).
- * @param {*} content - Content to print.
- * @returns {Logger} The same Logger instance (for chaining).
+ * Prints a message without a badge. Strings support markup, objects are
+ * pretty-printed, and several arguments are joined with spaces.
+ *
+ * @example
+ * nc.log("<% green ✔ Saved %> in <% bold 12ms %>");
+ * nc.log("user:", { id: 1, roles: ["admin"] });
+ *
+ * @param {...unknown} args
+ * @returns {typeof import("./Logger")}
  */
-export function warn(content: any): Logger;
+export function log(...args: unknown[]): typeof import("./Logger");
 /**
- * Logs an error, prefixed with a red `✖ ERROR` label.
+ * Very detailed diagnostics, shown only at the `trace` level.
  *
- * Accepts an `Error` and prints its stack when available.
- * @param {*} content - Content or Error to print.
- * @returns {Logger} The same Logger instance (for chaining).
+ * @param {...unknown} args
+ * @returns {typeof import("./Logger")}
  */
-export function error(content: any): Logger;
+export function trace(...args: unknown[]): typeof import("./Logger");
 /**
- * Logs a debug message (only when `DEBUG`/`NODE_DEBUG` env is set), prefixed
- * with a gray `● DEBUG` label.
- * @param {*} content - Content to print.
- * @returns {Logger} The same Logger instance (for chaining).
+ * Diagnostics for developers, shown at the `debug` level (the default when
+ * `DEBUG` is set).
+ *
+ * @example
+ * nc.debug("cache miss", { key });
+ *
+ * @param {...unknown} args
+ * @returns {typeof import("./Logger")}
  */
-export function debug(content: any): Logger;
+export function debug(...args: unknown[]): typeof import("./Logger");
 /**
- * Start a log group (displays a label and adds indentation)
- * @param {string} label - The group name to display
- * @returns {Logger} The same Logger instance (for chaining)
+ * An informational message.
+ *
+ * @example
+ * nc.info("Server listening on http://localhost:3000");
+ *
+ * @param {...unknown} args
+ * @returns {typeof import("./Logger")}
  */
-export function group(label: string): Logger;
+export function info(...args: unknown[]): typeof import("./Logger");
 /**
- * End the current log group
- * @returns {Logger} The same Logger instance (for chaining)
+ * A success message.
+ *
+ * @example
+ * nc.success("Database connected");
+ *
+ * @param {...unknown} args
+ * @returns {typeof import("./Logger")}
+ */
+export function success(...args: unknown[]): typeof import("./Logger");
+/**
+ * A warning, written to stderr.
+ *
+ * @param {...unknown} args
+ * @returns {typeof import("./Logger")}
+ */
+export function warn(...args: unknown[]): typeof import("./Logger");
+/**
+ * An error, written to stderr. Error objects show their stack trace and
+ * their chain of causes.
+ *
+ * @example
+ * nc.error(new Error("Cannot save order", { cause: dbError }));
+ *
+ * @param {...unknown} args
+ * @returns {typeof import("./Logger")}
+ */
+export function error(...args: unknown[]): typeof import("./Logger");
+/**
+ * A fatal error, written to stderr. It doesn't stop the process; call
+ * `process.exit(1)` yourself if you mean to.
+ *
+ * @param {...unknown} args
+ * @returns {typeof import("./Logger")}
+ */
+export function fatal(...args: unknown[]): typeof import("./Logger");
+/**
+ * Prints a label and indents what follows, until `groupEnd()`. Groups nest.
+ *
+ * @example
+ * nc.group("Startup").info("Loading config");
+ * nc.group("Database").success("Connected").groupEnd();
+ * nc.groupEnd();
+ *
+ * @param {string} [label]
+ * @returns {typeof import("./Logger")}
+ */
+export function group(label?: string): typeof import("./Logger");
+/**
+ * Closes the current group.
+ *
+ * @returns {typeof import("./Logger")}
+ */
+export function groupEnd(): typeof import("./Logger");
+/**
+ * Starts a named timer. `timeEnd()` prints the elapsed time.
+ *
+ * @example
+ * nc.timeStart("import");
+ * await importProducts();
+ * nc.timeEnd("import"); // "import: 1.24s"
+ *
+ * @param {string} [label="default"]
+ * @returns {typeof import("./Logger")}
+ */
+export function timeStart(label?: string): typeof import("./Logger");
+/**
+ * Prints the time since `timeStart()` with the same label.
+ *
+ * @param {string} [label="default"]
+ * @returns {typeof import("./Logger")}
+ */
+export function timeEnd(label?: string): typeof import("./Logger");
+/**
+ * Prints rows as a table.
+ *
+ * @example
+ * nc.table([{ name: "Ada", role: "admin" }, { name: "Bob", role: "user" }]);
+ *
+ * @param {Array<Record<string, unknown>> | unknown[][]} rows
+ * @param {import("./Cli").TableOptions} [options]
+ * @returns {typeof import("./Logger")}
+ */
+export function table(rows: Array<Record<string, unknown>> | unknown[][], options?: import("./Cli").TableOptions): typeof import("./Logger");
+/**
+ * Prints text in a box. Nice for startup banners.
+ *
+ * @example
+ * nc.box("Server ready\nhttp://localhost:3000", { title: "my-app", borderColor: "green" });
+ *
+ * @param {string} text
+ * @param {import("./Cli").BoxOptions} [options]
+ * @returns {typeof import("./Logger")}
+ */
+export function box(text: string, options?: import("./Cli").BoxOptions): typeof import("./Logger");
+/**
+ * Prints a horizontal line, with an optional title in it.
+ *
+ * @param {string} [title]
+ * @returns {typeof import("./Logger")}
+ */
+export function divider(title?: string): typeof import("./Logger");
+/**
+ * Sets the minimum level.
+ *
+ * @example
+ * nc.setLevel("warn");   // warnings and errors only
+ * nc.setLevel("silent"); // nothing
+ *
+ * @param {LogLevel} level
+ * @returns {typeof import("./Logger")}
+ * @throws {RangeError} For an unknown level.
+ */
+export function setLevel(level: LogLevel): typeof import("./Logger");
+/**
+ * The current minimum level.
+ *
+ * @returns {LogLevel}
+ */
+export function getLevel(): LogLevel;
+/**
+ * Would this level be printed? Use it to skip building expensive debug
+ * output.
+ *
+ * @example
+ * if (nc.isLevelEnabled("debug")) nc.debug(buildHugeReport());
+ *
+ * @param {LogLevel} level
+ * @returns {boolean}
+ */
+export function isLevelEnabled(level: LogLevel): boolean;
+/**
+ * Changes several settings at once.
+ *
+ * @example
+ * nc.configure({ level: "debug", file: "logs/app.log" });
+ * nc.configure({ format: "json", fields: { service: "api" } });
+ *
+ * @param {LoggerOptions} options
+ * @returns {typeof import("./Logger")}
+ */
+export function configure(options: LoggerOptions): typeof import("./Logger");
+/**
+ * Shows or hides timestamps, or sets their pattern.
+ *
+ * @example
+ * nc.setTimestamp(false);
+ * nc.setTimestamp("YYYY-MM-DD HH:mm:ss.SSS");
+ *
+ * @param {boolean | string} value
+ * @returns {typeof import("./Logger")}
+ */
+export function setTimestamp(value: boolean | string): typeof import("./Logger");
+/**
+ * Changes the markup delimiters, for when `<%` clashes with a template
+ * engine.
+ *
+ * @example
+ * nc.setDelimiter({ open: "{{", close: "}}" });
+ * nc.log("{{red Hello}} world");
+ *
+ * @param {{ open?: string, close?: string }} [options]
+ * @returns {typeof import("./Logger")}
+ */
+export function setDelimiter(options?: {
+    open?: string;
+    close?: string;
+}): typeof import("./Logger");
+/**
+ * Creates a logger with its own settings.
+ *
+ * @example
+ * const log = nc.createLogger({ scope: "api", timestamp: "HH:mm:ss.SSS" });
+ * log.info("GET /users 200"); // [14:30:05.120] [api] ℹ INFO GET /users 200
+ * log.child("db").debug("query took 12ms");
+ *
+ * const prod = nc.createLogger({ format: "json", fields: { service: "billing" } });
+ * prod.error("charge failed", { orderId: 42 }, error);
+ *
+ * @param {LoggerOptions} [options]
+ * @returns {Logger}
  */
-export function groupEnd(): Logger;
+export function createLogger(options?: LoggerOptions): Logger;
 //# sourceMappingURL=Logger.d.ts.map

package/types/src/Logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/Logger.js"],"names":[],"mappings":"AAiPE;;;;GAIG;AACH,oCAHW,OAAO,GACL,MAAM,CAKlB;AAED;;;;;;GAMG;AACH,uCAJG;IAAyB,IAAI;IACJ,KAAK;CAC9B,GAAU,MAAM,CAQlB;AAED;;;;GAIG;AACH,6BAHW,GAAC,GACC,MAAM,CAiClB;AAED;;;;GAIG;AACH,8BAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;GAIG;AACH,iCAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;GAIG;AACH,8BAHW,GAAC,GACC,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,+BAHW,GAAC,GACC,MAAM,CAMlB;AAED;;;;;GAKG;AACH,+BAHW,GAAC,GACC,MAAM,CAOlB;AAED;;;;GAIG;AACH,6BAHW,MAAM,GACJ,MAAM,CAOlB;AAED;;;GAGG;AACH,4BAFa,MAAM,CAKlB"}
+{"version":3,"file":"Logger.d.ts","sourceRoot":"","sources":["../../src/Logger.js"],"names":[],"mappings":"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"}