ts-prorm-orm 1.1.0

package/dist/nosql/sqs/index.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqsStore = void 0;
+/**
+ * Amazon SQS (Simple Queue Service) store.
+ *
+ * SQS is a managed, pull-based message queue. It has no query language and no
+ * SQL-shaped access pattern, so this store implements the minimal `NoSqlStore`
+ * marker interface (`src/nosql/store.ts`) and exposes SQS's real operations:
+ * sending a message to a queue (`publish`), a long-poll receive loop that
+ * delivers messages to a handler and deletes (acks) them afterward
+ * (`subscribe`), and queue administration (`createQueue`).
+ *
+ * Built on AWS SDK v3 (`@aws-sdk/client-sqs`): an `SQSClient` speaks the wire
+ * protocol via the command pattern — you build a command object
+ * (`new SendMessageCommand(input)`) and hand it to `client.send(command)`. The
+ * SDK is loaded lazily inside `connect()` (via `require`) so importing this
+ * module never hard-requires the driver, and tests inject a mock `client`
+ * (with a `send(command)` method) so no real SDK or network is used.
+ *
+ * Message encoding: `publish()` accepts a `string` (sent as-is), a `Buffer`
+ * (decoded to UTF-8), or any other JSON-serializable value (`JSON.stringify`d).
+ * The result becomes the message body (SQS bodies are strings).
+ */
+const errors_1 = require("../../errors");
+/** Encode a message into the string body SQS carries. */
+function toBody(message) {
+    if (typeof message === 'string')
+        return message;
+    if (Buffer.isBuffer(message))
+        return message.toString('utf8');
+    return JSON.stringify(message);
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        // Don't let a pending poll-interval timer keep the process alive.
+        timer.unref?.();
+    });
+}
+/**
+ * `SqsStore` wraps an AWS v3 `SQSClient` and exposes queue sending, a
+ * receive-and-ack poll loop, and queue administration.
+ */
+class SqsStore {
+    constructor(options = {}) {
+        this.name = 'sqs';
+        this.library = '@aws-sdk/client-sqs';
+        this.client = null;
+        this.aws = null;
+        this.connected = false;
+        /** Active subscriptions, tracked so `disconnect()` stops their receive loops. */
+        this.subscriptions = new Set();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        try {
+            if (this.options.client) {
+                this.client = this.options.client;
+                this.tryLoadSdk();
+            }
+            else {
+                const aws = require('@aws-sdk/client-sqs');
+                this.aws = aws;
+                this.client = new aws.SQSClient({
+                    region: this.options.region,
+                    credentials: this.options.credentials,
+                    endpoint: this.options.endpoint,
+                });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.connected = false;
+            this.client = null;
+            this.aws = null;
+            throw new errors_1.ConnectionError(`Failed to connect to SQS: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined, database: 'sqs' });
+        }
+    }
+    tryLoadSdk() {
+        if (this.aws)
+            return;
+        try {
+            this.aws = require('@aws-sdk/client-sqs');
+        }
+        catch {
+            this.aws = null;
+        }
+    }
+    async disconnect() {
+        for (const sub of this.subscriptions) {
+            try {
+                sub.stop();
+            }
+            catch {
+                // Best-effort teardown.
+            }
+        }
+        this.subscriptions.clear();
+        try {
+            this.client?.destroy?.();
+        }
+        finally {
+            this.client = null;
+            this.aws = null;
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `SQSClient` (loosely typed) for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('SQS client is not connected. Call connect() first.', {
+                database: 'sqs',
+            });
+        }
+        return this.client;
+    }
+    command(name, input) {
+        if (!this.aws)
+            this.tryLoadSdk();
+        const Ctor = this.aws?.[name];
+        if (typeof Ctor !== 'function') {
+            throw new errors_1.ConnectionError(`SQS command '${name}' is unavailable: '@aws-sdk/client-sqs' could not be loaded.`, { database: 'sqs' });
+        }
+        return new Ctor(input);
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        const name = parent.name ? ` (${parent.name})` : '';
+        return new errors_1.DatabaseError(`SQS ${action} failed${name}: ${parent.message}`, {
+            parent,
+            original: parent.message,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Producing
+    // ---------------------------------------------------------------------
+    /**
+     * `SendMessage` — publish one `message` to the queue at `queueUrl`. The
+     * message is encoded to a string body (string as-is, Buffer → UTF-8, else
+     * JSON). Returns the message id (and FIFO sequence number, if any).
+     */
+    async publish(queueUrl, message, options = {}) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('SendMessageCommand', {
+                QueueUrl: queueUrl,
+                MessageBody: toBody(message),
+                DelaySeconds: options.delaySeconds,
+                MessageGroupId: options.messageGroupId,
+                MessageDeduplicationId: options.messageDeduplicationId,
+                MessageAttributes: options.messageAttributes,
+            }));
+            return { messageId: result?.MessageId, sequenceNumber: result?.SequenceNumber };
+        }
+        catch (err) {
+            throw this.wrapError(`SendMessage to '${queueUrl}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Queue administration
+    // ---------------------------------------------------------------------
+    /** `CreateQueue` — create a queue by name. Returns its URL. */
+    async createQueue(name, options = {}) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(this.command('CreateQueueCommand', {
+                QueueName: name,
+                Attributes: options.attributes,
+                tags: options.tags,
+            }));
+            return result?.QueueUrl;
+        }
+        catch (err) {
+            throw this.wrapError(`CreateQueue '${name}'`, err);
+        }
+    }
+    /** Alias for `createQueue()`, matching the common store surface. */
+    createTopic(name, options = {}) {
+        return this.createQueue(name, options);
+    }
+    // ---------------------------------------------------------------------
+    // Consuming
+    // ---------------------------------------------------------------------
+    /**
+     * Subscribe to the queue at `queueUrl`: long-poll `ReceiveMessage` in a loop,
+     * invoke `handler` once per message, and (by default) `DeleteMessage` to ack
+     * each message after the handler resolves. Returns a subscription whose
+     * `stop()` ends the loop; the subscription is tracked so `disconnect()` stops
+     * it. The loop runs detached (not awaited); this method resolves immediately.
+     */
+    subscribe(queueUrl, handler, options = {}) {
+        const client = this.requireClient();
+        const autoDelete = options.autoDelete ?? true;
+        const pollIntervalMs = options.pollIntervalMs ?? 0;
+        let stopped = false;
+        const subscription = {
+            stop: () => {
+                stopped = true;
+                this.subscriptions.delete(subscription);
+            },
+        };
+        this.subscriptions.add(subscription);
+        const loop = async () => {
+            while (!stopped) {
+                const result = await client.send(this.command('ReceiveMessageCommand', {
+                    QueueUrl: queueUrl,
+                    MaxNumberOfMessages: options.maxMessages ?? 10,
+                    WaitTimeSeconds: options.waitTimeSeconds ?? 20,
+                    VisibilityTimeout: options.visibilityTimeout,
+                }));
+                const messages = result?.Messages ?? [];
+                for (const message of messages) {
+                    if (stopped)
+                        break;
+                    await handler(message);
+                    if (autoDelete && message?.ReceiptHandle) {
+                        await client.send(this.command('DeleteMessageCommand', {
+                            QueueUrl: queueUrl,
+                            ReceiptHandle: message.ReceiptHandle,
+                        }));
+                    }
+                }
+                if (stopped)
+                    break;
+                if (pollIntervalMs > 0)
+                    await sleep(pollIntervalMs);
+            }
+        };
+        loop().catch(() => {
+            /* swallow — best-effort background polling */
+        });
+        return subscription;
+    }
+}
+exports.SqsStore = SqsStore;
+exports.default = SqsStore;

package/dist/nosql/stardog/index.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Stardog store implementation.
+ *
+ * Stardog is an enterprise knowledge-graph / RDF triplestore. It speaks the
+ * SPARQL 1.1 Protocol over HTTP: a database exposes a query endpoint
+ * (`/<db>/query`) and an update endpoint (`/<db>/update`). There is no
+ * SQL-shaped surface, so it implements the minimal `NoSqlStore` marker
+ * interface (`src/nosql/store.ts`) rather than the SQL `Dialect` interface.
+ *
+ * ## Driver strategy - prefer HTTP over `fetch`
+ *
+ * Stardog publishes a `stardog` npm client, but this store prefers the plain
+ * SPARQL/HTTP protocol over the global `fetch` so it has no hard dependency
+ * (`library='fetch'`). For tests (and for callers who want their own
+ * transport) an alternative client can be injected via
+ * `StardogStoreOptions.client`; when omitted, a tiny internal client over
+ * `fetch` + `endpoint` is built at connect time.
+ *
+ * ## Surface
+ *
+ * - `query(sparql)`  -> POST to `/<db>/query`, returns bindings
+ * - `update(sparql)` -> POST to `/<db>/update`
+ * - `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.StardogStore = exports.DEFAULT_STARDOG_DATABASE = exports.DEFAULT_STARDOG_ENDPOINT = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+/** Default Stardog base URL. */
+exports.DEFAULT_STARDOG_ENDPOINT = 'http://localhost:5820';
+/** Default database name. */
+exports.DEFAULT_STARDOG_DATABASE = 'db';
+/** 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;
+        },
+    };
+}
+/**
+ * `StardogStore` wraps a Stardog database's SPARQL query/update endpoints
+ * behind the `NoSqlStore` lifecycle.
+ */
+class StardogStore {
+    constructor(options = {}) {
+        this.name = 'stardog';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.endpoint = options.endpoint ?? exports.DEFAULT_STARDOG_ENDPOINT;
+        this.database = options.database ?? exports.DEFAULT_STARDOG_DATABASE;
+        this.injectedClient = options.client;
+        this.headers = options.headers;
+    }
+    /** SPARQL query endpoint path for the configured database. */
+    get queryPath() {
+        return `/${this.database}/query`;
+    }
+    /** SPARQL update endpoint path for the configured database. */
+    get updatePath() {
+        return `/${this.database}/update`;
+    }
+    // ---------------------------------------------------------------------
+    // 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 Stardog', {
+                database: 'stardog',
+                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: `Stardog 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: `Stardog 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: `Stardog 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.StardogStore = StardogStore;

package/dist/nosql/starrocks/index.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * StarRocks store.
+ *
+ * StarRocks is a high-performance real-time analytical (MPP OLAP) database.
+ * Crucially it speaks the **MySQL wire protocol**, so it is queried with the
+ * `mysql2` driver over a normal MySQL connection/pool. Despite the MySQL
+ * wire, StarRocks is a columnar analytics engine (no OLTP transactions, no
+ * row-level UPDATE/DELETE in the usual sense on most table types), which does
+ * not fit this ORM's SQL `Dialect` abstraction cleanly, so it is modelled as
+ * a `NoSqlStore` (`src/nosql/store.ts`) exposing a direct `query`/`ingest`
+ * surface.
+ *
+ * ## Driver: `mysql2` (MySQL-wire)
+ *
+ * The `mysql2` package is an optional peer dependency, lazily `require`d
+ * inside `connect()` so importing this module never forces it to be
+ * installed. Tests inject a pre-built mock connection via
+ * `StarrocksStoreOptions.client`, which skips the `require` entirely.
+ *
+ * ## Ingestion
+ *
+ * `ingest()` here performs a batched `INSERT` over the MySQL wire, which is
+ * convenient for small/medium loads. For high-throughput loading StarRocks
+ * also offers **Stream Load** (an HTTP `PUT /api/{db}/{table}/_stream_load`
+ * endpoint). Stream Load is intentionally *not* wired here (it is a separate
+ * HTTP transport, optional); use the `mysql2`-based `ingest()` for wire-level
+ * inserts, or POST to the Stream Load endpoint yourself for bulk pipelines.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StarrocksStore = void 0;
+const errors_1 = require("../../errors");
+/**
+ * `StarrocksStore` wraps a `mysql2` connection to a StarRocks frontend and
+ * exposes `query(sql, params)` for reads/DDL and `ingest(table, rows)` for
+ * batched wire-level inserts.
+ */
+class StarrocksStore {
+    constructor(options = {}) {
+        this.name = 'starrocks';
+        this.library = 'mysql2';
+        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) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const mysql = require('mysql2/promise');
+                client = (await mysql.createConnection({
+                    host: this.options.host,
+                    port: this.options.port,
+                    user: this.options.user,
+                    password: this.options.password,
+                    database: this.options.database,
+                    ...this.options.connectionOptions,
+                }));
+            }
+            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 StarRocks: ${parent.message}`, {
+                parent,
+                database: 'starrocks',
+                host: this.options.host,
+            });
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.end?.();
+            }
+            finally {
+                this.client = null;
+                this.connected = false;
+            }
+        }
+        else {
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `mysql2` connection for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('StarRocks client is not connected. Call connect() first.', {
+                database: 'starrocks',
+            });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Query + ingest
+    // ---------------------------------------------------------------------
+    /**
+     * Execute a SQL statement over the MySQL wire with optional positional
+     * `params` and return the result rows (the first element of `mysql2`'s
+     * `[rows, fields]` tuple).
+     */
+    async query(sql, params) {
+        const client = this.requireClient();
+        try {
+            const [rows] = await client.query(sql, params);
+            return (rows ?? []);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, {
+                message: `StarRocks query failed: ${parent.message}`,
+                sql,
+            });
+        }
+    }
+    /**
+     * Batch-insert `rows` into `table` via a single parameterized
+     * `INSERT INTO table (cols) VALUES (...)` over the MySQL wire. Columns are
+     * taken from the first row. Returns the driver result (`OkPacket`).
+     *
+     * For high-throughput bulk loading, use StarRocks Stream Load (HTTP) instead
+     * — see the module header.
+     */
+    async ingest(table, rows) {
+        if (rows.length === 0) {
+            throw new errors_1.DatabaseError('ingest() requires at least one row', {
+                original: 'empty rows array',
+            });
+        }
+        const columns = Object.keys(rows[0]);
+        if (columns.length === 0) {
+            throw new errors_1.DatabaseError('ingest() requires at least one column', {
+                original: 'empty row object',
+            });
+        }
+        const values = rows.map((r) => columns.map((c) => r[c]));
+        const client = this.requireClient();
+        // mysql2 expands a single `?` bound to a nested array into a bulk VALUES list.
+        const sql = `INSERT INTO ${table} (${columns.join(', ')}) VALUES ?`;
+        try {
+            const [result] = await client.query(sql, [values]);
+            return result;
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, {
+                message: `StarRocks ingest failed: ${parent.message}`,
+                sql,
+            });
+        }
+    }
+}
+exports.StarrocksStore = StarrocksStore;
+exports.default = StarrocksStore;

package/dist/nosql/store.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });