@zudojs/cache 0.0.1

package/dist/cache.js

@@ -0,0 +1,135 @@
+/**
+ * @zudojs/cache — Cache Service
+ * High-level cache service combining adapter, serializer, key builder, tags, invalidation, locking, and metrics.
+ */
+import { DEFAULT_TTL_MS } from "./constants.js";
+import { DefaultKeyBuilder } from "./key-builder.js";
+import { createCacheStore, DefaultCacheStore } from "./store.js";
+import { createTagStore, InMemoryTagStore } from "./tags.js";
+import { CacheInvalidationManager, createInvalidationManager, } from "./invalidation.js";
+import { CacheLockManager, createLockManager } from "./lock.js";
+import { createCacheMetrics, InMemoryCacheMetrics } from "./metrics.js";
+export class CacheService {
+    store;
+    keyBuilder;
+    tagStore;
+    invalidation;
+    lockManager;
+    metrics;
+    defaultTtl;
+    enabled;
+    constructor(options) {
+        this.enabled = options.config?.enabled ?? true;
+        this.defaultTtl = options.config?.defaultTtl ?? DEFAULT_TTL_MS;
+        this.metrics =
+            options.config?.collectStats !== false ? createCacheMetrics() : null;
+        this.store = createCacheStore({
+            adapter: options.adapter,
+            metrics: this.metrics,
+        });
+        this.keyBuilder =
+            options.keyBuilder ??
+                new DefaultKeyBuilder({
+                    prefix: options.config?.prefix,
+                    separator: options.config?.separator,
+                    namespace: options.config?.namespace,
+                });
+        this.tagStore = createTagStore();
+        this.invalidation = createInvalidationManager({
+            adapter: options.adapter,
+            tagStore: this.tagStore,
+        });
+        this.lockManager = createLockManager();
+    }
+    async get(key, options) {
+        if (!this.enabled)
+            return { hit: false, value: null };
+        return this.store.get(this.keyBuilder.build(key, options));
+    }
+    async set(key, value, options) {
+        if (!this.enabled)
+            return { success: false, key, expiresAt: null };
+        const fullKey = this.keyBuilder.build(key, options);
+        const result = await this.store.set(fullKey, value, {
+            ttl: options?.ttl ?? this.defaultTtl,
+            ...options,
+        });
+        if (options?.tags && options.tags.length > 0)
+            await this.tagStore.add(fullKey, options.tags);
+        return result;
+    }
+    async delete(key, options) {
+        if (!this.enabled)
+            return { deleted: false, key };
+        return this.store.delete(this.keyBuilder.build(key, options));
+    }
+    async has(key, options) {
+        if (!this.enabled)
+            return false;
+        return this.store.has(this.keyBuilder.build(key, options));
+    }
+    async clear(options) {
+        if (!this.enabled)
+            return { cleared: 0 };
+        return this.store.clear(options);
+    }
+    async getOrSet(key, fn, options) {
+        if (!this.enabled)
+            return { value: await fn(), cached: false };
+        if (!options?.forceRefresh) {
+            const cached = await this.get(key, options);
+            if (cached.hit)
+                return { value: cached.value, cached: true };
+        }
+        const value = await fn();
+        await this.set(key, value, options);
+        return { value, cached: false };
+    }
+    async invalidateByTag(tags) {
+        return this.invalidation.invalidateByTag(tags);
+    }
+    async invalidateByPattern(pattern) {
+        return this.invalidation.invalidateByPattern(pattern);
+    }
+    async withLock(key, fn, options) {
+        return this.lockManager.withLock(key, fn, {
+            ttl: options?.ttl,
+            retry: options?.retryAttempts
+                ? { attempts: options.retryAttempts, delay: 100 }
+                : undefined,
+        });
+    }
+    getStats() {
+        return this.metrics?.getStats() ?? null;
+    }
+    async healthCheck() {
+        const start = performance.now();
+        try {
+            await this.store.has("__health__");
+            return {
+                healthy: true,
+                adapter: this.store.name,
+                latencyMs: performance.now() - start,
+                checkedAt: new Date(),
+            };
+        }
+        catch (error) {
+            return {
+                healthy: false,
+                adapter: this.store.name,
+                checkedAt: new Date(),
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    async connect() {
+        await this.store.connect?.();
+    }
+    async disconnect() {
+        await this.store.disconnect?.();
+    }
+}
+export function createCacheService(options) {
+    return new CacheService(options);
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @zudojs/cache — Constants
+ *
+ * Default values, limits, and magic numbers used across the cache package.
+ */
+/** Default time-to-live in milliseconds (5 minutes). */
+export declare const DEFAULT_TTL_MS: number;
+/** Maximum supported TTL (24 hours). */
+export declare const MAX_TTL_MS: number;
+/** Minimum TTL (1 second). */
+export declare const MIN_TTL_MS = 1000;
+/** Default namespace separator. */
+export declare const DEFAULT_SEPARATOR = ":";
+/** Default key prefix. */
+export declare const DEFAULT_PREFIX = "zudojs";
+/** Maximum key length in characters. */
+export declare const MAX_KEY_LENGTH = 256;
+/** Pattern used to validate cache keys. */
+export declare const CACHE_KEY_PATTERN: RegExp;
+/** Default lock TTL in milliseconds (30 seconds). */
+export declare const DEFAULT_LOCK_TTL_MS = 30000;
+/** Default number of retry attempts for lock acquisition. */
+export declare const DEFAULT_LOCK_RETRY_ATTEMPTS = 3;
+/** Default delay between lock retry attempts in milliseconds. */
+export declare const DEFAULT_LOCK_RETRY_DELAY_MS = 100;
+/** Maximum number of latency samples to keep per operation. */
+export declare const MAX_LATENCY_SAMPLES = 1000;
+/** Bucket boundaries for latency histograms (ms). */
+export declare const LATENCY_BUCKETS: readonly [1, 5, 10, 25, 50, 100, 250, 500, 1000];
+/** Default maximum number of entries for the in-memory adapter. */
+export declare const DEFAULT_MAX_ENTRIES = 10000;
+/** Default maximum memory budget in bytes (50 MB). */
+export declare const DEFAULT_MAX_MEMORY_BYTES: number;
+/** Maximum number of keys in a single batch operation. */
+export declare const MAX_BATCH_SIZE = 100;
+/** Glob pattern for matching all keys. */
+export declare const MATCH_ALL_PATTERN = "*";
+/** Regex pattern that matches valid namespace characters. */
+export declare const NAMESPACE_PATTERN: RegExp;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,wDAAwD;AACxD,eAAO,MAAM,cAAc,QAAgB,CAAC;AAE5C,wCAAwC;AACxC,eAAO,MAAM,UAAU,QAAsB,CAAC;AAE9C,8BAA8B;AAC9B,eAAO,MAAM,UAAU,OAAQ,CAAC;AAMhC,mCAAmC;AACnC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,0BAA0B;AAC1B,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC,wCAAwC;AACxC,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,2CAA2C;AAC3C,eAAO,MAAM,iBAAiB,QAAwB,CAAC;AAMvD,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,6DAA6D;AAC7D,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,iEAAiE;AACjE,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAM/C,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC,qDAAqD;AACrD,eAAO,MAAM,eAAe,YAAI,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAU,CAAC;AAMhF,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,sDAAsD;AACtD,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AAMzD,0DAA0D;AAC1D,eAAO,MAAM,cAAc,MAAM,CAAC;AAMlC,0CAA0C;AAC1C,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,QAAuB,CAAC"}

package/dist/constants.js

@@ -0,0 +1,61 @@
+/**
+ * @zudojs/cache — Constants
+ *
+ * Default values, limits, and magic numbers used across the cache package.
+ */
+/* -------------------------------------------------------------------------- */
+/* Default TTL                                                                */
+/* -------------------------------------------------------------------------- */
+/** Default time-to-live in milliseconds (5 minutes). */
+export const DEFAULT_TTL_MS = 5 * 60 * 1000;
+/** Maximum supported TTL (24 hours). */
+export const MAX_TTL_MS = 24 * 60 * 60 * 1000;
+/** Minimum TTL (1 second). */
+export const MIN_TTL_MS = 1_000;
+/* -------------------------------------------------------------------------- */
+/* Key Generation                                                             */
+/* -------------------------------------------------------------------------- */
+/** Default namespace separator. */
+export const DEFAULT_SEPARATOR = ":";
+/** Default key prefix. */
+export const DEFAULT_PREFIX = "zudojs";
+/** Maximum key length in characters. */
+export const MAX_KEY_LENGTH = 256;
+/** Pattern used to validate cache keys. */
+export const CACHE_KEY_PATTERN = /^[a-zA-Z0-9._\-:]+$/;
+/* -------------------------------------------------------------------------- */
+/* Lock Defaults                                                              */
+/* -------------------------------------------------------------------------- */
+/** Default lock TTL in milliseconds (30 seconds). */
+export const DEFAULT_LOCK_TTL_MS = 30_000;
+/** Default number of retry attempts for lock acquisition. */
+export const DEFAULT_LOCK_RETRY_ATTEMPTS = 3;
+/** Default delay between lock retry attempts in milliseconds. */
+export const DEFAULT_LOCK_RETRY_DELAY_MS = 100;
+/* -------------------------------------------------------------------------- */
+/* Metrics                                                                    */
+/* -------------------------------------------------------------------------- */
+/** Maximum number of latency samples to keep per operation. */
+export const MAX_LATENCY_SAMPLES = 1_000;
+/** Bucket boundaries for latency histograms (ms). */
+export const LATENCY_BUCKETS = [1, 5, 10, 25, 50, 100, 250, 500, 1000];
+/* -------------------------------------------------------------------------- */
+/* Memory Adapter                                                             */
+/* -------------------------------------------------------------------------- */
+/** Default maximum number of entries for the in-memory adapter. */
+export const DEFAULT_MAX_ENTRIES = 10_000;
+/** Default maximum memory budget in bytes (50 MB). */
+export const DEFAULT_MAX_MEMORY_BYTES = 50 * 1024 * 1024;
+/* -------------------------------------------------------------------------- */
+/* Batch Operations                                                           */
+/* -------------------------------------------------------------------------- */
+/** Maximum number of keys in a single batch operation. */
+export const MAX_BATCH_SIZE = 100;
+/* -------------------------------------------------------------------------- */
+/* Patterns                                                                   */
+/* -------------------------------------------------------------------------- */
+/** Glob pattern for matching all keys. */
+export const MATCH_ALL_PATTERN = "*";
+/** Regex pattern that matches valid namespace characters. */
+export const NAMESPACE_PATTERN = /^[a-zA-Z0-9._\-]+$/;
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,wDAAwD;AACxD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAE5C,wCAAwC;AACxC,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE9C,8BAA8B;AAC9B,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,CAAC;AAEhC,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,mCAAmC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,0BAA0B;AAC1B,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC,wCAAwC;AACxC,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC,2CAA2C;AAC3C,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEvD,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,qDAAqD;AACrD,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C,6DAA6D;AAC7D,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C,iEAAiE;AACjE,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAE/C,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAEzC,qDAAqD;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAU,CAAC;AAEhF,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,mEAAmE;AACnE,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C,sDAAsD;AACtD,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzD,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAEhF,0CAA0C;AAC1C,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAErC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @zudojs/cache — Error Types
+ *
+ * All cache error types are defined in @zudojs/errors and re-exported here
+ * for convenience. No local error classes are created in this package.
+ */
+export { CacheError, isCacheError, cacheConnectionError, cacheTimeoutError, cacheSerializationError, cacheDeserializationError, cacheInvalidKeyError, cacheAdapterNotConfiguredError, CacheOperation, } from "@zudojs/errors";
+export type { CacheErrorOptions } from "@zudojs/errors";
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,EAC9B,cAAc,GACf,MAAM,gBAAgB,CAAC;AAExB,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/errors.js

@@ -0,0 +1,8 @@
+/**
+ * @zudojs/cache — Error Types
+ *
+ * All cache error types are defined in @zudojs/errors and re-exported here
+ * for convenience. No local error classes are created in this package.
+ */
+export { CacheError, isCacheError, cacheConnectionError, cacheTimeoutError, cacheSerializationError, cacheDeserializationError, cacheInvalidKeyError, cacheAdapterNotConfiguredError, CacheOperation, } from "@zudojs/errors";
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,EAC9B,cAAc,GACf,MAAM,gBAAgB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @zudojs/cache
+ *
+ * Cache abstraction layer with memory adapter, tag-based
+ * invalidation, distributed locking, and metrics.
+ *
+ * @example
+ * ```ts
+ * import { createCacheService, createMemoryCacheAdapter } from "@zudojs/cache";
+ *
+ * const cache = createCacheService({
+ *   adapter: createMemoryCacheAdapter(),
+ *   config: { defaultTtl: 60_000 },
+ * });
+ *
+ * await cache.set("user:123", { name: "Alice" }, { tags: ["users"] });
+ * const result = await cache.get("user:123");
+ * ```
+ */
+export type { CacheKey, CacheNamespace, CacheKeyParts, CacheKeyOptions, CacheValue, SerializableCacheValue, CacheTTL, CacheExpiration, CacheExpirationInfo, CacheSetOptions, CacheGetOptions, CacheDeleteOptions, CacheHasOptions, CacheClearOptions, CacheKeysOptions, CacheGetManyOptions, CacheSetManyOptions, CacheDeleteManyOptions, CacheEntry, CacheEntryMetadata, CacheGetResult, CacheSetResult, CacheDeleteResult, CacheDeleteManyResult, CacheClearResult, CacheStats, CacheAdapter, CacheStore, CacheAdapterFactory, CacheConfig, CacheEventType, CacheTag, CacheTagOptions, CacheTagStore, CacheLockOptions, CacheLock, CacheLockStore, CacheHealth, CacheHealthChecker, CacheSerializer, CacheMetrics, CacheOperation, CacheMiddlewareContext, CacheMiddleware, CacheSerializationOptions, CacheErrorCode, CacheOrComputeOptions, CacheOrComputeResult, CacheBatchOperation, CacheBatchResult, MaybePromise, CacheResult, } from "./types.js";
+export type { BaseCacheEvent, CacheHitEvent, CacheMissEvent, CacheSetEvent, CacheDeleteEvent, CacheClearEvent, CacheErrorEvent, CacheEvent, CacheEventHandler, CacheEventSubscription, } from "./types-events.js";
+export type { CacheKeyBuilder } from "./types-keys.js";
+export { DEFAULT_TTL_MS, MAX_TTL_MS, MIN_TTL_MS, DEFAULT_SEPARATOR, DEFAULT_PREFIX, MAX_KEY_LENGTH, CACHE_KEY_PATTERN, DEFAULT_LOCK_TTL_MS, DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, MAX_LATENCY_SAMPLES, LATENCY_BUCKETS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_MEMORY_BYTES, MAX_BATCH_SIZE, MATCH_ALL_PATTERN, NAMESPACE_PATTERN, } from "./constants.js";
+export { CacheError, isCacheError, cacheConnectionError, cacheTimeoutError, cacheSerializationError, cacheDeserializationError, cacheInvalidKeyError, cacheAdapterNotConfiguredError, } from "./errors.js";
+export type { CacheErrorOptions } from "./errors.js";
+export { JsonCacheSerializer, RawCacheSerializer, defaultSerializer, rawSerializer, getSerializer, } from "./serializer.js";
+export { DefaultKeyBuilder, createKeyBuilder, defaultKeyBuilder, } from "./key-builder.js";
+export { DefaultCacheStore, createCacheStore } from "./store.js";
+export { MemoryCacheAdapter, createMemoryCacheAdapter } from "./memory.js";
+export { InMemoryTagStore, createTagStore } from "./tags.js";
+export { CacheInvalidationManager, createInvalidationManager, } from "./invalidation.js";
+export { InMemoryLockStore, CacheLockManager, createLockManager, defaultLockStore, } from "./lock.js";
+export { InMemoryCacheMetrics, createCacheMetrics } from "./metrics.js";
+export { CacheService, createCacheService } from "./cache.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EACV,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,UAAU,EACV,sBAAsB,EACtB,QAAQ,EACR,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,sBAAsB,EACtB,UAAU,EACV,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,cAAc,EACd,aAAa,EACb,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvD,OAAO,EACL,cAAc,EACd,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGrD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGjE,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG3E,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG7D,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGxE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * @zudojs/cache
+ *
+ * Cache abstraction layer with memory adapter, tag-based
+ * invalidation, distributed locking, and metrics.
+ *
+ * @example
+ * ```ts
+ * import { createCacheService, createMemoryCacheAdapter } from "@zudojs/cache";
+ *
+ * const cache = createCacheService({
+ *   adapter: createMemoryCacheAdapter(),
+ *   config: { defaultTtl: 60_000 },
+ * });
+ *
+ * await cache.set("user:123", { name: "Alice" }, { tags: ["users"] });
+ * const result = await cache.get("user:123");
+ * ```
+ */
+// Constants
+export { DEFAULT_TTL_MS, MAX_TTL_MS, MIN_TTL_MS, DEFAULT_SEPARATOR, DEFAULT_PREFIX, MAX_KEY_LENGTH, CACHE_KEY_PATTERN, DEFAULT_LOCK_TTL_MS, DEFAULT_LOCK_RETRY_ATTEMPTS, DEFAULT_LOCK_RETRY_DELAY_MS, MAX_LATENCY_SAMPLES, LATENCY_BUCKETS, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_MEMORY_BYTES, MAX_BATCH_SIZE, MATCH_ALL_PATTERN, NAMESPACE_PATTERN, } from "./constants.js";
+// Errors (re-exported from @zudojs/errors)
+export { CacheError, isCacheError, cacheConnectionError, cacheTimeoutError, cacheSerializationError, cacheDeserializationError, cacheInvalidKeyError, cacheAdapterNotConfiguredError, } from "./errors.js";
+// Serializer
+export { JsonCacheSerializer, RawCacheSerializer, defaultSerializer, rawSerializer, getSerializer, } from "./serializer.js";
+// Key Builder
+export { DefaultKeyBuilder, createKeyBuilder, defaultKeyBuilder, } from "./key-builder.js";
+// Store
+export { DefaultCacheStore, createCacheStore } from "./store.js";
+// Memory Adapter
+export { MemoryCacheAdapter, createMemoryCacheAdapter } from "./memory.js";
+// Tags
+export { InMemoryTagStore, createTagStore } from "./tags.js";
+// Invalidation
+export { CacheInvalidationManager, createInvalidationManager, } from "./invalidation.js";
+// Lock
+export { InMemoryLockStore, CacheLockManager, createLockManager, defaultLockStore, } from "./lock.js";
+// Metrics
+export { InMemoryCacheMetrics, createCacheMetrics } from "./metrics.js";
+// Cache Service
+export { CacheService, createCacheService } from "./cache.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAyEH,YAAY;AACZ,OAAO,EACL,cAAc,EACd,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,2CAA2C;AAC3C,OAAO,EACL,UAAU,EACV,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,yBAAyB,EACzB,oBAAoB,EACpB,8BAA8B,GAC/B,MAAM,aAAa,CAAC;AAIrB,aAAa;AACb,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,cAAc;AACd,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,QAAQ;AACR,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEjE,iBAAiB;AACjB,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO;AACP,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE7D,eAAe;AACf,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO;AACP,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAEnB,UAAU;AACV,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAExE,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/invalidation.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @zudojs/cache — Invalidation
+ *
+ * Coordinates cache invalidation across tags, patterns, and keys.
+ * Works with both the tag store and the cache adapter to ensure
+ * consistent invalidation.
+ */
+import type { CacheAdapter, CacheClearResult, CacheKey, CacheNamespace, CacheTag, CacheTagStore } from "./types.js";
+/**
+ * Coordinates cache invalidation across multiple strategies:
+ * - Tag-based invalidation
+ * - Pattern-based invalidation
+ * - Direct key invalidation
+ */
+export declare class CacheInvalidationManager {
+    private readonly adapter;
+    private readonly tagStore;
+    constructor(options: {
+        readonly adapter: CacheAdapter;
+        readonly tagStore: CacheTagStore;
+    });
+    /**
+     * Invalidates all cache entries associated with the given tags.
+     * Returns the number of keys that were affected.
+     */
+    invalidateByTag(tags: readonly CacheTag[], options?: {
+        readonly namespace?: CacheNamespace;
+    }): Promise<CacheClearResult>;
+    /**
+     * Invalidates all cache entries matching the given glob pattern.
+     */
+    invalidateByPattern(pattern: string, options?: {
+        readonly namespace?: CacheNamespace;
+    }): Promise<CacheClearResult>;
+    /**
+     * Invalidates all cache entries in the given namespace.
+     */
+    invalidateByNamespace(namespace: CacheNamespace): Promise<CacheClearResult>;
+    /**
+     * Invalidates a specific cache key.
+     */
+    invalidateKey(key: CacheKey, options?: {
+        readonly namespace?: CacheNamespace;
+    }): Promise<{
+        readonly deleted: boolean;
+    }>;
+    /**
+     * Invalidates multiple cache keys at once.
+     */
+    invalidateKeys(keys: readonly CacheKey[], options?: {
+        readonly namespace?: CacheNamespace;
+    }): Promise<{
+        readonly deleted: number;
+        readonly keys: readonly CacheKey[];
+    }>;
+    /**
+     * Clears all entries in the cache adapter and resets the tag store.
+     */
+    flushAll(): Promise<CacheClearResult>;
+}
+/**
+ * Creates a cache invalidation manager.
+ */
+export declare function createInvalidationManager(options: {
+    readonly adapter: CacheAdapter;
+    readonly tagStore: CacheTagStore;
+}): CacheInvalidationManager;
+//# sourceMappingURL=invalidation.d.ts.map

package/dist/invalidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidation.d.ts","sourceRoot":"","sources":["../src/invalidation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,aAAa,EACd,MAAM,YAAY,CAAC;AAOpB;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC,YAAY,OAAO,EAAE;QACnB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;QAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;KAClC,EAGA;IAID;;;OAGG;IACG,eAAe,CACnB,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;KAAE,GAChD,OAAO,CAAC,gBAAgB,CAAC,CAe3B;IAID;;OAEG;IACG,mBAAmB,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;KAAE,GAChD,OAAO,CAAC,gBAAgB,CAAC,CAK3B;IAID;;OAEG;IACG,qBAAqB,CACzB,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,gBAAgB,CAAC,CAE3B;IAID;;OAEG;IACG,aAAa,CACjB,GAAG,EAAE,QAAQ,EACb,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;KAAE,GAChD,OAAO,CAAC;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAGxC;IAID;;OAEG;IACG,cAAc,CAClB,IAAI,EAAE,SAAS,QAAQ,EAAE,EACzB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAA;KAAE,GAChD,OAAO,CAAC;QACT,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;KACpC,CAAC,CAaD;IAID;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAQ1C;CACF;AAMD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE;IACjD,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC,GAAG,wBAAwB,CAE3B"}

package/dist/invalidation.js

@@ -0,0 +1,103 @@
+/**
+ * @zudojs/cache — Invalidation
+ *
+ * Coordinates cache invalidation across tags, patterns, and keys.
+ * Works with both the tag store and the cache adapter to ensure
+ * consistent invalidation.
+ */
+/* -------------------------------------------------------------------------- */
+/* Invalidation Manager                                                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * Coordinates cache invalidation across multiple strategies:
+ * - Tag-based invalidation
+ * - Pattern-based invalidation
+ * - Direct key invalidation
+ */
+export class CacheInvalidationManager {
+    adapter;
+    tagStore;
+    constructor(options) {
+        this.adapter = options.adapter;
+        this.tagStore = options.tagStore;
+    }
+    /* ---- Tag Invalidation ---- */
+    /**
+     * Invalidates all cache entries associated with the given tags.
+     * Returns the number of keys that were affected.
+     */
+    async invalidateByTag(tags, options) {
+        let totalCleared = 0;
+        for (const tag of tags) {
+            const keys = await this.tagStore.getKeys(tag, options);
+            for (const key of keys) {
+                await this.adapter.delete(key, options);
+            }
+            const result = await this.tagStore.invalidate(tag, options);
+            totalCleared += result.cleared;
+        }
+        return { cleared: totalCleared };
+    }
+    /* ---- Pattern Invalidation ---- */
+    /**
+     * Invalidates all cache entries matching the given glob pattern.
+     */
+    async invalidateByPattern(pattern, options) {
+        return this.adapter.clear({
+            ...options,
+            pattern,
+        });
+    }
+    /* ---- Namespace Invalidation ---- */
+    /**
+     * Invalidates all cache entries in the given namespace.
+     */
+    async invalidateByNamespace(namespace) {
+        return this.adapter.clear({ namespace });
+    }
+    /* ---- Direct Key Invalidation ---- */
+    /**
+     * Invalidates a specific cache key.
+     */
+    async invalidateKey(key, options) {
+        const result = await this.adapter.delete(key, options);
+        return { deleted: result.deleted };
+    }
+    /* ---- Bulk Invalidation ---- */
+    /**
+     * Invalidates multiple cache keys at once.
+     */
+    async invalidateKeys(keys, options) {
+        let deleted = 0;
+        const deletedKeys = [];
+        for (const key of keys) {
+            const result = await this.adapter.delete(key, options);
+            if (result.deleted) {
+                deleted++;
+                deletedKeys.push(key);
+            }
+        }
+        return { deleted, keys: deletedKeys };
+    }
+    /* ---- Full Flush ---- */
+    /**
+     * Clears all entries in the cache adapter and resets the tag store.
+     */
+    async flushAll() {
+        const result = await this.adapter.clear();
+        if (typeof this.tagStore.clear === "function") {
+            this.tagStore.clear();
+        }
+        return result;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Factory                                                                    */
+/* -------------------------------------------------------------------------- */
+/**
+ * Creates a cache invalidation manager.
+ */
+export function createInvalidationManager(options) {
+    return new CacheInvalidationManager(options);
+}
+//# sourceMappingURL=invalidation.js.map

package/dist/invalidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidation.js","sourceRoot":"","sources":["../src/invalidation.ts"],"names":[],"mappings":"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"}

package/dist/key-builder.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @zudojs/cache — Key Builder
+ *
+ * Builds fully qualified cache keys from key parts, namespaces,
+ * and prefixes. Ensures keys are well-formed and consistently formatted.
+ */
+import type { CacheKey, CacheKeyOptions, CacheNamespace } from "./types.js";
+import type { CacheKeyBuilder } from "./types-keys.js";
+/**
+ * Default implementation of the `CacheKeyBuilder` contract.
+ *
+ * Keys are built as: `[prefix:][namespace:]key`
+ */
+export declare class DefaultKeyBuilder implements CacheKeyBuilder {
+    private readonly globalPrefix;
+    private readonly globalSeparator;
+    private readonly currentNamespace?;
+    constructor(options?: {
+        readonly prefix?: string;
+        readonly separator?: string;
+        readonly namespace?: CacheNamespace;
+    });
+    build(key: string, options?: CacheKeyOptions): CacheKey;
+    namespace(namespace: CacheNamespace): CacheKeyBuilder;
+}
+/**
+ * Creates a new `DefaultKeyBuilder` with the given options.
+ */
+export declare function createKeyBuilder(options?: {
+    readonly prefix?: string;
+    readonly separator?: string;
+    readonly namespace?: CacheNamespace;
+}): DefaultKeyBuilder;
+/** Default key builder singleton. */
+export declare const defaultKeyBuilder: DefaultKeyBuilder;
+//# sourceMappingURL=key-builder.d.ts.map

package/dist/key-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-builder.d.ts","sourceRoot":"","sources":["../src/key-builder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAavD;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAiB;IAEnD,YAAY,OAAO,CAAC,EAAE;QACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;KACrC,EAIA;IAED,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,QAAQ,CA+BtD;IAED,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,eAAe,CAMpD;CACF;AAMD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;CACrC,GAAG,iBAAiB,CAEpB;AAED,qCAAqC;AACrC,eAAO,MAAM,iBAAiB,mBAA0B,CAAC"}