actor-ts 0.9.0

package/dist/cache/MemcachedCache.d.ts

@@ -0,0 +1,71 @@
+import { type Option } from '../util/Option.js';
+import { type Cache } from './Cache.js';
+/**
+ * Memcached-backed `Cache` — wraps `memjs` (pure-JS memcached client,
+ * tiny, well-maintained).  Useful for shops with existing memcached
+ * infrastructure; in greenfield setups Redis is the better default
+ * (richer primitives, better cluster story).
+ *
+ * Wire format:
+ *   - Values are JSON-stringified before send and parsed on receive.
+ *   - TTLs are passed as seconds (memcached's native unit) — the
+ *     interface uses milliseconds, we round up to the nearest second
+ *     internally with a 1s minimum.
+ *   - `incr` uses memcached's atomic INCR with a CAS-based create
+ *     fallback for the first-key-write (memcached's `incr` doesn't
+ *     auto-create like Redis does).
+ *   - `setIfAbsent` maps to memcached's `add` operation.
+ *
+ * Failure model matches `RedisCache`: `get`/`set`/`delete` swallow
+ * transient errors; `incr` and `setIfAbsent` propagate so callers can
+ * detect lost atomicity.
+ */
+export interface MemcachedCacheOptions {
+    /** Comma-separated server list, e.g. `'localhost:11211'`.  Default: `'localhost:11211'`. */
+    readonly servers?: string;
+    /** Optional username/password for SASL auth. */
+    readonly username?: string;
+    readonly password?: string;
+    /** Optional key prefix (server-side, applied to every operation). */
+    readonly keyPrefix?: string;
+    /** Pre-built memjs client — bypass internal construction. */
+    readonly client?: MemcachedClientLike;
+}
+/** Subset of `memjs.Client` we use.  memjs uses Buffer; we always pass strings. */
+export interface MemcachedClientLike {
+    get(key: string): Promise<{
+        value: Buffer | null;
+        flags?: Buffer | null;
+    }>;
+    set(key: string, value: string | Buffer, opts?: {
+        expires?: number;
+    }): Promise<boolean>;
+    add(key: string, value: string | Buffer, opts?: {
+        expires?: number;
+    }): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    increment(key: string, amount: number, opts?: {
+        initial?: number;
+        expires?: number;
+    }): Promise<{
+        value: number | null;
+    }>;
+    quit(): Promise<void>;
+}
+export declare class MemcachedCache implements Cache {
+    private readonly clientLazy;
+    private readonly keyPrefix;
+    private closed;
+    constructor(opts?: MemcachedCacheOptions);
+    get<V>(key: string): Promise<Option<V>>;
+    set<V>(key: string, value: V, ttlMs?: number): Promise<void>;
+    incr(key: string, ttlMs?: number): Promise<number>;
+    setIfAbsent<V>(key: string, value: V, ttlMs?: number): Promise<boolean>;
+    delete(...keys: string[]): Promise<void>;
+    mget<V>(keys: ReadonlyArray<string>): Promise<Map<string, V>>;
+    mset<V>(entries: ReadonlyMap<string, V>, ttlMs?: number): Promise<void>;
+    close(): Promise<void>;
+    private k;
+}
+export declare const assertSafeMemcachedKey: (key: string) => void;
+//# sourceMappingURL=MemcachedCache.d.ts.map

package/dist/cache/MemcachedCache.d.ts.map

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

package/dist/cache/MemcachedCache.js

@@ -0,0 +1,243 @@
+import { makeKeyValidator } from '../persistence/storage/KeyValidator.js';
+import { Lazy } from '../util/Lazy.js';
+import { none, some } from '../util/Option.js';
+import { wrapError } from '../util/WrapError.js';
+import { CacheError } from './Cache.js';
+export class MemcachedCache {
+    clientLazy;
+    keyPrefix;
+    closed = false;
+    constructor(opts = {}) {
+        this.keyPrefix = opts.keyPrefix ?? '';
+        this.clientLazy = Lazy.of(async () => {
+            if (opts.client)
+                return opts.client;
+            const memjs = await memjsLazy.get();
+            const Client = memjs.Client
+                ?? memjs;
+            return Client.create(opts.servers ?? 'localhost:11211', {
+                username: opts.username,
+                password: opts.password,
+            });
+        });
+    }
+    async get(key) {
+        if (this.closed)
+            return none;
+        // Validate BEFORE the try/catch so protocol-injection attempts
+        // surface to the caller as a CacheError, rather than being
+        // silently swallowed as a "cache miss".
+        assertSafeMemcachedKey(key);
+        try {
+            const client = await this.clientLazy.get();
+            const { value } = await client.get(this.k(key));
+            if (!value)
+                return none;
+            return some(JSON.parse(value.toString('utf8')));
+        }
+        catch {
+            return none;
+        }
+    }
+    async set(key, value, ttlMs) {
+        if (this.closed)
+            return;
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new CacheError(`MemcachedCache.set: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        assertSafeMemcachedKey(key);
+        const expires = msToSeconds(ttlMs);
+        try {
+            const client = await this.clientLazy.get();
+            await client.set(this.k(key), JSON.stringify(value), expires === undefined ? undefined : { expires });
+        }
+        catch {
+            // Lost write is acceptable for a cache.
+        }
+    }
+    async incr(key, ttlMs) {
+        if (this.closed)
+            throw new CacheError('MemcachedCache.incr: cache is closed');
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new CacheError(`MemcachedCache.incr: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const client = await this.clientLazy.get();
+        const expires = msToSeconds(ttlMs);
+        try {
+            // memjs `increment` with `initial` auto-creates the counter on
+            // first call — matches Redis INCR semantics.  TTL only applies
+            // on the create path (memcached's native behaviour).
+            const { value } = await client.increment(this.k(key), 1, {
+                initial: 1,
+                expires,
+            });
+            if (value === null) {
+                throw new CacheError(`MemcachedCache.incr: server returned null for key '${key}'`);
+            }
+            return value;
+        }
+        catch (e) {
+            if (e instanceof CacheError)
+                throw e;
+            throw wrapError(e, CacheError, `MemcachedCache.incr failed for key '${key}'`);
+        }
+    }
+    async setIfAbsent(key, value, ttlMs) {
+        if (this.closed)
+            throw new CacheError('MemcachedCache.setIfAbsent: cache is closed');
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new CacheError(`MemcachedCache.setIfAbsent: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const expires = msToSeconds(ttlMs);
+        try {
+            const client = await this.clientLazy.get();
+            // memjs `add` returns true if stored, false if the key already exists.
+            return await client.add(this.k(key), JSON.stringify(value), expires === undefined ? undefined : { expires });
+        }
+        catch (e) {
+            throw wrapError(e, CacheError, `MemcachedCache.setIfAbsent failed for key '${key}'`);
+        }
+    }
+    async delete(...keys) {
+        if (this.closed || keys.length === 0)
+            return;
+        // Validate every key up-front; one bad key fails the whole call.
+        for (const k of keys)
+            assertSafeMemcachedKey(k);
+        try {
+            const client = await this.clientLazy.get();
+            // memjs has no multi-delete — issue them in parallel.
+            await Promise.all(keys.map((k) => client.delete(this.k(k)).catch(() => false)));
+        }
+        catch {
+            // ignore
+        }
+    }
+    async mget(keys) {
+        const out = new Map();
+        if (this.closed || keys.length === 0)
+            return out;
+        for (const k of keys)
+            assertSafeMemcachedKey(k);
+        try {
+            const client = await this.clientLazy.get();
+            // memjs has no native MGET — issue in parallel and rebuild the
+            // result Map.  We lose Redis's "preserves request order"
+            // guarantee, but the contract documents the order as backend-
+            // dependent for that reason.
+            const results = await Promise.all(keys.map(async (k) => {
+                try {
+                    const { value } = await client.get(this.k(k));
+                    if (!value)
+                        return null;
+                    try {
+                        return JSON.parse(value.toString('utf8'));
+                    }
+                    catch {
+                        return null;
+                    }
+                }
+                catch {
+                    return null;
+                }
+            }));
+            for (let i = 0; i < keys.length; i++) {
+                const v = results[i];
+                if (v !== null && v !== undefined)
+                    out.set(keys[i], v);
+            }
+        }
+        catch {
+            // ignore
+        }
+        return out;
+    }
+    async mset(entries, ttlMs) {
+        if (this.closed || entries.size === 0)
+            return;
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new CacheError(`MemcachedCache.mset: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        for (const k of entries.keys())
+            assertSafeMemcachedKey(k);
+        const expires = msToSeconds(ttlMs);
+        try {
+            const client = await this.clientLazy.get();
+            await Promise.all(Array.from(entries).map(([k, v]) => client.set(this.k(k), JSON.stringify(v), expires === undefined ? undefined : { expires }).catch(() => false)));
+        }
+        catch {
+            // ignore
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (!this.clientLazy.isEvaluated)
+            return;
+        try {
+            const client = await this.clientLazy.get();
+            await client.quit();
+        }
+        catch { /* ignore */ }
+    }
+    k(key) {
+        assertSafeMemcachedKey(key);
+        return this.keyPrefix ? `${this.keyPrefix}${key}` : key;
+    }
+}
+/**
+ * Reject memcached keys that contain whitespace, control characters,
+ * NUL bytes, or are over the protocol's 250-byte limit.
+ *
+ * **Exploit walkthrough (pre-fix).**  Memcached's text protocol uses
+ * whitespace (space, `\r`, `\n`, `\t`) as command delimiters.  Some
+ * memcached clients pass user-supplied keys straight onto the wire;
+ * a key like `'a\r\nFLUSHALL\r\n'` becomes two protocol lines once
+ * concatenated with the rest of the SET frame:
+ *
+ *   set <keyPrefix>a
+ *   FLUSHALL
+ *   ...
+ *
+ * The server interprets the second line as a real `FLUSHALL`,
+ * wiping the cache.  Even a server that ignores unknown commands
+ * leaks information: the response to the injected line lands in the
+ * pipeline reader, desynchronising every subsequent request.
+ *
+ * The framework's `Cache` interface accepts user-supplied keys
+ * (often derived from request paths or actor pids), so the
+ * sanitisation lives here.
+ */
+/**
+ * Memcached key-validation rules.  Same checks the pre-refactor
+ * `assertSafeMemcachedKey` enforced — exported so any other
+ * Memcached-text-protocol-style backend can reuse.
+ *
+ * See `src/persistence/storage/KeyValidator.ts` for the factory.
+ */
+const MemcachedKeyRules = {
+    errorClass: CacheError,
+    errorPrefix: 'memcached key',
+    maxLength: 250,
+    rejectNul: true,
+    rejectControlChars: true,
+    rejectSpace: true,
+};
+export const assertSafeMemcachedKey = makeKeyValidator(MemcachedKeyRules);
+/* ---------------------------- internals --------------------------------- */
+function msToSeconds(ttlMs) {
+    if (ttlMs === undefined)
+        return undefined;
+    return Math.max(1, Math.ceil(ttlMs / 1000));
+}
+const memjsLazy = Lazy.of(async () => {
+    try {
+        const name = 'memjs';
+        return await import(name);
+    }
+    catch (e) {
+        throw new CacheError('MemcachedCache requires the "memjs" package.  Install it with: npm install memjs', e);
+    }
+});
+//# sourceMappingURL=MemcachedCache.js.map

package/dist/cache/MemcachedCache.js.map

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

package/dist/cache/RedisCache.d.ts

@@ -0,0 +1,80 @@
+import { type Option } from '../util/Option.js';
+import { type Cache } from './Cache.js';
+/**
+ * Redis-backed `Cache` — wraps `ioredis`.  We pick ioredis over the
+ * official `redis` client because it's better typed, supports Redis
+ * Cluster out of the box, and is the de-facto choice in the Node
+ * ecosystem.  `ioredis` is a **lazy optional peer dependency**: it's
+ * imported on first cache operation, so users who don't reach for the
+ * Redis backend pay nothing.
+ *
+ * Values are JSON-serialized on set, JSON-parsed on get.  This matches
+ * 95% of cache use-cases (config, response bodies, counters).  Binary
+ * payloads or other formats need a custom Cache implementation —
+ * deliberately out of scope for v1.
+ *
+ * Connection failures **do not throw** from `get` — they return None.
+ * The caller's recovery path (re-fetch from source-of-truth) is the
+ * right behaviour for a cache miss.  `set` and `delete` swallow
+ * transient errors too, since lost cache writes are tolerable by
+ * definition.  `incr` and `setIfAbsent` *do* throw because the caller
+ * relies on their atomic semantics for correctness (rate-limit,
+ * idempotency-key).
+ */
+export interface RedisCacheOptions {
+    /**
+     * Redis URL (e.g. `redis://localhost:6379`) — passed straight to the
+     * ioredis constructor.  Mutually exclusive with `host`/`port`.
+     */
+    readonly url?: string;
+    readonly host?: string;
+    readonly port?: number;
+    readonly password?: string;
+    readonly db?: number;
+    /**
+     * Optional key prefix prepended to every key.  Useful when a single
+     * Redis instance is shared by multiple actor systems / environments.
+     */
+    readonly keyPrefix?: string;
+    /**
+     * Pre-built ioredis client — bypass internal construction (advanced
+     * usage: connection sharing, custom retry strategies, Redis Cluster).
+     */
+    readonly client?: RedisClientLike;
+}
+/**
+ * Minimal subset of the ioredis client surface we depend on.  Defined
+ * here so a custom client (mock, wrapper, Cluster) can satisfy the
+ * contract without pulling in the full ioredis types.
+ */
+export interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    set(key: string, value: string, mode: 'PX', ttlMs: number): Promise<unknown>;
+    set(key: string, value: string, mode: 'PX', ttlMs: number, flag: 'NX'): Promise<string | null>;
+    set(key: string, value: string, flag: 'NX'): Promise<string | null>;
+    incr(key: string): Promise<number>;
+    pexpire(key: string, ttlMs: number): Promise<number>;
+    del(...keys: string[]): Promise<number>;
+    /** Bulk get — returns one entry per key in order, `null` for misses. */
+    mget(...keys: string[]): Promise<Array<string | null>>;
+    /** Bulk set — variadic `key1, value1, key2, value2, …`.  No per-key TTL. */
+    mset(...keyValuePairs: string[]): Promise<unknown>;
+    quit(): Promise<unknown>;
+}
+export declare class RedisCache implements Cache {
+    private readonly clientLazy;
+    private readonly keyPrefix;
+    private closed;
+    constructor(opts?: RedisCacheOptions);
+    get<V>(key: string): Promise<Option<V>>;
+    set<V>(key: string, value: V, ttlMs?: number): Promise<void>;
+    incr(key: string, ttlMs?: number): Promise<number>;
+    setIfAbsent<V>(key: string, value: V, ttlMs?: number): Promise<boolean>;
+    delete(...keys: string[]): Promise<void>;
+    mget<V>(keys: ReadonlyArray<string>): Promise<Map<string, V>>;
+    mset<V>(entries: ReadonlyMap<string, V>, ttlMs?: number): Promise<void>;
+    close(): Promise<void>;
+    private k;
+}
+//# sourceMappingURL=RedisCache.d.ts.map

package/dist/cache/RedisCache.d.ts.map

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

package/dist/cache/RedisCache.js

@@ -0,0 +1,194 @@
+import { Lazy } from '../util/Lazy.js';
+import { none, some } from '../util/Option.js';
+import { wrapError } from '../util/WrapError.js';
+import { CacheError } from './Cache.js';
+export class RedisCache {
+    clientLazy;
+    keyPrefix;
+    closed = false;
+    constructor(opts = {}) {
+        this.keyPrefix = opts.keyPrefix ?? '';
+        this.clientLazy = Lazy.of(async () => {
+            if (opts.client)
+                return opts.client;
+            const ioredis = await ioredisLazy.get();
+            // ioredis.default is the constructor when imported from ESM consumers.
+            const Ctor = ioredis.default ?? ioredis;
+            if (opts.url)
+                return new Ctor(opts.url);
+            return new Ctor({
+                host: opts.host,
+                port: opts.port,
+                password: opts.password,
+                db: opts.db,
+            });
+        });
+    }
+    async get(key) {
+        if (this.closed)
+            return none;
+        try {
+            const client = await this.clientLazy.get();
+            const raw = await client.get(this.k(key));
+            if (raw === null)
+                return none;
+            return some(JSON.parse(raw));
+        }
+        catch {
+            // Cache miss on transient failures — caller will fall back to source.
+            return none;
+        }
+    }
+    async set(key, value, ttlMs) {
+        if (this.closed)
+            return;
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new CacheError(`RedisCache.set: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const payload = JSON.stringify(value);
+        try {
+            const client = await this.clientLazy.get();
+            if (ttlMs === undefined)
+                await client.set(this.k(key), payload);
+            else
+                await client.set(this.k(key), payload, 'PX', ttlMs);
+        }
+        catch {
+            // Lost write is acceptable for a cache.
+        }
+    }
+    async incr(key, ttlMs) {
+        if (this.closed)
+            throw new CacheError('RedisCache.incr: cache is closed');
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new CacheError(`RedisCache.incr: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const client = await this.clientLazy.get();
+        const k = this.k(key);
+        let next;
+        try {
+            next = await client.incr(k);
+        }
+        catch (e) {
+            throw wrapError(e, CacheError, `RedisCache.incr failed for key '${key}'`);
+        }
+        if (next === 1 && ttlMs !== undefined) {
+            // First increment → set the TTL.  If pexpire fails, we accept the
+            // inconsistency rather than rolling the counter back.
+            try {
+                await client.pexpire(k, ttlMs);
+            }
+            catch { /* swallow */ }
+        }
+        return next;
+    }
+    async setIfAbsent(key, value, ttlMs) {
+        if (this.closed)
+            throw new CacheError('RedisCache.setIfAbsent: cache is closed');
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new CacheError(`RedisCache.setIfAbsent: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        const client = await this.clientLazy.get();
+        const payload = JSON.stringify(value);
+        try {
+            const result = ttlMs === undefined
+                ? await client.set(this.k(key), payload, 'NX')
+                : await client.set(this.k(key), payload, 'PX', ttlMs, 'NX');
+            // ioredis returns 'OK' on success and null on collision.
+            return result === 'OK';
+        }
+        catch (e) {
+            throw wrapError(e, CacheError, `RedisCache.setIfAbsent failed for key '${key}'`);
+        }
+    }
+    async delete(...keys) {
+        if (this.closed || keys.length === 0)
+            return;
+        try {
+            const client = await this.clientLazy.get();
+            await client.del(...keys.map((k) => this.k(k)));
+        }
+        catch {
+            // Lost delete is acceptable.
+        }
+    }
+    async mget(keys) {
+        const out = new Map();
+        if (this.closed || keys.length === 0)
+            return out;
+        try {
+            const client = await this.clientLazy.get();
+            const raw = await client.mget(...keys.map((k) => this.k(k)));
+            for (let i = 0; i < keys.length; i++) {
+                const v = raw[i];
+                if (v === null || v === undefined)
+                    continue;
+                try {
+                    out.set(keys[i], JSON.parse(v));
+                }
+                catch {
+                    // Bad payload — treat as a miss.  Same semantics as `get`
+                    // returning None on a transient failure.
+                }
+            }
+        }
+        catch {
+            // Transient backend failure — return whatever we managed.
+        }
+        return out;
+    }
+    async mset(entries, ttlMs) {
+        if (this.closed || entries.size === 0)
+            return;
+        if (ttlMs !== undefined && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+            throw new CacheError(`RedisCache.mset: ttlMs must be a positive finite number, got ${ttlMs}`);
+        }
+        try {
+            const client = await this.clientLazy.get();
+            if (ttlMs === undefined) {
+                // Single MSET command — atomic on the server side.
+                const args = [];
+                for (const [k, v] of entries) {
+                    args.push(this.k(k));
+                    args.push(JSON.stringify(v));
+                }
+                await client.mset(...args);
+            }
+            else {
+                // MSET doesn't accept per-key TTL — fall back to parallel
+                // `SET k v PX ttl` calls.  Not atomic across keys, but a
+                // cache write losing atomicity is tolerable (same standing as
+                // the per-key `set` failure mode).
+                await Promise.all(Array.from(entries).map(([k, v]) => client.set(this.k(k), JSON.stringify(v), 'PX', ttlMs)));
+            }
+        }
+        catch {
+            // Lost write is acceptable for a cache.
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (!this.clientLazy.isEvaluated)
+            return;
+        try {
+            const client = await this.clientLazy.get();
+            await client.quit();
+        }
+        catch { /* ignore */ }
+    }
+    k(key) {
+        return this.keyPrefix ? `${this.keyPrefix}${key}` : key;
+    }
+}
+const ioredisLazy = Lazy.of(async () => {
+    try {
+        const name = 'ioredis';
+        return await import(name);
+    }
+    catch (e) {
+        throw new CacheError('RedisCache requires the "ioredis" package.  Install it with: npm install ioredis', e);
+    }
+});
+//# sourceMappingURL=RedisCache.js.map

package/dist/cache/RedisCache.js.map

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

package/dist/cache/index.d.ts

@@ -0,0 +1,9 @@
+export { CacheError } from './Cache.js';
+export type { Cache } from './Cache.js';
+export { InMemoryCache } from './InMemoryCache.js';
+export { RedisCache } from './RedisCache.js';
+export type { RedisCacheOptions, RedisClientLike } from './RedisCache.js';
+export { MemcachedCache } from './MemcachedCache.js';
+export type { MemcachedCacheOptions, MemcachedClientLike } from './MemcachedCache.js';
+export { CacheExtension, CacheExtensionId, IN_MEMORY_CACHE_PLUGIN_ID, REDIS_CACHE_PLUGIN_ID, MEMCACHED_CACHE_PLUGIN_ID, } from './CacheExtension.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,YAAY,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,6 @@
+export { CacheError } from './Cache.js';
+export { InMemoryCache } from './InMemoryCache.js';
+export { RedisCache } from './RedisCache.js';
+export { MemcachedCache } from './MemcachedCache.js';
+export { CacheExtension, CacheExtensionId, IN_MEMORY_CACHE_PLUGIN_ID, REDIS_CACHE_PLUGIN_ID, MEMCACHED_CACHE_PLUGIN_ID, } from './CacheExtension.js';
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC"}