lograil 0.1.0

package/dist/esm/context/async-context.d.ts

@@ -0,0 +1,10 @@
+export type AmbientContext = Record<string, unknown>;
+export declare const asyncContext: {
+    run<T>(fn: () => T, context: AmbientContext): T;
+    runAsync<T>(fn: () => Promise<T>, context: AmbientContext): Promise<T>;
+    get(): AmbientContext;
+    supported(): boolean;
+};
+/** Run `fn` with `context` active as the ambient logging context. */
+export declare function runWithContext<T>(fn: () => T, context: AmbientContext): T;
+//# sourceMappingURL=async-context.d.ts.map

package/dist/esm/context/async-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-context.d.ts","sourceRoot":"","sources":["../../../src/context/async-context.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAerD,eAAO,MAAM,YAAY;QACnB,CAAC,MAAM,MAAM,CAAC,WAAW,cAAc,GAAG,CAAC;aAGtC,CAAC,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,WAAW,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;WAG/D,cAAc;iBAGR,OAAO;CAGrB,CAAC;AAIF,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,CAAC,CAEzE"}

package/dist/esm/context/async-context.js

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * Ambient (request-scoped) context propagation.
+ *
+ * Built on `AsyncLocalStorage`, so a context set with {@link runWithContext}
+ * is automatically visible to **every** log call inside `fn` — including those
+ * reached after `await` — without manual plumbing. In non-Node runtimes this
+ * module is swapped for `async-context.browser.js` (via `package.json` `browser`)
+ * which is a no-op, so the API is safe to call everywhere.
+ */
+// Shared frozen empty object returned when no async store is active, so the
+// common (no ambient context) path allocates nothing on every `get()`.
+const EMPTY_AMBIENT = Object.freeze({});
+export const asyncContext = {
+    run(fn, context) {
+        return storage.run(context, fn);
+    },
+    runAsync(fn, context) {
+        return storage.run(context, fn);
+    },
+    get() {
+        return storage.getStore() ?? EMPTY_AMBIENT;
+    },
+    supported() {
+        return true;
+    },
+};
+const storage = new AsyncLocalStorage();
+/** Run `fn` with `context` active as the ambient logging context. */
+export function runWithContext(fn, context) {
+    return asyncContext.run(fn, context);
+}
+//# sourceMappingURL=async-context.js.map

package/dist/esm/context/async-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-context.js","sourceRoot":"","sources":["../../../src/context/async-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAIrD;;;;;;;;GAQG;AACH,4EAA4E;AAC5E,uEAAuE;AACvE,MAAM,aAAa,GAAmB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAExD,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,GAAG,CAAI,EAAW,EAAE,OAAuB;QACzC,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,QAAQ,CAAI,EAAoB,EAAE,OAAuB;QACvD,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAClC,CAAC;IACD,GAAG;QACD,OAAO,OAAO,CAAC,QAAQ,EAAE,IAAI,aAAa,CAAC;IAC7C,CAAC;IACD,SAAS;QACP,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAC;AAEF,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAExD,qEAAqE;AACrE,MAAM,UAAU,cAAc,CAAI,EAAW,EAAE,OAAuB;IACpE,OAAO,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC"}

package/dist/esm/context/context.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Context module.
+ *
+ * Manages structured contextual data (request id, user id, window id, etc.)
+ * that is attached to every log entry. Contexts are hierarchical:
+ * a global context provides defaults for all loggers, and child loggers
+ * can carry their own scoped context.
+ */
+export interface ContextStore {
+    /** Read the full context object. */
+    get(): Record<string, unknown>;
+    /** Set a single key. */
+    set(key: string, value: unknown): void;
+    /** Merge multiple keys at once. Returns the store for chaining. */
+    merge(values: Record<string, unknown>): ContextStore;
+    /** Remove a single key. */
+    delete(key: string): void;
+    /** Reset the store to empty. */
+    clear(): void;
+    /** Create a child store seeded with the current values. */
+    child(): ContextStore;
+}
+/**
+ * A shared, frozen empty record. Returned by `ContextStore.get()` when empty
+ * and used as the default `metadata` for every entry, so the hot path never
+ * allocates an empty object — and `freezeEntry` can recognise it as a sentinel
+ * and skip cloning/freezing entirely.
+ */
+export declare const EMPTY_RECORD: Record<string, unknown>;
+/** True when the record has no own enumerable keys. */
+export declare function isEmptyRecord(o: Record<string, unknown>): boolean;
+export declare function createContextStore(initial?: Record<string, unknown>): ContextStore;
+//# sourceMappingURL=context.d.ts.map

package/dist/esm/context/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/context/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,wBAAwB;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,mEAAmE;IACnE,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,CAAC;IACrD,2BAA2B;IAC3B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gCAAgC;IAChC,KAAK,IAAI,IAAI,CAAC;IACd,2DAA2D;IAC3D,KAAK,IAAI,YAAY,CAAC;CACvB;AAID;;;;;GAKG;AACH,eAAO,MAAM,YAAY,yBAAgB,CAAC;AAE1C,uDAAuD;AACvD,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAGjE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,CA6BlF"}

package/dist/esm/context/context.js

@@ -0,0 +1,52 @@
+/**
+ * Context module.
+ *
+ * Manages structured contextual data (request id, user id, window id, etc.)
+ * that is attached to every log entry. Contexts are hierarchical:
+ * a global context provides defaults for all loggers, and child loggers
+ * can carry their own scoped context.
+ */
+const EMPTY_CONTEXT = Object.freeze({});
+/**
+ * A shared, frozen empty record. Returned by `ContextStore.get()` when empty
+ * and used as the default `metadata` for every entry, so the hot path never
+ * allocates an empty object — and `freezeEntry` can recognise it as a sentinel
+ * and skip cloning/freezing entirely.
+ */
+export const EMPTY_RECORD = EMPTY_CONTEXT;
+/** True when the record has no own enumerable keys. */
+export function isEmptyRecord(o) {
+    for (const _k in o)
+        return false;
+    return true;
+}
+export function createContextStore(initial) {
+    let data = { ...(initial ?? {}) };
+    const store = {
+        get() {
+            // Avoid cloning (and allocating) when the store is empty — the shared
+            // frozen object can never be mutated by callers.
+            for (const _k in data)
+                return { ...data };
+            return EMPTY_CONTEXT;
+        },
+        set(key, value) {
+            data[key] = value;
+        },
+        merge(values) {
+            data = { ...data, ...values };
+            return store;
+        },
+        delete(key) {
+            delete data[key];
+        },
+        clear() {
+            data = {};
+        },
+        child() {
+            return createContextStore(data);
+        },
+    };
+    return store;
+}
+//# sourceMappingURL=context.js.map

package/dist/esm/context/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/context/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAA4B,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C,uDAAuD;AACvD,MAAM,UAAU,aAAa,CAAC,CAA0B;IACtD,KAAK,MAAM,EAAE,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACjC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAiC;IAClE,IAAI,IAAI,GAA4B,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;IAE3D,MAAM,KAAK,GAAiB;QAC1B,GAAG;YACD,sEAAsE;YACtE,iDAAiD;YACjD,KAAK,MAAM,EAAE,IAAI,IAAI;gBAAE,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;YAC1C,OAAO,aAAa,CAAC;QACvB,CAAC;QACD,GAAG,CAAC,GAAG,EAAE,KAAK;YACZ,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACpB,CAAC;QACD,KAAK,CAAC,MAAM;YACV,IAAI,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,CAAC,GAAG;YACR,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;QACD,KAAK;YACH,IAAI,GAAG,EAAE,CAAC;QACZ,CAAC;QACD,KAAK;YACH,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/esm/context/index.d.ts

@@ -0,0 +1,3 @@
+export * from './context.js';
+export * from './async-context.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}

package/dist/esm/context/index.js

@@ -0,0 +1,3 @@
+export * from './context.js';
+export * from './async-context.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/context/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}

package/dist/esm/core/entry.d.ts

@@ -0,0 +1,30 @@
+import type { LogEntry } from '../types.js';
+/**
+ * An entry that has crossed the immutability boundary: the entry itself and its
+ * `context`, `metadata` and `args` containers are frozen. Nested values are
+ * intentionally NOT deep-frozen (that would defeat the zero-copy goal) and must
+ * be treated as immutable by convention.
+ */
+export type FrozenLogEntry = Readonly<LogEntry> & {
+    readonly context: Readonly<Record<string, unknown>>;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly args: readonly unknown[];
+};
+/**
+ * Freeze a {@link LogEntry} at its transport boundary so it can be shared by
+ * reference (zero-copy) across all transports, plugins and formatters without
+ * any of them being able to mutate it.
+ *
+ * Behaviour:
+ * - The entry and its `context` / `metadata` / `args` containers are frozen.
+ * - When `context` is the logger's *live* ambient context (not already a frozen,
+ *   safe object) it is first copied into a fresh frozen snapshot. This prevents
+ *   us from freezing the logger's shared state and ensures an already-emitted
+ *   entry can never be mutated by a later `setContext`.
+ * - It is a no-op (and idempotent) when the entry is already frozen.
+ *
+ * Nested values are left unfrozen on purpose: deep-freezing a potentially large
+ * object graph on every log call would erase the zero-copy performance benefit.
+ */
+export declare function freezeEntry<T extends LogEntry>(entry: T): T & FrozenLogEntry;
+//# sourceMappingURL=entry.d.ts.map

package/dist/esm/core/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../../src/core/entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG;IAChD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,cAAc,CAiB5E"}

package/dist/esm/core/entry.js

@@ -0,0 +1,34 @@
+import { EMPTY_RECORD } from '../context/context.js';
+/**
+ * Freeze a {@link LogEntry} at its transport boundary so it can be shared by
+ * reference (zero-copy) across all transports, plugins and formatters without
+ * any of them being able to mutate it.
+ *
+ * Behaviour:
+ * - The entry and its `context` / `metadata` / `args` containers are frozen.
+ * - When `context` is the logger's *live* ambient context (not already a frozen,
+ *   safe object) it is first copied into a fresh frozen snapshot. This prevents
+ *   us from freezing the logger's shared state and ensures an already-emitted
+ *   entry can never be mutated by a later `setContext`.
+ * - It is a no-op (and idempotent) when the entry is already frozen.
+ *
+ * Nested values are left unfrozen on purpose: deep-freezing a potentially large
+ * object graph on every log call would erase the zero-copy performance benefit.
+ */
+export function freezeEntry(entry) {
+    if (Object.isFrozen(entry))
+        return entry;
+    const ctx = entry.context;
+    const meta = entry.metadata;
+    entry.context =
+        ctx === EMPTY_RECORD || Object.isFrozen(ctx) ? ctx : Object.freeze({ ...ctx });
+    // Skip cloning/freezing when empty: the shared `EMPTY_RECORD` sentinel is
+    // already frozen and reused by reference, so the common (no-metadata) path
+    // allocates nothing here.
+    entry.metadata =
+        meta === EMPTY_RECORD || Object.isFrozen(meta) ? meta : Object.freeze({ ...meta });
+    if (!Object.isFrozen(entry.args))
+        Object.freeze(entry.args);
+    return Object.freeze(entry);
+}
+//# sourceMappingURL=entry.js.map

package/dist/esm/core/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../src/core/entry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAcrD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAqB,KAAQ;IACtD,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAA2B,CAAC;IAE/D,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;IAC1B,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC;IAC3B,KAA8C,CAAC,OAAO;QACrD,GAAG,KAAK,YAAY,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;IAEjF,0EAA0E;IAC1E,2EAA2E;IAC3E,0BAA0B;IACzB,KAA+C,CAAC,QAAQ;QACvD,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IAErF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAE5D,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAuB,CAAC;AACpD,CAAC"}

package/dist/esm/core/index.d.ts

@@ -0,0 +1,7 @@
+export * from './level.js';
+export * from './logger.js';
+export * from './entry.js';
+export * from './printf.js';
+export { Pipeline } from '../pipeline/pipeline.js';
+export type { PipelineOptions } from '../pipeline/pipeline.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/esm/core/index.js

@@ -0,0 +1,6 @@
+export * from './level.js';
+export * from './logger.js';
+export * from './entry.js';
+export * from './printf.js';
+export { Pipeline } from '../pipeline/pipeline.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/esm/core/level.d.ts

@@ -0,0 +1,12 @@
+import type { LogLevelName, LogLevelValue, LogLevelInput } from '../types.js';
+import { LOG_LEVELS } from '../types.js';
+export { LOG_LEVELS };
+export type { LogLevelName, LogLevelValue, LogLevelInput };
+/**
+ * Resolve a level name from a numeric value, falling back to the closest
+ * lower-known level when the exact value is not registered.
+ */
+export declare function levelNameFromValue(value: LogLevelValue): LogLevelName;
+export declare function compareLevel(a: LogLevelInput, b: LogLevelInput): number;
+export declare function isLevelEnabled(configured: LogLevelInput, candidate: LogLevelInput): boolean;
+//# sourceMappingURL=level.d.ts.map

package/dist/esm/core/level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"level.d.ts","sourceRoot":"","sources":["../../../src/core/level.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAkB,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAWrE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM,CAEvE;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,GAAG,OAAO,CAE3F"}

package/dist/esm/core/level.js

@@ -0,0 +1,25 @@
+import { LOG_LEVELS, normalizeLevel } from '../types.js';
+export { LOG_LEVELS };
+/**
+ * Resolve a level name from a numeric value, falling back to the closest
+ * lower-known level when the exact value is not registered.
+ */
+export function levelNameFromValue(value) {
+    let best = 'trace';
+    let bestValue = -Infinity;
+    for (const name of Object.keys(LOG_LEVELS)) {
+        const lv = LOG_LEVELS[name];
+        if (lv <= value && lv > bestValue) {
+            best = name;
+            bestValue = lv;
+        }
+    }
+    return best;
+}
+export function compareLevel(a, b) {
+    return normalizeLevel(a) - normalizeLevel(b);
+}
+export function isLevelEnabled(configured, candidate) {
+    return normalizeLevel(candidate) >= normalizeLevel(configured);
+}
+//# sourceMappingURL=level.js.map

package/dist/esm/core/level.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"level.js","sourceRoot":"","sources":["../../../src/core/level.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,UAAU,EAAE,CAAC;AAItB;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAoB;IACrD,IAAI,IAAI,GAAiB,OAAO,CAAC;IACjC,IAAI,SAAS,GAAG,CAAC,QAAQ,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAmB,EAAE,CAAC;QAC7D,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,EAAE,IAAI,KAAK,IAAI,EAAE,GAAG,SAAS,EAAE,CAAC;YAClC,IAAI,GAAG,IAAI,CAAC;YACZ,SAAS,GAAG,EAAE,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,CAAgB,EAAE,CAAgB;IAC7D,OAAO,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,UAAyB,EAAE,SAAwB;IAChF,OAAO,cAAc,CAAC,SAAS,CAAC,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC;AACjE,CAAC"}

package/dist/esm/core/logger.d.ts

@@ -0,0 +1,271 @@
+import type { LogEntry, LogFn, LoggerMethods, LogLevelInput } from '../types.js';
+import type { RuntimeAdapter } from '../runtime/index.js';
+import type { PipelineOptions } from '../pipeline/pipeline.js';
+import { Pipeline } from '../pipeline/pipeline.js';
+import type { Transport } from '../transport/transport.js';
+import type { Plugin } from '../plugin/index.js';
+import { PluginManager } from '../plugin/index.js';
+import type { ContextStore } from '../context/index.js';
+/** Where in the pipeline an internal error originated. */
+export type LoggerErrorPhase = 'filter' | 'process' | 'plugin' | 'formatter' | 'transport';
+/** Context passed to {@link LoggerErrorHandler} when the logger catches an internal error. */
+export interface LoggerErrorInfo {
+    phase: LoggerErrorPhase;
+    /** The entry being processed when the error occurred, if available. */
+    entry?: LogEntry;
+    /** Name of the offending plugin/transport, when applicable. */
+    source?: string;
+}
+/**
+ * Global error handler. The logger never throws from a `log.*` call; when an
+ * internal step (filter, processor, plugin, formatter, transport) fails, the
+ * error is reported here instead of crashing the caller. By default it is
+ * printed to the native `console.error` (which is *not* the redirected one, so
+ * it cannot recurse into the logger).
+ */
+export type LoggerErrorHandler = (error: unknown, info: LoggerErrorInfo) => void;
+export interface LoggerOptions {
+    /** Minimum level to emit. Default `info`. */
+    level?: LogLevelInput;
+    /**
+     * Global handler for internal errors (a throwing filter/processor/plugin, a
+     * failing formatter, or a broken transport). When omitted, errors are printed
+     * to the native `console.error`. The logger never rethrows them.
+     */
+    onError?: LoggerErrorHandler;
+    /**
+     * Maximum time (ms) to wait for an async `Transport.write` before treating it
+     * as failed (reported via the transport's `onError` / the global handler), so
+     * a stalled sink can never hang `flush()`/`destroy()`. Default `5000`.
+     */
+    writeTimeoutMs?: number;
+    /**
+     * Maximum time (ms) to spend flushing on process exit (`beforeExit`,
+     * `SIGINT`, `SIGTERM`) before giving up and letting the process exit, so a
+     * stalled transport flush can never hang shutdown. Default `2000`.
+     */
+    exitFlushTimeoutMs?: number;
+    /** Optional scope / namespace for this logger. */
+    scope?: string;
+    /** Runtime adapter. Auto-detected when omitted. */
+    runtime?: RuntimeAdapter;
+    /** Initial context store. */
+    context?: ContextStore;
+    /** Transports. Defaults to the runtime's default transports. */
+    transports?: Transport[];
+    /** Pipeline configuration or instance. */
+    pipeline?: Pipeline | PipelineOptions;
+    /** Shared plugin manager. Internal: used by {@link scope}. */
+    plugins?: PluginManager;
+    /**
+     * Register `beforeExit` / `SIGINT` / `SIGTERM` handlers that flush the logger
+     * before the process exits (`SIGINT`/`SIGTERM` then terminate the process).
+     * Only effective in Node; ignored elsewhere. See {@link attachExitHandlers}.
+     */
+    autoFlushOnExit?: boolean;
+    /**
+     * Environment variable (name) whose value, if set to a valid level name,
+     * overrides `level`. Defaults to `"LOG_LEVEL"`. Set to `null` to disable.
+     */
+    levelEnvVar?: string | null;
+    /**
+     * Scope/namespace filter. A comma- or space-separated list of glob patterns
+     * (with `*` wildcards); a leading `-` excludes. Only entries whose `scope`
+     * matches are emitted. Read automatically from `namespaceEnvVar` when omitted.
+     */
+    namespaceFilter?: string | string[];
+    /**
+     * Environment variable whose value supplies the namespace filter when
+     * `namespaceFilter` is not set. Defaults to `"LOGRAIL_DEBUG"`. Set to `null`
+     * to disable.
+     */
+    namespaceEnvVar?: string | null;
+}
+/**
+ * Internal options passed by `scope`/`child` to build a **lightweight** child
+ * logger. The child reuses the parent's runtime, pipeline, plugins, transports
+ * and namespace filter — it only carries its own scope and context. This avoids
+ * re-running environment reads, regex compilation and runtime detection on
+ * every derived logger (important for per-request `child({ requestId })`).
+ */
+interface ChildOptions {
+    __child: true;
+    parent: Logger;
+    scope?: string;
+    context?: ContextStore;
+    levelOverride?: number;
+}
+/**
+ * Unified logging facade. Produces {@link LogEntry} records, runs them through
+ * the {@link Pipeline} (filter + processors), lets {@link Plugin}s intercept,
+ * formats and writes them to {@link Transport}s.
+ *
+ * Instances are cheap to derive via {@link scope} or {@link child}; all
+ * children share the same transports, pipeline and plugins, but carry their own
+ * scope and context (captured from the parent at creation).
+ */
+export declare class Logger implements LoggerMethods {
+    private runtime;
+    private pipeline;
+    private plugins;
+    private transports;
+    private context;
+    private level;
+    private scopeName?;
+    private parent?;
+    private levelOverride?;
+    /**
+     * Sequences the async plugin-interception step so entries are processed in
+     * emit order. Transport writes fan out to their own per-transport queues
+     * (see `transportQueues`), so a slow/blocked transport can never stall the
+     * others or this front queue.
+     */
+    private dispatchQueue;
+    /** Independent async-write queue per transport. */
+    private transportQueues;
+    private destroyed;
+    private detachReceiver?;
+    private processHandlersAttached;
+    private errorHandlersAttached;
+    private removeProcessHandlers?;
+    private onLoggerError?;
+    private writeTimeoutMs;
+    private exitFlushTimeoutMs;
+    private _exiting;
+    private namespaceFilter?;
+    /** True for loggers created via `scope`/`child` (share the parent's plumbing). */
+    private isChild;
+    /** Cached peer process level. When set, takes precedence over local `level` in `getLevel()`. */
+    private peerLevel?;
+    /** Original local level before any peer command modifies it. Restored on destroy. */
+    private originalLevel?;
+    /** Tracks whether the local level was explicitly set via setLevel(). */
+    private hasExplicitLocalLevel;
+    constructor(options?: LoggerOptions | ChildOptions);
+    /**
+     * Initialise a lightweight child from its parent. Reuses the parent's
+     * runtime, pipeline, plugins, transports and namespace filter, and shares the
+     * parent's error handler config so no duplicate `onError` wiring (or duplicate
+     * IPC receiver registration) happens.
+     */
+    private initFromParent;
+    /**
+     * Feed an externally produced {@link LogEntry} (e.g. received from a renderer
+     * process over IPC) into the pipeline/transports. Subject to the configured
+     * level and plugins, then written via the active transports.
+     */
+    ingestEntry(entry: LogEntry): void;
+    getLevel(): number;
+    setLevel(level: LogLevelInput): void;
+    /**
+     * Register a callback invoked when a cross-process level command is received
+     * (e.g. from a renderer, worker, or cluster peer). Called automatically by
+     * the runtime when {@link RuntimeAdapter.onLevelCommand} is wired up; most
+     * users should not call this directly.
+     */
+    setOnLevelCommand(cb: (level: number) => void): void;
+    setContext(key: string, value: unknown): void;
+    mergeContext(values: Record<string, unknown>): void;
+    addTransport(transport: Transport): void;
+    removeTransport(name: string): void;
+    /** Unregister a plugin by name at runtime. */
+    unregisterPlugin(name: string): void;
+    /** Whether a plugin with the given name is currently registered. */
+    hasPlugin(name: string): boolean;
+    /** Access the processing pipeline to add/remove filters & processors or change the formatter at runtime. */
+    getPipeline(): Pipeline;
+    /** Build the {@link PluginContext} handed to plugins so they can reconfigure the logger. */
+    private buildPluginContext;
+    getTransports(): readonly Transport[];
+    use(plugin: Plugin): Promise<void>;
+    /**
+     * Derive a scoped child logger. The child shares this logger's transports,
+     * pipeline, plugins and runtime, inherits its scope (joined with `:`) and
+     * context (captured from the parent at creation), and may carry extra
+     * context. The level is inherited live from the parent (see {@link child})
+     * unless overridden via `setLevel`.
+     *
+     * Construction is lightweight: no environment reads, regex compilation or
+     * runtime detection is performed — the child reuses this logger's plumbing.
+     */
+    scope(scope: string, context?: Record<string, unknown>): Logger;
+    /**
+     * Derive a child logger that shares this logger's transports, pipeline,
+     * plugins and runtime. The child:
+     * - merges `options.context` on top of the parent's context (captured at
+     *   creation),
+     * - inherits the parent's scope,
+     * - inherits the parent's level live, unless `options.level` overrides it
+     *   (the override also applies to any further descendants).
+     *
+     * This is the canonical "child logger" (à la `pino.child`), ideal for
+     * per-request context such as `logger.child({ requestId: id })`. Construction
+     * is lightweight — see {@link scope}.
+     */
+    child(options?: {
+        context?: Record<string, unknown>;
+        level?: LogLevelInput;
+    }): Logger;
+    trace: LogFn;
+    debug: LogFn;
+    info: LogFn;
+    warn: LogFn;
+    error: LogFn;
+    fatal: LogFn;
+    private emit;
+    /**
+     * Route a processed entry to the transports. When no plugin intercepts
+     * entries we can write synchronously and skip the per-call Promise + write
+     * queue entirely (the common case); the async path is only used when a plugin
+     * hook or an async transport needs it.
+     */
+    private dispatch;
+    /**
+     * Report an internal error without throwing. Routes to the user-supplied
+     * `onError` handler, falling back to the native `console.error` (deliberately
+     * not the redirected one, to avoid recursion).
+     */
+    private reportError;
+    private buildEntry;
+    private writeToTransports;
+    /** Await a transport's async `write`, but never let it stall the queue. */
+    private guardWrite;
+    /** Await a transport's async `flush`, but never let it stall teardown. */
+    private guardFlush;
+    /** Surface a transport failure via the transport's hook, else the global handler. */
+    private reportTransportError;
+    flush(): Promise<void>;
+    /**
+     * Flush, but never wait longer than `ms`. Resolves (does not reject) once the
+     * flush settles or the timeout elapses, so callers can always proceed (e.g.
+     * exit the process) without risking a hang on a stalled transport.
+     */
+    private flushWithTimeout;
+    /** Set the max time (ms) to flush on process exit before giving up. */
+    setExitFlushTimeout(ms: number): this;
+    /** Get the current exit-flush timeout (ms). */
+    getExitFlushTimeout(): number;
+    /**
+     * Register `beforeExit` / `SIGINT` / `SIGTERM` handlers that flush the logger
+     * before the process leaves. On `SIGINT` / `SIGTERM` the process exits (130 /
+     * 143) after the flush completes. No-op outside Node. Idempotent.
+     */
+    attachExitHandlers(): void;
+    /**
+     * Forward `uncaughtException` and `unhandledRejection` to the logger (at
+     * `fatal` level) and exit afterwards, so crashes are recorded before the
+     * process dies. No-op outside Node. Idempotent.
+     */
+    watchUncaughtErrors(): void;
+    /**
+     * Route `console.*` calls through this logger, so third-party `console.log`
+     * output is captured into the structured pipeline. The native console output
+     * is suppressed for those calls (the logger's own transports produce the
+     * visible output); if logging throws, the native console is used as a
+     * fallback. Returns a function that restores the original `console`.
+     */
+    redirectConsole(): () => void;
+    destroy(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/esm/core/logger.d.ts.map

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