@neezco/cache 0.5.0 → 0.7.0

package/dist/browser/index.d.ts

@@ -2,7 +2,7 @@
 declare const enum DELETE_REASON {
   MANUAL = "manual",
   EXPIRED = "expired",
-  STALE = "stale",
+  STALE = "stale"
 }
 //#endregion
 //#region src/types.d.ts
@@ -167,7 +167,7 @@ declare enum ENTRY_STATUS {
   /** Expired but within stale window; still served. */
   STALE = "stale",
   /** Beyond stale window; not served. */
-  EXPIRED = "expired",
+  EXPIRED = "expired"
 }
 /**
 * Metadata returned from `get()` with `includeMetadata: true`.

package/dist/browser/index.js

@@ -28,11 +28,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.
 */
@@ -55,11 +50,6 @@ 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;
-/**
 * Maximum allowed expired ratio when memory usage is low.
 * Upper bound for interpolation with MINIMAL_EXPIRED_RATIO.
 * Recommended range: `0.3 – 0.5` .
@@ -77,27 +67,6 @@ const DEFAULT_MAX_EXPIRED_RATIO = .4;
 */
 const OPTIMAL_SWEEP_INTERVAL = 2 * ONE_SECOND;
 /**
-* 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;
-/**
-* 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%.
 *
@@ -261,7 +230,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
@@ -361,38 +330,27 @@ function _batchUpdateExpiredRatio(currentExpiredRatios) {
 * 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);
@@ -400,7 +358,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;
 };
 
@@ -409,14 +367,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
@@ -442,22 +400,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
@@ -480,12 +438,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.
@@ -503,8 +461,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.
@@ -522,8 +480,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.
@@ -541,8 +499,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
@@ -613,7 +571,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;
@@ -631,9 +589,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) {
@@ -642,22 +602,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
 	};
 }
 
@@ -673,8 +631,6 @@ function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
 * 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
@@ -682,14 +638,7 @@ function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
 *    - 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
@@ -697,16 +646,6 @@ function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
 *    - 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() {
@@ -716,8 +655,7 @@ function _updateWeightSweep() {
 			instCache._sweepWeight = 0;
 			continue;
 		}
-		let expiredRatio = MINIMAL_EXPIRED_RATIO;
-		if (instCache._expiredRatio > MINIMAL_EXPIRED_RATIO) expiredRatio = instCache._expiredRatio;
+		const expiredRatio = instCache._expiredRatio;
 		instCache._sweepWeight = instCache.store.size * expiredRatio;
 		totalSweepWeight += instCache._sweepWeight;
 	}
@@ -743,7 +681,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;
 	const totalSweepWeight = _updateWeightSweep();
 	const currentExpiredRatios = [];
 	const maxKeysPerBatch = totalSweepWeight <= 0 ? MAX_KEYS_PER_BATCH / _instancesCache.length : MAX_KEYS_PER_BATCH;
@@ -780,7 +718,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({
@@ -849,10 +787,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];
 };
 /**