logixia 2.0.0 → 2.0.4

package/dist/internal-log-uCSd1PMc.mjs

@@ -0,0 +1,142 @@
+// src/utils/sensitive-names.ts
+/**
+* The one list of sensitive names. Log redaction (redact.utils), the HTTP logger
+* middleware and transport secret handling (transports/secret-config) all read it,
+* so the lists cannot drift. No imports: safe from any module, including browser code.
+*/
+/** Field names redacted by name, wherever they appear in logged data. */
+const SENSITIVE_KEY_NAMES = [
+	"password",
+	"passwd",
+	"secret",
+	"token",
+	"apiKey",
+	"api_key",
+	"accessToken",
+	"access_token",
+	"refreshToken",
+	"refresh_token",
+	"authorization",
+	"credentials",
+	"privateKey",
+	"private_key",
+	"clientSecret",
+	"client_secret",
+	"cookie",
+	"set-cookie",
+	"x-api-key",
+	"session",
+	"proxy-authorization",
+	"x-auth-token",
+	"x-access-token",
+	"aws_secret_access_key",
+	"awsSecretAccessKey",
+	"secretAccessKey"
+];
+/**
+* Extra names that only mean "secret" inside transport configuration, where
+* short words like `key` or `signature` are credentials, not log fields.
+*/
+const TRANSPORT_CONFIG_SECRET_NAMES = [
+	"writeKey",
+	"apiSecret",
+	"connectionString",
+	"sessionToken",
+	"passphrase",
+	"signature",
+	"pwd",
+	"pfx",
+	"cert",
+	"key",
+	"auth"
+];
+/** Request headers whose values are never logged. */
+const DEFAULT_REDACT_HEADERS = [
+	"authorization",
+	"cookie",
+	"set-cookie",
+	"x-api-key",
+	"proxy-authorization",
+	"x-auth-token",
+	"x-access-token",
+	"x-csrf-token",
+	"x-amz-security-token"
+];
+/** Query-string parameters whose values are never logged. */
+const DEFAULT_REDACT_QUERY_PARAMS = [
+	"token",
+	"access_token",
+	"refresh_token",
+	"code",
+	"password",
+	"secret",
+	"api_key",
+	"apikey",
+	"key",
+	"signature",
+	"sig",
+	"auth"
+];
+// src/utils/internal-log.ts
+/**
+* Internal logging helpers for use within the logixia library itself.
+*
+* These functions write directly to stderr/stdout without going through
+* LogixiaLogger — this avoids circular dependencies and ensures internal
+* diagnostics still surface even when the logger is misconfigured.
+*
+* Library code must NEVER call console.log/warn/error directly. Use these
+* helpers instead so that internal output can be silenced in tests by setting
+* the LOGIXIA_SILENT_INTERNAL=1 environment variable.
+*/
+/**
+* Read the silence flag on each call rather than caching it at import time, so
+* setting LOGIXIA_SILENT_INTERNAL=1 AFTER the module is first imported (e.g. in
+* a test setup file) still takes effect — the documented test-silencing
+* behavior was previously unreliable because the value was frozen at load.
+*/
+function isSilent() {
+	var _process$env;
+	if (typeof process !== "undefined" && ((_process$env = process.env) === null || _process$env === void 0 ? void 0 : _process$env.LOGIXIA_SILENT_INTERNAL) === "1") return true;
+	const flag = globalThis["LOGIXIA_SILENT_INTERNAL"];
+	return flag === "1" || flag === 1 || flag === true;
+}
+/**
+* Write a line to stderr, falling back to the matching console method where
+* `process` is unavailable (browsers, Cloudflare Workers, Deno without Node compat).
+*/
+function writeLine(method, line) {
+	var _process$stderr;
+	if (typeof process !== "undefined" && typeof ((_process$stderr = process.stderr) === null || _process$stderr === void 0 ? void 0 : _process$stderr.write) === "function") process.stderr.write(`${line}\n`);
+	else if (typeof console !== "undefined" && typeof console[method] === "function") console[method](line);
+}
+/**
+* Emit an internal debug/info message to stderr.
+* Use for field-enable/disable notifications that a developer might want to see
+* during development but should not appear in production log streams.
+*/
+function internalLog(message) {
+	if (!isSilent()) writeLine("log", `[logixia] ${message}`);
+}
+/**
+* Emit an internal warning to stderr.
+* Use when something is misconfigured but logixia can continue operating.
+*/
+function internalWarn(message) {
+	if (!isSilent()) writeLine("warn", `[logixia:warn] ${message}`);
+}
+/**
+* Emit an internal error to stderr.
+* Use when a transport write fails or a serious internal error occurs.
+*/
+function internalError(message, error) {
+	if (!isSilent()) {
+		let errStr = "";
+		if (error instanceof Error) errStr = ` — ${error.message}`;
+		else if (error != null) errStr = ` — ${String(error)}`;
+		writeLine("error", `[logixia:error] ${message}${errStr}`);
+	}
+}
+export { DEFAULT_REDACT_QUERY_PARAMS as a, DEFAULT_REDACT_HEADERS as i, internalLog as n, SENSITIVE_KEY_NAMES as o, internalWarn as r, TRANSPORT_CONFIG_SECRET_NAMES as s, internalError as t };
+
+//# sourceMappingURL=internal-log-uCSd1PMc.mjs.map

package/dist/internal-log-uCSd1PMc.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-log-uCSd1PMc.mjs","names":[],"sources":["../src/utils/sensitive-names.ts","../src/utils/internal-log.ts"],"sourcesContent":["/**\n * The one list of sensitive names. Log redaction (redact.utils), the HTTP logger\n * middleware and transport secret handling (transports/secret-config) all read it,\n * so the lists cannot drift. No imports: safe from any module, including browser code.\n */\n\n/** Field names redacted by name, wherever they appear in logged data. */\nexport const SENSITIVE_KEY_NAMES: readonly string[] = [\n  'password',\n  'passwd',\n  'secret',\n  'token',\n  'apiKey',\n  'api_key',\n  'accessToken',\n  'access_token',\n  'refreshToken',\n  'refresh_token',\n  'authorization',\n  'credentials',\n  'privateKey',\n  'private_key',\n  'clientSecret',\n  'client_secret',\n  'cookie',\n  'set-cookie',\n  'x-api-key',\n  'session',\n  'proxy-authorization',\n  'x-auth-token',\n  'x-access-token',\n  'aws_secret_access_key',\n  'awsSecretAccessKey',\n  'secretAccessKey',\n];\n\n/**\n * Extra names that only mean \"secret\" inside transport configuration, where\n * short words like `key` or `signature` are credentials, not log fields.\n */\nexport const TRANSPORT_CONFIG_SECRET_NAMES: readonly string[] = [\n  'writeKey',\n  'apiSecret',\n  'connectionString',\n  'sessionToken',\n  'passphrase',\n  'signature',\n  'pwd',\n  'pfx',\n  'cert',\n  'key',\n  'auth',\n];\n\n/** Request headers whose values are never logged. */\nexport const DEFAULT_REDACT_HEADERS: readonly string[] = [\n  'authorization',\n  'cookie',\n  'set-cookie',\n  'x-api-key',\n  'proxy-authorization',\n  'x-auth-token',\n  'x-access-token',\n  'x-csrf-token',\n  'x-amz-security-token',\n];\n\n/** Query-string parameters whose values are never logged. */\nexport const DEFAULT_REDACT_QUERY_PARAMS: readonly string[] = [\n  'token',\n  'access_token',\n  'refresh_token',\n  'code',\n  'password',\n  'secret',\n  'api_key',\n  'apikey',\n  'key',\n  'signature',\n  'sig',\n  'auth',\n];\n","/**\n * Internal logging helpers for use within the logixia library itself.\n *\n * These functions write directly to stderr/stdout without going through\n * LogixiaLogger — this avoids circular dependencies and ensures internal\n * diagnostics still surface even when the logger is misconfigured.\n *\n * Library code must NEVER call console.log/warn/error directly. Use these\n * helpers instead so that internal output can be silenced in tests by setting\n * the LOGIXIA_SILENT_INTERNAL=1 environment variable.\n */\n\n/**\n * Read the silence flag on each call rather than caching it at import time, so\n * setting LOGIXIA_SILENT_INTERNAL=1 AFTER the module is first imported (e.g. in\n * a test setup file) still takes effect — the documented test-silencing\n * behavior was previously unreliable because the value was frozen at load.\n */\nfunction isSilent(): boolean {\n  if (typeof process !== 'undefined' && process.env?.LOGIXIA_SILENT_INTERNAL === '1') return true;\n  const flag = (globalThis as Record<string, unknown>)['LOGIXIA_SILENT_INTERNAL'];\n  return flag === '1' || flag === 1 || flag === true;\n}\n\ntype ConsoleMethod = 'log' | 'warn' | 'error';\n\n/**\n * Write a line to stderr, falling back to the matching console method where\n * `process` is unavailable (browsers, Cloudflare Workers, Deno without Node compat).\n */\nfunction writeLine(method: ConsoleMethod, line: string): void {\n  if (typeof process !== 'undefined' && typeof process.stderr?.write === 'function') {\n    process.stderr.write(`${line}\\n`);\n  } else if (typeof console !== 'undefined' && typeof console[method] === 'function') {\n    console[method](line);\n  }\n}\n\n/**\n * Emit an internal debug/info message to stderr.\n * Use for field-enable/disable notifications that a developer might want to see\n * during development but should not appear in production log streams.\n */\nexport function internalLog(message: string): void {\n  if (!isSilent()) {\n    writeLine('log', `[logixia] ${message}`);\n  }\n}\n\n/**\n * Emit an internal warning to stderr.\n * Use when something is misconfigured but logixia can continue operating.\n */\nexport function internalWarn(message: string): void {\n  if (!isSilent()) {\n    writeLine('warn', `[logixia:warn] ${message}`);\n  }\n}\n\n/**\n * Emit an internal error to stderr.\n * Use when a transport write fails or a serious internal error occurs.\n */\nexport function internalError(message: string, error?: unknown): void {\n  if (!isSilent()) {\n    let errStr = '';\n    if (error instanceof Error) {\n      errStr = ` — ${error.message}`;\n    } else if (error != null) {\n      errStr = ` — ${String(error)}`;\n    }\n    writeLine('error', `[logixia:error] ${message}${errStr}`);\n  }\n}\n"],"mappings":";;;;;;;AAOA,MAAa,sBAAyC;CACpD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;AAMA,MAAa,gCAAmD;CAC9D;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,yBAA4C;CACvD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,8BAAiD;CAC5D;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;;;;;;;AC/DA,SAAS,WAAoB;;CAC3B,IAAI,OAAO,YAAY,iBAAA,eAAe,QAAQ,SAAA,QAAA,iBAAA,KAAA,IAAA,KAAA,IAAA,aAAK,6BAA4B,KAAK,OAAO;CAC3F,MAAM,OAAQ,WAAuC;CACrD,OAAO,SAAS,OAAO,SAAS,KAAK,SAAS;AAChD;;;;;AAQA,SAAS,UAAU,QAAuB,MAAoB;;CAC5D,IAAI,OAAO,YAAY,eAAe,SAAA,kBAAO,QAAQ,YAAA,QAAA,oBAAA,KAAA,IAAA,KAAA,IAAA,gBAAQ,WAAU,YACrE,QAAQ,OAAO,MAAM,GAAG,KAAK,GAAG;MAC3B,IAAI,OAAO,YAAY,eAAe,OAAO,QAAQ,YAAY,YACtE,QAAQ,OAAO,CAAC,IAAI;AAExB;;;;;;AAOA,SAAgB,YAAY,SAAuB;CACjD,IAAI,CAAC,SAAS,GACZ,UAAU,OAAO,aAAa,SAAS;AAE3C;;;;;AAMA,SAAgB,aAAa,SAAuB;CAClD,IAAI,CAAC,SAAS,GACZ,UAAU,QAAQ,kBAAkB,SAAS;AAEjD;;;;;AAMA,SAAgB,cAAc,SAAiB,OAAuB;CACpE,IAAI,CAAC,SAAS,GAAG;EACf,IAAI,SAAS;EACb,IAAI,iBAAiB,OACnB,SAAS,MAAM,MAAM;OAChB,IAAI,SAAS,MAClB,SAAS,MAAM,OAAO,KAAK;EAE7B,UAAU,SAAS,mBAAmB,UAAU,QAAQ;CAC1D;AACF"}

package/dist/{logitron-logger-UVeN-mQm.d.ts → logitron-logger-D2B75Oc7.d.ts}

@@ -1,7 +1,4 @@
-import { b as LoggerWithLevels, f as ILogger, h as LogEntry, p as ILoggerDefault, v as LogLevelString, x as NamespaceLevels, y as LoggerConfig } from "./index-DhIoploR.js";
-
-//#region src/plugin.d.ts
-
+import { b as LoggerWithLevels, f as ILogger, h as LogEntry, p as ILoggerDefault, v as LogLevelString, x as NamespaceLevels, y as LoggerConfig } from "./index-DwozbmB4.js";
 interface LogixiaPlugin {
   /**
    * Unique plugin name.
@@ -98,8 +95,19 @@ declare const globalPluginRegistry: PluginRegistry;
  * ```
  */
 declare function usePlugin(plugin: LogixiaPlugin): void;
-//#endregion
-//#region src/core/logitron-logger.d.ts
+/**
+ * The logixia logger. Create instances with {@link createLogger} so that custom
+ * levels from `levelOptions.levels` also become methods.
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger({ appName: 'api', environment: 'production' });
+ * await logger.info('Server started', { port: 3000 });
+ * const req = logger.child('RequestHandler', { requestId: 'r-1' });
+ * await req.error(new Error('boom'));
+ * await logger.close(); // flush buffered transports before exit
+ * ```
+ */
 declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>> = LoggerConfig> implements ILoggerDefault {
   [K: string]: any;
   private config;
@@ -114,6 +122,8 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
   private _levelValues;
   /** Numeric threshold for the currently active log level. */
   private _minLevelValue;
+  /** Level set via setLevel(); outranks every other level source until the process ends. */
+  private _runtimeLevel;
   /** `source=value` pairs already reported as unknown levels — warn once per logger. */
   private readonly _warnedInvalidLevels;
   /** Pre-built ANSI color codes to avoid recreating the object in colorize(). */
@@ -145,17 +155,61 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
    * Keeps the actual log() call free of allocations in the common case.
    */
   private _buildPerfCaches;
+  /**
+   * Log at `error` level. An `Error` is logged with its message and serialized
+   * (name, message, stack) under `data.error`; a string is logged as-is.
+   * `data` is merged into the entry payload.
+   */
   error(messageOrError: string | Error, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `warn` level; `data` is merged into the entry payload. */
   warn(message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `info` level; `data` is merged into the entry payload. */
   info(message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `debug` level; `data` is merged into the entry payload. */
   debug(message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `trace` level; `data` is merged into the entry payload. */
   trace(message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `verbose` level; `data` is merged into the entry payload. */
   verbose(message: string, data?: Record<string, unknown>): Promise<void>;
+  /**
+   * Log at an arbitrary level name, including custom levels. Levels below the
+   * active threshold are dropped, as are level names that are not registered
+   * in `levelOptions.levels` (and are not built-in).
+   */
   logLevel(level: string, message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Start a named timer; finish it with {@link timeEnd}. Reusing a label restarts it. */
   time(label: string): void;
+  /**
+   * Stop the timer `label`, log its duration at `info` level, and return the
+   * elapsed milliseconds. Logs a `warn` and returns `undefined` if the timer
+   * does not exist.
+   *
+   * @example
+   * ```ts
+   * logger.time('db');
+   * await query();
+   * const ms = await logger.timeEnd('db');
+   * ```
+   */
   timeEnd(label: string): Promise<number | undefined>;
   timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Change the minimum log level at runtime. The override outranks
+   * `LOGIXIA_LEVEL`, `LOGIXIA_LEVEL_<NS>` and `namespaceLevels`, and survives
+   * later changes to fields or namespace levels. Unknown level names are
+   * ignored with a warning and the current level is kept.
+   *
+   * @example
+   * ```ts
+   * logger.setLevel('debug');
+   * ```
+   */
   setLevel(level: LogLevelString): void;
+  /**
+   * Return the configured minimum log level, not the per-namespace effective
+   * one. Without `setLevel()` it is `LOGIXIA_LEVEL`, else `levelOptions.level`,
+   * else a `NODE_ENV` default (`debug` in development, `warn` in test), else `info`.
+   */
   getLevel(): LogLevelString;
   private _validLevelList;
   /**
@@ -182,21 +236,43 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
   patchNamespaceLevels(levels: NamespaceLevels): void;
   /** Return a copy of the current per-namespace level map. */
   getNamespaceLevels(): NamespaceLevels;
+  /** Set the context label (e.g. a class or module name) attached to every subsequent entry. */
   setContext(context: string): void;
+  /** Return the current context label, or `undefined` if none is set. */
   getContext(): string | undefined;
+  /** Show `fieldName` in log output, overriding the config for this logger instance. */
   enableField(fieldName: string): void;
+  /** Hide `fieldName` from log output, overriding the config for this logger instance. */
   disableField(fieldName: string): void;
+  /** Whether `fieldName` is currently shown: runtime override first, then config, default `true`. */
   isFieldEnabled(fieldName: string): boolean;
+  /** Return the visibility (`true` = shown) of every standard log field. */
   getFieldState(): Record<string, boolean>;
+  /** Drop all runtime enable/disable overrides so field visibility follows the config again. */
   resetFieldState(): void;
   /** @deprecated No-op. Library code never prompts on stdin; use setTransportLevels(). */
   enableTransportLevelPrompting(): void;
   /** @deprecated No-op. */
   disableTransportLevelPrompting(): void;
+  /** Restrict `transportId` to only the given `levels`. Warns if no transports are configured. */
   setTransportLevels(transportId: string, levels: string[]): void;
+  /** Return the levels `transportId` is restricted to, or `undefined` if it has none. */
   getTransportLevels(transportId: string): string[] | undefined;
   clearTransportLevelPreferences(): void;
+  /** Return the identifiers of the configured transports (empty if none). */
   getAvailableTransports(): string[];
+  /**
+   * Create a child logger with its own `context` that shares this logger's
+   * configuration and transports. `data` is merged into the bound fields
+   * inherited from this logger and added to every entry the child writes.
+   * Closing a child does not close the shared transports.
+   *
+   * @example
+   * ```ts
+   * const req = logger.child('Checkout', { requestId: 'r-42' });
+   * await req.info('started'); // entry includes requestId
+   * ```
+   */
   child(context: string, data?: Record<string, unknown>): ILogger;
   /**
    * Register a plugin on this logger instance.
@@ -215,11 +291,27 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
    * No-op if the plugin is not registered on this instance.
    */
   unuse(pluginName: string): this;
+  /** Flush buffered entries in all transports without closing them. */
   flush(): Promise<void>;
+  /** Report whether the transports are healthy; `healthy: false` if no transport manager exists. */
   healthCheck(): Promise<{
     healthy: boolean;
     details: Record<string, unknown>;
   }>;
+  /**
+   * Warn about timers that were never ended, then flush and close all transports,
+   * stop the sampler and run plugin shutdown hooks. On a child logger only the
+   * timer warnings run; the shared transports stay open.
+   *
+   * To flush on SIGTERM/SIGINT, set the `gracefulShutdown` config option rather
+   * than writing your own signal handler; do not combine it with a manual
+   * handler that calls `process.exit`, which can cut the flush short.
+   *
+   * @example
+   * ```ts
+   * await logger.close(); // e.g. at the end of a script or a test
+   * ```
+   */
   close(): Promise<void>;
   private log;
   /**
@@ -231,6 +323,7 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
    * Feature 3: Resolve the effective log level for this logger instance.
    *
    * Priority:
+   *  0. A level set at runtime with `setLevel()` (explicit programmatic call, wins over all below)
    *  1. ENV `LOGIXIA_LEVEL_<NS_UPPER>` (e.g. LOGIXIA_LEVEL_DB for ns "db" or "db.queries")
    *  2. Matching `namespaceLevels` config entry (longer pattern = more specific, wins)
    *  3. Global `LOGIXIA_LEVEL` ENV override
@@ -251,7 +344,22 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
    * back to a direct stdout/stderr write so the entry is never lost. */
   private _handleOutputError;
 }
+/**
+ * Create a logger from `config`, with an optional default `context` label.
+ *
+ * Every key of `levelOptions.levels` that is not already a method becomes an
+ * async method on the returned logger, typed through the config, and routes to
+ * {@link LogixiaLogger.logLevel}.
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger({
+ *   appName: 'api',
+ *   levelOptions: { level: 'info', levels: { error: 0, warn: 1, info: 2, audit: 2 } },
+ * });
+ * await logger.audit('user exported data', { userId: 'u1' });
+ * ```
+ */
 declare function createLogger<T extends LoggerConfig<Record<string, number>>>(config: T, context?: string): LoggerWithLevels<T>;
-//#endregion
 export { globalPluginRegistry as a, PluginRegistry as i, createLogger as n, usePlugin as o, LogixiaPlugin as r, LogixiaLogger as t };
-//# sourceMappingURL=logitron-logger-UVeN-mQm.d.ts.map
+//# sourceMappingURL=logitron-logger-D2B75Oc7.d.ts.map

package/dist/logitron-logger-D2B75Oc7.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logitron-logger-D2B75Oc7.d.ts","names":[],"sources":["../src/plugin.ts","../src/core/logitron-logger.ts"],"mappings":";UAkCiB;;;;;;EAMf;;;;;;EAOA,kBAAkB;;;;;;;;;;;;EAalB,OAAO,OAAO,WAAW,kBAAkB,QAAQ;;;;;;EAOnD,SAAS,OAAO,OAAO,QAAQ,kBAAkB;;;;;;EAOjD,sBAAsB;;;;;;;cAUX;mBACM;;;;;EAMjB,SAAS,QAAQ;;EAiBjB,WAAW;;EAMX,IAAI;;MAKA;;;;;;EASE,SAAS,OAAO,WAAW,QAAQ;;;;;EAsBnC,WAAW,OAAO,OAAO,QAAQ,WAAW;;EAiB5C,iBAAiB;;;;;;;;;cA2BZ,sBAAoB;;;;;;;;;;;;;;;;;;iBAmBjB,UAAU,QAAQ;;;;;;;;;;;;;;cC7BrB,cACX,gBAAgB,aAAa,0BAA0B,yBAC5C;GAEV;UAEO;UACA;UACA;UACA;UACA;UACA;;mBAGS;;UAIT;;UAEA;;UAEA;;mBAES;;UAET;;UAEA;;UAEA;;;;;UAKA;;UAEA;;UAEA;;UAEA;;mBAES;;mBAEA;EAEL,YAAA,QAAQ,SAAS,kBAAkB,SAAS,cAAc;UAqG9D;UAiBA;;;;;UAqBA;;;;;;EA2HF,MAAM,yBAAyB,OAAO,OAAO,0BAA0B;;EAYvE,KAAK,iBAAiB,OAAO,0BAA0B;;EAKvD,KAAK,iBAAiB,OAAO,0BAA0B;;EAKvD,MAAM,iBAAiB,OAAO,0BAA0B;;EAKxD,MAAM,iBAAiB,OAAO,0BAA0B;;EAKxD,QAAQ,iBAAiB,OAAO,0BAA0B;;;;;;EAS1D,SAAS,eAAe,iBAAiB,OAAO,0BAA0B;;EAOhF,KAAK;;;;;;;;;;;;;EAgBC,QAAQ,gBAAgB;EAmBxB,UAAU,GAAG,eAAe,UAAU,QAAQ,KAAK,QAAQ;;;;;;;;;;;;EAyBjE,SAAS,OAAO;;;;;;EAuBhB,YAAY;UAIJ;;;;;UAQA;;;;;;;;;;;;;;;EA8BR,mBAAmB,QAAQ;;EAQ3B,qBAAqB,QAAQ;;EAM7B,sBAAsB;;EAKtB,WAAW;;EAKX;;EAOA,YAAY;;EASZ,aAAa;;EASb,eAAe;;EASf,iBAAiB;;EAmBjB;;EAQA;;EAMA;;EAMA,mBAAmB,qBAAqB;;EAMxC,mBAAmB;EAMnB;;EAMA;;;;;;;;;;;;;EAkBA,MAAM,iBAAiB,OAAO,0BAA0B;;;;;;;;;;;;EA0BxD,IAAI,QAAQ;;;;;EASZ,MAAM;;EAQA,SAAS;;EAKT,eAAe;IAAU;IAAkB,SAAS;;;;;;;;;;;;;;;;EAqBpD,SAAS;UAsBD;;;;;UA0GN;;;;;;;;;;;UAeA;UAwCA;UAgDA;;;;;;;;UAcA;;;UAuBM;;;;;;;;;;;;;;;;;;iBA+BA,aAAa,UAAU,aAAa,yBAClD,QAAQ,GACR,mBACC,iBAAiB"}

package/dist/{logitron-logger-BFDSO8Io.d.mts → logitron-logger-oEd6wNhf.d.mts}

@@ -1,7 +1,4 @@
-import { b as LoggerWithLevels, f as ILogger, h as LogEntry, p as ILoggerDefault, v as LogLevelString, x as NamespaceLevels, y as LoggerConfig } from "./index-3mw5gaCw.mjs";
-
-//#region src/plugin.d.ts
-
+import { b as LoggerWithLevels, f as ILogger, h as LogEntry, p as ILoggerDefault, v as LogLevelString, x as NamespaceLevels, y as LoggerConfig } from "./index-xqaJtAZn.mjs";
 interface LogixiaPlugin {
   /**
    * Unique plugin name.
@@ -98,8 +95,19 @@ declare const globalPluginRegistry: PluginRegistry;
  * ```
  */
 declare function usePlugin(plugin: LogixiaPlugin): void;
-//#endregion
-//#region src/core/logitron-logger.d.ts
+/**
+ * The logixia logger. Create instances with {@link createLogger} so that custom
+ * levels from `levelOptions.levels` also become methods.
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger({ appName: 'api', environment: 'production' });
+ * await logger.info('Server started', { port: 3000 });
+ * const req = logger.child('RequestHandler', { requestId: 'r-1' });
+ * await req.error(new Error('boom'));
+ * await logger.close(); // flush buffered transports before exit
+ * ```
+ */
 declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>> = LoggerConfig> implements ILoggerDefault {
   [K: string]: any;
   private config;
@@ -114,6 +122,8 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
   private _levelValues;
   /** Numeric threshold for the currently active log level. */
   private _minLevelValue;
+  /** Level set via setLevel(); outranks every other level source until the process ends. */
+  private _runtimeLevel;
   /** `source=value` pairs already reported as unknown levels — warn once per logger. */
   private readonly _warnedInvalidLevels;
   /** Pre-built ANSI color codes to avoid recreating the object in colorize(). */
@@ -145,17 +155,61 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
    * Keeps the actual log() call free of allocations in the common case.
    */
   private _buildPerfCaches;
+  /**
+   * Log at `error` level. An `Error` is logged with its message and serialized
+   * (name, message, stack) under `data.error`; a string is logged as-is.
+   * `data` is merged into the entry payload.
+   */
   error(messageOrError: string | Error, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `warn` level; `data` is merged into the entry payload. */
   warn(message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `info` level; `data` is merged into the entry payload. */
   info(message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `debug` level; `data` is merged into the entry payload. */
   debug(message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `trace` level; `data` is merged into the entry payload. */
   trace(message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Log `message` at `verbose` level; `data` is merged into the entry payload. */
   verbose(message: string, data?: Record<string, unknown>): Promise<void>;
+  /**
+   * Log at an arbitrary level name, including custom levels. Levels below the
+   * active threshold are dropped, as are level names that are not registered
+   * in `levelOptions.levels` (and are not built-in).
+   */
   logLevel(level: string, message: string, data?: Record<string, unknown>): Promise<void>;
+  /** Start a named timer; finish it with {@link timeEnd}. Reusing a label restarts it. */
   time(label: string): void;
+  /**
+   * Stop the timer `label`, log its duration at `info` level, and return the
+   * elapsed milliseconds. Logs a `warn` and returns `undefined` if the timer
+   * does not exist.
+   *
+   * @example
+   * ```ts
+   * logger.time('db');
+   * await query();
+   * const ms = await logger.timeEnd('db');
+   * ```
+   */
   timeEnd(label: string): Promise<number | undefined>;
   timeAsync<T>(label: string, fn: () => Promise<T>): Promise<T>;
+  /**
+   * Change the minimum log level at runtime. The override outranks
+   * `LOGIXIA_LEVEL`, `LOGIXIA_LEVEL_<NS>` and `namespaceLevels`, and survives
+   * later changes to fields or namespace levels. Unknown level names are
+   * ignored with a warning and the current level is kept.
+   *
+   * @example
+   * ```ts
+   * logger.setLevel('debug');
+   * ```
+   */
   setLevel(level: LogLevelString): void;
+  /**
+   * Return the configured minimum log level, not the per-namespace effective
+   * one. Without `setLevel()` it is `LOGIXIA_LEVEL`, else `levelOptions.level`,
+   * else a `NODE_ENV` default (`debug` in development, `warn` in test), else `info`.
+   */
   getLevel(): LogLevelString;
   private _validLevelList;
   /**
@@ -182,21 +236,43 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
   patchNamespaceLevels(levels: NamespaceLevels): void;
   /** Return a copy of the current per-namespace level map. */
   getNamespaceLevels(): NamespaceLevels;
+  /** Set the context label (e.g. a class or module name) attached to every subsequent entry. */
   setContext(context: string): void;
+  /** Return the current context label, or `undefined` if none is set. */
   getContext(): string | undefined;
+  /** Show `fieldName` in log output, overriding the config for this logger instance. */
   enableField(fieldName: string): void;
+  /** Hide `fieldName` from log output, overriding the config for this logger instance. */
   disableField(fieldName: string): void;
+  /** Whether `fieldName` is currently shown: runtime override first, then config, default `true`. */
   isFieldEnabled(fieldName: string): boolean;
+  /** Return the visibility (`true` = shown) of every standard log field. */
   getFieldState(): Record<string, boolean>;
+  /** Drop all runtime enable/disable overrides so field visibility follows the config again. */
   resetFieldState(): void;
   /** @deprecated No-op. Library code never prompts on stdin; use setTransportLevels(). */
   enableTransportLevelPrompting(): void;
   /** @deprecated No-op. */
   disableTransportLevelPrompting(): void;
+  /** Restrict `transportId` to only the given `levels`. Warns if no transports are configured. */
   setTransportLevels(transportId: string, levels: string[]): void;
+  /** Return the levels `transportId` is restricted to, or `undefined` if it has none. */
   getTransportLevels(transportId: string): string[] | undefined;
   clearTransportLevelPreferences(): void;
+  /** Return the identifiers of the configured transports (empty if none). */
   getAvailableTransports(): string[];
+  /**
+   * Create a child logger with its own `context` that shares this logger's
+   * configuration and transports. `data` is merged into the bound fields
+   * inherited from this logger and added to every entry the child writes.
+   * Closing a child does not close the shared transports.
+   *
+   * @example
+   * ```ts
+   * const req = logger.child('Checkout', { requestId: 'r-42' });
+   * await req.info('started'); // entry includes requestId
+   * ```
+   */
   child(context: string, data?: Record<string, unknown>): ILogger;
   /**
    * Register a plugin on this logger instance.
@@ -215,11 +291,27 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
    * No-op if the plugin is not registered on this instance.
    */
   unuse(pluginName: string): this;
+  /** Flush buffered entries in all transports without closing them. */
   flush(): Promise<void>;
+  /** Report whether the transports are healthy; `healthy: false` if no transport manager exists. */
   healthCheck(): Promise<{
     healthy: boolean;
     details: Record<string, unknown>;
   }>;
+  /**
+   * Warn about timers that were never ended, then flush and close all transports,
+   * stop the sampler and run plugin shutdown hooks. On a child logger only the
+   * timer warnings run; the shared transports stay open.
+   *
+   * To flush on SIGTERM/SIGINT, set the `gracefulShutdown` config option rather
+   * than writing your own signal handler; do not combine it with a manual
+   * handler that calls `process.exit`, which can cut the flush short.
+   *
+   * @example
+   * ```ts
+   * await logger.close(); // e.g. at the end of a script or a test
+   * ```
+   */
   close(): Promise<void>;
   private log;
   /**
@@ -231,6 +323,7 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
    * Feature 3: Resolve the effective log level for this logger instance.
    *
    * Priority:
+   *  0. A level set at runtime with `setLevel()` (explicit programmatic call, wins over all below)
    *  1. ENV `LOGIXIA_LEVEL_<NS_UPPER>` (e.g. LOGIXIA_LEVEL_DB for ns "db" or "db.queries")
    *  2. Matching `namespaceLevels` config entry (longer pattern = more specific, wins)
    *  3. Global `LOGIXIA_LEVEL` ENV override
@@ -251,7 +344,22 @@ declare class LogixiaLogger<TConfig extends LoggerConfig<Record<string, number>>
    * back to a direct stdout/stderr write so the entry is never lost. */
   private _handleOutputError;
 }
+/**
+ * Create a logger from `config`, with an optional default `context` label.
+ *
+ * Every key of `levelOptions.levels` that is not already a method becomes an
+ * async method on the returned logger, typed through the config, and routes to
+ * {@link LogixiaLogger.logLevel}.
+ *
+ * @example
+ * ```ts
+ * const logger = createLogger({
+ *   appName: 'api',
+ *   levelOptions: { level: 'info', levels: { error: 0, warn: 1, info: 2, audit: 2 } },
+ * });
+ * await logger.audit('user exported data', { userId: 'u1' });
+ * ```
+ */
 declare function createLogger<T extends LoggerConfig<Record<string, number>>>(config: T, context?: string): LoggerWithLevels<T>;
-//#endregion
 export { globalPluginRegistry as a, PluginRegistry as i, createLogger as n, usePlugin as o, LogixiaPlugin as r, LogixiaLogger as t };
-//# sourceMappingURL=logitron-logger-BFDSO8Io.d.mts.map
+//# sourceMappingURL=logitron-logger-oEd6wNhf.d.mts.map

package/dist/logitron-logger-oEd6wNhf.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logitron-logger-oEd6wNhf.d.mts","names":[],"sources":["../src/plugin.ts","../src/core/logitron-logger.ts"],"mappings":";UAkCiB;;;;;;EAMf;;;;;;EAOA,kBAAkB;;;;;;;;;;;;EAalB,OAAO,OAAO,WAAW,kBAAkB,QAAQ;;;;;;EAOnD,SAAS,OAAO,OAAO,QAAQ,kBAAkB;;;;;;EAOjD,sBAAsB;;;;;;;cAUX;mBACM;;;;;EAMjB,SAAS,QAAQ;;EAiBjB,WAAW;;EAMX,IAAI;;MAKA;;;;;;EASE,SAAS,OAAO,WAAW,QAAQ;;;;;EAsBnC,WAAW,OAAO,OAAO,QAAQ,WAAW;;EAiB5C,iBAAiB;;;;;;;;;cA2BZ,sBAAoB;;;;;;;;;;;;;;;;;;iBAmBjB,UAAU,QAAQ;;;;;;;;;;;;;;cC7BrB,cACX,gBAAgB,aAAa,0BAA0B,yBAC5C;GAEV;UAEO;UACA;UACA;UACA;UACA;UACA;;mBAGS;;UAIT;;UAEA;;UAEA;;mBAES;;UAET;;UAEA;;UAEA;;;;;UAKA;;UAEA;;UAEA;;UAEA;;mBAES;;mBAEA;EAEL,YAAA,QAAQ,SAAS,kBAAkB,SAAS,cAAc;UAqG9D;UAiBA;;;;;UAqBA;;;;;;EA2HF,MAAM,yBAAyB,OAAO,OAAO,0BAA0B;;EAYvE,KAAK,iBAAiB,OAAO,0BAA0B;;EAKvD,KAAK,iBAAiB,OAAO,0BAA0B;;EAKvD,MAAM,iBAAiB,OAAO,0BAA0B;;EAKxD,MAAM,iBAAiB,OAAO,0BAA0B;;EAKxD,QAAQ,iBAAiB,OAAO,0BAA0B;;;;;;EAS1D,SAAS,eAAe,iBAAiB,OAAO,0BAA0B;;EAOhF,KAAK;;;;;;;;;;;;;EAgBC,QAAQ,gBAAgB;EAmBxB,UAAU,GAAG,eAAe,UAAU,QAAQ,KAAK,QAAQ;;;;;;;;;;;;EAyBjE,SAAS,OAAO;;;;;;EAuBhB,YAAY;UAIJ;;;;;UAQA;;;;;;;;;;;;;;;EA8BR,mBAAmB,QAAQ;;EAQ3B,qBAAqB,QAAQ;;EAM7B,sBAAsB;;EAKtB,WAAW;;EAKX;;EAOA,YAAY;;EASZ,aAAa;;EASb,eAAe;;EASf,iBAAiB;;EAmBjB;;EAQA;;EAMA;;EAMA,mBAAmB,qBAAqB;;EAMxC,mBAAmB;EAMnB;;EAMA;;;;;;;;;;;;;EAkBA,MAAM,iBAAiB,OAAO,0BAA0B;;;;;;;;;;;;EA0BxD,IAAI,QAAQ;;;;;EASZ,MAAM;;EAQA,SAAS;;EAKT,eAAe;IAAU;IAAkB,SAAS;;;;;;;;;;;;;;;;EAqBpD,SAAS;UAsBD;;;;;UA0GN;;;;;;;;;;;UAeA;UAwCA;UAgDA;;;;;;;;UAcA;;;UAuBM;;;;;;;;;;;;;;;;;;iBA+BA,aAAa,UAAU,aAAa,yBAClD,QAAQ,GACR,mBACC,iBAAiB"}

package/dist/middleware.d.mts

@@ -1,8 +1,4 @@
-import "./transport.types-BMnurPcc.mjs";
-import { u as IBaseLogger } from "./index-3mw5gaCw.mjs";
-
-//#region src/middleware/http-logger.d.ts
-
+import { u as IBaseLogger } from "./index-xqaJtAZn.mjs";
 interface HttpLoggerOptions {
   /**
    * Skip logging for a request. Called before any I/O.
@@ -28,10 +24,13 @@ interface HttpLoggerOptions {
    */
   extraFields?: (req: IncomingRequest) => Record<string, unknown>;
   /**
-   * Trace ID header. Default: 'x-trace-id'.
-   * If the header is absent, a short random ID is generated.
+   * Header name, or list of names tried in order, to read the trace ID from.
+   * Default: the library-wide list (`DEFAULT_TRACE_HEADERS`: traceparent,
+   * x-trace-id, x-request-id, x-correlation-id, trace-id).
+   * If none is present, `request.id` is used when it is not a framework counter,
+   * otherwise a UUID is generated and shared with the logixia context helpers.
    */
-  traceIdHeader?: string;
+  traceIdHeader?: string | readonly string[];
   /**
    * Additional headers to redact from logged output. Merged with the defaults
    * (authorization, cookie, set-cookie, x-api-key, proxy-authorization,
@@ -73,7 +72,7 @@ interface OutgoingResponse {
 /**
  * Create an Express / Connect compatible middleware that replaces Morgan.
  */
-declare function createExpressMiddleware(logger: IBaseLogger, options?: HttpLoggerOptions): (req: IncomingRequest, res: OutgoingResponse, next: () => void) => void;
+export declare function createExpressMiddleware(logger: IBaseLogger, options?: HttpLoggerOptions): (req: IncomingRequest, res: OutgoingResponse, next: () => void) => void;
 interface FastifyInstance {
   addHook: (name: string, fn: (req: unknown, reply: unknown, done: () => void) => void) => void;
 }
@@ -85,9 +84,8 @@ interface FastifyInstance {
  * await fastify.register(createFastifyPlugin(logger, { slowRequestThresholdMs: 500 }));
  * ```
  */
-declare function createFastifyPlugin(logger: IBaseLogger, options?: HttpLoggerOptions): ((fastify: FastifyInstance, _opts: unknown, done: () => void) => void) & {
+export declare function createFastifyPlugin(logger: IBaseLogger, options?: HttpLoggerOptions): ((fastify: FastifyInstance, _opts: unknown, done: () => void) => void) & {
   [x: symbol]: string | boolean;
 };
-//#endregion
-export { type FastifyInstance, type HttpLoggerOptions, type IncomingRequest, type OutgoingResponse, createExpressMiddleware, createFastifyPlugin };
+export type { FastifyInstance, HttpLoggerOptions, IncomingRequest, OutgoingResponse };
 //# sourceMappingURL=middleware.d.mts.map

package/dist/middleware.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.mts","names":[],"sources":["../src/middleware/http-logger.ts"],"sourcesContent":[],"mappings":";;;;;UA+BiB,iBAAA;;;;;eAKF;;;;;;;;;;;;;;;;;;sBAkBO,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA8BzB,eAAA;;;YAGL;;;;;;;UAMK,gBAAA;;;;;;;;;iBAsID,uBAAA,SACN,uBACC,0BACF,sBAAsB;UAqFd,eAAA;;;;;;;;;;;iBAYD,mBAAA,SAA4B,uBAAsB,+BAYzB"}
+{"version":3,"file":"middleware.d.mts","names":[],"sources":["../src/middleware/http-logger.ts"],"mappings":";UAgCiB;;;;;EAKf,QAAQ,KAAK;;;;;;EAMb;;EAEA;;;;;EAKA;;;;;EAKA,eAAe,KAAK,oBAAoB;;;;;;;;EAQxC;;;;;;EAMA;;;;;;EAMA;;;;;EAKA;;EAEA;;EAEA;;UAIe;EACf;EACA;EACA,UAAU;EACV;EACA;IAAW;;EACX;;UAGe;EACf;EACA,MAAM,eAAe;EACrB,QAAQ,eAAe;EACvB,aAAa;;;;;wBAkGC,wBACd,QAAQ,aACR,UAAS,qBACP,KAAK,iBAAiB,KAAK,kBAAkB;UAqFhC;EACf,UAAU,cAAc,KAAK,cAAc,gBAAgB;;;;;;;;;;wBAW7C,oBAAoB,QAAQ,aAAa,UAAS,sBAAsB,SAY/C,iBAAe,gBAAgB"}