ts-prorm-orm 1.1.0

package/dist/nosql/bigtable/index.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BigtableStore = void 0;
+/**
+ * Google Cloud Bigtable store.
+ *
+ * Bigtable is Google's fully-managed wide-column store — the system the
+ * original Bigtable paper describes and that HBase was later modelled on.
+ * Data is a sparse, sorted map addressed by `(row key, column family, column
+ * qualifier, timestamp)`: rows are keyed by an arbitrary byte-string row key
+ * (stored in lexicographic order), grouped into a small set of column
+ * families, with an unbounded number of qualifiers per family. There is no
+ * fixed schema beyond the family list, no joins, no secondary indexes, and no
+ * arbitrary WHERE filtering — reads are single-row lookups by key or range/
+ * filter 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
+ * Bigtable's own row operations directly.
+ *
+ * Built on the official `@google-cloud/bigtable` client. That client is
+ * resource-oriented: a `Bigtable` instance resolves to an `instance(id)`,
+ * which resolves to a `table(id)`, on which `insert`/`getRows`/`row(key)`/
+ * `createTable` operate. This store caches the resolved table handles and
+ * exposes flat `insertRow`/`getRow`/`deleteRow`/`readRows`/`createTable`
+ * methods over them. 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.
+ */
+const errors_1 = require("../../errors");
+/**
+ * `BigtableStore` wraps a `@google-cloud/bigtable` client and exposes
+ * Bigtable's row surface: `insertRow`/`getRow`/`deleteRow` for single-row
+ * operations, `readRows` for range/filter scans, and `createTable` for
+ * defining a table's column families. Instance and table ids are resolved once
+ * and the resulting handles cached per table id.
+ */
+class BigtableStore {
+    constructor(options = {}) {
+        this.name = 'bigtable';
+        this.library = '@google-cloud/bigtable';
+        this.client = null;
+        this.instance = null;
+        this.tables = new Map();
+        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 `@google-cloud/bigtable` to be installed. Tests inject a
+                // mock `client` above and never reach this branch.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { Bigtable } = require('@google-cloud/bigtable');
+                client = new Bigtable({
+                    projectId: this.options.projectId,
+                    ...this.options.clientOptions,
+                });
+            }
+            this.client = client;
+            // Resolve the instance handle once; individual table handles are
+            // resolved lazily/cached in tableFor().
+            if (this.options.instanceId) {
+                this.instance = client.instance(this.options.instanceId);
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.instance = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to connect to Bigtable: ${parent.message}`, {
+                parent,
+                database: 'bigtable',
+            });
+        }
+    }
+    /**
+     * The Bigtable client manages its own gRPC channel pool and does not expose
+     * a public close on the surface this store depends on, so `disconnect()`
+     * drops the cached handles and flips `connected` to false.
+     */
+    async disconnect() {
+        this.tables.clear();
+        this.instance = null;
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `Bigtable` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Bigtable client is not connected. Call connect() first.', {
+                database: 'bigtable',
+            });
+        }
+        return this.client;
+    }
+    /**
+     * Resolves (and caches) the `Table` handle for `table` (or the configured
+     * default `tableId`) within the configured instance. Requires both an
+     * instance id and a table id to be resolvable.
+     */
+    tableFor(table) {
+        const client = this.requireClient();
+        if (!this.instance) {
+            if (!this.options.instanceId) {
+                throw new errors_1.DatabaseError('Bigtable instanceId is required to resolve a table', {
+                    original: 'missing instanceId',
+                });
+            }
+            this.instance = client.instance(this.options.instanceId);
+        }
+        const tableId = table ?? this.options.tableId;
+        if (!tableId) {
+            throw new errors_1.DatabaseError('Bigtable tableId is required (pass a table name or set options.tableId)', {
+                original: 'missing tableId',
+            });
+        }
+        let handle = this.tables.get(tableId);
+        if (!handle) {
+            handle = this.instance.table(tableId);
+            this.tables.set(tableId, handle);
+        }
+        return handle;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `Bigtable ${action} failed: ${parent.message}` });
+    }
+    // ---------------------------------------------------------------------
+    // Row operations
+    // ---------------------------------------------------------------------
+    /**
+     * Inserts (writes) a single row via `table.insert(...)`. `data` maps column
+     * families to `{ qualifier: value }` maps, e.g.
+     * `{ cf: { name: 'alice', age: 30 } }`. Passed to the driver as a single
+     * `{ key, data }` insert entry.
+     */
+    async insertRow(table, key, data) {
+        const handle = this.tableFor(table);
+        try {
+            return await handle.insert([{ key, data }]);
+        }
+        catch (err) {
+            throw this.wrapError(`insertRow on '${table}' key '${key}'`, err);
+        }
+    }
+    /** Reads a single row by key via `table.row(key).get()`, returning the row data. */
+    async getRow(table, key) {
+        const handle = this.tableFor(table);
+        try {
+            return await handle.row(key).get();
+        }
+        catch (err) {
+            throw this.wrapError(`getRow on '${table}' key '${key}'`, err);
+        }
+    }
+    /** Deletes an entire row (all its cells) via `table.row(key).delete()`. */
+    async deleteRow(table, key) {
+        const handle = this.tableFor(table);
+        try {
+            return await handle.row(key).delete();
+        }
+        catch (err) {
+            throw this.wrapError(`deleteRow on '${table}' key '${key}'`, err);
+        }
+    }
+    /**
+     * Reads multiple rows via `table.getRows(options)`. `options` (ranges, keys,
+     * prefix, limit, filter) is forwarded straight to the client. Since Bigtable
+     * keeps row keys sorted, a `ranges`/`prefix` scan reads an efficient
+     * contiguous slice of the key space. Returns the rows as the driver
+     * surfaces them.
+     */
+    async readRows(table, opts = {}) {
+        const handle = this.tableFor(table);
+        try {
+            return await handle.getRows(opts);
+        }
+        catch (err) {
+            throw this.wrapError(`readRows on '${table}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Table lifecycle
+    // ---------------------------------------------------------------------
+    /**
+     * Creates a table with the given column families via `table.create(...)`.
+     * `families` is the list of column family names (e.g. `['cf', 'meta']`),
+     * passed to the client as its `families` create option. A table must declare
+     * its families up front — unlike qualifiers, families cannot be added
+     * implicitly at write time.
+     */
+    async createTable(table, families) {
+        const handle = this.tableFor(table);
+        if (!families || families.length === 0) {
+            throw new errors_1.DatabaseError('createTable() requires at least one column family', {
+                original: 'empty families list',
+            });
+        }
+        try {
+            return await handle.create({ families });
+        }
+        catch (err) {
+            throw this.wrapError(`createTable '${table}'`, err);
+        }
+    }
+}
+exports.BigtableStore = BigtableStore;
+exports.default = BigtableStore;

package/dist/nosql/blazegraph/index.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Blazegraph store implementation.
+ *
+ * Blazegraph is a high-performance RDF triplestore. It speaks the SPARQL 1.1
+ * Protocol over HTTP: a namespace exposes a single combined SPARQL endpoint
+ * (`/blazegraph/namespace/<ns>/sparql`) used for both queries and updates
+ * (dispatched by request content-type). There is no SQL-shaped surface, so it
+ * implements the minimal `NoSqlStore` marker interface (`src/nosql/store.ts`)
+ * rather than the SQL `Dialect` interface.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Blazegraph has no dedicated npm client; it is just a SPARQL/HTTP endpoint.
+ * This store talks to the server with the global `fetch`. For tests (and for
+ * callers who want their own transport) an alternative client can be injected
+ * via `BlazegraphStoreOptions.client`; when omitted, a tiny internal client
+ * over `fetch` + `endpoint` is built at connect time.
+ *
+ * ## Surface
+ *
+ * - `query(sparql)`  -> POST to `/blazegraph/namespace/<ns>/sparql`, bindings
+ * - `update(sparql)` -> POST to the same endpoint
+ * - `ask(sparql)`    -> POST an ASK query, returns the boolean
+ * - `add(triples)`   -> `INSERT DATA { ... }` update
+ * - `drop(graph?)`   -> `DROP GRAPH <g>` / `DROP ALL` update
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlazegraphStore = exports.DEFAULT_BLAZEGRAPH_NAMESPACE = exports.DEFAULT_BLAZEGRAPH_ENDPOINT = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+/** Default Blazegraph base URL. */
+exports.DEFAULT_BLAZEGRAPH_ENDPOINT = 'http://localhost:9999';
+/** Default namespace. */
+exports.DEFAULT_BLAZEGRAPH_NAMESPACE = 'kb';
+/** Build a `fetch`-backed SPARQL client for the given endpoint. */
+function createFetchClient(endpoint, headers) {
+    const base = endpoint.endsWith('/') ? endpoint : `${endpoint}/`;
+    const buildUrl = (path) => new URL(path.replace(/^\//, ''), base).toString();
+    return {
+        async query(path, sparql) {
+            const res = await fetch(buildUrl(path), {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/sparql-query',
+                    Accept: 'application/sparql-results+json',
+                    ...(headers ?? {}),
+                },
+                body: sparql,
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            return res.json();
+        },
+        async update(path, sparql) {
+            const res = await fetch(buildUrl(path), {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/sparql-update', ...(headers ?? {}) },
+                body: sparql,
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            const text = await res.text();
+            return text || undefined;
+        },
+    };
+}
+/**
+ * `BlazegraphStore` wraps a Blazegraph namespace's combined SPARQL endpoint
+ * behind the `NoSqlStore` lifecycle.
+ */
+class BlazegraphStore {
+    constructor(options = {}) {
+        this.name = 'blazegraph';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.endpoint = options.endpoint ?? exports.DEFAULT_BLAZEGRAPH_ENDPOINT;
+        this.namespace = options.namespace ?? exports.DEFAULT_BLAZEGRAPH_NAMESPACE;
+        this.injectedClient = options.client;
+        this.headers = options.headers;
+    }
+    /** Combined SPARQL endpoint path for the configured namespace. */
+    get sparqlPath() {
+        return `/blazegraph/namespace/${this.namespace}/sparql`;
+    }
+    /** SPARQL query endpoint path (same combined endpoint). */
+    get queryPath() {
+        return this.sparqlPath;
+    }
+    /** SPARQL update endpoint path (same combined endpoint). */
+    get updatePath() {
+        return this.sparqlPath;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client)
+            return;
+        this.client = this.injectedClient ?? createFetchClient(this.endpoint, this.headers);
+        this.connected = true;
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying (internal or injected) SPARQL HTTP client. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Blazegraph', {
+                database: 'blazegraph',
+                host: this.endpoint,
+            });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // SPARQL surface
+    // ---------------------------------------------------------------------
+    /** Runs a SPARQL SELECT/CONSTRUCT query; returns the result bindings. */
+    async query(sparql) {
+        const client = this.requireClient();
+        try {
+            const body = await client.query(this.queryPath, sparql);
+            return body?.results?.bindings ?? [];
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Blazegraph query failed: ${parent.message}`, sql: sparql });
+        }
+    }
+    /** Runs a SPARQL ASK query; returns the boolean answer. */
+    async ask(sparql) {
+        const client = this.requireClient();
+        try {
+            const body = await client.query(this.queryPath, sparql);
+            return Boolean(body?.boolean);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Blazegraph ask failed: ${parent.message}`, sql: sparql });
+        }
+    }
+    /** Runs a SPARQL UPDATE (INSERT/DELETE/DROP/...). */
+    async update(sparql) {
+        const client = this.requireClient();
+        try {
+            return await client.update(this.updatePath, sparql);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Blazegraph update failed: ${parent.message}`, sql: sparql });
+        }
+    }
+    /** Inserts triples via `INSERT DATA { ... }`. Accepts a triple string or array. */
+    async add(triples, graph) {
+        const body = Array.isArray(triples) ? triples.join('\n') : triples;
+        const inner = graph ? `GRAPH <${graph}> { ${body} }` : body;
+        return this.update(`INSERT DATA { ${inner} }`);
+    }
+    /** Drops a named graph, or all graphs when no graph is given. */
+    async drop(graph) {
+        return this.update(graph ? `DROP GRAPH <${graph}>` : 'DROP ALL');
+    }
+}
+exports.BlazegraphStore = BlazegraphStore;

package/dist/nosql/bullmq/index.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * BullMQ job/task-queue store.
+ *
+ * BullMQ is a Redis-backed queue: a `Queue` object adds jobs to a named
+ * queue, and a `Worker` object pulls jobs from that queue and runs a handler.
+ * Each queue is a distinct object bound to a name, so this store caches one
+ * `Queue` (and, once `process()`d, one `Worker`) per queue name. BullMQ is
+ * not a database and does not fit the SQL-shaped `Dialect` interface, so this
+ * class implements the minimal `NoSqlStore` marker interface and exposes
+ * BullMQ's real add/process/getJob operations instead.
+ *
+ * Uses the `bullmq` 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
+ * `BullMQStoreOptions.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.BullMQStore = 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 BullMQ: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'bullmq' });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `BullMQ ${action} failed: ${parent.message}` });
+}
+/**
+ * `BullMQStore` manages a pool of BullMQ `Queue`/`Worker` objects keyed by
+ * queue name and exposes the common queue surface
+ * (`enqueue`/`process`/`getJob`/`remove`/`stats`).
+ */
+class BullMQStore {
+    constructor(options = {}) {
+        this.name = 'bullmq';
+        this.library = 'bullmq';
+        this.driver = null;
+        this.connected = false;
+        this.queues = new Map();
+        this.workers = new Map();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.driver) {
+            return;
+        }
+        try {
+            // BullMQ has no single connection to open; "connecting" just resolves
+            // the driver module. Per-queue Redis connections open lazily when the
+            // first Queue/Worker for a name is constructed.
+            this.driver = this.options.client != null ? this.options.client : require('bullmq');
+            this.connected = true;
+        }
+        catch (err) {
+            this.driver = null;
+            this.connected = false;
+            throw wrapConnectionError(err);
+        }
+    }
+    async disconnect() {
+        for (const worker of this.workers.values()) {
+            try {
+                if (worker && typeof worker.close === 'function')
+                    await worker.close();
+            }
+            catch {
+                // Ignore teardown errors.
+            }
+        }
+        for (const queue of this.queues.values()) {
+            try {
+                if (queue && typeof queue.close === 'function')
+                    await queue.close();
+            }
+            catch {
+                // Ignore teardown errors.
+            }
+        }
+        this.workers.clear();
+        this.queues.clear();
+        this.driver = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.driver !== null;
+    }
+    /** Returns the underlying `bullmq` driver module (with `Queue`/`Worker`). */
+    getClient() {
+        return this.requireDriver();
+    }
+    requireDriver() {
+        if (!this.driver) {
+            throw new errors_1.ConnectionError('Not connected to BullMQ', { database: 'bullmq' });
+        }
+        return this.driver;
+    }
+    get connectionOpts() {
+        return this.options.connection ?? { host: '127.0.0.1', port: 6379 };
+    }
+    /** Get (creating and caching on first use) the `Queue` for a queue name. */
+    getQueue(name) {
+        const driver = this.requireDriver();
+        let queue = this.queues.get(name);
+        if (!queue) {
+            queue = new driver.Queue(name, { connection: this.connectionOpts });
+            this.queues.set(name, queue);
+        }
+        return queue;
+    }
+    // ---------------------------------------------------------------------
+    // Queue operations
+    // ---------------------------------------------------------------------
+    /**
+     * Add a job to the named queue via `queue.add(name, data, opts)`. Returns
+     * the id BullMQ assigns to the job.
+     */
+    async enqueue(queue, jobData, opts = {}) {
+        try {
+            const { name, ...jobOpts } = opts;
+            const q = this.getQueue(queue);
+            const job = await q.add(name ?? queue, jobData, jobOpts);
+            return job?.id;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'enqueue');
+        }
+    }
+    /**
+     * Register a `Worker` for the named queue that runs `handler(job)` for each
+     * job. One worker is cached per queue name; a second `process()` on the
+     * same name returns the existing worker.
+     */
+    async process(queue, handler, opts = {}) {
+        try {
+            const existing = this.workers.get(queue);
+            if (existing)
+                return existing;
+            const driver = this.requireDriver();
+            const worker = new driver.Worker(queue, handler, {
+                connection: this.connectionOpts,
+                ...opts,
+            });
+            this.workers.set(queue, worker);
+            return worker;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'process');
+        }
+    }
+    /** Fetch a job by id from the named queue (`null` if it no longer exists). */
+    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. */
+    async remove(queue, id) {
+        try {
+            const job = await this.getQueue(queue).getJob(id);
+            if (job && typeof job.remove === 'function') {
+                await job.remove();
+            }
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'remove');
+        }
+    }
+    /** Return job counts by state (`waiting`/`active`/`completed`/`failed`/...). */
+    async stats(queue) {
+        try {
+            return await this.getQueue(queue).getJobCounts();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'stats');
+        }
+    }
+}
+exports.BullMQStore = BullMQStore;
+exports.default = BullMQStore;