ts-prorm-orm 1.1.0

package/dist/nosql/redpanda/index.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedpandaStore = void 0;
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, brokers) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Redpanda: ${parent.message}`;
+    return new errors_1.ConnectionError(message, {
+        parent,
+        database: 'redpanda',
+        host: brokers?.join(','),
+    });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/**
+ * `RedpandaStore` wraps a `kafkajs` client (Redpanda is Kafka-protocol
+ * compatible) and exposes the core streaming operations: producing messages,
+ * topic administration, and consumer subscriptions.
+ */
+class RedpandaStore {
+    constructor(options = {}) {
+        this.name = 'redpanda';
+        this.library = 'kafkajs';
+        this.client = null;
+        this.producer = null;
+        /** Consumers created via `subscribe()`, tracked so `disconnect()` can stop them all. */
+        this.consumers = [];
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                this.client = this.options.client;
+            }
+            else {
+                // Lazy-load the driver so importing this module doesn't require
+                // `kafkajs` to be installed unless a real connection is made.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { Kafka } = require('kafkajs');
+                this.client = new Kafka({
+                    clientId: this.options.clientId,
+                    brokers: this.options.brokers ?? [],
+                    ssl: this.options.ssl,
+                    sasl: this.options.sasl,
+                });
+            }
+            this.producer = this.client.producer();
+            await this.producer.connect();
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.producer = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.brokers);
+        }
+    }
+    async disconnect() {
+        // Stop consumers first so they stop pulling before the producer/client go.
+        for (const consumer of this.consumers.splice(0)) {
+            try {
+                await consumer.disconnect();
+            }
+            catch {
+                // Best-effort teardown - keep disconnecting the rest.
+            }
+        }
+        if (this.producer) {
+            try {
+                await this.producer.disconnect();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+            this.producer = null;
+        }
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `kafkajs` `Kafka` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Redpanda', { database: 'redpanda' });
+        }
+        return this.client;
+    }
+    requireProducer() {
+        if (!this.producer) {
+            throw new errors_1.ConnectionError('Not connected to Redpanda', { database: 'redpanda' });
+        }
+        return this.producer;
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * Produce one or more messages to `topic`. Returns kafkajs's record
+     * metadata (per-partition base offsets).
+     */
+    async produce(topic, messages) {
+        const producer = this.requireProducer();
+        try {
+            return await producer.send({ topic, messages });
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Redpanda produce to "${topic}" failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Topic administration
+    // ---------------------------------------------------------------------
+    /**
+     * Create `topic` via a short-lived admin connection. Returns kafkajs's
+     * boolean indicating whether the topic was newly created (`false` if it
+     * already existed).
+     */
+    async createTopic(topic, opts = {}) {
+        const client = this.requireClient();
+        const admin = client.admin();
+        try {
+            await admin.connect();
+            return await admin.createTopics({
+                topics: [
+                    {
+                        topic,
+                        numPartitions: opts.numPartitions,
+                        replicationFactor: opts.replicationFactor,
+                    },
+                ],
+            });
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Redpanda createTopic "${topic}" failed`);
+        }
+        finally {
+            try {
+                await admin.disconnect();
+            }
+            catch {
+                // Best-effort teardown of the admin connection.
+            }
+        }
+    }
+    /** List all topic names known to the cluster via a short-lived admin connection. */
+    async listTopics() {
+        const client = this.requireClient();
+        const admin = client.admin();
+        try {
+            await admin.connect();
+            return await admin.listTopics();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'Redpanda listTopics failed');
+        }
+        finally {
+            try {
+                await admin.disconnect();
+            }
+            catch {
+                // Best-effort teardown of the admin connection.
+            }
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Consuming
+    // ---------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    async subscribe(topics, handler, options = {}) {
+        const client = this.requireClient();
+        const topicList = Array.isArray(topics) ? topics : [topics];
+        const groupId = options.groupId ?? `${this.options.clientId ?? 'redpanda'}-group-${Date.now()}`;
+        const consumer = client.consumer({ groupId });
+        try {
+            await consumer.connect();
+            await consumer.subscribe({
+                topics: topicList,
+                fromBeginning: options.fromBeginning ?? false,
+            });
+            await consumer.run({ eachMessage: handler });
+            this.consumers.push(consumer);
+            return consumer;
+        }
+        catch (err) {
+            try {
+                await consumer.disconnect();
+            }
+            catch {
+                // Don't leak the half-set-up consumer's connection.
+            }
+            throw wrapDatabaseError(err, `Redpanda subscribe to "${topicList.join(',')}" failed`);
+        }
+    }
+}
+exports.RedpandaStore = RedpandaStore;
+exports.default = RedpandaStore;

package/dist/nosql/resque/index.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResqueStore = void 0;
+const errors_1 = require("../../errors");
+function wrapConnectionError(err) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Resque: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'resque' });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `Resque ${action} failed: ${parent.message}` });
+}
+/** Normalize a job spec into `{ name, args }`. */
+function toSpec(jobData) {
+    if (typeof jobData === 'string')
+        return { name: jobData, args: [] };
+    return { name: jobData.name, args: jobData.args ?? [] };
+}
+/**
+ * `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.
+ */
+class ResqueStore {
+    constructor(options = {}) {
+        this.name = 'resque';
+        this.library = 'node-resque';
+        this.driver = null;
+        this.queue = null;
+        this.connected = false;
+        this.workers = new Map();
+        /** Accumulated `{ jobName: handler }` map shared across workers. */
+        this.jobs = {};
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.queue) {
+            return;
+        }
+        try {
+            this.driver = this.options.client != null ? this.options.client : require('node-resque');
+            this.queue = new this.driver.Queue({ connection: this.connectionOpts }, this.jobs);
+            if (typeof this.queue.connect === 'function') {
+                await this.queue.connect();
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.queue = null;
+            this.driver = null;
+            this.connected = false;
+            throw wrapConnectionError(err);
+        }
+    }
+    async disconnect() {
+        for (const worker of this.workers.values()) {
+            try {
+                if (worker && typeof worker.end === 'function')
+                    await worker.end();
+            }
+            catch {
+                // Ignore teardown errors.
+            }
+        }
+        this.workers.clear();
+        try {
+            if (this.queue && typeof this.queue.end === 'function')
+                await this.queue.end();
+        }
+        catch {
+            // Ignore teardown errors.
+        }
+        this.queue = null;
+        this.driver = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.queue !== null;
+    }
+    /** Returns the underlying node-resque `Queue` for operations not wrapped here. */
+    getClient() {
+        return this.requireQueue();
+    }
+    requireQueue() {
+        if (!this.queue) {
+            throw new errors_1.ConnectionError('Not connected to Resque', { database: 'resque' });
+        }
+        return this.queue;
+    }
+    get connectionOpts() {
+        return this.options.connection ?? { host: '127.0.0.1', port: 6379 };
+    }
+    // ---------------------------------------------------------------------
+    // Queue operations
+    // ---------------------------------------------------------------------
+    /**
+     * 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`.
+     */
+    async enqueue(queue, jobData) {
+        try {
+            const { name, args } = toSpec(jobData);
+            await this.requireQueue().enqueue(queue, name, args);
+            return null;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'enqueue');
+        }
+    }
+    /**
+     * 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).
+     */
+    async process(queue, handler, opts = {}) {
+        try {
+            const existing = this.workers.get(queue);
+            if (existing)
+                return existing;
+            // node-resque looks up handlers by job name in the jobs map; register
+            // this handler (as a `perform` function) under the queue name.
+            this.jobs[queue] = { perform: handler };
+            const driver = this.driver;
+            if (!driver) {
+                throw new errors_1.ConnectionError('Not connected to Resque', { database: 'resque' });
+            }
+            const worker = new driver.Worker({ connection: this.connectionOpts, queues: [queue], ...opts }, this.jobs);
+            if (typeof worker.connect === 'function')
+                await worker.connect();
+            if (typeof worker.start === 'function')
+                worker.start();
+            this.workers.set(queue, worker);
+            return worker;
+        }
+        catch (err) {
+            if (err instanceof errors_1.ConnectionError)
+                throw err;
+            throw wrapDatabaseError(err, 'process');
+        }
+    }
+    /**
+     * 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.
+     */
+    async getJob(queue, id) {
+        try {
+            const list = await this.requireQueue().queued(queue, 0, -1);
+            const index = typeof id === 'number' ? id : Number(id);
+            return Array.isArray(list) ? (list[index] ?? null) : null;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'getJob');
+        }
+    }
+    /**
+     * Remove matching jobs from a queue via `queue.del(queue, name, args)`.
+     * `id` is the registered job name to delete.
+     */
+    async remove(queue, id) {
+        try {
+            return await this.requireQueue().del(queue, id);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'remove');
+        }
+    }
+    /** Return the number of jobs currently queued on a named queue. */
+    async stats(queue) {
+        try {
+            return await this.requireQueue().length(queue);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'stats');
+        }
+    }
+}
+exports.ResqueStore = ResqueStore;
+exports.default = ResqueStore;

package/dist/nosql/rethinkdb/index.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * RethinkDB store implementation.
+ *
+ * RethinkDB is a document store whose queries are built by chaining methods
+ * on a term-builder (`r`) and executed with a trailing `.run()` - e.g.
+ * `r.table('users').filter({ active: true }).run(conn)`. That fluent,
+ * function-composition query model is nothing like the SQL-shaped `Dialect`
+ * interface (no `query(sql)`, no identifier escaping, no relational DDL), so
+ * this class implements the minimal `NoSqlStore` marker interface for
+ * connection lifecycle and otherwise exposes RethinkDB's real surface
+ * directly: document CRUD, ReQL `filter` predicates, table/database
+ * creation, and a `run()` escape hatch for arbitrary ReQL terms.
+ *
+ * Uses the `rethinkdb-ts` driver. The driver is lazily `require`d inside
+ * `connect()` so importing this module never forces `rethinkdb-ts` to be
+ * installed; the term-builder (`r`) and/or a `connection` can also be
+ * injected via the constructor options (used by the tests, and handy when a
+ * pool is managed elsewhere), in which case `connect()` skips the require.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RethinkDBStore = void 0;
+const errors_1 = require("../../errors");
+const DEFAULT_HOST = 'localhost';
+const DEFAULT_PORT = 28015;
+const DEFAULT_DB = 'test';
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to RethinkDB: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'rethinkdb', host });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    // Keep the action context (e.g. "RethinkDB insert failed") but don't
+    // discard the real underlying driver error text - append it so callers
+    // inspecting `err.message` still see what actually went wrong.
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/**
+ * `RethinkDBStore` wraps the `rethinkdb-ts` term-builder (`r`) in a small,
+ * promise-based convenience layer over document CRUD, ReQL `filter`
+ * queries, and table/database creation, plus a `run()` escape hatch for
+ * arbitrary ReQL terms.
+ */
+class RethinkDBStore {
+    constructor(options = {}) {
+        this.name = 'rethinkdb';
+        this.library = 'rethinkdb-ts';
+        /** The `rethinkdb-ts` term-builder (`r`) once connected. */
+        this.r = null;
+        /** A single connection, when in single-connection (injected) mode. */
+        this.connection = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.r) {
+            return;
+        }
+        const host = this.options.host ?? DEFAULT_HOST;
+        const port = this.options.port ?? DEFAULT_PORT;
+        const db = this.options.db ?? DEFAULT_DB;
+        try {
+            // Prefer an injected term-builder; otherwise lazily require the driver
+            // so importing this module never forces `rethinkdb-ts` to be installed.
+            let r = this.options.r;
+            if (!r) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const mod = require('rethinkdb-ts');
+                r = mod.r;
+            }
+            if (this.options.connection) {
+                // Single-connection mode: run queries against the injected connection.
+                this.connection = this.options.connection;
+            }
+            else if (!this.options.r) {
+                // Real-driver path: stand up a driver-managed connection pool. (When
+                // `r` is injected without a connection - e.g. in tests - queries run
+                // via the injected `r`'s own pool and no pool is created here.)
+                await r.connectPool({ servers: [{ host, port }], db });
+            }
+            this.r = r;
+            this.connected = true;
+        }
+        catch (err) {
+            this.r = null;
+            this.connection = null;
+            this.connected = false;
+            throw wrapConnectionError(err, host);
+        }
+    }
+    async disconnect() {
+        try {
+            if (this.connection && typeof this.connection.close === 'function') {
+                await this.connection.close();
+            }
+            else if (this.r && typeof this.r.getPoolMaster === 'function') {
+                const poolMaster = this.r.getPoolMaster();
+                if (poolMaster && typeof poolMaster.drain === 'function') {
+                    await poolMaster.drain();
+                }
+            }
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'RethinkDB disconnect failed');
+        }
+        finally {
+            this.r = null;
+            this.connection = null;
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.r !== null;
+    }
+    /** Returns the underlying `rethinkdb-ts` term-builder (`r`). */
+    getClient() {
+        return this.requireR();
+    }
+    requireR() {
+        if (!this.r || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to RethinkDB. Call connect() first.', {
+                database: 'rethinkdb',
+                host: this.options.host,
+            });
+        }
+        return this.r;
+    }
+    /**
+     * Execute a built ReQL query. In single-connection mode the connection is
+     * passed to `.run(connection)`; with a driver-managed pool `.run()` needs
+     * no argument.
+     */
+    runQuery(query) {
+        return this.connection ? query.run(this.connection) : query.run();
+    }
+    async exec(build, action) {
+        const r = this.requireR();
+        try {
+            return await this.runQuery(build(r));
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `RethinkDB ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Document CRUD
+    // ---------------------------------------------------------------------
+    /** Insert a document (or array of documents) into `table`. */
+    async insert(table, doc) {
+        return this.exec((r) => r.table(table).insert(doc), 'insert');
+    }
+    /** Fetch a single document from `table` by its primary key. Resolves to `null` if not found. */
+    async get(table, id) {
+        return this.exec((r) => r.table(table).get(id), 'get');
+    }
+    /** Partially update the document with primary key `id` in `table`, merging `patch`. */
+    async update(table, id, patch) {
+        return this.exec((r) => r.table(table).get(id).update(patch), 'update');
+    }
+    /** Delete the document with primary key `id` from `table`. */
+    async delete(table, id) {
+        return this.exec((r) => r.table(table).get(id).delete(), 'delete');
+    }
+    /**
+     * Return all documents in `table` matching `predicate` as an array.
+     * `predicate` is any ReQL `filter` argument - a match object
+     * (`{ active: true }`) or a predicate function (`row => row('age').gt(18)`).
+     * The result is materialized (cursor drained to an array) before returning.
+     */
+    async filter(table, predicate) {
+        const result = await this.exec((r) => r.table(table).filter(predicate), 'filter');
+        return this.toArray(result);
+    }
+    /** Drain a ReQL cursor to an array (arrays and plain values are passed through). */
+    async toArray(result) {
+        if (result && typeof result.toArray === 'function') {
+            return await result.toArray();
+        }
+        if (Array.isArray(result)) {
+            return result;
+        }
+        return result == null ? [] : [result];
+    }
+    // ---------------------------------------------------------------------
+    // Schema / administration
+    // ---------------------------------------------------------------------
+    /**
+     * Create a table. Pass a single `name` to create it in the connection's
+     * default database, or `(db, name)` to create it in a specific database.
+     */
+    async createTable(dbOrName, name) {
+        if (name !== undefined) {
+            return this.exec((r) => r.db(dbOrName).tableCreate(name), 'createTable');
+        }
+        return this.exec((r) => r.tableCreate(dbOrName), 'createTable');
+    }
+    /** Create a database. */
+    async createDatabase(name) {
+        return this.exec((r) => r.dbCreate(name), 'createDatabase');
+    }
+    // ---------------------------------------------------------------------
+    // Escape hatch
+    // ---------------------------------------------------------------------
+    /**
+     * Run an arbitrary ReQL `query` term (built from `getClient()`), for
+     * operations not wrapped here. In single-connection mode the store's
+     * connection is supplied to `.run()` automatically.
+     */
+    async run(query) {
+        if (!this.connected) {
+            throw new errors_1.ConnectionError('Not connected to RethinkDB. Call connect() first.', {
+                database: 'rethinkdb',
+                host: this.options.host,
+            });
+        }
+        try {
+            return await this.runQuery(query);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'RethinkDB run failed');
+        }
+    }
+}
+exports.RethinkDBStore = RethinkDBStore;
+exports.default = RethinkDBStore;