@neezco/cache 0.2.0 → 0.3.0

package/dist/node/index.d.cts

@@ -100,6 +100,34 @@ interface InvalidateTagOptions {
   asStale?: boolean;
   [key: string]: unknown;
 }
+/**
+* Status of a cache entry.
+*/
+declare enum ENTRY_STATUS {
+  /** The entry is fresh and valid. */
+  FRESH = "fresh",
+  /** The entry is stale but can still be served. */
+  STALE = "stale",
+  /** The entry has expired and is no longer valid. */
+  EXPIRED = "expired",
+}
+/**
+* Metadata returned when includeMetadata is enabled in get().
+* Contains complete information about a cache entry including
+* timing, status, and associated tags.
+*/
+interface EntryMetadata<T = unknown> {
+  /** The cached value. */
+  data: T;
+  /** Absolute timestamp when this entry becomes fully expired (in milliseconds). */
+  expirationTime: number;
+  /** Absolute timestamp when the stale window expires (in milliseconds). */
+  staleWindowExpiration: number;
+  /** Current status of the entry (fresh, stale, or expired). */
+  status: ENTRY_STATUS;
+  /** Tags associated with this entry, or null if no tags are set. */
+  tags: string[] | null;
+}
 //#endregion
 //#region src/index.d.ts
 /**
@@ -156,22 +184,31 @@ declare class LocalTtlCache {
   * 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
+  * @param options - Optional configuration object
+  * @param options.includeMetadata - If true, returns entry metadata (data, status, expirationTime, staleWindowExpiration, tags). Defaults to false
+  * @returns The cached value, or entry metadata if includeMetadata is true. Returns undefined if not found or expired
   *
   * @example
   * ```typescript
-  * const user = cache.get<{ name: string }>("user:123");
+  * // Get value
+  * const user = cache.get("user:123");
+  *
+  * // Get with metadata
+  * const entry = cache.get("user:123", { includeMetadata: true });
+  * if (entry) {
+  *   console.log(entry.data);
+  *   console.log(entry.status);
+  * }
   * ```
-  *
-  * @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<T = unknown>(key: string): T | undefined;
+  get<T = unknown>(key: string, options: {
+    includeMetadata: true;
+  }): EntryMetadata<T> | undefined;
+  get<T = unknown>(key: string, options: {
+    includeMetadata: false;
+  }): T | undefined;
   /**
   * Sets or updates a value in the cache.
   *
@@ -296,5 +333,5 @@ declare class LocalTtlCache {
   invalidateTag(tags: string | string[], options?: InvalidateTagOptions): void;
 }
 //#endregion
-export { type CacheOptions, type InvalidateTagOptions, LocalTtlCache };
+export { type CacheOptions, type EntryMetadata, type InvalidateTagOptions, LocalTtlCache };
 //# sourceMappingURL=index.d.cts.map

package/dist/node/index.d.mts

@@ -100,6 +100,34 @@ interface InvalidateTagOptions {
   asStale?: boolean;
   [key: string]: unknown;
 }
+/**
+* Status of a cache entry.
+*/
+declare enum ENTRY_STATUS {
+  /** The entry is fresh and valid. */
+  FRESH = "fresh",
+  /** The entry is stale but can still be served. */
+  STALE = "stale",
+  /** The entry has expired and is no longer valid. */
+  EXPIRED = "expired",
+}
+/**
+* Metadata returned when includeMetadata is enabled in get().
+* Contains complete information about a cache entry including
+* timing, status, and associated tags.
+*/
+interface EntryMetadata<T = unknown> {
+  /** The cached value. */
+  data: T;
+  /** Absolute timestamp when this entry becomes fully expired (in milliseconds). */
+  expirationTime: number;
+  /** Absolute timestamp when the stale window expires (in milliseconds). */
+  staleWindowExpiration: number;
+  /** Current status of the entry (fresh, stale, or expired). */
+  status: ENTRY_STATUS;
+  /** Tags associated with this entry, or null if no tags are set. */
+  tags: string[] | null;
+}
 //#endregion
 //#region src/index.d.ts
 /**
@@ -156,22 +184,31 @@ declare class LocalTtlCache {
   * 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
+  * @param options - Optional configuration object
+  * @param options.includeMetadata - If true, returns entry metadata (data, status, expirationTime, staleWindowExpiration, tags). Defaults to false
+  * @returns The cached value, or entry metadata if includeMetadata is true. Returns undefined if not found or expired
   *
   * @example
   * ```typescript
-  * const user = cache.get<{ name: string }>("user:123");
+  * // Get value
+  * const user = cache.get("user:123");
+  *
+  * // Get with metadata
+  * const entry = cache.get("user:123", { includeMetadata: true });
+  * if (entry) {
+  *   console.log(entry.data);
+  *   console.log(entry.status);
+  * }
   * ```
-  *
-  * @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<T = unknown>(key: string): T | undefined;
+  get<T = unknown>(key: string, options: {
+    includeMetadata: true;
+  }): EntryMetadata<T> | undefined;
+  get<T = unknown>(key: string, options: {
+    includeMetadata: false;
+  }): T | undefined;
   /**
   * Sets or updates a value in the cache.
   *
@@ -296,5 +333,5 @@ declare class LocalTtlCache {
   invalidateTag(tags: string | string[], options?: InvalidateTagOptions): void;
 }
 //#endregion
-export { type CacheOptions, type InvalidateTagOptions, LocalTtlCache };
+export { type CacheOptions, type EntryMetadata, type InvalidateTagOptions, LocalTtlCache };
 //# sourceMappingURL=index.d.mts.map

package/dist/node/index.mjs

@@ -566,11 +566,18 @@ function computeEntryStatus(state, entry, now) {
 * - 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 being evaluated.
+* @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) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.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.
 *
@@ -578,11 +585,18 @@ const isFresh = (state, entry, now) => computeEntryStatus(state, entry, now) ===
 * - 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 being evaluated.
+* @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) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.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.
 *
@@ -590,11 +604,18 @@ const isStale = (state, entry, now) => computeEntryStatus(state, entry, now) ===
 * - 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 being evaluated.
+* @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) => computeEntryStatus(state, entry, now) === ENTRY_STATUS.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/sweep/sweep-once.ts
@@ -619,10 +640,11 @@ function _sweepOnce(state, _maxKeysPerBatch = MAX_KEYS_PER_BATCH) {
 		processed += 1;
 		const [key, entry] = next.value;
 		const now = Date.now();
-		if (isExpired(state, entry, now)) {
+		const status = computeEntryStatus(state, entry, now);
+		if (isExpired(state, status, now)) {
 			deleteKey(state, key, DELETE_REASON.EXPIRED);
 			expiredCount += 1;
-		} else if (isStale(state, entry, now)) {
+		} else if (isStale(state, status, now)) {
 			staleCount += 1;
 			if (state.purgeStaleOnSweep) deleteKey(state, key, DELETE_REASON.STALE);
 		}
@@ -819,21 +841,40 @@ const createCache = (options = {}) => {
 //#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, 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 (!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 (state.purgeStaleOnGet) deleteKey(state, key, DELETE_REASON.STALE);
-		return entry[1];
+		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, now = Date.now()) => {
+	const [, entry] = getWithStatus(state, key, now);
+	return entry ? entry[1] : void 0;
 };
 
 //#endregion
@@ -982,28 +1023,20 @@ var LocalTtlCache = class {
 	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) {
+	get(key, options) {
+		if (options?.includeMetadata) {
+			const [status, entry] = getWithStatus(this.state, key);
+			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);
 	}
 	/**