ts-prorm-orm 1.1.0

package/dist/nosql/qdrant/index.js

@@ -0,0 +1,295 @@
+"use strict";
+/**
+ * Qdrant store implementation.
+ *
+ * Qdrant is a vector-similarity search engine: collections hold points
+ * (an ID, one or more dense/sparse vectors, and an arbitrary JSON payload),
+ * and the primary query shape is "find the points whose vector is closest
+ * to this query vector" (optionally constrained by a payload filter) -
+ * not SQL, not `WHERE`, not joins. It does not fit the SQL-shaped `Dialect`
+ * interface used by the SQL dialects in this repo, so this class implements
+ * the minimal `NoSqlStore` marker interface and exposes Qdrant's real
+ * collection/point/payload/alias operations instead of forcing them into a
+ * `query(sql)` shape.
+ *
+ * Uses the official `@qdrant/js-client-rest` driver, which talks to Qdrant's
+ * HTTP REST API (there is also a gRPC client, `@qdrant/js-client-grpc`, not
+ * used here). The REST client is stateless (plain HTTP requests, no
+ * persistent socket) - `connect()` verifies the server is reachable and the
+ * API key (if any) is accepted by calling `versionInfo()`, and
+ * `disconnect()` simply drops the client reference.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QdrantStore = void 0;
+const js_client_rest_1 = require("@qdrant/js-client-rest");
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /fetch failed|ECONNREFUSED/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Qdrant: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'qdrant', host });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    // Keep the `action` context (e.g. "Qdrant SEARCH failed") but don't discard
+    // the real underlying Qdrant error text (e.g. "Collection `foo` doesn't
+    // exist") - append it so callers inspecting `err.message` still see what
+    // actually went wrong.
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/**
+ * `QdrantStore` wraps a `@qdrant/js-client-rest` `QdrantClient` and exposes
+ * Qdrant's collection management, point upsert/search/scroll/retrieve/delete,
+ * payload management, and collection-alias operations as a typed,
+ * promise-based API.
+ */
+class QdrantStore {
+    constructor(options = {}) {
+        this.name = 'qdrant';
+        this.library = '@qdrant/js-client-rest';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        const client = new js_client_rest_1.QdrantClient(this.options);
+        try {
+            // The REST client has no persistent socket to open, so "connecting"
+            // means eagerly verifying the server is reachable and (if configured)
+            // that the API key is accepted, rather than deferring failures to the
+            // first real call.
+            await client.versionInfo();
+            this.client = client;
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.host ?? this.options.url);
+        }
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `QdrantClient` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Qdrant', { database: 'qdrant' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Qdrant ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Collection management
+    // ---------------------------------------------------------------------
+    /**
+     * Create a new, empty collection. `vectors` is either a single
+     * `{ size, distance }` (unnamed/default vector space) or a map of named
+     * vector spaces (for collections with multiple vector fields per point).
+     */
+    async createCollection(collectionName, vectors, options = {}) {
+        return this.exec((c) => c.createCollection(collectionName, { vectors, ...options }), 'CREATE COLLECTION');
+    }
+    /** Delete a collection and all of its data. */
+    async deleteCollection(collectionName, options = {}) {
+        return this.exec((c) => c.deleteCollection(collectionName, options), 'DELETE COLLECTION');
+    }
+    /** Detailed status, point counts, and configuration for a collection. */
+    async getCollection(collectionName) {
+        return this.exec((c) => c.getCollection(collectionName), 'GET COLLECTION');
+    }
+    /** List the names of all collections. */
+    async listCollections() {
+        return this.exec(async (c) => (await c.getCollections()).collections, 'LIST COLLECTIONS');
+    }
+    /** Whether a collection with this name exists. */
+    async collectionExists(collectionName) {
+        return this.exec(async (c) => (await c.collectionExists(collectionName)).exists, 'COLLECTION EXISTS');
+    }
+    /** Update mutable collection parameters (optimizer config, HNSW params, etc). */
+    async updateCollection(collectionName, args = {}) {
+        return this.exec((c) => c.updateCollection(collectionName, args), 'UPDATE COLLECTION');
+    }
+    /** Create an index on a payload field so filtered search on it is fast. */
+    async createPayloadIndex(collectionName, fieldName, fieldSchema, options = {}) {
+        return this.exec((c) => c.createPayloadIndex(collectionName, {
+            field_name: fieldName,
+            field_schema: fieldSchema,
+            ...options,
+        }), 'CREATE PAYLOAD INDEX');
+    }
+    /** Remove an index previously created with `createPayloadIndex()`. */
+    async deletePayloadIndex(collectionName, fieldName, options = {}) {
+        return this.exec((c) => c.deletePayloadIndex(collectionName, fieldName, options), 'DELETE PAYLOAD INDEX');
+    }
+    // ---------------------------------------------------------------------
+    // Point upsert
+    // ---------------------------------------------------------------------
+    /** Insert or update one or more points (matched by ID). */
+    async upsert(collectionName, points, options = {}) {
+        return this.exec((c) => c.upsert(collectionName, { points, ...options }), 'UPSERT');
+    }
+    /**
+     * Insert or update points given in Qdrant's columnar "batch" shape
+     * (`{ ids, vectors, payloads }`, index-aligned across the three arrays)
+     * rather than an array of `{ id, vector, payload }` objects. Equivalent
+     * to `upsert()`, just a more compact wire format for large batches.
+     */
+    async upsertBatch(collectionName, batch, options = {}) {
+        return this.exec((c) => c.upsert(collectionName, { batch, ...options }), 'UPSERT BATCH');
+    }
+    // ---------------------------------------------------------------------
+    // Search
+    // ---------------------------------------------------------------------
+    /** Find the points whose vector is closest to `vector`, optionally constrained by a filter. */
+    async search(collectionName, vector, options = {}) {
+        const { vectorName, withPayload, withVector, scoreThreshold, ...rest } = options;
+        return this.exec((c) => c.search(collectionName, {
+            vector: vectorName ? { name: vectorName, vector } : vector,
+            with_payload: withPayload,
+            with_vector: withVector,
+            score_threshold: scoreThreshold,
+            ...rest,
+        }), 'SEARCH');
+    }
+    /** Run several `search()` requests against the same collection in a single round trip. */
+    async searchBatch(collectionName, searches, options = {}) {
+        return this.exec((c) => c.searchBatch(collectionName, { searches, ...options }), 'SEARCH BATCH');
+    }
+    // ---------------------------------------------------------------------
+    // Scroll (paginated retrieval)
+    // ---------------------------------------------------------------------
+    /**
+     * Page through all (optionally filtered) points in a collection without
+     * doing a similarity search. Pass the returned `nextPageOffset` back in
+     * as `options.offset` to fetch the next page; a `null` `nextPageOffset`
+     * means there's no more data.
+     */
+    async scroll(collectionName, options = {}) {
+        const { withPayload, withVector, ...rest } = options;
+        const result = await this.exec((c) => c.scroll(collectionName, {
+            with_payload: withPayload,
+            with_vector: withVector,
+            ...rest,
+        }), 'SCROLL');
+        return { points: result.points, nextPageOffset: result.next_page_offset ?? null };
+    }
+    // ---------------------------------------------------------------------
+    // Retrieve / count
+    // ---------------------------------------------------------------------
+    /** Fetch specific points by ID. IDs not found are simply omitted from the result. */
+    async retrieve(collectionName, ids, options = {}) {
+        const { withPayload, withVector, ...rest } = options;
+        return this.exec((c) => c.retrieve(collectionName, {
+            ids,
+            with_payload: withPayload,
+            with_vector: withVector,
+            ...rest,
+        }), 'RETRIEVE');
+    }
+    /** Count points in a collection, optionally matching a filter. */
+    async count(collectionName, filter, options = {}) {
+        const result = await this.exec((c) => c.count(collectionName, { filter, ...options }), 'COUNT');
+        return result.count;
+    }
+    // ---------------------------------------------------------------------
+    // Delete
+    // ---------------------------------------------------------------------
+    /** Delete points by explicit ID list. */
+    async deleteByIds(collectionName, ids, options = {}) {
+        return this.exec((c) => c.delete(collectionName, { points: ids, ...options }), 'DELETE');
+    }
+    /** Delete every point matching a filter. */
+    async deleteByFilter(collectionName, filter, options = {}) {
+        return this.exec((c) => c.delete(collectionName, { filter, ...options }), 'DELETE');
+    }
+    // ---------------------------------------------------------------------
+    // Payload management
+    // ---------------------------------------------------------------------
+    /**
+     * Merge `payload` into the existing payload of the selected points
+     * (existing keys not present in `payload` are left untouched).
+     */
+    async setPayload(collectionName, payload, selector, options = {}) {
+        return this.exec((c) => c.setPayload(collectionName, { payload, ...selectorArgs(selector), ...options }), 'SET PAYLOAD');
+    }
+    /**
+     * Replace the entire payload of the selected points with `payload`
+     * (unlike `setPayload()`, keys not present in `payload` are removed).
+     */
+    async overwritePayload(collectionName, payload, selector, options = {}) {
+        return this.exec((c) => c.overwritePayload(collectionName, { payload, ...selectorArgs(selector), ...options }), 'OVERWRITE PAYLOAD');
+    }
+    /** Remove specific payload keys from the selected points. */
+    async deletePayload(collectionName, keys, selector, options = {}) {
+        return this.exec((c) => c.deletePayload(collectionName, { keys, ...selectorArgs(selector), ...options }), 'DELETE PAYLOAD');
+    }
+    /** Remove the entire payload (all keys) from the selected points. */
+    async clearPayload(collectionName, selector, options = {}) {
+        return this.exec((c) => c.clearPayload(collectionName, { ...selectorArgs(selector), ...options }), 'CLEAR PAYLOAD');
+    }
+    // ---------------------------------------------------------------------
+    // Collection aliasing
+    // ---------------------------------------------------------------------
+    /** Create an alternative name (`aliasName`) for a collection; the collection is queryable under both names. */
+    async createAlias(collectionName, aliasName, timeout) {
+        return this.exec((c) => c.updateCollectionAliases({
+            actions: [{ create_alias: { collection_name: collectionName, alias_name: aliasName } }],
+            timeout,
+        }), 'CREATE ALIAS');
+    }
+    /** Delete an alias (the underlying collection and its other aliases are unaffected). */
+    async deleteAlias(aliasName, timeout) {
+        return this.exec((c) => c.updateCollectionAliases({
+            actions: [{ delete_alias: { alias_name: aliasName } }],
+            timeout,
+        }), 'DELETE ALIAS');
+    }
+    /** Atomically rename an alias (equivalent to delete + create in one operation). */
+    async renameAlias(oldAliasName, newAliasName, timeout) {
+        return this.exec((c) => c.updateCollectionAliases({
+            actions: [{ rename_alias: { old_alias_name: oldAliasName, new_alias_name: newAliasName } }],
+            timeout,
+        }), 'RENAME ALIAS');
+    }
+    /** List the aliases pointing at a specific collection. */
+    async getCollectionAliases(collectionName) {
+        return this.exec((c) => c.getCollectionAliases(collectionName), 'GET COLLECTION ALIASES');
+    }
+    /** List every alias across all collections. */
+    async getAliases() {
+        return this.exec((c) => c.getAliases(), 'GET ALIASES');
+    }
+}
+exports.QdrantStore = QdrantStore;
+/** Spread a `PointsSelector` (`{ points }` or `{ filter }`, plus optional `shard_key`) into request args. */
+function selectorArgs(selector) {
+    if ('points' in selector) {
+        return { points: selector.points };
+    }
+    return { filter: selector.filter };
+}
+exports.default = QdrantStore;

package/dist/nosql/qldb/index.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Amazon QLDB store implementation.
+ *
+ * Amazon QLDB (Quantum Ledger Database) is a fully managed, append-only,
+ * cryptographically verifiable ledger database. Data is written as documents
+ * into ledger tables and queried with PartiQL (a SQL-compatible query
+ * language). Every revision of every document is retained in an immutable
+ * journal; the built-in `history(<table>)` PartiQL function exposes prior
+ * revisions, and each revision carries `metadata` (document id, version,
+ * transaction time, and a content hash) that forms the basis of QLDB's
+ * tamper-evidence.
+ *
+ * QLDB is not a SQL `Dialect` (no client-side DDL escaping, no row-level
+ * UPDATE/DELETE semantics beyond PartiQL), so this class implements the
+ * minimal `NoSqlStore` marker interface plus the ledger surface shared by
+ * this family of stores: `append`/`get`/`history`/`verify`/`query`.
+ *
+ * ## Lazy driver loading
+ *
+ * The official `amazon-qldb-driver-nodejs` package is loaded lazily inside
+ * `connect()`, so importing this module never requires the driver to be
+ * installed. Tests (and callers with their own transport) inject a pre-built
+ * driver via `QldbStoreOptions.client`, which bypasses the `require` entirely.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QldbStore = void 0;
+const errors_1 = require("../../errors");
+/** A validated PartiQL identifier - QLDB cannot parameterize table names. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function assertIdentifier(name) {
+    if (!IDENTIFIER.test(name)) {
+        throw new errors_1.DatabaseError(`Invalid QLDB table name: ${JSON.stringify(name)}`, {
+            code: 'VALIDATION_ERROR',
+        });
+    }
+    return name;
+}
+/**
+ * `QldbStore` wraps an `amazon-qldb-driver-nodejs` driver behind the shared
+ * ledger surface. `append` inserts a new document (returning its QLDB
+ * document id), `get` reads the current revision by document id, `history`
+ * returns every prior revision via the `history()` PartiQL function,
+ * `verify` returns a document's revision metadata (content hash +
+ * block address - QLDB's tamper-evidence proof material), and `query` is the
+ * raw PartiQL escape hatch.
+ */
+class QldbStore {
+    constructor(options) {
+        this.name = 'qldb';
+        this.library = 'amazon-qldb-driver-nodejs';
+        this.driver = null;
+        this.connected = false;
+        if (!options || !options.ledgerName) {
+            throw new errors_1.DatabaseError('QldbStore requires a `ledgerName`', {
+                code: 'INVALID_CONNECTION',
+            });
+        }
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.driver) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                this.driver = this.options.client;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const mod = require('amazon-qldb-driver-nodejs');
+                const QldbDriver = mod.QldbDriver ?? mod.default?.QldbDriver ?? mod.default;
+                this.driver = new QldbDriver(this.options.ledgerName, this.options.region ? { region: this.options.region } : undefined);
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.driver = null;
+            this.connected = false;
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw new errors_1.ConnectionError(`Unable to connect to QLDB: ${parent.message}`, {
+                parent,
+                database: 'qldb',
+            });
+        }
+    }
+    async disconnect() {
+        if (this.driver && typeof this.driver.close === 'function') {
+            try {
+                await this.driver.close();
+            }
+            catch {
+                // best-effort close
+            }
+        }
+        this.driver = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.driver !== null;
+    }
+    /** Returns the underlying `QldbDriver` for anything not wrapped here. */
+    getClient() {
+        return this.requireDriver();
+    }
+    requireDriver() {
+        if (!this.driver || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to QLDB. Call connect() first.', {
+                database: 'qldb',
+            });
+        }
+        return this.driver;
+    }
+    /** Run a PartiQL statement inside a managed transaction and return the rows. */
+    async execute(statement, params, action) {
+        const driver = this.requireDriver();
+        try {
+            return await driver.executeLambda(async (txn) => {
+                const result = await txn.execute(statement, ...params);
+                return result.getResultList();
+            });
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `QLDB ${action} failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Ledger surface
+    // ---------------------------------------------------------------------
+    /**
+     * Insert `data` as a new document into `table`, returning its QLDB document
+     * id (the stable identifier every revision of the document shares). Runs
+     * `INSERT INTO <table> ?`.
+     */
+    async append(table, data) {
+        const rows = await this.execute(`INSERT INTO ${assertIdentifier(table)} ?`, [data], 'append');
+        const first = rows[0];
+        return first?.documentId ?? String(first?.documentId ?? '');
+    }
+    /**
+     * Read the current revision of the document with QLDB document id `id`,
+     * addressed via PartiQL's `BY` clause. Returns the row or `null`.
+     */
+    async get(table, id) {
+        const rows = await this.execute(`SELECT * FROM ${assertIdentifier(table)} BY docId WHERE docId = ?`, [id], 'get');
+        return rows[0] ?? null;
+    }
+    /**
+     * Return every revision (including deletions) of the document with id `id`
+     * via the `history(<table>)` PartiQL function. Each entry carries `data`,
+     * `metadata`, `blockAddress` and `hash`.
+     */
+    async history(table, id) {
+        return this.execute(`SELECT * FROM history(${assertIdentifier(table)}) AS h WHERE h.metadata.id = ?`, [id], 'history');
+    }
+    /**
+     * Return the tamper-evidence proof material for document `id`: its revision
+     * `metadata` (content hash + version) and `blockAddress` from the journal,
+     * pulled from `history()`. This is the data QLDB's server-side digest/proof
+     * APIs cryptographically verify a revision against.
+     */
+    async verify(table, id) {
+        const rows = await this.execute(`SELECT metadata, blockAddress, hash FROM history(${assertIdentifier(table)}) AS h WHERE h.metadata.id = ?`, [id], 'verify');
+        return { documentId: id, revisions: rows };
+    }
+    /** Run a raw PartiQL `statement` with optional positional `params`. */
+    async query(statement, params = []) {
+        return this.execute(statement, params, 'query');
+    }
+    /** List the active table names in the ledger (thin passthrough). */
+    async tableNames() {
+        const driver = this.requireDriver();
+        if (typeof driver.getTableNames !== 'function') {
+            throw new errors_1.DatabaseError('QLDB driver does not support getTableNames()', {
+                code: 'QUERY_ERROR',
+            });
+        }
+        try {
+            return await driver.getTableNames();
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `QLDB tableNames failed: ${parent.message}` });
+        }
+    }
+}
+exports.QldbStore = QldbStore;
+exports.default = QldbStore;