@neezco/cache 0.2.1 → 0.4.0

package/dist/node/index.d.mts

@@ -11,10 +11,10 @@ declare const enum DELETE_REASON {
 */
 interface CacheConfigBase {
   /**
-  * Callback invoked when a key expires naturally.
+  * Callback invoked when an entry expires naturally (not manually deleted).
   * @param key - The expired key.
   * @param value - The value associated with the expired key.
-  * @param reason - The reason for deletion ('expired', or 'stale').
+  * @param reason - The reason for expiration: 'expired' (fully expired) or 'stale' (stale window expired).
   */
   onExpire?: (key: string, value: unknown, reason: Exclude<DELETE_REASON, DELETE_REASON.MANUAL>) => void;
   /**
@@ -30,16 +30,13 @@ interface CacheConfigBase {
   */
   defaultTtl: number;
   /**
-  * Default stale window in milliseconds for entries that do not
-  * specify their own `staleWindowMs`.
+  * Default stale window in milliseconds for entries without explicit `staleWindow`.
   *
-  * This window determines how long an entry may continue to be
-  * served as stale after it reaches its expiration time.
+  * Defines how long an entry can be served as stale after expiration.
+  * The window is relative to each entry's expiration moment, whether from
+  * explicit `ttl` or the cache's `defaultTtl`.
   *
-  * The window is always relative to the entry’s own expiration
-  * moment, regardless of whether that expiration comes from an
-  * explicit `ttl` or from the cache’s default TTL.
-  * @default null (No stale window)
+  * @default 0 (no stale window)
   */
   defaultStaleWindow: number;
   /**
@@ -55,246 +52,287 @@ interface CacheConfigBase {
   */
   maxMemorySize: number;
   /**
-  * Controls how stale entries are handled when read from the cache.
-  *
-  * - true  → stale entries are purged immediately after being returned.
-  * - false → stale entries are retained after being returned.
-  *
-  * @default false
+  * Controls stale entry purging behavior on `get()` operations.
+  *
+  * Possible values:
+  * - `true` → purge stale entries immediately after read.
+  * - `false` → retain stale entries after read.
+  * - `number (0-1)` → purge when `resourceUsage ≥ threshold` (uses `purgeResourceMetric`).
+  *
+  * Numeric threshold validation:
+  * - Must be 0 < value ≤ 1 (boolean fallback if invalid range)
+  * - Requires purgeResourceMetric to support thresholds (not 'fixed')
+  * - Requires matching configuration limits for the metric:
+  *   * 'size' metric requires maxSize
+  *   * 'memory' metric requires maxMemorySize
+  *   * 'higher' metric requires both maxSize and maxMemorySize
+  * - Invalid numeric values fallback to default: 0.80 (with limits) or false (without)
+  *
+  * Environment notes:
+  * - Backend: `"memory"` and `"higher"` metrics available; frontend: only `"size"`.
+  * - Can be overridden per-read via `get(key, { purgeStale })`.
+  *
+  * Defaults:
+  * - With matching limits → `0.80` (80% resource usage).
+  * - Without matching limits → `false`.
   */
-  purgeStaleOnGet: boolean;
+  purgeStaleOnGet: PurgeMode;
   /**
-  * Controls how stale entries are handled during sweep operations.
+  * Controls stale entry purging behavior during sweep operations.
+  *
+  * Possible values:
+  * - `true` → purge stale entries during sweeps.
+  * - `false` → retain stale entries during sweeps.
+  * - `number (0-1)` → purge when `resourceUsage ≥ threshold` (uses `purgeResourceMetric`).
+  *
+  * Numeric threshold validation:
+  * - Must be 0 < value ≤ 1 (boolean fallback if invalid range)
+  * - Requires purgeResourceMetric to support thresholds (not 'fixed')
+  * - Requires matching configuration limits for the metric:
+  *   * 'size' metric requires maxSize
+  *   * 'memory' metric requires maxMemorySize
+  *   * 'higher' metric requires both maxSize and maxMemorySize
+  * - Invalid numeric values fallback to default: 0.5 (with limits) or true (without)
+  *
+  * Prevents stale entry accumulation when enabled. Without limits, defaults to `true`
+  * to prevent unbounded growth.
+  *
+  * Environment notes:
+  * - Backend: `"memory"` and `"higher"` metrics available; frontend: only `"size"`.
+  *
+  * Defaults:
+  * - With matching limits → `0.5` (50% resource usage).
+  * - Without matching limits → `true` (prevent unbounded accumulation).
+  */
+  purgeStaleOnSweep: PurgeMode;
+  /**
+  * Metric used to evaluate resource usage for threshold-based stale purging.
   *
-  * - true  → stale entries are purged during sweeps.
-  * - false → stale entries are retained during sweeps.
+  * Applies when `purgeStaleOnGet` or `purgeStaleOnSweep` are numeric (0-1).
   *
-  * @default false
+  * Metric options:
+  * - `"size"` → normalized entry count (`current / maxSize`).
+  * - `"memory"` → normalized RAM (`currentMB / maxMemorySize`).
+  * - `"higher"` → max of both metrics (recommended for dual limits).
+  * - `"fixed"` → disable threshold purging; only bool values apply.
+  *
+  * Environment support:
+  * - Backend: all metrics available.
+  * - Frontend: only `"size"`; numeric thresholds fallback to `"fixed"`.
+  *
+  * Auto-selection (if not specified):
+  * - Backend: `"higher"` (both limits) → `"memory"` → `"size"` → `"fixed"`.
+  * - Frontend: `"size"` (if valid) → `"fixed"`.
+  *
+  * @default Depends on environment and valid limits.
   */
-  purgeStaleOnSweep: boolean;
+  purgeResourceMetric?: "memory" | "size" | "higher" | "fixed";
   /**
-  * Whether to automatically start the sweep process when the cache is created.
-  *
-  * - true  → sweep starts automatically.
-  * - false → sweep does not start automatically, allowing manual control.
+  * Auto-start sweep process on cache initialization.
   *
   * @internal
   * @default true
   */
   _autoStartSweep: boolean;
   /**
-  * Allowed expired ratio for the cache instance.
+  * @internal Maximum allowed ratio of expired entries before aggressive sweep.
   */
   _maxAllowExpiredRatio: number;
 }
 /**
-* Public configuration options for the TTL cache.
+* Purge mode: boolean for immediate/skip, or 0-1 for threshold-based purging.
+*/
+type PurgeMode = boolean | number;
+/**
+* Public cache configuration (all fields optional).
 */
 type CacheOptions = Partial<CacheConfigBase>;
 /**
-* Options for `invalidateTag` operation. Kept intentionally extensible so
-* future flags can be added without breaking callers.
+* Options for tag invalidation. Extensible for forward-compatibility.
 */
 interface InvalidateTagOptions {
-  /** If true, mark affected entries as stale instead of fully expired. */
+  /**
+  * If true, mark entries as stale instead of fully expired.
+  * They remain accessible via stale window if configured.
+  */
   asStale?: boolean;
   [key: string]: unknown;
 }
-//#endregion
-//#region src/index.d.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" }
-* ```
+* Entry status: fresh, stale, or expired.
 */
-declare class LocalTtlCache {
-  private state;
+declare enum ENTRY_STATUS {
+  /** Valid and within TTL. */
+  FRESH = "fresh",
+  /** Expired but within stale window; still served. */
+  STALE = "stale",
+  /** Beyond stale window; not served. */
+  EXPIRED = "expired",
+}
+/**
+* Metadata returned from `get()` with `includeMetadata: true`.
+* Provides complete entry state including timing, status, and tags.
+*/
+interface EntryMetadata<T = unknown> {
+  /** The cached value. */
+  data: T;
+  /** Absolute timestamp (ms) when entry expires. */
+  expirationTime: number;
+  /** Absolute timestamp (ms) when stale window ends. */
+  staleWindowExpiration: number;
+  /** Current entry status. */
+  status: ENTRY_STATUS;
+  /** Associated tags for group invalidation, or null. */
+  tags: string[] | null;
+}
+/**
+* Options for `get()` without metadata (default).
+* Returns only the cached value.
+*/
+interface GetOptionsWithoutMetadata {
   /**
-  * 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}`),
-  * });
-  * ```
+  * If false (or omitted), returns value only without metadata.
+  * @default false
   */
-  constructor(options?: CacheOptions);
+  includeMetadata?: false;
   /**
-  * 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.
+  * Controls stale entry purging on this read.
   *
-  * @returns The number of entries currently stored (including entries pending cleanup)
+  * - `true` → purge immediately after return.
+  * - `false` → keep stale entries.
+  * - `number (0-1)` → purge at resource usage threshold.
   *
-  * @example
-  * ```typescript
-  * console.log(cache.size); // e.g., 42
-  * ```
+  * Overrides global `purgeStaleOnGet` setting.
   */
-  get size(): number;
+  purgeStale?: PurgeMode;
+}
+/**
+* Options for `get()` with metadata.
+* Returns value and complete entry state.
+*/
+interface GetOptionsWithMetadata {
   /**
-  * 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
+  * If true, returns `EntryMetadata<T>` object with value, timing, and tags.
   */
-  get<T = unknown>(key: string): T | undefined;
+  includeMetadata: true;
   /**
-  * Sets or updates a value in the cache.
+  * Controls stale entry purging on this read.
   *
-  * If the key already exists, it will be completely replaced.
+  * - `true` → purge immediately after return.
+  * - `false` → keep stale entries.
+  * - `number (0-1)` → purge at resource usage threshold.
   *
-  * @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
+  * Overrides global `purgeStaleOnGet` setting.
+  */
+  purgeStale?: PurgeMode;
+}
+/**
+* Options for `set()` method.
+* Controls TTL, stale window, and tagging per entry.
+*/
+interface SetOptions {
+  /**
+  * Time-To-Live in milliseconds.
+  * Determines fresh period before expiration.
   *
-  * @example
-  * ```typescript
-  * const success = cache.set("user:123", { name: "Alice" }, {
-  *   ttl: 5 * 60 * 1000,
-  *   staleWindow: 1 * 60 * 1000,
-  *   tags: "user:123",
-  * });
+  * Special values:
+  * - `0` | `Infinity` → entry never expires
   *
-  * if (!success) {
-  *   console.log("Entry was rejected due to size or memory limits");
-  * }
-  * ```
+  * Falls back to cache's `defaultTtl` if omitted.
+  */
+  ttl?: number;
+  /**
+  * Stale window duration in milliseconds.
   *
-  * @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
+  * Determines how long entry serves stale after expiration.
+  * Falls back to cache's `defaultStaleWindow` if omitted.
   */
-  set(key: string, value: unknown, options?: {
-    ttl?: number;
-    staleWindow?: number;
-    tags?: string | string[];
-  }): boolean;
+  staleWindow?: number;
   /**
-  * Deletes a specific key from the cache.
+  * One or more tags for group-based invalidation.
   *
-  * @param key - The key to delete
-  * @returns True if the key was deleted, false if it didn't exist
+  * Tags enable batch invalidation via `invalidateTag()`.
+  * Invalidating ANY tag on an entry invalidates the whole entry.
   *
-  * @example
-  * ```typescript
-  * const wasDeleted = cache.delete("user:123");
-  * ```
+  * Falls back to cache's default if omitted.
+  */
+  tags?: string | string[];
+}
+/**
+* TTL cache public interface.
+* Implemented by `LocalTtlCache` class.
+*/
+interface LocalTtlCacheInterface {
+  /**
+  * Current number of entries (may include expired entries pending cleanup).
+  */
+  readonly size: number;
+  /**
+  * Retrieves value from cache.
+  * Returns fresh, stale, or undefined (expired or not found).
   *
-  * @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
+  * @overload `get<T>(key)` → `T | undefined` (no metadata)
+  * @overload `get<T>(key, { includeMetadata: true })` → `EntryMetadata<T> | undefined` (with metadata)
+  */
+  get<T = unknown>(key: string): T | undefined;
+  get<T = unknown>(key: string, options: GetOptionsWithMetadata): EntryMetadata<T> | undefined;
+  get<T = unknown>(key: string, options: GetOptionsWithoutMetadata): T | undefined;
+  /**
+  * Sets or replaces a cache entry.
+  * @returns true if set/updated, false if rejected (limits/invalid).
+  */
+  set(key: string, value: unknown, options?: SetOptions): boolean;
+  /**
+  * Deletes a specific key from cache.
+  * @returns true if deleted, false if not found.
   */
   delete(key: string): boolean;
   /**
-  * 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
+  * Checks if key exists (fresh or stale).
+  * @returns true if valid, false if not found or fully expired.
   */
   has(key: string): boolean;
   /**
-  * 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
+  * Removes all entries from cache.
+  * Does NOT trigger `onDelete` callbacks (optimization).
   */
   clear(): void;
   /**
-  * 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");
+  * Marks entries with given tags as expired (or stale).
+  * Invalidating ANY tag on an entry invalidates it.
+  */
+  invalidateTag(tags: string | string[], options?: InvalidateTagOptions): void;
+}
+//#endregion
+//#region src/index.d.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
+*/
+declare class LocalTtlCache implements LocalTtlCacheInterface {
+  private state;
+  /**
+  * Creates a new cache instance.
   *
-  * // Invalidate multiple tags
-  * cache.invalidateTag(["user:123", "posts:456"]);
-  * ```
+  * @param options - Configuration options for the cache (defaultTtl, defaultStaleWindow, maxSize, etc.)
   *
-  * @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)
   */
+  constructor(options?: CacheOptions);
+  get size(): number;
+  get<T = unknown>(key: string): T | undefined;
+  get<T = unknown>(key: string, options: GetOptionsWithMetadata): EntryMetadata<T>;
+  get<T = unknown>(key: string, options: GetOptionsWithoutMetadata): T | undefined;
+  set(key: string, value: unknown, options?: SetOptions): boolean;
+  delete(key: string): boolean;
+  has(key: string): boolean;
+  clear(): void;
   invalidateTag(tags: string | string[], options?: InvalidateTagOptions): void;
 }
 //#endregion
-export { type CacheOptions, type InvalidateTagOptions, LocalTtlCache };
+export { type CacheOptions, ENTRY_STATUS, type EntryMetadata, type GetOptionsWithMetadata, type GetOptionsWithoutMetadata, type InvalidateTagOptions, LocalTtlCache, type LocalTtlCacheInterface, type PurgeMode, type SetOptions };
 //# sourceMappingURL=index.d.mts.map