@zudojs/cache 0.0.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/cache
 
-Cache abstraction with memory adapter, tags, locking, and metrics for Zudojs applications.
+Cache abstraction with a memory adapter, namespaced tags, locking, events, middleware, and metrics for Zudojs applications.
 
 ## Installation
 
@@ -11,27 +11,103 @@ npm install @zudojs/cache
 ## Quick Start
 
 ```typescript
-import { createMemoryCache } from "@zudojs/cache";
+import { createCacheService, createMemoryCacheAdapter } from "@zudojs/cache";
 
-const cache = createMemoryCache({
-  ttl: 60000,
-  maxSize: 1000,
+const cache = createCacheService({
+  adapter: createMemoryCacheAdapter({ maxEntries: 1000 }),
+  config: { defaultTtl: 60_000 },
 });
 
-const user = await cache.get("user:123");
-if (!user) {
-  user = await fetchUserFromDb("123");
-  await cache.set("user:123", user);
+interface User {
+  id: string;
+  name: string;
 }
+
+async function getUser(id: string): Promise<User> {
+  // `get` returns a result wrapper, not the value: check `hit`, read `value`.
+  const cached = await cache.get<User>(`user.${id}`);
+  if (cached.hit) return cached.value!;
+
+  const user = await fetchUserFromDb(id);
+  await cache.set(`user.${id}`, user, { tags: ["users"] });
+  return user;
+}
+
+// Or let the cache do it, with stampede protection:
+const { value, cached } = await cache.getOrSet<User>(`user.${id}`, () =>
+  fetchUserFromDb(id),
+);
 ```
 
+Key parts are validated individually and must match `/^[a-zA-Z0-9._-]+$/`, so
+use `.` rather than the `:` separator inside a key (`user.123`, not
+`user:123`) — `:` is reserved for the `prefix:namespace:key` structure the key
+builder produces.
+
 ## Features
 
-- Pluggable cache adapters (memory, Redis, etc.)
-- TTL and size-based eviction
-- Cache tags for bulk invalidation
-- Distributed locking
-- Cache metrics and hit ratios
+- Pluggable cache adapters (memory built in; the `CacheAdapter` contract fits Redis and friends)
+- TTL and entry-count eviction, plus an approximate memory budget (`maxBytes`), with LRU ordering
+- Namespaced cache tags for bulk invalidation
+- Namespaced in-process locking with lease renewal (pluggable `CacheLockStore` for distributed backends)
+- Cache events, middleware, hit ratios, latency percentiles and hot keys
+
+## Multi-tenancy
+
+`namespace` is a scope boundary, not a pattern. It is validated everywhere it
+is used — including inside glob patterns — so an untrusted namespace can never
+widen an operation:
+
+```typescript
+await cache.set("u1", user, { namespace: tenantId, tags: ["users"] });
+
+// Only this tenant's entries — a tenantId of "*" is rejected, not honoured.
+await cache.clear({ namespace: tenantId });
+
+// Only this tenant's tagged entries.
+await cache.invalidateByTag(["users"], { namespace: tenantId });
+
+// Locks are namespaced and key-builder-qualified too.
+await cache.withLock("import", runImport, { namespace: tenantId });
+```
+
+In glob patterns, `*` matches within a single key segment and never crosses
+the `:` separator; `**` as a whole segment spans namespaces deliberately.
+
+## Observability
+
+```typescript
+const subscription = cache.subscribe("cache.miss", (event) => {
+  metrics.increment("cache.miss", { key: event.key });
+});
+
+cache.getStats(); // { hits, misses, sets, deletes, errors, hitRate }
+cache.getLatencyStats(CacheOperation.GET); // p50 / p95 / p99
+cache.getHotKeys(10);
+await cache.size();
+
+subscription.unsubscribe();
+```
+
+Middlewares wrap every adapter operation and are configured on the service:
+
+```typescript
+const cache = createCacheService({
+  adapter: createMemoryCacheAdapter(),
+  config: {
+    middlewares: [
+      async (ctx, next) => {
+        const span = tracer.start(ctx.operation);
+        try {
+          return await next(); // always return next()'s result
+        } finally {
+          span.end();
+        }
+      },
+    ],
+  },
+});
+```
 
 ## Use Cases
 

package/dist/cache.d.ts

@@ -1,9 +1,26 @@
 /**
  * @zudojs/cache — Cache Service
- * High-level cache service combining adapter, serializer, key builder, tags, invalidation, locking, and metrics.
+ * High-level cache service combining adapter, key builder, tags,
+ * invalidation, locking, metrics, middleware, events, and an optional
+ * serializer.
+ *
+ * Serialization: when `config.serializer` is provided, values are
+ * serialized on set and deserialized on get, so cached values are
+ * structural copies. Without a serializer the memory adapter stores
+ * values by reference — mutations of a cached object are visible to
+ * later readers.
+ *
+ * Scoping: keys, tags and locks are all namespace-scoped. A namespace is
+ * validated as an identity part everywhere it is used (including in glob
+ * patterns), so it can never widen an operation beyond its own tenant.
  */
-import type { CacheAdapter, CacheConfig, CacheDeleteResult, CacheGetResult, CacheHealth, CacheHealthChecker, CacheOrComputeOptions, CacheOrComputeResult, CacheSetResult, CacheStats, CacheTag } from "./types.js";
+import type { CacheAdapter, CacheBatchOperation, CacheBatchResult, CacheConfig, CacheDeleteResult, CacheEvent, CacheEventHandler, CacheEventSubscription, CacheGetResult, CacheHealth, CacheHealthChecker, CacheNamespace, CacheOperation, CacheOrComputeOptions, CacheOrComputeResult, CacheSetResult, CacheStats, CacheTag, CacheTTL } from "./types.js";
 import type { CacheKeyBuilder } from "./types-keys.js";
+import { InMemoryCacheMetrics } from "./metrics.js";
+/** Options accepted by every namespace-scoped read operation. */
+interface NamespaceOptions {
+    readonly namespace?: CacheNamespace;
+}
 export declare class CacheService implements CacheHealthChecker {
     private readonly store;
     private readonly keyBuilder;
@@ -11,52 +28,124 @@ export declare class CacheService implements CacheHealthChecker {
     private readonly invalidation;
     private readonly lockManager;
     private readonly metrics;
+    private readonly serializer;
     private readonly defaultTtl;
     private readonly enabled;
+    private readonly failSilently;
+    /** Namespace configured for this service; the default scope for keys, tags and locks. */
+    private readonly namespace;
+    private readonly separator;
+    /** In-flight getOrSet computations, keyed by full key (stampede protection). */
+    private readonly inFlight;
     constructor(options: {
         readonly adapter: CacheAdapter;
         readonly config?: CacheConfig;
         readonly keyBuilder?: CacheKeyBuilder;
     });
-    get<TValue = unknown>(key: string, options?: {
-        readonly namespace?: string;
-    }): Promise<CacheGetResult<TValue>>;
+    get<TValue = unknown>(key: string, options?: NamespaceOptions): Promise<CacheGetResult<TValue>>;
     set<TValue = unknown>(key: string, value: TValue, options?: {
-        readonly ttl?: number;
+        readonly ttl?: CacheTTL;
         readonly tags?: readonly CacheTag[];
-        readonly namespace?: string;
+        readonly namespace?: CacheNamespace;
+        readonly overwrite?: boolean;
+        readonly metadata?: Readonly<Record<string, unknown>>;
     }): Promise<CacheSetResult>;
-    delete(key: string, options?: {
-        readonly namespace?: string;
-    }): Promise<CacheDeleteResult>;
-    has(key: string, options?: {
-        readonly namespace?: string;
-    }): Promise<boolean>;
+    delete(key: string, options?: NamespaceOptions): Promise<CacheDeleteResult>;
+    has(key: string, options?: NamespaceOptions): Promise<boolean>;
+    /**
+     * Clears cache entries.
+     * - No options: clears everything (and flushes the tag store).
+     * - `namespace` and/or `pattern`: builds a fully-qualified pattern via
+     *   the key builder (prefix + namespace + pattern) so only matching
+     *   entries are removed. Both parts are validated: a `namespace` of `"*"`
+     *   is rejected rather than escaping its own scope.
+     */
     clear(options?: {
-        readonly namespace?: string;
+        readonly namespace?: CacheNamespace;
         readonly pattern?: string;
     }): Promise<{
         readonly cleared: number;
     }>;
+    /** Remaining TTL for a key (undefined = missing, null = never expires). */
+    ttl(key: string, options?: NamespaceOptions): Promise<number | null | undefined>;
+    /** Updates the TTL of an existing key. Returns false when unsupported or missing. */
+    expire(key: string, ttl: CacheTTL, options?: NamespaceOptions): Promise<boolean>;
     getOrSet<TValue>(key: string, fn: () => Promise<TValue>, options?: CacheOrComputeOptions): Promise<CacheOrComputeResult<TValue>>;
-    invalidateByTag(tags: readonly CacheTag[]): Promise<{
+    /**
+     * Invalidates every entry tagged with any of `tags`, within this
+     * service's namespace (or `options.namespace`). Tags registered under a
+     * different namespace are untouched.
+     */
+    invalidateByTag(tags: readonly CacheTag[], options?: NamespaceOptions): Promise<{
         readonly cleared: number;
     }>;
-    invalidateByPattern(pattern: string): Promise<{
+    /**
+     * Invalidates entries matching a service-level glob pattern. The
+     * pattern is qualified with the key builder's prefix (and namespace,
+     * if configured), so `invalidateByPattern("user.*")` matches keys this
+     * service wrote via `set("user.1", ...)`.
+     *
+     * `*` never crosses the key separator, so a pattern cannot reach into a
+     * namespace the caller did not name. Use `**` as the pattern to span
+     * whole namespaces deliberately.
+     */
+    invalidateByPattern(pattern: string, options?: NamespaceOptions): Promise<{
         readonly cleared: number;
     }>;
-    withLock<T>(key: string, fn: () => Promise<T>, options?: {
-        readonly ttl?: number;
+    /**
+     * Runs `fn` under a namespace-scoped, fully-qualified lock.
+     *
+     * The lock name goes through the key builder, so it is prefixed and
+     * namespaced exactly like a cache key and validated the same way — two
+     * tenants using the same lock name do not collide.
+     *
+     * The lease is renewed while `fn` runs and a lost lease throws (see
+     * `CacheLockManager.withLock`). `failSilently` deliberately does not apply:
+     * running a critical section without exclusion is never a safe
+     * degradation, and neither is running it while the cache is disabled.
+     */
+    withLock<T>(key: string, fn: (signal: AbortSignal) => Promise<T>, options?: {
+        readonly ttl?: CacheTTL;
         readonly retryAttempts?: number;
+        readonly namespace?: CacheNamespace;
     }): Promise<T>;
+    /**
+     * Applies a sequence of operations, one at a time, returning one result
+     * per operation in submission order. A failing operation does not stop
+     * the batch; its error is reported on its own result.
+     */
+    batch(operations: readonly CacheBatchOperation[], options?: NamespaceOptions): Promise<readonly CacheBatchResult[]>;
     getStats(): CacheStats | null;
+    /** Number of live entries, when the underlying adapter can report it. */
+    size(): Promise<number | undefined>;
+    /** Latency percentiles for one operation. */
+    getLatencyStats(operation: CacheOperation): ReturnType<InMemoryCacheMetrics["getLatencyStats"]> | null;
+    /** Latency histogram for one operation. */
+    getLatencyHistogram(operation: CacheOperation): ReturnType<InMemoryCacheMetrics["getLatencyHistogram"]> | null;
+    /** The most-read keys currently tracked, hottest first. */
+    getHotKeys(topN?: number): ReturnType<InMemoryCacheMetrics["getHotKeys"]> | null;
+    /** Resets all collected metrics. */
+    resetStats(): void;
+    /**
+     * Subscribes to cache events (`cache.hit`, `cache.miss`, `cache.set`,
+     * `cache.delete`, `cache.clear`, `cache.error`), or to `"*"` for all.
+     */
+    subscribe(eventType: CacheEvent["type"] | "*", handler: CacheEventHandler): CacheEventSubscription;
     healthCheck(): Promise<CacheHealth>;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
+    private applyBatchOperation;
+    /** The namespace scope applied to tag registrations and lookups. */
+    private tagScope;
+    private qualifyPattern;
+    private purgeTagsMatching;
+    private serialize;
+    private deserialize;
 }
 export declare function createCacheService(options: {
     readonly adapter: CacheAdapter;
     readonly config?: CacheConfig;
     readonly keyBuilder?: CacheKeyBuilder;
 }): CacheService;
+export {};
 //# sourceMappingURL=cache.d.ts.map