@neezco/cache 0.6.0 → 0.8.0

package/dist/node/index.mjs

@@ -0,0 +1,1287 @@
+import fs from "fs";
+import v8 from "v8";
+import { performance } from "perf_hooks";
+
+//#region src/cache/clear.ts
+/**
+* Clears all entries from the cache without invoking callbacks.
+*
+* @note The `onDelete` callback is NOT invoked during a clear operation.
+* This is intentional to avoid unnecessary overhead when bulk-removing entries.
+*
+* @param state - The cache state.
+* @returns void
+*/
+const clear = (state) => {
+	state.store.clear();
+};
+
+//#endregion
+//#region src/defaults.ts
+const ONE_SECOND = 1e3;
+const ONE_MINUTE = 60 * ONE_SECOND;
+/**
+* ===================================================================
+* Cache Entry Lifecycle
+* Default TTL and stale window settings for short-lived cache entries.
+* ===================================================================
+*/
+/**
+* Default Time-To-Live in milliseconds for cache entries.
+* @default 1_800_000 (30 minutes)
+*/
+const DEFAULT_TTL = 30 * ONE_MINUTE;
+/**
+* Maximum number of entries the cache can hold.
+* Beyond this limit, new entries are ignored.
+*/
+const DEFAULT_MAX_SIZE = Infinity;
+/**
+* Default maximum memory size in MB the cache can use.
+* Beyond this limit, new entries are ignored.
+* @default Infinite (unlimited)
+*/
+const DEFAULT_MAX_MEMORY_SIZE = Infinity;
+/**
+* ===================================================================
+* Sweep & Cleanup Operations
+* Parameters controlling how and when expired entries are removed.
+* ===================================================================
+*/
+/**
+* Maximum number of keys to process in a single sweep batch.
+* Higher values = more aggressive cleanup, lower latency overhead.
+*/
+const MAX_KEYS_PER_BATCH = 1e3;
+/**
+* Minimal expired ratio enforced during sweeps.
+*/
+const MINIMAL_EXPIRED_RATIO = .05;
+/**
+* Maximum allowed expired ratio when memory usage is low.
+* Upper bound for interpolation with MINIMAL_EXPIRED_RATIO.
+* Recommended range: `0.3 – 0.5` .
+*/
+const DEFAULT_MAX_EXPIRED_RATIO = .4;
+/**
+* ===================================================================
+* Sweep Intervals & Timing
+* Frequency and time budgets for cleanup operations.
+* ===================================================================
+*/
+/**
+* Optimal interval in milliseconds between sweeps.
+* Used when system load is minimal and metrics are available.
+*/
+const OPTIMAL_SWEEP_INTERVAL = 2 * ONE_SECOND;
+/**
+* ===================================================================
+* Memory Management
+* Process limits and memory-safe thresholds.
+* ===================================================================
+*/
+/**
+* Default maximum process memory limit in megabytes.
+* Acts as fallback when environment detection is unavailable.
+* NOTE: Overridable via environment detection at runtime.
+*/
+const DEFAULT_MAX_PROCESS_MEMORY_MB = 1024;
+/**
+* Weight applied to CPU utilization in sweep calculations.
+* Combined with event-loop weight to balance CPU-related pressure.
+*/
+const DEFAULT_CPU_WEIGHT = 8.5;
+/**
+* Weight applied to event-loop utilization in sweep calculations.
+* Complements CPU weight to assess overall processing capacity.
+*/
+const DEFAULT_LOOP_WEIGHT = 6.5;
+/**
+* Default threshold for purging stale entries on get operations (backend with limits).
+* Stale entries are purged when resource usage exceeds 80%.
+*
+* Note: This is used when limits are configured.
+* When no limits are defined, purgeStaleOnGet defaults to false.
+*/
+const DEFAULT_PURGE_STALE_ON_GET_THRESHOLD = .8;
+/**
+* Default threshold for purging stale entries during sweep operations (backend with limits).
+* Stale entries are purged when resource usage exceeds 50%.
+*
+* Note: This is used when limits are configured.
+* When no limits are defined, purgeStaleOnSweep defaults to true.
+*/
+const DEFAULT_PURGE_STALE_ON_SWEEP_THRESHOLD = .5;
+
+//#endregion
+//#region src/resolve-purge-config/validators.ts
+/**
+* Validates if a numeric value is a valid positive limit.
+* @internal
+*/
+const isValidLimit = (value) => Number.isFinite(value) && value > 0;
+/**
+* Checks if the required limits are configured for the given metric.
+* @internal
+*/
+const checkRequiredLimits = (metric, limitStatus) => {
+	if (metric === "fixed") return false;
+	if (metric === "size") return limitStatus.hasSizeLimit;
+	if (metric === "memory") return limitStatus.hasMemoryLimit;
+	if (metric === "higher") return limitStatus.hasSizeLimit && limitStatus.hasMemoryLimit;
+	return false;
+};
+
+//#endregion
+//#region src/resolve-purge-config/formatters.ts
+/**
+* Gets the requirement text for a metric when limits are missing.
+* @internal
+*/
+const getLimitRequirementText = (metric) => {
+	if (metric === "fixed") return "Numeric thresholds are not supported (metric is 'fixed')";
+	if (metric === "size") return "'maxSize' must be a valid positive number";
+	if (metric === "memory") return "'maxMemorySize' must be a valid positive number";
+	if (metric === "higher") return "both 'maxSize' and 'maxMemorySize' must be valid positive numbers";
+	return "required configuration";
+};
+/**
+* Formats a purge mode value for display.
+* @internal
+*/
+const formatPurgeValue = (mode) => {
+	if (typeof mode === "number") return `threshold ${(mode * 100).toFixed(0)}%`;
+	return `${mode}`;
+};
+
+//#endregion
+//#region src/resolve-purge-config/warnings.ts
+/**
+* Warns user about invalid purge configuration.
+* Only called when user-provided threshold value is invalid.
+*
+* @internal
+*/
+const warnInvalidPurgeMode = (config, invalidConditions) => {
+	if (invalidConditions.isOutOfRange) {
+		console.warn(`[Cache] ${config.operation}: Set to ${formatPurgeValue(config.mode)} with purgeResourceMetric '${config.metric}'.\n  ⚠ Invalid: Numeric threshold must be between 0 (exclusive) and 1 (inclusive).\n  ✓ Fallback: ${config.operation} = ${formatPurgeValue(config.fallback)}, purgeResourceMetric = '${config.metric}'`);
+		return;
+	}
+	if (invalidConditions.isIncompatibleWithMetric) {
+		console.warn(`[Cache] ${config.operation}: Set to ${formatPurgeValue(config.mode)} with purgeResourceMetric '${config.metric}'.\n  ⚠ Not supported: Numeric thresholds don't work with purgeResourceMetric 'fixed'.\n  ✓ Fallback: ${config.operation} = ${formatPurgeValue(config.fallback)}, purgeResourceMetric = '${config.metric}'`);
+		return;
+	}
+	if (invalidConditions.isMissingLimits) {
+		const requirement = getLimitRequirementText(config.metric);
+		console.warn(`[Cache] ${config.operation}: Set to ${formatPurgeValue(config.mode)} with purgeResourceMetric '${config.metric}'.\n  ⚠ Not supported: ${requirement}\n  ✓ Fallback: ${config.operation} = ${formatPurgeValue(config.fallback)}, purgeResourceMetric = '${config.metric}'`);
+	}
+};
+
+//#endregion
+//#region src/resolve-purge-config/core.ts
+/**
+* Generic purge mode resolver that handles both get and sweep operations.
+*
+* Resolves valid user values or returns appropriate defaults based on:
+* - Available configuration limits (maxSize, maxMemorySize)
+* - Purge resource metric support (size, memory, higher, fixed)
+* - User-provided threshold validity (0 < value ≤ 1)
+*
+* Behavior:
+* - Boolean values (true/false): always valid, returns as-is
+* - Numeric thresholds (0-1): validated against 3 conditions:
+*   1. Range validation: must be 0 < value ≤ 1
+*   2. Metric compatibility: metric must support thresholds (not 'fixed')
+*   3. Configuration requirement: metric's required limits must be set
+* - Invalid numerics: logs warning and returns configuration default
+*
+* Defaults:
+* - With required limits: threshold-based (0.80 for get, 0.5 for sweep)
+* - Without required limits: boolean (false for get, true for sweep)
+*
+* @internal
+*/
+const resolvePurgeMode = (limits, config, defaults, userValue) => {
+	const hasSizeLimit = isValidLimit(limits.maxSize);
+	const hasMemoryLimit = isValidLimit(limits.maxMemorySize);
+	const hasRequiredLimits = checkRequiredLimits(config.purgeResourceMetric, {
+		hasSizeLimit,
+		hasMemoryLimit
+	});
+	const fallback = hasRequiredLimits ? defaults.withLimits : defaults.withoutLimits;
+	if (userValue !== void 0) {
+		const isNumeric = typeof userValue === "number";
+		const isOutOfRange = isNumeric && (userValue <= 0 || userValue > 1);
+		const isIncompatibleWithMetric = isNumeric && config.purgeResourceMetric === "fixed";
+		const isMissingLimits = isNumeric && !hasRequiredLimits;
+		if (isOutOfRange || isIncompatibleWithMetric || isMissingLimits) {
+			warnInvalidPurgeMode({
+				mode: userValue,
+				metric: config.purgeResourceMetric,
+				operation: config.operation,
+				fallback
+			}, {
+				isOutOfRange,
+				isIncompatibleWithMetric,
+				isMissingLimits
+			});
+			return fallback;
+		}
+		return userValue;
+	}
+	return fallback;
+};
+
+//#endregion
+//#region src/resolve-purge-config/get.ts
+/**
+* Resolves the purgeStaleOnGet mode based on available configuration.
+*
+* Returns:
+* - User value if valid (boolean always valid; numeric must satisfy all conditions)
+* - Configuration default if user value is invalid
+*
+* Validation for numeric user values (0-1 thresholds):
+* - Must be in range: 0 < value ≤ 1
+* - Metric must support thresholds: not 'fixed'
+* - Metric must have required limits: 'size' needs maxSize, 'memory' needs maxMemorySize, 'higher' needs both
+*
+* Configuration defaults:
+* - With limits matching metric: 0.80 (80% purge threshold)
+* - Without matching limits: false (preserve stale entries)
+*
+* @param config - Configuration with limits, purgeResourceMetric, and optional userValue
+* @returns Valid purgeStaleOnGet value (boolean or threshold 0-1)
+*
+* @internal
+*/
+const resolvePurgeStaleOnGet = (config) => resolvePurgeMode(config.limits, {
+	purgeResourceMetric: config.purgeResourceMetric,
+	operation: "purgeStaleOnGet"
+}, {
+	withLimits: DEFAULT_PURGE_STALE_ON_GET_THRESHOLD,
+	withoutLimits: false
+}, config.userValue);
+
+//#endregion
+//#region src/resolve-purge-config/metric.ts
+/**
+* Resolves the purge resource metric based on available limits and environment.
+*
+* - Browser: returns "size" if maxSize is valid, otherwise "fixed"
+* - Backend with both maxSize and maxMemorySize: returns "higher"
+* - Backend with only maxMemorySize: returns "memory"
+* - Backend with only maxSize: returns "size"
+* - Backend with no limits: returns "fixed"
+*
+* @param config - Configuration object with maxSize and maxMemorySize limits
+* @returns The appropriate purge resource metric for this configuration
+*
+* @internal
+*/
+const resolvePurgeResourceMetric = (config) => {
+	const limitStatus = {
+		hasSizeLimit: isValidLimit(config.maxSize),
+		hasMemoryLimit: isValidLimit(config.maxMemorySize)
+	};
+	if (limitStatus.hasSizeLimit && limitStatus.hasMemoryLimit) return "higher";
+	if (limitStatus.hasMemoryLimit) return "memory";
+	if (limitStatus.hasSizeLimit) return "size";
+	return "fixed";
+};
+
+//#endregion
+//#region src/resolve-purge-config/sweep.ts
+/**
+* Resolves the purgeStaleOnSweep mode based on available configuration.
+*
+* Returns:
+* - User value if valid (boolean always valid; numeric must satisfy all conditions)
+* - Configuration default if user value is invalid
+*
+* Validation for numeric user values (0-1 thresholds):
+* - Must be in range: 0 < value ≤ 1
+* - Metric must support thresholds: not 'fixed'
+* - Metric must have required limits: 'size' needs maxSize, 'memory' needs maxMemorySize, 'higher' needs both
+*
+* Configuration defaults:
+* - With limits matching metric: 0.5 (50% purge threshold)
+* - Without matching limits: true (always purge to prevent unbounded growth)
+*
+* @param config - Configuration with limits, purgeResourceMetric, and optional userValue
+* @returns Valid purgeStaleOnSweep value (boolean or threshold 0-1)
+*
+* @internal
+*/
+const resolvePurgeStaleOnSweep = (config) => resolvePurgeMode(config.limits, {
+	purgeResourceMetric: config.purgeResourceMetric,
+	operation: "purgeStaleOnSweep"
+}, {
+	withLimits: DEFAULT_PURGE_STALE_ON_SWEEP_THRESHOLD,
+	withoutLimits: true
+}, config.userValue);
+
+//#endregion
+//#region src/utils/get-process-memory-limit.ts
+/**
+* Reads a number from a file.
+* @param path File path to read the number from.
+* @returns The number read from the file, or null if reading fails.
+*/
+function readNumber(path) {
+	try {
+		const raw = fs.readFileSync(path, "utf8").trim();
+		const n = Number(raw);
+		return Number.isFinite(n) ? n : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Gets the memory limit imposed by cgroups, if any.
+* @return The memory limit in bytes, or null if no limit is found.
+*/
+function getCgroupLimit() {
+	const v2 = readNumber("/sys/fs/cgroup/memory.max");
+	if (v2 !== null) return v2;
+	const v1 = readNumber("/sys/fs/cgroup/memory/memory.limit_in_bytes");
+	if (v1 !== null) return v1;
+	return null;
+}
+/**
+* Gets the effective memory limit for the current process, considering both V8 heap limits and cgroup limits.
+* @returns The effective memory limit in bytes.
+*/
+function getProcessMemoryLimit() {
+	const heapLimit = v8.getHeapStatistics().heap_size_limit;
+	const cgroupLimit = getCgroupLimit();
+	if (cgroupLimit && cgroupLimit > 0 && cgroupLimit < Infinity) return Math.min(heapLimit, cgroupLimit);
+	return heapLimit;
+}
+
+//#endregion
+//#region src/utils/process-monitor.ts
+/**
+* Creates a performance monitor that periodically samples memory usage,
+* CPU usage, and event loop utilization for the current Node.js process.
+*
+* The monitor runs on a configurable interval and optionally invokes a
+* callback with the collected metrics on each cycle. It also exposes
+* methods to start and stop monitoring, retrieve the latest metrics,
+* and update configuration dynamically.
+*
+* @param options Configuration options for the monitor, including sampling
+* interval, maximum thresholds for normalization, and an optional callback.
+* @returns An API object that allows controlling the monitor lifecycle.
+*/
+function createMonitorObserver(options) {
+	let intervalId = null;
+	let lastMetrics = null;
+	let prevHrtime = process.hrtime.bigint();
+	let prevMem = process.memoryUsage();
+	let prevCpu = process.cpuUsage();
+	let prevLoop = performance.eventLoopUtilization();
+	let lastCollectedAt = Date.now();
+	const config = {
+		interval: options?.interval ?? 500,
+		maxMemory: (options?.maxMemory ?? 512) * 1024 * 1024
+	};
+	function start() {
+		if (intervalId) return;
+		intervalId = setInterval(() => {
+			try {
+				const now = Date.now();
+				const metrics = collectMetrics({
+					prevCpu,
+					prevHrtime,
+					prevMem,
+					prevLoop,
+					maxMemory: config.maxMemory,
+					collectedAtMs: now,
+					previousCollectedAtMs: lastCollectedAt,
+					interval: config.interval
+				});
+				lastMetrics = metrics;
+				options?.callback?.(metrics);
+				prevCpu = metrics.cpu.total;
+				prevLoop = metrics.loop.total;
+				prevMem = metrics.memory.total;
+				prevHrtime = process.hrtime.bigint();
+				lastCollectedAt = now;
+			} catch (e) {
+				stop();
+				throw new Error("MonitorObserver: Not available", { cause: e });
+			}
+		}, config.interval);
+		if (typeof intervalId.unref === "function") intervalId.unref();
+	}
+	function stop() {
+		if (intervalId) {
+			clearInterval(intervalId);
+			intervalId = null;
+		}
+	}
+	function getMetrics() {
+		if (lastMetrics) return lastMetrics;
+		return null;
+	}
+	function updateConfig(newConfig) {
+		if (newConfig.maxMemory !== void 0) config.maxMemory = newConfig.maxMemory * 1024 * 1024;
+		if (newConfig.interval !== void 0) {
+			config.interval = newConfig.interval;
+			if (intervalId) {
+				stop();
+				start();
+			}
+		}
+	}
+	return {
+		start,
+		stop,
+		getMetrics,
+		updateConfig
+	};
+}
+/**
+* Collects and normalizes performance metrics for the current process,
+* including memory usage, CPU usage, and event loop utilization.
+*
+* CPU and event loop metrics are computed as deltas relative to previously
+* recorded values. All metrics are normalized into a utilization between 0 and 1
+* based on the configured maximum thresholds.
+*
+* @param props Previous metric snapshots and normalization limits.
+* @returns A structured object containing normalized performance metrics.
+*/
+function collectMetrics(props) {
+	const nowHrtime = process.hrtime.bigint();
+	const elapsedMs = Number(nowHrtime - props.prevHrtime) / 1e6;
+	const actualElapsed = props.collectedAtMs - props.previousCollectedAtMs;
+	const mem = process.memoryUsage();
+	const deltaMem = {
+		rss: mem.rss - props.prevMem.rss,
+		heapTotal: mem.heapTotal - props.prevMem.heapTotal,
+		heapUsed: mem.heapUsed - props.prevMem.heapUsed,
+		external: mem.external - props.prevMem.external,
+		arrayBuffers: mem.arrayBuffers - props.prevMem.arrayBuffers
+	};
+	const memRatio = Math.min(1, mem.rss / props.maxMemory);
+	const cpuDelta = process.cpuUsage(props.prevCpu);
+	const cpuRatio = (cpuDelta.system + cpuDelta.user) / 1e3 / elapsedMs;
+	const loop = performance.eventLoopUtilization(props.prevLoop);
+	return {
+		cpu: {
+			utilization: cpuRatio,
+			delta: cpuDelta,
+			total: process.cpuUsage()
+		},
+		loop: {
+			utilization: loop.utilization,
+			delta: loop,
+			total: performance.eventLoopUtilization()
+		},
+		memory: {
+			utilization: memRatio,
+			delta: deltaMem,
+			total: mem
+		},
+		collectedAt: props.collectedAtMs,
+		previousCollectedAt: props.previousCollectedAtMs,
+		interval: props.interval,
+		actualElapsed
+	};
+}
+
+//#endregion
+//#region src/utils/start-monitor.ts
+let _monitorInstance = null;
+/** Latest collected metrics from the monitor */
+let _metrics;
+/** Maximum memory limit for the monitor (in MB) */
+let maxMemoryLimit = DEFAULT_MAX_PROCESS_MEMORY_MB;
+function startMonitor() {
+	if (!_monitorInstance) {
+		try {
+			const processMemoryLimit = getProcessMemoryLimit();
+			if (processMemoryLimit) maxMemoryLimit = processMemoryLimit / 1024 / 1024;
+		} catch {}
+		_monitorInstance = createMonitorObserver({
+			callback(metrics) {
+				_metrics = metrics;
+			},
+			interval: 200,
+			maxMemory: maxMemoryLimit
+		});
+		_monitorInstance.start();
+	}
+}
+
+//#endregion
+//#region src/sweep/batchUpdateExpiredRatio.ts
+/**
+* Updates the expired ratio for each cache instance based on the collected ratios.
+* @param currentExpiredRatios - An array of arrays containing expired ratios for each cache instance.
+* @internal
+*/
+function _batchUpdateExpiredRatio(currentExpiredRatios) {
+	for (const inst of _instancesCache) {
+		const ratios = currentExpiredRatios[inst._instanceIndexState];
+		if (ratios && ratios.length > 0) {
+			const avgRatio = ratios.reduce((sum, val) => sum + val, 0) / ratios.length;
+			const alpha = .6;
+			inst._expiredRatio = inst._expiredRatio * (1 - alpha) + avgRatio * alpha;
+		}
+	}
+}
+
+//#endregion
+//#region src/utils/interpolate.ts
+/**
+* Interpolates a value between two numeric ranges.
+*
+* Maps `value` from [fromStart, fromEnd] to [toStart, toEnd].
+* Works with inverted ranges, negative values, and any numeric input.
+*/
+function interpolate({ value, fromStart, fromEnd, toStart, toEnd }) {
+	if (fromStart === fromEnd) return toStart;
+	return toStart + (value - fromStart) / (fromEnd - fromStart) * (toEnd - toStart);
+}
+
+//#endregion
+//#region src/sweep/calculate-optimal-sweep-params.ts
+/**
+* Calculates adaptive sweep parameters based on real-time system utilization.
+*
+* Memory utilization is used as-is: higher memory usage → more conservative sweeps.
+* CPU and event loop utilization are inverted: lower usage → more conservative sweeps.
+*
+* This inversion ensures:
+* - When CPU and loop are *free*, sweeping becomes more aggressive (worst-case behavior).
+* - When CPU and loop are *busy*, sweeping becomes more conservative (optimal behavior).
+*
+* The final ratio is a weighted average of the three metrics, clamped to [0, 1].
+* This ratio is then used to interpolate between optimal and worst-case sweep settings.
+*
+* @param options - Optional configuration for weights and sweep bounds.
+* @returns Interpolated sweep interval, time budget, and the ratio used.
+*/
+const calculateOptimalSweepParams = (options) => {
+	const { metrics, weights = {}, optimalSweepIntervalMs = OPTIMAL_SWEEP_INTERVAL, worstSweepIntervalMs = 200, worstSweepTimeBudgetMs = 40 } = options;
+	const memoryWeight = weights.memory ?? 10;
+	const cpuWeight = weights.cpu ?? 8.5;
+	const loopWeight = weights.loop ?? 6.5;
+	const memoryUtilization = metrics?.memory.utilization ?? 0;
+	const cpuUtilizationRaw = metrics?.cpu.utilization ?? 0;
+	const loopUtilizationRaw = metrics?.loop.utilization ?? 0;
+	const cpuUtilization = 1 - cpuUtilizationRaw;
+	const loopUtilization = 1 - loopUtilizationRaw;
+	const weightedSum = memoryUtilization * memoryWeight + cpuUtilization * cpuWeight + loopUtilization * loopWeight;
+	const totalWeight = memoryWeight + cpuWeight + loopWeight;
+	const ratio = Math.min(1, Math.max(0, weightedSum / totalWeight));
+	return {
+		sweepIntervalMs: interpolate({
+			value: ratio,
+			fromStart: 0,
+			fromEnd: 1,
+			toStart: optimalSweepIntervalMs,
+			toEnd: worstSweepIntervalMs
+		}),
+		sweepTimeBudgetMs: interpolate({
+			value: ratio,
+			fromStart: 0,
+			fromEnd: 1,
+			toStart: 0,
+			toEnd: worstSweepTimeBudgetMs
+		})
+	};
+};
+
+//#endregion
+//#region src/sweep/select-instance-to-sweep.ts
+/**
+* Selects a cache instance to sweep based on sweep weights or round‑robin order.
+*
+* Two selection modes are supported:
+* - **Round‑robin mode**: If `totalSweepWeight` ≤ 0, instances are selected
+*   deterministically in sequence using `batchSweep`. Once all instances
+*   have been processed, returns `null`.
+* - **Weighted mode**: If sweep weights are available, performs a probabilistic
+*   selection. Each instance’s `_sweepWeight` contributes proportionally to its
+*   chance of being chosen.
+*
+* This function depends on `_updateWeightSweep` to maintain accurate sweep weights.
+*
+* @param totalSweepWeight - Sum of all sweep weights across instances.
+* @param batchSweep - Current batch index used for round‑robin selection.
+* @returns The selected `CacheState` instance, `null` if no instance remains,
+* or `undefined` if the cache is empty.
+*/
+function _selectInstanceToSweep({ totalSweepWeight, batchSweep }) {
+	if (totalSweepWeight <= 0) {
+		if (batchSweep > _instancesCache.length) return null;
+		return _instancesCache[batchSweep - 1];
+	}
+	let threshold = Math.random() * totalSweepWeight;
+	for (const inst of _instancesCache) {
+		threshold -= inst._sweepWeight;
+		if (threshold <= 0) return inst;
+	}
+	return _instancesCache[0];
+}
+
+//#endregion
+//#region src/cache/delete.ts
+/**
+* Deletes a key from the cache.
+* @param state - The cache state.
+* @param key - The key.
+* @returns A boolean indicating whether the key was successfully deleted.
+*/
+const deleteKey = (state, key, reason = "manual") => {
+	const onDelete = state.onDelete;
+	const onExpire = state.onExpire;
+	if (!onDelete && !onExpire) return state.store.delete(key);
+	const entry = state.store.get(key);
+	if (!entry) return false;
+	state.store.delete(key);
+	state.onDelete?.(key, entry[1], reason);
+	if (reason !== "manual") state.onExpire?.(key, entry[1], reason);
+	return true;
+};
+
+//#endregion
+//#region src/types.ts
+/**
+* Entry status: fresh, stale, or expired.
+*/
+let ENTRY_STATUS = /* @__PURE__ */ function(ENTRY_STATUS) {
+	/** Valid and within TTL. */
+	ENTRY_STATUS["FRESH"] = "fresh";
+	/** Expired but within stale window; still served. */
+	ENTRY_STATUS["STALE"] = "stale";
+	/** Beyond stale window; not served. */
+	ENTRY_STATUS["EXPIRED"] = "expired";
+	return ENTRY_STATUS;
+}({});
+
+//#endregion
+//#region src/utils/status-from-tags.ts
+/**
+* Computes the derived status of a cache entry based on its associated tags.
+*
+* Tags may impose stricter expiration or stale rules on the entry. Only tags
+* created at or after the entry's creation timestamp are considered relevant.
+*
+* Resolution rules:
+* - If any applicable tag marks the entry as expired, the status becomes `EXPIRED`.
+* - Otherwise, if any applicable tag marks it as stale, the status becomes `STALE`.
+* - If no tag imposes stricter rules, the entry remains `FRESH`.
+*
+* @param state - The cache state containing tag metadata.
+* @param entry - The cache entry whose status is being evaluated.
+* @returns A tuple containing:
+*   - The final {@link ENTRY_STATUS} imposed by tags.
+*   - The earliest timestamp at which a tag marked the entry as stale
+*     (or 0 if no tag imposed a stale rule).
+*/
+function _statusFromTags(state, entry) {
+	const entryCreatedAt = entry[0][0];
+	let earliestTagStaleInvalidation = Infinity;
+	let status = "fresh";
+	const tags = entry[2];
+	if (tags) for (const tag of tags) {
+		const ts = state._tags.get(tag);
+		if (!ts) continue;
+		const [tagExpiredAt, tagStaleSinceAt] = ts;
+		if (tagExpiredAt >= entryCreatedAt) {
+			status = "expired";
+			break;
+		}
+		if (tagStaleSinceAt >= entryCreatedAt) {
+			if (tagStaleSinceAt < earliestTagStaleInvalidation) earliestTagStaleInvalidation = tagStaleSinceAt;
+			status = "stale";
+		}
+	}
+	return [status, status === "stale" ? earliestTagStaleInvalidation : 0];
+}
+
+//#endregion
+//#region src/cache/validators.ts
+/**
+* Computes the final derived status of a cache entry by combining:
+*
+* - The entry's own expiration timestamps (TTL and stale TTL).
+* - Any stricter expiration or stale rules imposed by its associated tags.
+*
+* Precedence rules:
+* - `EXPIRED` overrides everything.
+* - `STALE` overrides `FRESH`.
+* - If neither the entry nor its tags impose stricter rules, the entry is `FRESH`.
+*
+* @param state - The cache state containing tag metadata.
+* @param entry - The cache entry being evaluated.
+* @returns The final {@link ENTRY_STATUS} for the entry.
+*/
+function computeEntryStatus(state, entry, now) {
+	const [__createdAt, expiresAt, staleExpiresAt] = entry[0];
+	const [tagStatus, earliestTagStaleInvalidation] = _statusFromTags(state, entry);
+	if (tagStatus === "expired") return "expired";
+	const windowStale = staleExpiresAt - expiresAt;
+	if (tagStatus === "stale" && staleExpiresAt > 0 && now < earliestTagStaleInvalidation + windowStale && now <= staleExpiresAt) return "stale";
+	if (now < expiresAt) return "fresh";
+	if (staleExpiresAt > 0 && now < staleExpiresAt) return "stale";
+	return "expired";
+}
+/**
+* Determines whether a cache entry is fresh.
+*
+* A fresh entry is one whose final derived status is `FRESH`, meaning:
+* - It has not expired according to its own timestamps, and
+* - No associated tag imposes a stricter stale or expired rule.
+*
+* `entry` can be either a {@link CacheEntry} or a pre-computed {@link ENTRY_STATUS}.
+* Passing a pre-computed status avoids recalculating the entry status.
+*
+* @param state - The cache state containing tag metadata.
+* @param entry - The cache entry or pre-computed status being evaluated.
+* @param now - The current timestamp.
+* @returns True if the entry is fresh.
+*/
+const isFresh = (state, entry, now) => {
+	if (typeof entry === "string") return entry === "fresh";
+	return computeEntryStatus(state, entry, now) === "fresh";
+};
+/**
+* Determines whether a cache entry is stale.
+*
+* A stale entry is one whose final derived status is `STALE`, meaning:
+* - It has passed its TTL but is still within its stale window, or
+* - A tag imposes a stale rule that applies to this entry.
+*
+* `entry` can be either a {@link CacheEntry} or a pre-computed {@link ENTRY_STATUS}.
+* Passing a pre-computed status avoids recalculating the entry status.
+*
+* @param state - The cache state containing tag metadata.
+* @param entry - The cache entry or pre-computed status being evaluated.
+* @param now - The current timestamp.
+* @returns True if the entry is stale.
+*/
+const isStale = (state, entry, now) => {
+	if (typeof entry === "string") return entry === "stale";
+	return computeEntryStatus(state, entry, now) === "stale";
+};
+/**
+* Determines whether a cache entry is expired.
+*
+* An expired entry is one whose final derived status is `EXPIRED`, meaning:
+* - It has exceeded both its TTL and stale TTL, or
+* - A tag imposes an expiration rule that applies to this entry.
+*
+* `entry` can be either a {@link CacheEntry} or a pre-computed {@link ENTRY_STATUS}.
+* Passing a pre-computed status avoids recalculating the entry status.
+*
+* @param state - The cache state containing tag metadata.
+* @param entry - The cache entry or pre-computed status being evaluated.
+* @param now - The current timestamp.
+* @returns True if the entry is expired.
+*/
+const isExpired = (state, entry, now) => {
+	if (typeof entry === "string") return entry === "expired";
+	return computeEntryStatus(state, entry, now) === "expired";
+};
+
+//#endregion
+//#region src/utils/purge-eval.ts
+/**
+* Computes memory utilization as a normalized 0–1 value.
+*
+* In backend environments where metrics are available, returns the actual
+* memory utilization from the monitor. In browser environments or when
+* metrics are unavailable, returns 0.
+*
+* @returns Memory utilization in range [0, 1]
+*
+* @internal
+*/
+const getMemoryUtilization = () => {
+	if (!_metrics) return 0;
+	return _metrics.memory?.utilization ?? 0;
+};
+/**
+* Computes size utilization as a normalized 0–1 value.
+*
+* If maxSize is finite, returns `currentSize / maxSize`. Otherwise returns 0.
+*
+* @param state - The cache state
+* @returns Size utilization in range [0, 1]
+*
+* @internal
+*/
+const getSizeUtilization = (state) => {
+	if (!Number.isFinite(state.maxSize) || state.maxSize <= 0 || state.size <= 0) return 0;
+	return Math.min(1, state.size / state.maxSize);
+};
+/**
+* Computes a 0–1 resource usage metric based on the configured purge metric.
+*
+* - `"size"`: Returns size utilization only.
+* - `"memory"`: Returns memory utilization (backend only; returns 0 in browser).
+* - `"higher"`: Returns the maximum of memory and size utilization.
+*
+* The result is always clamped to [0, 1].
+*
+* @param state - The cache state
+* @returns Resource usage in range [0, 1]
+*
+* @internal
+*/
+const computeResourceUsage = (state) => {
+	const metric = state.purgeResourceMetric;
+	if (!metric || metric === "fixed") return null;
+	if (metric === "size") return getSizeUtilization(state);
+	if (metric === "memory") return getMemoryUtilization();
+	if (metric === "higher") return Math.min(1, Math.max(getMemoryUtilization(), getSizeUtilization(state)));
+	return null;
+};
+/**
+* Determines whether stale entries should be purged based on the purge mode and current resource usage.
+*
+* @param mode - The purge mode setting
+*  - `false` → never purge
+*  - `true` → always purge
+*  - `number (0–1)` → purge when `resourceUsage >= threshold`
+* @param state - The cache state
+* @returns True if stale entries should be purged, false otherwise
+*
+* @internal
+*/
+const shouldPurge = (mode, state, purgeContext) => {
+	if (mode === false) return false;
+	if (mode === true) return true;
+	const userThreshold = Number(mode);
+	const defaultPurge = purgeContext === "sweep" ? true : false;
+	if (Number.isNaN(userThreshold)) return defaultPurge;
+	const usage = computeResourceUsage(state);
+	if (!usage) return defaultPurge;
+	return usage >= Math.max(0, Math.min(1, userThreshold));
+};
+
+//#endregion
+//#region src/sweep/sweep-once.ts
+/**
+* Performs a single sweep operation on the cache to remove expired and optionally stale entries.
+* Uses a linear scan with a saved pointer to resume from the last processed key.
+* @param state - The cache state.
+* @param _maxKeysPerBatch - Maximum number of keys to process in this sweep.
+* @returns An object containing statistics about the sweep operation.
+*/
+function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
+	if (!state._sweepIter) state._sweepIter = state.store.entries();
+	const now = Date.now();
+	let processed = 0;
+	let expiredCount = 0;
+	let staleCount = 0;
+	const shouldPurgeStale = shouldPurge(state.purgeStaleOnSweep, state, "sweep");
+	for (let i = 0; i < _maxKeysPerBatch; i++) {
+		const next = state._sweepIter.next();
+		if (next.done) {
+			state._sweepIter = state.store.entries();
+			break;
+		}
+		processed += 1;
+		const [key, entry] = next.value;
+		const status = computeEntryStatus(state, entry, now);
+		if (isExpired(state, status, now)) {
+			deleteKey(state, key, "expired");
+			expiredCount += 1;
+		} else if (isStale(state, status, now)) {
+			staleCount += 1;
+			if (shouldPurgeStale) deleteKey(state, key, "stale");
+		}
+	}
+	return {
+		processed,
+		expiredCount,
+		staleCount,
+		ratio: processed > 0 ? (expiredCount + (shouldPurgeStale ? staleCount : 0)) / processed : 0
+	};
+}
+
+//#endregion
+//#region src/sweep/calculate-optimal-max-expired-ratio.ts
+/**
+* Calculates the optimal maximum expired ratio based on current memory utilization.
+*
+* This function interpolates between `maxAllowExpiredRatio` and `MINIMAL_EXPIRED_RATIO`
+* depending on the memory usage reported by `_metrics`. At low memory usage (0%),
+* the optimal ratio equals `maxAllowExpiredRatio`. At high memory usage
+* the optimal ratio decreases toward `MINIMAL_EXPIRED_RATIO`.
+*
+* @param maxAllowExpiredRatio - The maximum allowed expired ratio at minimal memory usage.
+* Defaults to `DEFAULT_MAX_EXPIRED_RATIO`.
+* @returns A normalized value between 0 and 1 representing the optimal expired ratio.
+*/
+function calculateOptimalMaxExpiredRatio(maxAllowExpiredRatio = DEFAULT_MAX_EXPIRED_RATIO) {
+	const optimalExpiredRatio = interpolate({
+		value: _metrics?.memory.utilization ?? 0,
+		fromStart: 0,
+		fromEnd: 1,
+		toStart: maxAllowExpiredRatio,
+		toEnd: MINIMAL_EXPIRED_RATIO
+	});
+	return Math.min(1, Math.max(0, optimalExpiredRatio));
+}
+
+//#endregion
+//#region src/sweep/update-weight.ts
+/**
+* Updates the sweep weight (`_sweepWeight`) for each cache instance.
+*
+* The sweep weight determines the probability that an instance will be selected
+* for a cleanup (sweep) process. It is calculated based on the store size and
+* the ratio of expired keys.
+*
+* This function complements (`_selectInstanceToSweep`), which is responsible
+* for selecting the correct instance based on the weights assigned here.
+*
+* ### Sweep systems:
+* 1. **Normal sweep**
+*    - Runs whenever the percentage of expired keys exceeds the allowed threshold
+*      calculated by `calculateOptimalMaxExpiredRatio`.
+*    - It is the main cleanup mechanism and is applied proportionally to the
+*      store size and the expired‑key ratio.
+*
+* 2. **Round‑robin sweep (minimal control)**
+*    - Always runs, even if the expired ratio is low or memory usage does not
+*      require it.
+*    - Processes a very small number of keys per instance, much smaller than
+*      the normal sweep.
+*    - Its main purpose is to ensure that all instances receive at least a
+*      periodic weight update and minimal expired‑key control.
+*
+* @returns The total accumulated sweep weight across all cache instances.
+*/
+function _updateWeightSweep() {
+	let totalSweepWeight = 0;
+	for (const instCache of _instancesCache) {
+		if (instCache.store.size <= 0) {
+			instCache._sweepWeight = 0;
+			continue;
+		}
+		const expiredRatio = instCache._expiredRatio;
+		if (expiredRatio <= calculateOptimalMaxExpiredRatio(instCache._maxAllowExpiredRatio)) {
+			instCache._sweepWeight = 0;
+			continue;
+		}
+		instCache._sweepWeight = instCache.store.size * expiredRatio;
+		totalSweepWeight += instCache._sweepWeight;
+	}
+	return totalSweepWeight;
+}
+
+//#endregion
+//#region src/sweep/sweep.ts
+let _isSweepActive = false;
+let _pendingSweepTimeout = null;
+function startSweep(state) {
+	if (_isSweepActive) return;
+	_isSweepActive = true;
+	startMonitor();
+	sweep(state);
+}
+/**
+* Performs a sweep operation on the cache to remove expired and optionally stale entries.
+* Uses a linear scan with a saved pointer to resume from the last processed key.
+* @param state - The cache state.
+*/
+const sweep = async (state, utilities = {}) => {
+	const { schedule = defaultSchedule, yieldFn = defaultYieldFn, now = Date.now(), runOnlyOne = false } = utilities;
+	const startTime = now;
+	let sweepIntervalMs = OPTIMAL_SWEEP_INTERVAL;
+	let sweepTimeBudgetMs = 15;
+	if (_metrics) ({sweepIntervalMs, sweepTimeBudgetMs} = calculateOptimalSweepParams({ metrics: _metrics }));
+	const totalSweepWeight = _updateWeightSweep();
+	const currentExpiredRatios = [];
+	const maxKeysPerBatch = totalSweepWeight <= 0 ? MAX_KEYS_PER_BATCH / _instancesCache.length : MAX_KEYS_PER_BATCH;
+	let batchSweep = 0;
+	while (true) {
+		batchSweep += 1;
+		const instanceToSweep = _selectInstanceToSweep({
+			batchSweep,
+			totalSweepWeight
+		});
+		if (!instanceToSweep) break;
+		const { ratio } = _sweepOnce(instanceToSweep, maxKeysPerBatch);
+		(currentExpiredRatios[instanceToSweep._instanceIndexState] ??= []).push(ratio);
+		if (Date.now() - startTime > sweepTimeBudgetMs) break;
+		await yieldFn();
+	}
+	_batchUpdateExpiredRatio(currentExpiredRatios);
+	if (!runOnlyOne) schedule(() => void sweep(state, utilities), sweepIntervalMs);
+};
+const defaultSchedule = (fn, ms) => {
+	_pendingSweepTimeout = setTimeout(fn, ms);
+	if (typeof _pendingSweepTimeout.unref === "function") _pendingSweepTimeout.unref();
+};
+const defaultYieldFn = () => new Promise((resolve) => setImmediate(resolve));
+
+//#endregion
+//#region src/cache/create-cache.ts
+let _instanceCount = 0;
+const INSTANCE_WARNING_THRESHOLD = 99;
+const _instancesCache = [];
+/**
+* Creates the initial state for the TTL cache.
+* @param options - Configuration options for the cache.
+* @returns The initial cache state.
+*/
+const createCache = (options = {}) => {
+	const { onExpire, onDelete, defaultTtl = DEFAULT_TTL, maxSize = DEFAULT_MAX_SIZE, maxMemorySize = DEFAULT_MAX_MEMORY_SIZE, _maxAllowExpiredRatio = DEFAULT_MAX_EXPIRED_RATIO, defaultStaleWindow = 0, purgeStaleOnGet, purgeStaleOnSweep, purgeResourceMetric, _autoStartSweep = true } = options;
+	_instanceCount++;
+	if (_instanceCount > INSTANCE_WARNING_THRESHOLD) console.warn(`Too many instances detected (${_instanceCount}). This may indicate a configuration issue; consider minimizing instance creation or grouping keys by expected expiration ranges. See the documentation: https://github.com/neezco/cache/docs/getting-started.md`);
+	const resolvedPurgeResourceMetric = purgeResourceMetric ?? resolvePurgeResourceMetric({
+		maxSize,
+		maxMemorySize
+	});
+	const resolvedPurgeStaleOnGet = resolvePurgeStaleOnGet({
+		limits: {
+			maxSize,
+			maxMemorySize
+		},
+		purgeResourceMetric: resolvedPurgeResourceMetric,
+		userValue: purgeStaleOnGet
+	});
+	const resolvedPurgeStaleOnSweep = resolvePurgeStaleOnSweep({
+		limits: {
+			maxSize,
+			maxMemorySize
+		},
+		purgeResourceMetric: resolvedPurgeResourceMetric,
+		userValue: purgeStaleOnSweep
+	});
+	const state = {
+		store: /* @__PURE__ */ new Map(),
+		_sweepIter: null,
+		get size() {
+			return state.store.size;
+		},
+		onExpire,
+		onDelete,
+		maxSize,
+		maxMemorySize,
+		defaultTtl,
+		defaultStaleWindow,
+		purgeStaleOnGet: resolvedPurgeStaleOnGet,
+		purgeStaleOnSweep: resolvedPurgeStaleOnSweep,
+		purgeResourceMetric: resolvedPurgeResourceMetric,
+		_maxAllowExpiredRatio,
+		_autoStartSweep,
+		_instanceIndexState: -1,
+		_expiredRatio: 0,
+		_sweepWeight: 0,
+		_tags: /* @__PURE__ */ new Map()
+	};
+	state._instanceIndexState = _instancesCache.push(state) - 1;
+	startSweep(state);
+	return state;
+};
+
+//#endregion
+//#region src/cache/get.ts
+/**
+* Internal function that retrieves a value from the cache with its status information.
+* Returns a tuple containing the entry status and the complete cache entry.
+*
+* @param state - The cache state.
+* @param key - The key to retrieve.
+* @param now - Optional timestamp override (defaults to Date.now()).
+* @returns A tuple of [status, entry] if the entry is valid, or [null, undefined] if not found or expired.
+*
+* @internal
+*/
+const getWithStatus = (state, key, purgeMode, now = Date.now()) => {
+	const entry = state.store.get(key);
+	if (!entry) return [null, void 0];
+	const status = computeEntryStatus(state, entry, now);
+	if (isFresh(state, status, now)) return [status, entry];
+	if (isStale(state, status, now)) {
+		if (shouldPurge(purgeMode ?? state.purgeStaleOnGet, state, "get")) deleteKey(state, key, "stale");
+		return [status, entry];
+	}
+	deleteKey(state, key, "expired");
+	return [status, void 0];
+};
+/**
+* Retrieves a value from the cache if the entry is valid.
+* @param state - The cache state.
+* @param key - The key to retrieve.
+* @param now - Optional timestamp override (defaults to Date.now()).
+* @returns The cached value if valid, undefined otherwise.
+*
+* @internal
+*/
+const get = (state, key, purgeMode, now = Date.now()) => {
+	const [, entry] = getWithStatus(state, key, purgeMode, now);
+	return entry ? entry[1] : void 0;
+};
+
+//#endregion
+//#region src/cache/has.ts
+/**
+* Checks if a key exists in the cache and is not expired.
+* @param state - The cache state.
+* @param key - The key to check.
+* @param now - Optional timestamp override (defaults to Date.now()).
+* @returns True if the key exists and is valid, false otherwise.
+*/
+const has = (state, key, now = Date.now()) => {
+	return get(state, key, now) !== void 0;
+};
+
+//#endregion
+//#region src/cache/invalidate-tag.ts
+/**
+* Invalidates one or more tags so that entries associated with them
+* become expired or stale from this moment onward.
+*
+* Semantics:
+* - Each tag maintains two timestamps in `state._tags`:
+*   [expiredAt, staleSinceAt].
+* - Calling this function updates one of those timestamps to `_now`,
+*   depending on whether the tag should force expiration or staleness.
+*
+* Rules:
+* - If `asStale` is false (default), the tag forces expiration:
+*   entries created before `_now` will be considered expired.
+* - If `asStale` is true, the tag forces staleness:
+*   entries created before `_now` will be considered stale,
+*   but only if they support a stale window.
+*
+* Behavior:
+* - Each call replaces any previous invalidation timestamp for the tag.
+* - Entries created after `_now` are unaffected.
+*
+* @param state - The cache state containing tag metadata.
+* @param tags - A tag or list of tags to invalidate.
+* @param options.asStale - Whether the tag should mark entries as stale.
+*/
+function invalidateTag(state, tags, options = {}, _now = Date.now()) {
+	const tagList = Array.isArray(tags) ? tags : [tags];
+	const asStale = options.asStale ?? false;
+	for (const tag of tagList) {
+		const currentTag = state._tags.get(tag);
+		if (currentTag) if (asStale) currentTag[1] = _now;
+		else currentTag[0] = _now;
+		else state._tags.set(tag, [asStale ? 0 : _now, asStale ? _now : 0]);
+	}
+}
+
+//#endregion
+//#region src/cache/set.ts
+/**
+* Sets or updates a value in the cache with TTL and an optional stale window.
+*
+* @param state - The cache state.
+* @param input - Cache entry definition (key, value, ttl, staleWindow, tags).
+* @param now - Optional timestamp override used as the base time (defaults to Date.now()).
+* @returns True if the entry was created or updated, false if rejected due to limits or invalid input.
+*
+* @remarks
+* - `ttl` defines when the entry becomes expired.
+* - `staleWindow` defines how long the entry may still be served as stale
+*   after the expiration moment (`now + ttl`).
+* - Returns false if value is `undefined` (entry ignored, existing value untouched).
+* - Returns false if new entry would exceed `maxSize` limit (existing keys always allowed).
+* - Returns false if new entry would exceed `maxMemorySize` limit (existing keys always allowed).
+* - Returns true if entry was set or updated (or if existing key was updated at limit).
+*/
+const setOrUpdate = (state, input, now = Date.now()) => {
+	const { key, value, ttl: ttlInput, staleWindow: staleWindowInput, tags } = input;
+	if (value === void 0) return false;
+	if (key == null) throw new Error("Missing key.");
+	if (state.size >= state.maxSize && !state.store.has(key)) return false;
+	if (_metrics?.memory.total.rss && _metrics?.memory.total.rss >= state.maxMemorySize * 1024 * 1024 && !state.store.has(key)) return false;
+	const ttl = ttlInput ?? state.defaultTtl;
+	const staleWindow = staleWindowInput ?? state.defaultStaleWindow;
+	const expiresAt = ttl > 0 ? now + ttl : Infinity;
+	const entry = [
+		[
+			now,
+			expiresAt,
+			staleWindow > 0 ? expiresAt + staleWindow : 0
+		],
+		value,
+		typeof tags === "string" ? [tags] : Array.isArray(tags) ? tags : null
+	];
+	state.store.set(key, entry);
+	return true;
+};
+
+//#endregion
+//#region src/index.ts
+/**
+* A TTL (Time-To-Live) cache implementation with support for expiration,
+* stale windows, tag-based invalidation, and smart automatic sweeping.
+*
+* Provides O(1) constant-time operations for all core methods with support for:
+* - Expiration and stale windows
+* - Tag-based invalidation
+* - Automatic sweeping
+*/
+var LocalTtlCache = class {
+	state;
+	/**
+	* Creates a new cache instance.
+	*
+	* @param options - Configuration options for the cache (defaultTtl, defaultStaleWindow, maxSize, etc.)
+	*
+	*/
+	constructor(options) {
+		this.state = createCache(options);
+	}
+	get size() {
+		return this.state.size;
+	}
+	get(key, options) {
+		if (options?.includeMetadata === true) {
+			const [status, entry] = getWithStatus(this.state, key, options.purgeStale);
+			if (!entry) return void 0;
+			const [timestamps, value, tags] = entry;
+			const [createdAt, expiresAt, staleExpiresAt] = timestamps;
+			return {
+				data: value,
+				createdAt,
+				expirationTime: expiresAt,
+				staleWindowExpiration: staleExpiresAt,
+				status,
+				tags
+			};
+		}
+		return get(this.state, key, options?.purgeStale);
+	}
+	set(key, value, options) {
+		return setOrUpdate(this.state, {
+			key,
+			value,
+			ttl: options?.ttl,
+			staleWindow: options?.staleWindow,
+			tags: options?.tags
+		});
+	}
+	delete(key) {
+		return deleteKey(this.state, key);
+	}
+	has(key) {
+		return has(this.state, key);
+	}
+	clear() {
+		clear(this.state);
+	}
+	invalidateTag(tags, options) {
+		invalidateTag(this.state, tags, options ?? {});
+	}
+};
+
+//#endregion
+export { ENTRY_STATUS, LocalTtlCache };
+//# sourceMappingURL=index.mjs.map