@fend/firo 0.0.1

package/dist/index.cjs

@@ -0,0 +1,352 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FIRO_COLORS: () => FIRO_COLORS,
+  createDevTransport: () => createDevTransport,
+  createJsonTransport: () => createJsonTransport,
+  createLogger: () => createLogger
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/utils.ts
+var LOG_LEVELS = {
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50
+};
+var FIRO_COLORS = {
+  // Basic ANSI (safe for any terminal)
+  cyan: "36",
+  green: "32",
+  yellow: "33",
+  magenta: "35",
+  blue: "34",
+  brightCyan: "96",
+  brightGreen: "92",
+  brightYellow: "93",
+  brightMagenta: "95",
+  brightBlue: "94",
+  // Extended 256-color palette
+  orange: "38;5;214",
+  pink: "38;5;213",
+  lilac: "38;5;141",
+  skyBlue: "38;5;117",
+  mint: "38;5;156",
+  salmon: "38;5;210",
+  lemon: "38;5;228",
+  lavender: "38;5;183",
+  sage: "38;5;114",
+  coral: "38;5;209",
+  teal: "38;5;116",
+  rose: "38;5;219",
+  pistachio: "38;5;150",
+  mauve: "38;5;175",
+  aqua: "38;5;81",
+  gold: "38;5;222",
+  thistle: "38;5;182",
+  seafoam: "38;5;115",
+  tangerine: "38;5;208",
+  periwinkle: "38;5;147"
+};
+var COLORS_LIST = Object.values(FIRO_COLORS);
+var SAFE_COLORS_COUNT = 10;
+var getColorIndex = (str, useAllColors = false) => {
+  let hash = 0;
+  str.split("").forEach((char) => {
+    hash = char.charCodeAt(0) + ((hash << 5) - hash);
+  });
+  const range = useAllColors ? COLORS_LIST.length : SAFE_COLORS_COUNT;
+  return Math.abs(hash % range);
+};
+var colorize = (text, colorIndex, color) => {
+  const code = color ?? (COLORS_LIST[colorIndex] || COLORS_LIST[colorIndex % SAFE_COLORS_COUNT]);
+  return `\x1B[${code}m${text}\x1B[0m`;
+};
+var colorizeLevel = (level, text) => {
+  if (level === "info") return text;
+  switch (level) {
+    case "error":
+      return `\x1B[31m${text}\x1B[0m`;
+    // Red
+    case "warn":
+      return `\x1B[33m${text}\x1B[0m`;
+    // Yellow
+    case "debug":
+      return `\x1B[2m${text}\x1B[0m`;
+    // Dim
+    default:
+      return text;
+  }
+};
+
+// src/transports.ts
+var import_node_util = require("util");
+var import_node_process = __toESM(require("process"), 1);
+var import_node_fs = __toESM(require("fs"), 1);
+var createDevTransport = (config = {}) => {
+  const locale = config.locale ?? void 0;
+  const timeOpts = {
+    hour12: false,
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    fractionalSecondDigits: 3,
+    ...config.timeOptions || {}
+  };
+  const transport = (level, context, msg, data, opts) => {
+    const now = /* @__PURE__ */ new Date();
+    const timestamp = now.toLocaleTimeString(locale, timeOpts);
+    const contextStr = context.map((ctx) => {
+      const key = ctx.options?.omitKey ? "" : `${ctx.key}:`;
+      const content = `${key}${ctx.value}`;
+      return colorize(`[${content}]`, ctx.options.colorIndex, ctx.options.color);
+    }).join(" ");
+    if (level === "error" && data === void 0) {
+      const realError = wrapToError(msg);
+      data = realError;
+      msg = realError.message;
+    }
+    let dataStr = "";
+    if (data !== void 0) {
+      const inspectOptions = opts?.pretty ? { compact: false, colors: true, depth: null } : { compact: true, breakLength: Infinity, colors: true, depth: null };
+      dataStr = (0, import_node_util.inspect)(data, inspectOptions);
+    }
+    const msgStr = typeof msg === "object" && msg !== null ? (0, import_node_util.inspect)(msg, { colors: true, compact: true, breakLength: Infinity }) : String(msg);
+    const parts = [
+      `[${timestamp}]`,
+      // Normal (not dimmed)
+      contextStr,
+      level === "error" ? colorizeLevel("error", `[ERROR] ${msgStr}`) : level === "warn" ? colorizeLevel("warn", `[WARN] ${msgStr}`) : level === "debug" ? colorizeLevel("debug", msgStr) : msgStr,
+      level === "debug" && dataStr ? `\x1B[2m${dataStr.replace(/\x1b\[0m/g, "\x1B[0m\x1B[2m")}\x1B[0m` : dataStr
+    ];
+    let finalLine = parts.filter(Boolean).join(" ") + "\n";
+    if (level === "error") import_node_process.default.stderr.write(finalLine);
+    else import_node_process.default.stdout.write(finalLine);
+  };
+  return transport;
+};
+var safeStringify = (obj) => {
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return (0, import_node_util.inspect)(obj);
+  }
+};
+var wrapToError = (obj) => {
+  if (obj instanceof Error) return obj;
+  return new Error(
+    typeof obj === "object" && obj !== null ? safeStringify(obj) : String(obj)
+  );
+};
+var serializeError = (_err) => {
+  const err = wrapToError(_err);
+  return {
+    message: err.message,
+    stack: err.stack,
+    name: err.name,
+    ...err
+  };
+};
+var buildRecord = (level, context, msg, data) => {
+  const contextObj = context.reduce((acc, item) => {
+    acc[item.key] = item.value;
+    return acc;
+  }, {});
+  const logRecord = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    ...contextObj
+  };
+  if (level === "error") {
+    const message = typeof msg === "string" ? msg : msg instanceof Error ? msg.message : typeof msg === "object" && msg !== null ? safeStringify(msg) : String(msg);
+    logRecord.message = message;
+    if (data instanceof Error) {
+      logRecord.error = serializeError(data);
+    } else if (msg instanceof Error) {
+      logRecord.error = serializeError(msg);
+      if (data !== void 0) logRecord.data = data;
+    } else {
+      logRecord.error = serializeError(msg);
+      if (data !== void 0) logRecord.data = data;
+    }
+  } else {
+    logRecord.message = typeof msg === "object" && msg !== null ? safeStringify(msg) : String(msg);
+    if (data !== void 0) {
+      logRecord.data = data instanceof Error ? serializeError(data) : data;
+    }
+  }
+  return logRecord;
+};
+var createJsonTransport = (config = {}) => {
+  const queue = [];
+  const maxQueueSize = config.maxQueueSize ?? 1e3;
+  let isDraining = false;
+  const flush = () => {
+    if (queue.length === 0 || isDraining) return;
+    while (queue.length > 0) {
+      const line = queue.shift();
+      const ok = import_node_process.default.stdout.write(line);
+      if (!ok) {
+        isDraining = true;
+        import_node_process.default.stdout.once("drain", () => {
+          isDraining = false;
+          flush();
+        });
+        return;
+      }
+    }
+  };
+  const flushSync = () => {
+    while (queue.length > 0) {
+      const line = queue.shift();
+      if (line) {
+        try {
+          import_node_fs.default.writeSync(1, line);
+        } catch {
+        }
+      }
+    }
+  };
+  if (config.async) {
+    import_node_process.default.on("beforeExit", flushSync);
+    import_node_process.default.on("exit", flushSync);
+  }
+  return (level, context, msg, data) => {
+    const record = buildRecord(level, context, msg, data);
+    let line;
+    try {
+      line = JSON.stringify(record) + "\n";
+    } catch {
+      if (record.data) record.data = (0, import_node_util.inspect)(record.data);
+      try {
+        line = JSON.stringify(record) + "\n";
+      } catch {
+        line = JSON.stringify({
+          timestamp: record.timestamp,
+          level,
+          message: record.message,
+          error: "Failed to serialize log record"
+        }) + "\n";
+      }
+    }
+    if (!config.async) {
+      import_node_process.default.stdout.write(line);
+      return;
+    }
+    queue.push(line);
+    if (queue.length > maxQueueSize) {
+      queue.shift();
+    }
+    flush();
+  };
+};
+
+// src/index.ts
+var fillContextItem = (item, useAllColors = false) => {
+  return {
+    ...item,
+    options: {
+      colorIndex: item.options && typeof item.options.colorIndex === "number" ? item.options.colorIndex : getColorIndex(item.key, useAllColors),
+      color: item.options?.color,
+      omitKey: item.options?.omitKey ?? false
+    }
+  };
+};
+var createLoggerInternal = (config, parentContext) => {
+  const useAllColors = config.useAllColors ?? false;
+  const fill = (item) => fillContextItem(item, useAllColors);
+  const appendContextWithInvokeContext = (context2, invokeContext) => {
+    if (!invokeContext || invokeContext.length === 0) return context2;
+    return [...context2, ...invokeContext.map(fill)];
+  };
+  const context = [...parentContext.map(fill)];
+  const transport = config.transport ?? (config.mode === "prod" ? createJsonTransport({ async: config.async }) : createDevTransport(config.devTransportConfig));
+  const minLevelName = config.mode === "prod" ? config.minLevelInProd ?? config.minLevel : config.minLevelInDev ?? config.minLevel;
+  const minLevel = LOG_LEVELS[minLevelName ?? "debug"];
+  const getContext = () => context;
+  const addContext = (key, value, options) => {
+    let item = typeof key === "string" ? { key, value, options } : key;
+    context.push(fill(item));
+  };
+  const removeKeyFromContext = (key) => {
+    const index = context.findIndex((ctx) => ctx.key === key);
+    if (index !== -1) context.splice(index, 1);
+  };
+  const child = (ctx) => {
+    const newItems = Object.entries(ctx).map(([key, value]) => ({
+      key,
+      value,
+      options: { colorIndex: getColorIndex(key, useAllColors) }
+    }));
+    return createLoggerInternal({ transport, minLevel: minLevelName, useAllColors }, [...context, ...newItems]);
+  };
+  const debug = (msg, data, opts) => {
+    if (minLevel > LOG_LEVELS.debug) return;
+    transport("debug", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+  };
+  const info = (msg, data, opts) => {
+    if (minLevel > LOG_LEVELS.info) return;
+    transport("info", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+  };
+  const warn = (msg, data, opts) => {
+    if (minLevel > LOG_LEVELS.warn) return;
+    transport("warn", appendContextWithInvokeContext(context, opts?.ctx), msg, data, opts);
+  };
+  const error = (msgOrError, err, opts) => {
+    if (minLevel > LOG_LEVELS.error) return;
+    transport("error", appendContextWithInvokeContext(context, opts?.ctx), msgOrError, err, opts);
+  };
+  const logInstance = ((msg, data, opts) => {
+    info(msg, data, opts);
+  });
+  return Object.assign(logInstance, {
+    debug,
+    info,
+    warn,
+    error,
+    child,
+    addContext,
+    getContext,
+    removeFromContext: removeKeyFromContext
+  });
+};
+var createLogger = (config = {}) => {
+  return createLoggerInternal(config, []);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FIRO_COLORS,
+  createDevTransport,
+  createJsonTransport,
+  createLogger
+});

package/dist/index.d.cts

@@ -0,0 +1,166 @@
+/** Available log severity levels. */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Primitive types allowed as context values. */
+type ContextValue = string | number | boolean | null | undefined;
+/** Options to customize how a context item is rendered. */
+type ContextOptions = {
+    /** Color index: 0-9 for safe terminal colors (used by auto-hash), 10+ for extended 256-color palette. */
+    colorIndex?: number;
+    /** Raw ANSI color code string (e.g. '36', '38;5;214', '38;2;255;100;0'). Takes priority over colorIndex. */
+    color?: string;
+    /** If true, the key name is hidden, and only the value is printed. */
+    omitKey?: boolean;
+};
+/** A single key-value context entry. */
+type ContextItem = {
+    key: string;
+    value: ContextValue;
+    options?: ContextOptions;
+};
+/** A context entry where options have been fully resolved with defaults. */
+type ContextItemWithOptions = ContextItem & {
+    options: Required<Pick<ContextOptions, 'colorIndex' | 'omitKey'>> & Pick<ContextOptions, 'color'>;
+};
+/** Options that can be passed to a single log call. */
+type LogOptions = {
+    /** If true, stringifies objects with indentation and line breaks. */
+    pretty?: boolean;
+    /** Additional inline context items applied only to this log call. */
+    ctx?: ContextItem[];
+};
+/** The signature of a function responsible for formatting and emitting log records. */
+type TransportFn = (level: LogLevel, context: ContextItemWithOptions[], message: string | Error | unknown, data?: Error | unknown, options?: LogOptions) => void;
+/** Named color palette for context badges. Use with `color` option: `{ color: FIRO_COLORS.skyBlue }` */
+declare const FIRO_COLORS: {
+    readonly cyan: "36";
+    readonly green: "32";
+    readonly yellow: "33";
+    readonly magenta: "35";
+    readonly blue: "34";
+    readonly brightCyan: "96";
+    readonly brightGreen: "92";
+    readonly brightYellow: "93";
+    readonly brightMagenta: "95";
+    readonly brightBlue: "94";
+    readonly orange: "38;5;214";
+    readonly pink: "38;5;213";
+    readonly lilac: "38;5;141";
+    readonly skyBlue: "38;5;117";
+    readonly mint: "38;5;156";
+    readonly salmon: "38;5;210";
+    readonly lemon: "38;5;228";
+    readonly lavender: "38;5;183";
+    readonly sage: "38;5;114";
+    readonly coral: "38;5;209";
+    readonly teal: "38;5;116";
+    readonly rose: "38;5;219";
+    readonly pistachio: "38;5;150";
+    readonly mauve: "38;5;175";
+    readonly aqua: "38;5;81";
+    readonly gold: "38;5;222";
+    readonly thistle: "38;5;182";
+    readonly seafoam: "38;5;115";
+    readonly tangerine: "38;5;208";
+    readonly periwinkle: "38;5;147";
+};
+
+/**
+ * Configuration options for the development transport.
+ */
+type DevTransportConfig = {
+    /** The locale used for formatting the timestamp. Defaults to the system locale. */
+    locale?: string;
+    /** Standard Intl.DateTimeFormatOptions to customize the timestamp output. */
+    timeOptions?: Intl.DateTimeFormatOptions;
+};
+/**
+ * Creates a built-in transport optimized for local development.
+ * Emits colored, human-readable strings to stdout/stderr.
+ *
+ * @param config Optional configuration for the transport, like timestamp formats.
+ * @returns A `TransportFn` that writes to the console.
+ */
+declare const createDevTransport: (config?: DevTransportConfig) => TransportFn;
+/**
+ * Configuration for the JSON transport.
+ */
+type JsonTransportConfig = {
+    /**
+     * Enable asynchronous/buffered output.
+     * When true, logs are queued and written when the stream is ready (handling backpressure).
+     */
+    async?: boolean;
+    /** Maximum number of log lines to buffer when async is enabled. Defaults to 1000. */
+    maxQueueSize?: number;
+};
+/**
+ * Creates a built-in transport optimized for production.
+ * Emits strictly structured NDJSON (Newline Delimited JSON) to stdout.
+ *
+ * @param config Optional configuration for async and buffering behavior.
+ * @returns A `TransportFn` that writes JSON to standard output.
+ */
+declare const createJsonTransport: (config?: JsonTransportConfig) => TransportFn;
+
+/**
+ * Configuration options for creating a logger instance.
+ */
+type LoggerConfig = {
+    /** The minimum log level for both modes. Overridden by mode-specific thresholds. */
+    minLevel?: LogLevel;
+    /** Minimum log level to emit in 'dev' mode. */
+    minLevelInDev?: LogLevel;
+    /** Minimum log level to emit in 'prod' mode. */
+    minLevelInProd?: LogLevel;
+    /** Specifies the built-in transport to use. Defaults to 'dev'. */
+    mode?: 'dev' | 'prod';
+    /** Provide a custom transport function to override the built-in behaviors. */
+    transport?: TransportFn;
+    /** Options for fine-tuning the built-in development transport (e.g. timestamp format). */
+    devTransportConfig?: DevTransportConfig;
+    /** Enable asynchronous/buffered output for 'prod' mode to avoid event loop blocking. */
+    async?: boolean;
+    /** Use the full extended color palette (30 colors including 256-color) for auto-assigned context badges. Defaults to false (safe 10-color palette). */
+    useAllColors?: boolean;
+};
+/**
+ * The logger instance returned by `createLogger`.
+ * It is a callable object: calling `log(msg)` is shorthand for `log.info(msg)`.
+ */
+interface ILogger {
+    /** Shorthand for log.info() */
+    (msg: string, data?: unknown, opts?: LogOptions): void;
+    /** Log a debug message (dimmed in dev mode). */
+    debug: (msg: string, data?: unknown, opts?: LogOptions) => void;
+    /** Log an informational message. */
+    info: (msg: string, data?: unknown, opts?: LogOptions) => void;
+    /** Log a warning message. */
+    warn: (msg: string, data?: unknown, opts?: LogOptions) => void;
+    /** Log an error object directly. */
+    error(err: Error | unknown): void;
+    /** Log a message alongside an error or custom data object. */
+    error(msg: string, err?: Error | unknown, opts?: LogOptions): void;
+    /**
+     * Create a scoped child logger that inherits the current logger's context.
+     * @param ctx An object containing key-value pairs to add to the child logger's context.
+     */
+    child: (ctx: Record<string, ContextValue>) => ILogger;
+    /** Add a context entry by key and value. */
+    addContext(key: string, value: ContextValue, opts?: ContextOptions): void;
+    /** Add a context entry using the object form. */
+    addContext(item: ContextItem): void;
+    /** Remove a context entry by its key. */
+    removeFromContext(key: string): void;
+    /** Return the current context array attached to this logger instance. */
+    getContext(): ContextItem[];
+}
+
+/**
+ * Creates a new logger instance with the specified configuration.
+ *
+ * @param config Optional configuration for log levels, mode, and transports.
+ * @returns A fully configured `ILogger` instance.
+ */
+declare const createLogger: (config?: LoggerConfig) => ILogger;
+
+export { type ContextItem, type ContextItemWithOptions, type ContextOptions, type ContextValue, type DevTransportConfig, FIRO_COLORS, type ILogger, type JsonTransportConfig, type LogLevel, type LogOptions, type LoggerConfig, type TransportFn, createDevTransport, createJsonTransport, createLogger };

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+/** Available log severity levels. */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Primitive types allowed as context values. */
+type ContextValue = string | number | boolean | null | undefined;
+/** Options to customize how a context item is rendered. */
+type ContextOptions = {
+    /** Color index: 0-9 for safe terminal colors (used by auto-hash), 10+ for extended 256-color palette. */
+    colorIndex?: number;
+    /** Raw ANSI color code string (e.g. '36', '38;5;214', '38;2;255;100;0'). Takes priority over colorIndex. */
+    color?: string;
+    /** If true, the key name is hidden, and only the value is printed. */
+    omitKey?: boolean;
+};
+/** A single key-value context entry. */
+type ContextItem = {
+    key: string;
+    value: ContextValue;
+    options?: ContextOptions;
+};
+/** A context entry where options have been fully resolved with defaults. */
+type ContextItemWithOptions = ContextItem & {
+    options: Required<Pick<ContextOptions, 'colorIndex' | 'omitKey'>> & Pick<ContextOptions, 'color'>;
+};
+/** Options that can be passed to a single log call. */
+type LogOptions = {
+    /** If true, stringifies objects with indentation and line breaks. */
+    pretty?: boolean;
+    /** Additional inline context items applied only to this log call. */
+    ctx?: ContextItem[];
+};
+/** The signature of a function responsible for formatting and emitting log records. */
+type TransportFn = (level: LogLevel, context: ContextItemWithOptions[], message: string | Error | unknown, data?: Error | unknown, options?: LogOptions) => void;
+/** Named color palette for context badges. Use with `color` option: `{ color: FIRO_COLORS.skyBlue }` */
+declare const FIRO_COLORS: {
+    readonly cyan: "36";
+    readonly green: "32";
+    readonly yellow: "33";
+    readonly magenta: "35";
+    readonly blue: "34";
+    readonly brightCyan: "96";
+    readonly brightGreen: "92";
+    readonly brightYellow: "93";
+    readonly brightMagenta: "95";
+    readonly brightBlue: "94";
+    readonly orange: "38;5;214";
+    readonly pink: "38;5;213";
+    readonly lilac: "38;5;141";
+    readonly skyBlue: "38;5;117";
+    readonly mint: "38;5;156";
+    readonly salmon: "38;5;210";
+    readonly lemon: "38;5;228";
+    readonly lavender: "38;5;183";
+    readonly sage: "38;5;114";
+    readonly coral: "38;5;209";
+    readonly teal: "38;5;116";
+    readonly rose: "38;5;219";
+    readonly pistachio: "38;5;150";
+    readonly mauve: "38;5;175";
+    readonly aqua: "38;5;81";
+    readonly gold: "38;5;222";
+    readonly thistle: "38;5;182";
+    readonly seafoam: "38;5;115";
+    readonly tangerine: "38;5;208";
+    readonly periwinkle: "38;5;147";
+};
+
+/**
+ * Configuration options for the development transport.
+ */
+type DevTransportConfig = {
+    /** The locale used for formatting the timestamp. Defaults to the system locale. */
+    locale?: string;
+    /** Standard Intl.DateTimeFormatOptions to customize the timestamp output. */
+    timeOptions?: Intl.DateTimeFormatOptions;
+};
+/**
+ * Creates a built-in transport optimized for local development.
+ * Emits colored, human-readable strings to stdout/stderr.
+ *
+ * @param config Optional configuration for the transport, like timestamp formats.
+ * @returns A `TransportFn` that writes to the console.
+ */
+declare const createDevTransport: (config?: DevTransportConfig) => TransportFn;
+/**
+ * Configuration for the JSON transport.
+ */
+type JsonTransportConfig = {
+    /**
+     * Enable asynchronous/buffered output.
+     * When true, logs are queued and written when the stream is ready (handling backpressure).
+     */
+    async?: boolean;
+    /** Maximum number of log lines to buffer when async is enabled. Defaults to 1000. */
+    maxQueueSize?: number;
+};
+/**
+ * Creates a built-in transport optimized for production.
+ * Emits strictly structured NDJSON (Newline Delimited JSON) to stdout.
+ *
+ * @param config Optional configuration for async and buffering behavior.
+ * @returns A `TransportFn` that writes JSON to standard output.
+ */
+declare const createJsonTransport: (config?: JsonTransportConfig) => TransportFn;
+
+/**
+ * Configuration options for creating a logger instance.
+ */
+type LoggerConfig = {
+    /** The minimum log level for both modes. Overridden by mode-specific thresholds. */
+    minLevel?: LogLevel;
+    /** Minimum log level to emit in 'dev' mode. */
+    minLevelInDev?: LogLevel;
+    /** Minimum log level to emit in 'prod' mode. */
+    minLevelInProd?: LogLevel;
+    /** Specifies the built-in transport to use. Defaults to 'dev'. */
+    mode?: 'dev' | 'prod';
+    /** Provide a custom transport function to override the built-in behaviors. */
+    transport?: TransportFn;
+    /** Options for fine-tuning the built-in development transport (e.g. timestamp format). */
+    devTransportConfig?: DevTransportConfig;
+    /** Enable asynchronous/buffered output for 'prod' mode to avoid event loop blocking. */
+    async?: boolean;
+    /** Use the full extended color palette (30 colors including 256-color) for auto-assigned context badges. Defaults to false (safe 10-color palette). */
+    useAllColors?: boolean;
+};
+/**
+ * The logger instance returned by `createLogger`.
+ * It is a callable object: calling `log(msg)` is shorthand for `log.info(msg)`.
+ */
+interface ILogger {
+    /** Shorthand for log.info() */
+    (msg: string, data?: unknown, opts?: LogOptions): void;
+    /** Log a debug message (dimmed in dev mode). */
+    debug: (msg: string, data?: unknown, opts?: LogOptions) => void;
+    /** Log an informational message. */
+    info: (msg: string, data?: unknown, opts?: LogOptions) => void;
+    /** Log a warning message. */
+    warn: (msg: string, data?: unknown, opts?: LogOptions) => void;
+    /** Log an error object directly. */
+    error(err: Error | unknown): void;
+    /** Log a message alongside an error or custom data object. */
+    error(msg: string, err?: Error | unknown, opts?: LogOptions): void;
+    /**
+     * Create a scoped child logger that inherits the current logger's context.
+     * @param ctx An object containing key-value pairs to add to the child logger's context.
+     */
+    child: (ctx: Record<string, ContextValue>) => ILogger;
+    /** Add a context entry by key and value. */
+    addContext(key: string, value: ContextValue, opts?: ContextOptions): void;
+    /** Add a context entry using the object form. */
+    addContext(item: ContextItem): void;
+    /** Remove a context entry by its key. */
+    removeFromContext(key: string): void;
+    /** Return the current context array attached to this logger instance. */
+    getContext(): ContextItem[];
+}
+
+/**
+ * Creates a new logger instance with the specified configuration.
+ *
+ * @param config Optional configuration for log levels, mode, and transports.
+ * @returns A fully configured `ILogger` instance.
+ */
+declare const createLogger: (config?: LoggerConfig) => ILogger;
+
+export { type ContextItem, type ContextItemWithOptions, type ContextOptions, type ContextValue, type DevTransportConfig, FIRO_COLORS, type ILogger, type JsonTransportConfig, type LogLevel, type LogOptions, type LoggerConfig, type TransportFn, createDevTransport, createJsonTransport, createLogger };