@neezco/cache 0.1.0

package/dist/node/index.cjs

@@ -0,0 +1,1153 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let fs = require("fs");
+fs = __toESM(fs);
+let v8 = require("v8");
+v8 = __toESM(v8);
+let perf_hooks = require("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.
+* Optimized for short-lived data (3 minutes by default).
+* @default 1_800_000 (30 minutes)
+*/
+const DEFAULT_TTL = 30 * ONE_MINUTE;
+/**
+* Default stale window in milliseconds after expiration.
+* Allows serving slightly outdated data while fetching fresh data.
+*/
+const DEFAULT_STALE_WINDOW = 0;
+/**
+* Maximum number of entries the cache can hold.
+* Beyond this limit, less-used entries are evicted.
+*/
+const DEFAULT_MAX_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.
+* Ensures control sweeps run above {@link EXPIRED_RATIO_MEMORY_THRESHOLD}.
+*/
+const MINIMAL_EXPIRED_RATIO = .05;
+/**
+* Memory usage threshold (normalized 0–1) triggering control sweeps.
+* At or above this level, sweeping becomes more aggressive.
+*/
+const EXPIRED_RATIO_MEMORY_THRESHOLD = .8;
+/**
+* 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;
+/**
+* Worst-case interval in milliseconds between sweeps.
+* Used when system load is high or metrics unavailable.
+*/
+const WORST_SWEEP_INTERVAL = 200;
+/**
+* Maximum time budget in milliseconds for sweep operations.
+* Prevents sweeping from consuming excessive CPU during high load.
+*/
+const WORST_SWEEP_TIME_BUDGET = 40;
+/**
+* Optimal time budget in milliseconds for each sweep cycle.
+* Used when performance metrics are not available or unreliable.
+*/
+const OPTIMAL_SWEEP_TIME_BUDGET_IF_NOTE_METRICS_AVAILABLE = 15;
+/**
+* ===================================================================
+* 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;
+/**
+* ===================================================================
+* System Utilization Weights
+* Balance how memory, CPU, and event-loop pressure influence sweep behavior.
+* Sum of all weights: 10 + 8.5 + 6.5 = 25
+* ===================================================================
+*/
+/**
+* Weight applied to memory utilization in sweep calculations.
+* Higher weight = memory pressure has more influence on sweep aggressiveness.
+*/
+const DEFAULT_MEMORY_WEIGHT = 10;
+/**
+* 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;
+
+//#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.default.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.default.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 = perf_hooks.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 = perf_hooks.performance.eventLoopUtilization(props.prevLoop);
+	return {
+		cpu: {
+			utilization: cpuRatio,
+			delta: cpuDelta,
+			total: process.cpuUsage()
+		},
+		loop: {
+			utilization: loop.utilization,
+			delta: loop,
+			total: perf_hooks.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;
+/** Use 90% of the effective limit */
+const SAFE_MEMORY_LIMIT_RATIO = .9;
+function startMonitor() {
+	if (!_monitorInstance) {
+		try {
+			const processMemoryLimit = getProcessMemoryLimit();
+			if (processMemoryLimit && processMemoryLimit > 0) maxMemoryLimit = processMemoryLimit / 1024 / 1024 * SAFE_MEMORY_LIMIT_RATIO;
+		} catch {}
+		_monitorInstance = createMonitorObserver({
+			callback(metrics) {
+				_metrics = metrics;
+			},
+			interval: WORST_SWEEP_INTERVAL,
+			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 = WORST_SWEEP_INTERVAL, worstSweepTimeBudgetMs = WORST_SWEEP_TIME_BUDGET } = options;
+	const memoryWeight = weights.memory ?? DEFAULT_MEMORY_WEIGHT;
+	const cpuWeight = weights.cpu ?? DEFAULT_CPU_WEIGHT;
+	const loopWeight = weights.loop ?? DEFAULT_LOOP_WEIGHT;
+	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 }) {
+	let instanceToSweep = _instancesCache[0];
+	if (totalSweepWeight <= 0) {
+		if (batchSweep > _instancesCache.length) instanceToSweep = null;
+		instanceToSweep = _instancesCache[batchSweep - 1];
+	} else {
+		let threshold = Math.random() * totalSweepWeight;
+		for (const inst of _instancesCache) {
+			threshold -= inst._sweepWeight;
+			if (threshold <= 0) {
+				instanceToSweep = inst;
+				break;
+			}
+		}
+	}
+	return instanceToSweep;
+}
+
+//#endregion
+//#region src/cache/delete.ts
+let DELETE_REASON = /* @__PURE__ */ function(DELETE_REASON$1) {
+	DELETE_REASON$1["MANUAL"] = "manual";
+	DELETE_REASON$1["EXPIRED"] = "expired";
+	DELETE_REASON$1["STALE"] = "stale";
+	return DELETE_REASON$1;
+}({});
+/**
+* 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 = DELETE_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 !== DELETE_REASON.MANUAL) state.onExpire?.(key, entry[1], reason);
+	return true;
+};
+
+//#endregion
+//#region src/types.ts
+/**
+* Status of a cache entry.
+*/
+let ENTRY_STATUS = /* @__PURE__ */ function(ENTRY_STATUS$1) {
+	/** The entry is fresh and valid. */
+	ENTRY_STATUS$1["FRESH"] = "fresh";
+	/** The entry is stale but can still be served. */
+	ENTRY_STATUS$1["STALE"] = "stale";
+	/** The entry has expired and is no longer valid. */
+	ENTRY_STATUS$1["EXPIRED"] = "expired";
+	return ENTRY_STATUS$1;
+}({});
+
+//#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 = ENTRY_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 = ENTRY_STATUS.EXPIRED;
+			break;
+		}
+		if (tagStaleSinceAt >= entryCreatedAt) {
+			if (tagStaleSinceAt < earliestTagStaleInvalidation) earliestTagStaleInvalidation = tagStaleSinceAt;
+			status = ENTRY_STATUS.STALE;
+		}
+	}
+	return [status, status === ENTRY_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 === ENTRY_STATUS.EXPIRED) return ENTRY_STATUS.EXPIRED;
+	const windowStale = staleExpiresAt - expiresAt;
+	if (tagStatus === ENTRY_STATUS.STALE && staleExpiresAt > 0 && now < earliestTagStaleInvalidation + windowStale) return ENTRY_STATUS.STALE;
+	if (now < expiresAt) return ENTRY_STATUS.FRESH;
+	if (staleExpiresAt > 0 && now < staleExpiresAt) return ENTRY_STATUS.STALE;
+	return ENTRY_STATUS.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.
+*
+* @param state - The cache state containing tag metadata.
+* @param entry - The cache entry being evaluated.
+* @returns True if the entry is fresh.
+*/
+const isFresh = (state, entry, now) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.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.
+*
+* @param state - The cache state containing tag metadata.
+* @param entry - The cache entry being evaluated.
+* @returns True if the entry is stale.
+*/
+const isStale = (state, entry, now) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.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.
+*
+* @param state - The cache state containing tag metadata.
+* @param entry - The cache entry being evaluated.
+* @returns True if the entry is expired.
+*/
+const isExpired = (state, entry, now) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.EXPIRED;
+
+//#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();
+	let processed = 0;
+	let expiredCount = 0;
+	let staleCount = 0;
+	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 now = Date.now();
+		if (isExpired(state, entry, now)) {
+			deleteKey(state, key, DELETE_REASON.EXPIRED);
+			expiredCount += 1;
+		} else if (isStale(state, entry, now)) {
+			staleCount += 1;
+			if (state.purgeStaleOnSweep) deleteKey(state, key, DELETE_REASON.STALE);
+		}
+	}
+	const expiredStaleCount = state.purgeStaleOnSweep ? staleCount : 0;
+	return {
+		processed,
+		expiredCount,
+		staleCount,
+		ratio: processed > 0 ? (expiredCount + expiredStaleCount) / 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`. As memory usage approaches or exceeds
+* 80% of the memory limit, 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 EFFECTIVE_MEMORY_THRESHOLD = EXPIRED_RATIO_MEMORY_THRESHOLD / SAFE_MEMORY_LIMIT_RATIO;
+	const optimalExpiredRatio = interpolate({
+		value: _metrics?.memory.utilization ?? 0,
+		fromStart: 0,
+		fromEnd: EFFECTIVE_MEMORY_THRESHOLD,
+		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. **Memory‑conditioned sweep (control)**
+*    - Works exactly like the normal sweep, except it may run even when it
+*      normally wouldn’t.
+*    - Only activates under **high memory pressure**.
+*    - Serves as an additional control mechanism to adjust weights, keep the
+*      system updated, and help prevent memory overflows.
+*
+* 3. **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.
+*
+* ---
+* #### Important notes:
+* - A minimum `MINIMAL_EXPIRED_RATIO` (e.g., 5%) is assumed to ensure that
+*   control sweeps can always run under high‑memory scenarios.
+* - Even with a minimum ratio, the normal sweep and the memory‑conditioned sweep
+*   may **skip execution** if memory usage allows it and the expired ratio is
+*   below the optimal maximum.
+* - The round‑robin sweep is never skipped: it always runs with a very small,
+*   almost imperceptible cost.
+*
+* @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;
+		}
+		let expiredRatio = MINIMAL_EXPIRED_RATIO;
+		if (instCache._expiredRatio > MINIMAL_EXPIRED_RATIO) expiredRatio = instCache._expiredRatio;
+		{
+			const optimalMaxExpiredRatio = calculateOptimalMaxExpiredRatio(instCache._maxAllowExpiredRatio);
+			if (expiredRatio <= optimalMaxExpiredRatio) {
+				instCache._sweepWeight = 0;
+				continue;
+			}
+		}
+		instCache._sweepWeight = instCache.store.size * expiredRatio;
+		totalSweepWeight += instCache._sweepWeight;
+	}
+	return totalSweepWeight;
+}
+
+//#endregion
+//#region src/sweep/sweep.ts
+/**
+* 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 = OPTIMAL_SWEEP_TIME_BUDGET_IF_NOTE_METRICS_AVAILABLE;
+	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) => {
+	const t = setTimeout(fn, ms);
+	if (typeof t.unref === "function") t.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 = [];
+let _initSweepScheduled = false;
+/**
+* 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, _maxAllowExpiredRatio = DEFAULT_MAX_EXPIRED_RATIO, defaultStaleWindow = DEFAULT_STALE_WINDOW, purgeStaleOnGet = false, purgeStaleOnSweep = false, _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 state = {
+		store: /* @__PURE__ */ new Map(),
+		_sweepIter: null,
+		get size() {
+			return state.store.size;
+		},
+		onExpire,
+		onDelete,
+		maxSize,
+		defaultTtl,
+		defaultStaleWindow,
+		purgeStaleOnGet,
+		purgeStaleOnSweep,
+		_maxAllowExpiredRatio,
+		_autoStartSweep,
+		_instanceIndexState: -1,
+		_expiredRatio: 0,
+		_sweepWeight: 0,
+		_tags: /* @__PURE__ */ new Map()
+	};
+	state._instanceIndexState = _instancesCache.push(state) - 1;
+	if (_autoStartSweep) {
+		if (_initSweepScheduled) return state;
+		_initSweepScheduled = true;
+		sweep(state);
+	}
+	startMonitor();
+	return state;
+};
+
+//#endregion
+//#region src/cache/get.ts
+/**
+* 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, null otherwise.
+*/
+const get = (state, key, now = Date.now()) => {
+	const entry = state.store.get(key);
+	if (!entry) return void 0;
+	if (isFresh(state, entry, now)) return entry[1];
+	if (isStale(state, entry, now)) {
+		if (state.purgeStaleOnGet) deleteKey(state, key, DELETE_REASON.STALE);
+		return entry[1];
+	}
+	deleteKey(state, key, DELETE_REASON.EXPIRED);
+};
+
+//#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()).
+*
+* @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`).
+*/
+const setOrUpdate = (state, input, now = Date.now()) => {
+	const { key, value, ttl: ttlInput, staleWindow: staleWindowInput, tags } = input;
+	if (value === void 0) return;
+	if (key == null) throw new Error("Missing key.");
+	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);
+};
+
+//#endregion
+//#region src/index.ts
+/**
+* A TTL (Time-To-Live) cache implementation with support for expiration,
+* stale windows, tag-based invalidation, and automatic sweeping.
+*
+* Provides O(1) constant-time operations for all core methods.
+*
+* @example
+* ```typescript
+* const cache = new LocalTtlCache();
+* cache.set("user:123", { name: "Alice" }, { ttl: 5 * 60 * 1000 });
+* const user = cache.get("user:123"); // { name: "Alice" }
+* ```
+*/
+var LocalTtlCache = class {
+	state;
+	/**
+	* Creates a new cache instance.
+	*
+	* @param options - Configuration options for the cache (defaultTtl, defaultStaleWindow, maxSize, etc.)
+	*
+	* @example
+	* ```typescript
+	* const cache = new LocalTtlCache({
+	*   defaultTtl: 30 * 60 * 1000, // 30 minutes
+	*   defaultStaleWindow: 5 * 60 * 1000, // 5 minutes
+	*   maxSize: 500_000, // Maximum 500_000 entries
+	*   onExpire: (key, value) => console.log(`Expired: ${key}`),
+	*   onDelete: (key, value, reason) => console.log(`Deleted: ${key}, reason: ${reason}`),
+	* });
+	* ```
+	*/
+	constructor(options) {
+		this.state = createCache(options);
+	}
+	/**
+	* Gets the current number of entries tracked by the cache.
+	*
+	* This value may include entries that are already expired but have not yet been
+	* removed by the lazy cleanup system. Expired keys are cleaned only when it is
+	* efficient to do so, so the count can temporarily be higher than the number of
+	* actually valid (non‑expired) entries.
+	*
+	* @returns The number of entries currently stored (including entries pending cleanup)
+	*
+	* @example
+	* ```typescript
+	* console.log(cache.size); // e.g., 42
+	* ```
+	*/
+	get size() {
+		return this.state.size;
+	}
+	/**
+	* Retrieves a value from the cache.
+	*
+	* Returns the value if it exists and is not fully expired. If an entry is in the
+	* stale window (expired but still within staleWindow), the stale value is returned.
+	*
+	
+	* @param key - The key to retrieve
+	* @returns The cached value if valid, undefined otherwise
+	*
+	* @example
+	* ```typescript
+	* const user = cache.get<{ name: string }>("user:123");
+	* ```
+	*
+	* @edge-cases
+	* - Returns `undefined` if the key doesn't exist
+	* - Returns `undefined` if the key has expired beyond the stale window
+	* - Returns the stale value if within the stale window
+	* - If `purgeStaleOnGet` is enabled, stale entries are deleted after being returned
+	*/
+	get(key) {
+		return get(this.state, key);
+	}
+	/**
+	* Sets or updates a value in the cache.
+	*
+	* If the key already exists, it will be completely replaced.
+	*
+	* @param key - The key under which to store the value
+	* @param value - The value to cache (any type)
+	* @param options - Optional configuration for this specific entry
+	* @param options.ttl - Time-To-Live in milliseconds. Defaults to `defaultTtl`
+	* @param options.staleWindow - How long to serve stale data after expiration (milliseconds)
+	* @param options.tags - One or more tags for group invalidation
+	*
+	* @example
+	* ```typescript
+	* cache.set("user:123", { name: "Alice" }, {
+	*   ttl: 5 * 60 * 1000,
+	*   staleWindow: 1 * 60 * 1000,
+	*   tags: "user:123",
+	* });
+	* ```
+	*
+	* @edge-cases
+	* - Overwriting an existing key replaces it completely
+	* - If `ttl` is 0 or Infinite, the entry never expires
+	* - If `staleWindow` is larger than `ttl`, the entry can be served as stale longer than it was fresh
+	* - Tags are optional; only necessary for group invalidation via `invalidateTag()`
+	*/
+	set(key, value, options) {
+		setOrUpdate(this.state, {
+			key,
+			value,
+			ttl: options?.ttl,
+			staleWindow: options?.staleWindow,
+			tags: options?.tags
+		});
+	}
+	/**
+	* Deletes a specific key from the cache.
+	*
+	* @param key - The key to delete
+	* @returns True if the key was deleted, false if it didn't exist
+	*
+	* @example
+	* ```typescript
+	* const wasDeleted = cache.delete("user:123");
+	* ```
+	*
+	* @edge-cases
+	* - Triggers the `onDelete` callback with reason `'manual'`
+	* - Does not trigger the `onExpire` callback
+	* - Returns `false` if the key was already expired
+	* - Deleting a non-existent key returns `false` without error
+	*/
+	delete(key) {
+		return deleteKey(this.state, key);
+	}
+	/**
+	* Checks if a key exists in the cache and is not fully expired.
+	*
+	* Returns true if the key exists and is either fresh or within the stale window.
+	* Use this when you only need to check existence without retrieving the value.
+	*
+	* @param key - The key to check
+	* @returns True if the key exists and is valid, false otherwise
+	*
+	* @example
+	* ```typescript
+	* if (cache.has("user:123")) {
+	*   // Key exists (either fresh or stale)
+	* }
+	* ```
+	*
+	* @edge-cases
+	* - Returns `false` if the key doesn't exist
+	* - Returns `false` if the key has expired beyond the stale window
+	* - Returns `true` if the key is in the stale window (still being served)
+	* - Both `has()` and `get()` have O(1) complexity; prefer `get()` if you need the value
+	*/
+	has(key) {
+		return has(this.state, key);
+	}
+	/**
+	* Removes all entries from the cache at once.
+	*
+	* This is useful for resetting the cache or freeing memory when needed.
+	* The `onDelete` callback is NOT invoked during clear (intentional optimization).
+	*
+	* @example
+	* ```typescript
+	* cache.clear(); // cache.size is now 0
+	* ```
+	*
+	* @edge-cases
+	* - The `onDelete` callback is NOT triggered during clear
+	* - Clears both expired and fresh entries
+	* - Resets `cache.size` to 0
+	*/
+	clear() {
+		clear(this.state);
+	}
+	/**
+	* Marks all entries with one or more tags as expired (or stale, if requested).
+	*
+	* If an entry has multiple tags, invalidating ANY of those tags will invalidate the entry.
+	*
+	* @param tags - A single tag (string) or array of tags to invalidate
+	* @param asStale - If true, marks entries as stale instead of fully expired (still served from stale window)
+	*
+	* @example
+	* ```typescript
+	* // Invalidate a single tag
+	* cache.invalidateTag("user:123");
+	*
+	* // Invalidate multiple tags
+	* cache.invalidateTag(["user:123", "posts:456"]);
+	* ```
+	*
+	* @edge-cases
+	* - Does not throw errors if a tag has no associated entries
+	* - Invalidating a tag doesn't prevent new entries from being tagged with it later
+	* - The `onDelete` callback is triggered with reason `'expired'` (even if `asStale` is true)
+	*/
+	invalidateTag(tags, asStale) {
+		invalidateTag(this.state, tags, { asStale });
+	}
+};
+
+//#endregion
+exports.LocalTtlCache = LocalTtlCache;
+//# sourceMappingURL=index.cjs.map