@zudojs/cache 1.2.3 → 1.2.4

package/README.md

@@ -45,10 +45,27 @@ const { value, cached } = await cache.getOrSet<User>(`user.${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.
+Key parts (prefix, namespace, key) are validated individually: letters,
+digits, `.`, `_`, `-` and `:`, minus the active separator. With the default
+`:` separator that means no `:` inside a key — `prefix:namespace:key` is the
+structure the key builder produces, so a key `a:b` would collide with key `b`
+in namespace `a`, and `clear({ namespace: "a" })` would delete it. Put the
+scope in `namespace` (`cache.get("dashboard", { namespace: tenantId })`), use
+`.` or `-` inside a key (`user.123`, not `user:123`), or, if your keys must
+contain `:` (keys built by another library, say), configure a different
+separator on both the service and the memory adapter:
+
+```typescript
+const cache = createCacheService({
+  adapter: createMemoryCacheAdapter({ separator: "/" }),
+  config: { separator: "/" },
+});
+await cache.set("tenant:kola:dashboard", totals); // zudojs/tenant:kola:dashboard
+```
+
+A rejected key throws a `CacheError` (`ERR_INVALID_INPUT`, status 400) whose
+`operation` names the call that rejected it (`get`, `set`, `lock_acquire`,
+`clear`, …) and whose message explains the separator rule.
 
 ## Features
 

package/dist/cache.d.ts

@@ -14,9 +14,10 @@
  * 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, CacheBatchOperation, CacheBatchResult, CacheConfig, CacheDeleteResult, CacheEvent, CacheEventHandler, CacheEventSubscription, CacheGetResult, CacheHealth, CacheHealthChecker, CacheNamespace, CacheOperation, CacheOrComputeOptions, CacheOrComputeResult, CacheSetResult, CacheStats, CacheTag, CacheTTL } from "./types.js";
+import type { CacheAdapter, CacheBatchOperation, CacheBatchResult, CacheConfig, CacheDeleteResult, CacheEvent, CacheEventHandler, CacheEventSubscription, CacheGetResult, CacheHealth, CacheHealthChecker, CacheNamespace, CacheOrComputeOptions, CacheOrComputeResult, CacheSetResult, CacheStats, CacheTag, CacheTTL } from "./types.js";
 import type { CacheKeyBuilder } from "./types-keys.js";
 import { InMemoryCacheMetrics } from "./metrics.js";
+import { CacheOperation } from "./errors.js";
 /** Options accepted by every namespace-scoped read operation. */
 interface NamespaceOptions {
     readonly namespace?: CacheNamespace;
@@ -44,6 +45,10 @@ export declare class CacheService implements CacheHealthChecker {
         readonly config?: CacheConfig;
         readonly keyBuilder?: CacheKeyBuilder;
     });
+    /**
+     * Reads one entry. `TValue` is an unchecked assertion — it only shapes
+     * the return type; nothing verifies the stored value matches it.
+     */
     get<TValue = unknown>(key: string, options?: NamespaceOptions): Promise<CacheGetResult<TValue>>;
     set<TValue = unknown>(key: string, value: TValue, options?: {
         readonly ttl?: CacheTTL;
@@ -150,7 +155,9 @@ export declare class CacheService implements CacheHealthChecker {
     /**
      * Runs input validation. A rejection is recorded like an adapter failure
      * (`getStats().errors`, `cache.error`) and rethrown: invalid input is a
-     * caller error, so `failSilently` never hides it.
+     * caller error, so `failSilently` never hides it. The key builder does
+     * not know which operation asked for the key, so the rejection is
+     * attributed to `operation` here rather than reported as `unknown`.
      */
     private guardInput;
     private purgeTagsMatching;
@@ -163,4 +170,3 @@ export declare function createCacheService(options: {
     readonly keyBuilder?: CacheKeyBuilder;
 }): CacheService;
 export {};
-//# sourceMappingURL=cache.d.ts.map

package/dist/cache.js

@@ -21,8 +21,8 @@ import { assertValidTag, createTagStore } from "./tags.js";
 import { CacheInvalidationManager, createInvalidationManager, } from "./invalidation.js";
 import { CacheLockManager, createLockManager } from "./lock.js";
 import { createCacheMetrics, InMemoryCacheMetrics } from "./metrics.js";
-import { CacheError, cacheDeserializationError, cacheSerializationError, isCacheError, } from "./errors.js";
-import { createGlobMatcher } from "./utils.js";
+import { CacheError, CacheOperation, cacheDeserializationError, cacheSerializationError, isCacheError, } from "./errors.js";
+import { attachCacheOperation, createGlobMatcher } from "./utils.js";
 export class CacheService {
     store;
     keyBuilder;
@@ -85,10 +85,14 @@ export class CacheService {
         });
         this.lockManager = createLockManager(options.config?.lockStore ? { store: options.config.lockStore } : {});
     }
+    /**
+     * Reads one entry. `TValue` is an unchecked assertion — it only shapes
+     * the return type; nothing verifies the stored value matches it.
+     */
     async get(key, options) {
         if (!this.enabled)
             return { hit: false, value: null };
-        const fullKey = this.buildKey(key, options);
+        const fullKey = this.buildKey(key, options, CacheOperation.GET);
         try {
             const result = await this.store.get(fullKey);
             if (!result.hit || !this.serializer)
@@ -111,9 +115,9 @@ export class CacheService {
     async set(key, value, options) {
         if (!this.enabled)
             return { success: false, key, expiresAt: null };
-        const fullKey = this.buildKey(key, options);
+        const fullKey = this.buildKey(key, options, CacheOperation.SET);
         if (options?.tags)
-            this.validateTags(key, options.tags);
+            this.validateTags(key, options.tags, CacheOperation.SET);
         try {
             const stored = this.serializer ? this.serialize(value) : value;
             const result = await this.store.set(fullKey, stored, {
@@ -145,7 +149,7 @@ export class CacheService {
     async delete(key, options) {
         if (!this.enabled)
             return { deleted: false, key };
-        const fullKey = this.buildKey(key, options);
+        const fullKey = this.buildKey(key, options, CacheOperation.DELETE);
         try {
             const result = await this.store.delete(fullKey);
             await this.tagStore.removeKey?.(fullKey);
@@ -160,7 +164,7 @@ export class CacheService {
     async has(key, options) {
         if (!this.enabled)
             return false;
-        const fullKey = this.buildKey(key, options);
+        const fullKey = this.buildKey(key, options, CacheOperation.HAS);
         try {
             return await this.store.has(fullKey);
         }
@@ -184,7 +188,7 @@ export class CacheService {
         if (options?.pattern !== undefined || options?.namespace !== undefined) {
             // Validation happens outside the failSilently guard: a malformed
             // pattern is programmer error, not an adapter fault.
-            const pattern = this.qualifyPattern(options.pattern ?? "*", options.namespace);
+            const pattern = this.qualifyPattern(options.pattern ?? "*", options.namespace, CacheOperation.CLEAR);
             try {
                 const result = await this.store.clear({ pattern });
                 await this.purgeTagsMatching(pattern);
@@ -214,7 +218,7 @@ export class CacheService {
     async ttl(key, options) {
         if (!this.enabled)
             return undefined;
-        const fullKey = this.buildKey(key, options);
+        const fullKey = this.buildKey(key, options, CacheOperation.TTL);
         try {
             const remaining = await this.store.ttl?.(fullKey);
             return typeof remaining === "number" && Number.isFinite(remaining)
@@ -233,7 +237,7 @@ export class CacheService {
     async expire(key, ttl, options) {
         if (!this.enabled)
             return false;
-        const fullKey = this.buildKey(key, options);
+        const fullKey = this.buildKey(key, options, CacheOperation.EXPIRE);
         try {
             return (await this.store.expire?.(fullKey, ttl)) ?? false;
         }
@@ -246,7 +250,7 @@ export class CacheService {
     async getOrSet(key, fn, options) {
         if (!this.enabled)
             return { value: await fn(), cached: false };
-        const fullKey = this.buildKey(key, options);
+        const fullKey = this.buildKey(key, options, CacheOperation.GET);
         if (!options?.forceRefresh) {
             const cached = await this.get(key, options);
             if (cached.hit)
@@ -278,7 +282,7 @@ export class CacheService {
     async invalidateByTag(tags, options) {
         if (!this.enabled)
             return { cleared: 0 };
-        this.validateTags(tags.join(","), tags);
+        this.validateTags(tags.join(","), tags, CacheOperation.DELETE_MANY);
         try {
             return await this.invalidation.invalidateByTag(tags, this.tagScope(options));
         }
@@ -301,7 +305,7 @@ export class CacheService {
     async invalidateByPattern(pattern, options) {
         if (!this.enabled)
             return { cleared: 0 };
-        const qualified = this.qualifyPattern(pattern, options?.namespace);
+        const qualified = this.qualifyPattern(pattern, options?.namespace, CacheOperation.DELETE_MANY);
         try {
             const result = await this.invalidation.invalidateByPattern(qualified);
             await this.purgeTagsMatching(qualified);
@@ -332,7 +336,7 @@ export class CacheService {
         }
         const lockKey = this.buildKey(key, options?.namespace !== undefined
             ? { namespace: options.namespace }
-            : undefined);
+            : undefined, CacheOperation.LOCK_ACQUIRE);
         return this.lockManager.withLock(lockKey, fn, {
             ...(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
             // `retryAttempts: 0` is honored (single attempt, no retries).
@@ -475,19 +479,19 @@ export class CacheService {
         assertNonEmptyNamespace(namespace);
         return namespace !== undefined ? { namespace } : {};
     }
-    qualifyPattern(pattern, namespace) {
+    qualifyPattern(pattern, namespace, operation) {
         const build = this.keyBuilder.buildPattern?.bind(this.keyBuilder);
         if (!build)
             return pattern;
-        return this.guardInput(pattern, () => build(pattern, namespace !== undefined ? { namespace } : undefined));
+        return this.guardInput(pattern, operation, () => build(pattern, namespace !== undefined ? { namespace } : undefined));
     }
     /** Builds a full key, counting a rejected key in the error stats. */
-    buildKey(key, options) {
-        return this.guardInput(key, () => this.keyBuilder.build(key, options));
+    buildKey(key, options, operation) {
+        return this.guardInput(key, operation, () => this.keyBuilder.build(key, options));
     }
     /** Validates tags, counting a rejected tag in the error stats. */
-    validateTags(key, tags) {
-        this.guardInput(key, () => {
+    validateTags(key, tags, operation) {
+        this.guardInput(key, operation, () => {
             for (const tag of tags)
                 assertValidTag(tag);
         });
@@ -495,15 +499,18 @@ export class CacheService {
     /**
      * Runs input validation. A rejection is recorded like an adapter failure
      * (`getStats().errors`, `cache.error`) and rethrown: invalid input is a
-     * caller error, so `failSilently` never hides it.
+     * caller error, so `failSilently` never hides it. The key builder does
+     * not know which operation asked for the key, so the rejection is
+     * attributed to `operation` here rather than reported as `unknown`.
      */
-    guardInput(key, validate) {
+    guardInput(key, operation, validate) {
         try {
             return validate();
         }
         catch (error) {
-            this.store.recordError(key, error);
-            throw error;
+            const attributed = attachCacheOperation(error, operation);
+            this.store.recordError(key, attributed);
+            throw attributed;
         }
     }
     async purgeTagsMatching(pattern) {
@@ -540,4 +547,3 @@ export class CacheService {
 export function createCacheService(options) {
     return new CacheService(options);
 }
-//# sourceMappingURL=cache.js.map

package/dist/constants.d.ts

@@ -19,18 +19,24 @@ export declare const DEFAULT_PREFIX = "zudojs";
 /** Maximum key length in characters. */
 export declare const MAX_KEY_LENGTH = 256;
 /**
- * Pattern used to validate each individual cache key part (prefix,
- * namespace, and raw key). Deliberately excludes the default separator
- * (`:`) so callers cannot forge namespaced keys (e.g. `build("admin:x")`
- * throws). Parts are additionally checked against the active separator.
+ * Alphabet of one cache key part (prefix, namespace, and raw key): letters,
+ * digits, `.`, `_`, `-` and `:`.
+ *
+ * The *active separator* is rejected separately, so with the default `:`
+ * separator a part can still never contain `:` — `build("admin:x")` would
+ * otherwise be indistinguishable from key `x` in namespace `admin`, and a
+ * namespace-scoped invalidation would reach it. `:` inside a part is only
+ * possible under a different separator
+ * (`createKeyBuilder({ separator: "/" })` gives `zudojs/tenant:1/dashboard`),
+ * where it cannot collide with the scope structure.
  */
 export declare const CACHE_KEY_PATTERN: RegExp;
 /**
  * Pattern used to validate the caller-supplied *glob* segment of a key
  * pattern. It is the key alphabet plus the two glob metacharacters `*` and
  * `?` — nothing else has meaning for the matcher, so anything else is
- * caller error. The separator is excluded so a pattern cannot escape the
- * prefix/namespace scope it is composed into.
+ * caller error. The active separator is rejected separately so a pattern
+ * cannot escape the prefix/namespace scope it is composed into.
  */
 export declare const CACHE_PATTERN_PART_PATTERN: RegExp;
 /** Maximum length of a cache tag. Tags are untrusted map keys. */
@@ -71,4 +77,3 @@ export declare const EXPIRED_PURGE_INTERVAL_MS = 30000;
  * Keeps `set` O(1)-ish for large object graphs at the cost of accuracy.
  */
 export declare const SIZE_ESTIMATE_NODE_BUDGET = 512;
-//# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -25,20 +25,26 @@ export const DEFAULT_PREFIX = "zudojs";
 /** Maximum key length in characters. */
 export const MAX_KEY_LENGTH = 256;
 /**
- * Pattern used to validate each individual cache key part (prefix,
- * namespace, and raw key). Deliberately excludes the default separator
- * (`:`) so callers cannot forge namespaced keys (e.g. `build("admin:x")`
- * throws). Parts are additionally checked against the active separator.
+ * Alphabet of one cache key part (prefix, namespace, and raw key): letters,
+ * digits, `.`, `_`, `-` and `:`.
+ *
+ * The *active separator* is rejected separately, so with the default `:`
+ * separator a part can still never contain `:` — `build("admin:x")` would
+ * otherwise be indistinguishable from key `x` in namespace `admin`, and a
+ * namespace-scoped invalidation would reach it. `:` inside a part is only
+ * possible under a different separator
+ * (`createKeyBuilder({ separator: "/" })` gives `zudojs/tenant:1/dashboard`),
+ * where it cannot collide with the scope structure.
  */
-export const CACHE_KEY_PATTERN = /^[a-zA-Z0-9._\-]+$/;
+export const CACHE_KEY_PATTERN = /^[a-zA-Z0-9._:\-]+$/;
 /**
  * Pattern used to validate the caller-supplied *glob* segment of a key
  * pattern. It is the key alphabet plus the two glob metacharacters `*` and
  * `?` — nothing else has meaning for the matcher, so anything else is
- * caller error. The separator is excluded so a pattern cannot escape the
- * prefix/namespace scope it is composed into.
+ * caller error. The active separator is rejected separately so a pattern
+ * cannot escape the prefix/namespace scope it is composed into.
  */
-export const CACHE_PATTERN_PART_PATTERN = /^[a-zA-Z0-9._\-*?]+$/;
+export const CACHE_PATTERN_PART_PATTERN = /^[a-zA-Z0-9._:\-*?]+$/;
 /** Maximum length of a cache tag. Tags are untrusted map keys. */
 export const MAX_TAG_LENGTH = 128;
 /* -------------------------------------------------------------------------- */
@@ -86,4 +92,3 @@ export const EXPIRED_PURGE_INTERVAL_MS = 30_000;
  * Keeps `set` O(1)-ish for large object graphs at the cost of accuracy.
  */
 export const SIZE_ESTIMATE_NODE_BUDGET = 512;
-//# sourceMappingURL=constants.js.map

package/dist/errors.d.ts

@@ -6,4 +6,3 @@
  */
 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.js

@@ -5,4 +5,3 @@
  * 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/index.d.ts

@@ -33,4 +33,3 @@ export { CacheInvalidationManager, createInvalidationManager, } from "./invalida
 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.js

@@ -40,4 +40,3 @@ export { InMemoryLockStore, CacheLockManager, createLockManager, defaultLockStor
 export { InMemoryCacheMetrics, createCacheMetrics } from "./metrics.js";
 // Cache Service
 export { CacheService, createCacheService } from "./cache.js";
-//# sourceMappingURL=index.js.map

package/dist/invalidation.d.ts

@@ -72,4 +72,3 @@ export declare function createInvalidationManager(options: {
     readonly tagStore: CacheTagStore;
     readonly keyBuilder?: CacheKeyBuilder;
 }): CacheInvalidationManager;
-//# sourceMappingURL=invalidation.d.ts.map

package/dist/invalidation.js

@@ -110,4 +110,3 @@ export class CacheInvalidationManager {
 export function createInvalidationManager(options) {
     return new CacheInvalidationManager(options);
 }
-//# sourceMappingURL=invalidation.js.map

package/dist/key-builder.d.ts

@@ -60,4 +60,3 @@ export declare function createKeyBuilder(options?: {
 }): DefaultKeyBuilder;
 /** Default key builder singleton. */
 export declare const defaultKeyBuilder: DefaultKeyBuilder;
-//# sourceMappingURL=key-builder.d.ts.map

package/dist/key-builder.js

@@ -104,7 +104,15 @@ export class DefaultKeyBuilder {
         });
     }
     validatePart(part, separator) {
-        if (part.includes(separator) || !CACHE_KEY_PATTERN.test(part)) {
+        if (part.includes(separator)) {
+            throw cacheInvalidKeyError(part, `Invalid cache key part "${part}": parts must not contain the ` +
+                `separator "${separator}", which delimits prefix, namespace and ` +
+                `key (a key "a${separator}b" would collide with key "b" in ` +
+                `namespace "a"). Put the scope in the namespace option ` +
+                `(cache.get("b", { namespace: "a" })), use "." or "-" inside ` +
+                `the part, or configure a different separator on the key builder.`);
+        }
+        if (!CACHE_KEY_PATTERN.test(part)) {
             throw cacheInvalidKeyError(part, `Invalid cache key part "${part}": parts must match ${String(CACHE_KEY_PATTERN)} and must not contain the separator "${separator}".`);
         }
     }
@@ -120,4 +128,3 @@ export function createKeyBuilder(options) {
 }
 /** Default key builder singleton. */
 export const defaultKeyBuilder = new DefaultKeyBuilder();
-//# sourceMappingURL=key-builder.js.map

package/dist/lock.d.ts

@@ -61,4 +61,3 @@ export declare function createLockManager(options?: {
  * `CacheService` instances in one process must share locks.
  */
 export declare const defaultLockStore: InMemoryLockStore;
-//# sourceMappingURL=lock.d.ts.map

package/dist/lock.js

@@ -259,4 +259,3 @@ export function createLockManager(options) {
  * `CacheService` instances in one process must share locks.
  */
 export const defaultLockStore = new InMemoryLockStore();
-//# sourceMappingURL=lock.js.map

package/dist/memory.d.ts

@@ -90,4 +90,3 @@ export declare function createMemoryCacheAdapter(options?: {
     readonly defaultTtl?: CacheTTL;
     readonly separator?: string;
 }): MemoryCacheAdapter;
-//# sourceMappingURL=memory.d.ts.map

package/dist/memory.js

@@ -325,4 +325,3 @@ export class MemoryCacheAdapter {
 export function createMemoryCacheAdapter(options) {
     return new MemoryCacheAdapter(options);
 }
-//# sourceMappingURL=memory.js.map

package/dist/metrics.d.ts

@@ -48,4 +48,3 @@ export declare class InMemoryCacheMetrics implements CacheMetrics {
     reset(): void;
 }
 export declare function createCacheMetrics(): InMemoryCacheMetrics;
-//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.js

@@ -138,4 +138,3 @@ function percentile(sorted, p) {
 export function createCacheMetrics() {
     return new InMemoryCacheMetrics();
 }
-//# sourceMappingURL=metrics.js.map

package/dist/serializer.d.ts

@@ -53,4 +53,3 @@ export declare class RawCacheSerializer implements CacheSerializer<unknown, unkn
 export declare const defaultSerializer: JsonCacheSerializer;
 /** Default raw (pass-through) serializer instance. */
 export declare const rawSerializer: RawCacheSerializer;
-//# sourceMappingURL=serializer.d.ts.map

package/dist/serializer.js

@@ -143,4 +143,3 @@ export class RawCacheSerializer {
 export const defaultSerializer = new JsonCacheSerializer();
 /** Default raw (pass-through) serializer instance. */
 export const rawSerializer = new RawCacheSerializer();
-//# sourceMappingURL=serializer.js.map

package/dist/store.d.ts

@@ -55,4 +55,3 @@ export declare function createCacheStore(options: {
     readonly metrics?: CacheMetrics;
     readonly middlewares?: readonly CacheMiddleware[];
 }): DefaultCacheStore;
-//# sourceMappingURL=store.d.ts.map

package/dist/store.js

@@ -246,4 +246,3 @@ export class DefaultCacheStore {
 export function createCacheStore(options) {
     return new DefaultCacheStore(options);
 }
-//# sourceMappingURL=store.js.map

package/dist/tags.d.ts

@@ -54,4 +54,3 @@ export declare class InMemoryTagStore implements CacheTagStore {
  * Creates an in-memory tag store.
  */
 export declare function createTagStore(): InMemoryTagStore;
-//# sourceMappingURL=tags.d.ts.map

package/dist/tags.js

@@ -171,4 +171,3 @@ export class InMemoryTagStore {
 export function createTagStore() {
     return new InMemoryTagStore();
 }
-//# sourceMappingURL=tags.js.map

package/dist/types-adapter.d.ts

@@ -13,6 +13,14 @@ export interface CacheAdapter {
     readonly name: string;
     connect?(): Promise<void>;
     disconnect?(): Promise<void>;
+    /**
+     * Reads one entry.
+     *
+     * `TValue` appears only in the return type, so it is an **unchecked
+     * assertion** by the caller: nothing verifies that the stored value has
+     * that shape. Validate a value that crosses a trust boundary (a shared
+     * cache, a schema that changed between deploys) before relying on it.
+     */
     get<TValue = unknown>(key: CacheKey): Promise<CacheGetResult<TValue>>;
     set<TValue = unknown>(key: CacheKey, value: TValue, options?: CacheSetOptions): Promise<CacheSetResult>;
     delete(key: CacheKey): Promise<CacheDeleteResult>;
@@ -35,4 +43,3 @@ export interface CacheAdapter {
 }
 export interface CacheStore extends CacheAdapter {
 }
-//# sourceMappingURL=types-adapter.d.ts.map

package/dist/types-adapter.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-adapter.js.map

package/dist/types-config.d.ts

@@ -64,4 +64,3 @@ export interface CacheConfig {
  * generic `ErrorCode` values, not these.
  */
 export type CacheErrorCode = "CACHE_DISABLED" | "CACHE_OPERATION_FAILED" | "CACHE_INVALID_TTL" | "CACHE_MIDDLEWARE_RESULT_MISSING" | "CACHE_LOCK_UNAVAILABLE" | "CACHE_LOCK_ACQUIRE_FAILED" | "CACHE_LOCK_LOST";
-//# sourceMappingURL=types-config.d.ts.map

package/dist/types-config.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-config.js.map

package/dist/types-events.d.ts

@@ -35,4 +35,3 @@ export type CacheEventHandler<TEvent extends CacheEvent = CacheEvent> = (event:
 export interface CacheEventSubscription {
     readonly unsubscribe: () => void;
 }
-//# sourceMappingURL=types-events.d.ts.map

package/dist/types-events.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-events.js.map

package/dist/types-health.d.ts

@@ -20,4 +20,3 @@ export interface CacheSerializer<TValue = unknown, TSerialized = unknown> {
 export interface CacheSerializationOptions {
     readonly serializer?: CacheSerializer;
 }
-//# sourceMappingURL=types-health.d.ts.map

package/dist/types-health.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-health.js.map

package/dist/types-keys.d.ts

@@ -16,4 +16,3 @@ export interface CacheKeyBuilder {
      */
     buildPattern?(pattern: string, options?: CacheKeyOptions): string;
 }
-//# sourceMappingURL=types-keys.d.ts.map

package/dist/types-keys.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-keys.js.map

package/dist/types-lock.d.ts

@@ -27,4 +27,3 @@ export interface CacheLockStore {
     /** Releases every held lease. Intended for tests and shutdown. */
     clear?(): void;
 }
-//# sourceMappingURL=types-lock.d.ts.map

package/dist/types-lock.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-lock.js.map

package/dist/types-metrics.d.ts

@@ -16,4 +16,3 @@ export interface CacheMiddlewareContext {
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
 export type CacheMiddleware = (context: CacheMiddlewareContext, next: () => Promise<unknown>) => Promise<unknown>;
-//# sourceMappingURL=types-metrics.d.ts.map

package/dist/types-metrics.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-metrics.js.map

package/dist/types-operations.d.ts

@@ -29,4 +29,3 @@ export interface CacheSetManyOptions {
     readonly ttl?: CacheTTL;
     readonly overwrite?: boolean;
 }
-//# sourceMappingURL=types-operations.d.ts.map

package/dist/types-operations.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-operations.js.map

package/dist/types-results.d.ts

@@ -36,4 +36,3 @@ export interface CacheStats {
     readonly errors: number;
     readonly hitRate: number;
 }
-//# sourceMappingURL=types-results.d.ts.map

package/dist/types-results.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-results.js.map

package/dist/types-tags.d.ts

@@ -30,4 +30,3 @@ export interface CacheTagStore {
      */
     trackedKeys?(): readonly CacheKey[] | Promise<readonly CacheKey[]>;
 }
-//# sourceMappingURL=types-tags.d.ts.map

package/dist/types-tags.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-tags.js.map

package/dist/types-utility.d.ts

@@ -24,4 +24,3 @@ export interface CacheBatchResult {
     readonly result?: unknown;
     readonly error?: unknown;
 }
-//# sourceMappingURL=types-utility.d.ts.map

package/dist/types-utility.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-utility.js.map

package/dist/types-values.d.ts

@@ -16,4 +16,3 @@ export interface CacheEntry<TValue = unknown> {
     readonly tags?: readonly string[];
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-//# sourceMappingURL=types-values.d.ts.map

package/dist/types-values.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types-values.js.map

package/dist/types.d.ts

@@ -10,4 +10,3 @@ export type { CacheHealth, CacheHealthChecker, CacheSerializer, CacheSerializati
 export type { CacheMiddleware, CacheMiddlewareContext, CacheMetrics, CacheOperation, } from "./types-metrics.js";
 export type { CacheConfig, CacheErrorCode } from "./types-config.js";
 export type { CacheBatchOperation, CacheBatchResult, CacheOrComputeOptions, CacheOrComputeResult, MaybePromise, } from "./types-utility.js";
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -5,6 +5,7 @@
  * TTL/pattern validation, and a monotonic clock.
  */
 import type { CacheDeleteManyResult, CacheDeleteResult, CacheKey, CacheTTL } from "./types.js";
+import { CacheOperation } from "./errors.js";
 /**
  * Monotonic milliseconds since process start. Unlike `Date.now()` this is
  * unaffected by NTP steps, VM resume, or manual clock changes, so deadlines
@@ -62,4 +63,11 @@ export declare function deleteManyViaDelete(keys: readonly CacheKey[], deleteOne
  * `CACHE_INVALID_TTL` code otherwise.
  */
 export declare function assertValidTtl(ttl: CacheTTL | undefined): void;
-//# sourceMappingURL=utils.d.ts.map
+/**
+ * Returns `error` with its `operation` filled in when it is a `CacheError`
+ * raised before the operation was known — key, namespace, pattern and tag
+ * validation happens in the key builder, which has no idea whether a
+ * `get` or a `set` asked for the key. Anything else is returned unchanged.
+ * The original stack is kept so the throw site stays visible.
+ */
+export declare function attachCacheOperation(error: unknown, operation: CacheOperation): unknown;

package/dist/utils.js

@@ -5,7 +5,7 @@
  * TTL/pattern validation, and a monotonic clock.
  */
 import { CACHE_PATTERN_PART_PATTERN, DEFAULT_SEPARATOR, MAX_KEY_LENGTH, MAX_TTL_MS, MIN_TTL_MS, } from "./constants.js";
-import { CacheError, cacheInvalidKeyError } from "./errors.js";
+import { CacheError, CacheOperation, cacheInvalidKeyError, isCacheError, } from "./errors.js";
 /* -------------------------------------------------------------------------- */
 /* Monotonic clock                                                            */
 /* -------------------------------------------------------------------------- */
@@ -164,7 +164,12 @@ export function assertValidPatternPart(part, separator) {
     if (part.length === 0) {
         throw cacheInvalidKeyError(part, "Cache pattern must not be empty.");
     }
-    if (part.includes(separator) || !CACHE_PATTERN_PART_PATTERN.test(part)) {
+    if (part.includes(separator)) {
+        throw cacheInvalidKeyError(part, `Invalid cache pattern "${part}": patterns must not contain the ` +
+            `separator "${separator}"; scope a pattern with the namespace ` +
+            `option instead of writing the namespace into it.`);
+    }
+    if (!CACHE_PATTERN_PART_PATTERN.test(part)) {
         throw cacheInvalidKeyError(part, `Invalid cache pattern "${part}": patterns must match ${String(CACHE_PATTERN_PART_PATTERN)} and must not contain the separator "${separator}".`);
     }
 }
@@ -207,4 +212,30 @@ export function assertValidTtl(ttl) {
         });
     }
 }
-//# sourceMappingURL=utils.js.map
+/**
+ * Returns `error` with its `operation` filled in when it is a `CacheError`
+ * raised before the operation was known — key, namespace, pattern and tag
+ * validation happens in the key builder, which has no idea whether a
+ * `get` or a `set` asked for the key. Anything else is returned unchanged.
+ * The original stack is kept so the throw site stays visible.
+ */
+export function attachCacheOperation(error, operation) {
+    if (!isCacheError(error) || error.operation !== CacheOperation.UNKNOWN) {
+        return error;
+    }
+    const attributed = new CacheError(error.message, {
+        code: error.code,
+        category: error.category,
+        severity: error.severity,
+        operation,
+        key: error.key,
+        adapter: error.adapter,
+        statusCode: error.statusCode,
+        expose: error.expose,
+        isOperational: error.isOperational,
+        metadata: error.metadata,
+        cause: error.cause,
+    });
+    attributed.stack = error.stack;
+    return attributed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/cache",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Caching primitives, abstractions, and adapters for the Zudojs framework.",
   "license": "MIT",
   "author": {
@@ -24,10 +24,10 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.4",
-    "@zudojs/errors": "1.3.2",
-    "@zudojs/serialization": "1.2.3",
-    "@zudojs/types": "1.2.0"
+    "@zudojs/constants": "1.2.0",
+    "@zudojs/errors": "1.4.0",
+    "@zudojs/serialization": "1.3.0",
+    "@zudojs/types": "1.3.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",