@neezco/cache 0.5.0 → 0.6.0

package/dist/browser/index.js

@@ -1,1030 +0,0 @@
-//#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;
-/**
-* 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.
-*/
-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.
-* 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` .
-*/
-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;
-/**
-* 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%.
-*
-* 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: DEFAULT_PURGE_STALE_ON_GET_NO_LIMITS
-}, 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) => {
-	return {
-		hasSizeLimit: isValidLimit(config.maxSize),
-		hasMemoryLimit: isValidLimit(config.maxMemorySize)
-	}.hasSizeLimit ? "size" : "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/start-monitor.ts
-function startMonitor() {}
-
-//#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/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
-/**
-* Entry status: fresh, stale, or expired.
-*/
-let ENTRY_STATUS = /* @__PURE__ */ function(ENTRY_STATUS$1) {
-	/** Valid and within TTL. */
-	ENTRY_STATUS$1["FRESH"] = "fresh";
-	/** Expired but within stale window; still served. */
-	ENTRY_STATUS$1["STALE"] = "stale";
-	/** Beyond stale window; not served. */
-	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 && 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;
-}
-/**
-* 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 === ENTRY_STATUS.FRESH;
-	return 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.
-*
-* `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 === ENTRY_STATUS.STALE;
-	return 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.
-*
-* `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 === ENTRY_STATUS.EXPIRED;
-	return computeEntryStatus(state, entry, now) === ENTRY_STATUS.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 = () => {
-	return 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" ? DEFAULT_PURGE_STALE_ON_SWEEP_NO_LIMITS : DEFAULT_PURGE_STALE_ON_GET_NO_LIMITS;
-	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();
-	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();
-		const status = computeEntryStatus(state, entry, now);
-		if (isExpired(state, status, now)) {
-			deleteKey(state, key, DELETE_REASON.EXPIRED);
-			expiredCount += 1;
-		} else if (isStale(state, status, now)) {
-			staleCount += 1;
-			if (shouldPurge(state.purgeStaleOnSweep, state, "sweep")) deleteKey(state, key, DELETE_REASON.STALE);
-		}
-	}
-	const expiredStaleCount = shouldPurge(state.purgeStaleOnSweep, state, "sweep") ? staleCount : 0;
-	return {
-		processed,
-		expiredCount,
-		staleCount,
-		ratio: processed > 0 ? (expiredCount + expiredStaleCount) / processed : 0
-	};
-}
-
-//#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;
-		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;
-	/* @__PURE__ */ 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 = OPTIMAL_SWEEP_TIME_BUDGET_IF_NOTE_METRICS_AVAILABLE;
-	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 = DEFAULT_STALE_WINDOW, 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, DELETE_REASON.STALE);
-		return [status, entry];
-	}
-	deleteKey(state, key, DELETE_REASON.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;
-	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.js.map