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

package/dist/types/serializers.d.ts

@@ -1,20 +1,92 @@
+/**
+ * Función de serialización registrada para un tipo específico de valor.
+ *
+ * Recibe el valor a serializar y un {@link SerializerContext} con el estado
+ * del recorrido (profundidad, camino de claves, set de objetos ya vistos para
+ * detectar ciclos). Devuelve una representación segura para logs / JSON —
+ * normalmente un plain object o un primitivo que `JSON.stringify` pueda emitir
+ * sin perder información ni lanzar sobre estructuras profundas.
+ *
+ * @typeParam T - Tipo del valor que este serializer sabe manejar.
+ * @param value - Instancia a serializar.
+ * @param context - Estado del recorrido (depth, path, seen).
+ * @returns Representación serializable del valor de entrada.
+ *
+ * @example
+ * // Serializer para `Error` que aplana los campos relevantes
+ * const errorSerializer: SerializerFn<Error> = (err) => ({
+ *   name: err.name,
+ *   message: err.message,
+ *   stack: err.stack
+ * });
+ */
 export type SerializerFn<T = any> = (value: T, context: SerializerContext) => any;
+/**
+ * Estado de recorrido que el {@link ISerializerRegistry} pasa a cada
+ * {@link SerializerFn} durante la serialización de un valor.
+ *
+ * Permite que los serializers personalizados respeten `maxDepth`, reconozcan
+ * su posición dentro del grafo de objetos y participen de la detección de
+ * referencias circulares.
+ *
+ * @property depth - Profundidad actual dentro del grafo (raíz = 0).
+ * @property maxDepth - Profundidad máxima permitida antes de truncar.
+ * @property path - Camino de claves desde la raíz hasta el nodo actual.
+ * @property seen - `WeakSet` de objetos ya visitados, para detectar ciclos.
+ */
 export interface SerializerContext {
     depth: number;
     maxDepth: number;
     path: string[];
     seen: WeakSet<object>;
 }
+/**
+ * Entrada del registry que asocia un constructor con su {@link SerializerFn}
+ * y la prioridad con la que fue registrado.
+ *
+ * Cuando varios serializers matchean por jerarquía (p.ej. `TypeError` vs
+ * `Error`), gana el de `priority` más alta; en empate gana el registrado más
+ * tarde. Devuelto por {@link ISerializerRegistry.getAll} para inspección y
+ * depuración del orden de resolución.
+ */
 export interface SerializerEntry<T = any> {
     type: new (...args: any[]) => T;
     serializer: SerializerFn<T>;
     priority: number;
 }
+/**
+ * Opciones de serialización pasadas a {@link ISerializerRegistry.serialize}.
+ *
+ * @property maxDepth - Profundidad máxima antes de truncar el subárbol con un placeholder. Toma el default del registry si se omite.
+ * @property circular - Estrategia ante referencias circulares:
+ *   - `'error'` — lanza al detectar un ciclo.
+ *   - `'skip'` — omite el campo circular del output.
+ *   - `'placeholder'` — reemplaza el ciclo por `'[Circular]'` (default).
+ * @property preserveUndefined - Si mantener `undefined` (en lugar de omitirlo). Por compatibilidad con JSON, default `false`.
+ */
 export interface SerializerConfig {
     maxDepth?: number;
     circular?: 'error' | 'skip' | 'placeholder';
     preserveUndefined?: boolean;
 }
+/**
+ * Contrato del registry de serializers por tipo.
+ *
+ * Mantiene una tabla de constructors → {@link SerializerFn} con prioridades,
+ * y expone `serialize()` para transformar valores arbitrarios (`Error`,
+ * `Date`, `Map`, `Set`, tipos custom del dominio) en representaciones
+ * seguras para logs y para `JSON.stringify`.
+ *
+ * La resolución recorre la cadena de prototipos del valor y aplica el
+ * serializer más específico registrado; si nadie matchea, cae al serializer
+ * por defecto (JSON-safe).
+ *
+ * @example
+ * const registry: ISerializerRegistry = createRegistry();
+ * registry.add(Error, (e: Error) => ({ name: e.name, message: e.message }), 10);
+ * registry.serialize(new TypeError('boom'));
+ * // → { name: 'TypeError', message: 'boom' }  (TypeError hereda de Error)
+ */
 export interface ISerializerRegistry {
     add<T>(type: new (...args: any[]) => T, serializer: SerializerFn<T>, priority?: number): void;
     remove<T>(type: new (...args: any[]) => T): boolean;

package/dist/types/serializers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializers.d.ts","sourceRoot":"","sources":["../../src/types/serializers.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,KAAK,GAAG,CAAC;AAElF,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,GAAG;IACpC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAChC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC;IAC5C,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAChC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9F,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC;IACpD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC;IACjD,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,GAAG,CAAC;IACtD,MAAM,IAAI,eAAe,EAAE,CAAC;CAC/B"}
+{"version":3,"file":"serializers.d.ts","sourceRoot":"","sources":["../../src/types/serializers.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,KAAK,GAAG,CAAC;AAElF;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,GAAG;IACpC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAChC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,aAAa,CAAC;IAC5C,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,mBAAmB;IAChC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9F,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC;IACpD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC;IACjD,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,GAAG,CAAC;IACtD,MAAM,IAAI,eAAe,EAAE,CAAC;CAC/B"}

package/dist/types/transports.d.ts

@@ -1,20 +1,20 @@
 import type { LogLevel, LogTag } from './core.js';
 /**
- * Map a `LogLevel` to the OpenTelemetry numeric severity (1-24) used by
- * SigNoz / any OTLP/HTTP backend. Spec-compliant banded values:
- *   TRACE=1-4, DEBUG=5-8, INFO=9-12, WARN=13-16, ERROR=17-20, FATAL=21-24
- * We use the canonical mid-band value per level.
+ * Mapea un `LogLevel` a la severidad numérica de OpenTelemetry (1-24) usada
+ * por SigNoz / cualquier backend OTLP/HTTP. Valores por banda conformes a la
+ * spec: TRACE=1-4, DEBUG=5-8, INFO=9-12, WARN=13-16, ERROR=17-20, FATAL=21-24.
+ * Se usa el valor canónico del medio de cada banda.
  *
  * @see https://opentelemetry.io/docs/specs/otel/logs/data-model/#severity-fields
  */
 export declare const LOG_LEVEL_TO_SEVERITY_NUMBER: Record<LogLevel, number>;
 /**
- * Map a `LogLevel` to its OpenTelemetry severity name (uppercase, OTel spec).
+ * Mapea un `LogLevel` a su nombre de severidad OpenTelemetry (mayúsculas, spec OTel).
  */
 export declare const LOG_LEVEL_TO_SEVERITY_TEXT: Record<LogLevel, string>;
 /**
- * OTel resource attributes attached once per batch (service.name, version, env, ...).
- * Values are string-coerced by the transport layer.
+ * Atributos de recurso OTel adjuntados una vez por batch (service.name, version,
+ * env, ...). Los valores son string-coerced por la capa de transport.
  */
 export interface ILogResource {
     'service.name': string;
@@ -23,71 +23,178 @@ export interface ILogResource {
     [key: string]: string | undefined;
 }
 /**
- * Structured attribute bag (OpenTelemetry-compatible). Every key maps to
- * a typed value; the transport layer decides how to serialise it.
+ * Valor admitido en un {@link ILogAttributes}: unión recursiva de primitivos
+ * serializables (string, number, boolean, null), arrays y structs anidados.
+ * Compatible con el modelo de attribute value de OpenTelemetry.
  */
 export type LogAttributeValue = string | number | boolean | null | LogAttributeValue[] | {
     [k: string]: LogAttributeValue;
 };
+/**
+ * Bag estructurado de atributos (compatible con OpenTelemetry). Cada clave
+ * mapea a un valor tipado; la capa de transport decide cómo serializarlo.
+ */
 export interface ILogAttributes {
     [key: string]: LogAttributeValue;
 }
 /**
- * The payload sent to every transport on each `log()` call. Fields are
- * deliberately explicit (no `[key: string]: any` safety hatch) so transport
- * implementations like `OtlpTransport` can map 1:1 to OTLP `logRecords`.
+ * Payload enviado a cada transport en cada llamada a `log()`. Los campos son
+ * deliberadamente explícitos (sin escape hatch `[key: string]: any`) para que
+ * implementaciones como `OtlpTransport` puedan mapear 1:1 a `logRecords` OTLP.
  */
 export interface TransportRecord {
-    /** Canonical log level (trace/debug/info/warn/error/critical). */
+    /** Nivel canónico (trace/debug/info/warn/error/critical). */
     level: LogLevel;
-    /** Numeric severity, copied from `LOG_LEVELS[level]`. */
+    /** Severidad numérica, copiada de `LOG_LEVELS[level]`. */
     levelValue: number;
-    /** OTel numeric severity (1-24). Set automatically by Logger. */
+    /** Severidad numérica OTel (1-24). La asigna automáticamente el Logger. */
     severityNumber: number;
-    /** OTel severity name (TRACE/DEBUG/INFO/WARN/ERROR/FATAL). */
+    /** Nombre de severidad OTel (TRACE/DEBUG/INFO/WARN/ERROR/FATAL). */
     severityText: string;
-    /** Epoch milliseconds at log time. */
+    /** Epoch milliseconds en el momento del log. */
     time: number;
-    /** Final, post-hook message text. */
+    /** Texto final del mensaje, ya procesado por los hooks. */
     msg: string;
-    /** Optional logical scope (e.g. "Auth", "API:Users"). */
+    /** Scope lógico opcional (p.ej. "Auth", "API:Users"). */
     prefix?: string;
-    /** Caller location, only when `enableStackTrace` is true. */
+    /** Ubicación del caller, solo cuando `enableStackTrace` es true. */
     location?: {
         file: string;
         line: number;
         column: number;
         function?: string;
     };
-    /** 32-char hex trace id (OTel), when correlated with an active span. */
+    /** Trace id hex de 32 chars (OTel), cuando hay correlación con un span activo. */
     traceId?: string;
-    /** 16-char hex span id (OTel), when correlated with an active span. */
+    /** Span id hex de 16 chars (OTel), cuando hay correlación con un span activo. */
     spanId?: string;
-    /** Structured attributes (requestId, userId, custom tags). */
+    /** Atributos estructurados (requestId, userId, tags custom). */
     attributes?: ILogAttributes;
-    /** Per-log resource (overrides Transport-level resource). */
+    /** Recurso a nivel de log (sobreescribe el resource del transport). */
     resource?: Partial<ILogResource>;
-    /** Special "success" tag — set by `Logger.success()`. */
+    /** Tag especial "success" — lo setea `Logger.success()`. */
     tag?: LogTag;
 }
 /**
- * Options accepted by any transport at registration time.
+ * Kind de record que circula por el pipeline de transports. Los transports
+ * declaran cuáles aceptan vía {@link ITransport.accepts}; el
+ * {@link ITransportManager} enruta cada record solo a los transports cuyo
+ * `accepts` lo incluye.
+ */
+export type TransportRecordKind = 'log' | 'span';
+/**
+ * Valor admitido en los attributes de un {@link SpanRecord}. Deliberadamente
+ * más estrecho que {@link LogAttributeValue}: el JSON mapping de OTLP traces
+ * solo acepta primitivos en `span.attributes` sin schema extra.
+ */
+export type SpanAttributeValue = string | number | boolean;
+/**
+ * Bag de attributes de un span (compatible con el modelo de attributes de
+ * OpenTelemetry para traces).
+ */
+export interface SpanAttributes {
+    [key: string]: SpanAttributeValue;
+}
+/**
+ * Status de finalización de un span, conforme al proto OTel `Status`.
+ * `code: 2` = `STATUS_CODE_ERROR`.
+ *
+ * @see https://opentelemetry.io/docs/specs/otel/trace/api/#set-status
+ */
+export interface SpanStatus {
+    code: number;
+    message?: string;
+}
+/**
+ * Record de span (trace) que emite el trio API `event`/`span`/`startSpan`.
+ * A diferencia de {@link TransportRecord}, NO atraviesa el hook path de logs:
+ * el {@link ITransportManager} lo despacha solo a transports cuyo
+ * {@link ITransport.accepts} incluye `'span'`.
+ *
+ * `traceId` son 16 bytes en hex (32 chars) y `spanId` 8 bytes en hex
+ * (16 chars), conforme a la spec W3C Trace Context que exige OTLP/HTTP.
+ */
+export interface SpanRecord {
+    kind: 'span';
+    /** Trace id hex de 32 chars. Se hereda del span activo si existe. */
+    traceId: string;
+    /** Span id hex de 16 chars. */
+    spanId: string;
+    /** Span id del padre, tomado del span activo en el ALS al crearse. */
+    parentSpanId?: string;
+    /** Nombre de la operación (`db.query`, `http.request`, ...). */
+    name: string;
+    /** Span kind OTel numérico. 1 = SPAN_KIND_INTERNAL. */
+    spanKind: number;
+    /** Instante de inicio en nanosegundos (string decimal). */
+    startTimeUnixNano: string;
+    /** Instante de fin en nanosegundos (string decimal). `'0'` hasta end(). */
+    endTimeUnixNano: string;
+    /** Attributes del span. Mutables vía {@link Span.set} hasta el end(). */
+    attributes: SpanAttributes;
+    /** Status de finalización. Presente si el span terminó con `fail()`. */
+    status?: SpanStatus;
+    /** `true` cuando el span se cerró por flush sin `end()` explícito. */
+    incomplete?: boolean;
+    /** Scope del logger que emitió el span (nombre del scoped logger). */
+    scope: string;
+}
+/**
+ * Handle de un span externally-ended. Lo devuelven `startSpan()` y el
+ * callback de `span(fn)`.
+ */
+export interface Span {
+    /**
+     * Añade o actualiza un attribute del span.
+     *
+     * @param key - Nombre del attribute.
+     * @param value - Valor primitivo (string | number | boolean).
+     * @returns `this`, para encadenar.
+     */
+    set(key: string, value: SpanAttributeValue): this;
+    /**
+     * Finaliza el span: fija `endTimeUnixNano` y encola el
+     * {@link SpanRecord} para export. Llamadas posteriores son no-op.
+     *
+     * @param attributes - Attributes finales a mergear antes del export.
+     */
+    end(attributes?: SpanAttributes): void;
+    /**
+     * Marca el span como fallido (`status.code = 2` con el mensaje del
+     * error) y luego lo finaliza como {@link end}.
+     *
+     * @param err - Error (o valor) que causó el fallo.
+     */
+    fail(err: unknown): void;
+    /** Trace id hex de 32 chars del span. */
+    readonly traceId: string;
+    /** Span id hex de 16 chars del span. */
+    readonly spanId: string;
+}
+/**
+ * Unión de todo record que puede atravesar el {@link ITransportManager}:
+ * un log ({@link TransportRecord}) o un span ({@link SpanRecord}).
+ * El routing por kind lo hace el manager vía {@link ITransport.accepts}.
+ */
+export type TransportDispatchRecord = TransportRecord | SpanRecord;
+/**
+ * Opciones aceptadas por cualquier transport al registrarse.
  */
 export interface TransportOptions {
     level?: LogLevel;
-    /** Transform the record before it's serialised. Return null to drop. */
+    /** Transforma el record antes de serializarlo. Devolver null descarta el record. */
     transform?: (record: TransportRecord) => TransportRecord | null;
-    /** Flush once the buffer reaches this many records. */
+    /** Flush cuando el buffer alcanza esta cantidad de records. */
     batchSize?: number;
-    /** Flush periodically at this interval (ms). */
+    /** Flush periódico a este intervalo (ms). */
     flushInterval?: number;
-    /** Hard cap on buffered records. Older entries are dropped on overflow. */
+    /** Tope duro de records en buffer. Los más antiguos se descartan al desbordar. */
     maxBufferSize?: number;
 }
 /**
- * A transport registration. `target` can be:
- *   - An `ITransport` instance (legacy / inline).
- *   - A string registered in `TransportManager`'s built-in registry
+ * Registro de un transport. `target` puede ser:
+ *   - Una instancia de `ITransport` (legacy / inline).
+ *   - Un string registrado en el registry built-in de `TransportManager`
  *     (`'console' | 'file' | 'http' | 'otlp'`).
  */
 export interface TransportTarget {
@@ -96,18 +203,31 @@ export interface TransportTarget {
     level?: LogLevel;
 }
 /**
- * Minimal contract every transport must satisfy.
+ * Contrato mínimo que todo transport debe satisfacer.
+ *
+ * Un transport declara qué kinds de record acepta vía {@link accepts}:
+ * ausente o `['log']` → log-only (default, comportamiento de todos los
+ * transports históricos); `['span']` → solo spans (p.ej. `OtlpTraceTransport`);
+ * `['log', 'span']` → ambos. El {@link ITransportManager} garantiza que un
+ * transport jamás recibe un record de un kind que no declaró — un
+ * `SpanRecord` nunca llega a un transport de logs.
  */
 export interface ITransport {
     readonly name: string;
-    write(record: TransportRecord): void | Promise<void>;
+    /**
+     * Kinds de record que este transport acepta. **Default `['log']` cuando
+     * está ausente** — los transports existentes siguen siendo log-only sin
+     * cambios.
+     */
+    readonly accepts?: readonly TransportRecordKind[];
+    write(record: TransportDispatchRecord): void | Promise<void>;
     flush?(): void | Promise<void>;
     close?(): void | Promise<void>;
     isReady?(): boolean;
 }
 /**
- * Buffered transport contract. Concrete transports like `HttpTransport`,
- * `FileTransport` and `OtlpTransport` extend this.
+ * Contrato de transport con buffer. Transports concretos como `HttpTransport`,
+ * `FileTransport` y `OtlpTransport` extienden esta interfaz.
  */
 export interface IBufferedTransport extends ITransport {
     readonly bufferSize: number;
@@ -115,12 +235,16 @@ export interface IBufferedTransport extends ITransport {
     flush(): Promise<void>;
 }
 /**
- * Transport registry / dispatch contract.
+ * Contrato del registry / dispatch de transports.
  */
 export interface ITransportManager {
     add(target: TransportTarget): string;
     remove(id: string): boolean;
-    write(record: TransportRecord): Promise<void>;
+    /**
+     * Dispatcha un record (log o span) a los transports que acepten su kind
+     * y (para logs) pasen el filtro de nivel del transport.
+     */
+    write(record: TransportDispatchRecord): Promise<void>;
     flush(): Promise<void>;
     close(): Promise<void>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"transports.d.ts","sourceRoot":"","sources":["../../src/types/transports.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transports.d.ts","sourceRoot":"","sources":["../../src/types/transports.ts"],"names":[],"mappings":"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"}

package/dist/utils/ansi-colors.d.ts

@@ -1,9 +1,9 @@
 /**
- * @fileoverview ANSI color utilities for terminal environments
+ * @fileoverview Utilidades de colores ANSI para entornos de terminal
  */
 import type { LogLevel } from '../types/index.js';
 /**
- * ANSI color codes for terminal styling
+ * Códigos de color ANSI para estilos en terminal
  */
 export declare const ANSI_CODES: {
     readonly black: 30;
@@ -57,7 +57,7 @@ export declare const ANSI_CODES: {
     readonly resetStrikethrough: 29;
 };
 /**
- * ANSI color presets for different log levels
+ * Presets de colores ANSI para los distintos niveles de log
  */
 export declare const ANSI_LEVEL_STYLES: Record<LogLevel | 'success', {
     color: number;
@@ -66,50 +66,50 @@ export declare const ANSI_LEVEL_STYLES: Record<LogLevel | 'success', {
     emoji: string;
 }>;
 /**
- * Applies ANSI styling to text
+ * Aplica estilos ANSI al texto
  */
 export declare function ansiStyle(text: string, codes: number[]): string;
 /**
- * Applies color to text
+ * Aplica color al texto
  */
 export declare function ansiColor(text: string, color: number): string;
 /**
- * Applies background color to text
+ * Aplica color de fondo al texto
  */
 export declare function ansiBackground(text: string, bg: number, color?: number): string;
 /**
- * Makes text bold
+ * Pone el texto en bold
  */
 export declare function ansiBold(text: string): string;
 /**
- * Makes text dim
+ * Aplica dim al texto
  */
 export declare function ansiDim(text: string): string;
 /**
- * Underlines text
+ * Subraya el texto
  */
 export declare function ansiUnderline(text: string): string;
 /**
- * Specialized formatters for different contexts
+ * Formatters especializados para distintos contextos
  */
 /**
- * Format timestamp for terminal
+ * Formatea el timestamp para terminal
  */
 export declare function formatTimestampANSI(timestamp: string): string;
 /**
- * Format log level for terminal
+ * Formatea el nivel de log para terminal
  */
 export declare function formatLogLevelANSI(level: LogLevel, useEmojis?: boolean): string;
 /**
- * Format success message for terminal
+ * Formatea el mensaje de success para terminal
  */
 export declare function formatSuccessANSI(message: string, useEmojis?: boolean): string;
 /**
- * Format prefix for terminal
+ * Formatea el prefix para terminal
  */
 export declare function formatPrefixANSI(prefix: string): string;
 /**
- * Format file location for terminal
+ * Formatea la ubicación del archivo para terminal
  */
 export declare function formatLocationANSI(location: string): string;
 //# sourceMappingURL=ansi-colors.d.ts.map

package/dist/utils/asyncLocalStorage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Resolución compartida de `AsyncLocalStorage` — utilidad
+ * interna, NO exportada por el barrel público (`src/utils/index.ts`).
+ *
+ * Único punto de verdad para resolver `node:async_hooks` por capas. Lo
+ * consumen tanto `transports/SpanRuntime.ts` (ALS singleton de spans) como
+ * `context/LogContext.ts` (ALS singleton de MDC). Antes había dos copias de
+ * este conocimiento: una acertaba (SpanRuntime, la que sigue este archivo) y
+ * otra usaba `typeof AsyncLocalStorage !== 'undefined'` — un feature-detect
+ * roto, porque en Node y Bun el constructor NO es global, así que esa rama
+ * quedaba siempre en `undefined` y el MDC de logs era no-op silencioso fuera
+ * del browser.
+ */
+/**
+ * Forma mínima de `AsyncLocalStorage<T>` que necesita este paquete.
+ */
+export interface AsyncLocalStorageLike<T> {
+    run<R>(store: T, fn: () => R): R;
+    getStore(): T | undefined;
+}
+/**
+ * Resuelve `AsyncLocalStorage` por capas:
+ *   1. global `AsyncLocalStorage` (runtimes/polyfills que lo exponen),
+ *   2. `process.getBuiltinModule('async_hooks')` (Node >= 22.3, Bun),
+ *   3. `require('node:async_hooks')` (CJS interop),
+ *   4. `undefined` → browser estricto: sin correlación (degradación
+ *      documentada; el caller decide qué hacer sin ALS).
+ *
+ * Nota: NO basta con `typeof AsyncLocalStorage !== 'undefined'` — en Node y
+ * Bun el constructor NO es global y hay que ir a `node:async_hooks`.
+ */
+export declare function resolveAsyncLocalStorage<T>(): AsyncLocalStorageLike<T> | undefined;
+//# sourceMappingURL=asyncLocalStorage.d.ts.map

package/dist/utils/asyncLocalStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncLocalStorage.d.ts","sourceRoot":"","sources":["../../src/utils/asyncLocalStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACpC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACjC,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,KAAK,qBAAqB,CAAC,CAAC,CAAC,GAAG,SAAS,CAiClF"}

package/dist/utils/environment-detector.d.ts

@@ -1,42 +1,42 @@
 /**
- * Environment Detector - Robust environment detection for logger
- * Detects browser, terminal, server, and other runtime environments
+ * Detector de entorno — Detección robusta del entorno para el logger
+ * Detecta entornos browser, terminal, server y otros runtime
  */
 export type Environment = 'browser' | 'terminal' | 'server' | 'webworker' | 'deno' | 'unknown';
 /**
- * Checks if running in Node.js environment
+ * Comprueba si se ejecuta en entorno Node.js
  */
 export declare const isNode: string | false;
 /**
- * Checks if running in browser environment
+ * Comprueba si se ejecuta en entorno browser
  */
 export declare const isBrowser: boolean;
 /**
- * Main environment detection function
+ * Función principal de detección de entorno
  */
 export declare function getEnvironment(): Environment;
 /**
- * Check if running in an interactive terminal
+ * Comprueba si se ejecuta en una terminal interactiva
  */
 export declare function isRunningInTerminal(): boolean;
 /**
- * Check if environment supports ANSI colors
+ * Comprueba si el entorno soporta colores ANSI
  */
 export declare function supportsANSI(): boolean;
 /**
- * Get environment-specific color capability
+ * Obtiene la capacidad de color específica del entorno
  */
 export declare function getColorCapability(): 'full' | 'basic' | 'none';
 /**
- * Get terminal width in columns
+ * Obtiene el ancho de la terminal en columnas
  */
 export declare function getTerminalWidth(): number;
 /**
- * Get terminal height in rows
+ * Obtiene el alto de la terminal en filas
  */
 export declare function getTerminalHeight(): number;
 /**
- * Environment information for debugging
+ * Información del entorno para debugging
  */
 export declare function getEnvironmentInfo(): {
     environment: Environment;

package/dist/utils/formatting.d.ts

@@ -1,20 +1,20 @@
 /**
- * @fileoverview Formatting utilities for Universal Logger
+ * @fileoverview Utilidades de formatting para Universal Logger
  */
 import type { LogLevel, StackInfo } from '../types/index.js';
 export type { OutputFormat } from '../types/index.js';
 /**
- * Creates plain text output for any environment
- * No colors, no styling - maximum compatibility
+ * Crea output en texto plano para cualquier entorno
+ * Sin colores ni estilos — máxima compatibilidad
  */
 export declare function createPlainOutput(level: LogLevel, message: string, prefix?: string, stackInfo?: StackInfo | null): string;
 /**
- * Gets the appropriate log method for the level
- * Uses different console methods for better semantics
+ * Obtiene el método de console adecuado para el nivel
+ * Usa distintos métodos de console para mejor semántica
  */
 export declare function getConsoleMethod(level: LogLevel): 'log' | 'info' | 'warn' | 'error';
 /**
- * Create a simple log entry object for handlers
+ * Crea un objeto simple de log entry para los handlers
  */
 export declare function createLogEntry(level: LogLevel, message: string, args: any[], prefix?: string, stackInfo?: StackInfo | null): {
     timestamp: string;
@@ -31,11 +31,11 @@ export declare function createLogEntry(level: LogLevel, message: string, args: a
     raw: any[];
 };
 /**
- * Format data for table display in plain text
+ * Formatea datos para visualización en tabla como texto plano
  */
 export declare function formatTablePlain(data: any, columns?: string[]): string;
 /**
- * Safe object serialization for logging
+ * Serialización segura de objetos para logging
  */
 export declare function safeSerialize(obj: any, maxDepth?: number, currentDepth?: number): any;
 //# sourceMappingURL=formatting.d.ts.map