ts-prorm-orm 1.1.0 → 1.2.0

package/dist/nosql/redis/index.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Redis store implementation.
+ *
+ * Redis is a key-value store with several typed data structures (strings,
+ * hashes, lists, sets, sorted sets, streams) plus pub/sub and pipelining. It has no
+ * query language and does not fit the SQL-shaped `Dialect` interface, so
+ * this class implements the minimal `NoSqlStore` marker interface and
+ * exposes Redis's real operations grouped by data structure instead of
+ * forcing everything into a `query(sql)` shape.
+ *
+ * Uses the `ioredis` driver.
+ */
+import type Redis from 'ioredis';
+import type { RedisOptions, ChainableCommander } from 'ioredis';
+import { NoSqlStore } from '../store';
+/**
+ * Connection options for `RedisStore`.
+ *
+ * Accepts either a connection URL (`redis://` / `rediss://`) or standard
+ * ioredis `RedisOptions` (host/port/password/db/tls/etc). All of ioredis's
+ * `RedisOptions` fields are passed straight through.
+ */
+export type RedisStoreOptions = ({
+    url: string;
+} & Partial<RedisOptions>) | (RedisOptions & {
+    url?: undefined;
+});
+/** Options for `set()`. */
+export interface SetOptions {
+    /** Expire after this many seconds. */
+    ex?: number;
+    /** Expire after this many milliseconds. */
+    px?: number;
+    /** Only set the key if it does not already exist. */
+    nx?: boolean;
+    /** Only set the key if it already exists. */
+    xx?: boolean;
+    /** Retain the key's existing TTL. */
+    keepttl?: boolean;
+}
+/** A single member/score pair for sorted-set commands. */
+export interface ZMember {
+    score: number;
+    member: string;
+}
+/** Options for `zrange()`/`zrangebyscore()`. */
+export interface ZRangeOptions {
+    withScores?: boolean;
+    /** Reverse iteration order (ZREVRANGE-equivalent behavior for zrange). */
+    rev?: boolean;
+    limit?: {
+        offset: number;
+        count: number;
+    };
+}
+/** A single Redis Stream entry: an auto/explicit ID plus its field/value pairs. */
+export interface StreamEntry {
+    id: string;
+    fields: Record<string, string>;
+}
+/** A `xread`/`xreadgroup` result for one stream key. */
+export interface StreamReadResult {
+    key: string;
+    entries: StreamEntry[];
+}
+/** Options for `xread()`/`xreadgroup()`. */
+export interface XReadOptions {
+    /** Max number of entries to return per stream. */
+    count?: number;
+    /** Block for up to this many milliseconds waiting for new entries (0 = block forever). */
+    block?: number;
+}
+/** Trim strategy for `xtrim()`. */
+export type XTrimStrategy = 'MAXLEN' | 'MINID';
+/**
+ * `RedisStore` wraps an `ioredis` client and exposes Redis's data-structure
+ * commands (string/hash/list/set/sorted-set/stream), pub/sub, and
+ * pipelining as a typed, promise-based API.
+ */
+export declare class RedisStore implements NoSqlStore {
+    readonly name = "redis";
+    readonly library = "ioredis";
+    private readonly options;
+    private client;
+    private subscriber;
+    private connected;
+    /**
+     * Per-channel handlers for the shared subscriber connection. A single
+     * `message` listener is attached once and dispatches to the handler
+     * registered for the incoming message's channel, so each `subscribe()`
+     * call's handler only ever receives messages for its own channel.
+     */
+    private readonly channelHandlers;
+    /**
+     * Per-pattern handlers for the shared subscriber connection, mirroring
+     * `channelHandlers` but for `PSUBSCRIBE`/`PUNSUBSCRIBE`.
+     */
+    private readonly patternHandlers;
+    constructor(options?: RedisStoreOptions);
+    private createClient;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `ioredis` client for anything not wrapped here. */
+    getClient(): Redis;
+    private requireClient;
+    private exec;
+    /** Serialize a value with `JSON.stringify` and `SET` it. */
+    setJSON<T>(key: string, value: T, options?: SetOptions): Promise<'OK' | null>;
+    /** `GET` a key and `JSON.parse` it. Returns `null` if the key is missing. */
+    getJSON<T>(key: string): Promise<T | null>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string | number, options?: SetOptions): Promise<'OK' | null>;
+    del(...keys: string[]): Promise<number>;
+    exists(...keys: string[]): Promise<number>;
+    incr(key: string): Promise<number>;
+    incrby(key: string, amount: number): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    ttl(key: string): Promise<number>;
+    hget(key: string, field: string): Promise<string | null>;
+    hset(key: string, fields: Record<string, string | number>): Promise<number>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    hincrby(key: string, field: string, amount: number): Promise<number>;
+    lpush(key: string, ...values: (string | number)[]): Promise<number>;
+    rpush(key: string, ...values: (string | number)[]): Promise<number>;
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    lpop(key: string, count?: number): Promise<string | string[] | null>;
+    rpop(key: string, count?: number): Promise<string | string[] | null>;
+    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>;
+    zadd(key: string, ...members: ZMember[]): Promise<number>;
+    zrange(key: string, start: number, stop: number, options?: ZRangeOptions): Promise<string[]>;
+    zrangebyscore(key: string, min: number | string, max: number | string, options?: Omit<ZRangeOptions, 'rev'>): Promise<string[]>;
+    zrem(key: string, ...members: string[]): Promise<number>;
+    zscore(key: string, member: string): Promise<string | null>;
+    /**
+     * `XADD` - append an entry to a stream, creating it if it doesn't exist.
+     * Pass `'*'` as `id` to let Redis auto-generate a monotonic
+     * `<ms>-<seq>` ID (the common case); returns the ID that was assigned.
+     */
+    xadd(key: string, id: string, fields: Record<string, string | number>): Promise<string>;
+    /** `XRANGE` - read entries with IDs between `start` and `end` (inclusive), in ID order. Use `'-'`/`'+'` for the full range. */
+    xrange(key: string, start: string, end: string, count?: number): Promise<StreamEntry[]>;
+    /** `XREVRANGE` - like `xrange()` but in reverse ID order; `start` is the higher/first ID, `end` the lower/last. */
+    xrevrange(key: string, start: string, end: string, count?: number): Promise<StreamEntry[]>;
+    /**
+     * `XREAD` - read entries newer than `ids` from one or more streams.
+     * `keys[i]` is paired with `ids[i]`; pass `'$'` for an ID to only read
+     * entries added after the call starts, or `'0'` to read from the
+     * beginning. With `options.block`, blocks (up to that many ms, or
+     * forever if `0`) waiting for new entries instead of returning
+     * immediately. Returns `null` if nothing matched (e.g. a non-blocking
+     * read found nothing new).
+     */
+    xread(keys: string[], ids: string[], options?: XReadOptions): Promise<StreamReadResult[] | null>;
+    /** `XLEN` - number of entries in a stream. */
+    xlen(key: string): Promise<number>;
+    /** `XDEL` - remove specific entries from a stream by ID. Returns the number actually removed. */
+    xdel(key: string, ids: string[]): Promise<number>;
+    /**
+     * `XTRIM` - trim a stream to (approximately) `threshold` entries
+     * (`'MAXLEN'`) or drop entries older than a given ID (`'MINID'`).
+     * Returns the number of entries removed.
+     */
+    xtrim(key: string, strategy: XTrimStrategy, threshold: number | string): Promise<number>;
+    /**
+     * `XGROUP CREATE` - create a consumer group on a stream, starting
+     * delivery from `id` (default `'$'`, i.e. only new entries). Creates the
+     * stream first (via `MKSTREAM`) if it doesn't exist yet.
+     */
+    xgroupCreate(key: string, groupName: string, id?: string): Promise<'OK'>;
+    /**
+     * `XREADGROUP` - read entries from one or more streams as a named
+     * consumer within a consumer group, so entries are tracked in the
+     * group's pending-entries list until `xack()`'d. Pass `'>'` for an ID to
+     * receive only entries never delivered to this group; any other ID
+     * re-reads this consumer's already-delivered-but-unacked entries.
+     */
+    xreadgroup(groupName: string, consumerName: string, keys: string[], ids: string[], options?: XReadOptions): Promise<StreamReadResult[] | null>;
+    /** `XACK` - acknowledge that a consumer group has finished processing the given entry IDs. */
+    xack(key: string, groupName: string, ids: string[]): Promise<number>;
+    /**
+     * `EVAL` - run a Lua `script` server-side, atomically. `keys` are passed
+     * as Redis's `KEYS[1..N]` (and count toward the `numkeys` argument),
+     * `args` as `ARGV[1..N]`. Prefer `evalsha()` once a script has been
+     * cached (via `scriptLoad()` or a prior `eval()`) to avoid resending the
+     * source on every call.
+     */
+    eval<T = unknown>(script: string, keys?: string[], args?: (string | number)[]): Promise<T>;
+    /**
+     * `EVALSHA` - run a previously cached Lua script by its SHA1 digest
+     * (see `scriptLoad()`), avoiding the cost of resending the script body.
+     * Redis replies with a `NOSCRIPT` error (surfaced here as a
+     * `DatabaseError`) if the script isn't cached on the server.
+     */
+    evalsha<T = unknown>(sha1: string, keys?: string[], args?: (string | number)[]): Promise<T>;
+    /**
+     * `SCRIPT LOAD` - cache a Lua script on the server without executing it,
+     * returning its SHA1 digest for later `evalsha()` calls.
+     */
+    scriptLoad(script: string): Promise<string>;
+    /** `PFADD` - add elements to a HyperLogLog. Returns `1` if the estimated cardinality changed, `0` otherwise. */
+    pfadd(key: string, ...elements: string[]): Promise<number>;
+    /** `PFCOUNT` - the approximate cardinality of one HyperLogLog, or the union of several. */
+    pfcount(...keys: string[]): Promise<number>;
+    /** `PFMERGE` - merge one or more source HyperLogLogs into `destKey` (created/overwritten as the union). */
+    pfmerge(destKey: string, ...sourceKeys: string[]): Promise<'OK'>;
+    publish(channel: string, message: string): Promise<number>;
+    /**
+     * Subscribe to a channel and invoke `handler` for each message received.
+     *
+     * Pub/sub requires a dedicated connection in Redis (a subscribed
+     * connection can't issue other commands), so this lazily creates a
+     * second `ioredis` client reusing the same connection options and keeps
+     * it alive for the lifetime of the store (or until `unsubscribe`/
+     * `disconnect` is called).
+     */
+    /**
+     * Lazily create the shared subscriber connection and attach the
+     * `message`/`pmessage` dispatch listeners exactly once. Both `subscribe()`
+     * and `psubscribe()` share this single connection (a subscribed Redis
+     * connection can't issue other commands, so both plain and pattern
+     * subscriptions ride the same dedicated socket).
+     */
+    private ensureSubscriber;
+    subscribe(channel: string, handler: (message: string, channel: string) => void): Promise<void>;
+    unsubscribe(channel?: string): Promise<void>;
+    /**
+     * `PSUBSCRIBE` - subscribe to all channels matching a glob-style `pattern`
+     * (e.g. `news.*`, `__keyevent@0__:expired`) and invoke `handler` for each
+     * matching message. This is the standard mechanism for consuming Redis
+     * keyspace notifications (e.g. subscribing to
+     * `__keyevent@0__:expired` to react to key expirations), where the
+     * concrete channel name varies and only a pattern subscription can catch
+     * all of them. Shares the same lazily-created subscriber connection as
+     * `subscribe()`.
+     */
+    psubscribe(pattern: string, handler: (message: string, channel: string, pattern: string) => void): Promise<void>;
+    /**
+     * `PUNSUBSCRIBE` - stop receiving messages for `pattern` (or every pattern
+     * subscription, if omitted). Closes the shared subscriber connection once
+     * both the channel and pattern handler sets are empty.
+     */
+    punsubscribe(pattern?: string): Promise<void>;
+    /** Tear down the shared subscriber connection once nothing is subscribed through it. */
+    private closeSubscriberIfIdle;
+    /**
+     * Queue multiple commands and send them in a single round trip. Unlike
+     * `multi()`, commands are not guaranteed atomic — a failure in one
+     * command does not abort the others. Returns the ioredis chainable
+     * commander; call `.exec()` to run it.
+     */
+    pipeline(): ChainableCommander;
+    /**
+     * Queue multiple commands to run atomically (Redis `MULTI`/`EXEC`). This
+     * is Redis's substitute for cross-key transactions: all queued commands
+     * either all run or (if `.discard()` is called) none do, but there is no
+     * rollback of partial effects and no cross-command isolation the way a
+     * SQL transaction provides. Returns the ioredis chainable commander;
+     * call `.exec()` to run it.
+     */
+    multi(): ChainableCommander;
+}
+export default RedisStore;

package/dist/nosql/redis/index.js

@@ -11,12 +11,25 @@
  *
  * Uses the `ioredis` driver.
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RedisStore = void 0;
-const ioredis_1 = __importDefault(require("ioredis"));
+// Lazily-loaded `ioredis` driver. Required only when a connection is opened, so
+// importing this ORM never loads the ioredis driver.
+let ioredisCtor = null;
+function loadIoRedis() {
+    if (!ioredisCtor) {
+        try {
+            const mod = require('ioredis');
+            ioredisCtor = mod && mod.default ? mod.default : mod;
+        }
+        catch (err) {
+            throw new Error("The 'ioredis' package is required to use the Redis store but could not be loaded. " +
+                'Install it with `npm install ioredis`. Original error: ' +
+                (err instanceof Error ? err.message : String(err)));
+        }
+    }
+    return ioredisCtor;
+}
 const errors_1 = require("../../errors");
 function wrapConnectionError(err, host) {
     const parent = err instanceof Error ? err : new Error(String(err));
@@ -89,7 +102,8 @@ class RedisStore {
         // explicitly opt into eager connection and await `connect()` below to
         // surface connection failures immediately.
         const opts = { lazyConnect: true, ...rest };
-        return url ? new ioredis_1.default(url, opts) : new ioredis_1.default(opts);
+        const RedisCtor = loadIoRedis();
+        return url ? new RedisCtor(url, opts) : new RedisCtor(opts);
     }
     async connect() {
         if (this.connected && this.client) {

package/dist/nosql/redpanda/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Redpanda store implementation.
+ *
+ * Redpanda is a streaming data platform that is wire-compatible with the
+ * Apache Kafka protocol - it speaks the exact same protocol, so it reuses the
+ * `kafkajs` driver unchanged. Like Kafka, it has no query language and does
+ * not fit the SQL-shaped `Dialect` interface, so this class implements the
+ * minimal `NoSqlStore` marker interface and exposes Redpanda's real
+ * operations - producing to topics, creating/listing topics via the admin
+ * client, and subscribing consumers - instead of a `query(sql)` shape.
+ *
+ * Because Redpanda speaks the Kafka protocol, this store is a mirror of
+ * `KafkaStore`: same `kafkajs` client, same producer/consumer/admin surface.
+ * `kafkajs` is loaded lazily inside `connect()` (or supplied pre-built via
+ * `options.client`) so importing this module does not require the driver to
+ * be installed.
+ */
+import { NoSqlStore } from '../store';
+/**
+ * SASL authentication options passed straight through to kafkajs.
+ */
+export interface RedpandaSaslOptions {
+    mechanism: string;
+    username: string;
+    password: string;
+    [key: string]: unknown;
+}
+/**
+ * Connection options for `RedpandaStore`.
+ *
+ * Mirrors kafkajs's `Kafka` constructor options. `brokers` is the list of
+ * `host:port` seed brokers (Redpanda broker addresses). A pre-built kafkajs
+ * `Kafka` instance can be injected via `client`, in which case `connect()`
+ * uses it directly and skips loading the driver (this is how tests inject a
+ * mock).
+ */
+export interface RedpandaStoreOptions {
+    /** Client identifier reported to the broker. */
+    clientId?: string;
+    /** Seed broker list, e.g. `['localhost:9092']`. */
+    brokers?: string[];
+    /** Enable TLS, or pass a kafkajs TLS options object. */
+    ssl?: boolean | Record<string, unknown>;
+    /** SASL authentication configuration. */
+    sasl?: RedpandaSaslOptions;
+    /**
+     * A pre-built kafkajs `Kafka` instance. When provided, `connect()` uses it
+     * directly and does not `require('kafkajs')`.
+     */
+    client?: any;
+}
+/** A single message to produce to a topic. */
+export interface RedpandaMessage {
+    key?: string | Buffer | null;
+    value: string | Buffer | null;
+    partition?: number;
+    headers?: Record<string, string | Buffer>;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+/** Options for `createTopic()`. */
+export interface CreateTopicOptions {
+    numPartitions?: number;
+    replicationFactor?: number;
+}
+/** Options for `subscribe()`. */
+export interface SubscribeOptions {
+    /** Consumer group id. Defaults to a generated id. */
+    groupId?: string;
+    /** Consume from the beginning of the topic rather than the latest offset. */
+    fromBeginning?: boolean;
+}
+/**
+ * `RedpandaStore` wraps a `kafkajs` client (Redpanda is Kafka-protocol
+ * compatible) and exposes the core streaming operations: producing messages,
+ * topic administration, and consumer subscriptions.
+ */
+export declare class RedpandaStore implements NoSqlStore {
+    readonly name = "redpanda";
+    readonly library = "kafkajs";
+    private readonly options;
+    private client;
+    private producer;
+    /** Consumers created via `subscribe()`, tracked so `disconnect()` can stop them all. */
+    private readonly consumers;
+    private connected;
+    constructor(options?: RedpandaStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying `kafkajs` `Kafka` client for anything not wrapped here. */
+    getClient(): any;
+    private requireClient;
+    private requireProducer;
+    /**
+     * Produce one or more messages to `topic`. Returns kafkajs's record
+     * metadata (per-partition base offsets).
+     */
+    produce(topic: string, messages: RedpandaMessage[]): Promise<any>;
+    /**
+     * Create `topic` via a short-lived admin connection. Returns kafkajs's
+     * boolean indicating whether the topic was newly created (`false` if it
+     * already existed).
+     */
+    createTopic(topic: string, opts?: CreateTopicOptions): Promise<boolean>;
+    /** List all topic names known to the cluster via a short-lived admin connection. */
+    listTopics(): Promise<string[]>;
+    /**
+     * Subscribe a new consumer to `topics` and invoke `handler` for each
+     * message (kafkajs's `eachMessage` payload: `{ topic, partition, message }`).
+     * The consumer joins the group `options.groupId` (a generated id is used if
+     * omitted) and is tracked so `disconnect()` stops it. Returns the created
+     * kafkajs consumer.
+     */
+    subscribe(topics: string | string[], handler: (payload: any) => Promise<void> | void, options?: SubscribeOptions): Promise<any>;
+}
+export default RedpandaStore;

package/dist/nosql/resque/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Resque (node-resque) job/task-queue store.
+ *
+ * node-resque is a Redis-backed background-job system compatible with Ruby's
+ * Resque. A `Queue` enqueues jobs (a job class name plus args) into named
+ * queues, and a `Worker`/`MultiWorker` pulls jobs and runs the matching
+ * handler from a *jobs* map. It is not a database and does not fit the
+ * SQL-shaped `Dialect` interface, so this class implements the minimal
+ * `NoSqlStore` marker interface and exposes node-resque's real
+ * enqueue/worker operations instead.
+ *
+ * Uses the `node-resque` driver. It is an optional peer loaded lazily (via
+ * `require`) inside `connect()`, so importing this module does not require it
+ * to be installed unless you actually connect. A pre-built driver module
+ * (providing `Queue` and `Worker` constructors) can be injected via
+ * `ResqueStoreOptions.client`, in which case `connect()` adopts it and skips
+ * the `require` entirely (used by the unit tests to inject mocks).
+ */
+import type { NoSqlStore } from '../store';
+/** Connection options for `ResqueStore`. */
+export interface ResqueStoreOptions {
+    /**
+     * node-resque connection descriptor, e.g.
+     * `{ pkg: 'ioredis', host, port, database }`. Defaults to
+     * `{ host: '127.0.0.1', port: 6379 }`.
+     */
+    connection?: any;
+    /**
+     * A pre-built `node-resque` module (or a stand-in exposing `Queue` and
+     * `Worker` constructors). When provided, `connect()` adopts it and does not
+     * `require('node-resque')` — used for injecting mocks in tests.
+     */
+    client?: any;
+}
+/**
+ * A job descriptor for `enqueue()`: the registered job `name` plus its
+ * positional `args`. A bare string is treated as the job name with no args.
+ */
+export interface ResqueJobSpec {
+    name: string;
+    args?: any[];
+}
+/**
+ * `ResqueStore` wraps a node-resque `Queue` for producing and a pool of
+ * `Worker`s (one per queue name) for consuming, exposing the common queue
+ * surface.
+ */
+export declare class ResqueStore implements NoSqlStore {
+    readonly name = "resque";
+    readonly library = "node-resque";
+    private readonly options;
+    private driver;
+    private queue;
+    private connected;
+    private readonly workers;
+    /** Accumulated `{ jobName: handler }` map shared across workers. */
+    private readonly jobs;
+    constructor(options?: ResqueStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the underlying node-resque `Queue` for operations not wrapped here. */
+    getClient(): any;
+    private requireQueue;
+    private get connectionOpts();
+    /**
+     * Enqueue a job onto a named queue via `queue.enqueue(queue, name, args)`.
+     * node-resque assigns no client-visible job id, so this resolves to `null`.
+     */
+    enqueue(queue: string, jobData: ResqueJobSpec | string): Promise<null>;
+    /**
+     * Register a `Worker` on a queue that runs `handler` for jobs on it. The
+     * handler is added to the shared jobs map under the queue name, and one
+     * worker is cached per queue name (a repeat `process()` returns it).
+     */
+    process(queue: string, handler: (...args: any[]) => any | Promise<any>, opts?: any): Promise<any>;
+    /**
+     * List queued jobs on a named queue (node-resque `queue.queued(queue,
+     * start, stop)`). node-resque has no addressable per-id lookup, so `id` is
+     * interpreted as the 0-based index into the returned list.
+     */
+    getJob(queue: string, id: string | number): Promise<any>;
+    /**
+     * Remove matching jobs from a queue via `queue.del(queue, name, args)`.
+     * `id` is the registered job name to delete.
+     */
+    remove(queue: string, id: string): Promise<any>;
+    /** Return the number of jobs currently queued on a named queue. */
+    stats(queue: string): Promise<number>;
+}
+export default ResqueStore;