@zudojs/cache 1.1.1 → 1.2.0

package/README.md

@@ -80,10 +80,36 @@ 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.
 
-An empty-string namespace is rejected with `CACHE_INVALID_KEY`, in the config
-and per call. A tenant id that failed to resolve to `""` can therefore never
-fall through to the unscoped global keyspace. Omit `namespace` to use that
-keyspace deliberately.
+An empty-string namespace is rejected, in the config and per call. A tenant id
+that failed to resolve to `""` can therefore never fall through to the unscoped
+global keyspace. Omit `namespace` to use that keyspace deliberately.
+
+## Invalid input
+
+A key, namespace, pattern or tag that fails validation throws a `CacheError`
+whose `code` is `ErrorCode.INVALID_INPUT` from `@zudojs/errors` — the string
+`"ERR_INVALID_INPUT"`. (Earlier docs named this `CACHE_INVALID_KEY`; no such
+code has ever been thrown.) An invalid TTL uses its own code,
+`"CACHE_INVALID_TTL"`.
+
+```typescript
+import { ErrorCode } from "@zudojs/errors";
+
+try {
+  await cache.get("");
+} catch (error) {
+  if (error instanceof CacheError && error.code === ErrorCode.INVALID_INPUT) {
+    // reject the request: the key came from the caller
+  }
+}
+```
+
+Invalid input is a caller error, so `failSilently` never hides it. Each
+rejection counts in `getStats().errors` and emits `cache.error`, exactly like
+an invalid TTL or an adapter failure.
+
+Since 1.2.0 an invalid tag (`tags: [""]`) is `ERR_INVALID_INPUT` too; it used
+to be `CACHE_OPERATION_FAILED`, which reads as an adapter fault.
 
 ## Tags across instances
 
@@ -116,6 +142,7 @@ const subscription = cache.subscribe("cache.miss", (event) => {
 });
 
 cache.getStats(); // { hits, misses, sets, deletes, errors, hitRate }
+await cache.ttl("user.1"); // remaining whole milliseconds, rounded down
 cache.getLatencyStats(CacheOperation.GET); // p50 / p95 / p99
 cache.getHotKeys(10);
 await cache.size();

package/dist/cache.d.ts

@@ -68,7 +68,10 @@ export declare class CacheService implements CacheHealthChecker {
     }): Promise<{
         readonly cleared: number;
     }>;
-    /** Remaining TTL for a key (undefined = missing, null = never expires). */
+    /**
+     * Remaining TTL for a key in whole milliseconds, rounded down
+     * (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>;
@@ -140,6 +143,16 @@ export declare class CacheService implements CacheHealthChecker {
     /** The namespace scope applied to tag registrations and lookups. */
     private tagScope;
     private qualifyPattern;
+    /** Builds a full key, counting a rejected key in the error stats. */
+    private buildKey;
+    /** Validates tags, counting a rejected tag in the error stats. */
+    private validateTags;
+    /**
+     * 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.
+     */
+    private guardInput;
     private purgeTagsMatching;
     private serialize;
     private deserialize;

package/dist/cache.js

@@ -88,7 +88,7 @@ export class CacheService {
     async get(key, options) {
         if (!this.enabled)
             return { hit: false, value: null };
-        const fullKey = this.keyBuilder.build(key, options);
+        const fullKey = this.buildKey(key, options);
         try {
             const result = await this.store.get(fullKey);
             if (!result.hit || !this.serializer)
@@ -111,10 +111,9 @@ export class CacheService {
     async set(key, value, options) {
         if (!this.enabled)
             return { success: false, key, expiresAt: null };
-        const fullKey = this.keyBuilder.build(key, options);
+        const fullKey = this.buildKey(key, options);
         if (options?.tags)
-            for (const tag of options.tags)
-                assertValidTag(tag);
+            this.validateTags(key, options.tags);
         try {
             const stored = this.serializer ? this.serialize(value) : value;
             const result = await this.store.set(fullKey, stored, {
@@ -146,7 +145,7 @@ export class CacheService {
     async delete(key, options) {
         if (!this.enabled)
             return { deleted: false, key };
-        const fullKey = this.keyBuilder.build(key, options);
+        const fullKey = this.buildKey(key, options);
         try {
             const result = await this.store.delete(fullKey);
             await this.tagStore.removeKey?.(fullKey);
@@ -161,7 +160,7 @@ export class CacheService {
     async has(key, options) {
         if (!this.enabled)
             return false;
-        const fullKey = this.keyBuilder.build(key, options);
+        const fullKey = this.buildKey(key, options);
         try {
             return await this.store.has(fullKey);
         }
@@ -208,13 +207,19 @@ export class CacheService {
             throw error;
         }
     }
-    /** Remaining TTL for a key (undefined = missing, null = never expires). */
+    /**
+     * Remaining TTL for a key in whole milliseconds, rounded down
+     * (undefined = missing, null = never expires).
+     */
     async ttl(key, options) {
         if (!this.enabled)
             return undefined;
-        const fullKey = this.keyBuilder.build(key, options);
+        const fullKey = this.buildKey(key, options);
         try {
-            return await this.store.ttl?.(fullKey);
+            const remaining = await this.store.ttl?.(fullKey);
+            return typeof remaining === "number" && Number.isFinite(remaining)
+                ? Math.max(0, Math.floor(remaining))
+                : remaining;
         }
         catch (error) {
             if (this.failSilently)
@@ -226,7 +231,7 @@ export class CacheService {
     async expire(key, ttl, options) {
         if (!this.enabled)
             return false;
-        const fullKey = this.keyBuilder.build(key, options);
+        const fullKey = this.buildKey(key, options);
         try {
             return (await this.store.expire?.(fullKey, ttl)) ?? false;
         }
@@ -239,7 +244,7 @@ export class CacheService {
     async getOrSet(key, fn, options) {
         if (!this.enabled)
             return { value: await fn(), cached: false };
-        const fullKey = this.keyBuilder.build(key, options);
+        const fullKey = this.buildKey(key, options);
         if (!options?.forceRefresh) {
             const cached = await this.get(key, options);
             if (cached.hit)
@@ -271,8 +276,7 @@ export class CacheService {
     async invalidateByTag(tags, options) {
         if (!this.enabled)
             return { cleared: 0 };
-        for (const tag of tags)
-            assertValidTag(tag);
+        this.validateTags(tags.join(","), tags);
         try {
             return await this.invalidation.invalidateByTag(tags, this.tagScope(options));
         }
@@ -324,7 +328,7 @@ export class CacheService {
             const code = "CACHE_DISABLED";
             throw new CacheError(`Cannot acquire lock "${key}": the cache is disabled.`, { code, statusCode: 503 });
         }
-        const lockKey = this.keyBuilder.build(key, options?.namespace !== undefined
+        const lockKey = this.buildKey(key, options?.namespace !== undefined
             ? { namespace: options.namespace }
             : undefined);
         return this.lockManager.withLock(lockKey, fn, {
@@ -470,10 +474,35 @@ export class CacheService {
         return namespace !== undefined ? { namespace } : {};
     }
     qualifyPattern(pattern, namespace) {
-        if (this.keyBuilder.buildPattern) {
-            return this.keyBuilder.buildPattern(pattern, namespace !== undefined ? { namespace } : undefined);
+        const build = this.keyBuilder.buildPattern?.bind(this.keyBuilder);
+        if (!build)
+            return pattern;
+        return this.guardInput(pattern, () => 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));
+    }
+    /** Validates tags, counting a rejected tag in the error stats. */
+    validateTags(key, tags) {
+        this.guardInput(key, () => {
+            for (const tag of tags)
+                assertValidTag(tag);
+        });
+    }
+    /**
+     * 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.
+     */
+    guardInput(key, validate) {
+        try {
+            return validate();
+        }
+        catch (error) {
+            this.store.recordError(key, error);
+            throw error;
         }
-        return pattern;
     }
     async purgeTagsMatching(pattern) {
         const store = this.tagStore;

package/dist/key-builder.d.ts

@@ -18,7 +18,8 @@ import type { CacheKeyBuilder } from "./types-keys.js";
  * namespace is either absent (`undefined`) or a valid identity part.
  *
  * @param namespace - The namespace to check.
- * @throws {CacheError} `CACHE_INVALID_KEY` when `namespace` is `""`.
+ * @throws {CacheError} `ERR_INVALID_INPUT` (`ErrorCode.INVALID_INPUT`) when
+ *   `namespace` is `""`.
  */
 export declare function assertNonEmptyNamespace(namespace: CacheNamespace | undefined): void;
 /**

package/dist/key-builder.js

@@ -19,7 +19,8 @@ import { assertValidPatternPart } from "./utils.js";
  * namespace is either absent (`undefined`) or a valid identity part.
  *
  * @param namespace - The namespace to check.
- * @throws {CacheError} `CACHE_INVALID_KEY` when `namespace` is `""`.
+ * @throws {CacheError} `ERR_INVALID_INPUT` (`ErrorCode.INVALID_INPUT`) when
+ *   `namespace` is `""`.
  */
 export function assertNonEmptyNamespace(namespace) {
     if (namespace === "") {

package/dist/memory.js

@@ -239,7 +239,9 @@ export class MemoryCacheAdapter {
         }
         if (entry.expiresAt === null)
             return null;
-        return entry.expiresAt - monotonicNow();
+        // Whole milliseconds, rounded down: the monotonic clock is fractional,
+        // so a TTL of 10000 read back straight after `set` was 9999.52….
+        return Math.max(0, Math.floor(entry.expiresAt - monotonicNow()));
     }
     async expire(key, ttl) {
         assertValidTtl(ttl);

package/dist/store.d.ts

@@ -33,6 +33,12 @@ export declare class DefaultCacheStore implements CacheStore {
     /** Number of live entries, when the underlying adapter can report it. */
     size(): Promise<number | undefined>;
     subscribe(eventType: CacheEvent["type"] | "*", handler: CacheEventHandler): CacheEventSubscription;
+    /**
+     * Records an error raised before any adapter call — a rejected key, tag or
+     * pattern — so `getStats().errors` and `cache.error` cover input
+     * validation the way they already covered a rejected TTL.
+     */
+    recordError(key: string, error: unknown): void;
     private emit;
     private recordGetOutcome;
     private executeWithMiddleware;

package/dist/store.js

@@ -119,6 +119,15 @@ export class DefaultCacheStore {
             },
         };
     }
+    /**
+     * Records an error raised before any adapter call — a rejected key, tag or
+     * pattern — so `getStats().errors` and `cache.error` cover input
+     * validation the way they already covered a rejected TTL.
+     */
+    recordError(key, error) {
+        this.metrics?.incrementError(key);
+        this.emit({ type: "cache.error", key, occurredAt: new Date(), error });
+    }
     emit(event) {
         const specific = this.handlers.get(event.type);
         const wildcard = this.handlers.get("*");

package/dist/tags.js

@@ -15,6 +15,7 @@
  * until `invalidateByTag`/`removeKey`/`clear` touches them, and
  * invalidation tolerates keys that no longer exist in the cache.
  */
+import { ErrorCode } from "@zudojs/errors";
 import { MAX_TAG_LENGTH } from "./constants.js";
 import { CacheError } from "./errors.js";
 /** Separates the namespace from the tag in the internal map key. */
@@ -33,13 +34,13 @@ function scopedTag(tag, options) {
 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",
+            code: ErrorCode.INVALID_INPUT,
             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 });
+        throw new CacheError(`Invalid cache tag: tags must be at most ${MAX_TAG_LENGTH} characters and must not contain NUL.`, { code: ErrorCode.INVALID_INPUT, statusCode: 400, expose: true });
     }
 }
 /* -------------------------------------------------------------------------- */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/cache",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Caching primitives, abstractions, and adapters for the Zudojs framework.",
   "license": "MIT",
   "author": {
@@ -24,14 +24,14 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.1",
-    "@zudojs/errors": "1.2.0",
-    "@zudojs/serialization": "1.1.1",
-    "@zudojs/types": "1.1.1"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/serialization": "1.2.0",
+    "@zudojs/types": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -46,7 +46,7 @@
     "memory",
     "tags"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-cache",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },