ts-prorm-orm 1.1.0

package/dist/nosql/beanstalkd/index.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * Beanstalkd job/work-queue store.
+ *
+ * Beanstalkd is a simple, fast work queue. Producers `put` jobs (opaque byte
+ * payloads) into named *tubes*; workers `reserve` jobs from the tubes they
+ * `watch`, do the work, then `delete` (destroy) them. It is not a database:
+ * there is no query language and it does not fit the SQL-shaped `Dialect`
+ * interface, so this class implements the minimal `NoSqlStore` marker
+ * interface and exposes Beanstalkd's real queue operations instead.
+ *
+ * Uses the `fivebeans` driver, whose client exposes a callback-style API
+ * (`client.put(pri, delay, ttr, payload, cb)` etc.); this store promisifies
+ * those calls internally so its surface is promise-based. `fivebeans` is an
+ * optional peer and is loaded lazily (via `require`) inside `connect()`, so
+ * importing this module does not require it to be installed unless you
+ * actually connect. A pre-built client can be injected via
+ * `BeanstalkdStoreOptions.client`, in which case `connect()` adopts it and
+ * skips the `require` entirely (used by the unit tests to inject a mock).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BeanstalkdStore = 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 Beanstalkd: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'beanstalkd' });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `Beanstalkd ${action} failed: ${parent.message}` });
+}
+/**
+ * `BeanstalkdStore` wraps a single `fivebeans` client and exposes the common
+ * queue surface (`enqueue`/`process`/`getJob`/`remove`/`stats`) over
+ * Beanstalkd tubes, promisifying the driver's callback API.
+ */
+class BeanstalkdStore {
+    constructor(options = {}) {
+        this.name = 'beanstalkd';
+        this.library = 'fivebeans';
+        this.client = null;
+        this.connected = false;
+        /** Set false on disconnect to break any running `process()` reserve loop. */
+        this.running = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client != null) {
+                // Injected client (e.g. a test mock): adopt it, don't require the driver.
+                this.client = this.options.client;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const fivebeans = require('fivebeans');
+                const host = this.options.host || '127.0.0.1';
+                const port = this.options.port || 11300;
+                this.client = new fivebeans.client(host, port);
+                await new Promise((resolve, reject) => {
+                    this.client.once('connect', () => resolve());
+                    this.client.once('error', (err) => reject(err));
+                    this.client.connect();
+                });
+            }
+            this.connected = true;
+            this.running = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err);
+        }
+    }
+    async disconnect() {
+        this.running = false;
+        try {
+            if (this.client && typeof this.client.end === 'function') {
+                this.client.end();
+            }
+            else if (this.client && typeof this.client.quit === 'function') {
+                this.client.quit();
+            }
+        }
+        catch {
+            // Ignore teardown errors.
+        }
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `fivebeans` client for operations not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Beanstalkd', { database: 'beanstalkd' });
+        }
+        return this.client;
+    }
+    /** Promisify a callback-style client method whose callback is `(err, result)`. */
+    call(method, ...args) {
+        const client = this.requireClient();
+        return new Promise((resolve, reject) => {
+            client[method](...args, (err, result) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve(result);
+            });
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Queue operations
+    // ---------------------------------------------------------------------
+    /**
+     * Enqueue a job into a tube. Selects the tube via `use()`, then `put()`s the
+     * (JSON-serialized) payload with the given priority/delay/ttr. Returns the
+     * job id assigned by the server.
+     */
+    async enqueue(queue, jobData, opts = {}) {
+        try {
+            await this.call('use', queue);
+            const payload = typeof jobData === 'string' ? jobData : JSON.stringify(jobData);
+            const priority = opts.priority ?? 0;
+            const delay = opts.delay ?? 0;
+            const ttr = opts.ttr ?? 60;
+            const jobId = await this.call('put', priority, delay, ttr, payload);
+            return jobId;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'enqueue');
+        }
+    }
+    /**
+     * Register a worker on a tube: `watch()` it, then loop `reserve()`ing jobs
+     * and invoking `handler(job)`. After the handler resolves the job is
+     * `destroy()`ed. The loop stops when the store disconnects.
+     */
+    async process(queue, handler) {
+        try {
+            await this.call('watch', queue);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'process');
+        }
+        const loop = async () => {
+            while (this.running && this.client) {
+                let job;
+                try {
+                    // fivebeans reserve callback is (err, jobid, payload).
+                    job = await new Promise((resolve, reject) => {
+                        this.client.reserve((err, id, payload) => {
+                            if (err)
+                                reject(err);
+                            else
+                                resolve({ id, payload: payload != null ? payload.toString() : '' });
+                        });
+                    });
+                }
+                catch {
+                    // Reserve failed (e.g. connection torn down): stop the loop.
+                    return;
+                }
+                try {
+                    await handler(job);
+                    await this.call('destroy', job.id);
+                }
+                catch {
+                    // Handler/destroy error: leave the job to time out and requeue.
+                }
+            }
+        };
+        // Fire-and-forget the reserve loop; it self-terminates on disconnect.
+        void loop();
+    }
+    /** Peek at a job by id, returning its id and payload (or `null` if absent). */
+    async getJob(_queue, id) {
+        try {
+            const payload = await new Promise((resolve, reject) => {
+                this.requireClient().peek(id, (err, _jobId, data) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve(data);
+                });
+            });
+            if (payload == null)
+                return null;
+            return { id, payload: payload.toString() };
+        }
+        catch (err) {
+            // fivebeans reports a missing job as a NOT_FOUND error; treat as null.
+            if (err instanceof Error && /not[_\s]?found/i.test(err.message)) {
+                return null;
+            }
+            throw wrapDatabaseError(err, 'getJob');
+        }
+    }
+    /** Delete (destroy) a job by id. */
+    async remove(_queue, id) {
+        try {
+            await this.call('destroy', id);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'remove');
+        }
+    }
+    /** Return per-tube statistics (`stats-tube`), e.g. ready/reserved/buried counts. */
+    async stats(queue) {
+        try {
+            return await this.call('stats_tube', queue);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'stats');
+        }
+    }
+}
+exports.BeanstalkdStore = BeanstalkdStore;
+exports.default = BeanstalkdStore;

package/dist/nosql/beequeue/index.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Bee-Queue job/task-queue store.
+ *
+ * Bee-Queue is a fast, lightweight Redis-backed job queue. A single `Queue`
+ * object (bound to a queue name) both produces jobs — `queue.createJob(data)`
+ * built into a job, then `.save()`d — and consumes them via
+ * `queue.process(handler)`. Each queue is a distinct object per name, so this
+ * store caches one `Queue` per queue name. 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 Bee-Queue's real
+ * create/process/getJob operations instead.
+ *
+ * Uses the `bee-queue` driver, whose default export is the `Queue`
+ * constructor. 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 `Queue` constructor can be
+ * injected via `BeeQueueStoreOptions.client`, in which case `connect()`
+ * adopts it and skips the `require` entirely (used by the unit tests to
+ * inject a mock).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BeeQueueStore = 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 Bee-Queue: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'beequeue' });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `Bee-Queue ${action} failed: ${parent.message}` });
+}
+/**
+ * `BeeQueueStore` manages a pool of Bee-Queue `Queue` objects keyed by queue
+ * name and exposes the common queue surface
+ * (`enqueue`/`process`/`getJob`/`remove`/`stats`).
+ */
+class BeeQueueStore {
+    constructor(options = {}) {
+        this.name = 'beequeue';
+        this.library = 'bee-queue';
+        this.Queue = null;
+        this.connected = false;
+        this.queues = new Map();
+        /** Queue names that already have a `process()` handler registered. */
+        this.processing = new Set();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.Queue) {
+            return;
+        }
+        try {
+            // Bee-Queue opens Redis connections per Queue; "connecting" here just
+            // resolves the Queue constructor. Injected client skips the require.
+            this.Queue = this.options.client != null ? this.options.client : require('bee-queue');
+            this.connected = true;
+        }
+        catch (err) {
+            this.Queue = null;
+            this.connected = false;
+            throw wrapConnectionError(err);
+        }
+    }
+    async disconnect() {
+        for (const queue of this.queues.values()) {
+            try {
+                if (queue && typeof queue.close === 'function')
+                    await queue.close();
+            }
+            catch {
+                // Ignore teardown errors.
+            }
+        }
+        this.queues.clear();
+        this.processing.clear();
+        this.Queue = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.Queue !== null;
+    }
+    /** Returns the underlying `bee-queue` `Queue` constructor. */
+    getClient() {
+        return this.requireDriver();
+    }
+    requireDriver() {
+        if (!this.Queue) {
+            throw new errors_1.ConnectionError('Not connected to Bee-Queue', { database: 'beequeue' });
+        }
+        return this.Queue;
+    }
+    get settings() {
+        return this.options.settings ?? { redis: { host: '127.0.0.1', port: 6379 } };
+    }
+    /** Get (creating and caching on first use) the `Queue` for a queue name. */
+    getQueue(name) {
+        const Queue = this.requireDriver();
+        let queue = this.queues.get(name);
+        if (!queue) {
+            queue = new Queue(name, this.settings);
+            this.queues.set(name, queue);
+        }
+        return queue;
+    }
+    // ---------------------------------------------------------------------
+    // Queue operations
+    // ---------------------------------------------------------------------
+    /**
+     * Build a job with `queue.createJob(data)`, apply any retry/delay/timeout
+     * options, `.save()` it, and return the id Bee-Queue assigns.
+     */
+    async enqueue(queue, jobData, opts = {}) {
+        try {
+            const q = this.getQueue(queue);
+            let job = q.createJob(jobData);
+            if (opts.retries !== undefined && typeof job.retries === 'function') {
+                job = job.retries(opts.retries);
+            }
+            if (opts.delayUntil !== undefined && typeof job.delayUntil === 'function') {
+                job = job.delayUntil(opts.delayUntil);
+            }
+            if (opts.timeout !== undefined && typeof job.timeout === 'function') {
+                job = job.timeout(opts.timeout);
+            }
+            const saved = await job.save();
+            // `save()` resolves with the job (carrying its assigned id).
+            return (saved ?? job)?.id;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'enqueue');
+        }
+    }
+    /**
+     * Register the worker handler for a queue via `queue.process(concurrency,
+     * handler)`. Bee-Queue allows only one `process()` per Queue object, so a
+     * repeat call on the same queue name is a no-op.
+     */
+    async process(queue, handler, opts = {}) {
+        try {
+            const q = this.getQueue(queue);
+            if (this.processing.has(queue))
+                return q;
+            if (opts.concurrency !== undefined) {
+                q.process(opts.concurrency, handler);
+            }
+            else {
+                q.process(handler);
+            }
+            this.processing.add(queue);
+            return q;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'process');
+        }
+    }
+    /** Fetch a job by id from the named queue (`queue.getJob(id)`). */
+    async getJob(queue, id) {
+        try {
+            return await this.getQueue(queue).getJob(id);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'getJob');
+        }
+    }
+    /**
+     * Remove a job by id from the named queue. Uses `queue.removeJob(id)` when
+     * available, otherwise fetches the job and calls `job.remove()`.
+     */
+    async remove(queue, id) {
+        try {
+            const q = this.getQueue(queue);
+            if (typeof q.removeJob === 'function') {
+                await q.removeJob(id);
+                return;
+            }
+            const job = await q.getJob(id);
+            if (job && typeof job.remove === 'function') {
+                await job.remove();
+            }
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'remove');
+        }
+    }
+    /**
+     * Return job counts by state for a queue. Uses `queue.getJobCounts()` when
+     * available, otherwise falls back to Bee-Queue's `queue.checkHealth()`.
+     */
+    async stats(queue) {
+        try {
+            const q = this.getQueue(queue);
+            if (typeof q.getJobCounts === 'function') {
+                return await q.getJobCounts();
+            }
+            return await q.checkHealth();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'stats');
+        }
+    }
+}
+exports.BeeQueueStore = BeeQueueStore;
+exports.default = BeeQueueStore;

package/dist/nosql/bigchaindb/index.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * BigchainDB store implementation.
+ *
+ * BigchainDB is a blockchain database: data is written as cryptographically
+ * signed, immutable **transactions** over **assets**. A CREATE transaction
+ * registers a new asset (with arbitrary immutable `asset.data` and mutable
+ * `metadata`); TRANSFER transactions spend prior outputs. Because every
+ * transaction is Ed25519-signed and content-addressed by its hash (`tx.id`),
+ * the ledger is append-only and tamper-evident by construction.
+ *
+ * BigchainDB is not a SQL `Dialect`, so this class implements the minimal
+ * `NoSqlStore` marker interface plus the shared ledger surface:
+ *  - `append(table, data)` -> build + sign + commit a CREATE transaction
+ *    whose asset carries `{ table, ...data }`, returning the new `tx.id`.
+ *  - `get(table, id)`      -> fetch a transaction by id.
+ *  - `history(table, id)`  -> list all transactions for the asset `id`.
+ *  - `verify(table, id)`   -> return the signed transaction (its signatures
+ *    and content hash are the proof of integrity).
+ *  - `query(text)`         -> full-text asset search (`searchAssets`).
+ *
+ * ## Lazy driver loading
+ *
+ * `bigchaindb-driver` is loaded lazily inside `connect()`. Tests inject a
+ * pre-built connection via `BigchaindbStoreOptions.client` and the transaction
+ * factory via `BigchaindbStoreOptions.transaction`, bypassing the `require`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BigchaindbStore = void 0;
+const errors_1 = require("../../errors");
+/**
+ * `BigchaindbStore` wraps a `bigchaindb-driver` connection + transaction
+ * factory behind the shared ledger surface.
+ */
+class BigchaindbStore {
+    constructor(options = {}) {
+        this.name = 'bigchaindb';
+        this.library = 'bigchaindb-driver';
+        this.conn = null;
+        this.txFactory = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.conn) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                this.conn = this.options.client;
+                this.txFactory = this.options.transaction ?? null;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const driver = require('bigchaindb-driver');
+                this.conn = new driver.Connection(this.options.url ?? 'http://localhost:9984/api/v1/', this.options.headers ?? {});
+                this.txFactory = this.options.transaction ?? driver.Transaction;
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.conn = null;
+            this.txFactory = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to connect to BigchainDB: ${parent.message}`, {
+                parent,
+                database: 'bigchaindb',
+            });
+        }
+    }
+    async disconnect() {
+        this.conn = null;
+        this.txFactory = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.conn !== null;
+    }
+    /** Returns the underlying `Connection` for anything not wrapped here. */
+    getClient() {
+        return this.requireConn();
+    }
+    requireConn() {
+        if (!this.conn || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to BigchainDB. Call connect() first.', {
+                database: 'bigchaindb',
+            });
+        }
+        return this.conn;
+    }
+    requireTxFactory() {
+        if (!this.txFactory) {
+            throw new errors_1.DatabaseError('BigchainDB Transaction factory unavailable. Provide `transaction` in options.', { code: 'QUERY_ERROR' });
+        }
+        return this.txFactory;
+    }
+    // ---------------------------------------------------------------------
+    // Ledger surface
+    // ---------------------------------------------------------------------
+    /**
+     * Build, sign and commit a CREATE transaction registering a new asset whose
+     * immutable `asset.data` is `{ table, ...data }`. Returns the resulting
+     * transaction id (its content hash). Requires `options.keypair`.
+     */
+    async append(table, data) {
+        const conn = this.requireConn();
+        const tx = this.requireTxFactory();
+        const keypair = this.options.keypair;
+        if (!keypair) {
+            throw new errors_1.DatabaseError('BigchaindbStore.append requires a `keypair` to sign transactions', {
+                code: 'INVALID_CONNECTION',
+            });
+        }
+        try {
+            const assetData = { table, ...data };
+            const output = tx.makeOutput(tx.makeEd25519Condition(keypair.publicKey));
+            const created = tx.makeCreateTransaction(assetData, { table }, [output], keypair.publicKey);
+            const signed = tx.signTransaction(created, keypair.privateKey);
+            const committed = await conn.postTransactionCommit(signed);
+            return String(committed?.id ?? signed?.id ?? '');
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `BigchainDB append failed: ${parent.message}` });
+        }
+    }
+    /** Fetch a transaction by its id (`get(_, id)`). Returns the signed transaction. */
+    async get(_table, id) {
+        const conn = this.requireConn();
+        try {
+            return await conn.getTransaction(id);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `BigchainDB get failed: ${parent.message}` });
+        }
+    }
+    /**
+     * List every transaction (CREATE + subsequent TRANSFERs) for the asset `id`
+     * - the append-only history of that asset. Uses `listTransactions`.
+     */
+    async history(_table, id) {
+        const conn = this.requireConn();
+        if (typeof conn.listTransactions !== 'function') {
+            throw new errors_1.DatabaseError('BigchainDB connection does not support listTransactions()', {
+                code: 'QUERY_ERROR',
+            });
+        }
+        try {
+            return await conn.listTransactions({ asset_id: id });
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `BigchainDB history failed: ${parent.message}` });
+        }
+    }
+    /**
+     * Return the signed transaction `id` as its own proof of integrity: its
+     * Ed25519 signatures and content-hash id are what any party independently
+     * re-verifies against the asset data. Returns `{ id, valid, transaction }`.
+     */
+    async verify(_table, id) {
+        const conn = this.requireConn();
+        try {
+            const transaction = await conn.getTransaction(id);
+            return { id, valid: transaction != null, transaction };
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `BigchainDB verify failed: ${parent.message}` });
+        }
+    }
+    /** Full-text search over asset data via `searchAssets`. */
+    async query(text) {
+        const conn = this.requireConn();
+        if (typeof conn.searchAssets !== 'function') {
+            throw new errors_1.DatabaseError('BigchainDB connection does not support searchAssets()', {
+                code: 'QUERY_ERROR',
+            });
+        }
+        try {
+            return await conn.searchAssets(text);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `BigchainDB query failed: ${parent.message}` });
+        }
+    }
+}
+exports.BigchaindbStore = BigchaindbStore;
+exports.default = BigchaindbStore;