@zudojs/cache 0.1.0 → 1.0.1

package/dist/types-config.d.ts

@@ -1,21 +1,58 @@
 import type { CacheNamespace } from "./types-keys.js";
 import type { CacheTTL } from "./types-values.js";
-import type { CacheOperation } from "./types-metrics.js";
+import type { CacheMiddleware } from "./types-metrics.js";
+import type { CacheSerializer } from "./types-health.js";
+import type { CacheLockStore } from "./types-lock.js";
 export interface CacheConfig {
     readonly enabled?: boolean;
     readonly defaultTtl?: CacheTTL;
     readonly namespace?: CacheNamespace;
     readonly prefix?: string;
     readonly separator?: string;
+    /**
+     * When true, adapter failures are swallowed and a neutral result is
+     * returned instead of throwing, for every fallible operation:
+     * `get`/`has` report a miss, `set`/`delete` report a no-op,
+     * `clear`/`invalidateByTag`/`invalidateByPattern` report `cleared: 0`,
+     * `ttl` returns `undefined` and `expire` returns `false`.
+     *
+     * Two deliberate exclusions:
+     * - Key/pattern/TTL **validation** errors always throw. A malformed key is
+     *   programmer error, not an adapter fault, and silently ignoring it would
+     *   hide a bug rather than degrade gracefully.
+     * - `withLock` always throws when the lock cannot be acquired or its lease
+     *   is lost. Running a critical section without mutual exclusion is never
+     *   a safe degradation.
+     */
     readonly failSilently?: boolean;
     readonly collectStats?: boolean;
+    /**
+     * Optional serializer applied by CacheService: values are serialized on
+     * set and deserialized on get, so cached values are structural copies.
+     * When omitted, values are stored by reference (memory adapter).
+     */
+    readonly serializer?: CacheSerializer;
+    /**
+     * Middlewares wrapping every adapter operation, applied in order (the
+     * first entry is outermost). Used for tracing, circuit-breaking,
+     * per-operation timeouts, and similar cross-cutting concerns.
+     */
+    readonly middlewares?: readonly CacheMiddleware[];
+    /**
+     * Lock store backing `withLock`. Defaults to a fresh in-process store per
+     * service. Pass a shared store (e.g. the exported `defaultLockStore`, or a
+     * Redis-backed implementation) to share locks across service instances or
+     * processes.
+     */
+    readonly lockStore?: CacheLockStore;
 }
-export type CacheErrorCode = "CACHE_DISABLED" | "CACHE_CONNECTION_FAILED" | "CACHE_TIMEOUT" | "CACHE_SERIALIZATION_FAILED" | "CACHE_DESERIALIZATION_FAILED" | "CACHE_OPERATION_FAILED" | "CACHE_INVALID_KEY" | "CACHE_INVALID_TTL" | "CACHE_ADAPTER_NOT_CONFIGURED" | "CACHE_NOT_SUPPORTED";
-export interface CacheErrorOptions {
-    readonly cause?: unknown;
-    readonly details?: Readonly<Record<string, unknown>>;
-    readonly operation?: CacheOperation;
-    readonly key?: CacheKey;
-}
-import type { CacheKey } from "./types-keys.js";
+/**
+ * Error codes set by errors this package constructs directly. Every member
+ * is produced by some code path in `@zudojs/cache`.
+ *
+ * NOTE: errors created by the re-exported `@zudojs/errors` cache factories
+ * (`cacheConnectionError`, `cacheInvalidKeyError`, …) carry that package's
+ * 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-health.d.ts

@@ -4,6 +4,11 @@ export interface CacheHealth {
     readonly latencyMs?: number;
     readonly checkedAt: Date;
     readonly error?: string;
+    /**
+     * True when the cache is configured `enabled: false`. The check is
+     * reported healthy without touching the adapter.
+     */
+    readonly disabled?: boolean;
 }
 export interface CacheHealthChecker {
     healthCheck(): Promise<CacheHealth>;
@@ -14,7 +19,5 @@ export interface CacheSerializer<TValue = unknown, TSerialized = unknown> {
 }
 export interface CacheSerializationOptions {
     readonly serializer?: CacheSerializer;
-    readonly compress?: boolean;
-    readonly encryption?: boolean;
 }
 //# sourceMappingURL=types-health.d.ts.map

package/dist/types-keys.d.ts

@@ -1,9 +1,5 @@
 export type CacheKey = string;
 export type CacheNamespace = string;
-export interface CacheKeyParts {
-    readonly namespace?: CacheNamespace;
-    readonly key: CacheKey;
-}
 export interface CacheKeyOptions {
     readonly namespace?: CacheNamespace;
     readonly prefix?: string;
@@ -11,5 +7,13 @@ export interface CacheKeyOptions {
 }
 export interface CacheKeyBuilder {
     build(key: string, options?: CacheKeyOptions): CacheKey;
+    /**
+     * Builds a fully-qualified glob pattern for pattern-based operations.
+     *
+     * Prefix and namespace are identity parts, never glob parts, so they are
+     * validated exactly as `build()` validates them. Only the trailing
+     * pattern segment may contain the glob metacharacters `*` and `?`.
+     */
+    buildPattern?(pattern: string, options?: CacheKeyOptions): string;
 }
 //# sourceMappingURL=types-keys.d.ts.map

package/dist/types-lock.d.ts

@@ -2,6 +2,10 @@ import type { CacheNamespace } from "./types-keys.js";
 import type { CacheTTL } from "./types-values.js";
 export interface CacheLockOptions {
     readonly ttl?: CacheTTL;
+    /**
+     * Scopes the lock. Two callers using the same key under different
+     * namespaces do not contend with each other.
+     */
     readonly namespace?: CacheNamespace;
     readonly retry?: {
         readonly attempts: number;
@@ -18,5 +22,9 @@ export interface CacheLock {
 }
 export interface CacheLockStore {
     acquire(key: string, options?: CacheLockOptions): Promise<CacheLock | null>;
+    /** Drops expired leases. Called opportunistically by in-process stores. */
+    sweepExpired?(now?: number): void;
+    /** Releases every held lease. Intended for tests and shutdown. */
+    clear?(): void;
 }
 //# sourceMappingURL=types-lock.d.ts.map

package/dist/types-operations.d.ts

@@ -1,39 +1,32 @@
-import type { CacheNamespace } from "./types-keys.js";
 import type { CacheTTL } from "./types-values.js";
+/**
+ * Adapter-level operation options.
+ *
+ * NOTE: Adapters always receive fully-qualified keys. Namespace and prefix
+ * resolution happens in `CacheService` / the key builder, so adapter-level
+ * options intentionally carry no `namespace` field — every option present
+ * here is honored by the adapter.
+ */
 export interface CacheSetOptions {
     readonly ttl?: CacheTTL;
-    readonly namespace?: CacheNamespace;
     readonly tags?: readonly string[];
+    /**
+     * When `false`, the set is skipped if the key already exists (the result
+     * carries `skipped: true` and `success: false`). Defaults to `true`.
+     */
     readonly overwrite?: boolean;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-export interface CacheGetOptions {
-    readonly namespace?: CacheNamespace;
-}
-export interface CacheDeleteOptions {
-    readonly namespace?: CacheNamespace;
-}
-export interface CacheHasOptions {
-    readonly namespace?: CacheNamespace;
-}
 export interface CacheClearOptions {
-    readonly namespace?: CacheNamespace;
+    /** Glob pattern of fully-qualified keys to clear. Omit to clear everything. */
     readonly pattern?: string;
 }
 export interface CacheKeysOptions {
-    readonly namespace?: CacheNamespace;
     readonly pattern?: string;
     readonly limit?: number;
 }
-export interface CacheGetManyOptions {
-    readonly namespace?: CacheNamespace;
-}
 export interface CacheSetManyOptions {
     readonly ttl?: CacheTTL;
-    readonly namespace?: CacheNamespace;
     readonly overwrite?: boolean;
 }
-export interface CacheDeleteManyOptions {
-    readonly namespace?: CacheNamespace;
-}
 //# sourceMappingURL=types-operations.d.ts.map

package/dist/types-results.d.ts

@@ -3,12 +3,19 @@ import type { CacheEntry } from "./types-values.js";
 export interface CacheGetResult<TValue = unknown> {
     readonly hit: boolean;
     readonly value: TValue | null;
+    /**
+     * The full entry (creation time, expiry, tags, metadata) when the adapter
+     * retains it and the read was a hit. The memory adapter always populates
+     * this on a hit.
+     */
     readonly entry?: CacheEntry<TValue>;
 }
 export interface CacheSetResult {
     readonly success: boolean;
     readonly key: CacheKey;
     readonly expiresAt: Date | null;
+    /** True when the set was skipped because the key exists and `overwrite: false` was passed. */
+    readonly skipped?: boolean;
 }
 export interface CacheDeleteResult {
     readonly deleted: boolean;
@@ -27,7 +34,6 @@ export interface CacheStats {
     readonly sets: number;
     readonly deletes: number;
     readonly errors: number;
-    readonly size?: number;
     readonly hitRate: number;
 }
 //# sourceMappingURL=types-results.d.ts.map

package/dist/types-tags.d.ts

@@ -2,6 +2,11 @@ import type { CacheKey, CacheNamespace } from "./types-keys.js";
 import type { CacheClearResult } from "./types-results.js";
 export type CacheTag = string;
 export interface CacheTagOptions {
+    /**
+     * Scopes the tag. Tags registered under one namespace are invisible to
+     * lookups and invalidations made under another, so one tenant's
+     * `invalidateByTag` can never reach another tenant's entries.
+     */
     readonly namespace?: CacheNamespace;
 }
 export interface CacheTagStore {
@@ -9,5 +14,9 @@ export interface CacheTagStore {
     remove(key: CacheKey, tags: readonly CacheTag[], options?: CacheTagOptions): Promise<void>;
     getKeys(tag: CacheTag, options?: CacheTagOptions): Promise<readonly CacheKey[]>;
     invalidate(tag: CacheTag, options?: CacheTagOptions): Promise<CacheClearResult>;
+    /** Removes all tag mappings for a key, across every namespace. */
+    removeKey?(key: CacheKey): void;
+    /** Removes all tag mappings. */
+    clear?(): void;
 }
 //# sourceMappingURL=types-tags.d.ts.map

package/dist/types-utility.d.ts

@@ -1,31 +1,27 @@
-import type { CacheKey } from "./types-keys.js";
+import type { CacheKey, CacheNamespace } from "./types-keys.js";
 import type { MaybePromise as BaseMaybePromise } from "@zudojs/types";
-import type { CacheDeleteOptions, CacheGetOptions, CacheSetOptions } from "./types-operations.js";
+import type { CacheSetOptions } from "./types-operations.js";
 export type { BaseMaybePromise as MaybePromise };
 export interface CacheOrComputeOptions extends CacheSetOptions {
+    readonly namespace?: CacheNamespace;
     readonly forceRefresh?: boolean;
 }
 export interface CacheOrComputeResult<TValue> {
     readonly value: TValue;
     readonly cached: boolean;
 }
+/** A single operation in a `CacheService.batch()` call. */
 export interface CacheBatchOperation {
     readonly type: "get" | "set" | "delete";
     readonly key: CacheKey;
     readonly value?: unknown;
-    readonly options?: CacheGetOptions | CacheSetOptions | CacheDeleteOptions;
+    readonly options?: CacheSetOptions;
 }
+/** The outcome of one `CacheBatchOperation`, in submission order. */
 export interface CacheBatchResult {
     readonly operation: CacheBatchOperation;
     readonly success: boolean;
     readonly result?: unknown;
     readonly error?: unknown;
 }
-export type CacheResult<TValue> = {
-    readonly success: true;
-    readonly value: TValue;
-} | {
-    readonly success: false;
-    readonly error: unknown;
-};
 //# sourceMappingURL=types-utility.d.ts.map

package/dist/types-values.d.ts

@@ -1,12 +1,13 @@
 import type { CacheKey } from "./types-keys.js";
-export type CacheValue = string | number | boolean | null | Record<string, unknown> | readonly unknown[];
-export type SerializableCacheValue = CacheValue;
-export type CacheTTL = number;
-export type CacheExpiration = CacheTTL | null | undefined;
-export interface CacheExpirationInfo {
-    readonly ttl: number | null;
-    readonly expiresAt: Date | null;
-}
+/**
+ * Time-to-live in milliseconds. `null` means the entry never expires.
+ */
+export type CacheTTL = number | null;
+export type CacheExpiration = CacheTTL | undefined;
+/**
+ * A cached entry with its metadata, as returned on `CacheGetResult.entry`
+ * by adapters that retain per-entry metadata (the memory adapter does).
+ */
 export interface CacheEntry<TValue = unknown> {
     readonly key: CacheKey;
     readonly value: TValue;
@@ -15,10 +16,4 @@ export interface CacheEntry<TValue = unknown> {
     readonly tags?: readonly string[];
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-export interface CacheEntryMetadata {
-    readonly createdAt?: Date;
-    readonly expiresAt?: Date | null;
-    readonly tags?: readonly string[];
-    readonly metadata?: Readonly<Record<string, unknown>>;
-}
 //# sourceMappingURL=types-values.d.ts.map

package/dist/types.d.ts

@@ -1,13 +1,13 @@
-export type { CacheKey, CacheKeyOptions, CacheKeyParts, CacheNamespace, } from "./types-keys.js";
-export type { CacheExpiration, CacheExpirationInfo, CacheEntry, CacheEntryMetadata, CacheTTL, CacheValue, SerializableCacheValue, } from "./types-values.js";
-export type { CacheClearOptions, CacheDeleteManyOptions, CacheDeleteOptions, CacheGetManyOptions, CacheGetOptions, CacheHasOptions, CacheKeysOptions, CacheSetManyOptions, CacheSetOptions, } from "./types-operations.js";
+export type { CacheKey, CacheKeyOptions, CacheNamespace, } from "./types-keys.js";
+export type { CacheExpiration, CacheEntry, CacheTTL } from "./types-values.js";
+export type { CacheClearOptions, CacheKeysOptions, CacheSetManyOptions, CacheSetOptions, } from "./types-operations.js";
 export type { CacheClearResult, CacheDeleteManyResult, CacheDeleteResult, CacheGetResult, CacheSetResult, CacheStats, } from "./types-results.js";
-export type { CacheAdapter, CacheAdapterFactory, CacheStore, } from "./types-adapter.js";
+export type { CacheAdapter, CacheStore } from "./types-adapter.js";
 export type { CacheClearEvent, CacheDeleteEvent, CacheErrorEvent, CacheEvent, CacheEventHandler, CacheEventSubscription, CacheEventType, CacheHitEvent, CacheMissEvent, CacheSetEvent, } from "./types-events.js";
 export type { CacheTag, CacheTagOptions, CacheTagStore } from "./types-tags.js";
 export type { CacheLock, CacheLockOptions, CacheLockStore, } from "./types-lock.js";
 export type { CacheHealth, CacheHealthChecker, CacheSerializer, CacheSerializationOptions, } from "./types-health.js";
 export type { CacheMiddleware, CacheMiddlewareContext, CacheMetrics, CacheOperation, } from "./types-metrics.js";
-export type { CacheConfig, CacheErrorCode, CacheErrorOptions, } from "./types-config.js";
-export type { CacheBatchOperation, CacheBatchResult, CacheOrComputeOptions, CacheOrComputeResult, CacheResult, MaybePromise, } from "./types-utility.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/utils.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @zudojs/cache — Internal Utilities
+ *
+ * Shared helpers: glob matching, sequential delete-many fallback,
+ * TTL/pattern validation, and a monotonic clock.
+ */
+import type { CacheDeleteManyResult, CacheDeleteResult, CacheKey, CacheTTL } from "./types.js";
+/**
+ * Monotonic milliseconds since process start. Unlike `Date.now()` this is
+ * unaffected by NTP steps, VM resume, or manual clock changes, so deadlines
+ * computed from it cannot be extended or collapsed by a wall-clock jump.
+ *
+ * Use `wallClockFor()` to convert a monotonic deadline back into a `Date`
+ * for human-facing fields.
+ */
+export declare function monotonicNow(): number;
+/** Converts a monotonic timestamp into an approximate wall-clock `Date`. */
+export declare function wallClockFor(monotonicMs: number): Date;
+/** A compiled glob matcher. */
+export type GlobMatcher = (value: string) => boolean;
+/**
+ * Compiles a glob pattern into a linear-time matcher.
+ *
+ * Semantics (deliberately segment-aware, so a wildcard cannot escape the
+ * scope it was written for):
+ * - `*` matches any run of characters **within a single key segment**; it
+ *   never crosses the separator. `zudojs:*` therefore matches `zudojs:a`
+ *   but not `zudojs:tenant:a`.
+ * - `?` matches exactly one character within a segment.
+ * - `**` as a whole segment matches zero or more whole segments, so
+ *   `zudojs:**` matches every key under the `zudojs` prefix.
+ *
+ * The pattern is length-bounded (see `assertValidPattern`) and star runs are
+ * collapsed, so pathological patterns cannot cause catastrophic backtracking.
+ */
+export declare function createGlobMatcher(pattern: string, options?: {
+    readonly separator?: string;
+}): GlobMatcher;
+/**
+ * Validates a glob pattern before it is compiled or composed into a key
+ * pattern. Patterns are untrusted input on every pattern-based entry point,
+ * so they are bounded in length and restricted to the key alphabet plus the
+ * glob metacharacters and the separator.
+ */
+export declare function assertValidPattern(pattern: string): void;
+/**
+ * Validates a single pattern segment supplied by a caller (the part that is
+ * appended after prefix/namespace). Only the key alphabet plus `*` and `?`
+ * have meaning; anything else is caller error.
+ */
+export declare function assertValidPatternPart(part: string, separator: string): void;
+/**
+ * Deletes many keys by calling a single-key delete function sequentially.
+ * Shared fallback used by the memory adapter, the store, and the
+ * invalidation manager.
+ */
+export declare function deleteManyViaDelete(keys: readonly CacheKey[], deleteOne: (key: CacheKey) => Promise<CacheDeleteResult>): Promise<CacheDeleteManyResult>;
+/**
+ * Validates a TTL value. `null` means "never expires" and `undefined`
+ * means "use the default"; both are valid. Finite numbers must be within
+ * [MIN_TTL_MS, MAX_TTL_MS]. Throws a CacheError with the
+ * `CACHE_INVALID_TTL` code otherwise.
+ */
+export declare function assertValidTtl(ttl: CacheTTL | undefined): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,210 @@
+/**
+ * @zudojs/cache — Internal Utilities
+ *
+ * Shared helpers: glob matching, sequential delete-many fallback,
+ * 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";
+/* -------------------------------------------------------------------------- */
+/* Monotonic clock                                                            */
+/* -------------------------------------------------------------------------- */
+/**
+ * Monotonic milliseconds since process start. Unlike `Date.now()` this is
+ * unaffected by NTP steps, VM resume, or manual clock changes, so deadlines
+ * computed from it cannot be extended or collapsed by a wall-clock jump.
+ *
+ * Use `wallClockFor()` to convert a monotonic deadline back into a `Date`
+ * for human-facing fields.
+ */
+export function monotonicNow() {
+    return performance.now();
+}
+/** Converts a monotonic timestamp into an approximate wall-clock `Date`. */
+export function wallClockFor(monotonicMs) {
+    return new Date(performance.timeOrigin + monotonicMs);
+}
+/**
+ * Splits one pattern segment into tokens, collapsing runs of `*` into a
+ * single star token. Collapsing is what makes matching cheap: without it a
+ * pattern of *n* consecutive stars is a catastrophic-backtracking hazard.
+ */
+function tokenizeSegment(segment) {
+    const tokens = [];
+    for (const char of segment) {
+        if (char === "*") {
+            if (tokens[tokens.length - 1]?.kind === "star")
+                continue;
+            tokens.push({ kind: "star" });
+        }
+        else if (char === "?") {
+            tokens.push({ kind: "single" });
+        }
+        else {
+            tokens.push({ kind: "literal", char });
+        }
+    }
+    return tokens;
+}
+/**
+ * Classic linear wildcard matcher (greedy with single-star backtracking).
+ * Runs in O(pattern × value) worst case and O(value) in practice — it can
+ * never backtrack exponentially.
+ */
+function matchSegment(tokens, value) {
+    let ti = 0;
+    let vi = 0;
+    let starTi = -1;
+    let starVi = 0;
+    while (vi < value.length) {
+        const token = tokens[ti];
+        if (token !== undefined &&
+            ((token.kind === "literal" && token.char === value[vi]) ||
+                token.kind === "single")) {
+            ti++;
+            vi++;
+            continue;
+        }
+        if (token !== undefined && token.kind === "star") {
+            starTi = ti;
+            starVi = vi;
+            ti++;
+            continue;
+        }
+        if (starTi >= 0) {
+            starVi++;
+            vi = starVi;
+            ti = starTi + 1;
+            continue;
+        }
+        return false;
+    }
+    while (tokens[ti]?.kind === "star")
+        ti++;
+    return ti === tokens.length;
+}
+/**
+ * Compiles a glob pattern into a linear-time matcher.
+ *
+ * Semantics (deliberately segment-aware, so a wildcard cannot escape the
+ * scope it was written for):
+ * - `*` matches any run of characters **within a single key segment**; it
+ *   never crosses the separator. `zudojs:*` therefore matches `zudojs:a`
+ *   but not `zudojs:tenant:a`.
+ * - `?` matches exactly one character within a segment.
+ * - `**` as a whole segment matches zero or more whole segments, so
+ *   `zudojs:**` matches every key under the `zudojs` prefix.
+ *
+ * The pattern is length-bounded (see `assertValidPattern`) and star runs are
+ * collapsed, so pathological patterns cannot cause catastrophic backtracking.
+ */
+export function createGlobMatcher(pattern, options) {
+    assertValidPattern(pattern);
+    const separator = options?.separator ?? DEFAULT_SEPARATOR;
+    const rawSegments = pattern.split(separator);
+    const compiled = rawSegments.map((segment) => segment === "**"
+        ? "globstar"
+        : { tokens: tokenizeSegment(segment) });
+    return (value) => {
+        const valueSegments = value.split(separator);
+        // Two-pointer match at the segment level: `**` behaves as a star over
+        // whole segments, using the same linear greedy algorithm.
+        let pi = 0;
+        let vi = 0;
+        let starPi = -1;
+        let starVi = 0;
+        while (vi < valueSegments.length) {
+            const part = compiled[pi];
+            if (part !== undefined &&
+                part !== "globstar" &&
+                matchSegment(part.tokens, valueSegments[vi])) {
+                pi++;
+                vi++;
+                continue;
+            }
+            if (part === "globstar") {
+                starPi = pi;
+                starVi = vi;
+                pi++;
+                continue;
+            }
+            if (starPi >= 0) {
+                starVi++;
+                vi = starVi;
+                pi = starPi + 1;
+                continue;
+            }
+            return false;
+        }
+        while (compiled[pi] === "globstar")
+            pi++;
+        return pi === compiled.length;
+    };
+}
+/**
+ * Validates a glob pattern before it is compiled or composed into a key
+ * pattern. Patterns are untrusted input on every pattern-based entry point,
+ * so they are bounded in length and restricted to the key alphabet plus the
+ * glob metacharacters and the separator.
+ */
+export function assertValidPattern(pattern) {
+    if (pattern.length === 0) {
+        throw cacheInvalidKeyError(pattern, "Cache pattern must not be empty.");
+    }
+    if (pattern.length > MAX_KEY_LENGTH) {
+        throw cacheInvalidKeyError(pattern, `Cache pattern exceeds maximum length of ${MAX_KEY_LENGTH} characters.`);
+    }
+}
+/**
+ * Validates a single pattern segment supplied by a caller (the part that is
+ * appended after prefix/namespace). Only the key alphabet plus `*` and `?`
+ * have meaning; anything else is caller error.
+ */
+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)) {
+        throw cacheInvalidKeyError(part, `Invalid cache pattern "${part}": patterns must match ${String(CACHE_PATTERN_PART_PATTERN)} and must not contain the separator "${separator}".`);
+    }
+}
+/* -------------------------------------------------------------------------- */
+/* Misc                                                                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * Deletes many keys by calling a single-key delete function sequentially.
+ * Shared fallback used by the memory adapter, the store, and the
+ * invalidation manager.
+ */
+export async function deleteManyViaDelete(keys, deleteOne) {
+    let deleted = 0;
+    const deletedKeys = [];
+    for (const key of keys) {
+        const result = await deleteOne(key);
+        if (result.deleted) {
+            deleted++;
+            deletedKeys.push(key);
+        }
+    }
+    return { deleted, keys: deletedKeys };
+}
+/**
+ * Validates a TTL value. `null` means "never expires" and `undefined`
+ * means "use the default"; both are valid. Finite numbers must be within
+ * [MIN_TTL_MS, MAX_TTL_MS]. Throws a CacheError with the
+ * `CACHE_INVALID_TTL` code otherwise.
+ */
+export function assertValidTtl(ttl) {
+    if (ttl === null || ttl === undefined)
+        return;
+    if (!Number.isFinite(ttl) || ttl < MIN_TTL_MS || ttl > MAX_TTL_MS) {
+        const code = "CACHE_INVALID_TTL";
+        throw new CacheError(`Invalid cache TTL: ${ttl}. TTL must be between ${MIN_TTL_MS} and ${MAX_TTL_MS} ms, or null for no expiry.`, {
+            code,
+            statusCode: 400,
+            expose: true,
+            metadata: { ttl },
+        });
+    }
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/cache",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Caching primitives, abstractions, and adapters for the Zudojs framework.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -14,19 +18,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "dependencies": {
-    "@zudojs/errors": "0.1.0",
-    "@zudojs/types": "0.1.0",
-    "@zudojs/serialization": "0.1.0"
+    "@zudojs/errors": "1.0.1",
+    "@zudojs/types": "1.0.0",
+    "@zudojs/serialization": "1.0.1"
   },
   "devDependencies": {
     "typescript": "7.0.2",
@@ -46,8 +46,19 @@
     "tags"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/cache"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}