@kikiutils/shared 20.0.1 → 20.1.0

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

@@ -1 +1 @@
-{"version":3,"file":"logger.js","names":[],"sources":["../../../src/logger/_internals/logger.ts"],"sourcesContent":["import type {\n    Logger,\n    LoggerDiagnostic,\n    LoggerLevel,\n    LoggerMethod,\n    LoggerOptions,\n} from '../types';\n\nimport { loggerMethods } from './levels';\nimport type { LoggerRecord } from './types';\n\ninterface LoggerHooks {\n    /** A non-throwing reporter created by createDiagnosticReporter. */\n    report: (event: LoggerDiagnostic) => void;\n    write: (record: LoggerRecord) => Promise<void> | void;\n}\n\n// Constants/Variables\nconst booleanPresentationKeys = [\n    'console',\n    'icons',\n    'timestamp',\n] as const;\n\nconst stringPresentationKeys = [\n    'prefix',\n    'suffix',\n] as const;\n\n// Functions\n\n/** A non-recursive, rate-limited diagnostic boundary shared by server and browser adapters. */\nexport function createDiagnosticReporter(\n    onError?: (event: Readonly<LoggerDiagnostic>) => void,\n    fallback?: (message: string) => void,\n): (event: LoggerDiagnostic) => void {\n    let reporting = false;\n    let callbackPending = false;\n    const stateByType = new Map<LoggerDiagnostic['type'], { lastReportedAt: number; suppressedCount: number }>();\n\n    return (event) => {\n        if (reporting) return;\n        try {\n            const now = Date.now();\n            const state = stateByType.get(event.type);\n            if (state && now - state.lastReportedAt < 1000) {\n                state.suppressedCount++;\n                return;\n            }\n\n            reporting = true;\n            const suppressedCount = state?.suppressedCount ?? 0;\n            if (suppressedCount) {\n                event = {\n                    ...event,\n                    suppressedCount,\n                };\n            }\n\n            stateByType.set(\n                event.type,\n                {\n                    lastReportedAt: now,\n                    suppressedCount: 0,\n                },\n            );\n\n            try {\n                const summary = suppressedCount ? ` (${suppressedCount} similar diagnostics suppressed)` : '';\n                fallback?.(`[logger] ${event.message}${summary}\\n`);\n            } catch {\n                // Diagnostics must never re-enter the normal logging pipeline.\n            }\n\n            if (!callbackPending) {\n                try {\n                    callbackPending = true;\n                    const result: unknown = onError?.(Object.freeze({ ...event }));\n                    if (result !== null && (typeof result === 'object' || typeof result === 'function')) {\n                        void Promise.resolve(result).then(\n                            () => {\n                                callbackPending = false;\n                            },\n                            () => {\n                                callbackPending = false;\n                            },\n                        );\n                    } else {\n                        callbackPending = false;\n                    }\n                } catch {\n                    callbackPending = false;\n                    // User diagnostic callbacks have the same non-throwing boundary.\n                }\n            }\n        } catch { /* Diagnostics must never escape into the logging pipeline. */ } finally {\n            reporting = false;\n        }\n    };\n}\n\nexport function createLoggerCore(options: LoggerOptions, hooks: LoggerHooks): Readonly<Logger> {\n    validateLevel(options.level);\n    validatePresentation(options);\n    if (options.onError !== undefined && typeof options.onError !== 'function') {\n        throw new TypeError('Logger onError must be a function');\n    }\n\n    const presentation = {\n        console: options.console ?? true,\n        icons: options.icons ?? true,\n        prefix: options.prefix ?? '',\n        suffix: options.suffix ?? '',\n        timestamp: options.timestamp ?? true,\n    };\n\n    const { report } = hooks;\n\n    let override = options.level === 'env' ? undefined : options.level;\n    let previousEnvironment: string | undefined;\n    let currentLevel: LoggerLevel = override ?? 'info';\n    let environmentRead = false;\n\n    function refreshLevel() {\n        if (override !== undefined) return;\n        const input = readEnvironmentLevel();\n        if (environmentRead && input === previousEnvironment) return;\n        environmentRead = true;\n        previousEnvironment = input;\n        const normalized = input?.trim().toLowerCase() || undefined;\n        currentLevel = isLevel(normalized) ? normalized : 'info';\n        if (normalized !== undefined && !isLevel(normalized)) {\n            report({\n                message: 'Invalid LOG_LEVEL; using info',\n                type: 'invalid-level',\n            });\n        }\n    }\n\n    const logger = {\n        configure(configuration) {\n            validatePresentation(configuration);\n            for (const name of booleanPresentationKeys) {\n                const value = configuration[name];\n                if (value !== undefined) presentation[name] = value;\n            }\n\n            for (const name of stringPresentationKeys) {\n                const value = configuration[name];\n                if (value !== undefined) presentation[name] = value;\n            }\n        },\n        isLevelEnabled(level) {\n            if (level !== 'success' && !isLevel(level)) throw new TypeError('Invalid logger level');\n            refreshLevel();\n            return level !== 'silent' && getLevelSeverity(level) >= getLevelSeverity(currentLevel);\n        },\n        setLevel(level) {\n            validateLevel(level);\n            if (level === undefined) throw new TypeError('Invalid logger level');\n            override = level === 'env' ? undefined : level;\n            environmentRead = false;\n            if (override !== undefined) {\n                currentLevel = override;\n            } else {\n                refreshLevel();\n            }\n        },\n    } as Logger;\n\n    for (const type of Object.keys(loggerMethods) as LoggerMethod[]) {\n        logger[type] = async (...args: unknown[]) => {\n            try {\n                refreshLevel();\n                if (loggerMethods[type].severity < getLevelSeverity(currentLevel)) return;\n                await hooks.write({\n                    ...presentation,\n                    args,\n                    date: new Date(),\n                    type,\n                });\n            } catch (error) {\n                report({\n                    error,\n                    message: 'Logger output failed',\n                    type: 'format',\n                });\n            }\n        };\n    }\n\n    return Object.freeze(logger);\n}\n\nfunction getLevelSeverity(level: LoggerLevel | LoggerMethod): number {\n    return level === 'silent' ? Number.POSITIVE_INFINITY : loggerMethods[level].severity;\n}\n\nfunction isLevel(value: unknown): value is LoggerLevel {\n    return typeof value === 'string'\n      && (value === 'silent' || (value !== 'success' && Object.hasOwn(loggerMethods, value)));\n}\n\nfunction readEnvironmentLevel(): string | undefined {\n    return (globalThis as { process?: { env?: { LOG_LEVEL?: string } } }).process?.env?.LOG_LEVEL;\n}\n\nfunction validateLevel(value: unknown): asserts value is 'env' | LoggerLevel | undefined {\n    if (value !== undefined && value !== 'env' && !isLevel(value)) throw new TypeError('Invalid logger level');\n}\n\nfunction validatePresentation(options: Pick<LoggerOptions, 'console' | 'icons' | 'prefix' | 'suffix' | 'timestamp'>) {\n    for (const name of booleanPresentationKeys) {\n        if (options[name] !== undefined && typeof options[name] !== 'boolean') {\n            throw new TypeError(`Logger ${name} must be a boolean`);\n        }\n    }\n\n    for (const name of stringPresentationKeys) {\n        if (options[name] !== undefined && typeof options[name] !== 'string') {\n            throw new TypeError(`Logger ${name} must be a string`);\n        }\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"logger.js","names":[],"sources":["../../../src/logger/_internals/logger.ts"],"sourcesContent":["import type {\n    Logger,\n    LoggerDiagnostic,\n    LoggerLevel,\n    LoggerMethod,\n    LoggerOptions,\n} from '../types';\n\nimport { loggerMethods } from './levels';\nimport type { LoggerRecord } from './types';\n\ninterface LoggerHooks {\n    /**\n     * A non-throwing reporter created by createDiagnosticReporter.\n     */\n    report: (event: LoggerDiagnostic) => void;\n    write: (record: LoggerRecord) => Promise<void> | void;\n}\n\n// Constants/Variables\nconst booleanPresentationKeys = [\n    'console',\n    'icons',\n    'timestamp',\n] as const;\n\nconst stringPresentationKeys = [\n    'prefix',\n    'suffix',\n] as const;\n\n// Functions\n\n/**\n * A non-recursive, rate-limited diagnostic boundary shared by server and browser adapters.\n */\nexport function createDiagnosticReporter(\n    onError?: (event: Readonly<LoggerDiagnostic>) => void,\n    fallback?: (message: string) => void,\n): (event: LoggerDiagnostic) => void {\n    let reporting = false;\n    let callbackPending = false;\n    const stateByType = new Map<LoggerDiagnostic['type'], { lastReportedAt: number; suppressedCount: number }>();\n\n    return (event) => {\n        if (reporting) return;\n        try {\n            const now = Date.now();\n            const state = stateByType.get(event.type);\n            if (state && now - state.lastReportedAt < 1000) {\n                state.suppressedCount++;\n                return;\n            }\n\n            reporting = true;\n            const suppressedCount = state?.suppressedCount ?? 0;\n            if (suppressedCount) {\n                event = {\n                    ...event,\n                    suppressedCount,\n                };\n            }\n\n            stateByType.set(\n                event.type,\n                {\n                    lastReportedAt: now,\n                    suppressedCount: 0,\n                },\n            );\n\n            try {\n                const summary = suppressedCount ? ` (${suppressedCount} similar diagnostics suppressed)` : '';\n                fallback?.(`[logger] ${event.message}${summary}\\n`);\n            } catch {\n                // Diagnostics must never re-enter the normal logging pipeline.\n            }\n\n            if (!callbackPending) {\n                try {\n                    callbackPending = true;\n                    const result: unknown = onError?.(Object.freeze({ ...event }));\n                    if (result !== null && (typeof result === 'object' || typeof result === 'function')) {\n                        void Promise.resolve(result).then(\n                            () => {\n                                callbackPending = false;\n                            },\n                            () => {\n                                callbackPending = false;\n                            },\n                        );\n                    } else {\n                        callbackPending = false;\n                    }\n                } catch {\n                    callbackPending = false;\n                    // User diagnostic callbacks have the same non-throwing boundary.\n                }\n            }\n        } catch { /* Diagnostics must never escape into the logging pipeline. */ } finally {\n            reporting = false;\n        }\n    };\n}\n\nexport function createLoggerCore(options: LoggerOptions, hooks: LoggerHooks): Readonly<Logger> {\n    validateLevel(options.level);\n    validatePresentation(options);\n    if (options.onError !== undefined && typeof options.onError !== 'function') {\n        throw new TypeError('Logger onError must be a function');\n    }\n\n    const presentation = {\n        console: options.console ?? true,\n        icons: options.icons ?? true,\n        prefix: options.prefix ?? '',\n        suffix: options.suffix ?? '',\n        timestamp: options.timestamp ?? true,\n    };\n\n    const { report } = hooks;\n\n    let override = options.level === 'env' ? undefined : options.level;\n    let previousEnvironment: string | undefined;\n    let currentLevel: LoggerLevel = override ?? 'info';\n    let environmentRead = false;\n\n    function refreshLevel() {\n        if (override !== undefined) return;\n        const input = readEnvironmentLevel();\n        if (environmentRead && input === previousEnvironment) return;\n        environmentRead = true;\n        previousEnvironment = input;\n        const normalized = input?.trim().toLowerCase() || undefined;\n        currentLevel = isLevel(normalized) ? normalized : 'info';\n        if (normalized !== undefined && !isLevel(normalized)) {\n            report({\n                message: 'Invalid LOG_LEVEL; using info',\n                type: 'invalid-level',\n            });\n        }\n    }\n\n    const logger = {\n        configure(configuration) {\n            validatePresentation(configuration);\n            for (const name of booleanPresentationKeys) {\n                const value = configuration[name];\n                if (value !== undefined) presentation[name] = value;\n            }\n\n            for (const name of stringPresentationKeys) {\n                const value = configuration[name];\n                if (value !== undefined) presentation[name] = value;\n            }\n        },\n        isLevelEnabled(level) {\n            if (level !== 'success' && !isLevel(level)) throw new TypeError('Invalid logger level');\n            refreshLevel();\n            return level !== 'silent' && getLevelSeverity(level) >= getLevelSeverity(currentLevel);\n        },\n        setLevel(level) {\n            validateLevel(level);\n            if (level === undefined) throw new TypeError('Invalid logger level');\n            override = level === 'env' ? undefined : level;\n            environmentRead = false;\n            if (override !== undefined) {\n                currentLevel = override;\n            } else {\n                refreshLevel();\n            }\n        },\n    } as Logger;\n\n    for (const type of Object.keys(loggerMethods) as LoggerMethod[]) {\n        logger[type] = async (...args: unknown[]) => {\n            try {\n                refreshLevel();\n                if (loggerMethods[type].severity < getLevelSeverity(currentLevel)) return;\n                await hooks.write({\n                    ...presentation,\n                    args,\n                    date: new Date(),\n                    type,\n                });\n            } catch (error) {\n                report({\n                    error,\n                    message: 'Logger output failed',\n                    type: 'format',\n                });\n            }\n        };\n    }\n\n    return Object.freeze(logger);\n}\n\nfunction getLevelSeverity(level: LoggerLevel | LoggerMethod): number {\n    return level === 'silent' ? Number.POSITIVE_INFINITY : loggerMethods[level].severity;\n}\n\nfunction isLevel(value: unknown): value is LoggerLevel {\n    return typeof value === 'string'\n      && (value === 'silent' || (value !== 'success' && Object.hasOwn(loggerMethods, value)));\n}\n\nfunction readEnvironmentLevel(): string | undefined {\n    return (globalThis as { process?: { env?: { LOG_LEVEL?: string } } }).process?.env?.LOG_LEVEL;\n}\n\nfunction validateLevel(value: unknown): asserts value is 'env' | LoggerLevel | undefined {\n    if (value !== undefined && value !== 'env' && !isLevel(value)) throw new TypeError('Invalid logger level');\n}\n\nfunction validatePresentation(options: Pick<LoggerOptions, 'console' | 'icons' | 'prefix' | 'suffix' | 'timestamp'>) {\n    for (const name of booleanPresentationKeys) {\n        if (options[name] !== undefined && typeof options[name] !== 'boolean') {\n            throw new TypeError(`Logger ${name} must be a boolean`);\n        }\n    }\n\n    for (const name of stringPresentationKeys) {\n        if (options[name] !== undefined && typeof options[name] !== 'string') {\n            throw new TypeError(`Logger ${name} must be a string`);\n        }\n    }\n}\n"],"mappings":"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"}

package/dist/logger/node/_internals/file-writer.d.ts

@@ -5,7 +5,9 @@ interface LoggerFileWriter {
   getStats: () => Readonly<NodeLoggerStats>;
   write: (text: string) => Promise<void>;
 }
-/** A bounded admission layer over the stream's own ordered write buffer; not a second FIFO. */
+/**
+ * A bounded admission layer over the stream's own ordered write buffer; not a second FIFO.
+ */
 export declare function createFileWriter(options: LoggerFileOptions, report: (event: LoggerDiagnostic) => void): Promise<Readonly<LoggerFileWriter>>;
 export {};
 //# sourceMappingURL=file-writer.d.ts.map

package/dist/logger/node/_internals/file-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-writer.d.ts","names":[],"sources":["../../../../src/logger/node/_internals/file-writer.ts"],"mappings":";;UAiBU;EACN,aAAa;EACb,gBAAgB,SAAS;EACzB,QAAQ,iBAAiB;;;wBASP,iBAClB,SAAS,mBACT,SAAS,OAAO,4BACjB,QAAQ,SAAS"}
+{"version":3,"file":"file-writer.d.ts","names":[],"sources":["../../../../src/logger/node/_internals/file-writer.ts"],"mappings":";;UAiBU;EACN,aAAa;EACb,gBAAgB,SAAS;EACzB,QAAQ,iBAAiB;;;;;wBAWP,iBAClB,SAAS,mBACT,SAAS,OAAO,4BACjB,QAAQ,SAAS"}

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

@@ -6,7 +6,9 @@ import { createWriteStream } from "node:fs";
 import { fileURLToPath } from "node:url";
 // src/logger/node/_internals/file-writer.ts
 const defaultMaxPendingBytes = 8388608;
-/** A bounded admission layer over the stream's own ordered write buffer; not a second FIFO. */
+/**
+* A bounded admission layer over the stream's own ordered write buffer; not a second FIFO.
+*/
 async function createFileWriter(options, report) {
 	const { maxPendingBytes, path, rotate } = validateFileOptions(options);
 	const createRotatingStream = rotate ? (await import("rotating-file-stream")).createStream : void 0;
@@ -147,7 +149,9 @@ async function createFileWriter(options, report) {
 		}
 	});
 }
-/** Validate before mkdir, stream creation, or other filesystem side effects. */
+/**
+* Validate before mkdir, stream creation, or other filesystem side effects.
+*/
 function validateFileOptions(options) {
 	if (!options || typeof options !== "object" || !(typeof options.path === "string" || options.path instanceof Path || options.path instanceof URL || Buffer.isBuffer(options.path))) throw new TypeError("file.path must be a string, Buffer, file URL, or Path");
 	const path = options.path instanceof URL ? fileURLToPath(options.path) : options.path.toString();

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

@@ -1 +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: () => Readonly<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<Readonly<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 Object.freeze({\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: () => Object.freeze({\n            droppedCount,\n            pendingBytes,\n            writeErrorCount,\n        }),\n        write(text: string) {\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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"}
+{"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: () => Readonly<NodeLoggerStats>;\n    write: (text: string) => Promise<void>;\n}\n\n// Constants/Variables\nconst defaultMaxPendingBytes = 8 * 1024 * 1024;\n\n// Functions\n\n/**\n * A bounded admission layer over the stream's own ordered write buffer; not a second FIFO.\n */\nexport async function createFileWriter(\n    options: LoggerFileOptions,\n    report: (event: LoggerDiagnostic) => void,\n): Promise<Readonly<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 Object.freeze({\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: () => Object.freeze({\n            droppedCount,\n            pendingBytes,\n            writeErrorCount,\n        }),\n        write(text: string) {\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/**\n * Validate before mkdir, stream creation, or other filesystem side effects.\n */\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

@@ -1,4 +1,6 @@
 import { LoggerRecord } from "../../_internals/types.js";
-/** Preserve user ANSI for console output without invoking custom inspect callbacks/getters. */
+/**
+ * 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

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

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

@@ -1,7 +1,9 @@
 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. */
+/**
+* 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,

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

@@ -1 +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"}
+{"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/**\n * Preserve user ANSI for console output without invoking custom inspect callbacks/getters.\n */\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":";;;;;;AAUA,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.js

@@ -76,7 +76,9 @@ async function createNodeLogger(options = {}) {
 		})
 	});
 }
-/** One error listener per shared output stream; retained until its last owning logger calls close(). */
+/**
+* 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) {

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

@@ -1 +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<Readonly<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.freeze({\n        ...logger,\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() ?? Object.freeze({\n            droppedCount: 0,\n            pendingBytes: 0,\n            writeErrorCount: 0,\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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"}
+{"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<Readonly<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.freeze({\n        ...logger,\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\n            return closePromise;\n        },\n        getStats: () => writer?.getStats() ?? Object.freeze({\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().\n */\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":";;;;;;;;AA0BA,MAAM,iCAAiB,IAAI,QAAgD;;;;;;;;AAW3E,eAAsB,iBAAiB,UAA6B,CAAC,GAAkC;CACnG,MAAM,SAAS,yBAAyB,QAAQ,UAAU,YAAY,UAAU,GAAG,OAAO,CAAC;CAC3F,IAAI;CACJ,IAAI,SAAS;CACb,IAAI;CACJ,MAAM,eAAe,CAAC;CACtB,MAAM,iCAAiB,IAAI,IAAwB;CACnD,MAAM,gCAAgB,IAAI,IAAmB;CAC7C,MAAM,SAAS,iBACX,SACA;EACI;EACA,MAAM,QAAQ;GACV,IAAI,QAAQ;IACR,OAAO;KACH,SAAS;KACT,MAAM;IACV,CAAC;IAED;GACJ;GAEA,IAAI,CAAC,OAAO,WAAW,CAAC,QAAQ;GAChC,MAAM,SAAS,QAAQ,oBAAoB,OAAO,IAAI;GAEtD,MAAM,OAAO,uBAAuB,QAAQ,OAAO,WAAW,oBAAoB,MAAM,CAAC;GACzF,IAAI,OAAO,SAAS;IAChB,MAAM,OAAO,GAAG,KAAK;IACrB,eAAe,IAAI,MAAM;IACzB,MAAM,aAAa,aAAa,QAAQ,MAAM,QAAQ,YAAY;IAClE,cAAc,IAAI,UAAU;IAC5B,WAAgB,WAAW,cAAc,OAAO,UAAU,CAAC;IAC3D,MAAM,iBAAiB,QAAQ,MAAM,GAAG,yBAAyB,IAAI,EAAE,GAAG;IAC1E,OAAO,iBACD,QAAQ,IAAI,CACV,YACA,cACJ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IACd;GACV;GAEA,OAAO,QAAQ,MAAM,GAAG,yBAAyB,IAAI,EAAE,GAAG;EAC9D;CACJ,CACJ;CAEA,IAAI,QAAQ,SAAS,KAAA,KAAa,QAAQ,SAAS,OAAO,SAAS,MAAM,iBAAiB,QAAQ,MAAM,MAAM;CAE9G,OAAO,OAAO,OAAO;EACjB,GAAG;EACH,QAAQ;GACJ,IAAI,cAAc,OAAO;GACzB,SAAS;GACT,gBAAgB,YAAY;IACxB,MAAM,QAAQ,IAAI,CACd,QAAQ,MAAM,GACd,GAAG,aACP,CAAC;IAED,KAAK,MAAM,UAAU,gBAAgB;KACjC,MAAM,QAAQ,eAAe,IAAI,MAAM;KACvC,IAAI,CAAC,OAAO;KACZ,MAAM,OAAO,OAAO,YAAY;KAChC,IAAI,CAAC,MAAM,OAAO,MAAM;MACpB,OAAO,IAAI,SAAS,MAAM,OAAO;MACjC,OAAO,IAAI,SAAS,MAAM,OAAO;MACjC,eAAe,OAAO,MAAM;KAChC;IACJ;IAEA,eAAe,MAAM;GACzB,EAAA,CAAG;GAEH,OAAO;EACX;EACA,gBAAgB,QAAQ,SAAS,KAAK,OAAO,OAAO;GAChD,cAAc;GACd,cAAc;GACd,iBAAiB;EACrB,CAAC;CACL,CAAC;AACL;;;;AAKA,SAAS,aACL,QACA,MACA,QACA,OACF;CACE,IAAI,QAAQ,eAAe,IAAI,MAAM;CACrC,IAAI,CAAC,OAAO;EACR,MAAM,0BAAU,IAAI,IAAoC;EACxD,MAAM,WAAW,UAAiB;GAC9B,KAAK,MAAM,UAAU,SAAS,OAAO,KAAK;EAC9C;EAEA,MAAM,gBAAgB,wBAAQ,IAAI,MAAM,wBAAwB,CAAC;EACjE,QAAQ;GACJ;GACA;GACA,wBAAQ,IAAI,IAAI;GAChB;EACJ;EAEA,eAAe,IAAI,QAAQ,KAAK;EAChC,OAAO,GAAG,SAAS,OAAO;EAC1B,OAAO,GAAG,SAAS,OAAO;CAC9B;CAEA,MAAM,OAAO,IAAI,KAAK;CACtB,MAAM,UAAU;CAChB,OAAO,IAAI,SAAe,mBAAmB;EACzC,IAAI,UAAU;EACd,MAAM,UAAU,UAAyB;GACrC,IAAI,SAAS;GACb,UAAU;GACV,QAAQ,QAAQ,OAAO,MAAM;GAC7B,IAAI,OACA,OAAO;IACH;IACA,SAAS;IACT,MAAM;GACV,CAAC;GAGL,eAAe;EACnB;EAEA,QAAQ,QAAQ,IAAI,MAAM;EAC1B,IAAI;GACA,OAAO,MAAM,MAAM,MAAM;EAC7B,SAAS,OAAO;GACZ,OAAO,iBAAiB,QAAQ,wBAAQ,IAAI,MAAM,wBAAwB,CAAC;EAC/E;CACJ,CAAC;AACL"}

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

@@ -1,38 +1,62 @@
 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). */
+/**
+ * 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. */
+  /**
+   * Gzip historical files. Defaults to true.
+   */
   compress?: boolean;
-  /** Number of historical files, excluding the active file. Defaults to 30. */
+  /**
+   * Number of historical files, excluding the active file. Defaults to 30.
+   */
   keepFiles?: number;
-  /** Maximum combined size of historical files. */
+  /**
+   * Maximum combined size of historical files.
+   */
   maxTotalSize?: string;
 } & ({
-  /** Opt-in time rotation aligned to the system's local calendar boundary. */
+  /**
+   * 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. */
+  /**
+   * 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. */
+  /**
+   * Maximum unfinished payload bytes, including data already submitted to the stream.
+   */
   maxPendingBytes?: number;
-  /** Resolved once at creation. The file is opened in append mode. */
+  /**
+   * 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. */
+  /**
+   * 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. */
+  /**
+   * Stop accepting records, finish accepted file writes, then release the stream. Not fsync.
+   */
   close: () => Promise<void>;
-  /** A fresh, frozen file-output snapshot. Dropped/failed records still resolve their logging promises. */
+  /**
+   * A fresh, frozen file-output snapshot. Dropped/failed records still resolve their logging promises.
+   */
   getStats: () => Readonly<NodeLoggerStats>;
 }
 export interface NodeLoggerOptions extends LoggerOptions {
-  /** Disabled by default. Each logger owns at most one fixed file destination. */
+  /**
+   * Disabled by default. Each logger owns at most one fixed file destination.
+   */
   file?: false | LoggerFileOptions;
 }
 export interface NodeLoggerStats {

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

@@ -1 +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,SAAS;;iBAGZ,0BAA0B;;EAEvC,eAAe;;iBAGF;EACb;EACA;EACA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/logger/node/types.ts"],"mappings":";;;;;YASY;;;;EAIR;;;;EAKA;;;;EAKA;;;;;EAME;EACA;;;;;EAMA;EACA;;iBAIW;;;;EAIb;;;;EAKA,MAAM;;;;EAKN,iBAAiB;;iBAGJ,mBAAmB;;;;EAIhC,aAAa;;;;EAKb,gBAAgB,SAAS;;iBAGZ,0BAA0B;;;;EAIvC,eAAe;;iBAGF;EACb;EACA;EACA"}

package/dist/logger/types.d.ts

@@ -1,6 +1,11 @@
-/** Minimum severity to emit; `success` uses the same threshold as `info`. */
+import { SafePromise } from "../types/index.js";
+/**
+ * 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. */
+/**
+ * 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.
@@ -11,40 +16,60 @@ export type LoggerMethod = 'success' | Exclude<LoggerLevel, 'silent'>;
  */
 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. */
+  debug: (...args: unknown[]) => SafePromise<void>;
+  error: (...args: unknown[]) => SafePromise<void>;
+  fatal: (...args: unknown[]) => SafePromise<void>;
+  info: (...args: unknown[]) => SafePromise<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. */
+  /**
+   * 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>;
+  success: (...args: unknown[]) => SafePromise<void>;
+  trace: (...args: unknown[]) => SafePromise<void>;
+  warn: (...args: unknown[]) => SafePromise<void>;
 }
-/** A shallow-frozen failure notification; nested error values retain their original ownership. */
+/**
+ * A shallow-frozen failure notification; nested error values retain their original ownership.
+ */
 export interface LoggerDiagnostic {
   droppedCount?: number;
   error?: unknown;
   message: string;
-  /** Same-type notifications suppressed since the previous emitted diagnostic. */
+  /**
+   * 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. */
+/**
+ * Configuration shared by browser and server loggers.
+ */
 export interface LoggerOptions {
-  /** Enables console output. Defaults to `true`. */
+  /**
+   * Enables console output. Defaults to `true`.
+   */
   console?: boolean;
-  /** Enables Unicode level icons. Defaults to `true`. */
+  /**
+   * Enables Unicode level icons. Defaults to `true`.
+   */
   icons?: boolean;
-  /** Overrides LOG_LEVEL; `env` restores the environment-driven threshold. */
+  /**
+   * Overrides LOG_LEVEL; `env` restores the environment-driven threshold.
+   */
   level?: 'env' | LoggerLevel;
-  /** Best-effort, rate-limited notification; failures in this callback are contained. */
+  /**
+   * Best-effort, rate-limited notification; failures in this callback are contained.
+   */
   onError?: (event: Readonly<LoggerDiagnostic>) => void;
   prefix?: string;
   suffix?: string;
-  /** Enables the fixed local-time millisecond prefix. Defaults to `true`. */
+  /**
+   * Enables the fixed local-time millisecond prefix. Defaults to `true`.
+   */
   timestamp?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/logger/types.ts"],"mappings":";YACY;;YAGA,2BAA2B,QAAQ;;;;;;;;iBAS9B;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,SAAS;EAC3B;EACA;;EAGA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/logger/types.ts"],"mappings":";;;;YAKY;;;;YAKA,2BAA2B,QAAQ;;;;;;;;iBAS9B;EACb,YAAY,SAAS,KAAK;EAC1B,WAAW,oBAAoB;EAC/B,WAAW,oBAAoB;EAC/B,WAAW,oBAAoB;EAC/B,UAAU,oBAAoB;;;;EAK9B,iBAAiB,OAAO,cAAc;;;;EAKtC,WAAW,eAAe;EAC1B,aAAa,oBAAoB;EACjC,WAAW,oBAAoB;EAC/B,UAAU,oBAAoB;;;;;iBAMjB;EACb;EACA;EACA;;;;EAKA;EACA;;;;;iBAMa;;;;EAIb;;;;EAKA;;;;EAKA,gBAAgB;;;;EAKhB,WAAW,OAAO,SAAS;EAC3B;EACA;;;;EAKA"}

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

@@ -12,7 +12,7 @@
  *
  * @returns A promise resolving to the Redis script result after execution completes.
  */
-export type RedisScriptRunner<T = unknown> = (keys: readonly string[], args: readonly (number | string)[]) => Promise<T>;
+export type RedisScriptRunner<T = unknown> = (keys: readonly string[], args: ReadonlyArray<number | string>) => Promise<T>;
 /**
  * A caller-owned Redis client exposing raw command execution.
  *

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,MAAM,mCAAmC,QAC5G;;;;;;;;;iBAWa;;;;;;;EAOb,OAAO,iBAAiB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;wBAwB/B,wBAAwB,aACpC,QAAQ,uBACR,gBACA,uBACD,kBAAkB"}

package/dist/redis/script-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"script-runner.js","names":[],"sources":["../../src/redis/script-runner.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\n\n/**\n * An asynchronous Lua script runner with caller-declared results.\n *\n * @remarks\n * Input arrays are unchanged, and numeric arguments are converted to strings before execution.\n * Results are not cached or validated against the declared type.\n *\n * @typeParam T - The expected Lua result type, without runtime validation.\n *\n * @param keys - The script's Redis keys, in `KEYS` order.\n * @param args - The script's arguments, in `ARGV` order.\n *\n * @returns A promise resolving to the Redis script result after execution completes.\n */\nexport type RedisScriptRunner<T = unknown> = (keys: readonly string[], args: readonly (number | string)[]) => Promise<\n    T\n>;\n\n/**\n * A caller-owned Redis client exposing raw command execution.\n *\n * @remarks\n * The client manages connections and command routing. `SCRIPT LOAD` and `EVALSHA` must target the same server\n * for script-cache recovery to succeed. Missing-script rejections must be `Error` instances whose messages\n * begin with the Redis error code `NOSCRIPT`, followed by whitespace or the end of the message.\n */\nexport interface RedisLikeScriptClient {\n    /**\n     * Sends a raw Redis command and resolves to its reply, or rejects on failure.\n     *\n     * @param command - The Redis command name.\n     * @param args - The command arguments in protocol order.\n     */\n    send: (command: string, args: string[]) => Promise<unknown>;\n}\n\n/**\n * Creates a Lua script runner that reloads missing cached scripts before retrying execution.\n *\n * @remarks\n * Calls use `EVALSHA` with the SHA-1 digest of the source. A `NOSCRIPT` rejection loads the script with\n * `SCRIPT LOAD` before another execution attempt, provided the attempt limit has not been reached.\n * Concurrent cache misses on the same runner share an in-flight load; reuse the runner to share that load.\n * Load failures and errors other than `NOSCRIPT` propagate without retries. The final execution error is\n * preserved when the attempt limit is reached. The runner does not cache results or close the client.\n *\n * @typeParam T - The expected Lua result type, without runtime validation.\n *\n * @param client - The caller-owned client used for raw Redis commands.\n * @param source - The Lua source loaded when the script is absent from the server's cache.\n * @param maxAttempts - The maximum `EVALSHA` attempts per invocation, including the initial attempt.\n * Must be a positive safe integer. Defaults to `3`; `1` disables script loading and retries.\n *\n * @returns A reusable runner sharing the client and any in-flight script load.\n *\n * @throws RangeError if `maxAttempts` is not a positive safe integer.\n */\nexport function createRedisScriptRunner<T = unknown>(\n    client: RedisLikeScriptClient,\n    source: string,\n    maxAttempts: number = 3,\n): RedisScriptRunner<T> {\n    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {\n        throw new RangeError('maxAttempts must be a positive safe integer');\n    }\n\n    const digest = createHash('sha1').update(source).digest('hex');\n    let loadingPromise: Promise<unknown> | undefined;\n\n    return async (keys, args) => {\n        for (let attempt = 1; ; attempt += 1) {\n            try {\n                return await client.send(\n                    'EVALSHA',\n                    [\n                        digest,\n                        String(keys.length),\n                        ...keys,\n                        ...args.map(String),\n                    ],\n                ) as T;\n            } catch (error) {\n                if (\n                    !(error instanceof Error)\n                    || !/^NOSCRIPT(?:\\s|$)/.test(error.message)\n                    || attempt >= maxAttempts\n                ) throw error;\n\n                if (loadingPromise === undefined) {\n                    loadingPromise = client\n                        .send(\n                            'SCRIPT',\n                            [\n                                'LOAD',\n                                source,\n                            ],\n                        )\n                        .finally(() => loadingPromise = undefined);\n                }\n\n                await loadingPromise;\n            }\n        }\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA2DA,SAAgB,wBACZ,QACA,QACA,cAAsB,GACF;CACpB,IAAI,CAAC,OAAO,cAAc,WAAW,KAAK,cAAc,GACpD,MAAM,IAAI,WAAW,6CAA6C;CAGtE,MAAM,SAAS,WAAW,MAAM,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,OAAO,KAAK;CAC7D,IAAI;CAEJ,OAAO,OAAO,MAAM,SAAS;EACzB,KAAK,IAAI,UAAU,IAAK,WAAW,GAC/B,IAAI;GACA,OAAO,MAAM,OAAO,KAChB,WACA;IACI;IACA,OAAO,KAAK,MAAM;IAClB,GAAG;IACH,GAAG,KAAK,IAAI,MAAM;GACtB,CACJ;EACJ,SAAS,OAAO;GACZ,IACI,EAAE,iBAAiB,UAChB,CAAC,oBAAoB,KAAK,MAAM,OAAO,KACvC,WAAW,aAChB,MAAM;GAER,IAAI,mBAAmB,KAAA,GACnB,iBAAiB,OACZ,KACG,UACA,CACI,QACA,MACJ,CACJ,CAAC,CACA,cAAc,iBAAiB,KAAA,CAAS;GAGjD,MAAM;EACV;CAER;AACJ"}
+{"version":3,"file":"script-runner.js","names":[],"sources":["../../src/redis/script-runner.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\n\n/**\n * An asynchronous Lua script runner with caller-declared results.\n *\n * @remarks\n * Input arrays are unchanged, and numeric arguments are converted to strings before execution.\n * Results are not cached or validated against the declared type.\n *\n * @typeParam T - The expected Lua result type, without runtime validation.\n *\n * @param keys - The script's Redis keys, in `KEYS` order.\n * @param args - The script's arguments, in `ARGV` order.\n *\n * @returns A promise resolving to the Redis script result after execution completes.\n */\nexport type RedisScriptRunner<T = unknown> = (keys: readonly string[], args: ReadonlyArray<number | string>) => Promise<\n    T\n>;\n\n/**\n * A caller-owned Redis client exposing raw command execution.\n *\n * @remarks\n * The client manages connections and command routing. `SCRIPT LOAD` and `EVALSHA` must target the same server\n * for script-cache recovery to succeed. Missing-script rejections must be `Error` instances whose messages\n * begin with the Redis error code `NOSCRIPT`, followed by whitespace or the end of the message.\n */\nexport interface RedisLikeScriptClient {\n    /**\n     * Sends a raw Redis command and resolves to its reply, or rejects on failure.\n     *\n     * @param command - The Redis command name.\n     * @param args - The command arguments in protocol order.\n     */\n    send: (command: string, args: string[]) => Promise<unknown>;\n}\n\n/**\n * Creates a Lua script runner that reloads missing cached scripts before retrying execution.\n *\n * @remarks\n * Calls use `EVALSHA` with the SHA-1 digest of the source. A `NOSCRIPT` rejection loads the script with\n * `SCRIPT LOAD` before another execution attempt, provided the attempt limit has not been reached.\n * Concurrent cache misses on the same runner share an in-flight load; reuse the runner to share that load.\n * Load failures and errors other than `NOSCRIPT` propagate without retries. The final execution error is\n * preserved when the attempt limit is reached. The runner does not cache results or close the client.\n *\n * @typeParam T - The expected Lua result type, without runtime validation.\n *\n * @param client - The caller-owned client used for raw Redis commands.\n * @param source - The Lua source loaded when the script is absent from the server's cache.\n * @param maxAttempts - The maximum `EVALSHA` attempts per invocation, including the initial attempt.\n * Must be a positive safe integer. Defaults to `3`; `1` disables script loading and retries.\n *\n * @returns A reusable runner sharing the client and any in-flight script load.\n *\n * @throws RangeError if `maxAttempts` is not a positive safe integer.\n */\nexport function createRedisScriptRunner<T = unknown>(\n    client: RedisLikeScriptClient,\n    source: string,\n    maxAttempts: number = 3,\n): RedisScriptRunner<T> {\n    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {\n        throw new RangeError('maxAttempts must be a positive safe integer');\n    }\n\n    const digest = createHash('sha1').update(source).digest('hex');\n    let loadingPromise: Promise<unknown> | undefined;\n\n    return async (keys, args) => {\n        for (let attempt = 1; ; attempt += 1) {\n            try {\n                return await client.send(\n                    'EVALSHA',\n                    [\n                        digest,\n                        String(keys.length),\n                        ...keys,\n                        ...args.map(String),\n                    ],\n                ) as T;\n            } catch (error) {\n                if (\n                    !(error instanceof Error)\n                    || !/^NOSCRIPT(?:\\s|$)/.test(error.message)\n                    || attempt >= maxAttempts\n                ) throw error;\n\n                if (loadingPromise === undefined) {\n                    loadingPromise = client\n                        .send(\n                            'SCRIPT',\n                            [\n                                'LOAD',\n                                source,\n                            ],\n                        )\n                        .finally(() => loadingPromise = undefined);\n                }\n\n                await loadingPromise;\n            }\n        }\n    };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AA2DA,SAAgB,wBACZ,QACA,QACA,cAAsB,GACF;CACpB,IAAI,CAAC,OAAO,cAAc,WAAW,KAAK,cAAc,GACpD,MAAM,IAAI,WAAW,6CAA6C;CAGtE,MAAM,SAAS,WAAW,MAAM,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,OAAO,KAAK;CAC7D,IAAI;CAEJ,OAAO,OAAO,MAAM,SAAS;EACzB,KAAK,IAAI,UAAU,IAAK,WAAW,GAC/B,IAAI;GACA,OAAO,MAAM,OAAO,KAChB,WACA;IACI;IACA,OAAO,KAAK,MAAM;IAClB,GAAG;IACH,GAAG,KAAK,IAAI,MAAM;GACtB,CACJ;EACJ,SAAS,OAAO;GACZ,IACI,EAAE,iBAAiB,UAChB,CAAC,oBAAoB,KAAK,MAAM,OAAO,KACvC,WAAW,aAChB,MAAM;GAER,IAAI,mBAAmB,KAAA,GACnB,iBAAiB,OACZ,KACG,UACA,CACI,QACA,MACJ,CACJ,CAAC,CACA,cAAc,iBAAiB,KAAA,CAAS;GAGjD,MAAM;EACV;CAER;AACJ"}

package/dist/types/filtered-key-path.d.ts

@@ -8,9 +8,9 @@ type DefaultPath<K extends number | string, V, U = never, RK = `${K}`> = V exten
  * @typeParam U - The value type to select; `never` disables filtering.
  */
 export type FilteredKeyPath<T, U = never> = T extends ReadonlyArray<infer V> ? (IsTuple<T> extends true ? { [K in TupleKey<T>]-?: PathImpl<Exclude<K, symbol>, T[K], U>; }[TupleKey<T>] : PathImpl<number, V, U>) : { [K in keyof T]-?: PathImpl<Exclude<K, symbol>, T[K], U>; }[keyof T];
-type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
+type IsTuple<T extends readonly any[]> = number extends T['length'] ? false : true;
 type PathImpl<K extends number | string, V, U> = [U] extends [never] ? DefaultPath<K, V> : ConditionalPath<K, V, U>;
 type TerminalType = bigint | Blob | boolean | Date | File | null | number | ObjectId | RegExp | string | symbol | undefined;
-type TupleKey<T extends ReadonlyArray<any>> = Exclude<keyof T, keyof any[]>;
+type TupleKey<T extends readonly any[]> = Exclude<keyof T, keyof any[]>;
 export {};
 //# sourceMappingURL=filtered-key-path.d.ts.map

package/dist/types/filtered-key-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filtered-key-path.d.ts","names":[],"sources":["../../src/types/filtered-key-path.ts"],"mappings":";KAKK,gBAAgB,2BAA2B,GAAG,KAAK,UAAU,OAAO,MAAM,YAAY,GAAG,GAAG;KAC5F,YACD,2BACA,GACA,WACA,QAAQ,OACR,UAAU,eAAe,QAAQ,KAAK,gBAAgB,GAAG;;;;;;;YAUjD,gBAAgB,GAAG,aAAa,UAAU,oBAAoB,MAAM,QAAQ,qBAAqB,KAAK,SAAS,OAAO,SAAS,QAAQ,YAAY,EAAE,IAAI,MAAK,SAAS,MAAM,iBAAiB,GAAG,SAAS,WAAW,MAAM,SAAS,QAAQ,YAAY,EAAE,IAAI,YAAW;KAGhR,QAAQ,UAAU,qCAAqC;KACvD,SAAS,2BAA2B,GAAG,MAAM,qBAAqB,YAAY,GAAG,KAAK,gBAAgB,GAAG,GAAG;KAC5G,wBAED,iBAEA,OACA,uBAGA,WACA;KAKC,SAAS,UAAU,sBAAsB,cAAc"}
+{"version":3,"file":"filtered-key-path.d.ts","names":[],"sources":["../../src/types/filtered-key-path.ts"],"mappings":";KAKK,gBAAgB,2BAA2B,GAAG,KAAK,UAAU,OAAO,MAAM,YAAY,GAAG,GAAG;KAC5F,YACD,2BACA,GACA,WACA,QAAQ,OACR,UAAU,eAAe,QAAQ,KAAK,gBAAgB,GAAG;;;;;;;YAUjD,gBAAgB,GAAG,aAAa,UAAU,oBAAoB,MAAM,QAAQ,qBAAqB,KAAK,SAAS,OAAO,SAAS,QAAQ,YAAY,EAAE,IAAI,MAAK,SAAS,MAAM,iBAAiB,GAAG,SAAS,WAAW,MAAM,SAAS,QAAQ,YAAY,EAAE,IAAI,YAAW;KAGhR,QAAQ,2CAA2C;KACnD,SAAS,2BAA2B,GAAG,MAAM,qBAAqB,YAAY,GAAG,KAAK,gBAAgB,GAAG,GAAG;KAC5G,wBAED,iBAEA,OACA,uBAGA,WACA;KAKC,SAAS,4BAA4B,cAAc"}

package/dist/types/index.d.ts

@@ -28,5 +28,12 @@ export type ReadonlyPartialRecord<K extends keyof any, T> = Readonly<PartialReco
  * A readonly `Record`.
  */
 export type ReadonlyRecord<K extends keyof any, T> = Readonly<Record<K, T>>;
+/**
+ * A promise whose rejection is handled internally and can safely be left unawaited.
+ * This type only marks that contract; it does not add runtime rejection handling.
+ */
+export type SafePromise<T> = Promise<T> & {
+  readonly __safePromise?: true;
+};
 export type { FilteredKeyPath };
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":["NodeBlob","NodeFile"],"sources":["../../src/types/index.ts"],"mappings":";;;;;YAWY,cAAc,cAAc,OAAO,SAAS,OAAOA,SAAWC,SAAW;;;;YAKzE;;;;YAKA,aAAa,KAAK,QAAQ,KAAK;;;;YAK/B,cAAc,KAAK,SAAS,KAAK;;;;YAKjC,cAAc,qBAAqB,KAAK,QAAQ,OAAO,GAAG;;;;YAK1D,sBAAsB,qBAAqB,KAAK,SAAS,cAAc,GAAG;;;;YAK1E,eAAe,qBAAqB,KAAK,SAAS,OAAO,GAAG"}
+{"version":3,"file":"index.d.ts","names":["NodeBlob","NodeFile"],"sources":["../../src/types/index.ts"],"mappings":";;;;;YAWY,cAAc,cAAc,OAAO,SAAS,OAAOA,SAAWC,SAAW;;;;YAKzE;;;;YAKA,aAAa,KAAK,QAAQ,KAAK;;;;YAK/B,cAAc,KAAK,SAAS,KAAK;;;;YAKjC,cAAc,qBAAqB,KAAK,QAAQ,OAAO,GAAG;;;;YAK1D,sBAAsB,qBAAqB,KAAK,SAAS,cAAc,GAAG;;;;YAK1E,eAAe,qBAAqB,KAAK,SAAS,OAAO,GAAG;;;;;YAM5D,YAAY,KAAK,QAAQ;WAAgB"}

package/dist/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","names":[],"sources":["../src/url.ts"],"mappings":";;;;;;;;;;;;;wBAagB,yBAAyB,aAAa;;;;;;;;;;;;;wBAwBtC,mBAAmB,iBAAiB;;;;;;;;;;;;;wBAoBpC,sBAAsB,gBAAgB"}
+{"version":3,"file":"url.d.ts","names":[],"sources":["../src/url.ts"],"mappings":";;;;;;;;;;;;;wBAagB,yBAAyB,aAAa;;;;;;;;;;;;;wBAuBtC,mBAAmB,iBAAiB;;;;;;;;;;;;;wBAoBpC,sBAAsB,gBAAgB"}

package/dist/url.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.js","names":[],"sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * @remarks\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param url - The target URL to modify.\n * @param redirectPath - The safe same-origin application path starting with `/` to use as the redirect destination.\n *\n * @returns A new URL string with the `redirect` query parameter.\n *\n * @throws Error if `redirectPath` is not a safe same-origin application path.\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    // eslint-disable-next-line style/max-len\n    if (!isSafeRedirectPath(redirectPath)) throw new Error(`Invalid redirect path: \"${redirectPath}\". Redirect paths must be safe same-origin paths starting with '/'.`);\n\n    const [baseAndHash, rawQuery = ''] = url.split('?');\n    const [base, hash] = (baseAndHash || '').split('#');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    const queryString = searchParams.toString();\n    return hash ? `${base}?${queryString}#${hash}` : `${base}?${queryString}`;\n}\n\n/**\n * Returns whether a value is a safe same-origin redirect path.\n *\n * @remarks\n * Safe redirect paths are absolute application paths such as `/dashboard`.\n * Protocol-relative URLs (`//example.com`), absolute URLs, backslash paths,\n * and non-string values are rejected.\n *\n * @param value - The value to check.\n *\n * @returns Whether the value is safe to use as an application redirect path.\n */\nexport function isSafeRedirectPath(value: unknown): value is string {\n    if (typeof value !== 'string') return false;\n    if (!value.startsWith('/')) return false;\n    if (value.startsWith('//')) return false;\n    if (value.includes('\\\\')) return false;\n    return true;\n}\n\n/**\n * Normalizes a redirect value into a safe same-origin application path.\n *\n * @remarks\n * If an array is provided, the first value is checked. Unsafe values fall back\n * to the provided fallback path.\n *\n * @param value - The redirect value to normalize.\n * @param fallback - The caller-supplied safe fallback path; it is returned unchanged and is not validated.\n *\n * @returns The validated input path, or the unvalidated fallback path.\n */\nexport function normalizeRedirectPath(value: unknown, fallback = '/') {\n    const redirectPath = Array.isArray(value) ? value[0] : value;\n    return isSafeRedirectPath(redirectPath) ? redirectPath : fallback;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,KAAa,cAAsB;CAExE,IAAI,CAAC,mBAAmB,YAAY,GAAG,MAAM,IAAI,MAAM,2BAA2B,aAAa,oEAAoE;CAEnK,MAAM,CAAC,aAAa,WAAW,MAAM,IAAI,MAAM,GAAG;CAClD,MAAM,CAAC,MAAM,SAAS,eAAe,GAAA,CAAI,MAAM,GAAG;CAClD,MAAM,eAAe,IAAI,gBAAgB,QAAQ;CACjD,aAAa,IAAI,YAAY,YAAY;CACzC,MAAM,cAAc,aAAa,SAAS;CAC1C,OAAO,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,SAAS,GAAG,KAAK,GAAG;AAChE;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,OAAiC;CAChE,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,CAAC,MAAM,WAAW,GAAG,GAAG,OAAO;CACnC,IAAI,MAAM,WAAW,IAAI,GAAG,OAAO;CACnC,IAAI,MAAM,SAAS,IAAI,GAAG,OAAO;CACjC,OAAO;AACX;;;;;;;;;;;;;AAcA,SAAgB,sBAAsB,OAAgB,WAAW,KAAK;CAClE,MAAM,eAAe,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;CACvD,OAAO,mBAAmB,YAAY,IAAI,eAAe;AAC7D"}
+{"version":3,"file":"url.js","names":[],"sources":["../src/url.ts"],"sourcesContent":["/**\n * Appends or updates the `redirect` query parameter on a given URL.\n *\n * @remarks\n * Typically used to preserve the user's current path for post-login navigation.\n *\n * @param url - The target URL to modify.\n * @param redirectPath - The safe same-origin application path starting with `/` to use as the redirect destination.\n *\n * @returns A new URL string with the `redirect` query parameter.\n *\n * @throws Error if `redirectPath` is not a safe same-origin application path.\n */\nexport function appendRedirectParamToUrl(url: string, redirectPath: string) {\n    if (!isSafeRedirectPath(redirectPath)) throw new Error(`Invalid redirect path: \"${redirectPath}\". Redirect paths must be safe same-origin paths starting with '/'.`);\n\n    const [baseAndHash, rawQuery = ''] = url.split('?');\n    const [base, hash] = (baseAndHash || '').split('#');\n    const searchParams = new URLSearchParams(rawQuery);\n    searchParams.set('redirect', redirectPath);\n    const queryString = searchParams.toString();\n    return hash ? `${base}?${queryString}#${hash}` : `${base}?${queryString}`;\n}\n\n/**\n * Returns whether a value is a safe same-origin redirect path.\n *\n * @remarks\n * Safe redirect paths are absolute application paths such as `/dashboard`.\n * Protocol-relative URLs (`//example.com`), absolute URLs, backslash paths,\n * and non-string values are rejected.\n *\n * @param value - The value to check.\n *\n * @returns Whether the value is safe to use as an application redirect path.\n */\nexport function isSafeRedirectPath(value: unknown): value is string {\n    if (typeof value !== 'string') return false;\n    if (!value.startsWith('/')) return false;\n    if (value.startsWith('//')) return false;\n    if (value.includes('\\\\')) return false;\n    return true;\n}\n\n/**\n * Normalizes a redirect value into a safe same-origin application path.\n *\n * @remarks\n * If an array is provided, the first value is checked. Unsafe values fall back\n * to the provided fallback path.\n *\n * @param value - The redirect value to normalize.\n * @param fallback - The caller-supplied safe fallback path; it is returned unchanged and is not validated.\n *\n * @returns The validated input path, or the unvalidated fallback path.\n */\nexport function normalizeRedirectPath(value: unknown, fallback = '/') {\n    const redirectPath = Array.isArray(value) ? value[0] : value;\n    return isSafeRedirectPath(redirectPath) ? redirectPath : fallback;\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,yBAAyB,KAAa,cAAsB;CACxE,IAAI,CAAC,mBAAmB,YAAY,GAAG,MAAM,IAAI,MAAM,2BAA2B,aAAa,oEAAoE;CAEnK,MAAM,CAAC,aAAa,WAAW,MAAM,IAAI,MAAM,GAAG;CAClD,MAAM,CAAC,MAAM,SAAS,eAAe,GAAA,CAAI,MAAM,GAAG;CAClD,MAAM,eAAe,IAAI,gBAAgB,QAAQ;CACjD,aAAa,IAAI,YAAY,YAAY;CACzC,MAAM,cAAc,aAAa,SAAS;CAC1C,OAAO,OAAO,GAAG,KAAK,GAAG,YAAY,GAAG,SAAS,GAAG,KAAK,GAAG;AAChE;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,OAAiC;CAChE,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,IAAI,CAAC,MAAM,WAAW,GAAG,GAAG,OAAO;CACnC,IAAI,MAAM,WAAW,IAAI,GAAG,OAAO;CACnC,IAAI,MAAM,SAAS,IAAI,GAAG,OAAO;CACjC,OAAO;AACX;;;;;;;;;;;;;AAcA,SAAgB,sBAAsB,OAAgB,WAAW,KAAK;CAClE,MAAM,eAAe,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK;CACvD,OAAO,mBAAmB,YAAY,IAAI,eAAe;AAC7D"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "20.0.1",
+  "version": "20.1.0",
   "description": "A lightweight and modular utility library for modern JavaScript and TypeScript — includes secure hashing, flexible logging, datetime tools, Vue/web helpers, storage abstraction, and more.",
   "author": "kiki-kanri",
   "license": "MIT",
@@ -146,7 +146,7 @@
   "devDependencies": {
     "@antfu/eslint-config": "^10.0.0",
     "@arethetypeswrong/core": "^0.18.5",
-    "@kikiutils/eslint-config": "^9.3.2",
+    "@kikiutils/eslint-config": "^10.1.0",
     "@kikiutils/tsconfigs": "^7.0.0",
     "@noble/hashes": "^2.4.0",
     "@types/node": "^26.6.6",
@@ -161,7 +161,7 @@
     "eslint": "^10.14.0",
     "file-type": "^22.3.0",
     "jsdom": "^30.1.3",
-    "knip": "^6.44.0",
+    "knip": "^6.44.1",
     "lru-cache": "^11.5.3",
     "millify": "^6.1.0",
     "msgpackr": "^2.1.3",

package/src/buffer.ts

@@ -36,6 +36,5 @@ export async function toBuffer(input: BinaryInput) {
     if (input instanceof ArrayBuffer) return Buffer.from(input);
     if (input instanceof Uint8Array) return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
     if (typeof input.arrayBuffer === 'function') return Buffer.from(await input.arrayBuffer());
-    // eslint-disable-next-line style/max-len
     throw new TypeError('The provided input is not a supported binary type (Blob, Buffer, File, ArrayBuffer, or Uint8Array).');
 }

package/src/classes/enhanced-date.ts

@@ -100,7 +100,7 @@ export class EnhancedDate extends Date {
      *
      * @returns A new `EnhancedDate`, or `Invalid Date` if the array is empty or contains an invalid date.
      */
-    static max(dates: (Date | number)[]) {
+    static max(dates: Array<Date | number>) {
         return new EnhancedDate(dateFns.max(dates));
     }
 
@@ -111,7 +111,7 @@ export class EnhancedDate extends Date {
      *
      * @returns A new `EnhancedDate`, or `Invalid Date` if the array is empty or contains an invalid date.
      */
-    static min(dates: (Date | number)[]) {
+    static min(dates: Array<Date | number>) {
         return new EnhancedDate(dateFns.min(dates));
     }