@kikiutils/shared 19.0.0 → 20.0.1

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

@@ -6,7 +6,7 @@ interface LoggerHooks {
   write: (record: LoggerRecord) => Promise<void> | void;
 }
 /** A non-recursive, rate-limited diagnostic boundary shared by server and browser adapters. */
-export declare function createDiagnosticReporter(onError?: (event: LoggerDiagnostic) => void, fallback?: (message: string) => void): (event: LoggerDiagnostic) => void;
-export declare function createLoggerCore(options: LoggerOptions, hooks: LoggerHooks): Logger;
+export declare function createDiagnosticReporter(onError?: (event: Readonly<LoggerDiagnostic>) => void, fallback?: (message: string) => void): (event: LoggerDiagnostic) => void;
+export declare function createLoggerCore(options: LoggerOptions, hooks: LoggerHooks): Readonly<Logger>;
 export {};
 //# sourceMappingURL=logger.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","names":[],"sources":["../../../src/logger/_internals/logger.ts"],"mappings":";;UAWU;;EAEN,SAAS,OAAO;EAChB,QAAQ,QAAQ,iBAAiB;;;wBAkBrB,yBACZ,WAAW,OAAO,2BAClB,YAAY,4BACZ,OAAO;wBAkEK,iBAAiB,SAAS,eAAe,OAAO,cAAc"}
+{"version":3,"file":"logger.d.ts","names":[],"sources":["../../../src/logger/_internals/logger.ts"],"mappings":";;UAWU;;EAEN,SAAS,OAAO;EAChB,QAAQ,QAAQ,iBAAiB;;;wBAkBrB,yBACZ,WAAW,OAAO,SAAS,4BAC3B,YAAY,4BACZ,OAAO;wBAkEK,iBAAiB,SAAS,eAAe,OAAO,cAAc,SAAS"}

package/dist/logger/_internals/logger.js

@@ -36,7 +36,7 @@ function createDiagnosticReporter(onError, fallback) {
 			} catch {}
 			if (!callbackPending) try {
 				callbackPending = true;
-				const result = onError?.(event);
+				const result = onError?.(Object.freeze({ ...event }));
 				if (result !== null && (typeof result === "object" || typeof result === "function")) Promise.resolve(result).then(() => {
 					callbackPending = false;
 				}, () => {
@@ -124,7 +124,7 @@ function createLoggerCore(options, hooks) {
 			});
 		}
 	};
-	return logger;
+	return Object.freeze(logger);
 }
 function getLevelSeverity(level) {
 	return level === "silent" ? Number.POSITIVE_INFINITY : loggerMethods[level].severity;

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: 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?.(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): 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 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":";;AAkBA,MAAM,0BAA0B;CAC5B;CACA;CACA;AACJ;AAEA,MAAM,yBAAyB,CAC3B,UACA,QACJ;;AAKA,SAAgB,yBACZ,SACA,UACiC;CACjC,IAAI,YAAY;CAChB,IAAI,kBAAkB;CACtB,MAAM,8BAAc,IAAI,IAAmF;CAE3G,QAAQ,UAAU;EACd,IAAI,WAAW;EACf,IAAI;GACA,MAAM,MAAM,KAAK,IAAI;GACrB,MAAM,QAAQ,YAAY,IAAI,MAAM,IAAI;GACxC,IAAI,SAAS,MAAM,MAAM,iBAAiB,KAAM;IAC5C,MAAM;IACN;GACJ;GAEA,YAAY;GACZ,MAAM,kBAAkB,OAAO,mBAAmB;GAClD,IAAI,iBACA,QAAQ;IACJ,GAAG;IACH;GACJ;GAGJ,YAAY,IACR,MAAM,MACN;IACI,gBAAgB;IAChB,iBAAiB;GACrB,CACJ;GAEA,IAAI;IACA,MAAM,UAAU,kBAAkB,KAAK,gBAAgB,oCAAoC;IAC3F,WAAW,YAAY,MAAM,UAAU,QAAQ,GAAG;GACtD,QAAQ,CAER;GAEA,IAAI,CAAC,iBACD,IAAI;IACA,kBAAkB;IAClB,MAAM,SAAkB,UAAU,KAAK;IACvC,IAAI,WAAW,SAAS,OAAO,WAAW,YAAY,OAAO,WAAW,aACpE,QAAa,QAAQ,MAAM,CAAC,CAAC,WACnB;KACF,kBAAkB;IACtB,SACM;KACF,kBAAkB;IACtB,CACJ;SAEA,kBAAkB;GAE1B,QAAQ;IACJ,kBAAkB;GAEtB;EAER,QAAQ,CAAiE,UAAU;GAC/E,YAAY;EAChB;CACJ;AACJ;AAEA,SAAgB,iBAAiB,SAAwB,OAA4B;CACjF,cAAc,QAAQ,KAAK;CAC3B,qBAAqB,OAAO;CAC5B,IAAI,QAAQ,YAAY,KAAA,KAAa,OAAO,QAAQ,YAAY,YAC5D,MAAM,IAAI,UAAU,mCAAmC;CAG3D,MAAM,eAAe;EACjB,SAAS,QAAQ,WAAW;EAC5B,OAAO,QAAQ,SAAS;EACxB,QAAQ,QAAQ,UAAU;EAC1B,QAAQ,QAAQ,UAAU;EAC1B,WAAW,QAAQ,aAAa;CACpC;CAEA,MAAM,EAAE,WAAW;CAEnB,IAAI,WAAW,QAAQ,UAAU,QAAQ,KAAA,IAAY,QAAQ;CAC7D,IAAI;CACJ,IAAI,eAA4B,YAAY;CAC5C,IAAI,kBAAkB;CAEtB,SAAS,eAAe;EACpB,IAAI,aAAa,KAAA,GAAW;EAC5B,MAAM,QAAQ,qBAAqB;EACnC,IAAI,mBAAmB,UAAU,qBAAqB;EACtD,kBAAkB;EAClB,sBAAsB;EACtB,MAAM,aAAa,OAAO,KAAK,CAAC,CAAC,YAAY,KAAK,KAAA;EAClD,eAAe,QAAQ,UAAU,IAAI,aAAa;EAClD,IAAI,eAAe,KAAA,KAAa,CAAC,QAAQ,UAAU,GAC/C,OAAO;GACH,SAAS;GACT,MAAM;EACV,CAAC;CAET;CAEA,MAAM,SAAS;EACX,UAAU,eAAe;GACrB,qBAAqB,aAAa;GAClC,KAAK,MAAM,QAAQ,yBAAyB;IACxC,MAAM,QAAQ,cAAc;IAC5B,IAAI,UAAU,KAAA,GAAW,aAAa,QAAQ;GAClD;GAEA,KAAK,MAAM,QAAQ,wBAAwB;IACvC,MAAM,QAAQ,cAAc;IAC5B,IAAI,UAAU,KAAA,GAAW,aAAa,QAAQ;GAClD;EACJ;EACA,eAAe,OAAO;GAClB,IAAI,UAAU,aAAa,CAAC,QAAQ,KAAK,GAAG,MAAM,IAAI,UAAU,sBAAsB;GACtF,aAAa;GACb,OAAO,UAAU,YAAY,iBAAiB,KAAK,KAAK,iBAAiB,YAAY;EACzF;EACA,SAAS,OAAO;GACZ,cAAc,KAAK;GACnB,IAAI,UAAU,KAAA,GAAW,MAAM,IAAI,UAAU,sBAAsB;GACnE,WAAW,UAAU,QAAQ,KAAA,IAAY;GACzC,kBAAkB;GAClB,IAAI,aAAa,KAAA,GACb,eAAe;QAEf,aAAa;EAErB;CACJ;CAEA,KAAK,MAAM,QAAQ,OAAO,KAAK,aAAa,GACxC,OAAO,QAAQ,OAAO,GAAG,SAAoB;EACzC,IAAI;GACA,aAAa;GACb,IAAI,cAAc,KAAK,CAAC,WAAW,iBAAiB,YAAY,GAAG;GACnE,MAAM,MAAM,MAAM;IACd,GAAG;IACH;IACA,sBAAM,IAAI,KAAK;IACf;GACJ,CAAC;EACL,SAAS,OAAO;GACZ,OAAO;IACH;IACA,SAAS;IACT,MAAM;GACV,CAAC;EACL;CACJ;CAGJ,OAAO;AACX;AAEA,SAAS,iBAAiB,OAA2C;CACjE,OAAO,UAAU,WAAW,OAAO,oBAAoB,cAAc,MAAM,CAAC;AAChF;AAEA,SAAS,QAAQ,OAAsC;CACnD,OAAO,OAAO,UAAU,aAClB,UAAU,YAAa,UAAU,aAAa,OAAO,OAAO,eAAe,KAAK;AAC1F;AAEA,SAAS,uBAA2C;CAChD,OAAQ,WAA8D,SAAS,KAAK;AACxF;AAEA,SAAS,cAAc,OAAkE;CACrF,IAAI,UAAU,KAAA,KAAa,UAAU,SAAS,CAAC,QAAQ,KAAK,GAAG,MAAM,IAAI,UAAU,sBAAsB;AAC7G;AAEA,SAAS,qBAAqB,SAAuF;CACjH,KAAK,MAAM,QAAQ,yBACf,IAAI,QAAQ,UAAU,KAAA,KAAa,OAAO,QAAQ,UAAU,WACxD,MAAM,IAAI,UAAU,UAAU,KAAK,mBAAmB;CAI9D,KAAK,MAAM,QAAQ,wBACf,IAAI,QAAQ,UAAU,KAAA,KAAa,OAAO,QAAQ,UAAU,UACxD,MAAM,IAAI,UAAU,UAAU,KAAK,kBAAkB;AAGjE"}
+{"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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"}

package/dist/logger/index.d.ts

@@ -6,5 +6,5 @@ import { Logger, LoggerOptions } from "./types.js";
  * waits for the console invocation, not display or durable delivery. Unspecified
  * levels follow LOG_LEVEL when a process environment is available, otherwise info.
  */
-export declare function createLogger(options?: LoggerOptions): Logger;
+export declare function createLogger(options?: LoggerOptions): Readonly<Logger>;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/logger/index.ts"],"mappings":";;;;;;;;wBAoBgB,aAAa,UAAS,gBAAqB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/logger/index.ts"],"mappings":";;;;;;;;wBAoBgB,aAAa,UAAS,gBAAqB,SAAS"}

package/dist/logger/index.js

@@ -1,5 +1,5 @@
-import { loggerMethods } from "./_internals/levels.js";
 import { formatLoggerConsoleArgs } from "./_internals/formatter.js";
+import { loggerMethods } from "./_internals/levels.js";
 import { createDiagnosticReporter, createLoggerCore } from "./_internals/logger.js";
 // src/logger/index.ts
 /**

package/dist/logger/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/logger/index.ts"],"sourcesContent":["import { formatLoggerConsoleArgs } from './_internals/formatter';\nimport { loggerMethods } from './_internals/levels';\nimport {\n    createDiagnosticReporter,\n    createLoggerCore,\n} from './_internals/logger';\nimport type {\n    Logger,\n    LoggerOptions,\n} from './types';\n\n// Functions\n\n/**\n * Creates an independent, browser-safe console logger.\n *\n * Log calls never throw or reject for recoverable output failures. Awaiting a call\n * waits for the console invocation, not display or durable delivery. Unspecified\n * levels follow LOG_LEVEL when a process environment is available, otherwise info.\n */\nexport function createLogger(options: LoggerOptions = {}): Logger {\n    const target = globalThis.console;\n    const fallback = target?.error?.bind(target);\n    return createLoggerCore(\n        options,\n        {\n            report: createDiagnosticReporter(options.onError, (message) => fallback?.(message.trimEnd())),\n            write(record) {\n                if (!record.console) return;\n                target?.[loggerMethods[record.type].consoleMethod](...formatLoggerConsoleArgs(record));\n            },\n        },\n    );\n}\n"],"mappings":";;;;;;;;;;;AAoBA,SAAgB,aAAa,UAAyB,CAAC,GAAW;CAC9D,MAAM,SAAS,WAAW;CAC1B,MAAM,WAAW,QAAQ,OAAO,KAAK,MAAM;CAC3C,OAAO,iBACH,SACA;EACI,QAAQ,yBAAyB,QAAQ,UAAU,YAAY,WAAW,QAAQ,QAAQ,CAAC,CAAC;EAC5F,MAAM,QAAQ;GACV,IAAI,CAAC,OAAO,SAAS;GACrB,SAAS,cAAc,OAAO,KAAK,CAAC,cAAc,CAAC,GAAG,wBAAwB,MAAM,CAAC;EACzF;CACJ,CACJ;AACJ"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/logger/index.ts"],"sourcesContent":["import { formatLoggerConsoleArgs } from './_internals/formatter';\nimport { loggerMethods } from './_internals/levels';\nimport {\n    createDiagnosticReporter,\n    createLoggerCore,\n} from './_internals/logger';\nimport type {\n    Logger,\n    LoggerOptions,\n} from './types';\n\n// Functions\n\n/**\n * Creates an independent, browser-safe console logger.\n *\n * Log calls never throw or reject for recoverable output failures. Awaiting a call\n * waits for the console invocation, not display or durable delivery. Unspecified\n * levels follow LOG_LEVEL when a process environment is available, otherwise info.\n */\nexport function createLogger(options: LoggerOptions = {}): Readonly<Logger> {\n    const target = globalThis.console;\n    const fallback = target?.error?.bind(target);\n    return createLoggerCore(\n        options,\n        {\n            report: createDiagnosticReporter(options.onError, (message) => fallback?.(message.trimEnd())),\n            write(record) {\n                if (!record.console) return;\n                target?.[loggerMethods[record.type].consoleMethod](...formatLoggerConsoleArgs(record));\n            },\n        },\n    );\n}\n"],"mappings":";;;;;;;;;;;AAoBA,SAAgB,aAAa,UAAyB,CAAC,GAAqB;CACxE,MAAM,SAAS,WAAW;CAC1B,MAAM,WAAW,QAAQ,OAAO,KAAK,MAAM;CAC3C,OAAO,iBACH,SACA;EACI,QAAQ,yBAAyB,QAAQ,UAAU,YAAY,WAAW,QAAQ,QAAQ,CAAC,CAAC;EAC5F,MAAM,QAAQ;GACV,IAAI,CAAC,OAAO,SAAS;GACrB,SAAS,cAAc,OAAO,KAAK,CAAC,cAAc,CAAC,GAAG,wBAAwB,MAAM,CAAC;EACzF;CACJ,CACJ;AACJ"}

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

@@ -2,10 +2,10 @@ import { LoggerDiagnostic } from "../../types.js";
 import { LoggerFileOptions, NodeLoggerStats } from "../types.js";
 interface LoggerFileWriter {
   close: () => Promise<void>;
-  getStats: () => NodeLoggerStats;
+  getStats: () => Readonly<NodeLoggerStats>;
   write: (text: string) => Promise<void>;
 }
 /** 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<LoggerFileWriter>;
+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;EAChB,QAAQ,iBAAiB;;;wBASP,iBAClB,SAAS,mBACT,SAAS,OAAO,4BACjB,QAAQ"}
+{"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"}

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

@@ -83,7 +83,7 @@ async function createFileWriter(options, report) {
 		rejectInitialization = void 0;
 		initializing = false;
 	}
-	return {
+	return Object.freeze({
 		close() {
 			if (closePromise) return closePromise;
 			closing = true;
@@ -101,7 +101,7 @@ async function createFileWriter(options, report) {
 			});
 			return closePromise;
 		},
-		getStats: () => ({
+		getStats: () => Object.freeze({
 			droppedCount,
 			pendingBytes,
 			writeErrorCount
@@ -145,7 +145,7 @@ async function createFileWriter(options, report) {
 				}
 			});
 		}
-	};
+	});
 }
 /** Validate before mkdir, stream creation, or other filesystem side effects. */
 function validateFileOptions(options) {

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: () => 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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"}
+{"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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"}

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

@@ -6,5 +6,5 @@ import { NodeLogger, NodeLoggerOptions } from "./types.js";
  * 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>;
+export declare function createNodeLogger(options?: NodeLoggerOptions): Promise<Readonly<NodeLogger>>;
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/logger/node/index.js

@@ -1,5 +1,5 @@
-import { getLoggerStreamName } from "../_internals/levels.js";
 import { supportsLoggerColor } from "../_internals/formatter.js";
+import { getLoggerStreamName } from "../_internals/levels.js";
 import { createDiagnosticReporter, createLoggerCore } from "../_internals/logger.js";
 import { createFileWriter } from "./_internals/file-writer.js";
 import { formatNodeLoggerRecord } from "./_internals/formatter.js";
@@ -48,7 +48,8 @@ async function createNodeLogger(options = {}) {
 		}
 	});
 	if (options.file !== void 0 && options.file !== false) writer = await createFileWriter(options.file, report);
-	return Object.assign(logger, {
+	return Object.freeze({
+		...logger,
 		close() {
 			if (closePromise) return closePromise;
 			closed = true;
@@ -68,11 +69,11 @@ async function createNodeLogger(options = {}) {
 			})();
 			return closePromise;
 		},
-		getStats: () => writer?.getStats() ?? {
+		getStats: () => writer?.getStats() ?? Object.freeze({
 			droppedCount: 0,
 			pendingBytes: 0,
 			writeErrorCount: 0
-		}
+		})
 	});
 }
 /** One error listener per shared output stream; retained until its last owning logger calls close(). */

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<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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"}
+{"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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"}

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

@@ -28,8 +28,8 @@ export interface LoggerFileOptions {
 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;
+  /** 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. */

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;;iBAGH,0BAA0B;;EAEvC,eAAe;;iBAGF;EACb;EACA;EACA"}
+{"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"}

package/dist/logger/types.d.ts

@@ -7,6 +7,7 @@ export type LoggerMethod = 'success' | Exclude<LoggerLevel, 'silent'>;
  *
  * Awaiting a method waits for processing, not guaranteed successful delivery or fsync.
  * Configuration errors may throw from the factory, configure(), or setLevel().
+ * Factories freeze the API object; settings remain adjustable through its methods.
  */
 export interface Logger {
   configure: (options: Pick<LoggerOptions, 'console' | 'icons' | 'prefix' | 'suffix' | 'timestamp'>) => void;
@@ -22,7 +23,7 @@ export interface Logger {
   trace: (...args: unknown[]) => Promise<void>;
   warn: (...args: unknown[]) => Promise<void>;
 }
-/** A recoverable logging failure, reported without throwing from log methods. */
+/** A shallow-frozen failure notification; nested error values retain their original ownership. */
 export interface LoggerDiagnostic {
   droppedCount?: number;
   error?: unknown;
@@ -40,7 +41,7 @@ export interface LoggerOptions {
   /** 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;
+  onError?: (event: Readonly<LoggerDiagnostic>) => void;
   prefix?: string;
   suffix?: string;
   /** Enables the fixed local-time millisecond prefix. Defaults to `true`. */

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;;;;;;;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"}
+{"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"}

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

@@ -6,7 +6,7 @@ import { RedisLikeStorage } from "./types.js";
  * @remarks
  * The key resolver is called synchronously once per operation with the operation's key arguments.
  * Resolver exceptions propagate synchronously; asynchronous storage failures retain the underlying rejection.
- * `setItemWithTtl` accepts its TTL in seconds before the value and key arguments.
+ * `setItemWithTtl` and `setItemWithTtlIfAbsent` accept their TTL in seconds before the value and key arguments.
  * The factory does not open or close the underlying connection; cleanup remains the caller's responsibility.
  *
  * @typeParam D - The stored value type used by reads and writes.
@@ -14,9 +14,10 @@ import { RedisLikeStorage } from "./types.js";
  * @param storage - The shared Redis-like storage instance.
  *
  * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the storage.
- * Reads, writes, removals, and TTL results retain the underlying storage contract.
+ * Reads, atomic read-and-removals, writes, removals, and TTL results retain the underlying storage contract.
  */
 export declare function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>): <P extends any[]>(keyFn: (...args: P) => string) => Readonly<{
+  getAndRemoveItem: (...args: P) => Promise<D | null>;
   getItem: (...args: P) => Promise<D | null>;
   getItemTtl: (...args: P) => Promise<number>;
   hasItem: (...args: P) => Promise<boolean>;
@@ -24,5 +25,6 @@ export declare function createRedisKeyedStore<D = unknown>(storage: MaybeReadonl
   resolveKey: (...args: P) => string;
   setItem: (value: D, ...args: P) => Promise<boolean>;
   setItemWithTtl(ttlSeconds: number, value: D, ...args: P): Promise<boolean>;
+  setItemWithTtlIfAbsent(ttlSeconds: number, value: D, ...args: P): Promise<boolean>;
 }>;
 //# 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;EACtB,sBAAA,MAAA,MAAC,QAAA;EACV,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;EAGpB,uBAAA,oBAAM,OAAS,MAAC,MAAW,IAAC"}

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

@@ -5,7 +5,7 @@
 * @remarks
 * The key resolver is called synchronously once per operation with the operation's key arguments.
 * Resolver exceptions propagate synchronously; asynchronous storage failures retain the underlying rejection.
-* `setItemWithTtl` accepts its TTL in seconds before the value and key arguments.
+* `setItemWithTtl` and `setItemWithTtlIfAbsent` accept their TTL in seconds before the value and key arguments.
 * The factory does not open or close the underlying connection; cleanup remains the caller's responsibility.
 *
 * @typeParam D - The stored value type used by reads and writes.
@@ -13,10 +13,11 @@
 * @param storage - The shared Redis-like storage instance.
 *
 * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the storage.
-* Reads, writes, removals, and TTL results retain the underlying storage contract.
+* Reads, atomic read-and-removals, writes, removals, and TTL results retain the underlying storage contract.
 */
 function createRedisKeyedStore(storage) {
 	return (keyFn) => Object.freeze({
+		getAndRemoveItem: (...args) => storage.getAndRemoveItem(keyFn(...args)),
 		getItem: (...args) => storage.getItem(keyFn(...args)),
 		getItemTtl: (...args) => storage.getItemTtl(keyFn(...args)),
 		hasItem: (...args) => storage.hasItem(keyFn(...args)),
@@ -25,6 +26,9 @@ function createRedisKeyedStore(storage) {
 		setItem: (value, ...args) => storage.setItem(keyFn(...args), value),
 		setItemWithTtl(ttlSeconds, value, ...args) {
 			return storage.setItemWithTtl(keyFn(...args), ttlSeconds, value);
+		},
+		setItemWithTtlIfAbsent(ttlSeconds, value, ...args) {
+			return storage.setItemWithTtlIfAbsent(keyFn(...args), ttlSeconds, value);
 		}
 	});
 }

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

@@ -1 +1 @@
-{"version":3,"file":"keyed-store.js","names":[],"sources":["../../../src/storages/redis/keyed-store.ts"],"sourcesContent":["import type { MaybeReadonly } from '../../types';\n\nimport type { RedisLikeStorage } from './types';\n\n/**\n * Creates a keyed store factory sharing a caller-owned Redis-like storage facade.\n *\n * @remarks\n * The key resolver is called synchronously once per operation with the operation's key arguments.\n * Resolver exceptions propagate synchronously; asynchronous storage failures retain the underlying rejection.\n * `setItemWithTtl` accepts its TTL in seconds before the value and key arguments.\n * The factory does not open or close the underlying connection; cleanup remains the caller's responsibility.\n *\n * @typeParam D - The stored value type used by reads and writes.\n *\n * @param storage - The shared Redis-like storage instance.\n *\n * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the storage.\n * Reads, writes, removals, and TTL results retain the underlying storage contract.\n */\nexport function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>) {\n    return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({\n        getItem: (...args: P) => storage.getItem<D>(keyFn(...args)),\n        getItemTtl: (...args: P) => storage.getItemTtl(keyFn(...args)),\n        hasItem: (...args: P) => storage.hasItem(keyFn(...args)),\n        removeItem: (...args: P) => storage.removeItem(keyFn(...args)),\n        resolveKey: (...args: P) => keyFn(...args),\n        setItem: (value: D, ...args: P) => storage.setItem(keyFn(...args), value),\n        setItemWithTtl(ttlSeconds: number, value: D, ...args: P) {\n            return storage.setItemWithTtl(keyFn(...args), ttlSeconds, value);\n        },\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAoBA,SAAgB,sBAAmC,SAA0C;CACzF,QAAyB,UAAkC,OAAO,OAAO;EACrE,UAAU,GAAG,SAAY,QAAQ,QAAW,MAAM,GAAG,IAAI,CAAC;EAC1D,aAAa,GAAG,SAAY,QAAQ,WAAW,MAAM,GAAG,IAAI,CAAC;EAC7D,UAAU,GAAG,SAAY,QAAQ,QAAQ,MAAM,GAAG,IAAI,CAAC;EACvD,aAAa,GAAG,SAAY,QAAQ,WAAW,MAAM,GAAG,IAAI,CAAC;EAC7D,aAAa,GAAG,SAAY,MAAM,GAAG,IAAI;EACzC,UAAU,OAAU,GAAG,SAAY,QAAQ,QAAQ,MAAM,GAAG,IAAI,GAAG,KAAK;EACxE,eAAe,YAAoB,OAAU,GAAG,MAAS;GACrD,OAAO,QAAQ,eAAe,MAAM,GAAG,IAAI,GAAG,YAAY,KAAK;EACnE;CACJ,CAAC;AACL"}
+{"version":3,"file":"keyed-store.js","names":[],"sources":["../../../src/storages/redis/keyed-store.ts"],"sourcesContent":["import type { MaybeReadonly } from '../../types';\n\nimport type { RedisLikeStorage } from './types';\n\n/**\n * Creates a keyed store factory sharing a caller-owned Redis-like storage facade.\n *\n * @remarks\n * The key resolver is called synchronously once per operation with the operation's key arguments.\n * Resolver exceptions propagate synchronously; asynchronous storage failures retain the underlying rejection.\n * `setItemWithTtl` and `setItemWithTtlIfAbsent` accept their TTL in seconds before the value and key arguments.\n * The factory does not open or close the underlying connection; cleanup remains the caller's responsibility.\n *\n * @typeParam D - The stored value type used by reads and writes.\n *\n * @param storage - The shared Redis-like storage instance.\n *\n * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the storage.\n * Reads, atomic read-and-removals, writes, removals, and TTL results retain the underlying storage contract.\n */\nexport function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>) {\n    return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({\n        getAndRemoveItem: (...args: P) => storage.getAndRemoveItem<D>(keyFn(...args)),\n        getItem: (...args: P) => storage.getItem<D>(keyFn(...args)),\n        getItemTtl: (...args: P) => storage.getItemTtl(keyFn(...args)),\n        hasItem: (...args: P) => storage.hasItem(keyFn(...args)),\n        removeItem: (...args: P) => storage.removeItem(keyFn(...args)),\n        resolveKey: (...args: P) => keyFn(...args),\n        setItem: (value: D, ...args: P) => storage.setItem(keyFn(...args), value),\n        setItemWithTtl(ttlSeconds: number, value: D, ...args: P) {\n            return storage.setItemWithTtl(keyFn(...args), ttlSeconds, value);\n        },\n        setItemWithTtlIfAbsent(ttlSeconds: number, value: D, ...args: P) {\n            return storage.setItemWithTtlIfAbsent(keyFn(...args), ttlSeconds, value);\n        },\n    });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAoBA,SAAgB,sBAAmC,SAA0C;CACzF,QAAyB,UAAkC,OAAO,OAAO;EACrE,mBAAmB,GAAG,SAAY,QAAQ,iBAAoB,MAAM,GAAG,IAAI,CAAC;EAC5E,UAAU,GAAG,SAAY,QAAQ,QAAW,MAAM,GAAG,IAAI,CAAC;EAC1D,aAAa,GAAG,SAAY,QAAQ,WAAW,MAAM,GAAG,IAAI,CAAC;EAC7D,UAAU,GAAG,SAAY,QAAQ,QAAQ,MAAM,GAAG,IAAI,CAAC;EACvD,aAAa,GAAG,SAAY,QAAQ,WAAW,MAAM,GAAG,IAAI,CAAC;EAC7D,aAAa,GAAG,SAAY,MAAM,GAAG,IAAI;EACzC,UAAU,OAAU,GAAG,SAAY,QAAQ,QAAQ,MAAM,GAAG,IAAI,GAAG,KAAK;EACxE,eAAe,YAAoB,OAAU,GAAG,MAAS;GACrD,OAAO,QAAQ,eAAe,MAAM,GAAG,IAAI,GAAG,YAAY,KAAK;EACnE;EACA,uBAAuB,YAAoB,OAAU,GAAG,MAAS;GAC7D,OAAO,QAAQ,uBAAuB,MAAM,GAAG,IAAI,GAAG,YAAY,KAAK;EAC3E;CACJ,CAAC;AACL"}

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

@@ -4,7 +4,8 @@ import { RedisLikeAdapter, RedisLikeStorage } from "./types.js";
  *
  * @remarks
  * Adapter rejections and MessagePack serialization errors propagate to the caller.
- * Reads resolve to `null` when no raw value exists. Writes resolve to `true` only when the adapter returns `OK`;
+ * Reads resolve to `null` when no raw value exists; `getAndRemoveItem` reads and deletes in one atomic adapter call.
+ * Writes resolve to `true` only when the adapter returns `OK`;
  * removal resolves to `true` only when exactly one key is deleted.
  * The adapter remains caller-owned; creating the facade does not open or close a connection.
  *
@@ -23,6 +24,11 @@ import { RedisLikeAdapter, RedisLikeStorage } from "./types.js";
  * const adapter: RedisLikeAdapter = {
  *     delete: async (key) => values.delete(key) ? 1 : 0,
  *     getBuffer: async (key) => values.get(key) ?? null,
+ *     getBufferAndDelete: async (key) => {
+ *         const value = values.get(key) ?? null;
+ *         values.delete(key);
+ *         return value;
+ *     },
  *     has: async (key) => values.has(key),
  *     setBuffer: async (key, value) => {
  *         values.set(key, value);
@@ -31,6 +37,9 @@ import { RedisLikeAdapter, RedisLikeStorage } from "./types.js";
  *     setBufferEx: async () => {
  *         throw new Error('TTL writes are not supported by this example adapter');
  *     },
+ *     setBufferExNx: async () => {
+ *         throw new Error('TTL writes are not supported by this example adapter');
+ *     },
  *     ttl: async (key) => values.has(key) ? -1 : -2,
  * };
  *

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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAiEgB,0BAA0B,SAAS,mBAAmB,SAAS"}

package/dist/storages/redis/msgpack.js

@@ -6,7 +6,8 @@ if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled
 *
 * @remarks
 * Adapter rejections and MessagePack serialization errors propagate to the caller.
-* Reads resolve to `null` when no raw value exists. Writes resolve to `true` only when the adapter returns `OK`;
+* Reads resolve to `null` when no raw value exists; `getAndRemoveItem` reads and deletes in one atomic adapter call.
+* Writes resolve to `true` only when the adapter returns `OK`;
 * removal resolves to `true` only when exactly one key is deleted.
 * The adapter remains caller-owned; creating the facade does not open or close a connection.
 *
@@ -25,6 +26,11 @@ if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled
 * const adapter: RedisLikeAdapter = {
 *     delete: async (key) => values.delete(key) ? 1 : 0,
 *     getBuffer: async (key) => values.get(key) ?? null,
+*     getBufferAndDelete: async (key) => {
+*         const value = values.get(key) ?? null;
+*         values.delete(key);
+*         return value;
+*     },
 *     has: async (key) => values.has(key),
 *     setBuffer: async (key, value) => {
 *         values.set(key, value);
@@ -33,6 +39,9 @@ if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled
 *     setBufferEx: async () => {
 *         throw new Error('TTL writes are not supported by this example adapter');
 *     },
+*     setBufferExNx: async () => {
+*         throw new Error('TTL writes are not supported by this example adapter');
+*     },
 *     ttl: async (key) => values.has(key) ? -1 : -2,
 * };
 *
@@ -44,6 +53,10 @@ if (!isNativeAccelerationEnabled) console.warn("Native acceleration not enabled
 */
 function createRedisMsgpackStorage(adapter) {
 	return Object.freeze({
+		async getAndRemoveItem(key) {
+			const rawValue = await adapter.getBufferAndDelete(key);
+			return rawValue ? decode(rawValue) : null;
+		},
 		async getItem(key) {
 			const rawValue = await adapter.getBuffer(key);
 			return rawValue ? decode(rawValue) : null;
@@ -54,6 +67,9 @@ function createRedisMsgpackStorage(adapter) {
 		setItem: async (key, value) => await adapter.setBuffer(key, encode(value)) === "OK",
 		async setItemWithTtl(key, ttlSeconds, value) {
 			return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === "OK";
+		},
+		async setItemWithTtlIfAbsent(key, ttlSeconds, value) {
+			return await adapter.setBufferExNx(key, ttlSeconds, encode(value)) === "OK";
 		}
 	});
 }

package/dist/storages/redis/msgpack.js.map

@@ -1 +1 @@
-{"version":3,"file":"msgpack.js","names":[],"sources":["../../../src/storages/redis/msgpack.ts"],"sourcesContent":["import {\n    decode,\n    encode,\n    isNativeAccelerationEnabled,\n} from 'msgpackr';\n\nimport type {\n    RedisLikeAdapter,\n    RedisLikeStorage,\n} from './types';\n\nif (!isNativeAccelerationEnabled) {\n    console.warn('Native acceleration not enabled for msgpackr, verify that install finished properly');\n}\n\n/**\n * Creates a frozen Redis-like storage facade using MessagePack serialization.\n *\n * @remarks\n * Adapter rejections and MessagePack serialization errors propagate to the caller.\n * Reads resolve to `null` when no raw value exists. Writes resolve to `true` only when the adapter returns `OK`;\n * removal resolves to `true` only when exactly one key is deleted.\n * The adapter remains caller-owned; creating the facade does not open or close a connection.\n *\n * @param adapter - The caller-owned adapter for raw binary operations.\n *\n * @returns A new frozen facade sharing the supplied adapter.\n *\n * @example\n *\n * ```ts\n * import { createRedisMsgpackStorage } from '@kikiutils/shared/storages/redis/msgpack';\n * import type { RedisLikeAdapter } from '@kikiutils/shared/storages/redis/types';\n *\n * // This in-memory adapter demonstrates non-expiring operations without an external service.\n * const values = new Map<string, Uint8Array>();\n * const adapter: RedisLikeAdapter = {\n *     delete: async (key) => values.delete(key) ? 1 : 0,\n *     getBuffer: async (key) => values.get(key) ?? null,\n *     has: async (key) => values.has(key),\n *     setBuffer: async (key, value) => {\n *         values.set(key, value);\n *         return 'OK';\n *     },\n *     setBufferEx: async () => {\n *         throw new Error('TTL writes are not supported by this example adapter');\n *     },\n *     ttl: async (key) => values.has(key) ? -1 : -2,\n * };\n *\n * const storage = createRedisMsgpackStorage(adapter);\n * await storage.setItem('profile', { name: 'Alice' });\n * const profile = await storage.getItem<{ name: string }>('profile');\n * console.log(profile); // => { name: 'Alice' }\n * ```\n */\nexport function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {\n    return Object.freeze({\n        async getItem<T = unknown>(key: string) {\n            const rawValue = await adapter.getBuffer(key);\n            return rawValue ? decode(rawValue) as T : null;\n        },\n        getItemTtl: (key: string) => adapter.ttl(key),\n        hasItem: (key: string) => adapter.has(key),\n        removeItem: async (key: string) => await adapter.delete(key) === 1,\n        setItem: async (key: string, value: any) => await adapter.setBuffer(key, encode(value)) === 'OK',\n        async setItemWithTtl(key: string, ttlSeconds: number, value: any) {\n            return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === 'OK';\n        },\n    });\n}\n"],"mappings":";;AAWA,IAAI,CAAC,6BACD,QAAQ,KAAK,qFAAqF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CtG,SAAgB,0BAA0B,SAAuD;CAC7F,OAAO,OAAO,OAAO;EACjB,MAAM,QAAqB,KAAa;GACpC,MAAM,WAAW,MAAM,QAAQ,UAAU,GAAG;GAC5C,OAAO,WAAW,OAAO,QAAQ,IAAS;EAC9C;EACA,aAAa,QAAgB,QAAQ,IAAI,GAAG;EAC5C,UAAU,QAAgB,QAAQ,IAAI,GAAG;EACzC,YAAY,OAAO,QAAgB,MAAM,QAAQ,OAAO,GAAG,MAAM;EACjE,SAAS,OAAO,KAAa,UAAe,MAAM,QAAQ,UAAU,KAAK,OAAO,KAAK,CAAC,MAAM;EAC5F,MAAM,eAAe,KAAa,YAAoB,OAAY;GAC9D,OAAO,MAAM,QAAQ,YAAY,KAAK,YAAY,OAAO,KAAK,CAAC,MAAM;EACzE;CACJ,CAAC;AACL"}
+{"version":3,"file":"msgpack.js","names":[],"sources":["../../../src/storages/redis/msgpack.ts"],"sourcesContent":["import {\n    decode,\n    encode,\n    isNativeAccelerationEnabled,\n} from 'msgpackr';\n\nimport type {\n    RedisLikeAdapter,\n    RedisLikeStorage,\n} from './types';\n\nif (!isNativeAccelerationEnabled) {\n    console.warn('Native acceleration not enabled for msgpackr, verify that install finished properly');\n}\n\n/**\n * Creates a frozen Redis-like storage facade using MessagePack serialization.\n *\n * @remarks\n * Adapter rejections and MessagePack serialization errors propagate to the caller.\n * Reads resolve to `null` when no raw value exists; `getAndRemoveItem` reads and deletes in one atomic adapter call.\n * Writes resolve to `true` only when the adapter returns `OK`;\n * removal resolves to `true` only when exactly one key is deleted.\n * The adapter remains caller-owned; creating the facade does not open or close a connection.\n *\n * @param adapter - The caller-owned adapter for raw binary operations.\n *\n * @returns A new frozen facade sharing the supplied adapter.\n *\n * @example\n *\n * ```ts\n * import { createRedisMsgpackStorage } from '@kikiutils/shared/storages/redis/msgpack';\n * import type { RedisLikeAdapter } from '@kikiutils/shared/storages/redis/types';\n *\n * // This in-memory adapter demonstrates non-expiring operations without an external service.\n * const values = new Map<string, Uint8Array>();\n * const adapter: RedisLikeAdapter = {\n *     delete: async (key) => values.delete(key) ? 1 : 0,\n *     getBuffer: async (key) => values.get(key) ?? null,\n *     getBufferAndDelete: async (key) => {\n *         const value = values.get(key) ?? null;\n *         values.delete(key);\n *         return value;\n *     },\n *     has: async (key) => values.has(key),\n *     setBuffer: async (key, value) => {\n *         values.set(key, value);\n *         return 'OK';\n *     },\n *     setBufferEx: async () => {\n *         throw new Error('TTL writes are not supported by this example adapter');\n *     },\n *     setBufferExNx: async () => {\n *         throw new Error('TTL writes are not supported by this example adapter');\n *     },\n *     ttl: async (key) => values.has(key) ? -1 : -2,\n * };\n *\n * const storage = createRedisMsgpackStorage(adapter);\n * await storage.setItem('profile', { name: 'Alice' });\n * const profile = await storage.getItem<{ name: string }>('profile');\n * console.log(profile); // => { name: 'Alice' }\n * ```\n */\nexport function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {\n    return Object.freeze({\n        async getAndRemoveItem<T = unknown>(key: string) {\n            const rawValue = await adapter.getBufferAndDelete(key);\n            return rawValue ? decode(rawValue) as T : null;\n        },\n        async getItem<T = unknown>(key: string) {\n            const rawValue = await adapter.getBuffer(key);\n            return rawValue ? decode(rawValue) as T : null;\n        },\n        getItemTtl: (key: string) => adapter.ttl(key),\n        hasItem: (key: string) => adapter.has(key),\n        removeItem: async (key: string) => await adapter.delete(key) === 1,\n        setItem: async (key: string, value: any) => await adapter.setBuffer(key, encode(value)) === 'OK',\n        async setItemWithTtl(key: string, ttlSeconds: number, value: any) {\n            return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === 'OK';\n        },\n        async setItemWithTtlIfAbsent(key: string, ttlSeconds: number, value: any) {\n            return await adapter.setBufferExNx(key, ttlSeconds, encode(value)) === 'OK';\n        },\n    });\n}\n"],"mappings":";;AAWA,IAAI,CAAC,6BACD,QAAQ,KAAK,qFAAqF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDtG,SAAgB,0BAA0B,SAAuD;CAC7F,OAAO,OAAO,OAAO;EACjB,MAAM,iBAA8B,KAAa;GAC7C,MAAM,WAAW,MAAM,QAAQ,mBAAmB,GAAG;GACrD,OAAO,WAAW,OAAO,QAAQ,IAAS;EAC9C;EACA,MAAM,QAAqB,KAAa;GACpC,MAAM,WAAW,MAAM,QAAQ,UAAU,GAAG;GAC5C,OAAO,WAAW,OAAO,QAAQ,IAAS;EAC9C;EACA,aAAa,QAAgB,QAAQ,IAAI,GAAG;EAC5C,UAAU,QAAgB,QAAQ,IAAI,GAAG;EACzC,YAAY,OAAO,QAAgB,MAAM,QAAQ,OAAO,GAAG,MAAM;EACjE,SAAS,OAAO,KAAa,UAAe,MAAM,QAAQ,UAAU,KAAK,OAAO,KAAK,CAAC,MAAM;EAC5F,MAAM,eAAe,KAAa,YAAoB,OAAY;GAC9D,OAAO,MAAM,QAAQ,YAAY,KAAK,YAAY,OAAO,KAAK,CAAC,MAAM;EACzE;EACA,MAAM,uBAAuB,KAAa,YAAoB,OAAY;GACtE,OAAO,MAAM,QAAQ,cAAc,KAAK,YAAY,OAAO,KAAK,CAAC,MAAM;EAC3E;CACJ,CAAC;AACL"}

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

@@ -14,6 +14,11 @@ export interface RedisLikeAdapter {
    * Reads a key and resolves to its raw bytes, or `null` when the key is missing.
    */
   getBuffer: (key: string) => Promise<null | Uint8Array>;
+  /**
+   * Atomically reads and deletes a key, such as with Redis `GETDEL`,
+   * and resolves to its raw bytes, or `null` when the key is missing.
+   */
+  getBufferAndDelete: (key: string) => Promise<null | Uint8Array>;
   /**
    * Checks a key and resolves to whether it exists.
    */
@@ -30,6 +35,15 @@ export interface RedisLikeAdapter {
    * @param value - The raw bytes to store.
    */
   setBufferEx: (key: string, ttlSeconds: number, value: Uint8Array) => Promise<'OK' | void>;
+  /**
+   * Writes raw bytes with an expiry only when the key is missing, such as with Redis `SET key value EX ttl NX`,
+   * and resolves to the backend acknowledgment, or `null` or no value when the key already exists.
+   *
+   * @param key - The storage key.
+   * @param ttlSeconds - The expiry duration in seconds.
+   * @param value - The raw bytes to store.
+   */
+  setBufferExNx: (key: string, ttlSeconds: number, value: Uint8Array) => Promise<'OK' | null | void>;
   /**
    * Reads a key's remaining TTL in seconds, or `-1` for no expiry and `-2` for a missing key.
    */
@@ -43,6 +57,13 @@ export interface RedisLikeAdapter {
  * `-1` means no expiry, and `-2` means the key is missing. Connection cleanup remains caller-owned.
  */
 export interface RedisLikeStorage {
+  /**
+   * Atomically reads and removes a deserialized value and resolves to `null` when the key is missing.
+   * Concurrent callers on the same key receive the value at most once.
+   *
+   * @typeParam T - The expected value type; deserialization does not validate this type.
+   */
+  getAndRemoveItem: <T = unknown>(key: string) => Promise<null | T>;
   /**
    * Reads a deserialized value and resolves to `null` when the key is missing.
    *
@@ -73,5 +94,14 @@ export interface RedisLikeStorage {
    * @param value - The value to serialize and store.
    */
   setItemWithTtl: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
+  /**
+   * Atomically stores a value with an expiry only when the key is missing
+   * and resolves to whether the backend acknowledges the write.
+   *
+   * @param key - The storage key.
+   * @param ttlSeconds - The expiry duration in seconds.
+   * @param value - The value to serialize and store.
+   */
+  setItemWithTtlIfAbsent: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
 }
 //# 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;;;;;EAM3C,qBAAqB,gBAAgB,eAAe;;;;EAKpD,MAAM,gBAAgB;;;;EAKtB,YAAY,aAAa,OAAO,eAAe;;;;;;;;EAS/C,cAAc,aAAa,oBAAoB,OAAO,eAAe;;;;;;;;;EAUrE,gBAAgB,aAAa,oBAAoB,OAAO,eAAe;;;;EAKvE,MAAM,gBAAgB;;;;;;;;;iBAUT;;;;;;;EAOb,mBAAmB,aAAa,gBAAgB,eAAe;;;;;;EAO/D,UAAU,aAAa,gBAAgB,eAAe;;;;EAKtD,aAAa,gBAAgB;;;;EAK7B,UAAU,gBAAgB;;;;EAK1B,aAAa,gBAAgB;;;;EAK7B,UAAU,aAAa,eAAe;;;;;;;;EAStC,iBAAiB,aAAa,oBAAoB,eAAe;;;;;;;;;EAUjE,yBAAyB,aAAa,oBAAoB,eAAe"}

package/dist/types/filtered-key-path.js

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

package/dist/types/index.js

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

package/dist/types/vue.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kikiutils/shared",
   "type": "module",
-  "version": "19.0.0",
+  "version": "20.0.1",
   "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",
@@ -31,68 +31,41 @@
   ],
   "sideEffects": false,
   "exports": {
-    "./logger": {
-      "types": "./dist/logger/index.d.ts",
-      "import": "./dist/logger/index.js",
-      "require": null
-    },
-    "./logger/_internals/formatter": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/_internals/levels": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/_internals/logger": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/_internals/types": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/index": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/node": {
-      "types": "./dist/logger/node/index.d.ts",
-      "import": "./dist/logger/node/index.js",
-      "require": null
-    },
-    "./logger/node/_internals/file-writer": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/node/_internals/formatter": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./logger/node/index": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./package.json": "./package.json",
-    "./types": {
-      "types": "./dist/types/index.d.ts",
-      "import": null,
-      "require": null
-    },
-    "./types/index": {
-      "types": null,
-      "import": null,
-      "require": null
-    },
-    "./*": "./dist/*.js"
+    "./buffer": "./dist/buffer.js",
+    "./classes/enhanced-date": "./dist/classes/enhanced-date.js",
+    "./classes/path": "./dist/classes/path.js",
+    "./classes/precision-number": "./dist/classes/precision-number.js",
+    "./clipboard": "./dist/clipboard.js",
+    "./crypto-hash": "./dist/crypto-hash.js",
+    "./datetime": "./dist/datetime.js",
+    "./element-plus": "./dist/element-plus.js",
+    "./enum": "./dist/enum.js",
+    "./env": "./dist/env.js",
+    "./event-awaiter": "./dist/event-awaiter.js",
+    "./file": "./dist/file.js",
+    "./general": "./dist/general.js",
+    "./hash": "./dist/hash.js",
+    "./logger": "./dist/logger/index.js",
+    "./logger/node": "./dist/logger/node/index.js",
+    "./logger/node/types": "./dist/logger/node/types.js",
+    "./logger/types": "./dist/logger/types.js",
+    "./math": "./dist/math.js",
+    "./number": "./dist/number.js",
+    "./random": "./dist/random.js",
+    "./redis/script-runner": "./dist/redis/script-runner.js",
+    "./storages/lru/keyed-store": "./dist/storages/lru/keyed-store.js",
+    "./storages/redis/keyed-store": "./dist/storages/redis/keyed-store.js",
+    "./storages/redis/msgpack": "./dist/storages/redis/msgpack.js",
+    "./storages/redis/types": "./dist/storages/redis/types.js",
+    "./string": "./dist/string.js",
+    "./time": "./dist/time.js",
+    "./types": "./dist/types/index.js",
+    "./types/filtered-key-path": "./dist/types/filtered-key-path.js",
+    "./types/vue": "./dist/types/vue.js",
+    "./url": "./dist/url.js",
+    "./vue": "./dist/vue.js",
+    "./web": "./dist/web.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "./dist",
@@ -172,10 +145,11 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^10.0.0",
-    "@kikiutils/eslint-config": "^9.3.1",
+    "@arethetypeswrong/core": "^0.18.5",
+    "@kikiutils/eslint-config": "^9.3.2",
     "@kikiutils/tsconfigs": "^7.0.0",
     "@noble/hashes": "^2.4.0",
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "@vitest/coverage-v8": "^5.0.5",
     "async-validator": "^4.2.5",
     "bson": "^7.3.3",
@@ -184,16 +158,16 @@
     "date-fns": "^4.4.0",
     "decimal.js": "^10.6.0",
     "element-plus": "^2.14.7",
-    "eslint": "^10.13.0",
-    "file-type": "^22.2.0",
+    "eslint": "^10.14.0",
+    "file-type": "^22.3.0",
     "jsdom": "^30.1.3",
-    "knip": "^6.42.1",
+    "knip": "^6.44.0",
     "lru-cache": "^11.5.3",
     "millify": "^6.1.0",
-    "msgpackr": "^2.1.2",
+    "msgpackr": "^2.1.3",
     "publint": "^0.3.25",
     "rotating-file-stream": "^3.2.10",
-    "tsdown": "^0.23.2",
+    "tsdown": "^0.23.4",
     "typescript": "^6.0.3",
     "unplugin-unused": "^0.6.0",
     "vitest": "^5.0.5",

package/src/logger/_internals/logger.ts

@@ -31,7 +31,7 @@ const stringPresentationKeys = [
 
 /** A non-recursive, rate-limited diagnostic boundary shared by server and browser adapters. */
 export function createDiagnosticReporter(
-    onError?: (event: LoggerDiagnostic) => void,
+    onError?: (event: Readonly<LoggerDiagnostic>) => void,
     fallback?: (message: string) => void,
 ): (event: LoggerDiagnostic) => void {
     let reporting = false;
@@ -75,7 +75,7 @@ export function createDiagnosticReporter(
             if (!callbackPending) {
                 try {
                     callbackPending = true;
-                    const result: unknown = onError?.(event);
+                    const result: unknown = onError?.(Object.freeze({ ...event }));
                     if (result !== null && (typeof result === 'object' || typeof result === 'function')) {
                         void Promise.resolve(result).then(
                             () => {
@@ -99,7 +99,7 @@ export function createDiagnosticReporter(
     };
 }
 
-export function createLoggerCore(options: LoggerOptions, hooks: LoggerHooks): Logger {
+export function createLoggerCore(options: LoggerOptions, hooks: LoggerHooks): Readonly<Logger> {
     validateLevel(options.level);
     validatePresentation(options);
     if (options.onError !== undefined && typeof options.onError !== 'function') {
@@ -189,7 +189,7 @@ export function createLoggerCore(options: LoggerOptions, hooks: LoggerHooks): Lo
         };
     }
 
-    return logger;
+    return Object.freeze(logger);
 }
 
 function getLevelSeverity(level: LoggerLevel | LoggerMethod): number {

package/src/logger/index.ts

@@ -18,7 +18,7 @@ import type {
  * waits for the console invocation, not display or durable delivery. Unspecified
  * levels follow LOG_LEVEL when a process environment is available, otherwise info.
  */
-export function createLogger(options: LoggerOptions = {}): Logger {
+export function createLogger(options: LoggerOptions = {}): Readonly<Logger> {
     const target = globalThis.console;
     const fallback = target?.error?.bind(target);
     return createLoggerCore(

package/src/logger/node/_internals/file-writer.ts

@@ -17,7 +17,7 @@ import type {
 
 interface LoggerFileWriter {
     close: () => Promise<void>;
-    getStats: () => NodeLoggerStats;
+    getStats: () => Readonly<NodeLoggerStats>;
     write: (text: string) => Promise<void>;
 }
 
@@ -30,7 +30,7 @@ const defaultMaxPendingBytes = 8 * 1024 * 1024;
 export async function createFileWriter(
     options: LoggerFileOptions,
     report: (event: LoggerDiagnostic) => void,
-): Promise<LoggerFileWriter> {
+): Promise<Readonly<LoggerFileWriter>> {
     const {
         maxPendingBytes,
         path,
@@ -138,7 +138,7 @@ export async function createFileWriter(
         initializing = false;
     }
 
-    return {
+    return Object.freeze({
         close() {
             if (closePromise) return closePromise;
             closing = true;
@@ -158,12 +158,12 @@ export async function createFileWriter(
 
             return closePromise;
         },
-        getStats: () => ({
+        getStats: () => Object.freeze({
             droppedCount,
             pendingBytes,
             writeErrorCount,
         }),
-        write(text) {
+        write(text: string) {
             if (closing || closed || failed) {
                 report({
                     message: 'File output is closed or unavailable.',
@@ -210,7 +210,7 @@ export async function createFileWriter(
                 }
             });
         },
-    };
+    });
 }
 
 /** Validate before mkdir, stream creation, or other filesystem side effects. */

package/src/logger/node/index.ts

@@ -35,7 +35,7 @@ const consoleStreams = new WeakMap<NodeJS.WriteStream, ConsoleStreamState>();
  * 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 async function createNodeLogger(options: NodeLoggerOptions = {}): Promise<NodeLogger> {
+export async function createNodeLogger(options: NodeLoggerOptions = {}): Promise<Readonly<NodeLogger>> {
     const report = createDiagnosticReporter(options.onError, (message) => writeSync(2, message));
     let writer: Awaited<ReturnType<typeof createFileWriter>> | undefined;
     let closed = false;
@@ -83,40 +83,38 @@ export async function createNodeLogger(options: NodeLoggerOptions = {}): Promise
 
     if (options.file !== undefined && 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);
-                        }
+    return Object.freeze({
+        ...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,
-            },
+                consoleTargets.clear();
+            })();
+            return closePromise;
         },
-    );
+        getStats: () => writer?.getStats() ?? Object.freeze({
+            droppedCount: 0,
+            pendingBytes: 0,
+            writeErrorCount: 0,
+        }),
+    });
 }
 
 /** One error listener per shared output stream; retained until its last owning logger calls close(). */

package/src/logger/node/types.ts

@@ -42,8 +42,8 @@ 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;
+    /** A fresh, frozen file-output snapshot. Dropped/failed records still resolve their logging promises. */
+    getStats: () => Readonly<NodeLoggerStats>;
 }
 
 export interface NodeLoggerOptions extends LoggerOptions {

package/src/logger/types.ts

@@ -9,6 +9,7 @@ export type LoggerMethod = 'success' | Exclude<LoggerLevel, 'silent'>;
  *
  * Awaiting a method waits for processing, not guaranteed successful delivery or fsync.
  * Configuration errors may throw from the factory, configure(), or setLevel().
+ * Factories freeze the API object; settings remain adjustable through its methods.
  */
 export interface Logger {
     configure: (options: Pick<LoggerOptions, 'console' | 'icons' | 'prefix' | 'suffix' | 'timestamp'>) => void;
@@ -27,7 +28,7 @@ export interface Logger {
     warn: (...args: unknown[]) => Promise<void>;
 }
 
-/** A recoverable logging failure, reported without throwing from log methods. */
+/** A shallow-frozen failure notification; nested error values retain their original ownership. */
 export interface LoggerDiagnostic {
     droppedCount?: number;
     error?: unknown;
@@ -50,7 +51,7 @@ export interface LoggerOptions {
     level?: 'env' | LoggerLevel;
 
     /** Best-effort, rate-limited notification; failures in this callback are contained. */
-    onError?: (event: LoggerDiagnostic) => void;
+    onError?: (event: Readonly<LoggerDiagnostic>) => void;
     prefix?: string;
     suffix?: string;
 

package/src/storages/redis/keyed-store.ts

@@ -8,7 +8,7 @@ import type { RedisLikeStorage } from './types';
  * @remarks
  * The key resolver is called synchronously once per operation with the operation's key arguments.
  * Resolver exceptions propagate synchronously; asynchronous storage failures retain the underlying rejection.
- * `setItemWithTtl` accepts its TTL in seconds before the value and key arguments.
+ * `setItemWithTtl` and `setItemWithTtlIfAbsent` accept their TTL in seconds before the value and key arguments.
  * The factory does not open or close the underlying connection; cleanup remains the caller's responsibility.
  *
  * @typeParam D - The stored value type used by reads and writes.
@@ -16,10 +16,11 @@ import type { RedisLikeStorage } from './types';
  * @param storage - The shared Redis-like storage instance.
  *
  * @returns A factory accepting a key resolver and returning a new frozen keyed facade sharing the storage.
- * Reads, writes, removals, and TTL results retain the underlying storage contract.
+ * Reads, atomic read-and-removals, writes, removals, and TTL results retain the underlying storage contract.
  */
 export function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisLikeStorage>) {
     return <P extends any[]>(keyFn: (...args: P) => string) => Object.freeze({
+        getAndRemoveItem: (...args: P) => storage.getAndRemoveItem<D>(keyFn(...args)),
         getItem: (...args: P) => storage.getItem<D>(keyFn(...args)),
         getItemTtl: (...args: P) => storage.getItemTtl(keyFn(...args)),
         hasItem: (...args: P) => storage.hasItem(keyFn(...args)),
@@ -29,5 +30,8 @@ export function createRedisKeyedStore<D = unknown>(storage: MaybeReadonly<RedisL
         setItemWithTtl(ttlSeconds: number, value: D, ...args: P) {
             return storage.setItemWithTtl(keyFn(...args), ttlSeconds, value);
         },
+        setItemWithTtlIfAbsent(ttlSeconds: number, value: D, ...args: P) {
+            return storage.setItemWithTtlIfAbsent(keyFn(...args), ttlSeconds, value);
+        },
     });
 }

package/src/storages/redis/msgpack.ts

@@ -18,7 +18,8 @@ if (!isNativeAccelerationEnabled) {
  *
  * @remarks
  * Adapter rejections and MessagePack serialization errors propagate to the caller.
- * Reads resolve to `null` when no raw value exists. Writes resolve to `true` only when the adapter returns `OK`;
+ * Reads resolve to `null` when no raw value exists; `getAndRemoveItem` reads and deletes in one atomic adapter call.
+ * Writes resolve to `true` only when the adapter returns `OK`;
  * removal resolves to `true` only when exactly one key is deleted.
  * The adapter remains caller-owned; creating the facade does not open or close a connection.
  *
@@ -37,6 +38,11 @@ if (!isNativeAccelerationEnabled) {
  * const adapter: RedisLikeAdapter = {
  *     delete: async (key) => values.delete(key) ? 1 : 0,
  *     getBuffer: async (key) => values.get(key) ?? null,
+ *     getBufferAndDelete: async (key) => {
+ *         const value = values.get(key) ?? null;
+ *         values.delete(key);
+ *         return value;
+ *     },
  *     has: async (key) => values.has(key),
  *     setBuffer: async (key, value) => {
  *         values.set(key, value);
@@ -45,6 +51,9 @@ if (!isNativeAccelerationEnabled) {
  *     setBufferEx: async () => {
  *         throw new Error('TTL writes are not supported by this example adapter');
  *     },
+ *     setBufferExNx: async () => {
+ *         throw new Error('TTL writes are not supported by this example adapter');
+ *     },
  *     ttl: async (key) => values.has(key) ? -1 : -2,
  * };
  *
@@ -56,6 +65,10 @@ if (!isNativeAccelerationEnabled) {
  */
 export function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<RedisLikeStorage> {
     return Object.freeze({
+        async getAndRemoveItem<T = unknown>(key: string) {
+            const rawValue = await adapter.getBufferAndDelete(key);
+            return rawValue ? decode(rawValue) as T : null;
+        },
         async getItem<T = unknown>(key: string) {
             const rawValue = await adapter.getBuffer(key);
             return rawValue ? decode(rawValue) as T : null;
@@ -67,5 +80,8 @@ export function createRedisMsgpackStorage(adapter: RedisLikeAdapter): Readonly<R
         async setItemWithTtl(key: string, ttlSeconds: number, value: any) {
             return await adapter.setBufferEx(key, ttlSeconds, encode(value)) === 'OK';
         },
+        async setItemWithTtlIfAbsent(key: string, ttlSeconds: number, value: any) {
+            return await adapter.setBufferExNx(key, ttlSeconds, encode(value)) === 'OK';
+        },
     });
 }

package/src/storages/redis/types.ts

@@ -16,6 +16,12 @@ export interface RedisLikeAdapter {
      */
     getBuffer: (key: string) => Promise<null | Uint8Array>;
 
+    /**
+     * Atomically reads and deletes a key, such as with Redis `GETDEL`,
+     * and resolves to its raw bytes, or `null` when the key is missing.
+     */
+    getBufferAndDelete: (key: string) => Promise<null | Uint8Array>;
+
     /**
      * Checks a key and resolves to whether it exists.
      */
@@ -35,6 +41,16 @@ export interface RedisLikeAdapter {
      */
     setBufferEx: (key: string, ttlSeconds: number, value: Uint8Array) => Promise<'OK' | void>;
 
+    /**
+     * Writes raw bytes with an expiry only when the key is missing, such as with Redis `SET key value EX ttl NX`,
+     * and resolves to the backend acknowledgment, or `null` or no value when the key already exists.
+     *
+     * @param key - The storage key.
+     * @param ttlSeconds - The expiry duration in seconds.
+     * @param value - The raw bytes to store.
+     */
+    setBufferExNx: (key: string, ttlSeconds: number, value: Uint8Array) => Promise<'OK' | null | void>;
+
     /**
      * Reads a key's remaining TTL in seconds, or `-1` for no expiry and `-2` for a missing key.
      */
@@ -49,6 +65,14 @@ export interface RedisLikeAdapter {
  * `-1` means no expiry, and `-2` means the key is missing. Connection cleanup remains caller-owned.
  */
 export interface RedisLikeStorage {
+    /**
+     * Atomically reads and removes a deserialized value and resolves to `null` when the key is missing.
+     * Concurrent callers on the same key receive the value at most once.
+     *
+     * @typeParam T - The expected value type; deserialization does not validate this type.
+     */
+    getAndRemoveItem: <T = unknown>(key: string) => Promise<null | T>;
+
     /**
      * Reads a deserialized value and resolves to `null` when the key is missing.
      *
@@ -84,4 +108,14 @@ export interface RedisLikeStorage {
      * @param value - The value to serialize and store.
      */
     setItemWithTtl: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
+
+    /**
+     * Atomically stores a value with an expiry only when the key is missing
+     * and resolves to whether the backend acknowledges the write.
+     *
+     * @param key - The storage key.
+     * @param ttlSeconds - The expiry duration in seconds.
+     * @param value - The value to serialize and store.
+     */
+    setItemWithTtlIfAbsent: (key: string, ttlSeconds: number, value: any) => Promise<boolean>;
 }