@neezco/cache 0.2.1 → 0.4.0

package/dist/node/index.mjs

@@ -134,6 +134,246 @@ const DEFAULT_CPU_WEIGHT = 8.5;
 * Complements CPU weight to assess overall processing capacity.
 */
 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%.
+*
+* 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) => {
+	const limitStatus = {
+		hasSizeLimit: isValidLimit(config.maxSize),
+		hasMemoryLimit: isValidLimit(config.maxMemorySize)
+	};
+	if (limitStatus.hasSizeLimit && limitStatus.hasMemoryLimit) return "higher";
+	if (limitStatus.hasMemoryLimit) return "memory";
+	if (limitStatus.hasSizeLimit) return "size";
+	return "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/get-process-memory-limit.ts
@@ -479,14 +719,14 @@ const deleteKey = (state, key, reason = DELETE_REASON.MANUAL) => {
 //#endregion
 //#region src/types.ts
 /**
-* Status of a cache entry.
+* Entry status: fresh, stale, or expired.
 */
 let ENTRY_STATUS = /* @__PURE__ */ function(ENTRY_STATUS$1) {
-	/** The entry is fresh and valid. */
+	/** Valid and within TTL. */
 	ENTRY_STATUS$1["FRESH"] = "fresh";
-	/** The entry is stale but can still be served. */
+	/** Expired but within stale window; still served. */
 	ENTRY_STATUS$1["STALE"] = "stale";
-	/** The entry has expired and is no longer valid. */
+	/** Beyond stale window; not served. */
 	ENTRY_STATUS$1["EXPIRED"] = "expired";
 	return ENTRY_STATUS$1;
 }({});
@@ -554,7 +794,7 @@ function computeEntryStatus(state, entry, now) {
 	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 (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;
@@ -617,6 +857,82 @@ const isExpired = (state, entry, now) => {
 	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 = () => {
+	if (!_metrics) return 0;
+	return _metrics.memory?.utilization ?? 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
 /**
@@ -646,10 +962,10 @@ function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
 			expiredCount += 1;
 		} else if (isStale(state, status, now)) {
 			staleCount += 1;
-			if (state.purgeStaleOnSweep) deleteKey(state, key, DELETE_REASON.STALE);
+			if (shouldPurge(state.purgeStaleOnSweep, state, "sweep")) deleteKey(state, key, DELETE_REASON.STALE);
 		}
 	}
-	const expiredStaleCount = state.purgeStaleOnSweep ? staleCount : 0;
+	const expiredStaleCount = shouldPurge(state.purgeStaleOnSweep, state, "sweep") ? staleCount : 0;
 	return {
 		processed,
 		expiredCount,
@@ -756,6 +1072,14 @@ function _updateWeightSweep() {
 
 //#endregion
 //#region src/sweep/sweep.ts
+let _isSweepActive = false;
+let _pendingSweepTimeout = null;
+function startSweep(state) {
+	if (_isSweepActive) return;
+	_isSweepActive = true;
+	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.
@@ -787,8 +1111,8 @@ const sweep = async (state, utilities = {}) => {
 	if (!runOnlyOne) schedule(() => void sweep(state, utilities), sweepIntervalMs);
 };
 const defaultSchedule = (fn, ms) => {
-	const t = setTimeout(fn, ms);
-	if (typeof t.unref === "function") t.unref();
+	_pendingSweepTimeout = setTimeout(fn, ms);
+	if (typeof _pendingSweepTimeout.unref === "function") _pendingSweepTimeout.unref();
 };
 const defaultYieldFn = () => new Promise((resolve) => setImmediate(resolve));
 
@@ -797,16 +1121,35 @@ const defaultYieldFn = () => new Promise((resolve) => setImmediate(resolve));
 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, maxMemorySize = DEFAULT_MAX_MEMORY_SIZE, _maxAllowExpiredRatio = DEFAULT_MAX_EXPIRED_RATIO, defaultStaleWindow = DEFAULT_STALE_WINDOW, purgeStaleOnGet = false, purgeStaleOnSweep = false, _autoStartSweep = true } = 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,
@@ -819,8 +1162,9 @@ const createCache = (options = {}) => {
 		maxMemorySize,
 		defaultTtl,
 		defaultStaleWindow,
-		purgeStaleOnGet,
-		purgeStaleOnSweep,
+		purgeStaleOnGet: resolvedPurgeStaleOnGet,
+		purgeStaleOnSweep: resolvedPurgeStaleOnSweep,
+		purgeResourceMetric: resolvedPurgeResourceMetric,
 		_maxAllowExpiredRatio,
 		_autoStartSweep,
 		_instanceIndexState: -1,
@@ -829,34 +1173,47 @@ const createCache = (options = {}) => {
 		_tags: /* @__PURE__ */ new Map()
 	};
 	state._instanceIndexState = _instancesCache.push(state) - 1;
-	if (_autoStartSweep) {
-		if (_initSweepScheduled) return state;
-		_initSweepScheduled = true;
-		sweep(state);
-	}
-	startMonitor();
+	startSweep(state);
 	return state;
 };
 
 //#endregion
 //#region src/cache/get.ts
 /**
-* Retrieves a value from the cache if the entry is valid.
+* 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 The cached value if valid, null otherwise.
+* @returns A tuple of [status, entry] if the entry is valid, or [null, undefined] if not found or expired.
+*
+* @internal
 */
-const get = (state, key, now = Date.now()) => {
+const getWithStatus = (state, key, purgeMode, now = Date.now()) => {
 	const entry = state.store.get(key);
-	if (!entry) return void 0;
+	if (!entry) return [null, void 0];
 	const status = computeEntryStatus(state, entry, now);
-	if (isFresh(state, status, now)) return entry[1];
+	if (isFresh(state, status, now)) return [status, entry];
 	if (isStale(state, status, now)) {
-		if (state.purgeStaleOnGet) deleteKey(state, key, DELETE_REASON.STALE);
-		return entry[1];
+		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
@@ -955,16 +1312,12 @@ const setOrUpdate = (state, input, now = Date.now()) => {
 //#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.
+* stale windows, tag-based invalidation, and smart automatic sweeping.
 *
-* @example
-* ```typescript
-* const cache = new LocalTtlCache();
-* cache.set("user:123", { name: "Alice" }, { ttl: 5 * 60 * 1000 });
-* const user = cache.get("user:123"); // { name: "Alice" }
-* ```
+* 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;
@@ -973,98 +1326,29 @@ var LocalTtlCache = class {
 	*
 	* @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);
+	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 [, expiresAt, staleExpiresAt] = timestamps;
+			return {
+				data: value,
+				expirationTime: expiresAt,
+				staleWindowExpiration: staleExpiresAt,
+				status,
+				tags
+			};
+		}
+		return get(this.state, key, options?.purgeStale);
 	}
-	/**
-	* 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
-	* @returns True if the entry was set or updated, false if rejected due to limits or invalid input
-	*
-	* @example
-	* ```typescript
-	* const success = cache.set("user:123", { name: "Alice" }, {
-	*   ttl: 5 * 60 * 1000,
-	*   staleWindow: 1 * 60 * 1000,
-	*   tags: "user:123",
-	* });
-	*
-	* if (!success) {
-	*   console.log("Entry was rejected due to size or memory limits");
-	* }
-	* ```
-	*
-	* @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()`
-	* - Returns `false` if value is `undefined` (existing value remains untouched)
-	* - Returns `false` if new key would exceed [`maxSize`](./docs/configuration.md#maxsize-number) limit
-	* - Returns `false` if new key would exceed [`maxMemorySize`](./docs/configuration.md#maxmemorysize-number) limit
-	* - Updating existing keys always succeeds, even at limit
-	*/
 	set(key, value, options) {
 		return setOrUpdate(this.state, {
 			key,
@@ -1074,97 +1358,20 @@ var LocalTtlCache = class {
 			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, options) {
 		invalidateTag(this.state, tags, options ?? {});
 	}
 };
 
 //#endregion
-export { LocalTtlCache };
+export { ENTRY_STATUS, LocalTtlCache };
 //# sourceMappingURL=index.mjs.map