@neezco/cache 0.5.0 → 0.7.0

package/dist/node/index.mjs

@@ -32,11 +32,6 @@ const ONE_MINUTE = 60 * ONE_SECOND;
 */
 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, new entries are ignored.
 */
@@ -60,15 +55,9 @@ const DEFAULT_MAX_MEMORY_SIZE = Infinity;
 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` .
@@ -86,21 +75,6 @@ const DEFAULT_MAX_EXPIRED_RATIO = .4;
 */
 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.
@@ -113,18 +87,6 @@ const OPTIMAL_SWEEP_TIME_BUDGET_IF_NOTE_METRICS_AVAILABLE = 15;
 */
 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.
 */
@@ -135,22 +97,6 @@ const DEFAULT_CPU_WEIGHT = 8.5;
 */
 const DEFAULT_LOOP_WEIGHT = 6.5;
 /**
-* Fallback behavior for stale purging on GET
-* when no resource limits are defined.
-*
-* In this scenario, threshold-based purging is disabled,
-* so GET operations do NOT purge stale entries.
-*/
-const DEFAULT_PURGE_STALE_ON_GET_NO_LIMITS = false;
-/**
-* Fallback behavior for stale purging on SWEEP
-* when no resource limits are defined.
-*
-* In this scenario, threshold-based purging is disabled,
-* so SWEEP operations DO purge stale entries to prevent buildup.
-*/
-const DEFAULT_PURGE_STALE_ON_SWEEP_NO_LIMITS = true;
-/**
 * Default threshold for purging stale entries on get operations (backend with limits).
 * Stale entries are purged when resource usage exceeds 80%.
 *
@@ -314,7 +260,7 @@ const resolvePurgeStaleOnGet = (config) => resolvePurgeMode(config.limits, {
 	operation: "purgeStaleOnGet"
 }, {
 	withLimits: DEFAULT_PURGE_STALE_ON_GET_THRESHOLD,
-	withoutLimits: DEFAULT_PURGE_STALE_ON_GET_NO_LIMITS
+	withoutLimits: false
 }, config.userValue);
 
 //#endregion
@@ -563,7 +509,7 @@ function startMonitor() {
 			callback(metrics) {
 				_metrics = metrics;
 			},
-			interval: WORST_SWEEP_INTERVAL,
+			interval: 200,
 			maxMemory: maxMemoryLimit
 		});
 		_monitorInstance.start();
@@ -620,10 +566,10 @@ function interpolate({ value, fromStart, fromEnd, toStart, toEnd }) {
 * @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 { 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;
@@ -671,38 +617,27 @@ const calculateOptimalSweepParams = (options) => {
 * 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;
-			}
-		}
+		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 instanceToSweep;
+	return _instancesCache[0];
 }
 
 //#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 deleteKey = (state, key, reason = "manual") => {
 	const onDelete = state.onDelete;
 	const onExpire = state.onExpire;
 	if (!onDelete && !onExpire) return state.store.delete(key);
@@ -710,7 +645,7 @@ const deleteKey = (state, key, reason = DELETE_REASON.MANUAL) => {
 	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);
+	if (reason !== "manual") state.onExpire?.(key, entry[1], reason);
 	return true;
 };
 
@@ -719,14 +654,14 @@ const deleteKey = (state, key, reason = DELETE_REASON.MANUAL) => {
 /**
 * Entry status: fresh, stale, or expired.
 */
-let ENTRY_STATUS = /* @__PURE__ */ function(ENTRY_STATUS$1) {
+let ENTRY_STATUS = /* @__PURE__ */ function(ENTRY_STATUS) {
 	/** Valid and within TTL. */
-	ENTRY_STATUS$1["FRESH"] = "fresh";
+	ENTRY_STATUS["FRESH"] = "fresh";
 	/** Expired but within stale window; still served. */
-	ENTRY_STATUS$1["STALE"] = "stale";
+	ENTRY_STATUS["STALE"] = "stale";
 	/** Beyond stale window; not served. */
-	ENTRY_STATUS$1["EXPIRED"] = "expired";
-	return ENTRY_STATUS$1;
+	ENTRY_STATUS["EXPIRED"] = "expired";
+	return ENTRY_STATUS;
 }({});
 
 //#endregion
@@ -752,22 +687,22 @@ let ENTRY_STATUS = /* @__PURE__ */ function(ENTRY_STATUS$1) {
 function _statusFromTags(state, entry) {
 	const entryCreatedAt = entry[0][0];
 	let earliestTagStaleInvalidation = Infinity;
-	let status = ENTRY_STATUS.FRESH;
+	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 = ENTRY_STATUS.EXPIRED;
+			status = "expired";
 			break;
 		}
 		if (tagStaleSinceAt >= entryCreatedAt) {
 			if (tagStaleSinceAt < earliestTagStaleInvalidation) earliestTagStaleInvalidation = tagStaleSinceAt;
-			status = ENTRY_STATUS.STALE;
+			status = "stale";
 		}
 	}
-	return [status, status === ENTRY_STATUS.STALE ? earliestTagStaleInvalidation : 0];
+	return [status, status === "stale" ? earliestTagStaleInvalidation : 0];
 }
 
 //#endregion
@@ -790,12 +725,12 @@ function _statusFromTags(state, 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;
+	if (tagStatus === "expired") return "expired";
 	const windowStale = staleExpiresAt - expiresAt;
-	if (tagStatus === ENTRY_STATUS.STALE && staleExpiresAt > 0 && now < earliestTagStaleInvalidation + windowStale && now <= staleExpiresAt) return ENTRY_STATUS.STALE;
-	if (now < expiresAt) return ENTRY_STATUS.FRESH;
-	if (staleExpiresAt > 0 && now < staleExpiresAt) return ENTRY_STATUS.STALE;
-	return ENTRY_STATUS.EXPIRED;
+	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.
@@ -813,8 +748,8 @@ function computeEntryStatus(state, entry, now) {
 * @returns True if the entry is fresh.
 */
 const isFresh = (state, entry, now) => {
-	if (typeof entry === "string") return entry === ENTRY_STATUS.FRESH;
-	return computeEntryStatus(state, entry, now) === ENTRY_STATUS.FRESH;
+	if (typeof entry === "string") return entry === "fresh";
+	return computeEntryStatus(state, entry, now) === "fresh";
 };
 /**
 * Determines whether a cache entry is stale.
@@ -832,8 +767,8 @@ const isFresh = (state, entry, now) => {
 * @returns True if the entry is stale.
 */
 const isStale = (state, entry, now) => {
-	if (typeof entry === "string") return entry === ENTRY_STATUS.STALE;
-	return computeEntryStatus(state, entry, now) === ENTRY_STATUS.STALE;
+	if (typeof entry === "string") return entry === "stale";
+	return computeEntryStatus(state, entry, now) === "stale";
 };
 /**
 * Determines whether a cache entry is expired.
@@ -851,8 +786,8 @@ const isStale = (state, entry, now) => {
 * @returns True if the entry is expired.
 */
 const isExpired = (state, entry, now) => {
-	if (typeof entry === "string") return entry === ENTRY_STATUS.EXPIRED;
-	return computeEntryStatus(state, entry, now) === ENTRY_STATUS.EXPIRED;
+	if (typeof entry === "string") return entry === "expired";
+	return computeEntryStatus(state, entry, now) === "expired";
 };
 
 //#endregion
@@ -924,7 +859,7 @@ const shouldPurge = (mode, state, purgeContext) => {
 	if (mode === false) return false;
 	if (mode === true) return true;
 	const userThreshold = Number(mode);
-	const defaultPurge = purgeContext === "sweep" ? DEFAULT_PURGE_STALE_ON_SWEEP_NO_LIMITS : DEFAULT_PURGE_STALE_ON_GET_NO_LIMITS;
+	const defaultPurge = purgeContext === "sweep" ? true : false;
 	if (Number.isNaN(userThreshold)) return defaultPurge;
 	const usage = computeResourceUsage(state);
 	if (!usage) return defaultPurge;
@@ -942,9 +877,11 @@ const shouldPurge = (mode, state, purgeContext) => {
 */
 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) {
@@ -953,22 +890,20 @@ function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
 		}
 		processed += 1;
 		const [key, entry] = next.value;
-		const now = Date.now();
 		const status = computeEntryStatus(state, entry, now);
 		if (isExpired(state, status, now)) {
-			deleteKey(state, key, DELETE_REASON.EXPIRED);
+			deleteKey(state, key, "expired");
 			expiredCount += 1;
 		} else if (isStale(state, status, now)) {
 			staleCount += 1;
-			if (shouldPurge(state.purgeStaleOnSweep, state, "sweep")) deleteKey(state, key, DELETE_REASON.STALE);
+			if (shouldPurgeStale) deleteKey(state, key, "stale");
 		}
 	}
-	const expiredStaleCount = shouldPurge(state.purgeStaleOnSweep, state, "sweep") ? staleCount : 0;
 	return {
 		processed,
 		expiredCount,
 		staleCount,
-		ratio: processed > 0 ? (expiredCount + expiredStaleCount) / processed : 0
+		ratio: processed > 0 ? (expiredCount + (shouldPurgeStale ? staleCount : 0)) / processed : 0
 	};
 }
 
@@ -979,8 +914,8 @@ function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
 *
 * 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`.
+* 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`.
@@ -990,7 +925,7 @@ function calculateOptimalMaxExpiredRatio(maxAllowExpiredRatio = DEFAULT_MAX_EXPI
 	const optimalExpiredRatio = interpolate({
 		value: _metrics?.memory.utilization ?? 0,
 		fromStart: 0,
-		fromEnd: EXPIRED_RATIO_MEMORY_THRESHOLD,
+		fromEnd: 1,
 		toStart: maxAllowExpiredRatio,
 		toEnd: MINIMAL_EXPIRED_RATIO
 	});
@@ -1009,8 +944,6 @@ function calculateOptimalMaxExpiredRatio(maxAllowExpiredRatio = DEFAULT_MAX_EXPI
 * 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
@@ -1018,14 +951,7 @@ function calculateOptimalMaxExpiredRatio(maxAllowExpiredRatio = DEFAULT_MAX_EXPI
 *    - 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)**
+* 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
@@ -1033,16 +959,6 @@ function calculateOptimalMaxExpiredRatio(maxAllowExpiredRatio = DEFAULT_MAX_EXPI
 *    - 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() {
@@ -1052,14 +968,10 @@ function _updateWeightSweep() {
 			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;
-			}
+		const expiredRatio = instCache._expiredRatio;
+		if (expiredRatio <= calculateOptimalMaxExpiredRatio(instCache._maxAllowExpiredRatio)) {
+			instCache._sweepWeight = 0;
+			continue;
 		}
 		instCache._sweepWeight = instCache.store.size * expiredRatio;
 		totalSweepWeight += instCache._sweepWeight;
@@ -1086,7 +998,7 @@ 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;
+	let sweepTimeBudgetMs = 15;
 	if (_metrics) ({sweepIntervalMs, sweepTimeBudgetMs} = calculateOptimalSweepParams({ metrics: _metrics }));
 	const totalSweepWeight = _updateWeightSweep();
 	const currentExpiredRatios = [];
@@ -1124,7 +1036,7 @@ const _instancesCache = [];
 * @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 = DEFAULT_STALE_WINDOW, purgeStaleOnGet, purgeStaleOnSweep, purgeResourceMetric, _autoStartSweep = true } = 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({
@@ -1193,10 +1105,10 @@ const getWithStatus = (state, key, purgeMode, now = Date.now()) => {
 	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, DELETE_REASON.STALE);
+		if (shouldPurge(purgeMode ?? state.purgeStaleOnGet, state, "get")) deleteKey(state, key, "stale");
 		return [status, entry];
 	}
-	deleteKey(state, key, DELETE_REASON.EXPIRED);
+	deleteKey(state, key, "expired");
 	return [status, void 0];
 };
 /**