@kikiutils/shared 18.2.0 → 19.0.0

package/dist/logger/node/_internals/file-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-writer.js","names":[],"sources":["../../../../src/logger/node/_internals/file-writer.ts"],"sourcesContent":["import { Buffer } from 'node:buffer';\nimport { createWriteStream } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport {\n    basename,\n    dirname,\n} from 'node:path';\nimport type { Writable } from 'node:stream';\nimport { fileURLToPath } from 'node:url';\n\nimport { Path } from '../../../classes/path';\nimport type { LoggerDiagnostic } from '../../types';\nimport type {\n    LoggerFileOptions,\n    NodeLoggerStats,\n} from '../types';\n\ninterface LoggerFileWriter {\n    close: () => Promise<void>;\n    getStats: () => NodeLoggerStats;\n    write: (text: string) => Promise<void>;\n}\n\n// Constants/Variables\nconst defaultMaxPendingBytes = 8 * 1024 * 1024;\n\n// Functions\n\n/** A bounded admission layer over the stream's own ordered write buffer; not a second FIFO. */\nexport async function createFileWriter(\n    options: LoggerFileOptions,\n    report: (event: LoggerDiagnostic) => void,\n): Promise<LoggerFileWriter> {\n    const {\n        maxPendingBytes,\n        path,\n        rotate,\n    } = validateFileOptions(options);\n\n    const createRotatingStream = rotate ? (await import('rotating-file-stream')).createStream : undefined;\n    await mkdir(dirname(path), { recursive: true });\n    const stream: Writable = rotate && createRotatingStream\n        ? createRotatingStream(\n            basename(path),\n            {\n                compress: rotate.compress === false ? false : 'gzip',\n                ...rotate.interval === undefined ? {} : { interval: rotate.interval === 'hourly' ? '1h' : '1d' },\n                intervalBoundary: true,\n                intervalUTC: false,\n                maxFiles: rotate.keepFiles ?? 30,\n                ...rotate.maxTotalSize === undefined ? {} : { maxSize: rotate.maxTotalSize },\n                path: dirname(path),\n                ...rotate.maxSize === undefined ? {} : { size: rotate.maxSize },\n            },\n        )\n        : createWriteStream(path, { flags: 'a' });\n\n    let pendingBytes = 0;\n    let droppedCount = 0;\n    let writeErrorCount = 0;\n    let failed = false;\n    let closing = false;\n    let closed = false;\n    let closePromise: Promise<void> | undefined;\n    let initializing = true;\n    const unfinished = new Set<() => void>();\n    let rejectInitialization: ((error: unknown) => void) | undefined;\n\n    const settleAll = () => {\n        for (const settle of unfinished) settle();\n    };\n\n    const fail = (error: unknown) => {\n        rejectInitialization?.(error);\n        if (!failed) {\n            failed = true;\n            if (!initializing) {\n                writeErrorCount++;\n                report({\n                    error,\n                    message: 'File output failed and has been disabled.',\n                    type: 'file',\n                });\n            }\n        }\n\n        settleAll();\n        if (!stream.destroyed) stream.destroy();\n    };\n\n    stream.on('error', fail);\n    stream.on(\n        'warning',\n        (error: unknown) => {\n            writeErrorCount++;\n            report({\n                error,\n                message: 'File rotation cleanup failed.',\n                type: 'file',\n            });\n        },\n    );\n\n    stream.on(\n        'close',\n        () => {\n            closed = true;\n            if (!closing && !failed) fail(new Error('File stream closed unexpectedly.'));\n            settleAll();\n        },\n    );\n\n    // A write callback also waits for RFS's asynchronous initialization and initial rotation.\n    try {\n        await new Promise<void>((resolveReady, rejectReady) => {\n            rejectInitialization = rejectReady;\n            stream.write(\n                Buffer.alloc(0),\n                (error) => {\n                    if (error) rejectReady(error);\n                    else resolveReady();\n                },\n            );\n        });\n\n        if (failed || closed) throw new Error('File output failed during initialization.');\n    } catch (error) {\n        if (!stream.destroyed) stream.destroy();\n        if (!closed) {\n            await new Promise<void>((resolveClosed) => {\n                stream.once('close', resolveClosed);\n            });\n        }\n\n        throw error;\n    } finally {\n        rejectInitialization = undefined;\n        initializing = false;\n    }\n\n    return {\n        close() {\n            if (closePromise) return closePromise;\n            closing = true;\n            closePromise = new Promise<void>((resolveClosed) => {\n                if (closed) {\n                    resolveClosed();\n                    return;\n                }\n\n                stream.once('close', resolveClosed);\n                try {\n                    if (!stream.destroyed) stream.end();\n                } catch (error) {\n                    fail(error);\n                }\n            });\n\n            return closePromise;\n        },\n        getStats: () => ({\n            droppedCount,\n            pendingBytes,\n            writeErrorCount,\n        }),\n        write(text) {\n            if (closing || closed || failed) {\n                report({\n                    message: 'File output is closed or unavailable.',\n                    type: 'closed',\n                });\n\n                return Promise.resolve();\n            }\n\n            const bytes = Buffer.byteLength(text);\n            if (bytes > maxPendingBytes - pendingBytes) {\n                droppedCount++;\n                report({\n                    droppedCount,\n                    message: 'File output queue is full; the newest record was discarded.',\n                    type: 'overflow',\n                });\n\n                return Promise.resolve();\n            }\n\n            pendingBytes += bytes;\n            return new Promise<void>((resolveWritten) => {\n                let settled = false;\n                const settle = () => {\n                    if (settled) return;\n                    settled = true;\n                    pendingBytes -= bytes;\n                    unfinished.delete(settle);\n                    resolveWritten();\n                };\n\n                unfinished.add(settle);\n                try {\n                    stream.write(\n                        text,\n                        (error) => {\n                            if (error) fail(error);\n                            settle();\n                        },\n                    );\n                } catch (error) {\n                    fail(error);\n                }\n            });\n        },\n    };\n}\n\n/** Validate before mkdir, stream creation, or other filesystem side effects. */\nfunction validateFileOptions(options: LoggerFileOptions) {\n    if (\n        !options\n        || typeof options !== 'object'\n        || !(\n            typeof options.path === 'string'\n            || options.path instanceof Path\n            || options.path instanceof URL\n            || Buffer.isBuffer(options.path)\n        )\n    ) {\n        throw new TypeError('file.path must be a string, Buffer, file URL, or Path');\n    }\n\n    const path = options.path instanceof URL\n        ? fileURLToPath(options.path)\n        : options.path.toString();\n\n    if (Buffer.isBuffer(options.path) && !Buffer.from(path).equals(options.path)) {\n        throw new TypeError('file.path Buffer must contain valid UTF-8');\n    }\n\n    if (!path.trim() || path.includes('\\0')) {\n        throw new TypeError('file.path must be a nonempty path without null bytes');\n    }\n\n    const maxPendingBytes = options.maxPendingBytes ?? defaultMaxPendingBytes;\n    if (!Number.isSafeInteger(maxPendingBytes) || maxPendingBytes <= 0) {\n        throw new RangeError('file.maxPendingBytes must be a positive safe integer');\n    }\n\n    const rotate = options.rotate;\n    if (rotate !== undefined && rotate !== false) {\n        if (!rotate || typeof rotate !== 'object') {\n            throw new TypeError('file.rotate must be false or an options object');\n        }\n\n        if (rotate.interval !== undefined && rotate.interval !== 'hourly' && rotate.interval !== 'daily') {\n            throw new TypeError('file.rotate.interval must be hourly or daily');\n        }\n\n        if (rotate.interval === undefined && rotate.maxSize === undefined) {\n            throw new TypeError('file.rotate requires interval or maxSize');\n        }\n\n        const keepFiles = rotate.keepFiles ?? 30;\n        if (!Number.isSafeInteger(keepFiles) || keepFiles <= 0) {\n            throw new RangeError('file.rotate.keepFiles must be a positive safe integer');\n        }\n\n        if (rotate.compress !== undefined && typeof rotate.compress !== 'boolean') {\n            throw new TypeError('file.rotate.compress must be a boolean');\n        }\n\n        validateSize(rotate.maxSize, 'file.rotate.maxSize');\n        validateSize(rotate.maxTotalSize, 'file.rotate.maxTotalSize');\n    }\n\n    return {\n        maxPendingBytes,\n        path: Path.resolve(path).value,\n        rotate,\n    };\n}\n\nfunction validateSize(value: string | undefined, name: string) {\n    if (value === undefined) return;\n    if (typeof value !== 'string' || !/^[1-9]\\d*[BKMG]$/.test(value)) {\n        throw new TypeError(`${name} must be a positive integer followed by B, K, M, or G`);\n    }\n\n    const multiplier = {\n        B: 1,\n        G: 1024 ** 3,\n        K: 1024,\n        M: 1024 ** 2,\n    }[value.at(-1) as 'B' | 'G' | 'K' | 'M'];\n\n    if (!Number.isSafeInteger(Number(value.slice(0, -1)) * multiplier)) {\n        throw new RangeError(`${name} exceeds the supported size range`);\n    }\n}\n"],"mappings":"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"}

package/dist/logger/node/_internals/formatter.d.ts

@@ -0,0 +1,4 @@
+import { LoggerRecord } from "../../_internals/types.js";
+/** Preserve user ANSI for console output without invoking custom inspect callbacks/getters. */
+export declare function formatNodeLoggerRecord(record: LoggerRecord, colors?: boolean): string;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/logger/node/_internals/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","names":[],"sources":["../../../../src/logger/node/_internals/formatter.ts"],"mappings":";;wBAQgB,uBAAuB,QAAQ,cAAc"}

package/dist/logger/node/_internals/formatter.js

@@ -0,0 +1,21 @@
+import { formatLoggerParts } from "../../_internals/formatter.js";
+import { inspect } from "node:util";
+// src/logger/node/_internals/formatter.ts
+/** Preserve user ANSI for console output without invoking custom inspect callbacks/getters. */
+function formatNodeLoggerRecord(record, colors = false) {
+	const message = record.args.map((arg) => typeof arg === "string" ? arg : inspect(arg, {
+		colors: false,
+		customInspect: false,
+		depth: 6,
+		getters: false,
+		maxArrayLength: 100,
+		maxStringLength: 1e4
+	})).join(" ");
+	return formatLoggerParts({
+		...record,
+		args: record.args.length ? [message] : []
+	}, colors).join(" ");
+}
+export { formatNodeLoggerRecord };
+
+//# sourceMappingURL=formatter.js.map

package/dist/logger/node/_internals/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","names":[],"sources":["../../../../src/logger/node/_internals/formatter.ts"],"sourcesContent":["import { inspect } from 'node:util';\n\nimport { formatLoggerParts } from '../../_internals/formatter';\nimport type { LoggerRecord } from '../../_internals/types';\n\n// Functions\n\n/** Preserve user ANSI for console output without invoking custom inspect callbacks/getters. */\nexport function formatNodeLoggerRecord(record: LoggerRecord, colors = false) {\n    const message = record.args.map(\n        (arg) => typeof arg === 'string'\n            ? arg\n            : inspect(\n                arg,\n                {\n                    colors: false,\n                    customInspect: false,\n                    depth: 6,\n                    getters: false,\n                    maxArrayLength: 100,\n                    maxStringLength: 10_000,\n                },\n            ),\n    ).join(' ');\n\n    return formatLoggerParts(\n        {\n            ...record,\n            args: record.args.length ? [message] : [],\n        },\n        colors,\n    ).join(' ');\n}\n"],"mappings":";;;;AAQA,SAAgB,uBAAuB,QAAsB,SAAS,OAAO;CACzE,MAAM,UAAU,OAAO,KAAK,KACvB,QAAQ,OAAO,QAAQ,WAClB,MACA,QACE,KACA;EACI,QAAQ;EACR,eAAe;EACf,OAAO;EACP,SAAS;EACT,gBAAgB;EAChB,iBAAiB;CACrB,CACJ,CACR,CAAC,CAAC,KAAK,GAAG;CAEV,OAAO,kBACH;EACI,GAAG;EACH,MAAM,OAAO,KAAK,SAAS,CAAC,OAAO,IAAI,CAAC;CAC5C,GACA,MACJ,CAAC,CAAC,KAAK,GAAG;AACd"}

package/dist/logger/node/index.d.ts

@@ -0,0 +1,10 @@
+import { NodeLogger, NodeLoggerOptions } from "./types.js";
+/**
+ * Creates a Node.js/Bun logger with optional bounded, append-only file output and rotation.
+ *
+ * Log calls never throw or reject. Awaiting them waits for processing, not proof of successful
+ * persistence: overload drops the newest file record and failures are reported safely. Factory
+ * validation/open failures reject. Call close explicitly; no process signal handlers are installed.
+ */
+export declare function createNodeLogger(options?: NodeLoggerOptions): Promise<NodeLogger>;
+//# sourceMappingURL=index.d.ts.map

package/dist/logger/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/logger/node/index.ts"],"mappings":";;;;;;;;wBAqCsB,iBAAiB,UAAS,oBAAyB,QAAQ"}

package/dist/logger/node/index.js

@@ -0,0 +1,122 @@
+import { getLoggerStreamName } from "../_internals/levels.js";
+import { supportsLoggerColor } from "../_internals/formatter.js";
+import { createDiagnosticReporter, createLoggerCore } from "../_internals/logger.js";
+import { createFileWriter } from "./_internals/file-writer.js";
+import { formatNodeLoggerRecord } from "./_internals/formatter.js";
+import { writeSync } from "node:fs";
+import { stripVTControlCharacters } from "node:util";
+// src/logger/node/index.ts
+const consoleStreams = /* @__PURE__ */ new WeakMap();
+/**
+* Creates a Node.js/Bun logger with optional bounded, append-only file output and rotation.
+*
+* Log calls never throw or reject. Awaiting them waits for processing, not proof of successful
+* persistence: overload drops the newest file record and failures are reported safely. Factory
+* validation/open failures reject. Call close explicitly; no process signal handlers are installed.
+*/
+async function createNodeLogger(options = {}) {
+	const report = createDiagnosticReporter(options.onError, (message) => writeSync(2, message));
+	let writer;
+	let closed = false;
+	let closePromise;
+	const consoleOwner = {};
+	const consoleTargets = /* @__PURE__ */ new Set();
+	const consoleWrites = /* @__PURE__ */ new Set();
+	const logger = createLoggerCore(options, {
+		report,
+		write(record) {
+			if (closed) {
+				report({
+					message: "Logger is closed.",
+					type: "closed"
+				});
+				return;
+			}
+			if (!record.console && !writer) return;
+			const target = process[getLoggerStreamName(record.type)];
+			const text = formatNodeLoggerRecord(record, record.console && supportsLoggerColor(target));
+			if (record.console) {
+				const line = `${text}\n`;
+				consoleTargets.add(target);
+				const completion = writeConsole(target, line, report, consoleOwner);
+				consoleWrites.add(completion);
+				completion.then(() => consoleWrites.delete(completion));
+				const fileCompletion = writer?.write(`${stripVTControlCharacters(text)}\n`);
+				return fileCompletion ? Promise.all([completion, fileCompletion]).then(() => {}) : completion;
+			}
+			return writer?.write(`${stripVTControlCharacters(text)}\n`);
+		}
+	});
+	if (options.file !== void 0 && options.file !== false) writer = await createFileWriter(options.file, report);
+	return Object.assign(logger, {
+		close() {
+			if (closePromise) return closePromise;
+			closed = true;
+			closePromise = (async () => {
+				await Promise.all([writer?.close(), ...consoleWrites]);
+				for (const target of consoleTargets) {
+					const state = consoleStreams.get(target);
+					if (!state) continue;
+					state.owners.delete(consoleOwner);
+					if (!state.owners.size) {
+						target.off("error", state.onError);
+						target.off("close", state.onClose);
+						consoleStreams.delete(target);
+					}
+				}
+				consoleTargets.clear();
+			})();
+			return closePromise;
+		},
+		getStats: () => writer?.getStats() ?? {
+			droppedCount: 0,
+			pendingBytes: 0,
+			writeErrorCount: 0
+		}
+	});
+}
+/** One error listener per shared output stream; retained until its last owning logger calls close(). */
+function writeConsole(target, text, report, owner) {
+	let state = consoleStreams.get(target);
+	if (!state) {
+		const pending = /* @__PURE__ */ new Set();
+		const onError = (error) => {
+			for (const settle of pending) settle(error);
+		};
+		const onClose = () => onError(/* @__PURE__ */ new Error("Console stream closed."));
+		state = {
+			onClose,
+			onError,
+			owners: /* @__PURE__ */ new Set(),
+			pending
+		};
+		consoleStreams.set(target, state);
+		target.on("error", onError);
+		target.on("close", onClose);
+	}
+	state.owners.add(owner);
+	const current = state;
+	return new Promise((resolveWritten) => {
+		let settled = false;
+		const settle = (error) => {
+			if (settled) return;
+			settled = true;
+			current.pending.delete(settle);
+			if (error) report({
+				error,
+				message: "Console output failed.",
+				type: "console"
+			});
+			resolveWritten();
+		};
+		current.pending.add(settle);
+		try {
+			target.write(text, settle);
+		} catch (error) {
+			settle(error instanceof Error ? error : /* @__PURE__ */ new Error("Console output failed."));
+		}
+	});
+}
+export { createNodeLogger };
+
+//# sourceMappingURL=index.js.map

package/dist/logger/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/logger/node/index.ts"],"sourcesContent":["import { writeSync } from 'node:fs';\nimport { stripVTControlCharacters } from 'node:util';\n\nimport { supportsLoggerColor } from '../_internals/formatter';\nimport { getLoggerStreamName } from '../_internals/levels';\nimport {\n    createDiagnosticReporter,\n    createLoggerCore,\n} from '../_internals/logger';\nimport type { LoggerDiagnostic } from '../types';\n\nimport { createFileWriter } from './_internals/file-writer';\nimport { formatNodeLoggerRecord } from './_internals/formatter';\nimport type {\n    NodeLogger,\n    NodeLoggerOptions,\n} from './types';\n\ninterface ConsoleStreamState {\n    onClose: () => void;\n    onError: (error: Error) => void;\n    owners: Set<object>;\n    pending: Set<(error?: Error | null) => void>;\n}\n\n// Constants/Variables\nconst consoleStreams = new WeakMap<NodeJS.WriteStream, ConsoleStreamState>();\n\n// Functions\n\n/**\n * Creates a Node.js/Bun logger with optional bounded, append-only file output and rotation.\n *\n * Log calls never throw or reject. Awaiting them waits for processing, not proof of successful\n * persistence: overload drops the newest file record and failures are reported safely. Factory\n * validation/open failures reject. Call close explicitly; no process signal handlers are installed.\n */\nexport async function createNodeLogger(options: NodeLoggerOptions = {}): Promise<NodeLogger> {\n    const report = createDiagnosticReporter(options.onError, (message) => writeSync(2, message));\n    let writer: Awaited<ReturnType<typeof createFileWriter>> | undefined;\n    let closed = false;\n    let closePromise: Promise<void> | undefined;\n    const consoleOwner = {};\n    const consoleTargets = new Set<NodeJS.WriteStream>();\n    const consoleWrites = new Set<Promise<void>>();\n    const logger = createLoggerCore(\n        options,\n        {\n            report,\n            write(record) {\n                if (closed) {\n                    report({\n                        message: 'Logger is closed.',\n                        type: 'closed',\n                    });\n\n                    return;\n                }\n\n                if (!record.console && !writer) return;\n                const target = process[getLoggerStreamName(record.type)];\n\n                const text = formatNodeLoggerRecord(record, record.console && supportsLoggerColor(target));\n                if (record.console) {\n                    const line = `${text}\\n`;\n                    consoleTargets.add(target);\n                    const completion = writeConsole(target, line, report, consoleOwner);\n                    consoleWrites.add(completion);\n                    void completion.then(() => consoleWrites.delete(completion));\n                    const fileCompletion = writer?.write(`${stripVTControlCharacters(text)}\\n`);\n                    return fileCompletion\n                        ? Promise.all([\n                            completion,\n                            fileCompletion,\n                        ]).then(() => {})\n                        : completion;\n                }\n\n                return writer?.write(`${stripVTControlCharacters(text)}\\n`);\n            },\n        },\n    );\n\n    if (options.file !== undefined && options.file !== false) writer = await createFileWriter(options.file, report);\n\n    return Object.assign(\n        logger,\n        {\n            close() {\n                if (closePromise) return closePromise;\n                closed = true;\n                closePromise = (async () => {\n                    await Promise.all([\n                        writer?.close(),\n                        ...consoleWrites,\n                    ]);\n\n                    for (const target of consoleTargets) {\n                        const state = consoleStreams.get(target);\n                        if (!state) continue;\n                        state.owners.delete(consoleOwner);\n                        if (!state.owners.size) {\n                            target.off('error', state.onError);\n                            target.off('close', state.onClose);\n                            consoleStreams.delete(target);\n                        }\n                    }\n\n                    consoleTargets.clear();\n                })();\n                return closePromise;\n            },\n            getStats: () => writer?.getStats() ?? {\n                droppedCount: 0,\n                pendingBytes: 0,\n                writeErrorCount: 0,\n            },\n        },\n    );\n}\n\n/** One error listener per shared output stream; retained until its last owning logger calls close(). */\nfunction writeConsole(\n    target: NodeJS.WriteStream,\n    text: string,\n    report: (event: LoggerDiagnostic) => void,\n    owner: object,\n) {\n    let state = consoleStreams.get(target);\n    if (!state) {\n        const pending = new Set<(error?: Error | null) => void>();\n        const onError = (error: Error) => {\n            for (const settle of pending) settle(error);\n        };\n\n        const onClose = () => onError(new Error('Console stream closed.'));\n        state = {\n            onClose,\n            onError,\n            owners: new Set(),\n            pending,\n        };\n\n        consoleStreams.set(target, state);\n        target.on('error', onError);\n        target.on('close', onClose);\n    }\n\n    state.owners.add(owner);\n    const current = state;\n    return new Promise<void>((resolveWritten) => {\n        let settled = false;\n        const settle = (error?: Error | null) => {\n            if (settled) return;\n            settled = true;\n            current.pending.delete(settle);\n            if (error) {\n                report({\n                    error,\n                    message: 'Console output failed.',\n                    type: 'console',\n                });\n            }\n\n            resolveWritten();\n        };\n\n        current.pending.add(settle);\n        try {\n            target.write(text, settle);\n        } catch (error) {\n            settle(error instanceof Error ? error : new Error('Console output failed.'));\n        }\n    });\n}\n"],"mappings":"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"}

package/dist/logger/node/types.d.ts

@@ -0,0 +1,43 @@
+import { PathLike } from "../../classes/path.js";
+import { Logger, LoggerOptions } from "../types.js";
+/** Specify interval and/or maxSize. Size limits use positive integers with B, K, M, or G (binary units). */
+export type LoggerRotationOptions = {
+  /** Gzip historical files. Defaults to true. */
+  compress?: boolean;
+  /** Number of historical files, excluding the active file. Defaults to 30. */
+  keepFiles?: number;
+  /** Maximum combined size of historical files. */
+  maxTotalSize?: string;
+} & ({
+  /** Opt-in time rotation aligned to the system's local calendar boundary. */
+  interval: 'daily' | 'hourly';
+  maxSize?: string;
+} | {
+  /** Opt-in time rotation aligned to the system's local calendar boundary. */
+  interval?: 'daily' | 'hourly';
+  maxSize: string;
+});
+export interface LoggerFileOptions {
+  /** Maximum unfinished payload bytes, including data already submitted to the stream. */
+  maxPendingBytes?: number;
+  /** Resolved once at creation. The file is opened in append mode. */
+  path: PathLike;
+  /** Omitted or false disables rotation. An object must specify interval or maxSize. */
+  rotate?: false | LoggerRotationOptions;
+}
+export interface NodeLogger extends Logger {
+  /** Stop accepting records, finish accepted file writes, then release the stream. Not fsync. */
+  close: () => Promise<void>;
+  /** A fresh snapshot. Dropped/failed records still resolve their logging promises. */
+  getStats: () => NodeLoggerStats;
+}
+export interface NodeLoggerOptions extends LoggerOptions {
+  /** Disabled by default. Each logger owns at most one fixed file destination. */
+  file?: false | LoggerFileOptions;
+}
+export interface NodeLoggerStats {
+  droppedCount: number;
+  pendingBytes: number;
+  writeErrorCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/logger/node/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/logger/node/types.ts"],"mappings":";;;YAOY;;EAER;;EAGA;;EAGA;;;EAIE;EACA;;;EAIA;EACA;;iBAIW;;EAEb;;EAGA,MAAM;;EAGN,iBAAiB;;iBAGJ,mBAAmB;;EAEhC,aAAa;;EAGb,gBAAgB;;iBAGH,0BAA0B;;EAEvC,eAAe;;iBAGF;EACb;EACA;EACA"}

package/dist/logger/node/types.js

@@ -0,0 +1 @@
+export {};

package/dist/logger/types.d.ts

@@ -0,0 +1,49 @@
+/** Minimum severity to emit; `success` uses the same threshold as `info`. */
+export type LoggerLevel = 'debug' | 'error' | 'fatal' | 'info' | 'silent' | 'trace' | 'warn';
+/** A logging method, including the informational success presentation. */
+export type LoggerMethod = 'success' | Exclude<LoggerLevel, 'silent'>;
+/**
+ * A logger whose logging methods never throw or reject for recoverable failures.
+ *
+ * Awaiting a method waits for processing, not guaranteed successful delivery or fsync.
+ * Configuration errors may throw from the factory, configure(), or setLevel().
+ */
+export interface Logger {
+  configure: (options: Pick<LoggerOptions, 'console' | 'icons' | 'prefix' | 'suffix' | 'timestamp'>) => void;
+  debug: (...args: unknown[]) => Promise<void>;
+  error: (...args: unknown[]) => Promise<void>;
+  fatal: (...args: unknown[]) => Promise<void>;
+  info: (...args: unknown[]) => Promise<void>;
+  /** Accepts success as an informational method; it is not a configurable threshold. */
+  isLevelEnabled: (level: LoggerLevel | LoggerMethod) => boolean;
+  /** Sets a severity threshold (not success); env restores environment-driven filtering. */
+  setLevel: (level: 'env' | LoggerLevel) => void;
+  success: (...args: unknown[]) => Promise<void>;
+  trace: (...args: unknown[]) => Promise<void>;
+  warn: (...args: unknown[]) => Promise<void>;
+}
+/** A recoverable logging failure, reported without throwing from log methods. */
+export interface LoggerDiagnostic {
+  droppedCount?: number;
+  error?: unknown;
+  message: string;
+  /** Same-type notifications suppressed since the previous emitted diagnostic. */
+  suppressedCount?: number;
+  type: 'closed' | 'console' | 'file' | 'format' | 'invalid-level' | 'overflow';
+}
+/** Configuration shared by browser and server loggers. */
+export interface LoggerOptions {
+  /** Enables console output. Defaults to `true`. */
+  console?: boolean;
+  /** Enables Unicode level icons. Defaults to `true`. */
+  icons?: boolean;
+  /** Overrides LOG_LEVEL; `env` restores the environment-driven threshold. */
+  level?: 'env' | LoggerLevel;
+  /** Best-effort, rate-limited notification; failures in this callback are contained. */
+  onError?: (event: LoggerDiagnostic) => void;
+  prefix?: string;
+  suffix?: string;
+  /** Enables the fixed local-time millisecond prefix. Defaults to `true`. */
+  timestamp?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/logger/types.ts"],"mappings":";YACY;;YAGA,2BAA2B,QAAQ;;;;;;;iBAQ9B;EACb,YAAY,SAAS,KAAK;EAC1B,WAAW,oBAAoB;EAC/B,WAAW,oBAAoB;EAC/B,WAAW,oBAAoB;EAC/B,UAAU,oBAAoB;;EAG9B,iBAAiB,OAAO,cAAc;;EAGtC,WAAW,eAAe;EAC1B,aAAa,oBAAoB;EACjC,WAAW,oBAAoB;EAC/B,UAAU,oBAAoB;;;iBAIjB;EACb;EACA;EACA;;EAGA;EACA;;;iBAIa;;EAEb;;EAGA;;EAGA,gBAAgB;;EAGhB,WAAW,OAAO;EAClB;EACA;;EAGA"}

package/dist/logger/types.js

@@ -0,0 +1 @@
+export {};

package/dist/math.d.ts

@@ -1,5 +1,4 @@
 import { Decimal } from "decimal.js";
-//#region src/math.d.ts
 type CalculableValue = Decimal.Value | {
   toString: () => string;
 };
@@ -45,5 +44,5 @@ export interface ToPercentageStringOptions {
  * ```
  */
 export declare function toPercentageString(molecular: CalculableValue, denominator: CalculableValue, options?: ToPercentageStringOptions): string;
-//#endregion
+export {};
 //# sourceMappingURL=math.d.ts.map

package/dist/math.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"math.d.ts","names":[],"sources":["../src/math.ts"],"mappings":";;KAEK,kBAAkB,QAAQ;EAAU;;;;;iBAKxB;;;;;;EAMb;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2BY,mBACZ,WAAW,iBACX,aAAa,iBACb,UAAU"}
+{"version":3,"file":"math.d.ts","names":[],"sources":["../src/math.ts"],"mappings":";KAEK,kBAAkB,QAAQ;EAAU;;;;;iBAKxB;;;;;;EAMb;;;;;;EAOA;;;;;;;;;;;;;;;;;;;;;;;;;;wBA2BY,mBACZ,WAAW,iBACX,aAAa,iBACb,UAAU"}

package/dist/math.js

@@ -1,5 +1,5 @@
 import { Decimal } from "decimal.js";
-//#region src/math.ts
+// src/math.ts
 /**
 * Converts a numerator and denominator into a formatted percentage.
 *
@@ -31,7 +31,6 @@ function toPercentageString(molecular, denominator, options) {
 	const result = calculationResult.isNaN() || !calculationResult.isFinite() ? "0.00" : calculationResult.times(100).toFixed(options?.decimalPlaces ?? 2);
 	return options?.withSymbol ?? true ? `${result}%` : result;
 }
-//#endregion
 export { toPercentageString };
 
 //# sourceMappingURL=math.js.map

package/dist/number.d.ts

@@ -1,5 +1,4 @@
 import { millify } from "millify";
-//#region src/number.d.ts
 /**
  * Converts a large number into a compact, human-readable string using `millify`.
  *
@@ -21,5 +20,4 @@ import { millify } from "millify";
  * ```
  */
 export declare function toCompactNumberString(value: number, options?: Parameters<typeof millify>[1]): string;
-//#endregion
 //# sourceMappingURL=number.d.ts.map

package/dist/number.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"number.d.ts","names":[],"sources":["../src/number.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;wBAsBgB,sBAAsB,eAAe,UAAU,kBAAkB"}
+{"version":3,"file":"number.d.ts","names":[],"sources":["../src/number.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;wBAsBgB,sBAAsB,eAAe,UAAU,kBAAkB"}

package/dist/number.js

@@ -1,5 +1,5 @@
 import { millify } from "millify";
-//#region src/number.ts
+// src/number.ts
 /**
 * Converts a large number into a compact, human-readable string using `millify`.
 *
@@ -27,7 +27,6 @@ function toCompactNumberString(value, options) {
 		...options
 	});
 }
-//#endregion
 export { toCompactNumberString };
 
 //# sourceMappingURL=number.js.map

package/dist/random.d.ts

@@ -1,4 +1,3 @@
-//#region src/random.d.ts
 /**
  * Calls a generator once with a length sampled from two nested random ranges.
  *
@@ -23,5 +22,4 @@
  * @throws Error if `minMin` exceeds `minMax` or `maxMin` exceeds `maxMax`.
  */
 export declare function generateWithNestedRandomLength<T = string>(generator: (length: number) => T, minMin: number, minMax: number, maxMin: number, maxMax: number): T;
-//#endregion
 //# sourceMappingURL=random.d.ts.map

package/dist/random.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"random.d.ts","names":[],"sources":["../src/random.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;wBAuBgB,+BAA+B,YAC3C,YAAY,mBAAmB,GAC/B,gBACA,gBACA,gBACA,iBAAc"}
+{"version":3,"file":"random.d.ts","names":[],"sources":["../src/random.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;wBAuBgB,+BAA+B,YAC3C,YAAY,mBAAmB,GAC/B,gBACA,gBACA,gBACA,iBAAc"}

package/dist/random.js

@@ -1,4 +1,4 @@
-//#region src/random.ts
+// src/random.ts
 /**
 * Calls a generator once with a length sampled from two nested random ranges.
 *
@@ -29,7 +29,6 @@ function generateWithNestedRandomLength(generator, minMin, minMax, maxMin, maxMa
 	const innerMin = random(minMin, minMax);
 	return generator(random(Math.max(innerMin, maxMin), maxMax));
 }
-//#endregion
 export { generateWithNestedRandomLength };
 
 //# sourceMappingURL=random.js.map

package/dist/redis/script-runner.d.ts

@@ -1,4 +1,3 @@
-//#region src/redis/script-runner.d.ts
 /**
  * An asynchronous Lua script runner with caller-declared results.
  *
@@ -53,5 +52,4 @@ export interface RedisLikeScriptClient {
  * @throws RangeError if `maxAttempts` is not a positive safe integer.
  */
 export declare function createRedisScriptRunner<T = unknown>(client: RedisLikeScriptClient, source: string, maxAttempts?: number): RedisScriptRunner<T>;
-//#endregion
 //# sourceMappingURL=script-runner.d.ts.map

package/dist/redis/script-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"script-runner.d.ts","names":[],"sources":["../../src/redis/script-runner.ts"],"mappings":";;;;;;;;;;;;;;;YAgBY,kBAAkB,gBAAgB,yBAAyB,uCAAuC,QAC1G;;;;;;;;;iBAWa;;;;;;;EAOb,OAAO,iBAAiB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;wBAwB/B,wBAAwB,aACpC,QAAQ,uBACR,gBACA,uBACD,kBAAkB"}
+{"version":3,"file":"script-runner.d.ts","names":[],"sources":["../../src/redis/script-runner.ts"],"mappings":";;;;;;;;;;;;;;YAgBY,kBAAkB,gBAAgB,yBAAyB,uCAAuC,QAC1G;;;;;;;;;iBAWa;;;;;;;EAOb,OAAO,iBAAiB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;wBAwB/B,wBAAwB,aACpC,QAAQ,uBACR,gBACA,uBACD,kBAAkB"}

package/dist/redis/script-runner.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-//#region src/redis/script-runner.ts
+// src/redis/script-runner.ts
 /**
 * Creates a Lua script runner that reloads missing cached scripts before retrying execution.
 *
@@ -40,7 +40,6 @@ function createRedisScriptRunner(client, source, maxAttempts = 3) {
 		}
 	};
 }
-//#endregion
 export { createRedisScriptRunner };
 
 //# sourceMappingURL=script-runner.js.map

package/dist/storages/lru/keyed-store.d.ts

@@ -1,5 +1,4 @@
 import { LRUCache } from "lru-cache";
-//#region src/storages/lru/keyed-store.d.ts
 /**
  * Creates a keyed cache factory sharing a caller-owned LRU cache.
  *
@@ -7,6 +6,7 @@ import { LRUCache } from "lru-cache";
  * The key resolver is called synchronously once per operation, and its exceptions propagate.
  * Reads return the cached value without copying it, or `null` for missing or nullish values.
  * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.
+ * `setItemWithTtl` accepts its TTL in milliseconds before the value and key arguments and returns the cache.
  * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.
  *
  * @typeParam D - The stored value type used by reads and writes.
@@ -42,6 +42,6 @@ export declare function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<a
    */
   resolveKey: (...args: P) => string;
   setItem: (value: D, ...args: P) => LRUCache<any, any, any>;
+  setItemWithTtl(ttlMilliseconds: number, value: D, ...args: P): LRUCache<any, any, any>;
 }>;
-//#endregion
 //# sourceMappingURL=keyed-store.d.ts.map

package/dist/storages/lru/keyed-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA6BgB,oBAAoB,aAAa,aAAa,2BAClD,iBAAiB,WAAW,MAAM,iBAAY;;;;;;EAMjC,WAAA,MAAA,IAAC,YAAA;EAII,gBAAA,MAAA;EACH,aAAA,MAAA;EACG,gBAAA,MAAA;;;;EAIA,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC"}
+{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA8BgB,oBAAoB,aAAa,aAAa,2BAClD,iBAAiB,WAAW,MAAM,iBAAY;;;;;;EAMjC,WAAA,MAAA,IAAC,YAAA;EAII,gBAAA,MAAA;EACH,aAAA,MAAA;EACG,gBAAA,MAAA;;;;EAIA,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC;EACE,eAAA,yBAAM,OAAS,MAAC,MAAW,IAAC"}

package/dist/storages/lru/keyed-store.js

@@ -1,4 +1,4 @@
-//#region src/storages/lru/keyed-store.ts
+// src/storages/lru/keyed-store.ts
 /**
 * Creates a keyed cache factory sharing a caller-owned LRU cache.
 *
@@ -6,6 +6,7 @@
 * The key resolver is called synchronously once per operation, and its exceptions propagate.
 * Reads return the cached value without copying it, or `null` for missing or nullish values.
 * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.
+* `setItemWithTtl` accepts its TTL in milliseconds before the value and key arguments and returns the cache.
 * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.
 *
 * @typeParam D - The stored value type used by reads and writes.
@@ -43,10 +44,12 @@ function createLruKeyedStore(lruInstance) {
 		* Resolves the full cache key from the given arguments.
 		*/
 		resolveKey: (...args) => keyFn(...args),
-		setItem: (value, ...args) => lruInstance.set(keyFn(...args), value)
+		setItem: (value, ...args) => lruInstance.set(keyFn(...args), value),
+		setItemWithTtl(ttlMilliseconds, value, ...args) {
+			return lruInstance.set(keyFn(...args), value, { ttl: ttlMilliseconds });
+		}
 	});
 }
-//#endregion
 export { createLruKeyedStore };
 
 //# sourceMappingURL=keyed-store.js.map

package/dist/storages/lru/keyed-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.js","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"sourcesContent":["import type { LRUCache } from 'lru-cache';\n\n/**\n * Creates a keyed cache factory sharing a caller-owned LRU cache.\n *\n * @remarks\n * The key resolver is called synchronously once per operation, and its exceptions propagate.\n * Reads return the cached value without copying it, or `null` for missing or nullish values.\n * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.\n * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.\n *\n * @typeParam D - The stored value type used by reads and writes.\n *\n * @param lruInstance - The shared LRU cache instance.\n *\n * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the cache.\n *\n * @example\n *\n * ```ts\n * import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';\n * import { LRUCache } from 'lru-cache';\n *\n * const cache = new LRUCache<string, { name: string }>({ max: 100 });\n * const keyedStore = createLruKeyedStore<{ name: string }>(cache)((userId: string) => `user:${userId}`);\n * keyedStore.setItem({ name: 'Alice' }, 'user-123');\n * console.log(keyedStore.getItem('user-123')); // => { name: 'Alice' }\n * ```\n */\nexport function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {\n    return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({\n        /**\n         * Returns the cached value and applies the underlying cache's read-recency policy.\n         *\n         * @returns The cached value without copying it, or `null` when absent or nullish.\n         */\n        getItem(...args: P) {\n            const rawValue = lruInstance.get(keyFn(...args));\n            return rawValue as D ?? null;\n        },\n        getItemTtl: (...args: P) => lruInstance.getRemainingTTL(keyFn(...args)),\n        hasItem: (...args: P) => lruInstance.has(keyFn(...args)),\n        removeItem: (...args: P) => lruInstance.delete(keyFn(...args)),\n        /**\n         * Resolves the full cache key from the given arguments.\n         */\n        resolveKey: (...args: P) => keyFn(...args),\n        setItem: (value: D, ...args: P) => lruInstance.set(keyFn(...args), value),\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,oBAAiC,aAAsC;CACnF,QAAyB,UAAkC,OAAO,OAAO;;;;;;EAMrE,QAAQ,GAAG,MAAS;GAEhB,OADiB,YAAY,IAAI,MAAM,GAAG,IAAI,CAChC,KAAU;EAC5B;EACA,aAAa,GAAG,SAAY,YAAY,gBAAgB,MAAM,GAAG,IAAI,CAAC;EACtE,UAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;EACvD,aAAa,GAAG,SAAY,YAAY,OAAO,MAAM,GAAG,IAAI,CAAC;;;;EAI7D,aAAa,GAAG,SAAY,MAAM,GAAG,IAAI;EACzC,UAAU,OAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,KAAK;CAC5E,CAAC;AACL"}
+{"version":3,"file":"keyed-store.js","names":[],"sources":["../../../src/storages/lru/keyed-store.ts"],"sourcesContent":["import type { LRUCache } from 'lru-cache';\n\n/**\n * Creates a keyed cache factory sharing a caller-owned LRU cache.\n *\n * @remarks\n * The key resolver is called synchronously once per operation, and its exceptions propagate.\n * Reads return the cached value without copying it, or `null` for missing or nullish values.\n * `getItemTtl` exposes the underlying remaining TTL in milliseconds; `setItem` returns the underlying cache.\n * `setItemWithTtl` accepts its TTL in milliseconds before the value and key arguments and returns the cache.\n * The facade does not dispose the supplied cache, and LRU defaults remain those of the supplied instance.\n *\n * @typeParam D - The stored value type used by reads and writes.\n *\n * @param lruInstance - The shared LRU cache instance.\n *\n * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the cache.\n *\n * @example\n *\n * ```ts\n * import { createLruKeyedStore } from '@kikiutils/shared/storages/lru/keyed-store';\n * import { LRUCache } from 'lru-cache';\n *\n * const cache = new LRUCache<string, { name: string }>({ max: 100 });\n * const keyedStore = createLruKeyedStore<{ name: string }>(cache)((userId: string) => `user:${userId}`);\n * keyedStore.setItem({ name: 'Alice' }, 'user-123');\n * console.log(keyedStore.getItem('user-123')); // => { name: 'Alice' }\n * ```\n */\nexport function createLruKeyedStore<D = unknown>(lruInstance: LRUCache<any, any, any>) {\n    return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({\n        /**\n         * Returns the cached value and applies the underlying cache's read-recency policy.\n         *\n         * @returns The cached value without copying it, or `null` when absent or nullish.\n         */\n        getItem(...args: P) {\n            const rawValue = lruInstance.get(keyFn(...args));\n            return rawValue as D ?? null;\n        },\n        getItemTtl: (...args: P) => lruInstance.getRemainingTTL(keyFn(...args)),\n        hasItem: (...args: P) => lruInstance.has(keyFn(...args)),\n        removeItem: (...args: P) => lruInstance.delete(keyFn(...args)),\n        /**\n         * Resolves the full cache key from the given arguments.\n         */\n        resolveKey: (...args: P) => keyFn(...args),\n        setItem: (value: D, ...args: P) => lruInstance.set(keyFn(...args), value),\n        setItemWithTtl(ttlMilliseconds: number, value: D, ...args: P) {\n            return lruInstance.set(keyFn(...args), value, { ttl: ttlMilliseconds });\n        },\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,SAAgB,oBAAiC,aAAsC;CACnF,QAAyB,UAAkC,OAAO,OAAO;;;;;;EAMrE,QAAQ,GAAG,MAAS;GAEhB,OADiB,YAAY,IAAI,MAAM,GAAG,IAAI,CAChC,KAAU;EAC5B;EACA,aAAa,GAAG,SAAY,YAAY,gBAAgB,MAAM,GAAG,IAAI,CAAC;EACtE,UAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;EACvD,aAAa,GAAG,SAAY,YAAY,OAAO,MAAM,GAAG,IAAI,CAAC;;;;EAI7D,aAAa,GAAG,SAAY,MAAM,GAAG,IAAI;EACzC,UAAU,OAAU,GAAG,SAAY,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,KAAK;EACxE,eAAe,iBAAyB,OAAU,GAAG,MAAS;GAC1D,OAAO,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,OAAO,EAAE,KAAK,gBAAgB,CAAC;EAC1E;CACJ,CAAC;AACL"}

package/dist/storages/redis/keyed-store.d.ts

@@ -1,6 +1,5 @@
 import { MaybeReadonly } from "../../types/index.js";
 import { RedisLikeStorage } from "./types.js";
-//#region src/storages/redis/keyed-store.d.ts
 /**
  * Creates a keyed store factory sharing a caller-owned Redis-like storage facade.
  *
@@ -26,5 +25,4 @@ export declare function createRedisKeyedStore<D = unknown>(storage: MaybeReadonl
   setItem: (value: D, ...args: P) => Promise<boolean>;
   setItemWithTtl(ttlSeconds: number, value: D, ...args: P): Promise<boolean>;
 }>;
-//#endregion
 //# sourceMappingURL=keyed-store.d.ts.map

package/dist/storages/redis/keyed-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/redis/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;;wBAoBgB,sBAAsB,aAAa,SAAS,cAAc,qBAC9D,iBAAiB,WAAW,MAAM,iBAAY;EAC/B,aAAA,MAAA,MAAC,QAAA;EACE,gBAAA,MAAA,MAAC;EACJ,aAAA,MAAA,MAAC;EACE,gBAAA,MAAA,MAAC;EACD,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC;EACH,eAAA,oBAAM,OAAS,MAAC,MAAW,IAAC"}
+{"version":3,"file":"keyed-store.d.ts","names":[],"sources":["../../../src/storages/redis/keyed-store.ts"],"mappings":";;;;;;;;;;;;;;;;;;wBAoBgB,sBAAsB,aAAa,SAAS,cAAc,qBAC9D,iBAAiB,WAAW,MAAM,iBAAY;EAC/B,aAAA,MAAA,MAAC,QAAA;EACE,gBAAA,MAAA,MAAC;EACJ,aAAA,MAAA,MAAC;EACE,gBAAA,MAAA,MAAC;EACD,gBAAA,MAAA;EACL,UAAA,OAAA,MAAC,MAAW,MAAC;EACH,eAAA,oBAAM,OAAS,MAAC,MAAW,IAAC"}

package/dist/storages/redis/keyed-store.js

@@ -1,4 +1,4 @@
-//#region src/storages/redis/keyed-store.ts
+// src/storages/redis/keyed-store.ts
 /**
 * Creates a keyed store factory sharing a caller-owned Redis-like storage facade.
 *
@@ -28,7 +28,6 @@ function createRedisKeyedStore(storage) {
 		}
 	});
 }
-//#endregion
 export { createRedisKeyedStore };
 
 //# sourceMappingURL=keyed-store.js.map

package/dist/storages/redis/msgpack.d.ts

@@ -1,5 +1,4 @@
 import { RedisLikeAdapter, RedisLikeStorage } from "./types.js";
-//#region src/storages/redis/msgpack.d.ts
 /**
  * Creates a frozen Redis-like storage facade using MessagePack serialization.
  *
@@ -42,5 +41,4 @@ import { RedisLikeAdapter, RedisLikeStorage } from "./types.js";
  * ```
  */
 export declare function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage>;
-//#endregion
 //# sourceMappingURL=msgpack.d.ts.map

package/dist/storages/redis/msgpack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"msgpack.d.ts","names":[],"sources":["../../../src/storages/redis/msgpack.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwDgB,0BAA0B,SAAS,mBAAmB,SAAS"}
+{"version":3,"file":"msgpack.d.ts","names":[],"sources":["../../../src/storages/redis/msgpack.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAwDgB,0BAA0B,SAAS,mBAAmB,SAAS"}

package/dist/storages/redis/msgpack.js

@@ -1,5 +1,5 @@
 import { decode, encode, isNativeAccelerationEnabled } from "msgpackr";
-//#region src/storages/redis/msgpack.ts
+// src/storages/redis/msgpack.ts
 if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled for msgpackr, verify that install finished properly");
 /**
 * Creates a frozen Redis-like storage facade using MessagePack serialization.
@@ -57,7 +57,6 @@ function createRedisMsgpackStorage(adapter) {
 		}
 	});
 }
-//#endregion
 export { createRedisMsgpackStorage };
 
 //# sourceMappingURL=msgpack.js.map

package/dist/storages/redis/types.d.ts

@@ -1,4 +1,3 @@
-//#region src/storages/redis/types.d.ts
 /**
  * A caller-owned asynchronous adapter for Redis-like binary operations.
  *
@@ -75,5 +74,4 @@ export interface RedisLikeStorage {
    */
   setItemWithTtl: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
 }
-//#endregion
 //# sourceMappingURL=types.d.ts.map

package/dist/storages/redis/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/storages/redis/types.ts"],"mappings":";;;;;;;;iBAOiB;;;;EAIb,SAAS,gBAAgB;;;;EAKzB,YAAY,gBAAgB,eAAe;;;;EAK3C,MAAM,gBAAgB;;;;EAKtB,YAAY,aAAa,OAAO,eAAe;;;;;;;;EAS/C,cAAc,aAAa,oBAAoB,OAAO,eAAe;;;;EAKrE,MAAM,gBAAgB;;;;;;;;;iBAUT;;;;;;EAMb,UAAU,aAAa,gBAAgB,eAAe;;;;EAKtD,aAAa,gBAAgB;;;;EAK7B,UAAU,gBAAgB;;;;EAK1B,aAAa,gBAAgB;;;;EAK7B,UAAU,aAAa,eAAe;;;;;;;;EAStC,iBAAiB,aAAa,oBAAoB,eAAe"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/storages/redis/types.ts"],"mappings":";;;;;;;iBAOiB;;;;EAIb,SAAS,gBAAgB;;;;EAKzB,YAAY,gBAAgB,eAAe;;;;EAK3C,MAAM,gBAAgB;;;;EAKtB,YAAY,aAAa,OAAO,eAAe;;;;;;;;EAS/C,cAAc,aAAa,oBAAoB,OAAO,eAAe;;;;EAKrE,MAAM,gBAAgB;;;;;;;;;iBAUT;;;;;;EAMb,UAAU,aAAa,gBAAgB,eAAe;;;;EAKtD,aAAa,gBAAgB;;;;EAK7B,UAAU,gBAAgB;;;;EAK1B,aAAa,gBAAgB;;;;EAK7B,UAAU,aAAa,eAAe;;;;;;;;EAStC,iBAAiB,aAAa,oBAAoB,eAAe"}