snugkv-nest 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,9 @@
 # snugkv-nest
 
-A message bus for NestJS microservices, built on [SnugKV](https://github.com/edijs1984/snugkv) streams.
+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.
@@ -18,6 +21,119 @@ 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 }`.
+
+## Job queues
+
+BullMQ-style queues that run inside SnugKV (the `snugq` function library, loaded by the server by default). Needs a server version that includes it.
+
+```ts
+import { Queue, Worker, QueueEvents, FlowProducer } from 'snugkv-nest';
+
+const emails = new Queue('emails', { connection: { host: '127.0.0.1', port: 6379 } });
+await emails.add('welcome', { to: 'a@b.c' }, { attempts: 3, backoff: { type: 'exponential', delay: 1000 }, removeOnComplete: 100 });
+
+const worker = new Worker('emails', async (job) => {
+  await job.updateProgress(50);
+  return send(job.data);
+}, { connection: { host: '127.0.0.1', port: 6379 }, concurrency: 5 });
+worker.on('failed', (job, err) => console.error(job.id, err.message));
+```
+
+With Nest, register queues and mark processors; workers start and stop with the app:
+
+```ts
+SnugKvQueueModule.registerQueue({ name: 'emails' })
+
+@SnugProcessor('emails', { concurrency: 5 })
+export class EmailProcessor extends WorkerHost {
+  async process(job: Job<{ to: string }>) { /* … */ }
+
+  @OnSnugWorkerEvent('failed')
+  onFailed(job: Job, err: Error) { /* … */ }
+}
+
+constructor(@InjectSnugQueue('emails') private readonly emails: Queue) {}
+```
+
+Use `@SnugProcess('jobName')` on methods instead of `process()` to route by job name.
+
+Supported: priorities, LIFO, delayed jobs, attempts with fixed, exponential or custom backoff (`UnrecoverableError` skips retries), locks with stalled-job recovery, pause/resume, global concurrency, queue rate limits (`limiter`, `queue.setRateLimit`, `worker.rateLimit` + `RateLimitError`), custom ids and deduplication, `removeOnComplete`/`removeOnFail`, progress and logs, `QueueEvents` and `job.waitUntilFinished`, `drain`/`clean`/`obliterate`/`retryJobs`/`promoteJobs`, repeatable jobs (`upsertJobScheduler` with `every` or a cron `pattern` and `tz`), and parent/child flows (`FlowProducer`, `job.getChildrenValues()`, `failParentOnFailure`, `ignoreDependencyOnFailure`). Job data must be JSON-serialisable. Cron patterns are computed by workers, so keep one running. See the server's `docs/QUEUES.md` for the storage layout.
+
+## Messaging (streams)
+
 ## Quick start
 
 ```ts
@@ -188,4 +304,4 @@ Tests that need a server are skipped when `SNUGKV_BIN` is not set.
 
 ## License
 
-MIT
+MIT. This package is only a client. The SnugKV server it talks to is a separate project, licensed under AGPL-3.0 with a commercial licence option.

package/dist/core/bus.d.ts

@@ -1,5 +1,6 @@
 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';
@@ -39,6 +40,7 @@ export declare class SnugKvBus {
     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>;
@@ -48,6 +50,8 @@ export declare class SnugKvBus {
     }): 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[];

package/dist/core/bus.js

@@ -20,6 +20,7 @@ class SnugKvBus {
     logger;
     keyPrefix;
     closed = false;
+    pubsub;
     constructor(options) {
         this.options = options;
         if (!options.service)
@@ -86,6 +87,11 @@ class SnugKvBus {
             },
         };
     }
+    /** 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()) };
     }
@@ -96,6 +102,7 @@ class SnugKvBus {
         this.closed = true;
         await Promise.allSettled(this.consumers.splice(0).map((c) => c.stop()));
         await this.presence?.stop();
+        this.pubsub?.close();
         this.client.close();
     }
 }

package/dist/core/bus.js.map

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

package/dist/core/client.d.ts

@@ -1,10 +1,23 @@
 import { EventEmitter } from 'node:events';
-import { ConnectionOptions } from './connection';
+import { Connection, ConnectionOptions } from './connection';
 import { Arg, Reply } from './resp';
+import { SnugKvSubscriber } from './pubsub';
+import { Transaction } from './tx';
 export interface SnugKvClientOptions extends Partial<ConnectionOptions> {
     /** `redis://user:pass@host:port`, `rediss://…`, `snugkv://…` or `snugkvs://…`. */
     url?: string;
 }
+export interface SetOptions {
+    exSeconds?: number;
+    pxMs?: number;
+    /** Only set when the key does not exist. */
+    nx?: boolean;
+    /** Only set when the key already exists. */
+    xx?: boolean;
+    keepTtl?: boolean;
+}
+export declare function asArray(r: Reply): Reply[];
+export declare function pairsToObject(flat: Reply[]): Record<string, string>;
 export interface StreamEntry {
     id: string;
     fields: Record<string, string>;
@@ -36,7 +49,8 @@ export interface XReadGroupOptions {
 }
 export declare function toEntries(raw: Reply): StreamEntry[];
 /**
- * A small client for the commands the bus needs, plus a raw `call` for
+ * A typed client for SnugKV: strings, hashes, lists, sets, sorted sets,
+ * expiry, scan, Lua, pub/sub, transactions and streams, plus a raw `call` for
  * anything else. One client owns one connection; blocking reads belong on
  * their own client (see {@link SnugKvClient.duplicate}).
  */
@@ -44,6 +58,8 @@ export declare class SnugKvClient extends EventEmitter {
     private readonly conn;
     private readonly options;
     constructor(options?: SnugKvClientOptions);
+    /** @internal */
+    get connection(): Connection;
     get isReady(): boolean;
     connect(timeoutMs?: number): Promise<void>;
     /** New client with its own connection and the same settings. */
@@ -59,6 +75,103 @@ export declare class SnugKvClient extends EventEmitter {
         exSeconds?: number;
     }): Promise<void>;
     del(...keys: string[]): Promise<number>;
+    setOpts(key: string, value: string | number, opts?: SetOptions): Promise<boolean>;
+    mget(...keys: string[]): Promise<Array<string | null>>;
+    mset(values: Record<string, string | number>): Promise<void>;
+    incr(key: string, by?: number): Promise<number>;
+    decr(key: string, by?: number): Promise<number>;
+    incrByFloat(key: string, by: number): Promise<number>;
+    append(key: string, value: string): Promise<number>;
+    getDel(key: string): Promise<string | null>;
+    /** JSON convenience: stores `JSON.stringify(value)`; `ttlSeconds` optional. */
+    setJson(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    getJson<T = unknown>(key: string): Promise<T | null>;
+    exists(...keys: string[]): Promise<number>;
+    type(key: string): Promise<string>;
+    expire(key: string, seconds: number): Promise<boolean>;
+    pexpire(key: string, ms: number): Promise<boolean>;
+    persist(key: string): Promise<boolean>;
+    /** Seconds left; -1 = no expiry, -2 = no such key. */
+    ttl(key: string): Promise<number>;
+    pttl(key: string): Promise<number>;
+    rename(from: string, to: string): Promise<void>;
+    dbsize(): Promise<number>;
+    /** One SCAN page. */
+    scan(cursor: string, opts?: {
+        match?: string;
+        count?: number;
+        type?: string;
+    }): Promise<{
+        cursor: string;
+        keys: string[];
+    }>;
+    /** Iterates every matching key without loading them all at once. */
+    scanIterator(opts?: {
+        match?: string;
+        count?: number;
+        type?: string;
+    }): AsyncGenerator<string>;
+    /** Sets fields; returns how many were new. */
+    hset(key: string, fields: Record<string, string | number>): Promise<number>;
+    hget(key: string, field: string): Promise<string | null>;
+    hmget(key: string, ...fields: string[]): Promise<Array<string | null>>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    hexists(key: string, field: string): Promise<boolean>;
+    hlen(key: string): Promise<number>;
+    hkeys(key: string): Promise<string[]>;
+    hvals(key: string): Promise<string[]>;
+    hincrBy(key: string, field: string, by?: number): Promise<number>;
+    hincrByFloat(key: string, field: string, by: number): Promise<number>;
+    lpush(key: string, ...values: Array<string | number>): Promise<number>;
+    rpush(key: string, ...values: Array<string | number>): Promise<number>;
+    lpop(key: string): Promise<string | null>;
+    rpop(key: string): Promise<string | null>;
+    lrange(key: string, start?: number, stop?: number): Promise<string[]>;
+    llen(key: string): Promise<number>;
+    ltrim(key: string, start: number, stop: number): Promise<void>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    srem(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    sismember(key: string, member: string): Promise<boolean>;
+    scard(key: string): Promise<number>;
+    spop(key: string): Promise<string | null>;
+    /** Adds or updates members; returns how many were new. */
+    zadd(key: string, members: Array<{
+        member: string;
+        score: number;
+    }>): Promise<number>;
+    zincrBy(key: string, member: string, by?: number): Promise<number>;
+    zscore(key: string, member: string): Promise<number | null>;
+    zrank(key: string, member: string): Promise<number | null>;
+    zrem(key: string, ...members: string[]): Promise<number>;
+    zcard(key: string): Promise<number>;
+    /** Members by rank, lowest score first (or highest first with `reverse`). */
+    zrange(key: string, start?: number, stop?: number, opts?: {
+        reverse?: boolean;
+    }): Promise<Array<{
+        member: string;
+        score: number;
+    }>>;
+    /** Members with min <= score <= max. Use `-inf` / `+inf` or `(5` for exclusive bounds. */
+    zrangeByScore(key: string, min: number | string, max: number | string, opts?: {
+        offset?: number;
+        count?: number;
+    }): Promise<string[]>;
+    zpopMin(key: string): Promise<{
+        member: string;
+        score: number;
+    } | null>;
+    /** Runs a Lua script. */
+    eval(script: string, keys?: string[], args?: Array<string | number>): Promise<Reply>;
+    /** Returns the number of subscribers that received it. */
+    publish(channel: string, message: string): Promise<number>;
+    /** A subscriber with its own connection and the same settings. */
+    subscriber(overrides?: SnugKvClientOptions): SnugKvSubscriber;
+    /** Builds a MULTI/EXEC block that is sent in one write, so other callers cannot interleave. */
+    tx(): Transaction;
+    /** @internal */
+    execBlock(commands: Arg[][]): Promise<Reply[]>;
     static xaddArgs(key: string, fields: Record<string, string>, opts?: XAddOptions): Arg[];
     xadd(key: string, fields: Record<string, string>, opts?: XAddOptions): Promise<string>;
     xlen(key: string): Promise<number>;