ts-prorm-orm 1.1.0

package/dist/nosql/hbase/index.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HBaseStore = void 0;
+/**
+ * Apache HBase store.
+ *
+ * HBase is a wide-column, sorted-map distributed store built on top of HDFS,
+ * modelled on Google's Bigtable paper. Data is addressed by a `(row key,
+ * column family, column qualifier, timestamp)` tuple: rows are identified by
+ * an arbitrary byte-string row key (kept in sorted order), and each row holds
+ * cells grouped into a small, fixed set of column families, with an unbounded
+ * number of qualifiers per family created on the fly at write time. There is
+ * no fixed schema beyond the family list, no joins, no secondary indexes, and
+ * no arbitrary WHERE filtering — reads are either single-row gets by row key
+ * or range scans over the sorted key space. None of that fits the SQL-shaped
+ * `Dialect` interface (`src/dialects/dialect.ts`), so this store implements
+ * the minimal `NoSqlStore` marker interface (`src/nosql/store.ts`) and exposes
+ * HBase's own row/cell operations directly.
+ *
+ * Built on the `hbase` npm package (an HBase Stargate / REST-gateway client).
+ * That driver exposes a fluent surface — `client.table(name).row(key).put(...)`
+ * and `client.table(name).scan(...)` — with Node-style `(err, result)`
+ * callbacks. This store assumes that shape and promisifies each call. The
+ * driver is an optional peer dependency loaded lazily inside `connect()` (via
+ * `require`) so importing this module never forces the driver to be installed;
+ * tests inject a pre-built mock `client` instead.
+ *
+ * Assumed driver call surface (from the `hbase` REST client):
+ *   client.table(name).create({ ColumnSchema: [{ name }, ...] }, cb)
+ *   client.table(name).row(key).put(column, value, cb)          // single cell
+ *   client.table(name).row(key).put(columns, values, cb)        // multi cell
+ *   client.table(name).row(key).get(cb)                         // -> cells
+ *   client.table(name).row(key).delete(cb)
+ *   client.table(name).scan(options, cb)                        // -> rows
+ * A cell/column is addressed as `'family:qualifier'`, matching HBase's own
+ * column naming.
+ */
+const errors_1 = require("../../errors");
+/**
+ * `HBaseStore` wraps an `hbase` REST-gateway client and exposes HBase's
+ * row/cell surface: `put`/`get`/`deleteRow` for single-row operations, `scan`
+ * for range reads over the sorted key space, and `createTable` for defining a
+ * table's column families. Column cells are addressed as `'family:qualifier'`.
+ */
+class HBaseStore {
+    constructor(options = {}) {
+        this.name = 'hbase';
+        this.library = 'hbase';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // NoSqlStore lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            let client = this.options.client;
+            if (!client) {
+                // Lazy-load the optional driver so importing this module never
+                // requires `hbase` to be installed. Tests inject a mock `client`
+                // above and never reach this branch.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const hbase = require('hbase');
+                client = hbase({
+                    host: this.options.host,
+                    port: this.options.port,
+                    ...this.options.clientOptions,
+                });
+            }
+            this.client = client;
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to connect to HBase: ${parent.message}`, {
+                parent,
+                database: 'hbase',
+                host: this.options.host,
+            });
+        }
+    }
+    /**
+     * The `hbase` REST client is stateless (each call is an HTTP request), so
+     * there is no socket to tear down; `disconnect()` simply drops the reference
+     * and flips `connected` to false.
+     */
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `hbase` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('HBase client is not connected. Call connect() first.', {
+                database: 'hbase',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `HBase ${action} failed: ${parent.message}` });
+    }
+    // ---------------------------------------------------------------------
+    // Row / cell operations
+    // ---------------------------------------------------------------------
+    /**
+     * Writes (puts) one or more cells into a single row. `data` maps
+     * `'family:qualifier'` column keys to values, e.g.
+     * `{ 'cf:name': 'alice', 'cf:age': 30 }`. Passed to the driver as parallel
+     * `columns`/`values` arrays via `table(table).row(row).put(...)`.
+     */
+    async put(table, row, data) {
+        const client = this.requireClient();
+        const columns = Object.keys(data);
+        if (columns.length === 0) {
+            throw new errors_1.DatabaseError('put() requires at least one column', {
+                original: 'empty put data',
+            });
+        }
+        const values = columns.map((c) => data[c]);
+        try {
+            return await new Promise((resolve, reject) => {
+                client
+                    .table(table)
+                    .row(row)
+                    .put(columns, values, (err, result) => err ? reject(err) : resolve(result));
+            });
+        }
+        catch (err) {
+            throw this.wrapError(`put on '${table}' row '${row}'`, err);
+        }
+    }
+    /**
+     * Reads a single row by key via `table(table).row(row).get(...)`, returning
+     * the row's cells as the driver surfaces them (an array of
+     * `{ column, timestamp, $ }` cell descriptors for the `hbase` REST client).
+     */
+    async get(table, row) {
+        const client = this.requireClient();
+        try {
+            return await new Promise((resolve, reject) => {
+                client
+                    .table(table)
+                    .row(row)
+                    .get((err, cells) => (err ? reject(err) : resolve(cells)));
+            });
+        }
+        catch (err) {
+            throw this.wrapError(`get on '${table}' row '${row}'`, err);
+        }
+    }
+    /** Deletes an entire row (all its cells) via `table(table).row(row).delete(...)`. */
+    async deleteRow(table, row) {
+        const client = this.requireClient();
+        try {
+            return await new Promise((resolve, reject) => {
+                client
+                    .table(table)
+                    .row(row)
+                    .delete((err, result) => (err ? reject(err) : resolve(result)));
+            });
+        }
+        catch (err) {
+            throw this.wrapError(`deleteRow on '${table}' row '${row}'`, err);
+        }
+    }
+    /**
+     * Range-scans a table via `table(table).scan(options, ...)`, returning the
+     * matching rows. Since HBase keeps row keys sorted, `startRow`/`endRow`
+     * define an efficient contiguous range; `columns` restricts which families/
+     * qualifiers are read. Returns the rows as the driver surfaces them.
+     */
+    async scan(table, opts = {}) {
+        const client = this.requireClient();
+        try {
+            return await new Promise((resolve, reject) => {
+                client
+                    .table(table)
+                    .scan(opts, (err, rows) => (err ? reject(err) : resolve(rows)));
+            });
+        }
+        catch (err) {
+            throw this.wrapError(`scan on '${table}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Table lifecycle
+    // ---------------------------------------------------------------------
+    /**
+     * Creates a table with the given column families via
+     * `table(table).create(...)`. `families` is the list of column family names
+     * (e.g. `['cf', 'meta']`); each is sent to the driver as an HBase
+     * `ColumnSchema` entry. A table must declare its families up front — unlike
+     * qualifiers, families cannot be added implicitly at write time.
+     */
+    async createTable(table, families) {
+        const client = this.requireClient();
+        if (!families || families.length === 0) {
+            throw new errors_1.DatabaseError('createTable() requires at least one column family', {
+                original: 'empty families list',
+            });
+        }
+        const schema = { ColumnSchema: families.map((name) => ({ name })) };
+        try {
+            return await new Promise((resolve, reject) => {
+                client
+                    .table(table)
+                    .create(schema, (err, result) => err ? reject(err) : resolve(result));
+            });
+        }
+        catch (err) {
+            throw this.wrapError(`createTable '${table}'`, err);
+        }
+    }
+}
+exports.HBaseStore = HBaseStore;
+exports.default = HBaseStore;

package/dist/nosql/ignite/index.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Apache Ignite store implementation.
+ *
+ * Apache Ignite is a distributed in-memory data grid / database. Data lives
+ * in distributed key/value caches partitioned across cluster nodes, accessed
+ * here via Ignite's thin-client protocol. Although Ignite also speaks SQL,
+ * this store targets its distributed-cache (key/value grid) surface, which
+ * does not fit the SQL-shaped `Dialect` interface, so it implements the
+ * minimal `NoSqlStore` marker interface and exposes cache operations
+ * (getCache/put/get/removeKey/getKeys/getSize) as a typed, promise-based API.
+ *
+ * Uses the `apache-ignite-client` driver (the official Node.js thin client).
+ * The driver is loaded lazily inside `connect()` (or supplied pre-built via
+ * the `client` option) so importing this module never requires
+ * `apache-ignite-client` to be installed unless an Ignite store is actually
+ * connected. Tests inject a mock client this way.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IgniteStore = exports.IGNITE_DB = void 0;
+const errors_1 = require("../../errors");
+/** Slug + human label for error/message context. Shared with `GridGainStore`. */
+exports.IGNITE_DB = 'ignite';
+function wrapConnectionError(err, database = exports.IGNITE_DB, label = 'Ignite') {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to ${label}: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database });
+}
+function wrapDatabaseError(err, action, label = 'Ignite') {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `${label} ${action} failed: ${parent.message}` });
+}
+/**
+ * `IgniteStore` wraps an `apache-ignite-client` `IgniteClient` and exposes
+ * its distributed-cache operations as a typed, promise-based API.
+ */
+class IgniteStore {
+    constructor(options = {}) {
+        this.name = 'ignite';
+        this.library = 'apache-ignite-client';
+        this.database = exports.IGNITE_DB;
+        this.label = 'Ignite';
+        this.client = null;
+        this.connected = false;
+        /** Resolved `CacheClient` handles, cached by name so `getMap` is idempotent. */
+        this.caches = new Map();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                this.client = this.options.client;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const mod = require('apache-ignite-client');
+                const IgniteClient = mod.IgniteClient ?? mod;
+                const IgniteClientConfiguration = mod.IgniteClientConfiguration;
+                const client = new IgniteClient();
+                const endpoints = this.options.endpoints ?? ['127.0.0.1:10800'];
+                const cfg = new IgniteClientConfiguration(...endpoints);
+                await client.connect(cfg);
+                this.client = client;
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.database, this.label);
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.disconnect();
+            }
+            catch {
+                // best-effort disconnect
+            }
+            this.client = null;
+        }
+        this.caches.clear();
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `apache-ignite-client` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError(`Not connected to ${this.label}`, { database: this.database });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Distributed cache operations
+    // ---------------------------------------------------------------------
+    /** Resolve (and cache) a distributed cache handle by name. */
+    async getMap(name) {
+        const cached = this.caches.get(name);
+        if (cached) {
+            return cached;
+        }
+        const client = this.requireClient();
+        try {
+            const cache = await client.getCache(name);
+            this.caches.set(name, cache);
+            return cache;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'getCache', this.label);
+        }
+    }
+    /** Put `value` under `key` in `map` (an Ignite cache handle). */
+    async mapPut(map, key, value) {
+        try {
+            return await map.put(key, value);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'cache put', this.label);
+        }
+    }
+    /** Get the value stored under `key` in `map` (or null if absent). */
+    async mapGet(map, key) {
+        try {
+            return await map.get(key);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'cache get', this.label);
+        }
+    }
+    /** Remove `key` from `map`. Returns Ignite's boolean success flag. */
+    async mapRemove(map, key) {
+        try {
+            return await map.removeKey(key);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'cache removeKey', this.label);
+        }
+    }
+    /** Return all keys currently in `map` as an array. */
+    async mapKeys(map) {
+        try {
+            return await map.getKeys();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'cache getKeys', this.label);
+        }
+    }
+    /** Return the number of entries in `map`. */
+    async mapSize(map) {
+        try {
+            return await map.getSize();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'cache getSize', this.label);
+        }
+    }
+}
+exports.IgniteStore = IgniteStore;
+exports.default = IgniteStore;

package/dist/nosql/immudb/index.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * immudb store implementation.
+ *
+ * immudb is an immutable, append-only key-value (and SQL) database with
+ * built-in cryptographic verification: every write is added to a tamper-
+ * evident Merkle-tree-backed log, and `verifiedSet`/`verifiedGet` return an
+ * inclusion/consistency proof the client checks locally, so a compromised
+ * server cannot lie about stored data without detection.
+ *
+ * immudb is a key-value ledger, not a SQL `Dialect`, so this class implements
+ * the minimal `NoSqlStore` marker interface plus the shared ledger surface
+ * (`append`/`get`/`history`/`verify`/`query`). Because immudb addresses
+ * records by key rather than by (table, row), `append`/`get`/`history`/
+ * `verify` treat their first argument as a key namespace and compose the
+ * immudb key as `<table>:<id>` (or just `<table>` when no id is given).
+ * `query` maps to immudb's embedded SQL engine (`sqlQuery`/`sqlExec`).
+ *
+ * ## Lazy driver loading
+ *
+ * The `immudb-node` package is loaded lazily inside `connect()`; importing
+ * this module never requires it. Tests inject a pre-built, already-logged-in
+ * client via `ImmudbStoreOptions.client`, bypassing the `require`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImmudbStore = void 0;
+const errors_1 = require("../../errors");
+/**
+ * `ImmudbStore` wraps an `immudb-node` client behind the shared ledger
+ * surface. `append` performs a `verifiedSet` (returning the write's
+ * transaction id), `get` a `verifiedGet`, `history` returns prior revisions
+ * of a key, `verify` returns the full verified-read response (value + proof),
+ * and `query` runs embedded SQL via `sqlQuery`.
+ */
+class ImmudbStore {
+    constructor(options = {}) {
+        this.name = 'immudb';
+        this.library = 'immudb-node';
+        this.client = null;
+        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 {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const mod = require('immudb-node');
+                const ImmudbClient = mod.default ?? mod.ImmudbClient ?? mod;
+                this.client = new ImmudbClient({
+                    host: this.options.host ?? '127.0.0.1',
+                    port: this.options.port ?? 3322,
+                });
+                if (typeof this.client.login === 'function') {
+                    await this.client.login({
+                        user: this.options.user ?? 'immudb',
+                        password: this.options.password ?? 'immudb',
+                    });
+                }
+                if (this.options.database && typeof this.client.useDatabase === 'function') {
+                    await this.client.useDatabase({ databasename: this.options.database });
+                }
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to connect to immudb: ${parent.message}`, {
+                parent,
+                database: 'immudb',
+            });
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                if (typeof this.client.close === 'function')
+                    await this.client.close();
+                else if (typeof this.client.shutdown === 'function')
+                    await this.client.shutdown();
+            }
+            catch {
+                // best-effort close
+            }
+        }
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `immudb-node` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to immudb. Call connect() first.', {
+                database: 'immudb',
+            });
+        }
+        return this.client;
+    }
+    /** Compose the immudb key from a (table, id) address. */
+    keyFor(table, id) {
+        return id === undefined || id === null || id === '' ? table : `${table}:${id}`;
+    }
+    encode(data) {
+        return typeof data === 'string' ? data : JSON.stringify(data);
+    }
+    async run(action, fn) {
+        this.requireClient();
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `immudb ${action} failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Ledger surface
+    // ---------------------------------------------------------------------
+    /**
+     * Append `data` under the key `<table>:<data.id>` (or `<table>` if `data`
+     * has no `id`) via a verified, tamper-evident write. Returns the write's
+     * transaction id/hash from immudb's response.
+     */
+    async append(table, data) {
+        const id = data?.id;
+        const key = this.keyFor(table, id === undefined ? undefined : String(id));
+        const client = this.requireClient();
+        const res = await this.run('append', () => client.verifiedSet({ key, value: this.encode(data) }));
+        return String(res?.transactionId ?? res?.id ?? res?.txId ?? res?.tx ?? key);
+    }
+    /** Verified read of the current value at `<table>:<id>` (or `<table>`). */
+    async get(table, id) {
+        const client = this.requireClient();
+        return this.run('get', () => client.verifiedGet({ key: this.keyFor(table, id) }));
+    }
+    /** Return every prior revision of the key `<table>:<id>` (or `<table>`). */
+    async history(table, id) {
+        const client = this.requireClient();
+        return this.run('history', () => client.history({ key: this.keyFor(table, id) }));
+    }
+    /**
+     * Verified read returning the full response - value plus the cryptographic
+     * inclusion proof immudb generates for `verifiedGet`. The presence of a
+     * resolved response (rather than a thrown verification error) is the proof
+     * that the value is consistent with the tamper-evident log.
+     */
+    async verify(table, id) {
+        const client = this.requireClient();
+        return this.run('verify', () => client.verifiedGet({ key: this.keyFor(table, id) }));
+    }
+    /** Run a SQL `statement` against immudb's embedded SQL engine (`sqlQuery`). */
+    async query(statement, params) {
+        const client = this.requireClient();
+        if (typeof client.sqlQuery !== 'function') {
+            throw new errors_1.DatabaseError('immudb client does not support sqlQuery()', { code: 'QUERY_ERROR' });
+        }
+        return this.run('query', () => client.sqlQuery({ sql: statement, params }));
+    }
+    /** Execute a SQL DDL/DML `statement` via `sqlExec` (no rows returned). */
+    async exec(statement, params) {
+        const client = this.requireClient();
+        if (typeof client.sqlExec !== 'function') {
+            throw new errors_1.DatabaseError('immudb client does not support sqlExec()', { code: 'QUERY_ERROR' });
+        }
+        return this.run('exec', () => client.sqlExec({ sql: statement, params }));
+    }
+}
+exports.ImmudbStore = ImmudbStore;
+exports.default = ImmudbStore;