snugkv-nest 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edijs Ziedins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,270 @@
-# Temporary Holding Version
+# snugkv-nest
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The NestJS module and TypeScript client for [SnugKV](https://github.com/edijs1984/snugkv): strings, hashes, lists, sets, sorted sets, expiry, Lua, pub/sub and transactions, plus cache, lock and rate-limit helpers and a durable message bus on streams.
+
+- [Using SnugKV as a data store](#using-snugkv-as-a-data-store)
+- [Messaging (streams)](#messaging-streams)
+
+- **Durable topics.** Messages are stream entries. They survive restarts and are replayable.
+- **Consumer groups.** Instances of one service share the work; every different service gets every message.
+- **Safe delivery.** At-least-once with acknowledgements, retries with backoff, dead-letter topics, and automatic takeover of messages a crashed instance left behind.
+- **No dependencies.** A small built-in RESP client (reconnect, AUTH, TLS, pipelining). Only `@nestjs/common` and `@nestjs/core` as peers.
+- **Visible.** Every publisher and consumer reports itself, so [snugkv-stream-ui](https://github.com/edijs1984/snugkv-stream-ui) can show who publishes and who listens to each topic.
+
+It also works as a plain Redis-protocol streams client, so it should run against Redis 6.2+ too, but SnugKV is what it is tested with.
+
+## Install
+
+```bash
+npm install snugkv-nest
+```
+
+Needs Node 18+ and NestJS 10 or 11.
+
+## Using SnugKV as a data store
+
+Import the module once; everything below can be injected.
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { SnugKvCache, SnugKvClient, SnugKvLocks, SnugKvModule, SnugKvRateLimiter, SnugKvSubscriber } from 'snugkv-nest';
+
+// app.module.ts
+@Module({ imports: [SnugKvModule.forRoot({ url: process.env.SNUGKV_URL, cache: { prefix: 'app:', ttlSeconds: 120 } })] })
+export class AppModule {}
+
+@Injectable()
+export class UsersService {
+  constructor(
+    private readonly kv: SnugKvClient,
+    private readonly cache: SnugKvCache,
+    private readonly locks: SnugKvLocks,
+    private readonly limiter: SnugKvRateLimiter,
+    private readonly pubsub: SnugKvSubscriber,
+  ) {}
+
+  profile(id: string) {
+    return this.cache.wrap(`user:${id}`, () => this.loadFromDb(id)); // loader runs once, result cached 120 s
+  }
+
+  async rebuild() {
+    const r = await this.locks.run('rebuild', () => this.doRebuild(), { ttlMs: 60_000 });
+    return r.acquired;
+  }
+
+  async allow(ip: string) {
+    return (await this.limiter.hit(ip, 100, 60_000)).allowed; // 100 per minute
+  }
+}
+```
+
+`service` is only needed for messaging; without it the module uses `app`. Outside Nest, use `new SnugKvClient({ url })` from `snugkv-nest/core`.
+
+### Client
+
+```ts
+await kv.set('a', '1');  await kv.setOpts('a', '1', { nx: true, exSeconds: 30 });
+await kv.incr('visits');  await kv.setJson('cfg', { a: 1 });  await kv.getJson('cfg');
+await kv.hset('user:1', { name: 'Ann', age: 31 });  await kv.hgetall('user:1');
+await kv.rpush('queue', 'a', 'b');  await kv.lrange('queue');
+await kv.sadd('tags', 'x', 'y');  await kv.smembers('tags');
+await kv.zadd('board', [{ member: 'ann', score: 10 }]);  await kv.zrange('board', 0, 9, { reverse: true });
+await kv.expire('a', 60);  await kv.ttl('a');
+for await (const key of kv.scanIterator({ match: 'user:*' })) { /* … */ }
+await kv.eval("return redis.call('get', KEYS[1])", ['a']);
+await kv.tx().set('a', '1').incr('n').hset('h', { f: 1 }).exec(); // MULTI/EXEC in one write
+await kv.call('ANYTHING', 'else');                                 // raw command
+```
+
+### Pub/sub
+
+Fire-and-forget broadcast. Use the streams below when a message must not be lost.
+
+```ts
+const off = await pubsub.subscribe('news', (message, channel) => console.log(channel, message));
+await pubsub.psubscribe('events.*', (message, channel, pattern) => { /* … */ });
+await kv.publish('news', 'hello');
+await off();
+```
+
+Subscriptions are restored after a reconnect; messages sent while disconnected are not replayed.
+
+### Cache, locks, rate limits
+
+- `SnugKvCache`: `get`, `set`, `del`, `wrap(key, loader, ttl)` (concurrent callers share one load), `clear(pattern)`.
+- `SnugKvLocks`: `acquire(name, { ttlMs, waitMs })`, `run(name, fn)`. A lock expires on its own, and only its holder can release or extend it. It protects against crashed holders, not against the server itself failing, so keep critical sections idempotent.
+- `SnugKvRateLimiter`: `hit(key, limit, windowMs)` is a fixed window; it returns `{ allowed, count, remaining, resetMs }`.
+
+## Messaging (streams)
+
+## Quick start
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { SnugKvModule } from 'snugkv-nest';
+
+@Module({
+  imports: [
+    SnugKvModule.forRoot({
+      url: 'redis://localhost:6379',
+      service: 'billing', // this microservice's name
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Publish:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { SnugKvBus } from 'snugkv-nest';
+
+@Injectable()
+export class OrdersService {
+  constructor(private readonly bus: SnugKvBus) {}
+
+  async create(order: Order) {
+    await this.bus.publish('orders.created', order, { event: 'order.created', headers: { tenant: 'acme' } });
+  }
+}
+```
+
+Consume:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { SnugSubscribe, MessageContext } from 'snugkv-nest';
+
+@Injectable()
+export class BillingHandlers {
+  @SnugSubscribe('orders.created', { concurrency: 4 })
+  async onOrder(order: Order, ctx: MessageContext) {
+    // throw to retry; after maxAttempts the message goes to "orders.created.dlq"
+  }
+}
+```
+
+Any provider or controller with `@SnugSubscribe` methods is picked up when the app starts. Consumers stop cleanly when the app closes (`app.enableShutdownHooks()` makes this work on SIGTERM).
+
+Prefer parameter decorators?
+
+```ts
+@SnugSubscribe('orders.created')
+onOrder(@SnugPayload() order: Order, @SnugHeader('tenant') tenant: string, @SnugContext() ctx: MessageContext) {}
+```
+
+## How delivery works
+
+| You want | Do this |
+| --- | --- |
+| Run 3 copies of `billing`, each message handled once | Same `service` name on all copies |
+| `mailer` and `billing` both react to the same event | Different `service` names |
+| Two handlers in one service on one topic | Give one a different `group` |
+
+The consumer group defaults to the `service` name. Each running copy is a consumer named `<service>-<instance>`.
+
+**Retries.** A handler that throws is called again after a delay (200 ms doubling to 10 s) up to `maxAttempts` (3). Then the message is copied to `<topic>.dlq` with `dlq_error`, `dlq_attempts`, `dlq_source`, `dlq_group` and `dlq_id`, and acknowledged. `ctx.attempt` tells the handler which try it is.
+
+**Crashes.** Messages a consumer read but never acknowledged stay pending. Every consumer checks for pending messages idle longer than `claimMinIdleMs` (60 s) and takes them over. A message that has already been delivered `maxAttempts` times goes straight to the dead-letter topic, so a message that kills the process cannot loop forever. Set `claimMinIdleMs` above your slowest handler.
+
+**Order.** `concurrency: 1` (the default) handles messages one at a time in stream order. Higher values trade order for throughput.
+
+**At-least-once.** After a crash a message can be handled twice. Make handlers idempotent; `ctx.messageId` is stable across redeliveries.
+
+**Manual ack.** With `autoAck: false` the message stays pending until the handler calls `await ctx.ack()`.
+
+## Options
+
+### `SnugKvModule.forRoot(options)` / `SnugKvBus`
+
+| Option | Default | |
+| --- | --- | --- |
+| `service` | required | Name of this microservice. Default consumer group. |
+| `url` | | `redis://user:pass@host:port`, `rediss://` for TLS. `snugkv://` and `snugkvs://` also work. |
+| `host`, `port`, `username`, `password`, `tls` | `127.0.0.1`, `6379` | Instead of `url`. |
+| `instance` | `<hostname>-<random>` | Id of this running copy. Use the pod name for fast recovery after a restart. |
+| `keyPrefix` | none | Prepended to every topic to form the stream key. |
+| `maxLen` | none | Trim published streams to about this many entries. |
+| `presence` | `true` | Report publishers and consumers for the UI. `false` turns it off. |
+| `isGlobal` | `true` | Make the module global. |
+| `autoSubscribe` | `true` | Start `@SnugSubscribe` consumers automatically. |
+
+`forRootAsync({ imports, inject, useFactory })` works as usual:
+
+```ts
+SnugKvModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({ url: config.get('SNUGKV_URL')!, service: 'billing' }),
+});
+```
+
+### `@SnugSubscribe(topic, options)`
+
+| Option | Default | |
+| --- | --- | --- |
+| `group` | `service` | Consumer group. |
+| `consumer` | `<service>-<instance>` | Consumer name. |
+| `startFrom` | `'$'` | Where a new group starts: `'$'` new messages only, `'0'` from the oldest retained. |
+| `concurrency` | `1` | Messages handled at once. |
+| `prefetch` | `max(10, 2×concurrency)` | Messages read ahead. |
+| `autoAck` | `true` | Acknowledge when the handler returns. |
+| `maxAttempts` | `3` | Handler runs before dead-lettering. |
+| `retryDelayMs` | 200 ms × 2ⁿ, max 10 s | Number, or `(failedAttempt) => ms`. |
+| `deadLetterTopic` | `<topic>.dlq` | `false` drops failed messages after logging. |
+| `claimMinIdleMs` | `60000` | Take over messages idle this long. |
+| `claimIntervalMs` | `15000` | How often to look. |
+| `shutdownTimeoutMs` | `10000` | How long to wait for running handlers on stop. |
+
+### Publishing
+
+```ts
+bus.publish(topic, payload, { event?, headers?, maxLen? }): Promise<string>   // entry id
+bus.publishBatch(topic, [{ payload, event?, headers? }, …]): Promise<string[]> // one round trip
+```
+
+Each entry has the fields `payload` (JSON), `event`, `mid` (message uuid), `ts` (ms), `producer` (`service/instance`) and optionally `headers` (JSON). Entries written by other tools are delivered too; without a `payload` field the handler gets an object of all fields.
+
+### Raw commands and health
+
+`SnugKvClient` is injectable for anything else:
+
+```ts
+constructor(private readonly kv: SnugKvClient) {}
+await this.kv.call('XLEN', 'orders.created');
+await this.kv.ping(); // use in a health check
+```
+
+## Without Nest
+
+```ts
+import { SnugKvBus } from 'snugkv-nest/core';
+
+const bus = new SnugKvBus({ url: 'redis://localhost:6379', service: 'worker' });
+const sub = await bus.subscribe({ topic: 'jobs' }, async (job) => { /* … */ });
+await bus.publish('jobs', { id: 1 });
+await bus.close(); // stops consumers, removes presence records
+```
+
+## Presence protocol
+
+For tools that want to show who is connected: each publisher and consumer keeps a JSON string at
+`snugkv:presence:<role>:<topic>:<service-or-group>:<instance>` with a 15 s expiry, refreshed every 5 s. Fields:
+`v, role, service, instance, topic, group?, consumer?, host, pid, startedAt, updatedAt` and counters
+`published?, processed?, failed?, deadLettered?, inflight?, concurrency?`.
+
+## Development
+
+```bash
+git clone https://github.com/edijs1984/snugkv && (cd snugkv && go build -o /tmp/snugkv ./cmd/snugkv)
+npm install
+npm run build
+SNUGKV_BIN=/tmp/snugkv npm test   # tests start real servers on free ports
+```
+
+Tests that need a server are skipped when `SNUGKV_BIN` is not set.
+
+## License
+
+MIT

package/dist/core/bus.d.ts

@@ -0,0 +1,61 @@
+import { SnugKvClient, SnugKvClientOptions } from './client';
+import { MessageHandler, SubscribeOptions, ConsumerStats } from './consumer';
+import { SnugKvSubscriber } from './pubsub';
+import { PresenceOptions } from './presence';
+import { BatchMessage, PublishOptions, Publisher, Serializer } from './publisher';
+import { BusLogger } from './util';
+export interface SnugKvBusOptions extends SnugKvClientOptions {
+    /** Name of this microservice, e.g. `billing`. Default consumer group. */
+    service: string;
+    /** Unique id of this running copy. Default `<hostname>-<random>`. Use a stable id (e.g. the pod name) for faster crash recovery. */
+    instance?: string;
+    /** Prepended to every topic to form the stream key. Default none. */
+    keyPrefix?: string;
+    /** Trim published streams to about this many entries. Default: no trimming. */
+    maxLen?: number;
+    /** Report this process to tools like the stream UI. Default true. */
+    presence?: boolean | PresenceOptions;
+    serializer?: Serializer;
+    logger?: BusLogger;
+    /** Wait this long for the first connection in `connect()`. Default 10 s. */
+    connectTimeoutMs?: number;
+}
+export interface Subscription {
+    readonly topic: string;
+    readonly group: string;
+    readonly consumer: string;
+    stats(): ConsumerStats;
+    stop(): Promise<void>;
+}
+/** Everything in one object: publish, subscribe, presence, shutdown. */
+export declare class SnugKvBus {
+    private readonly options;
+    readonly client: SnugKvClient;
+    readonly service: string;
+    readonly instance: string;
+    readonly publisher: Publisher;
+    private readonly presence?;
+    private readonly consumers;
+    private readonly serializer;
+    private readonly logger;
+    private readonly keyPrefix;
+    private closed;
+    private pubsub?;
+    constructor(options: SnugKvBusOptions);
+    /** Connects the main connection. Rejects if the server is not reachable in time. */
+    connect(): Promise<void>;
+    publish<T = unknown>(topic: string, payload: T, options?: PublishOptions): Promise<string>;
+    publishBatch<T = unknown>(topic: string, messages: Array<BatchMessage<T>>, options?: {
+        maxLen?: number;
+    }): Promise<string[]>;
+    /** Starts a consumer. Resolves when it is reading. */
+    subscribe<T = unknown>(options: SubscribeOptions, handler: MessageHandler<T>): Promise<Subscription>;
+    /** Shared pub/sub subscriber (own connection, opened on first use, closed with the bus). */
+    subscriber(): SnugKvSubscriber;
+    stats(): {
+        published: Record<string, number>;
+        consumers: ConsumerStats[];
+    };
+    /** Stops consumers (letting running handlers finish), removes presence records and closes connections. */
+    close(): Promise<void>;
+}

package/dist/core/bus.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnugKvBus = void 0;
+const node_os_1 = require("node:os");
+const client_1 = require("./client");
+const consumer_1 = require("./consumer");
+const presence_1 = require("./presence");
+const publisher_1 = require("./publisher");
+const util_1 = require("./util");
+/** Everything in one object: publish, subscribe, presence, shutdown. */
+class SnugKvBus {
+    options;
+    client;
+    service;
+    instance;
+    publisher;
+    presence;
+    consumers = [];
+    serializer;
+    logger;
+    keyPrefix;
+    closed = false;
+    pubsub;
+    constructor(options) {
+        this.options = options;
+        if (!options.service)
+            throw new Error('snugkv: "service" is required');
+        this.service = options.service;
+        this.instance = options.instance ?? `${(0, node_os_1.hostname)()}-${(0, util_1.uuid)().slice(0, 8)}`;
+        this.serializer = options.serializer ?? publisher_1.jsonSerializer;
+        this.logger = options.logger ?? util_1.consoleLogger;
+        this.keyPrefix = options.keyPrefix ?? '';
+        const { service, instance, keyPrefix, maxLen, presence, serializer, logger, connectTimeoutMs, ...conn } = options;
+        this.client = new client_1.SnugKvClient({ name: `${this.service}/${this.instance}`, ...conn });
+        this.client.on('error', (e) => this.logger.warn(`connection error: ${e.message}`));
+        if (options.presence !== false) {
+            this.presence = new presence_1.PresenceReporter(this.client, this.logger, typeof options.presence === 'object' ? options.presence : {});
+        }
+        this.publisher = new publisher_1.Publisher(this.client, { service: this.service, instance: this.instance, keyPrefix: this.keyPrefix, defaultMaxLen: options.maxLen, serializer: this.serializer }, this.presence);
+    }
+    /** Connects the main connection. Rejects if the server is not reachable in time. */
+    async connect() {
+        await this.client.connect(this.options.connectTimeoutMs ?? 10_000);
+    }
+    publish(topic, payload, options) {
+        return this.publisher.publish(topic, payload, options);
+    }
+    publishBatch(topic, messages, options) {
+        return this.publisher.publishBatch(topic, messages, options);
+    }
+    /** Starts a consumer. Resolves when it is reading. */
+    async subscribe(options, handler) {
+        if (this.closed)
+            throw new Error('snugkv: bus is closed');
+        await this.connect();
+        const read = this.client.duplicate({ name: `${this.service}/${this.instance}:read:${options.topic}` });
+        read.on('error', (e) => this.logger.warn(`read connection error: ${e.message}`));
+        const consumer = new consumer_1.Consumer(options, handler, {
+            cmd: this.client,
+            read,
+            service: this.service,
+            instance: this.instance,
+            keyPrefix: this.keyPrefix,
+            serializer: this.serializer,
+            logger: this.logger,
+            presence: this.presence,
+        });
+        this.consumers.push(consumer);
+        try {
+            await consumer.start();
+        }
+        catch (err) {
+            this.consumers.splice(this.consumers.indexOf(consumer), 1);
+            read.close();
+            throw err;
+        }
+        return {
+            topic: consumer.topic,
+            group: consumer.group,
+            consumer: consumer.consumer,
+            stats: () => consumer.stats(),
+            stop: async () => {
+                const i = this.consumers.indexOf(consumer);
+                if (i >= 0)
+                    this.consumers.splice(i, 1);
+                await consumer.stop();
+            },
+        };
+    }
+    /** Shared pub/sub subscriber (own connection, opened on first use, closed with the bus). */
+    subscriber() {
+        this.pubsub ??= this.client.subscriber();
+        return this.pubsub;
+    }
+    stats() {
+        return { published: this.publisher.stats(), consumers: this.consumers.map((c) => c.stats()) };
+    }
+    /** Stops consumers (letting running handlers finish), removes presence records and closes connections. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await Promise.allSettled(this.consumers.splice(0).map((c) => c.stop()));
+        await this.presence?.stop();
+        this.pubsub?.close();
+        this.client.close();
+    }
+}
+exports.SnugKvBus = SnugKvBus;
+//# sourceMappingURL=bus.js.map

package/dist/core/bus.js.map

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

package/dist/core/cache.d.ts

@@ -0,0 +1,27 @@
+import type { SnugKvClient } from './client';
+export interface CacheOptions {
+    /** Prefix for every key. Default `cache:`. */
+    prefix?: string;
+    /** Default time to live in seconds. Default 60. */
+    ttlSeconds?: number;
+}
+/**
+ * JSON cache on top of strings with expiry. `wrap` runs the loader at most
+ * once at a time per key inside this process (concurrent callers share the
+ * result).
+ */
+export declare class SnugKvCache {
+    private readonly client;
+    private readonly prefix;
+    private readonly ttl;
+    private readonly inflight;
+    constructor(client: SnugKvClient, opts?: CacheOptions);
+    key(key: string): string;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    del(...keys: string[]): Promise<number>;
+    /** Returns the cached value, or runs `load`, stores the result and returns it. `undefined` results are not cached. */
+    wrap<T>(key: string, load: () => Promise<T> | T, ttlSeconds?: number): Promise<T>;
+    /** Deletes every key under the cache prefix that matches `pattern` (default all). */
+    clear(pattern?: string): Promise<number>;
+}

package/dist/core/cache.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnugKvCache = void 0;
+/**
+ * JSON cache on top of strings with expiry. `wrap` runs the loader at most
+ * once at a time per key inside this process (concurrent callers share the
+ * result).
+ */
+class SnugKvCache {
+    client;
+    prefix;
+    ttl;
+    inflight = new Map();
+    constructor(client, opts = {}) {
+        this.client = client;
+        this.prefix = opts.prefix ?? 'cache:';
+        this.ttl = opts.ttlSeconds ?? 60;
+    }
+    key(key) {
+        return this.prefix + key;
+    }
+    async get(key) {
+        const raw = await this.client.get(this.key(key));
+        return raw === null ? undefined : JSON.parse(raw);
+    }
+    async set(key, value, ttlSeconds = this.ttl) {
+        await this.client.setJson(this.key(key), value, ttlSeconds);
+    }
+    async del(...keys) {
+        return keys.length ? this.client.del(...keys.map((k) => this.key(k))) : 0;
+    }
+    /** Returns the cached value, or runs `load`, stores the result and returns it. `undefined` results are not cached. */
+    async wrap(key, load, ttlSeconds = this.ttl) {
+        const hit = await this.get(key);
+        if (hit !== undefined)
+            return hit;
+        const running = this.inflight.get(key);
+        if (running)
+            return running;
+        const p = (async () => {
+            try {
+                const value = await load();
+                if (value !== undefined)
+                    await this.set(key, value, ttlSeconds);
+                return value;
+            }
+            finally {
+                this.inflight.delete(key);
+            }
+        })();
+        this.inflight.set(key, p);
+        return p;
+    }
+    /** Deletes every key under the cache prefix that matches `pattern` (default all). */
+    async clear(pattern = '*') {
+        let n = 0;
+        let batch = [];
+        for await (const k of this.client.scanIterator({ match: this.prefix + pattern, count: 200 })) {
+            batch.push(k);
+            if (batch.length >= 200) {
+                n += await this.client.del(...batch);
+                batch = [];
+            }
+        }
+        if (batch.length)
+            n += await this.client.del(...batch);
+        return n;
+    }
+}
+exports.SnugKvCache = SnugKvCache;
+//# sourceMappingURL=cache.js.map

package/dist/core/cache.js.map

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