ts-prorm-orm 1.1.0

package/dist/nosql/marklogic/index.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * MarkLogic store implementation for the Prorm NoSQL layer.
+ *
+ * MarkLogic is a multi-model database (document, graph/RDF triples, search,
+ * relational views) where documents are addressed by an opaque URI. It does
+ * not fit the SQL-shaped `Dialect` interface, so this class implements the
+ * minimal `NoSqlStore` marker interface for connection lifecycle and exposes
+ * MarkLogic's real `documents.write/read/remove` plus `documents.query` API
+ * through a small document-CRUD convenience layer. Collection + id are mapped
+ * to a URI of the form `/<collection>/<id>.json`.
+ *
+ * Uses the official `marklogic` driver. That driver is an optional peer
+ * dependency and is loaded lazily inside `connect()` so importing this module
+ * never requires it to be installed. Tests inject a pre-built mock `client`
+ * (and `queryBuilder`) via options, which bypasses the lazy `require`
+ * entirely - no real driver and no network are needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarkLogicStore = void 0;
+const errors_1 = require("../../errors");
+class MarkLogicStore {
+    constructor(options = {}) {
+        this.name = 'marklogic';
+        this.library = 'marklogic';
+        this.client = null;
+        this.qb = 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;
+                this.qb = this.options.queryBuilder ?? this.tryRequireQueryBuilder();
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const marklogic = require('marklogic');
+                this.client = marklogic.createDatabaseClient({
+                    host: this.options.host,
+                    port: this.options.port,
+                    user: this.options.user,
+                    password: this.options.password,
+                    authType: this.options.authType,
+                    database: this.options.database,
+                });
+                this.qb = this.options.queryBuilder ?? marklogic.queryBuilder;
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.qb = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to connect to MarkLogic: ${parent.message}`, {
+                parent,
+                database: 'marklogic',
+            });
+        }
+    }
+    tryRequireQueryBuilder() {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            return require('marklogic').queryBuilder;
+        }
+        catch {
+            return null;
+        }
+    }
+    async disconnect() {
+        // The MarkLogic client is stateless over HTTP; drop the reference so a
+        // subsequent call must connect() again.
+        this.client = null;
+        this.qb = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to MarkLogic. Call connect() first.', {
+                database: 'marklogic',
+            });
+        }
+        return this.client;
+    }
+    uri(collection, id) {
+        return `/${collection}/${id}.json`;
+    }
+    // ---------------------------------------------------------------------
+    // Document CRUD
+    // ---------------------------------------------------------------------
+    /** Write a document into `collection`; returns the id used. */
+    async insert(collection, doc) {
+        const client = this.requireClient();
+        try {
+            const id = (doc.id ?? genId());
+            await client.documents
+                .write({
+                uri: this.uri(collection, id),
+                contentType: 'application/json',
+                collections: [collection],
+                content: doc,
+            })
+                .result();
+            return id;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'MarkLogic insert failed');
+        }
+    }
+    /** Read a document by id, returning its stored `content`. */
+    async get(collection, id) {
+        const client = this.requireClient();
+        try {
+            const docs = await client.documents.read(this.uri(collection, id)).result();
+            return docs?.[0]?.content;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'MarkLogic get failed');
+        }
+    }
+    /** Merge `patch` into an existing document and re-write it. */
+    async update(collection, id, patch) {
+        const client = this.requireClient();
+        try {
+            const docs = await client.documents.read(this.uri(collection, id)).result();
+            const current = docs?.[0]?.content ?? {};
+            const merged = { ...current, ...patch };
+            await client.documents
+                .write({
+                uri: this.uri(collection, id),
+                contentType: 'application/json',
+                collections: [collection],
+                content: merged,
+            })
+                .result();
+            return merged;
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'MarkLogic update failed');
+        }
+    }
+    /** Remove a document by id. */
+    async delete(collection, id) {
+        const client = this.requireClient();
+        try {
+            return await client.documents.remove(this.uri(collection, id)).result();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'MarkLogic delete failed');
+        }
+    }
+    /**
+     * Query documents. When `builtQuery` is provided it is passed straight to
+     * `documents.query`; otherwise all documents in `collection` are matched via
+     * `queryBuilder.where(queryBuilder.collection(collection))`. Returns the
+     * result documents.
+     */
+    async query(collection, builtQuery) {
+        const client = this.requireClient();
+        try {
+            const query = builtQuery !== undefined ? builtQuery : this.buildCollectionQuery(collection);
+            const result = await client.documents.query(query).result();
+            return result ?? [];
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'MarkLogic query failed');
+        }
+    }
+    buildCollectionQuery(collection) {
+        const qb = this.qb;
+        if (!qb) {
+            throw new errors_1.ConnectionError('MarkLogic queryBuilder unavailable. Call connect() first.', {
+                database: 'marklogic',
+            });
+        }
+        return qb.where(qb.collection(collection));
+    }
+}
+exports.MarkLogicStore = MarkLogicStore;
+function genId() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+}
+function wrapDatabaseError(err, message) {
+    if (err instanceof errors_1.ConnectionError) {
+        return err;
+    }
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `${message}: ${parent.message}` });
+}
+exports.default = MarkLogicStore;

package/dist/nosql/materialize/index.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Materialize store.
+ *
+ * Materialize is a streaming (incrementally-updated) analytics database: you
+ * define SOURCEs over event streams and MATERIALIZED VIEWs whose results are
+ * kept continuously up to date as new data arrives, then read them with
+ * low-latency SQL. Materialize speaks the **PostgreSQL wire protocol**, so it
+ * is driven with the `pg` client over a normal Postgres-style connection.
+ * Although the wire is Postgres, Materialize's compute model (streaming
+ * dataflows, `SUBSCRIBE`, `CREATE SOURCE`) is not a general OLTP relational
+ * store and does not fit this ORM's SQL `Dialect` abstraction, so it is
+ * modelled as a `NoSqlStore` (`src/nosql/store.ts`) exposing a direct `query`
+ * surface plus source/view helpers.
+ *
+ * ## Driver: `pg` (PostgreSQL-wire)
+ *
+ * The `pg` 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 client via `MaterializeStoreOptions.client`, which
+ * skips the `require` entirely.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaterializeStore = void 0;
+const errors_1 = require("../../errors");
+/**
+ * `MaterializeStore` wraps a `pg` client connected to Materialize and exposes
+ * `query(sql, params)` for reads/DDL, plus `createSource()` and
+ * `createMaterializedView()` convenience helpers for the streaming-specific
+ * DDL that defines what Materialize keeps incrementally up to date.
+ */
+class MaterializeStore {
+    constructor(options = {}) {
+        this.name = 'materialize';
+        this.library = 'pg';
+        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 pg = require('pg');
+                client = new pg.Client({
+                    host: this.options.host,
+                    port: this.options.port,
+                    user: this.options.user,
+                    password: this.options.password,
+                    database: this.options.database,
+                    connectionString: this.options.connectionString,
+                    ...this.options.connectionOptions,
+                });
+            }
+            await client.connect();
+            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 Materialize: ${parent.message}`, {
+                parent,
+                database: 'materialize',
+                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 `pg` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Materialize client is not connected. Call connect() first.', {
+                database: 'materialize',
+            });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Query + streaming DDL
+    // ---------------------------------------------------------------------
+    /**
+     * Execute a SQL statement over the Postgres wire with optional positional
+     * `params` and return the result rows (`pg`'s `result.rows`).
+     */
+    async query(sql, params) {
+        const client = this.requireClient();
+        try {
+            const result = await client.query(sql, params);
+            return (result?.rows ?? []);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, {
+                message: `Materialize query failed: ${parent.message}`,
+                sql,
+            });
+        }
+    }
+    /**
+     * Create a streaming SOURCE via `CREATE SOURCE <name> <definition>`, e.g.
+     * `createSource('kafka_src', "FROM KAFKA CONNECTION ... (TOPIC 'events')")`.
+     * Returns the driver result rows.
+     */
+    async createSource(name, definition) {
+        return this.query(`CREATE SOURCE ${name} ${definition}`);
+    }
+    /**
+     * Create a MATERIALIZED VIEW (kept incrementally up to date) via
+     * `CREATE MATERIALIZED VIEW <name> AS <selectSql>`. Returns the driver
+     * result rows.
+     */
+    async createMaterializedView(name, selectSql) {
+        return this.query(`CREATE MATERIALIZED VIEW ${name} AS ${selectSql}`);
+    }
+}
+exports.MaterializeStore = MaterializeStore;
+exports.default = MaterializeStore;

package/dist/nosql/meilisearch/index.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Meilisearch store implementation.
+ *
+ * Meilisearch is a search engine built around an inverted index with
+ * typo-tolerant, prefix, full-text search and faceting rather than SQL: no
+ * `JOIN`, no transaction log, schema-flexible documents grouped into indexes
+ * (each identified by a `uid` and a primary key). It therefore does not fit
+ * the SQL-shaped `Dialect` interface used by the SQL dialects in this repo.
+ * Instead it implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes Meilisearch's real capabilities grouped
+ * by concern: connection lifecycle, index management and document CRUD/search.
+ *
+ * Uses the official `meilisearch` JS driver. The driver is loaded lazily via
+ * `require` so importing this module does not force the dependency to be
+ * resolved unless a Meilisearch store is actually constructed. For
+ * unit-testing without a live server, the constructor also accepts an
+ * already-built `client`, which `connect()` will use as-is instead of
+ * instantiating a new one.
+ *
+ * Most operations are scoped to an index and reached through
+ * `client.index(uid).<op>(...)`; index lifecycle (`createIndex`/`deleteIndex`)
+ * and cluster stats live directly on the top-level client.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeilisearchStore = void 0;
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Meilisearch: ${parent.message}`;
+    return new errors_1.ConnectionError(message, {
+        parent,
+        database: 'meilisearch',
+        host: typeof host === 'string' ? host : undefined,
+    });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const statusCode = err?.httpStatus;
+    const detail = statusCode ? `${parent.message} (HTTP ${statusCode})` : parent.message;
+    const combined = message ? `${message}: ${detail}` : detail;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/**
+ * `MeilisearchStore` wraps the official `meilisearch` client and exposes
+ * index management, document CRUD, and search as a typed, promise-based API.
+ */
+class MeilisearchStore {
+    constructor(options) {
+        this.name = 'meilisearch';
+        this.library = 'meilisearch';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        let client = this.options.client;
+        if (!client) {
+            // Lazy-load the driver so importing this module doesn't require the
+            // dependency to be present unless a store is actually constructed.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { MeiliSearch } = require('meilisearch');
+            client = new MeiliSearch({ host: this.options.host, apiKey: this.options.apiKey });
+        }
+        try {
+            // `health()` surfaces connection failures (bad host, refused
+            // connection) immediately instead of on the caller's first real
+            // operation.
+            await client.health();
+            this.client = client;
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.host);
+        }
+    }
+    async disconnect() {
+        // The Meilisearch client is stateless HTTP; there's no socket to close.
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `meilisearch` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Meilisearch', { database: 'meilisearch' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Meilisearch ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Index management
+    // ---------------------------------------------------------------------
+    /** Create an index by `uid`, optionally specifying its primary key via `options`. */
+    async createIndex(uid, options) {
+        return this.exec((c) => c.createIndex(uid, options), 'CREATE INDEX');
+    }
+    /** Delete an index by `uid`. */
+    async deleteIndex(uid) {
+        return this.exec((c) => c.deleteIndex(uid), 'DELETE INDEX');
+    }
+    // ---------------------------------------------------------------------
+    // Document CRUD + search
+    // ---------------------------------------------------------------------
+    /** Add (or replace) documents in an index. Returns the enqueued task. */
+    async addDocuments(index, documents, options) {
+        return this.exec((c) => c.index(index).addDocuments(documents, options), 'ADD DOCUMENTS');
+    }
+    /** Run a search against an index and return the `hits` array from the response. */
+    async search(index, query, options) {
+        const result = await this.exec((c) => c.index(index).search(query, options), 'SEARCH');
+        return result?.hits ?? [];
+    }
+    /** Get a single document by its primary-key value. */
+    async getDocument(index, id) {
+        return this.exec((c) => c.index(index).getDocument(id), 'GET DOCUMENT');
+    }
+    /** Delete a single document by its primary-key value. Returns the enqueued task. */
+    async deleteDocument(index, id) {
+        return this.exec((c) => c.index(index).deleteDocument(id), 'DELETE DOCUMENT');
+    }
+    // ---------------------------------------------------------------------
+    // Stats
+    // ---------------------------------------------------------------------
+    /** Get server-wide stats (database size, per-index document counts, etc.). */
+    async getStats() {
+        return this.exec((c) => c.getStats(), 'GET STATS');
+    }
+}
+exports.MeilisearchStore = MeilisearchStore;
+exports.default = MeilisearchStore;