@venizia/ignis-helpers 0.1.1 → 0.2.0-0

package/dist/cjs/modules/logger/hf/flusher.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HfLogFlusher = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const promise_utility_1 = require("../../../utilities/promise.utility");
+const common_1 = require("./common");
+const ring_1 = require("./ring");
+/** Drains the ring in bounded batches, yielding between them - see the spec's lap accounting. */
+class HfLogFlusher {
+    static { this.textDecoder = new TextDecoder(); }
+    constructor(options) {
+        this.flushIndex = 0;
+        this.inFlightDrain = null;
+        this.timer = null;
+        this.sink = options?.sink ?? HfLogFlusher.buildDefaultSink(options?.filePath);
+        const batchSize = options?.batchSize ?? common_1.HF_DEFAULT_BATCH_SIZE;
+        if (!Number.isInteger(batchSize) || batchSize < 1) {
+            // console, not the Logger: this IS the drain path - routing through a logger re-enters it.
+            console.warn('[HfLogFlusher] Invalid batchSize | value: %s | fallback: %s', batchSize, common_1.HF_DEFAULT_BATCH_SIZE);
+            this.batchSize = common_1.HF_DEFAULT_BATCH_SIZE;
+        }
+        else {
+            this.batchSize = batchSize;
+        }
+    }
+    static renderEntry(ring, sequence) {
+        const offset = (sequence & (common_1.BUFFER_SIZE - 1)) * common_1.ENTRY_SIZE;
+        const bytes = ring.bytes;
+        const iso = new Date(ring.f64[offset >> 3]).toISOString();
+        const levelName = common_1.HF_LEVEL_NAMES[bytes[offset + common_1.OFFSET_LEVEL]] ?? 'info';
+        const scopeLength = bytes[offset + common_1.OFFSET_SCOPE_LENGTH];
+        const scope = HfLogFlusher.textDecoder.decode(bytes.subarray(offset + common_1.OFFSET_SCOPE, offset + common_1.OFFSET_SCOPE + scopeLength));
+        const messageLength = bytes[offset + common_1.OFFSET_MESSAGE_LENGTH];
+        const message = HfLogFlusher.textDecoder.decode(bytes.subarray(offset + common_1.OFFSET_MESSAGE, offset + common_1.OFFSET_MESSAGE + messageLength));
+        return `${iso} [${levelName}] ${scope} ${message}`;
+    }
+    static buildDefaultSink(filePath) {
+        return batch => {
+            const rendered = (batch.dropped > 0
+                ? `${new Date().toISOString()} [warn] HfLogFlusher ring lapped - ${batch.dropped} entries overwritten before they could be read\n`
+                : '') +
+                batch.lines.join('\n') +
+                '\n';
+            if (filePath) {
+                node_fs_1.default.appendFileSync(filePath, rendered);
+                return;
+            }
+            process.stdout.write(rendered);
+        };
+    }
+    flush() {
+        if (this.inFlightDrain) {
+            return this.inFlightDrain;
+        }
+        this.inFlightDrain = this.drain().finally(() => {
+            this.inFlightDrain = null;
+        });
+        return this.inFlightDrain;
+    }
+    async drain() {
+        const ring = ring_1.HfLogRing.get();
+        while (this.flushIndex < ring.writeIndex) {
+            // Lap accounting, re-checked every batch: the producer may advance during yields.
+            let dropped = 0;
+            const backlog = ring.writeIndex - this.flushIndex;
+            if (backlog > common_1.BUFFER_SIZE) {
+                dropped = backlog - common_1.BUFFER_SIZE;
+                this.flushIndex = ring.writeIndex - common_1.BUFFER_SIZE;
+            }
+            const count = Math.min(this.batchSize, ring.writeIndex - this.flushIndex);
+            const lines = [];
+            for (let index = 0; index < count; index++) {
+                lines.push(HfLogFlusher.renderEntry(ring, this.flushIndex++));
+            }
+            await this.deliverBatch({ lines, dropped });
+            if (this.flushIndex < ring.writeIndex) {
+                await new Promise(resolve => setImmediate(resolve));
+            }
+        }
+    }
+    async deliverBatch(opts) {
+        try {
+            // THfSink is typed `=> void`, but an async sink still returns a thenable at runtime - await it inside the try so its rejection is caught here, never unhandled.
+            const delivered = this.sink(opts);
+            if ((0, promise_utility_1.isPromiseLike)(delivered)) {
+                await delivered;
+            }
+        }
+        catch (error) {
+            console.error('[HfLogFlusher][drain] Sink failed | error: ', error);
+        }
+    }
+    start(intervalMs = common_1.HF_DEFAULT_FLUSH_INTERVAL_MS) {
+        this.stop();
+        this.timer = setInterval(() => {
+            this.flush().catch(error => {
+                console.error('[HfLogFlusher][start] Flush failed | error: ', error);
+            });
+        }, intervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+exports.HfLogFlusher = HfLogFlusher;
+//# sourceMappingURL=flusher.js.map

package/dist/cjs/modules/logger/hf/flusher.js.map

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

package/dist/cjs/modules/logger/hf/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/modules/logger/hf/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACpE,YAAY,EAAE,oBAAoB,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACzF,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}

package/dist/cjs/modules/logger/hf/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/modules/logger/hf/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mCAAoE;AAA3D,8GAAA,oBAAoB,OAAA;AAAE,4GAAA,kBAAkB,OAAA;AAEjD,4CAA0B;AAC1B,2CAAyB"}

package/dist/cjs/modules/logger/hf/logger.d.ts

@@ -0,0 +1,31 @@
+import { AnyType } from '../../../common/types';
+import { AbstractLogger } from '../base';
+import { ILogger, TLogLevel } from '../common';
+/** Ring-buffer logger for hot paths; extends AbstractLogger, NOT BaseLogger - BaseLogger's string-sink plumbing is exactly the cost this implementation exists to avoid. */
+export declare class HfLogger extends AbstractLogger {
+    private static readonly textEncoder;
+    private static readonly scopeCache;
+    private static cache;
+    private static messageCache;
+    private readonly scope;
+    private readonly scopeBytes;
+    private readonly scopeLength;
+    private readonly ring;
+    private constructor();
+    private static encodeScope;
+    static get(scope: string): HfLogger;
+    /** Pre-encode a message at initialization time; the cache is FIFO-bounded so dynamic strings can't grow it without limit. */
+    static encodeMessage(message: string): Uint8Array;
+    private static evictOldestMessage;
+    private writeEntry;
+    private writeString;
+    debug(message: string, ...args: AnyType[]): void;
+    info(message: string, ...args: AnyType[]): void;
+    warn(message: string, ...args: AnyType[]): void;
+    error(message: string, ...args: AnyType[]): void;
+    emerg(message: string, ...args: AnyType[]): void;
+    log(level: TLogLevel, message: string, ...args: AnyType[]): void;
+    log(level: TLogLevel, messageBytes: Uint8Array): void;
+    for(methodName: string): ILogger;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/cjs/modules/logger/hf/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../../src/modules/logger/hf/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,OAAO,EAAoB,SAAS,EAAE,MAAM,WAAW,CAAC;AAkBjE,4KAA4K;AAC5K,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACxD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAiC;IACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAA+B;IACnD,OAAO,CAAC,MAAM,CAAC,YAAY,CAAiC;IAE5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAElC,OAAO;IAQP,OAAO,CAAC,MAAM,CAAC,WAAW;IAS1B,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ;IASnC,6HAA6H;IAC7H,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAcjD,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAQjC,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,WAAW;IASnB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAOhD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIhD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAIhD,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAChE,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,GAAG,IAAI;IAUrD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;CAGjC"}

package/dist/cjs/modules/logger/hf/logger.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HfLogger = void 0;
+const base_1 = require("../base");
+const common_1 = require("../common");
+const formatting_1 = require("../formatting");
+const common_2 = require("./common");
+const ring_1 = require("./ring");
+/** Ring-buffer logger for hot paths; extends AbstractLogger, NOT BaseLogger - BaseLogger's string-sink plumbing is exactly the cost this implementation exists to avoid. */
+class HfLogger extends base_1.AbstractLogger {
+    static { this.textEncoder = new TextEncoder(); }
+    static { this.scopeCache = new Map(); }
+    static { this.cache = new Map(); }
+    static { this.messageCache = new Map(); }
+    constructor(scope) {
+        super();
+        this.scope = scope;
+        this.scopeBytes = HfLogger.encodeScope(scope);
+        this.scopeLength = this.scopeBytes.length;
+        this.ring = ring_1.HfLogRing.get();
+    }
+    static encodeScope(scope) {
+        let bytes = HfLogger.scopeCache.get(scope);
+        if (!bytes) {
+            bytes = HfLogger.textEncoder.encode(scope).subarray(0, common_2.HF_SCOPE_MAX_BYTES);
+            HfLogger.scopeCache.set(scope, bytes);
+        }
+        return bytes;
+    }
+    static get(scope) {
+        let logger = this.cache.get(scope);
+        if (!logger) {
+            logger = new HfLogger(scope); // first logger allocates the ring - never at import
+            this.cache.set(scope, logger);
+        }
+        return logger;
+    }
+    /** Pre-encode a message at initialization time; the cache is FIFO-bounded so dynamic strings can't grow it without limit. */
+    static encodeMessage(message) {
+        const cached = this.messageCache.get(message);
+        if (cached) {
+            return cached;
+        }
+        const bytes = HfLogger.textEncoder.encode(message);
+        if (this.messageCache.size >= common_2.MESSAGE_CACHE_CAP) {
+            this.evictOldestMessage();
+        }
+        this.messageCache.set(message, bytes);
+        return bytes;
+    }
+    static evictOldestMessage() {
+        const oldest = this.messageCache.keys().next().value;
+        if (oldest === undefined) {
+            return;
+        }
+        this.messageCache.delete(oldest);
+    }
+    writeEntry(levelCode, messageBytes) {
+        const ring = this.ring;
+        const slot = ring.writeIndex++ & (common_2.BUFFER_SIZE - 1);
+        const offset = slot * common_2.ENTRY_SIZE;
+        ring.f64[offset >> 3] = performance.timeOrigin + performance.now();
+        const bytes = ring.bytes;
+        bytes[offset + common_2.OFFSET_LEVEL] = levelCode;
+        bytes[offset + common_2.OFFSET_SCOPE_LENGTH] = this.scopeLength;
+        bytes.set(this.scopeBytes, offset + common_2.OFFSET_SCOPE);
+        const messageLength = messageBytes.length < common_2.HF_MESSAGE_MAX_BYTES ? messageBytes.length : common_2.HF_MESSAGE_MAX_BYTES;
+        bytes[offset + common_2.OFFSET_MESSAGE_LENGTH] = messageLength;
+        bytes.set(messageLength === messageBytes.length
+            ? messageBytes
+            : messageBytes.subarray(0, messageLength), offset + common_2.OFFSET_MESSAGE);
+    }
+    writeString(levelCode, message, args) {
+        if (args.length > 0) {
+            // Slow path, documented: args are formatted (deep inspection + redaction) - never dropped.
+            this.writeEntry(levelCode, HfLogger.textEncoder.encode((0, formatting_1.formatLogMessage)({ message, args })));
+            return;
+        }
+        this.writeEntry(levelCode, HfLogger.encodeMessage(message));
+    }
+    debug(message, ...args) {
+        if (!common_1.SHOULD_LOG_DEBUG) {
+            return;
+        }
+        this.writeString(common_2.HF_LEVEL_CODES.debug, message, args);
+    }
+    info(message, ...args) {
+        this.writeString(common_2.HF_LEVEL_CODES.info, message, args);
+    }
+    warn(message, ...args) {
+        this.writeString(common_2.HF_LEVEL_CODES.warn, message, args);
+    }
+    error(message, ...args) {
+        this.writeString(common_2.HF_LEVEL_CODES.error, message, args);
+    }
+    emerg(message, ...args) {
+        this.writeString(common_2.HF_LEVEL_CODES.emerg, message, args);
+    }
+    log(level, message, ...args) {
+        const levelCode = common_2.HF_LEVEL_CODES[level] ?? common_2.HF_LEVEL_CODES.info;
+        if (typeof message === 'string') {
+            this.writeString(levelCode, message, args);
+            return;
+        }
+        this.writeEntry(levelCode, message);
+    }
+    for(methodName) {
+        return HfLogger.get(`${this.scope}-${methodName}`);
+    }
+}
+exports.HfLogger = HfLogger;
+//# sourceMappingURL=logger.js.map

package/dist/cjs/modules/logger/hf/logger.js.map

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

package/dist/cjs/modules/logger/hf/ring.d.ts

@@ -0,0 +1,7 @@
+import { TRingState } from './common';
+/** One ring per process, allocated on FIRST use. Plain ArrayBuffer on purpose - single hot thread design, so shared memory/atomics would only tax the hot path. */
+export declare class HfLogRing {
+    private static state;
+    static get(): TRingState;
+}
+//# sourceMappingURL=ring.d.ts.map

package/dist/cjs/modules/logger/hf/ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring.d.ts","sourceRoot":"","sources":["../../../../../src/modules/logger/hf/ring.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/D,mKAAmK;AACnK,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAA2B;IAE/C,MAAM,CAAC,GAAG,IAAI,UAAU;CAazB"}

package/dist/cjs/modules/logger/hf/ring.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HfLogRing = void 0;
+const common_1 = require("./common");
+/** One ring per process, allocated on FIRST use. Plain ArrayBuffer on purpose - single hot thread design, so shared memory/atomics would only tax the hot path. */
+class HfLogRing {
+    static { this.state = null; }
+    static get() {
+        if (HfLogRing.state) {
+            return HfLogRing.state;
+        }
+        const buffer = new ArrayBuffer(common_1.BUFFER_SIZE * common_1.ENTRY_SIZE);
+        HfLogRing.state = {
+            bytes: new Uint8Array(buffer),
+            f64: new Float64Array(buffer),
+            writeIndex: 0,
+        };
+        return HfLogRing.state;
+    }
+}
+exports.HfLogRing = HfLogRing;
+//# sourceMappingURL=ring.js.map

package/dist/cjs/modules/logger/hf/ring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring.js","sourceRoot":"","sources":["../../../../../src/modules/logger/hf/ring.ts"],"names":[],"mappings":";;;AAAA,qCAA+D;AAE/D,mKAAmK;AACnK,MAAa,SAAS;aACL,UAAK,GAAsB,IAAI,CAAC;IAE/C,MAAM,CAAC,GAAG;QACR,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;YACpB,OAAO,SAAS,CAAC,KAAK,CAAC;QACzB,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,oBAAW,GAAG,mBAAU,CAAC,CAAC;QACzD,SAAS,CAAC,KAAK,GAAG;YAChB,KAAK,EAAE,IAAI,UAAU,CAAC,MAAM,CAAC;YAC7B,GAAG,EAAE,IAAI,YAAY,CAAC,MAAM,CAAC;YAC7B,UAAU,EAAE,CAAC;SACd,CAAC;QACF,OAAO,SAAS,CAAC,KAAK,CAAC;IACzB,CAAC;;AAfH,8BAgBC"}

package/dist/cjs/modules/logger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/modules/logger/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,MAAM,CAAC;AACrB,cAAc,YAAY,CAAC"}

package/dist/cjs/modules/logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/modules/logger/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yCAAuB;AACvB,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,uCAAqB;AACrB,6CAA2B"}

package/dist/cjs/modules/logger/pino/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/logger/pino/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC"}

package/dist/cjs/modules/logger/pino/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../src/modules/logger/pino/common/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB"}

package/dist/cjs/modules/logger/pino/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../src/modules/logger/pino/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,0LAA0L;AAC1L,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAE3C,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAE9D,wGAAwG;AACxG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B"}

package/dist/cjs/modules/logger/pino/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../src/modules/logger/pino/common/types.ts"],"names":[],"mappings":""}

package/dist/cjs/modules/logger/pino/define.d.ts

@@ -0,0 +1,76 @@
+import pino from 'pino';
+import { TPinoCustomLevelName, TPinoInstance } from './common';
+/** pino levels are ASCENDING severity (error 50 > warn 40 > info 30 > debug 20); `emerg`(70) extends above error. NORMATIVE - do not renumber without updating the spec. */
+export declare const PINO_CUSTOM_LEVELS: Record<TPinoCustomLevelName, number>;
+export type TFrequency = 'hourly' | 'daily';
+/** Pure description of where pino should write, derived from env; `PinoDestination.build()` is the impure half that acts on it. */
+export type TDestinationPlan = {
+    kind: 'stdout';
+} | {
+    kind: 'pretty';
+} | {
+    kind: 'roll';
+    options: {
+        file: string;
+        frequency: TFrequency;
+        size: string;
+        limit: {
+            count: number;
+        };
+        mkdir: true;
+    };
+};
+/** Reads `APP_ENV_LOGGER_*` and turns it into a destination. Warning prefixes name the operation, not the class - the tests and the published API still call these `mapFrequency`/`mapMaxFilesToCount`. */
+export declare class PinoDestination {
+    private static readonly DEFAULT_FREQUENCY;
+    private static readonly DEFAULT_MAX_FILES;
+    /** `APP_ENV_LOGGER_FILE_FREQUENCY` -> pino-roll's `frequency`; an unrecognized value warns and falls back rather than throwing, so the app still boots. */
+    static mapFrequency(value?: string): TFrequency;
+    /** `null` means "not a recognized shape" - the caller decides what default to fall back to. */
+    private static parseMaxFilesValue;
+    /** `APP_ENV_LOGGER_FILE_MAX_FILES` -> pino-roll's `limit.count`: `'<n>d'` scales by frequency (hourly: days*24), a bare integer is a literal count, unrecognized falls back to `'5d'`. */
+    static mapMaxFilesToCount(opts: {
+        value?: string;
+        frequency: TFrequency;
+    }): number;
+    /** Pure: which destination pino should write to, derived from `APP_ENV_LOGGER_*` at CALL time. `DATE_PATTERN` is deliberately not read - pino-roll has no equivalent. */
+    static resolvePlan(): TDestinationPlan;
+    /** `pino.transport()` is SYNCHRONOUS - it returns a `ThreadStream` that BUFFERS writes until its worker thread loads, so no async gating is needed; `ModuleUtility.assertInstalled` runs first so a missing optional peer fails loudly here, not as an opaque worker-thread crash. */
+    static build(plan: TDestinationPlan): pino.DestinationStream | undefined;
+}
+/** Owns the single pino instance every scope writes through, and the transport thread behind it. */
+export declare class PinoBackingLogger {
+    private static instance;
+    /** The `ThreadStream` behind `instance`, held ONLY when built via a transport (pretty/roll) and `undefined` for `stdout` or an injected instance - tracked so a replacement can close the worker instead of orphaning it. */
+    private static transport;
+    /** Pure: pino constructor options derived from env at CALL time. Public so tests can build a REAL instance against an in-memory destination, without the impure singleton. */
+    static buildOptions(): {
+        name: string;
+        level: string;
+        customLevels: Record<"emerg", number>;
+    };
+    /** Lazy, env-driven singleton, built once and reused by every scope entirely synchronously - the very first log line already targets the real env-configured destination, no stdout bootstrap. `set()` is the only way to replace it; this getter never resets it. */
+    static get(): TPinoInstance;
+    /** Replaces the singleton outright: an outgoing transport-backed instance (pretty/roll) is a `ThreadStream` on a live worker thread, so this flushes then `.end()`s it first rather than orphaning the worker; failures are logged via `console.error`, never swallowed. */
+    static set(opts: {
+        instance: TPinoInstance;
+    }): void;
+    private static closeTransport;
+}
+export declare const mapFrequency: (value?: string) => TFrequency;
+export declare const mapMaxFilesToCount: (opts: {
+    value?: string;
+    frequency: TFrequency;
+}) => number;
+export declare const resolveDestinationPlan: () => TDestinationPlan;
+export declare const buildDestination: (plan: TDestinationPlan) => pino.DestinationStream | undefined;
+export declare const buildPinoOptions: () => {
+    name: string;
+    level: string;
+    customLevels: Record<"emerg", number>;
+};
+export declare const getPinoBackingLogger: () => TPinoInstance;
+export declare const setPinoBackingLogger: (opts: {
+    instance: TPinoInstance;
+}) => void;
+//# sourceMappingURL=define.d.ts.map

package/dist/cjs/modules/logger/pino/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../../../src/modules/logger/pino/define.ts"],"names":[],"mappings":"AAIA,OAAO,IAAI,MAAM,MAAM,CAAC;AAGxB,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE/D,4KAA4K;AAC5K,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAEnE,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5C,mIAAmI;AACnI,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,UAAU,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE;YAAE,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;QACzB,KAAK,EAAE,IAAI,CAAC;KACb,CAAC;CACH,CAAC;AAEN,2MAA2M;AAC3M,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAwB;IACjE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAQ;IAEjD,2JAA2J;IAC3J,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU;IAsB/C,+FAA+F;IAC/F,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAejC,0LAA0L;IAC1L,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,UAAU,CAAA;KAAE,GAAG,MAAM;IA0BlF,yKAAyK;IACzK,MAAM,CAAC,WAAW,IAAI,gBAAgB;IA8BtC,sRAAsR;IACtR,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC,iBAAiB,GAAG,SAAS;CAkBzE;AAED,oGAAoG;AACpG,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA4B;IACnD,6NAA6N;IAC7N,OAAO,CAAC,MAAM,CAAC,SAAS,CAAqC;IAE7D,8KAA8K;IAC9K,MAAM,CAAC,YAAY;;;;;IAQnB,sQAAsQ;IACtQ,MAAM,CAAC,GAAG,IAAI,aAAa;IAY3B,4QAA4Q;IAC5Q,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE;QAAE,QAAQ,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAUnD,OAAO,CAAC,MAAM,CAAC,cAAc;CAW9B;AAID,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,KAAG,UAAiD,CAAC;AAEhG,eAAO,MAAM,kBAAkB,GAAI,MAAM;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,UAAU,CAAA;CAAE,KAAG,MAC3C,CAAC;AAE3C,eAAO,MAAM,sBAAsB,QAAO,gBAAiD,CAAC;AAE5F,eAAO,MAAM,gBAAgB,GAAI,MAAM,gBAAgB,KAAG,IAAI,CAAC,iBAAiB,GAAG,SACtD,CAAC;AAE9B,eAAO,MAAM,gBAAgB;;;;CAAyC,CAAC;AAEvE,eAAO,MAAM,oBAAoB,QAAO,aAAwC,CAAC;AAEjF,eAAO,MAAM,oBAAoB,GAAI,MAAM;IAAE,QAAQ,EAAE,aAAa,CAAA;CAAE,KAAG,IAC5C,CAAC"}

package/dist/cjs/modules/logger/pino/define.js

@@ -0,0 +1,170 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPinoBackingLogger = exports.getPinoBackingLogger = exports.buildPinoOptions = exports.buildDestination = exports.resolveDestinationPlan = exports.mapMaxFilesToCount = exports.mapFrequency = exports.PinoBackingLogger = exports.PinoDestination = exports.PINO_CUSTOM_LEVELS = void 0;
+const constants_1 = require("../../../common/constants");
+const module_utility_1 = require("../../../utilities/module.utility");
+const node_path_1 = __importDefault(require("node:path"));
+const pino_1 = __importDefault(require("pino"));
+const common_1 = require("../common");
+/** pino levels are ASCENDING severity (error 50 > warn 40 > info 30 > debug 20); `emerg`(70) extends above error. NORMATIVE - do not renumber without updating the spec. */
+exports.PINO_CUSTOM_LEVELS = {
+    emerg: 70,
+};
+/** Reads `APP_ENV_LOGGER_*` and turns it into a destination. Warning prefixes name the operation, not the class - the tests and the published API still call these `mapFrequency`/`mapMaxFilesToCount`. */
+class PinoDestination {
+    static { this.DEFAULT_FREQUENCY = 'hourly'; }
+    static { this.DEFAULT_MAX_FILES = '5d'; }
+    /** `APP_ENV_LOGGER_FILE_FREQUENCY` -> pino-roll's `frequency`; an unrecognized value warns and falls back rather than throwing, so the app still boots. */
+    static mapFrequency(value) {
+        const normalized = (value ?? '1h').trim().toLowerCase();
+        switch (normalized) {
+            case '1h': {
+                return 'hourly';
+            }
+            case '1d':
+            case '24h': {
+                return 'daily';
+            }
+            default: {
+                console.warn('[mapFrequency] Invalid logger file frequency | value: %s | fallback: %s', value, PinoDestination.DEFAULT_FREQUENCY);
+                return PinoDestination.DEFAULT_FREQUENCY;
+            }
+        }
+    }
+    /** `null` means "not a recognized shape" - the caller decides what default to fall back to. */
+    static parseMaxFilesValue(value, frequency) {
+        const dayMatch = /^(\d+)d$/i.exec(value);
+        if (dayMatch) {
+            const days = Number.parseInt(dayMatch[1], 10);
+            return frequency === 'hourly' ? days * 24 : days;
+        }
+        const bareMatch = /^\d+$/.exec(value);
+        if (bareMatch) {
+            return Number.parseInt(value, 10);
+        }
+        return null;
+    }
+    /** `APP_ENV_LOGGER_FILE_MAX_FILES` -> pino-roll's `limit.count`: `'<n>d'` scales by frequency (hourly: days*24), a bare integer is a literal count, unrecognized falls back to `'5d'`. */
+    static mapMaxFilesToCount(opts) {
+        const { value, frequency } = opts;
+        const normalized = value?.trim();
+        if (normalized) {
+            const parsed = PinoDestination.parseMaxFilesValue(normalized, frequency);
+            if (parsed !== null) {
+                return parsed;
+            }
+        }
+        // Unset is a normal configuration (mirror the sibling defaults) - only a PROVIDED value that failed to parse deserves a warning.
+        if (normalized && normalized !== PinoDestination.DEFAULT_MAX_FILES) {
+            console.warn('[mapMaxFilesToCount] Invalid logger file max files value | value: %s | fallback: %s', value, PinoDestination.DEFAULT_MAX_FILES);
+        }
+        return PinoDestination.parseMaxFilesValue(PinoDestination.DEFAULT_MAX_FILES, frequency);
+    }
+    /** Pure: which destination pino should write to, derived from `APP_ENV_LOGGER_*` at CALL time. `DATE_PATTERN` is deliberately not read - pino-roll has no equivalent. */
+    static resolvePlan() {
+        const folderPath = process.env.APP_ENV_LOGGER_FOLDER_PATH;
+        if (folderPath && folderPath.trim() !== '') {
+            const frequency = PinoDestination.mapFrequency(process.env.APP_ENV_LOGGER_FILE_FREQUENCY);
+            const count = PinoDestination.mapMaxFilesToCount({
+                value: process.env.APP_ENV_LOGGER_FILE_MAX_FILES,
+                frequency,
+            });
+            return {
+                kind: 'roll',
+                options: {
+                    file: node_path_1.default.join(folderPath, constants_1.Defaults.APPLICATION_NAME),
+                    frequency,
+                    size: process.env.APP_ENV_LOGGER_FILE_MAX_SIZE ?? '100m',
+                    limit: { count },
+                    mkdir: true,
+                },
+            };
+        }
+        // UNSET means NDJSON to stdout, the locked default for this provider; only an EXPLICIT `text` opts into pino-pretty, and falling back to TEXT here (winston's default) would make the documented minimal install (pino only, no pino-pretty) crash on its first log line.
+        if (process.env.APP_ENV_LOGGER_FORMAT === common_1.LoggerFormats.TEXT) {
+            return { kind: 'pretty' };
+        }
+        return { kind: 'stdout' };
+    }
+    /** `pino.transport()` is SYNCHRONOUS - it returns a `ThreadStream` that BUFFERS writes until its worker thread loads, so no async gating is needed; `ModuleUtility.assertInstalled` runs first so a missing optional peer fails loudly here, not as an opaque worker-thread crash. */
+    static build(plan) {
+        switch (plan.kind) {
+            case 'stdout': {
+                return undefined;
+            }
+            case 'pretty': {
+                module_utility_1.ModuleUtility.assertInstalled({ scope: 'PinoLogger', modules: ['pino-pretty'] });
+                return pino_1.default.transport({ target: 'pino-pretty' });
+            }
+            case 'roll': {
+                module_utility_1.ModuleUtility.assertInstalled({ scope: 'PinoLogger', modules: ['pino-roll'] });
+                return pino_1.default.transport({ target: 'pino-roll', options: plan.options });
+            }
+            default: {
+                return undefined;
+            }
+        }
+    }
+}
+exports.PinoDestination = PinoDestination;
+/** Owns the single pino instance every scope writes through, and the transport thread behind it. */
+class PinoBackingLogger {
+    /** Pure: pino constructor options derived from env at CALL time. Public so tests can build a REAL instance against an in-memory destination, without the impure singleton. */
+    static buildOptions() {
+        return {
+            name: constants_1.Defaults.APPLICATION_NAME,
+            level: (0, common_1.resolveLoggerLevel)({ configured: process.env.APP_ENV_LOGGER_LEVEL }),
+            customLevels: exports.PINO_CUSTOM_LEVELS,
+        };
+    }
+    /** Lazy, env-driven singleton, built once and reused by every scope entirely synchronously - the very first log line already targets the real env-configured destination, no stdout bootstrap. `set()` is the only way to replace it; this getter never resets it. */
+    static get() {
+        if (!PinoBackingLogger.instance) {
+            const destination = PinoDestination.build(PinoDestination.resolvePlan());
+            PinoBackingLogger.instance = (0, pino_1.default)(PinoBackingLogger.buildOptions(), destination);
+            PinoBackingLogger.transport = destination;
+        }
+        return PinoBackingLogger.instance;
+    }
+    /** Replaces the singleton outright: an outgoing transport-backed instance (pretty/roll) is a `ThreadStream` on a live worker thread, so this flushes then `.end()`s it first rather than orphaning the worker; failures are logged via `console.error`, never swallowed. */
+    static set(opts) {
+        if (PinoBackingLogger.instance) {
+            PinoBackingLogger.instance.flush();
+            PinoBackingLogger.closeTransport();
+        }
+        PinoBackingLogger.instance = opts.instance;
+        PinoBackingLogger.transport = undefined;
+    }
+    static closeTransport() {
+        if (!PinoBackingLogger.transport) {
+            return;
+        }
+        try {
+            PinoBackingLogger.transport.end();
+        }
+        catch (error) {
+            console.error('[setPinoBackingLogger] Failed to close previous transport stream', error);
+        }
+    }
+}
+exports.PinoBackingLogger = PinoBackingLogger;
+// Published names, kept so `@venizia/ignis-helpers/pino` consumers do not have to move; the classes
+// above are the implementation and the entry point for new code.
+const mapFrequency = (value) => PinoDestination.mapFrequency(value);
+exports.mapFrequency = mapFrequency;
+const mapMaxFilesToCount = (opts) => PinoDestination.mapMaxFilesToCount(opts);
+exports.mapMaxFilesToCount = mapMaxFilesToCount;
+const resolveDestinationPlan = () => PinoDestination.resolvePlan();
+exports.resolveDestinationPlan = resolveDestinationPlan;
+const buildDestination = (plan) => PinoDestination.build(plan);
+exports.buildDestination = buildDestination;
+const buildPinoOptions = () => PinoBackingLogger.buildOptions();
+exports.buildPinoOptions = buildPinoOptions;
+const getPinoBackingLogger = () => PinoBackingLogger.get();
+exports.getPinoBackingLogger = getPinoBackingLogger;
+const setPinoBackingLogger = (opts) => PinoBackingLogger.set(opts);
+exports.setPinoBackingLogger = setPinoBackingLogger;
+//# sourceMappingURL=define.js.map

package/dist/cjs/modules/logger/pino/define.js.map

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

package/dist/cjs/modules/logger/pino/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/modules/logger/pino/index.ts"],"names":[],"mappings":"AAAA,yLAAyL;AACzL,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC"}

package/dist/cjs/modules/logger/pino/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/modules/logger/pino/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yLAAyL;AACzL,2CAAyB;AACzB,2CAAyB;AACzB,2CAAyB"}