layercache 1.3.3 → 1.4.0

package/dist/{edge-CUHTP9Bc.d.cts → edge-D2FpRlyS.d.cts}

@@ -11,18 +11,26 @@ declare class CacheMissError extends Error {
 interface LayerTtlMap {
     [layerName: string]: number | undefined;
 }
-interface CacheWriteOptions {
+type CacheEntryWriteKind = 'value' | 'empty';
+interface CacheEntryWriteOptions {
     tags?: string[];
     ttl?: number | LayerTtlMap;
     ttlPolicy?: CacheTtlPolicy;
-    negativeCache?: boolean;
     negativeTtl?: number | LayerTtlMap;
     staleWhileRevalidate?: number | LayerTtlMap;
     staleIfError?: number | LayerTtlMap;
     ttlJitter?: number | LayerTtlMap;
+    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
+}
+interface CacheContextOptionsContext {
+    key: string;
+    value: unknown;
+    kind: CacheEntryWriteKind;
+}
+interface CacheWriteOptions extends CacheEntryWriteOptions {
+    negativeCache?: boolean;
     slidingTtl?: boolean;
     refreshAhead?: number | LayerTtlMap;
-    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
     fetcherRateLimit?: CacheRateLimitOptions;
     /**
@@ -34,12 +42,37 @@ interface CacheWriteOptions {
      * cache.get('key', fetchData, { shouldCache: (v) => v.status === 200 })
      */
     shouldCache?: (value: unknown) => boolean;
+    /**
+     * Optional resolver that can override cache entry options using the current
+     * write context. This runs right before a value is stored, so callers can
+     * derive TTLs or tags from the fetched value instead of guessing upfront.
+     *
+     * Returned values override any static entry options already present on the
+     * same object. Fetch controls like `shouldCache`, `negativeCache`,
+     * `refreshAhead`, or `circuitBreaker` are not affected.
+     *
+     * @example
+     * cache.get('oauth:token', fetchToken, {
+     *   ttl: 300_000,
+     *   contextOptions: ({ value }) => ({
+     *     ttl: Math.max(1, Math.floor(((value as { refreshExpiresIn: number }).refreshExpiresIn ?? 0) / 1_000))
+     *   })
+     * })
+     */
+    contextOptions?: (context: CacheContextOptionsContext) => CacheEntryWriteOptions | undefined;
 }
 interface CacheGetOptions extends CacheWriteOptions {
 }
+interface CacheFetcherContext<T = unknown> {
+    key: string;
+    currentValue: T | undefined;
+    state: 'miss' | 'fresh' | 'stale-while-revalidate' | 'stale-if-error';
+    layer?: string;
+}
+type CacheFetcher<T = unknown> = (context: CacheFetcherContext<T>) => Promise<T>;
 interface CacheMGetEntry<T> {
     key: string;
-    fetch?: () => Promise<T>;
+    fetch?: CacheFetcher<T>;
     options?: CacheGetOptions;
 }
 interface CacheMSetEntry<T> {
@@ -75,7 +108,7 @@ interface CacheLayer {
      */
     has?(key: string): Promise<boolean>;
     /**
-     * Returns the remaining TTL in seconds for the key, or null if the key
+     * Returns the remaining TTL in milliseconds for the key, or null if the key
      * does not exist, has no TTL, or has already expired.
      * Implementations may omit this.
      */
@@ -159,7 +192,7 @@ interface InvalidationMessage {
     scope: 'key' | 'keys' | 'clear';
     sourceId: string;
     keys?: string[];
-    operation?: 'write' | 'delete' | 'invalidate' | 'clear';
+    operation?: 'write' | 'delete' | 'invalidate' | 'expire' | 'clear';
 }
 interface InvalidationBus {
     subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void> | void>;
@@ -255,7 +288,7 @@ interface CacheWriteBehindOptions {
 }
 interface CacheWarmEntry<T = unknown> {
     key: string;
-    fetcher: () => Promise<T>;
+    fetcher: CacheFetcher<T>;
     options?: CacheGetOptions;
     priority?: number;
 }
@@ -301,12 +334,12 @@ interface CacheInspectResult {
     key: string;
     /** Layers in which the key is currently stored (not expired). */
     foundInLayers: string[];
-    /** Remaining fresh TTL in seconds, or null if no expiry or not an envelope. */
-    freshTtlSeconds: number | null;
-    /** Remaining stale-while-revalidate window in seconds, or null. */
-    staleTtlSeconds: number | null;
-    /** Remaining stale-if-error window in seconds, or null. */
-    errorTtlSeconds: number | null;
+    /** Remaining fresh TTL in milliseconds, or null if no expiry or not an envelope. */
+    freshTtlMs: number | null;
+    /** Remaining stale-while-revalidate window in milliseconds, or null. */
+    staleTtlMs: number | null;
+    /** Remaining stale-if-error window in milliseconds, or null. */
+    errorTtlMs: number | null;
     /** Whether the key is currently serving stale-while-revalidate. */
     isStale: boolean;
     /** Tags associated with this key (from the TagIndex). */
@@ -335,6 +368,10 @@ interface CacheStackEvents {
     delete: {
         keys: string[];
     };
+    /** Fired after one or more keys are marked expired but retained. */
+    expire: {
+        keys: string[];
+    };
     /** Fired when a value is backfilled into a faster layer. */
     backfill: {
         key: string;
@@ -486,12 +523,12 @@ declare class CacheNamespace {
     private static readonly metricsMutexes;
     private metrics;
     constructor(cache: CacheStack, prefix: string);
-    get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
-    getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    get<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
+    getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      */
-    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
+    getOrThrow<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T>;
     has(key: string): Promise<boolean>;
     ttl(key: string): Promise<number | null>;
     set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
@@ -501,9 +538,13 @@ declare class CacheNamespace {
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
+    expireByTag(tag: string): Promise<void>;
     invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    expireByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    expireByPattern(pattern: string): Promise<void>;
     invalidateByPrefix(prefix: string): Promise<void>;
+    expireByPrefix(prefix: string): Promise<void>;
     /**
      * Returns detailed metadata about a single cache key within this namespace.
      */
@@ -557,8 +598,6 @@ declare class CacheStack extends EventEmitter {
     private readonly invalidation;
     private readonly layerWriter;
     private readonly snapshots;
-    private readonly backgroundRefreshes;
-    private readonly backgroundRefreshAbort;
     private readonly layerDegradedUntil;
     private readonly maintenance;
     private readonly ttlResolver;
@@ -566,6 +605,7 @@ declare class CacheStack extends EventEmitter {
     private nextOperationId;
     private currentGeneration?;
     private isDisconnecting;
+    private readonly reader;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
     /**
@@ -574,25 +614,24 @@ declare class CacheStack extends EventEmitter {
      * and stores the result across all layers. Returns `null` if the key is not found
      * and no `fetcher` is provided.
      */
-    get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
-    private getPrepared;
+    get<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
     /**
      * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
      * Fetches and caches the value if not already present.
      */
-    getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      * Useful when the value is expected to exist or the fetcher is expected to
      * return non-null.
      */
-    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
+    getOrThrow<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T>;
     /**
      * Returns true if the given key exists and is not expired in any layer.
      */
     has(key: string): Promise<boolean>;
     /**
-     * Returns the remaining TTL in seconds for the key in the fastest layer
+     * Returns the remaining TTL in milliseconds for the key in the fastest layer
      * that has it, or null if the key is not found / has no TTL.
      */
     ttl(key: string): Promise<number | null>;
@@ -623,9 +662,13 @@ declare class CacheStack extends EventEmitter {
      */
     namespace(prefix: string): CacheNamespace;
     invalidateByTag(tag: string): Promise<void>;
+    expireByTag(tag: string): Promise<void>;
     invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    expireByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    expireByPattern(pattern: string): Promise<void>;
     invalidateByPrefix(prefix: string): Promise<void>;
+    expireByPrefix(prefix: string): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getStats(): CacheStatsSnapshot;
     resetMetrics(): void;
@@ -652,21 +695,15 @@ declare class CacheStack extends EventEmitter {
     restoreFromFile(filePath: string): Promise<void>;
     disconnect(): Promise<void>;
     private initialize;
-    private fetchWithGuards;
-    private waitForFreshValue;
-    private fetchAndPopulate;
     private storeEntry;
     private writeBatch;
-    private readFromLayers;
-    private readLayerEntry;
-    private backfill;
     private resolveFreshTtl;
-    private resolveLayerSeconds;
-    private shouldNegativeCache;
-    private scheduleBackgroundRefresh;
-    private runBackgroundRefresh;
-    private resolveSingleFlightOptions;
+    private resolveLayerMs;
+    private resolveContextOptions;
+    private isPlainObject;
     private deleteKeys;
+    private expireKeys;
+    private expireKeysInLayers;
     private publishInvalidation;
     private handleInvalidationMessage;
     private getTagsForKey;
@@ -689,13 +726,14 @@ declare class CacheStack extends EventEmitter {
     private validateWriteOptions;
     private assertActive;
     private awaitStartup;
+    private readLayerEntry;
+    private scheduleBackgroundRefresh;
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
     private reportRecoverableLayerFailure;
     private isGracefulDegradationEnabled;
     private recordCircuitFailure;
-    private isNegativeStoredValue;
     private emitError;
     private snapshotMaxBytes;
     private snapshotMaxEntries;
@@ -722,4 +760,4 @@ interface HonoCacheMiddlewareOptions extends CacheGetOptions {
 }
 declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<unknown>;
 
-export { type CacheStatsSnapshot as A, type CacheTtlPolicy as B, type CacheLogger as C, type CacheTtlPolicyContext as D, type CacheWarmEntry as E, type CacheWarmOptions as F, type CacheWarmProgress as G, type CacheWriteBehindOptions as H, type InvalidationBus as I, type CacheWriteOptions as J, type EvictionPolicy as K, type LayerTtlMap as L, MemoryLayer as M, type MemoryLayerOptions as N, type MemoryLayerSnapshotEntry as O, PatternMatcher as P, createHonoCacheMiddleware as Q, TagIndex as T, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheDegradationOptions as m, type CacheHealthCheckResult as n, type CacheHitRateSnapshot as o, type CacheInspectResult as p, type CacheLayerLatency as q, type CacheMGetEntry as r, type CacheMSetEntry as s, type CacheMetricsSnapshot as t, CacheMissError as u, CacheNamespace as v, type CacheRateLimitOptions as w, type CacheSnapshotEntry as x, type CacheStackEvents as y, type CacheStackOptions as z };
+export { CacheNamespace as A, type CacheRateLimitOptions as B, type CacheLogger as C, type CacheSnapshotEntry as D, type CacheStackEvents as E, type CacheStackOptions as F, type CacheStatsSnapshot as G, type CacheTtlPolicy as H, type InvalidationBus as I, type CacheTtlPolicyContext as J, type CacheWarmEntry as K, type CacheWarmOptions as L, type CacheWarmProgress as M, type CacheWriteBehindOptions as N, type CacheWriteOptions as O, type EvictionPolicy as P, type LayerTtlMap as Q, MemoryLayer as R, type MemoryLayerOptions as S, type MemoryLayerSnapshotEntry as T, PatternMatcher as U, TagIndex as V, createHonoCacheMiddleware as W, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheContextOptionsContext as m, type CacheDegradationOptions as n, type CacheEntryWriteKind as o, type CacheEntryWriteOptions as p, type CacheFetcher as q, type CacheFetcherContext as r, type CacheHealthCheckResult as s, type CacheHitRateSnapshot as t, type CacheInspectResult as u, type CacheLayerLatency as v, type CacheMGetEntry as w, type CacheMSetEntry as x, type CacheMetricsSnapshot as y, CacheMissError as z };

package/dist/{edge-CUHTP9Bc.d.ts → edge-D2FpRlyS.d.ts}

@@ -11,18 +11,26 @@ declare class CacheMissError extends Error {
 interface LayerTtlMap {
     [layerName: string]: number | undefined;
 }
-interface CacheWriteOptions {
+type CacheEntryWriteKind = 'value' | 'empty';
+interface CacheEntryWriteOptions {
     tags?: string[];
     ttl?: number | LayerTtlMap;
     ttlPolicy?: CacheTtlPolicy;
-    negativeCache?: boolean;
     negativeTtl?: number | LayerTtlMap;
     staleWhileRevalidate?: number | LayerTtlMap;
     staleIfError?: number | LayerTtlMap;
     ttlJitter?: number | LayerTtlMap;
+    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
+}
+interface CacheContextOptionsContext {
+    key: string;
+    value: unknown;
+    kind: CacheEntryWriteKind;
+}
+interface CacheWriteOptions extends CacheEntryWriteOptions {
+    negativeCache?: boolean;
     slidingTtl?: boolean;
     refreshAhead?: number | LayerTtlMap;
-    adaptiveTtl?: boolean | CacheAdaptiveTtlOptions;
     circuitBreaker?: CacheCircuitBreakerOptions;
     fetcherRateLimit?: CacheRateLimitOptions;
     /**
@@ -34,12 +42,37 @@ interface CacheWriteOptions {
      * cache.get('key', fetchData, { shouldCache: (v) => v.status === 200 })
      */
     shouldCache?: (value: unknown) => boolean;
+    /**
+     * Optional resolver that can override cache entry options using the current
+     * write context. This runs right before a value is stored, so callers can
+     * derive TTLs or tags from the fetched value instead of guessing upfront.
+     *
+     * Returned values override any static entry options already present on the
+     * same object. Fetch controls like `shouldCache`, `negativeCache`,
+     * `refreshAhead`, or `circuitBreaker` are not affected.
+     *
+     * @example
+     * cache.get('oauth:token', fetchToken, {
+     *   ttl: 300_000,
+     *   contextOptions: ({ value }) => ({
+     *     ttl: Math.max(1, Math.floor(((value as { refreshExpiresIn: number }).refreshExpiresIn ?? 0) / 1_000))
+     *   })
+     * })
+     */
+    contextOptions?: (context: CacheContextOptionsContext) => CacheEntryWriteOptions | undefined;
 }
 interface CacheGetOptions extends CacheWriteOptions {
 }
+interface CacheFetcherContext<T = unknown> {
+    key: string;
+    currentValue: T | undefined;
+    state: 'miss' | 'fresh' | 'stale-while-revalidate' | 'stale-if-error';
+    layer?: string;
+}
+type CacheFetcher<T = unknown> = (context: CacheFetcherContext<T>) => Promise<T>;
 interface CacheMGetEntry<T> {
     key: string;
-    fetch?: () => Promise<T>;
+    fetch?: CacheFetcher<T>;
     options?: CacheGetOptions;
 }
 interface CacheMSetEntry<T> {
@@ -75,7 +108,7 @@ interface CacheLayer {
      */
     has?(key: string): Promise<boolean>;
     /**
-     * Returns the remaining TTL in seconds for the key, or null if the key
+     * Returns the remaining TTL in milliseconds for the key, or null if the key
      * does not exist, has no TTL, or has already expired.
      * Implementations may omit this.
      */
@@ -159,7 +192,7 @@ interface InvalidationMessage {
     scope: 'key' | 'keys' | 'clear';
     sourceId: string;
     keys?: string[];
-    operation?: 'write' | 'delete' | 'invalidate' | 'clear';
+    operation?: 'write' | 'delete' | 'invalidate' | 'expire' | 'clear';
 }
 interface InvalidationBus {
     subscribe(handler: (message: InvalidationMessage) => Promise<void> | void): Promise<() => Promise<void> | void>;
@@ -255,7 +288,7 @@ interface CacheWriteBehindOptions {
 }
 interface CacheWarmEntry<T = unknown> {
     key: string;
-    fetcher: () => Promise<T>;
+    fetcher: CacheFetcher<T>;
     options?: CacheGetOptions;
     priority?: number;
 }
@@ -301,12 +334,12 @@ interface CacheInspectResult {
     key: string;
     /** Layers in which the key is currently stored (not expired). */
     foundInLayers: string[];
-    /** Remaining fresh TTL in seconds, or null if no expiry or not an envelope. */
-    freshTtlSeconds: number | null;
-    /** Remaining stale-while-revalidate window in seconds, or null. */
-    staleTtlSeconds: number | null;
-    /** Remaining stale-if-error window in seconds, or null. */
-    errorTtlSeconds: number | null;
+    /** Remaining fresh TTL in milliseconds, or null if no expiry or not an envelope. */
+    freshTtlMs: number | null;
+    /** Remaining stale-while-revalidate window in milliseconds, or null. */
+    staleTtlMs: number | null;
+    /** Remaining stale-if-error window in milliseconds, or null. */
+    errorTtlMs: number | null;
     /** Whether the key is currently serving stale-while-revalidate. */
     isStale: boolean;
     /** Tags associated with this key (from the TagIndex). */
@@ -335,6 +368,10 @@ interface CacheStackEvents {
     delete: {
         keys: string[];
     };
+    /** Fired after one or more keys are marked expired but retained. */
+    expire: {
+        keys: string[];
+    };
     /** Fired when a value is backfilled into a faster layer. */
     backfill: {
         key: string;
@@ -486,12 +523,12 @@ declare class CacheNamespace {
     private static readonly metricsMutexes;
     private metrics;
     constructor(cache: CacheStack, prefix: string);
-    get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
-    getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    get<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
+    getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      */
-    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
+    getOrThrow<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T>;
     has(key: string): Promise<boolean>;
     ttl(key: string): Promise<number | null>;
     set<T>(key: string, value: T, options?: CacheWriteOptions): Promise<void>;
@@ -501,9 +538,13 @@ declare class CacheNamespace {
     mget<T>(entries: CacheMGetEntry<T>[]): Promise<Array<T | null>>;
     mset<T>(entries: CacheMSetEntry<T>[]): Promise<void>;
     invalidateByTag(tag: string): Promise<void>;
+    expireByTag(tag: string): Promise<void>;
     invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    expireByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    expireByPattern(pattern: string): Promise<void>;
     invalidateByPrefix(prefix: string): Promise<void>;
+    expireByPrefix(prefix: string): Promise<void>;
     /**
      * Returns detailed metadata about a single cache key within this namespace.
      */
@@ -557,8 +598,6 @@ declare class CacheStack extends EventEmitter {
     private readonly invalidation;
     private readonly layerWriter;
     private readonly snapshots;
-    private readonly backgroundRefreshes;
-    private readonly backgroundRefreshAbort;
     private readonly layerDegradedUntil;
     private readonly maintenance;
     private readonly ttlResolver;
@@ -566,6 +605,7 @@ declare class CacheStack extends EventEmitter {
     private nextOperationId;
     private currentGeneration?;
     private isDisconnecting;
+    private readonly reader;
     private disconnectPromise?;
     constructor(layers: CacheLayer[], options?: CacheStackOptions);
     /**
@@ -574,25 +614,24 @@ declare class CacheStack extends EventEmitter {
      * and stores the result across all layers. Returns `null` if the key is not found
      * and no `fetcher` is provided.
      */
-    get<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
-    private getPrepared;
+    get<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
     /**
      * Alias for `get(key, fetcher, options)` — explicit get-or-set pattern.
      * Fetches and caches the value if not already present.
      */
-    getOrSet<T>(key: string, fetcher: () => Promise<T>, options?: CacheGetOptions): Promise<T | null>;
+    getOrSet<T>(key: string, fetcher: CacheFetcher<T>, options?: CacheGetOptions): Promise<T | null>;
     /**
      * Like `get()`, but throws `CacheMissError` instead of returning `null`.
      * Useful when the value is expected to exist or the fetcher is expected to
      * return non-null.
      */
-    getOrThrow<T>(key: string, fetcher?: () => Promise<T>, options?: CacheGetOptions): Promise<T>;
+    getOrThrow<T>(key: string, fetcher?: CacheFetcher<T>, options?: CacheGetOptions): Promise<T>;
     /**
      * Returns true if the given key exists and is not expired in any layer.
      */
     has(key: string): Promise<boolean>;
     /**
-     * Returns the remaining TTL in seconds for the key in the fastest layer
+     * Returns the remaining TTL in milliseconds for the key in the fastest layer
      * that has it, or null if the key is not found / has no TTL.
      */
     ttl(key: string): Promise<number | null>;
@@ -623,9 +662,13 @@ declare class CacheStack extends EventEmitter {
      */
     namespace(prefix: string): CacheNamespace;
     invalidateByTag(tag: string): Promise<void>;
+    expireByTag(tag: string): Promise<void>;
     invalidateByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
+    expireByTags(tags: string[], mode?: 'any' | 'all'): Promise<void>;
     invalidateByPattern(pattern: string): Promise<void>;
+    expireByPattern(pattern: string): Promise<void>;
     invalidateByPrefix(prefix: string): Promise<void>;
+    expireByPrefix(prefix: string): Promise<void>;
     getMetrics(): CacheMetricsSnapshot;
     getStats(): CacheStatsSnapshot;
     resetMetrics(): void;
@@ -652,21 +695,15 @@ declare class CacheStack extends EventEmitter {
     restoreFromFile(filePath: string): Promise<void>;
     disconnect(): Promise<void>;
     private initialize;
-    private fetchWithGuards;
-    private waitForFreshValue;
-    private fetchAndPopulate;
     private storeEntry;
     private writeBatch;
-    private readFromLayers;
-    private readLayerEntry;
-    private backfill;
     private resolveFreshTtl;
-    private resolveLayerSeconds;
-    private shouldNegativeCache;
-    private scheduleBackgroundRefresh;
-    private runBackgroundRefresh;
-    private resolveSingleFlightOptions;
+    private resolveLayerMs;
+    private resolveContextOptions;
+    private isPlainObject;
     private deleteKeys;
+    private expireKeys;
+    private expireKeysInLayers;
     private publishInvalidation;
     private handleInvalidationMessage;
     private getTagsForKey;
@@ -689,13 +726,14 @@ declare class CacheStack extends EventEmitter {
     private validateWriteOptions;
     private assertActive;
     private awaitStartup;
+    private readLayerEntry;
+    private scheduleBackgroundRefresh;
     private applyFreshReadPolicies;
     private shouldSkipLayer;
     private handleLayerFailure;
     private reportRecoverableLayerFailure;
     private isGracefulDegradationEnabled;
     private recordCircuitFailure;
-    private isNegativeStoredValue;
     private emitError;
     private snapshotMaxBytes;
     private snapshotMaxEntries;
@@ -722,4 +760,4 @@ interface HonoCacheMiddlewareOptions extends CacheGetOptions {
 }
 declare function createHonoCacheMiddleware(cache: CacheStack, options?: HonoCacheMiddlewareOptions): (context: HonoLikeContext, next: () => Promise<void>) => Promise<unknown>;
 
-export { type CacheStatsSnapshot as A, type CacheTtlPolicy as B, type CacheLogger as C, type CacheTtlPolicyContext as D, type CacheWarmEntry as E, type CacheWarmOptions as F, type CacheWarmProgress as G, type CacheWriteBehindOptions as H, type InvalidationBus as I, type CacheWriteOptions as J, type EvictionPolicy as K, type LayerTtlMap as L, MemoryLayer as M, type MemoryLayerOptions as N, type MemoryLayerSnapshotEntry as O, PatternMatcher as P, createHonoCacheMiddleware as Q, TagIndex as T, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheDegradationOptions as m, type CacheHealthCheckResult as n, type CacheHitRateSnapshot as o, type CacheInspectResult as p, type CacheLayerLatency as q, type CacheMGetEntry as r, type CacheMSetEntry as s, type CacheMetricsSnapshot as t, CacheMissError as u, CacheNamespace as v, type CacheRateLimitOptions as w, type CacheSnapshotEntry as x, type CacheStackEvents as y, type CacheStackOptions as z };
+export { CacheNamespace as A, type CacheRateLimitOptions as B, type CacheLogger as C, type CacheSnapshotEntry as D, type CacheStackEvents as E, type CacheStackOptions as F, type CacheStatsSnapshot as G, type CacheTtlPolicy as H, type InvalidationBus as I, type CacheTtlPolicyContext as J, type CacheWarmEntry as K, type CacheWarmOptions as L, type CacheWarmProgress as M, type CacheWriteBehindOptions as N, type CacheWriteOptions as O, type EvictionPolicy as P, type LayerTtlMap as Q, MemoryLayer as R, type MemoryLayerOptions as S, type MemoryLayerSnapshotEntry as T, PatternMatcher as U, TagIndex as V, createHonoCacheMiddleware as W, type InvalidationMessage as a, type CacheTagIndex as b, CacheStack as c, type CacheWrapOptions as d, type CacheGetOptions as e, type CacheLayer as f, type CacheSerializer as g, type CacheLayerSetManyEntry as h, type CacheSingleFlightCoordinator as i, type CacheSingleFlightExecutionOptions as j, type CacheAdaptiveTtlOptions as k, type CacheCircuitBreakerOptions as l, type CacheContextOptionsContext as m, type CacheDegradationOptions as n, type CacheEntryWriteKind as o, type CacheEntryWriteOptions as p, type CacheFetcher as q, type CacheFetcherContext as r, type CacheHealthCheckResult as s, type CacheHitRateSnapshot as t, type CacheInspectResult as u, type CacheLayerLatency as v, type CacheMGetEntry as w, type CacheMSetEntry as x, type CacheMetricsSnapshot as y, CacheMissError as z };

package/dist/edge.cjs

@@ -67,17 +67,17 @@ function isStoredValueEnvelope(value) {
   if (typeof v.freshUntil === "number" && typeof v.errorUntil === "number" && v.errorUntil < v.freshUntil) {
     return false;
   }
-  const maxTtlSeconds = 10 * 365 * 24 * 60 * 60;
-  if (!isValidEnvelopeTtlSeconds(v.freshTtlSeconds, maxTtlSeconds)) {
+  const maxTtlMs = 10 * 365 * 24 * 60 * 60 * 1e3;
+  if (!isValidEnvelopeTtlMs(v.freshTtlMs, maxTtlMs)) {
     return false;
   }
-  if (!isValidEnvelopeTtlSeconds(v.staleWhileRevalidateSeconds, maxTtlSeconds)) {
+  if (!isValidEnvelopeTtlMs(v.staleWhileRevalidateMs, maxTtlMs)) {
     return false;
   }
-  if (!isValidEnvelopeTtlSeconds(v.staleIfErrorSeconds, maxTtlSeconds)) {
+  if (!isValidEnvelopeTtlMs(v.staleIfErrorMs, maxTtlMs)) {
     return false;
   }
-  if (v.freshTtlSeconds == null && (v.staleWhileRevalidateSeconds != null || v.staleIfErrorSeconds != null)) {
+  if (v.freshTtlMs == null && (v.staleWhileRevalidateMs != null || v.staleIfErrorMs != null)) {
     return false;
   }
   return true;
@@ -91,11 +91,11 @@ function unwrapStoredValue(stored) {
   }
   return stored.value ?? null;
 }
-function isValidEnvelopeTtlSeconds(value, maxTtlSeconds) {
+function isValidEnvelopeTtlMs(value, maxTtlMs) {
   if (value == null) {
     return true;
   }
-  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlSeconds;
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= maxTtlMs;
 }
 
 // src/layers/MemoryLayer.ts
@@ -153,7 +153,7 @@ var MemoryLayer = class {
     this.entries.delete(key);
     this.entries.set(key, {
       value,
-      expiresAt: ttl && ttl > 0 ? Date.now() + ttl * 1e3 : null,
+      expiresAt: ttl && ttl > 0 ? Date.now() + ttl : null,
       accessCount: 0,
       insertedAt: Date.now()
     });
@@ -184,7 +184,7 @@ var MemoryLayer = class {
     if (entry.expiresAt === null) {
       return null;
     }
-    return Math.max(0, Math.ceil((entry.expiresAt - Date.now()) / 1e3));
+    return Math.max(0, Math.ceil(entry.expiresAt - Date.now()));
   }
   async size() {
     this.pruneExpired();

package/dist/edge.d.cts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-CUHTP9Bc.cjs';
+export { m as CacheContextOptionsContext, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, y as CacheMetricsSnapshot, B as CacheRateLimitOptions, H as CacheTtlPolicy, J as CacheTtlPolicyContext, O as CacheWriteOptions, P as EvictionPolicy, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-D2FpRlyS.cjs';
 import 'node:events';

package/dist/edge.d.ts

@@ -1,2 +1,2 @@
-export { e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, t as CacheMetricsSnapshot, w as CacheRateLimitOptions, B as CacheTtlPolicy, D as CacheTtlPolicyContext, J as CacheWriteOptions, K as EvictionPolicy, M as MemoryLayer, N as MemoryLayerOptions, O as MemoryLayerSnapshotEntry, P as PatternMatcher, T as TagIndex, Q as createHonoCacheMiddleware } from './edge-CUHTP9Bc.js';
+export { m as CacheContextOptionsContext, o as CacheEntryWriteKind, p as CacheEntryWriteOptions, e as CacheGetOptions, f as CacheLayer, h as CacheLayerSetManyEntry, y as CacheMetricsSnapshot, B as CacheRateLimitOptions, H as CacheTtlPolicy, J as CacheTtlPolicyContext, O as CacheWriteOptions, P as EvictionPolicy, R as MemoryLayer, S as MemoryLayerOptions, T as MemoryLayerSnapshotEntry, U as PatternMatcher, V as TagIndex, W as createHonoCacheMiddleware } from './edge-D2FpRlyS.js';
 import 'node:events';

package/dist/edge.js

@@ -2,10 +2,10 @@ import {
   MemoryLayer,
   TagIndex,
   createHonoCacheMiddleware
-} from "./chunk-5RCAX2BQ.js";
+} from "./chunk-FFZCC7EQ.js";
 import {
   PatternMatcher
-} from "./chunk-4PPBOOXT.js";
+} from "./chunk-KJDFYE5T.js";
 export {
   MemoryLayer,
   PatternMatcher,