@mks2508/better-logger 0.18.2-alpha.1 → 0.18.3

package/dist/transports/TransportManager.d.ts

@@ -1,36 +1,258 @@
-import type { TransportRecord, TransportTarget, TransportOptions, ITransport, ITransportManager, LogLevel } from '../types/index.js';
+import type { TransportTarget, TransportOptions, ITransport, ITransportManager, LogLevel, TransportDispatchRecord } from '../types/index.js';
 /**
- * Constructor signature for transports registered in the built-in registry.
- * Accepts the transport's own options type; pass-through is enforced at
- * registration time via TypeScript but erased at runtime.
+ * Firma del constructor de los transports registrados en el registry
+ * built-in. Acepta el tipo propio de options del transport; el pass-through
+ * se enforcea en registro vía TypeScript pero se borra en runtime.
  */
 export type TransportConstructor = new (options?: TransportOptions) => ITransport;
+/**
+ * Registry y dispatcher de transports. Mantiene el set activo de destinos
+ * de log (console, file, http, otlp, o transports custom registrados vía
+ * {@link TransportManager.register}) y les dispatcha cada
+ * {@link TransportRecord} producido por el Logger.
+ *
+ * Cada transport added se identifica por un `id` opaco (generado por la
+ * propia instancia) que devuelven {@link add} y {@link list}, y que acepta
+ * {@link remove}. El registry arranca con los cuatro built-ins
+ * (`console` / `file` / `http` / `otlp`) ya cargados; {@link register}
+ * añade customs sin poder sobreescribir los built-ins (lanza).
+ *
+ * El dispatch ({@link write}) aplica el filtro de `level` por transport y
+ * el `transform` opcional de {@link TransportOptions}, y captura toda
+ * excepción / rechazo de cada transport para que un transport roto nunca
+ * rompa el log call del caller. El propio Logger habla con el manager a
+ * través del facade {@link TransportBridge} (ver
+ * `Logger.addTransport` / `Logger.getTransportManager`).
+ *
+ * Implementa {@link ITransportManager}.
+ *
+ * @example
+ * // Manager con nivel default y transports añadidos por nombre
+ * const tm = new TransportManager('info');
+ * tm.add({ target: 'console' });
+ * tm.add({ target: 'file', options: { path: './app.log' } });
+ *
+ * @example
+ * // Registrar un transport custom y usarlo por nombre
+ * tm.register('datadog', DatadogTransport);
+ * tm.add({ target: 'datadog', options: { apiKey: env('DD_KEY') } });
+ *
+ * @example
+ * // Pasar una instancia de ITransport directamente (sin pasar por registry)
+ * tm.add({ target: new MyTransport(), level: 'warn' });
+ *
+ * @example
+ * // Dispatch + ciclo de vida
+ * await tm.write(record);
+ * await tm.flush();   // flusha todos los buffered
+ * await tm.close();   // flush + close + clear
+ *
+ * @see {@link ITransportManager}
+ * @see {@link TransportTarget}
+ * @see {@link TransportBridge}
+ */
 export declare class TransportManager implements ITransportManager {
     private transports;
     private defaultLevel;
     private readonly registry;
+    /**
+     * Crea un nuevo manager.
+     *
+     * @param {LogLevel} [defaultLevel='info'] - Nivel mínimo por defecto
+     *   para transports añadidos sin `level` explícito en su
+     *   {@link TransportTarget}. Records con `levelValue` inferior al del
+     *   transport se descartan en {@link write}.
+     *
+     * @example
+     * const tm = new TransportManager('debug'); // todo pasa salvo filter propio
+     */
     constructor(defaultLevel?: LogLevel);
     /**
-     * Registers a custom transport under a string name. Once registered,
-     * `addTransport({ target: 'name', options })` instantiates it.
+     * Registra un constructor de transport bajo un nombre string. Tras el
+     * registro, `add({ target: name, options })` instancia ese transport con
+     * las options pasadas.
+     *
+     * No se puede sobreescribir un built-in (`console` / `file` / `http` /
+     * `otlp`): lanza para evitar silenciar un transport crítico por un
+     * accidente de naming. El registro es por-instancia (no comparte entre
+     * managers).
+     *
+     * @param {string} name - Nombre bajo el que registrar (usado luego como
+     *   `target` en {@link TransportTarget}).
+     * @param {TransportConstructor} ctor - Constructor que acepta
+     *   {@link TransportOptions} y devuelve un {@link ITransport}.
+     * @throws {Error} Si `name` colisiona con un built-in del registry.
      *
      * @example
-     * transportManager.register('datadog', DatadogTransport);
-     * transportManager.add({ target: 'datadog', options: { apiKey: env('DD_KEY') } });
+     * tm.register('datadog', DatadogTransport);
+     * tm.add({ target: 'datadog', options: { apiKey: env('DD_KEY') } });
      *
+     * @see {@link listRegistered}
      */
     register(name: string, ctor: TransportConstructor): void;
     /**
-     * Lists all registered transport names (built-ins + custom).
+     * Lista los nombres de transports registrados en esta instancia
+     * (built-ins + customs añadidos vía {@link register}).
      *
+     * @returns {string[]} Nombres registrados. Incluye siempre los cuatro
+     *   built-ins.
+     *
+     * @example
+     * tm.register('loki', LokiTransport);
+     * tm.listRegistered(); // ['console', 'file', 'http', 'otlp', 'loki']
      */
     listRegistered(): string[];
+    /**
+     * Añade un transport al set activo y devuelve su id opaco.
+     *
+     * Acepta dos formas de `target`:
+     *   - **string**: se resuelve contra el registry (built-ins + customs
+     *     vía {@link register}). Lanza si el nombre no existe, listando los
+     *     registrados para facilitar el debug.
+     *   - **ITransport instancia**: se registra tal cual, sin pasar por el
+     *     registry. Útil para transports one-off o cuya configuración no
+     *     encaja en un constructor reutilizable.
+     *
+     * El `level` (explícito en el target o `defaultLevel` del manager) fija
+     * el filtro por transport — los records con `levelValue` inferior se
+     * descartan en {@link write}. El `transform` opcional de
+     * {@link TransportOptions} se aplica por transport antes de delegar al
+     * `write` concreto.
+     *
+     * @param {TransportTarget} target - Especificación del transport a añadir.
+     * @returns {string} Id opaco del transport añadido. Úsalo con
+     *   {@link remove}; aparece en {@link list}.
+     * @throws {Error} Si `target.target` es un string no presente en el
+     *   registry.
+     *
+     * @example
+     * // Por nombre (built-in o custom registrado)
+     * const id = tm.add({ target: 'console' });
+     *
+     * @example
+     * // Instancia directa con nivel y transform propios
+     * const id = tm.add({
+     *   target: new MyTransport(),
+     *   level: 'warn',
+     *   options: { transform: r => r.level === 'debug' ? null : r }
+     * });
+     *
+     * @see {@link TransportTarget}
+     */
     add(target: TransportTarget): string;
+    /**
+     * Elimina un transport del set por su id. Si el transport expone
+     * `close()`, lo invoca para liberar recursos (timers, sockets, file
+     * handles). Si `close()` devuelve una Promise, su eventual rechazo se
+     * ignora de forma best-effort — los errores de close durante la
+     * remoción no se propagan al caller.
+     *
+     * @param {string} id - Id devuelto por {@link add}.
+     * @returns {boolean} `true` si había un transport con ese id (y se
+     *   eliminó), `false` si el id no existía.
+     *
+     * @example
+     * const id = tm.add({ target: 'file', options: { path: './app.log' } });
+     * tm.remove(id); // true — FileTransport.close() se invoca
+     */
     remove(id: string): boolean;
-    write(record: TransportRecord): Promise<void>;
+    /**
+     * Dispatcha un {@link TransportRecord} o {@link SpanRecord} a todos los
+     * transports activos que acepten su kind.
+     *
+     * Por cada transport, en orden:
+     *   1. **Routing por kind**: el kind del record (`'log'` o `'span'`)
+     *      debe estar en el `accepts` del transport (default `['log']` cuando
+     *      no lo declara). Un `SpanRecord` JAMÁS llega a un transport
+     *      log-only, y viceversa — esto evita que un `OtlpTransport` serialice
+     *      spans como `logRecords` hacia `/v1/logs`.
+     *   2. **Filtro de nivel** (solo logs): si `record.levelValue <
+     *      entry.levelValue`, se skipa. Los spans no tienen nivel.
+     *   3. **Transform** (solo logs): si `entry.options.transform` está
+     *      seteado, se aplica al record. Si devuelve `null`, el record se
+     *      droppea para este transport. Los spans NO pasan por transform —
+     *      su contrato asume shape de log (muta `record.message`).
+     *   4. **Write**: se llama a `transport.write(record)`. Si
+     *      devuelve una Promise, se añade al batch await. Toda excepción
+     *      sincrónica o rechazo de Promise se captura y se loguea por
+     *      consola — el log call original del caller nunca rompe por un
+     *      transport roto.
+     *
+     * El método es async: retorna después de que todos los transports hayan
+     * resuelto (o fallado) su write. Para fire-and-forget desde el Logger,
+     * el caller puede ignorar la Promise.
+     *
+     * @param {TransportDispatchRecord} record - Record (log o span) a dispatchar.
+     * @returns {Promise<void>} Resuelve cuando todos los writes terminaron
+     *   (exitosos o fallidos). Nunca rechaza.
+     *
+     * @example
+     * await tm.write({
+     *   level: 'info', levelValue: 1, severityNumber: 9, severityText: 'INFO',
+     *   time: Date.now(), msg: 'boot ok'
+     * });
+     *
+     * @see {@link TransportRecord}
+     * @see {@link SpanRecord}
+     */
+    write(record: TransportDispatchRecord): Promise<void>;
+    /**
+     * Flushea todos los transports que expongan `flush()` (buffered transports
+     * como {@link HttpTransport}, {@link FileTransport}, {@link OtlpTransport}).
+     * Los transports sin `flush()` (p.ej. {@link ConsoleTransport}) se
+     * skipan sin error.
+     *
+     * Errores de flush (sync throw o Promise rejection) se capturan y
+     * loguean por consola — nunca propagan al caller. Útil para forzar el
+     * envío del batch pendiente antes de un graceful shutdown.
+     *
+     * @returns {Promise<void>} Resuelve cuando todos los flushes terminaron.
+     *
+     * @example
+     * await tm.flush();
+     */
     flush(): Promise<void>;
+    /**
+     * Shutdown ordenado: flushea todos los transports buffered, luego
+     * invoca `close()` en cada uno, y finalmente limpia el set interno.
+     * Tras esto la instancia queda sin transports — reusarla requiere
+     * `add()` de nuevo.
+     *
+     * Los errores de close (sync throw o Promise rejection) se capturan y
+     * loguean — nunca propagan al caller.
+     *
+     * @returns {Promise<void>} Resuelve cuando flush + close de todos los
+     *   transports terminaron.
+     *
+     * @example
+     * // Shutdown limpio del proceso
+     * process.on('SIGTERM', async () => {
+     *   await logger.getTransportManager()?.close();
+     *   process.exit(0);
+     * });
+     */
     close(): Promise<void>;
+    /**
+     * Número de transports actualmente en el set activo.
+     *
+     * @returns {number}
+     *
+     * @example
+     * if (tm.count === 0) console.warn('no transports configured');
+     */
     get count(): number;
+    /**
+     * Lista los ids opacos de los transports actualmente activos.
+     *
+     * @returns {string[]} Array de ids (mismo formato opaco que devolvió
+     *   {@link add}).
+     *
+     * @example
+     * for (const id of tm.list()) {
+     *   console.log('removing transport', id);
+     *   tm.remove(id);
+     * }
+     */
     list(): string[];
 }
 //# sourceMappingURL=TransportManager.d.ts.map

package/dist/transports/TransportManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TransportManager.d.ts","sourceRoot":"","sources":["../../src/transports/TransportManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACX,MAAM,mBAAmB,CAAC;AAW3B;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,OAAO,CAAC,EAAE,gBAAgB,KAAK,UAAU,CAAC;AA6BlF,qBAAa,gBAAiB,YAAW,iBAAiB;IACtD,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgE;gBAE7E,YAAY,CAAC,EAAE,QAAQ;IAMnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAOxD;;;OAGG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;IA+BpC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAcrB,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B5B,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,IAAI,MAAM,EAAE;CAGnB"}
+{"version":3,"file":"TransportManager.d.ts","sourceRoot":"","sources":["../../src/transports/TransportManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAER,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,QAAQ,EAER,uBAAuB,EAC1B,MAAM,mBAAmB,CAAC;AAoB3B;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,OAAO,CAAC,EAAE,gBAAgB,KAAK,UAAU,CAAC;AAiDlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAiB,YAAW,iBAAiB;IACtD,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgE;IAEzF;;;;;;;;;;OAUG;gBACS,YAAY,CAAC,EAAE,QAAQ;IAMnC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAOxD;;;;;;;;;;OAUG;IACH,cAAc,IAAI,MAAM,EAAE;IAI1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,GAAG,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM;IA+BpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAc3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACG,KAAK,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IA8C3D;;;;;;;;;;;;;;OAcG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB5B;;;;;;;;;;;;;;;;;;OAkBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B5B;;;;;;;OAOG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,MAAM,EAAE;CAGnB"}

package/dist/transports/index.d.ts

@@ -3,4 +3,5 @@ export { ConsoleTransport } from './ConsoleTransport.js';
 export { FileTransport, type FileTransportOptions } from './FileTransport.js';
 export { HttpTransport, type HttpTransportOptions } from './HttpTransport.js';
 export { OtlpTransport, type OtlpTransportOptions } from './OtlpTransport.js';
+export { OtlpTraceTransport, type OtlpTraceTransportOptions } from './OtlpTraceTransport.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/transports/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/transports-module.d.ts

@@ -1,10 +1,12 @@
 /**
  * @fileoverview Entry point for ./transports subpath.
- * Transport classes: FileTransport, HttpTransport, OtlpTransport, ConsoleTransport.
+ * Transport classes: FileTransport, HttpTransport, OtlpTransport,
+ * OtlpTraceTransport, ConsoleTransport.
  */
 export { TransportManager } from './transports/index.js';
 export { ConsoleTransport } from './transports/index.js';
 export { FileTransport, type FileTransportOptions } from './transports/index.js';
 export { HttpTransport, type HttpTransportOptions } from './transports/index.js';
 export { OtlpTransport, type OtlpTransportOptions } from './transports/index.js';
+export { OtlpTraceTransport, type OtlpTraceTransportOptions } from './transports/index.js';
 //# sourceMappingURL=transports-module.d.ts.map

package/dist/transports-module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports-module.d.ts","sourceRoot":"","sources":["../src/transports-module.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"transports-module.d.ts","sourceRoot":"","sources":["../src/transports-module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/transports.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_transports = require("./chunks/transports-COPWmlF1.cjs");
+const require_transports = require("./chunks/transports-BZ-Mc2IT.cjs");
 exports.ConsoleTransport = require_transports.ConsoleTransport;
 exports.FileTransport = require_transports.FileTransport;
 exports.HttpTransport = require_transports.HttpTransport;
+exports.OtlpTraceTransport = require_transports.OtlpTraceTransport;
 exports.OtlpTransport = require_transports.OtlpTransport;
 exports.TransportManager = require_transports.TransportManager;

package/dist/transports.js

@@ -1,2 +1,2 @@
-import { a as ConsoleTransport, i as FileTransport, n as OtlpTransport, r as HttpTransport, t as TransportManager } from "./chunks/transports-BiDk345e.js";
-export { ConsoleTransport, FileTransport, HttpTransport, OtlpTransport, TransportManager };
+import { a as FileTransport, i as HttpTransport, n as OtlpTraceTransport, o as ConsoleTransport, r as OtlpTransport, t as TransportManager } from "./chunks/transports-DvaLAeGJ.js";
+export { ConsoleTransport, FileTransport, HttpTransport, OtlpTraceTransport, OtlpTransport, TransportManager };