@zudojs/cache 0.1.0 → 1.0.0

package/dist/store.d.ts

@@ -1,8 +1,11 @@
 /**
  * @zudojs/cache — Store
  * Wraps a CacheAdapter with metrics, events, middleware, and error handling.
+ * Batch operations run through the same instrumentation path as single
+ * operations: per-key hit/miss metrics and events fire, and errors are
+ * wrapped in CacheError.
  */
-import type { CacheAdapter, CacheClearOptions, CacheClearResult, CacheDeleteOptions, CacheDeleteResult, CacheEvent, CacheEventHandler, CacheEventSubscription, CacheGetManyOptions, CacheGetOptions, CacheGetResult, CacheHasOptions, CacheKeysOptions, CacheMiddleware, CacheMetrics, CacheSetManyOptions, CacheSetOptions, CacheSetResult, CacheStore } from "./types.js";
+import type { CacheAdapter, CacheClearOptions, CacheClearResult, CacheDeleteManyResult, CacheDeleteResult, CacheEvent, CacheEventHandler, CacheEventSubscription, CacheGetResult, CacheKeysOptions, CacheMiddleware, CacheMetrics, CacheSetManyOptions, CacheSetOptions, CacheSetResult, CacheStore, CacheTTL } from "./types.js";
 export declare class DefaultCacheStore implements CacheStore {
     readonly name: string;
     private readonly adapter;
@@ -16,23 +19,30 @@ export declare class DefaultCacheStore implements CacheStore {
     });
     connect(): Promise<void>;
     disconnect(): Promise<void>;
-    get<TValue = unknown>(key: string, options?: CacheGetOptions): Promise<CacheGetResult<TValue>>;
-    has(key: string, options?: CacheHasOptions): Promise<boolean>;
+    get<TValue = unknown>(key: string): Promise<CacheGetResult<TValue>>;
+    has(key: string): Promise<boolean>;
     keys(options?: CacheKeysOptions): Promise<readonly string[]>;
     set<TValue = unknown>(key: string, value: TValue, options?: CacheSetOptions): Promise<CacheSetResult>;
-    delete(key: string, options?: CacheDeleteOptions): Promise<CacheDeleteResult>;
+    delete(key: string): Promise<CacheDeleteResult>;
     clear(options?: CacheClearOptions): Promise<CacheClearResult>;
-    getMany<TValue = unknown>(keys: readonly string[], options?: CacheGetManyOptions): Promise<ReadonlyMap<string, CacheGetResult<TValue>>>;
+    getMany<TValue = unknown>(keys: readonly string[]): Promise<ReadonlyMap<string, CacheGetResult<TValue>>>;
     setMany<TValue = unknown>(entries: ReadonlyMap<string, TValue>, options?: CacheSetManyOptions): Promise<readonly CacheSetResult[]>;
-    deleteMany(keys: readonly string[], options?: {
-        readonly namespace?: string;
-    }): Promise<{
-        readonly deleted: number;
-        readonly keys: readonly string[];
-    }>;
+    deleteMany(keys: readonly string[]): Promise<CacheDeleteManyResult>;
+    ttl(key: string): Promise<number | null | undefined>;
+    expire(key: string, ttl: CacheTTL): Promise<boolean>;
+    /** Number of live entries, when the underlying adapter can report it. */
+    size(): Promise<number | undefined>;
     subscribe(eventType: CacheEvent["type"] | "*", handler: CacheEventHandler): CacheEventSubscription;
     private emit;
+    private recordGetOutcome;
     private executeWithMiddleware;
+    /**
+     * A middleware that forgets to return `next()`'s result resolves
+     * `undefined`, which would otherwise be laundered into `T` by an unchecked
+     * cast and surface as a `TypeError` far from the cause. Only `ttl` may
+     * legitimately resolve `undefined`.
+     */
+    private narrowMiddlewareResult;
 }
 export declare function createCacheStore(options: {
     readonly adapter: CacheAdapter;

package/dist/store.js

@@ -1,8 +1,12 @@
 /**
  * @zudojs/cache — Store
  * Wraps a CacheAdapter with metrics, events, middleware, and error handling.
+ * Batch operations run through the same instrumentation path as single
+ * operations: per-key hit/miss metrics and events fire, and errors are
+ * wrapped in CacheError.
  */
 import { CacheError, CacheOperation } from "./errors.js";
+import { deleteManyViaDelete } from "./utils.js";
 export class DefaultCacheStore {
     name;
     adapter;
@@ -22,53 +26,88 @@ export class DefaultCacheStore {
     disconnect() {
         return this.adapter.disconnect?.() ?? Promise.resolve();
     }
-    async get(key, options) {
-        return this.executeWithMiddleware("get", key, () => this.adapter.get(key, options));
+    async get(key) {
+        return this.executeWithMiddleware(CacheOperation.GET, key, () => this.adapter.get(key));
     }
-    async has(key, options) {
-        return this.executeWithMiddleware("has", key, () => this.adapter.has(key, options));
+    async has(key) {
+        return this.executeWithMiddleware(CacheOperation.HAS, key, () => this.adapter.has(key));
     }
     async keys(options) {
-        return this.executeWithMiddleware("keys", "*", () => this.adapter.keys?.(options) ?? Promise.resolve([]));
+        return this.executeWithMiddleware(CacheOperation.KEYS, "*", () => this.adapter.keys?.(options) ?? Promise.resolve([]));
     }
     async set(key, value, options) {
-        return this.executeWithMiddleware("set", key, () => this.adapter.set(key, value, options));
+        return this.executeWithMiddleware(CacheOperation.SET, key, () => this.adapter.set(key, value, options), { ttl: options?.ttl });
     }
-    async delete(key, options) {
-        return this.executeWithMiddleware("delete", key, () => this.adapter.delete(key, options));
+    async delete(key) {
+        return this.executeWithMiddleware(CacheOperation.DELETE, key, () => this.adapter.delete(key));
     }
     async clear(options) {
-        return this.executeWithMiddleware("clear", "*", () => this.adapter.clear(options));
-    }
-    async getMany(keys, options) {
-        if (this.adapter.getMany)
-            return this.adapter.getMany(keys, options);
-        const results = new Map();
-        for (const key of keys)
-            results.set(key, await this.get(key, options));
+        return this.executeWithMiddleware(CacheOperation.CLEAR, "*", () => this.adapter.clear(options));
+    }
+    async getMany(keys) {
+        if (!this.adapter.getMany) {
+            const results = new Map();
+            for (const key of keys)
+                results.set(key, await this.get(key));
+            return results;
+        }
+        const results = await this.executeWithMiddleware(CacheOperation.GET_MANY, "*", () => this.adapter.getMany(keys));
+        for (const key of keys) {
+            this.recordGetOutcome(key, results.get(key)?.hit ?? false);
+        }
         return results;
     }
     async setMany(entries, options) {
-        if (this.adapter.setMany)
-            return this.adapter.setMany(entries, options);
-        const results = [];
-        for (const [key, value] of entries)
-            results.push(await this.set(key, value, options));
+        if (!this.adapter.setMany) {
+            const results = [];
+            for (const [key, value] of entries)
+                results.push(await this.set(key, value, options));
+            return results;
+        }
+        const results = await this.executeWithMiddleware(CacheOperation.SET_MANY, "*", () => this.adapter.setMany(entries, options));
+        for (const result of results) {
+            if (!result.success)
+                continue;
+            this.metrics?.incrementSet(result.key);
+            this.emit({
+                type: "cache.set",
+                key: result.key,
+                occurredAt: new Date(),
+                ...(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
+            });
+        }
         return results;
     }
-    async deleteMany(keys, options) {
-        if (this.adapter.deleteMany)
-            return this.adapter.deleteMany(keys, options);
-        let deleted = 0;
-        const deletedKeys = [];
+    async deleteMany(keys) {
+        if (!this.adapter.deleteMany) {
+            return deleteManyViaDelete(keys, (key) => this.delete(key));
+        }
+        const result = await this.executeWithMiddleware(CacheOperation.DELETE_MANY, "*", () => this.adapter.deleteMany(keys));
+        const deletedKeys = new Set(result.keys);
         for (const key of keys) {
-            const result = await this.delete(key, options);
-            if (result.deleted) {
-                deleted++;
-                deletedKeys.push(key);
-            }
+            this.metrics?.incrementDelete(key);
+            this.emit({
+                type: "cache.delete",
+                key,
+                occurredAt: new Date(),
+                deleted: deletedKeys.has(key),
+            });
         }
-        return { deleted, keys: deletedKeys };
+        return result;
+    }
+    async ttl(key) {
+        if (!this.adapter.ttl)
+            return undefined;
+        return this.executeWithMiddleware(CacheOperation.TTL, key, () => this.adapter.ttl(key));
+    }
+    async expire(key, ttl) {
+        if (!this.adapter.expire)
+            return false;
+        return this.executeWithMiddleware(CacheOperation.EXPIRE, key, () => this.adapter.expire(key, ttl));
+    }
+    /** Number of live entries, when the underlying adapter can report it. */
+    async size() {
+        return this.adapter.size?.();
     }
     subscribe(eventType, handler) {
         if (!this.handlers.has(eventType))
@@ -89,14 +128,28 @@ export class DefaultCacheStore {
         ]);
         for (const handler of all) {
             try {
-                handler(event);
+                // Swallow both sync throws and async rejections so a faulty
+                // handler can never crash the process.
+                Promise.resolve(handler(event)).catch(() => {
+                    /* swallow */
+                });
             }
             catch {
                 /* swallow */
             }
         }
     }
-    async executeWithMiddleware(operation, key, fn) {
+    recordGetOutcome(key, hit, latencyMs) {
+        if (hit) {
+            this.metrics?.incrementHit(key);
+            this.emit({ type: "cache.hit", key, occurredAt: new Date(), latencyMs });
+        }
+        else {
+            this.metrics?.incrementMiss(key);
+            this.emit({ type: "cache.miss", key, occurredAt: new Date(), latencyMs });
+        }
+    }
+    async executeWithMiddleware(operation, key, fn, details) {
         const context = {
             key,
             operation,
@@ -108,45 +161,33 @@ export class DefaultCacheStore {
                 const result = await fn();
                 const latencyMs = performance.now() - start;
                 this.metrics?.observeLatency(operation, latencyMs);
-                if (operation === "get") {
+                if (operation === CacheOperation.GET) {
                     const hitResult = result;
-                    if (hitResult.hit) {
-                        this.metrics?.incrementHit(key);
-                        this.emit({
-                            type: "cache.hit",
-                            key,
-                            occurredAt: new Date(),
-                            latencyMs,
-                        });
-                    }
-                    else {
-                        this.metrics?.incrementMiss(key);
-                        this.emit({
-                            type: "cache.miss",
-                            key,
-                            occurredAt: new Date(),
-                            latencyMs,
-                        });
-                    }
+                    this.recordGetOutcome(key, hitResult.hit, latencyMs);
                 }
-                else if (operation === "set") {
+                else if (operation === CacheOperation.SET) {
                     this.metrics?.incrementSet(key);
-                    this.emit({ type: "cache.set", key, occurredAt: new Date() });
+                    this.emit({
+                        type: "cache.set",
+                        key,
+                        occurredAt: new Date(),
+                        ...(details?.ttl !== undefined ? { ttl: details.ttl } : {}),
+                    });
                 }
-                else if (operation === "delete") {
+                else if (operation === CacheOperation.DELETE) {
                     this.metrics?.incrementDelete(key);
                     this.emit({
                         type: "cache.delete",
                         key,
                         occurredAt: new Date(),
-                        deleted: true,
+                        deleted: result.deleted,
                     });
                 }
-                else if (operation === "clear") {
+                else if (operation === CacheOperation.CLEAR) {
                     this.emit({
                         type: "cache.clear",
                         occurredAt: new Date(),
-                        cleared: 0,
+                        cleared: result.cleared,
                     });
                 }
                 return result;
@@ -154,24 +195,43 @@ export class DefaultCacheStore {
             catch (error) {
                 this.metrics?.incrementError(key);
                 this.emit({ type: "cache.error", key, occurredAt: new Date(), error });
+                if (error instanceof CacheError)
+                    throw error;
+                const code = "CACHE_OPERATION_FAILED";
                 throw new CacheError(`Cache ${operation} failed for key "${key}".`, {
+                    code,
                     cause: error,
                     operation,
                     key,
                 });
             }
         };
-        let index = 0;
-        const chain = async () => {
+        // The position is a parameter, not shared mutable state: a middleware
+        // that calls next() twice (retry middlewares do) re-enters at the same
+        // position instead of skipping the middlewares after it.
+        const chain = async (index) => {
             if (index >= this.middlewares.length)
                 return execute();
             const middleware = this.middlewares[index];
-            index++;
             if (middleware === undefined)
-                return execute();
-            return middleware(context, chain);
+                return chain(index + 1);
+            const result = await middleware(context, () => chain(index + 1));
+            return this.narrowMiddlewareResult(result, operation, key);
         };
-        return chain();
+        return chain(0);
+    }
+    /**
+     * A middleware that forgets to return `next()`'s result resolves
+     * `undefined`, which would otherwise be laundered into `T` by an unchecked
+     * cast and surface as a `TypeError` far from the cause. Only `ttl` may
+     * legitimately resolve `undefined`.
+     */
+    narrowMiddlewareResult(result, operation, key) {
+        if (result === undefined && operation !== CacheOperation.TTL) {
+            const code = "CACHE_MIDDLEWARE_RESULT_MISSING";
+            throw new CacheError(`A cache middleware resolved undefined for ${operation} on key "${key}". Middlewares must return the result of next().`, { code, operation, key });
+        }
+        return result;
     }
 }
 export function createCacheStore(options) {

package/dist/tags.d.ts

@@ -3,30 +3,50 @@
  *
  * Tag-based cache invalidation registry. Maps tags to cache keys,
  * allowing bulk invalidation of related entries.
+ *
+ * Tags are scoped by namespace: the internal map key is the
+ * `(namespace, tag)` pair, so the same tag registered under two namespaces
+ * yields two independent sets. Without this, one tenant's
+ * `invalidateByTag(["users"])` would delete another tenant's entries — the
+ * keys are namespace-qualified, but a flat tag map would not be.
+ *
+ * NOTE: The tag store is not notified when entries expire or are evicted
+ * by the adapter, so cleanup of stale mappings is lazy — dead keys linger
+ * until `invalidateByTag`/`removeKey`/`clear` touches them, and
+ * invalidation tolerates keys that no longer exist in the cache.
  */
 import type { CacheClearResult, CacheKey, CacheTag, CacheTagOptions, CacheTagStore } from "./types.js";
+/**
+ * Validates a tag. Tags are untrusted strings used as map keys, so they are
+ * required to be non-empty, length-bounded, and free of the scope separator.
+ */
+export declare function assertValidTag(tag: CacheTag): void;
 /**
  * In-memory implementation of `CacheTagStore`.
  *
- * Maintains a bidirectional mapping between tags and cache keys.
+ * Maintains a bidirectional mapping between scoped tags and cache keys.
  * For production use, this should be backed by a persistent store
  * (e.g., Redis SETs).
  */
 export declare class InMemoryTagStore implements CacheTagStore {
-    /** Tag → Set of keys */
+    /** (namespace, tag) → Set of keys */
     private readonly tagToKeys;
-    /** Key → Set of tags */
+    /** Key → Set of (namespace, tag) */
     private readonly keyToTags;
-    add(key: CacheKey, tags: readonly CacheTag[], _options?: CacheTagOptions): Promise<void>;
-    remove(key: CacheKey, tags: readonly CacheTag[], _options?: CacheTagOptions): Promise<void>;
-    getKeys(tag: CacheTag, _options?: CacheTagOptions): Promise<readonly CacheKey[]>;
-    invalidate(tag: CacheTag, _options?: CacheTagOptions): Promise<CacheClearResult>;
-    /** Returns all registered tags. */
-    tags(): readonly CacheTag[];
+    add(key: CacheKey, tags: readonly CacheTag[], options?: CacheTagOptions): Promise<void>;
+    remove(key: CacheKey, tags: readonly CacheTag[], options?: CacheTagOptions): Promise<void>;
+    getKeys(tag: CacheTag, options?: CacheTagOptions): Promise<readonly CacheKey[]>;
+    invalidate(tag: CacheTag, options?: CacheTagOptions): Promise<CacheClearResult>;
+    /** Removes all tag mappings for a key (e.g. after the key is deleted). */
+    removeKey(key: CacheKey): void;
+    /** Returns all keys that currently have tag mappings. */
+    trackedKeys(): readonly CacheKey[];
+    /** Returns all registered tags, optionally scoped to a namespace. */
+    tags(options?: CacheTagOptions): readonly CacheTag[];
     /** Returns the number of keys mapped to a tag. */
-    count(tag: CacheTag): number;
-    /** Returns all tags for a given key. */
-    tagsForKey(key: CacheKey): readonly CacheTag[];
+    count(tag: CacheTag, options?: CacheTagOptions): number;
+    /** Returns all tags for a given key, optionally scoped to a namespace. */
+    tagsForKey(key: CacheKey, options?: CacheTagOptions): readonly CacheTag[];
     /** Clears all tag mappings. */
     clear(): void;
 }

package/dist/tags.js

@@ -3,77 +3,157 @@
  *
  * Tag-based cache invalidation registry. Maps tags to cache keys,
  * allowing bulk invalidation of related entries.
+ *
+ * Tags are scoped by namespace: the internal map key is the
+ * `(namespace, tag)` pair, so the same tag registered under two namespaces
+ * yields two independent sets. Without this, one tenant's
+ * `invalidateByTag(["users"])` would delete another tenant's entries — the
+ * keys are namespace-qualified, but a flat tag map would not be.
+ *
+ * NOTE: The tag store is not notified when entries expire or are evicted
+ * by the adapter, so cleanup of stale mappings is lazy — dead keys linger
+ * until `invalidateByTag`/`removeKey`/`clear` touches them, and
+ * invalidation tolerates keys that no longer exist in the cache.
+ */
+import { MAX_TAG_LENGTH } from "./constants.js";
+import { CacheError } from "./errors.js";
+/** Separates the namespace from the tag in the internal map key. */
+const SCOPE_SEPARATOR = "\u0000";
+/**
+ * Composes the internal `(namespace, tag)` map key. A NUL byte cannot appear
+ * in a validated tag, so the composition is unambiguous.
  */
+function scopedTag(tag, options) {
+    return `${options?.namespace ?? ""}${SCOPE_SEPARATOR}${tag}`;
+}
+/**
+ * Validates a tag. Tags are untrusted strings used as map keys, so they are
+ * required to be non-empty, length-bounded, and free of the scope separator.
+ */
+export function assertValidTag(tag) {
+    if (typeof tag !== "string" || tag.length === 0) {
+        throw new CacheError("Cache tag must be a non-empty string.", {
+            code: "CACHE_OPERATION_FAILED",
+            statusCode: 400,
+            expose: true,
+        });
+    }
+    if (tag.length > MAX_TAG_LENGTH || tag.includes(SCOPE_SEPARATOR)) {
+        throw new CacheError(`Invalid cache tag: tags must be at most ${MAX_TAG_LENGTH} characters and must not contain NUL.`, { code: "CACHE_OPERATION_FAILED", statusCode: 400, expose: true });
+    }
+}
 /* -------------------------------------------------------------------------- */
 /* In-Memory Tag Store                                                        */
 /* -------------------------------------------------------------------------- */
 /**
  * In-memory implementation of `CacheTagStore`.
  *
- * Maintains a bidirectional mapping between tags and cache keys.
+ * Maintains a bidirectional mapping between scoped tags and cache keys.
  * For production use, this should be backed by a persistent store
  * (e.g., Redis SETs).
  */
 export class InMemoryTagStore {
-    /** Tag → Set of keys */
+    /** (namespace, tag) → Set of keys */
     tagToKeys = new Map();
-    /** Key → Set of tags */
+    /** Key → Set of (namespace, tag) */
     keyToTags = new Map();
     /* ---- Add Tags ---- */
-    async add(key, tags, _options) {
+    async add(key, tags, options) {
+        for (const tag of tags)
+            assertValidTag(tag);
         for (const tag of tags) {
-            if (!this.tagToKeys.has(tag)) {
-                this.tagToKeys.set(tag, new Set());
+            const scoped = scopedTag(tag, options);
+            if (!this.tagToKeys.has(scoped)) {
+                this.tagToKeys.set(scoped, new Set());
             }
-            this.tagToKeys.get(tag).add(key);
-        }
-        if (!this.keyToTags.has(key)) {
-            this.keyToTags.set(key, new Set());
-        }
-        for (const tag of tags) {
-            this.keyToTags.get(key).add(tag);
+            this.tagToKeys.get(scoped).add(key);
+            if (!this.keyToTags.has(key)) {
+                this.keyToTags.set(key, new Set());
+            }
+            this.keyToTags.get(key).add(scoped);
         }
     }
     /* ---- Remove Tags ---- */
-    async remove(key, tags, _options) {
-        for (const tag of tags) {
-            this.tagToKeys.get(tag)?.delete(key);
-        }
+    async remove(key, tags, options) {
         for (const tag of tags) {
-            this.keyToTags.get(key)?.delete(tag);
+            const scoped = scopedTag(tag, options);
+            const keys = this.tagToKeys.get(scoped);
+            keys?.delete(key);
+            if (keys && keys.size === 0)
+                this.tagToKeys.delete(scoped);
+            const owned = this.keyToTags.get(key);
+            owned?.delete(scoped);
+            if (owned && owned.size === 0)
+                this.keyToTags.delete(key);
         }
     }
     /* ---- Get Keys by Tag ---- */
-    async getKeys(tag, _options) {
-        return [...(this.tagToKeys.get(tag) ?? [])];
+    async getKeys(tag, options) {
+        return [...(this.tagToKeys.get(scopedTag(tag, options)) ?? [])];
     }
     /* ---- Invalidate by Tag ---- */
-    async invalidate(tag, _options) {
-        const keys = this.tagToKeys.get(tag);
+    async invalidate(tag, options) {
+        const scoped = scopedTag(tag, options);
+        const keys = this.tagToKeys.get(scoped);
         if (!keys) {
             return { cleared: 0 };
         }
         const count = keys.size;
-        // Remove reverse mappings
+        // Remove reverse mappings, dropping keys that end up with no tags at
+        // all — otherwise every key ever tagged would leak an empty Set for the
+        // lifetime of the process and pollute `trackedKeys()`.
         for (const key of keys) {
-            this.keyToTags.get(key)?.delete(tag);
+            const remaining = this.keyToTags.get(key);
+            remaining?.delete(scoped);
+            if (remaining && remaining.size === 0)
+                this.keyToTags.delete(key);
         }
         // Clear the tag
-        this.tagToKeys.delete(tag);
+        this.tagToKeys.delete(scoped);
         return { cleared: count };
     }
+    /* ---- Remove Key ---- */
+    /** Removes all tag mappings for a key (e.g. after the key is deleted). */
+    removeKey(key) {
+        const tags = this.keyToTags.get(key);
+        if (!tags)
+            return;
+        for (const scoped of tags) {
+            const keys = this.tagToKeys.get(scoped);
+            keys?.delete(key);
+            if (keys && keys.size === 0)
+                this.tagToKeys.delete(scoped);
+        }
+        this.keyToTags.delete(key);
+    }
     /* ---- Utility ---- */
-    /** Returns all registered tags. */
-    tags() {
-        return [...this.tagToKeys.keys()];
+    /** Returns all keys that currently have tag mappings. */
+    trackedKeys() {
+        return [...this.keyToTags.keys()];
+    }
+    /** Returns all registered tags, optionally scoped to a namespace. */
+    tags(options) {
+        const prefix = `${options?.namespace ?? ""}${SCOPE_SEPARATOR}`;
+        const result = [];
+        for (const scoped of this.tagToKeys.keys()) {
+            if (scoped.startsWith(prefix))
+                result.push(scoped.slice(prefix.length));
+        }
+        return result;
     }
     /** Returns the number of keys mapped to a tag. */
-    count(tag) {
-        return this.tagToKeys.get(tag)?.size ?? 0;
+    count(tag, options) {
+        return this.tagToKeys.get(scopedTag(tag, options))?.size ?? 0;
     }
-    /** Returns all tags for a given key. */
-    tagsForKey(key) {
-        return [...(this.keyToTags.get(key) ?? [])];
+    /** Returns all tags for a given key, optionally scoped to a namespace. */
+    tagsForKey(key, options) {
+        const prefix = `${options?.namespace ?? ""}${SCOPE_SEPARATOR}`;
+        const result = [];
+        for (const scoped of this.keyToTags.get(key) ?? []) {
+            if (scoped.startsWith(prefix))
+                result.push(scoped.slice(prefix.length));
+        }
+        return result;
     }
     /** Clears all tag mappings. */
     clear() {

package/dist/types-adapter.d.ts

@@ -1,24 +1,38 @@
 import type { CacheKey } from "./types-keys.js";
 import type { CacheTTL } from "./types-values.js";
-import type { CacheClearOptions, CacheDeleteManyOptions, CacheDeleteOptions, CacheGetManyOptions, CacheGetOptions, CacheHasOptions, CacheKeysOptions, CacheSetManyOptions, CacheSetOptions } from "./types-operations.js";
+import type { CacheClearOptions, CacheKeysOptions, CacheSetManyOptions, CacheSetOptions } from "./types-operations.js";
 import type { CacheClearResult, CacheDeleteManyResult, CacheDeleteResult, CacheGetResult, CacheSetResult } from "./types-results.js";
+/**
+ * Low-level cache adapter contract.
+ *
+ * Adapters operate on fully-qualified keys — namespace/prefix resolution is
+ * the responsibility of `CacheService` and the key builder. Adapters only
+ * understand raw keys and glob patterns.
+ */
 export interface CacheAdapter {
     readonly name: string;
     connect?(): Promise<void>;
     disconnect?(): Promise<void>;
-    get<TValue = unknown>(key: CacheKey, options?: CacheGetOptions): Promise<CacheGetResult<TValue>>;
+    get<TValue = unknown>(key: CacheKey): Promise<CacheGetResult<TValue>>;
     set<TValue = unknown>(key: CacheKey, value: TValue, options?: CacheSetOptions): Promise<CacheSetResult>;
-    delete(key: CacheKey, options?: CacheDeleteOptions): Promise<CacheDeleteResult>;
-    has(key: CacheKey, options?: CacheHasOptions): Promise<boolean>;
+    delete(key: CacheKey): Promise<CacheDeleteResult>;
+    has(key: CacheKey): Promise<boolean>;
     clear(options?: CacheClearOptions): Promise<CacheClearResult>;
     keys?(options?: CacheKeysOptions): Promise<readonly CacheKey[]>;
-    getMany?<TValue = unknown>(keys: readonly CacheKey[], options?: CacheGetManyOptions): Promise<ReadonlyMap<CacheKey, CacheGetResult<TValue>>>;
+    getMany?<TValue = unknown>(keys: readonly CacheKey[]): Promise<ReadonlyMap<CacheKey, CacheGetResult<TValue>>>;
     setMany?<TValue = unknown>(entries: ReadonlyMap<CacheKey, TValue>, options?: CacheSetManyOptions): Promise<readonly CacheSetResult[]>;
-    deleteMany?(keys: readonly CacheKey[], options?: CacheDeleteManyOptions): Promise<CacheDeleteManyResult>;
-    ttl?(key: CacheKey, options?: CacheGetOptions): Promise<number | null>;
-    expire?(key: CacheKey, ttl: CacheTTL, options?: CacheGetOptions): Promise<boolean>;
+    deleteMany?(keys: readonly CacheKey[]): Promise<CacheDeleteManyResult>;
+    /**
+     * Remaining TTL for a key in milliseconds.
+     * - `undefined` — the key does not exist (or has expired)
+     * - `null` — the key exists and never expires
+     * - `number` — remaining milliseconds until expiry
+     */
+    ttl?(key: CacheKey): Promise<number | null | undefined>;
+    expire?(key: CacheKey, ttl: CacheTTL): Promise<boolean>;
+    /** Number of live entries currently held, when the adapter can report it. */
+    size?(): Promise<number | undefined>;
 }
 export interface CacheStore extends CacheAdapter {
 }
-export type CacheAdapterFactory<TOptions = unknown> = (options: TOptions) => CacheAdapter | Promise<CacheAdapter>;
 //# sourceMappingURL=types-adapter.d.ts.map