@reliverse/relinka 1.2.4 → 1.2.5

package/dist-npm/components/relinka/relinka.js

@@ -1,16 +1,19 @@
 import { defu } from "defu";
 import { LogTypes } from "../../components/levels/levels.js";
 import { isLogObj } from "../../utils/log.js";
-const paused = false;
-const queue = [];
-export class Relinka {
+export class RelinkaInterface {
   options;
   _lastLog;
-  
+  // Instance properties for paused state and queue
   _paused;
   _queue;
   _mockFn;
-    constructor(options = {}) {
+  /**
+   * Creates an instance of Relinka with specified options or defaults.
+   *
+   * @param {Partial<RelinkaOptions>} [options={}] - Configuration options for the Relinka instance.
+   */
+  constructor(options = {}) {
     const types = options.types || LogTypes;
     this.options = defu(
       {
@@ -49,18 +52,34 @@ export class Relinka {
     this._paused = false;
     this._queue = [];
   }
-    get level() {
+  /**
+   * Gets the current log level of the Relinka instance.
+   *
+   * @returns {number} The current log level.
+   */
+  get level() {
     return this.options.level;
   }
-    set level(level) {
+  /**
+   * Sets the minimum log level that will be output by the instance.
+   *
+   * @param {number} level - The new log level to set.
+   */
+  set level(level) {
     this.options.level = _normalizeLogLevel(
       level,
       this.options.types,
       this.options.level
     );
   }
-    create(options) {
-    const instance = new Relinka({
+  /**
+   * Creates a new instance of Relinka, inheriting options from the current instance, with possible overrides.
+   *
+   * @param {Partial<RelinkaOptions>} options - Optional overrides for the new instance. See {@link RelinkaOptions}.
+   * @returns {RelinkaInstance} A new Relinka instance. See {@link RelinkaInstance}.
+   */
+  create(options) {
+    const instance = new RelinkaInterface({
       ...this.options,
       ...options
     });
@@ -69,7 +88,13 @@ export class Relinka {
     }
     return instance;
   }
-    withDefaults(defaults) {
+  /**
+   * Creates a new Relinka instance with the specified default log object properties.
+   *
+   * @param {InputLogObject} defaults - Default properties to include in any log from the new instance. See {@link InputLogObject}.
+   * @returns {RelinkaInstance} A new Relinka instance. See {@link RelinkaInstance}.
+   */
+  withDefaults(defaults) {
     return this.create({
       ...this.options,
       defaults: {
@@ -78,16 +103,36 @@ export class Relinka {
       }
     });
   }
-    withTag(tag) {
+  /**
+   * Creates a new Relinka instance with a specified tag, which will be included in every log.
+   *
+   * @param {string} tag - The tag to include in each log of the new instance.
+   * @returns {RelinkaInstance} A new Relinka instance. See {@link RelinkaInstance}.
+   */
+  withTag(tag) {
     return this.withDefaults({
       tag: this.options.defaults.tag ? this.options.defaults.tag + ":" + tag : tag
     });
   }
-    addReporter(reporter) {
+  /**
+   * Adds a custom reporter to the Relinka instance.
+   * Reporters will be called for each log message, depending on their implementation and log level.
+   *
+   * @param {RelinkaReporter} reporter - The reporter to add. See {@link RelinkaReporter}.
+   * @returns {Relinka} The current Relinka instance.
+   */
+  addReporter(reporter) {
     this.options.reporters.push(reporter);
     return this;
   }
-    removeReporter(reporter) {
+  /**
+   * Removes a custom reporter from the Relinka instance.
+   * If no reporter is specified, all reporters will be removed.
+   *
+   * @param {RelinkaReporter} reporter - The reporter to remove. See {@link RelinkaReporter}.
+   * @returns {Relinka} The current Relinka instance.
+   */
+  removeReporter(reporter) {
     if (reporter) {
       const i = this.options.reporters.indexOf(reporter);
       if (i >= 0) {
@@ -98,7 +143,13 @@ export class Relinka {
     }
     return this;
   }
-    setReporters(reporters) {
+  /**
+   * Replaces all reporters of the Relinka instance with the specified array of reporters.
+   *
+   * @param {RelinkaReporter[]} reporters - The new reporters to set. See {@link RelinkaReporter}.
+   * @returns {Relinka} The current Relinka instance.
+   */
+  setReporters(reporters) {
     this.options.reporters = Array.isArray(reporters) ? reporters : [reporters];
     return this;
   }
@@ -110,7 +161,10 @@ export class Relinka {
     this.restoreConsole();
     this.restoreStd();
   }
-    wrapConsole() {
+  /**
+   * Overrides console methods with Relinka logging methods for consistent logging.
+   */
+  wrapConsole() {
     for (const type in this.options.types) {
       if (!console["__" + type]) {
         console["__" + type] = console[type];
@@ -118,7 +172,10 @@ export class Relinka {
       console[type] = this[type].raw;
     }
   }
-    restoreConsole() {
+  /**
+   * Restores the original console methods, removing Relinka overrides.
+   */
+  restoreConsole() {
     for (const type in this.options.types) {
       if (console["__" + type]) {
         console[type] = console["__" + type];
@@ -126,7 +183,10 @@ export class Relinka {
       }
     }
   }
-    wrapStd() {
+  /**
+   * Overrides standard output and error streams to redirect them through RelinkaInterface.
+   */
+  wrapStd() {
     this._wrapStream(this.options.stdout, "log");
     this._wrapStream(this.options.stderr, "log");
   }
@@ -141,7 +201,10 @@ export class Relinka {
       this[type].raw(String(data).trim());
     };
   }
-    restoreStd() {
+  /**
+   * Restores the original standard output and error streams, removing the Relinka redirection.
+   */
+  restoreStd() {
     this._restoreStream(this.options.stdout);
     this._restoreStream(this.options.stderr);
   }
@@ -154,7 +217,14 @@ export class Relinka {
       delete stream.__write;
     }
   }
-    clear(clearConsole = false) {
+  /**
+   * Clears the internal state of the Relinka instance.
+   * This will reset any throttling, last log data, clear any queued logs,
+   * and optionally clear the actual console.
+   *
+   * @param {boolean} clearConsole - Whether to clear the actual console. Defaults to false.
+   */
+  clear(clearConsole = false) {
     this._lastLog = {};
     this._queue = [];
     this._paused = false;
@@ -162,17 +232,28 @@ export class Relinka {
       console.clear();
     }
   }
-    pauseLogs() {
+  /**
+   * Pauses logging, queues incoming logs until resumed.
+   */
+  pauseLogs() {
     this._paused = true;
   }
-    resumeLogs() {
+  /**
+   * Resumes logging, processing any queued logs.
+   */
+  resumeLogs() {
     this._paused = false;
     const _queue = this._queue.splice(0);
     for (const item of _queue) {
       item[0]._logFn(item[1], item[2]);
     }
   }
-    mockTypes(mockFn) {
+  /**
+   * Replaces logging methods with mocks if a mock function is provided.
+   *
+   * @param {RelinkaOptions["mockFn"]} mockFn - The function to use for mocking logging methods. See {@link RelinkaOptions["mockFn"]}.
+   */
+  mockTypes(mockFn) {
     const _mockFn = mockFn || this.options.mockFn;
     this._mockFn = _mockFn;
     if (typeof _mockFn !== "function") {
@@ -183,12 +264,12 @@ export class Relinka {
       this[type].raw = this[type];
     }
   }
-  
+  // _wrapLogFn uses instances: _paused, _queue, etc
   _wrapLogFn(defaults, isRaw) {
     return (...args) => {
       if (this._paused) {
         this._queue.push([this, defaults, args, isRaw]);
-        return;
+        return false;
       }
       return this._logFn(defaults, args, isRaw);
     };
@@ -198,7 +279,7 @@ export class Relinka {
       return false;
     }
     const logObj = {
-      date:  new Date(),
+      date: /* @__PURE__ */ new Date(),
       args: [],
       ...defaults,
       level: _normalizeLogLevel(defaults.level, this.options.types)
@@ -255,13 +336,15 @@ export class Relinka {
               resolveLog,
               this.options.throttle
             );
-            return;
+            return false;
           }
         }
       } catch {
+        return true;
       }
     }
     resolveLog(true);
+    return true;
   }
   _log(logObj) {
     for (const reporter of this.options.reporters) {
@@ -283,13 +366,13 @@ function _normalizeLogLevel(input, types = {}, defaultLevel = 3) {
   }
   return defaultLevel;
 }
-Relinka.prototype.add = Relinka.prototype.addReporter;
-Relinka.prototype.remove = Relinka.prototype.removeReporter;
-Relinka.prototype.clear = Relinka.prototype.removeReporter;
-Relinka.prototype.withScope = Relinka.prototype.withTag;
-Relinka.prototype.mock = Relinka.prototype.mockTypes;
-Relinka.prototype.pause = Relinka.prototype.pauseLogs;
-Relinka.prototype.resume = Relinka.prototype.resumeLogs;
+RelinkaInterface.prototype.add = RelinkaInterface.prototype.addReporter;
+RelinkaInterface.prototype.remove = RelinkaInterface.prototype.removeReporter;
+RelinkaInterface.prototype.clear = RelinkaInterface.prototype.removeReporter;
+RelinkaInterface.prototype.withScope = RelinkaInterface.prototype.withTag;
+RelinkaInterface.prototype.mock = RelinkaInterface.prototype.mockTypes;
+RelinkaInterface.prototype.pause = RelinkaInterface.prototype.pauseLogs;
+RelinkaInterface.prototype.resume = RelinkaInterface.prototype.resumeLogs;
 export function createRelinka(options = {}) {
-  return new Relinka(options);
+  return new RelinkaInterface(options);
 }

package/dist-npm/components/reporters/basic.d.ts

@@ -1,6 +1,6 @@
 import type { LogObject, RelinkaReporter, FormatOptions, RelinkaOptions } from "../../types/mod.js";
 export declare class BasicReporter implements RelinkaReporter {
-    formatStack(stack: string, opts: FormatOptions): string;
+    formatStack(stack: string): string;
     formatArgs(args: any[], opts: FormatOptions): string;
     formatDate(date: Date, opts: FormatOptions): string;
     filterAndJoin(arr: any[]): string;

package/dist-npm/components/reporters/basic.js

@@ -3,17 +3,17 @@ import { parseStack } from "../../utils/error.js";
 import { writeStream } from "../../utils/stream.js";
 const bracket = (x) => x ? `[${x}]` : "";
 export class BasicReporter {
-  formatStack(stack, opts) {
+  formatStack(stack) {
     return "  " + parseStack(stack).join("\n  ");
   }
   formatArgs(args, opts) {
-    const _args = args.map((arg) => {
+    const formattedArgs = args.map((arg) => {
       if (arg && typeof arg.stack === "string") {
-        return arg.message + "\n" + this.formatStack(arg.stack, opts);
+        return arg.message + "\n" + this.formatStack(arg.stack);
       }
       return arg;
     });
-    return formatWithOptions(opts, ..._args);
+    return formatWithOptions(opts, ...formattedArgs);
   }
   formatDate(date, opts) {
     return opts.date ? date.toLocaleTimeString() : "";
@@ -26,7 +26,7 @@ export class BasicReporter {
     if (logObj.type === "box") {
       return "\n" + [
         bracket(logObj.tag),
-        logObj.title && logObj.title,
+        logObj["title"] && logObj["title"],
         ...message.split("\n")
       ].filter(Boolean).map((l) => " > " + l).join("\n") + "\n";
     }

package/dist-npm/components/reporters/browser.js

@@ -8,15 +8,15 @@ export class BrowserReporter {
     this.defaultColor = "#7f8c8d";
     this.levelColorMap = {
       0: "#c0392b",
-      
+      // Red
       1: "#f39c12",
-      
+      // Yellow
       3: "#00BCD4"
-      
+      // Cyan
     };
     this.typeColorMap = {
       success: "#2ecc71"
-      
+      // Green
     };
   }
   _getLogFn(level) {
@@ -45,7 +45,7 @@ export class BrowserReporter {
       consoleLogFn(
         `${badge}%c ${logObj.args[0]}`,
         style,
-        
+        // Empty string as style resets to default console style
         "",
         ...logObj.args.slice(1)
       );

package/dist-npm/components/reporters/fancy.d.ts

@@ -5,6 +5,6 @@ export declare const TYPE_COLOR_MAP: Partial<Record<LogType, string>>;
 export declare const LEVEL_COLOR_MAP: Partial<Record<LogLevel, string>>;
 export declare class FancyReporter extends BasicReporter {
     formatStack(stack: string): string;
-    formatType(logObj: LogObject, isBadge: boolean, opts: FormatOptions): any;
+    formatType(logObj: LogObject, isBadge: boolean): any;
     formatLogObj(logObj: LogObject, opts: FormatOptions): any;
 }

package/dist-npm/components/reporters/fancy.js

@@ -1,5 +1,5 @@
 import isUnicodeSupported from "is-unicode-supported";
-import _stringWidth from "string-width";
+import stringWidth from "string-width";
 import { BasicReporter } from "../../components/reporters/basic.js";
 import { box } from "../../utils/box.js";
 import { colors } from "../../utils/color.js";
@@ -31,11 +31,11 @@ const TYPE_ICONS = {
   start: s("\u25D0", "o"),
   log: ""
 };
-function stringWidth(str) {
+function getStringWidth(str) {
   if (!Intl.Segmenter) {
     return stripAnsi(str).length;
   }
-  return _stringWidth(str);
+  return stringWidth(str);
 }
 export class FancyReporter extends BasicReporter {
   formatStack(stack) {
@@ -43,7 +43,7 @@ export class FancyReporter extends BasicReporter {
       (line) => "  " + line.replace(/^at +/, (m) => colors.gray(m)).replace(/\((.+)\)/, (_, m) => `(${colors.cyan(m)})`)
     ).join("\n");
   }
-  formatType(logObj, isBadge, opts) {
+  formatType(logObj, isBadge) {
     const typeColor = TYPE_COLOR_MAP[logObj.type] || LEVEL_COLOR_MAP[logObj.level] || "gray";
     if (isBadge) {
       return getBgColor(typeColor)(
@@ -63,20 +63,20 @@ export class FancyReporter extends BasicReporter {
           message + (additional.length > 0 ? "\n" + additional.join("\n") : "")
         ),
         {
-          title: logObj.title ? characterFormat(logObj.title) : void 0,
-          style: logObj.style
+          title: logObj["title"] ? characterFormat(logObj["title"]) : void 0,
+          style: logObj["style"]
         }
       );
     }
     const date = this.formatDate(logObj.date, opts);
     const coloredDate = date && colors.gray(date);
-    const isBadge = logObj.badge ?? logObj.level < 2;
-    const type = this.formatType(logObj, isBadge, opts);
+    const isBadge = logObj["badge"] ?? logObj.level < 2;
+    const type = this.formatType(logObj, isBadge);
     const tag = logObj.tag ? colors.gray(logObj.tag) : "";
     let line;
     const left = this.filterAndJoin([type, characterFormat(message)]);
     const right = this.filterAndJoin(opts.columns ? [tag, coloredDate] : [tag]);
-    const space = (opts.columns || 0) - stringWidth(left) - stringWidth(right) - 2;
+    const space = (opts.columns || 0) - getStringWidth(left) - getStringWidth(right) - 2;
     line = space > 0 && (opts.columns || 0) >= 80 ? left + " ".repeat(space) + right : (right ? `${colors.gray(`[${right}]`)} ` : "") + left;
     line += characterFormat(
       additional.length > 0 ? "\n" + additional.join("\n") : ""

package/dist-npm/main.d.ts

@@ -1,8 +1,3 @@
-import type { RelinkaInstance } from "./components/relinka/relinka.js";
-import type { RelinkaOptions } from "./types/mod.js";
-export * from "./components/modes/shared.js";
-export declare function createRelinka(options?: Partial<RelinkaOptions & {
-    fancy: boolean;
-}>): RelinkaInstance;
-export declare const relinka: RelinkaInstance;
-export default relinka;
+export * from "./components/relinka/mod.js";
+export * from "./components/messages/mod.js";
+export * from "./components/relinka/logger.js";

package/dist-npm/main.js

@@ -1,34 +1,3 @@
-import { isDebug, isTest, isCI } from "std-env";
-import { LogLevels } from "./components/levels/levels.js";
-import { createRelinka as _createRelinka } from "./components/relinka/relinka.js";
-import { BasicReporter } from "./components/reporters/basic.js";
-import { FancyReporter } from "./components/reporters/fancy.js";
-export * from "./components/modes/shared.js";
-export function createRelinka(options = {}) {
-  let level = _getDefaultLogLevel();
-  if (process.env.RELINKA_LEVEL) {
-    level = Number.parseInt(process.env.RELINKA_LEVEL) ?? level;
-  }
-  const relinka2 = _createRelinka({
-    level,
-    defaults: { level },
-    stdout: process.stdout,
-    stderr: process.stderr,
-    reporters: options.reporters || [
-      options.fancy ?? !(isCI || isTest) ? new FancyReporter() : new BasicReporter()
-    ],
-    ...options
-  });
-  return relinka2;
-}
-function _getDefaultLogLevel() {
-  if (isDebug) {
-    return LogLevels.debug;
-  }
-  if (isTest) {
-    return LogLevels.warn;
-  }
-  return LogLevels.info;
-}
-export const relinka = createRelinka();
-export default relinka;
+export * from "./components/relinka/mod.js";
+export * from "./components/messages/mod.js";
+export * from "./components/relinka/logger.js";

package/dist-npm/types/mod.d.ts

@@ -1,42 +1,149 @@
 import type { LogLevel, LogType } from "../components/levels/levels.js";
 export type RelinkaOptions = {
-        reporters: RelinkaReporter[];
-        types: Record<LogType, InputLogObject>;
-        level: LogLevel;
-        defaults: InputLogObject;
-        throttle: number;
-        throttleMin: number;
-        stdout?: NodeJS.WriteStream;
-        stderr?: NodeJS.WriteStream;
-        mockFn?: (type: LogType, defaults: InputLogObject) => (...args: any) => void;
-        formatOptions: FormatOptions;
+    /**
+     * An array of RelinkaReporter instances used to handle and output log messages.
+     */
+    reporters: RelinkaReporter[];
+    /**
+     * A record mapping LogType to InputLogObject, defining the log configuration for each log type.
+     * See {@link LogType} and {@link InputLogObject}.
+     */
+    types: Record<LogType, InputLogObject>;
+    /**
+     * The minimum log level to output. See {@link LogLevel}.
+     */
+    level: LogLevel;
+    /**
+     * Default properties applied to all log messages unless overridden. See {@link InputLogObject}.
+     */
+    defaults: InputLogObject;
+    /**
+     * The maximum number of times a log message can be repeated within a given timeframe.
+     */
+    throttle: number;
+    /**
+     * The minimum time in milliseconds that must elapse before a throttled log message can be logged again.
+     */
+    throttleMin: number;
+    /**
+     * The Node.js writable stream for standard output. See {@link NodeJS.WriteStream}.
+     * @optional
+     */
+    stdout?: NodeJS.WriteStream;
+    /**
+     * The Node.js writeable stream for standard error output. See {@link NodeJS.WriteStream}.
+     * @optional
+     */
+    stderr?: NodeJS.WriteStream;
+    /**
+     * A function that allows you to mock log messages for testing purposes.
+     * @optional
+     */
+    mockFn?: (type: LogType, defaults: InputLogObject) => (...args: any) => void;
+    /**
+     * Configuration options for formatting log messages. See {@link FormatOptions}.
+     */
+    formatOptions: FormatOptions;
 };
+/**
+ * @see https://nodejs.org/api/util.html#util_util_inspect_object_showhidden_depth_colors
+ */
 export type FormatOptions = {
-        columns?: number;
-        date?: boolean;
-        colors?: boolean;
-        compact?: boolean | number;
-        [key: string]: unknown;
+    /**
+     * The maximum number of columns to output, affects formatting.
+     * @optional
+     */
+    columns?: number;
+    /**
+     * Whether to include timestamp information in log messages.
+     * @optional
+     */
+    date?: boolean;
+    /**
+     * Whether to use colors in the output.
+     * @optional
+     */
+    colors?: boolean;
+    /**
+     * Specifies whether or not the output should be compact. Accepts a boolean or numeric level of compactness.
+     * @optional
+     */
+    compact?: boolean | number;
+    /**
+     * Allows additional custom formatting options.
+     */
+    [key: string]: unknown;
 };
 export type InputLogObject = {
-        level?: LogLevel;
-        tag?: string;
-        type?: LogType;
-        message?: string;
-        additional?: string | string[];
-        args?: any[];
-        date?: Date;
+    /**
+     * The logging level of the message. See {@link LogLevel}.
+     * @optional
+     */
+    level?: LogLevel;
+    /**
+     * A string tag to categorize or identify the log message.
+     * @optional
+     */
+    tag?: string;
+    /**
+     * The type of log message, which affects how it's processed and displayed. See {@link LogType}.
+     * @optional
+     */
+    type?: LogType;
+    /**
+     * The main log message text.
+     * @optional
+     */
+    message?: string;
+    /**
+     * Additional text or texts to be logged with the message.
+     * @optional
+     */
+    additional?: string | string[];
+    /**
+     * Additional arguments to be logged with the message.
+     * @optional
+     */
+    args?: any[];
+    /**
+     * The date and time when the log message was created.
+     * @optional
+     */
+    date?: Date;
 };
 export type LogObject = {
-        level: LogLevel;
-        type: LogType;
-        tag: string;
-        args: any[];
-        date: Date;
-        [key: string]: unknown;
+    /**
+     * The logging level of the message, overridden if required. See {@link LogLevel}.
+     */
+    level: LogLevel;
+    /**
+     * The type of log message, overridden if required. See {@link LogType}.
+     */
+    type: LogType;
+    /**
+     * A string tag to categorize or identify the log message, overridden if necessary.
+     */
+    tag: string;
+    /**
+     * Additional arguments to be logged with the message, overridden if necessary.
+     */
+    args: any[];
+    /**
+     * The date and time the log message was created, overridden if necessary.
+     */
+    date: Date;
+    /**
+     * Allows additional custom properties to be set on the log object.
+     */
+    [key: string]: unknown;
 } & InputLogObject;
 export type RelinkaReporter = {
-        log: (logObj: LogObject, ctx: {
+    /**
+     * Defines how a log message is processed and displayed by this reporter.
+     * @param logObj The LogObject containing the log information to process. See {@link LogObject}.
+     * @param ctx An object containing context information such as options. See {@link RelinkaOptions}.
+     */
+    log: (logObj: LogObject, ctx: {
         options: RelinkaOptions;
     }) => void;
 };