@neezco/cache 0.1.0

package/dist/browser/index.js

@@ -0,0 +1,782 @@
+//#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;
+/**
+* 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;
+
+//#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
+/**
+* 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/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
+/**
+* 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) => {
+	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);
+	}
+	/* @__PURE__ */ 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
+export { LocalTtlCache };
+//# sourceMappingURL=index.js.map