ts-prorm-orm 1.1.0

package/dist/nosql/memcached/index.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Memcached store implementation.
+ *
+ * Memcached is a distributed in-memory key-value cache. It has no query
+ * language, no secondary indexes and no persistence, so it does not fit the
+ * SQL-shaped `Dialect` interface. This class implements the minimal
+ * `NoSqlStore` marker interface and exposes Memcached's real operations
+ * (set/get/delete/add/replace/increment/decrement/flush) as a typed,
+ * promise-based API instead of forcing them into a `query(sql)` shape.
+ *
+ * Uses the `memjs` driver. The driver is loaded lazily inside `connect()`
+ * (or supplied pre-built via the `client` option) so importing this module
+ * never requires `memjs` to be installed unless a Memcached store is
+ * actually connected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemcachedStore = 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 Memcached: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'memcached', host });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `Memcached ${action} failed: ${parent.message}` });
+}
+/**
+ * Serialize a value for storage. Strings and Buffers are stored verbatim;
+ * everything else (numbers, booleans, objects, arrays) is JSON-encoded so
+ * it round-trips through `get(key, { decode: 'json' })`.
+ */
+function serialize(value) {
+    if (typeof value === 'string' || Buffer.isBuffer(value)) {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * `MemcachedStore` wraps a `memjs` client and exposes Memcached's key-value
+ * operations as a typed, promise-based API.
+ */
+class MemcachedStore {
+    constructor(options = {}) {
+        this.name = 'memcached';
+        this.library = 'memjs';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                // A pre-built client was injected - use it as-is and skip the
+                // lazy require entirely (tests inject a mock this way).
+                this.client = this.options.client;
+            }
+            else {
+                // Lazily load memjs so importing this module never requires the
+                // driver unless a store is actually connected.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const memjs = require('memjs');
+                this.client = memjs.Client.create(this.options.servers, this.options.options);
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.servers);
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            if (typeof this.client.close === 'function') {
+                this.client.close();
+            }
+            else if (typeof this.client.quit === 'function') {
+                this.client.quit();
+            }
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    /** Alias for `disconnect()`, mirroring memjs's own `quit()`/`close()` naming. */
+    async quit() {
+        return this.disconnect();
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `memjs` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Memcached', { database: 'memcached' });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Key-value operations
+    // ---------------------------------------------------------------------
+    /**
+     * Store `value` under `key`, overwriting any existing value. Strings and
+     * Buffers are stored verbatim; other values are JSON-serialized (see
+     * `serialize`). Returns memjs's boolean success flag.
+     */
+    async set(key, value, options) {
+        const client = this.requireClient();
+        try {
+            return await client.set(key, serialize(value), options);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'SET');
+        }
+    }
+    /**
+     * Read `key`. Returns `null` if the key is missing. By default returns the
+     * raw `Buffer`; pass `{ decode: 'string' }` or `{ decode: 'json' }` to
+     * decode the stored value.
+     */
+    async get(key, options = {}) {
+        const client = this.requireClient();
+        try {
+            const result = await client.get(key);
+            const value = result ? result.value : null;
+            if (value === null || value === undefined) {
+                return null;
+            }
+            switch (options.decode) {
+                case 'string':
+                    return value.toString('utf8');
+                case 'json':
+                    return JSON.parse(value.toString('utf8'));
+                case 'buffer':
+                default:
+                    return value;
+            }
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'GET');
+        }
+    }
+    /** Delete `key`. Returns memjs's boolean success flag. */
+    async delete(key) {
+        const client = this.requireClient();
+        try {
+            return await client.delete(key);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'DELETE');
+        }
+    }
+    /**
+     * Store `value` under `key` only if the key does not already exist
+     * (Memcached `add`). Returns `false` if the key was already present.
+     */
+    async add(key, value, options) {
+        const client = this.requireClient();
+        try {
+            return await client.add(key, serialize(value), options);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'ADD');
+        }
+    }
+    /**
+     * Store `value` under `key` only if the key already exists (Memcached
+     * `replace`). Returns `false` if the key was missing.
+     */
+    async replace(key, value, options) {
+        const client = this.requireClient();
+        try {
+            return await client.replace(key, serialize(value), options);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'REPLACE');
+        }
+    }
+    /** Atomically increment the numeric value at `key` by `amount`. */
+    async increment(key, amount, options) {
+        const client = this.requireClient();
+        try {
+            return await client.increment(key, amount, options);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'INCREMENT');
+        }
+    }
+    /** Atomically decrement the numeric value at `key` by `amount`. */
+    async decrement(key, amount, options) {
+        const client = this.requireClient();
+        try {
+            return await client.decrement(key, amount, options);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'DECREMENT');
+        }
+    }
+    /** Flush (delete) all keys across every configured server. */
+    async flush() {
+        const client = this.requireClient();
+        try {
+            return await client.flush();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'FLUSH');
+        }
+    }
+}
+exports.MemcachedStore = MemcachedStore;
+exports.default = MemcachedStore;

package/dist/nosql/milvus/index.js

@@ -0,0 +1,410 @@
+"use strict";
+/**
+ * Milvus store implementation.
+ *
+ * Milvus is a vector database: collections are defined by a field schema
+ * (a primary key, one or more vector fields with a fixed dimension, and
+ * optional scalar fields) rather than rows of arbitrary SQL types, queries
+ * are approximate-nearest-neighbor searches (or scalar filter expressions)
+ * rather than `SELECT ... WHERE`, and there is no join/transaction-log
+ * concept. None of that fits the SQL-shaped `Dialect` interface, so this
+ * class implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes Milvus's real operations (collection
+ * management, index management, insert/upsert, vector search, scalar
+ * query, delete, and partitions) grouped the way the underlying SDK groups
+ * them, instead of forcing everything into a `query(sql)` shape.
+ *
+ * Uses the official `@zilliz/milvus2-sdk-node` gRPC client.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MilvusStore = void 0;
+const milvus2_sdk_node_1 = require("@zilliz/milvus2-sdk-node");
+const errors_1 = require("../../errors");
+function isSuccess(errorCode) {
+    return errorCode === undefined || errorCode === milvus2_sdk_node_1.ErrorCode.SUCCESS || errorCode === 0;
+}
+function checkStatus(status, action) {
+    if (!status)
+        return;
+    if (!isSuccess(status.error_code)) {
+        throw new errors_1.DatabaseError(`Milvus ${action} failed: ${status.reason || status.error_code}`, {
+            original: status.reason,
+        });
+    }
+}
+function wrapConnectionError(err, address) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Milvus: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'milvus', host: address });
+}
+function wrapDatabaseError(err, message) {
+    if (err instanceof errors_1.DatabaseError) {
+        return err;
+    }
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const combined = message ? `${message}: ${parent.message}` : parent.message;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/** Convert an `IndexDescription` (the raw wire shape) to the friendlier `MilvusIndexInfo`. */
+function toIndexInfo(desc) {
+    const params = Object.fromEntries((desc.params || []).map((p) => [p.key, p.value]));
+    return {
+        indexName: desc.index_name,
+        fieldName: desc.field_name,
+        indexType: params.index_type,
+        metricType: params.metric_type,
+        state: desc.state,
+        indexedRows: desc.indexed_rows,
+        totalRows: desc.total_rows,
+    };
+}
+/**
+ * `MilvusStore` wraps `@zilliz/milvus2-sdk-node`'s `MilvusClient` and exposes
+ * Milvus's collection/index/data/partition operations as a typed,
+ * promise-based API.
+ */
+class MilvusStore {
+    constructor(options) {
+        this.name = 'milvus';
+        this.library = '@zilliz/milvus2-sdk-node';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            const client = new milvus2_sdk_node_1.MilvusClient(this.options);
+            const health = await client.checkHealth();
+            if (!health.isHealthy) {
+                throw new Error('Milvus server reported unhealthy');
+            }
+            this.client = client;
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.address);
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.closeConnection();
+            }
+            catch {
+                // ignore - we're tearing down anyway
+            }
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `MilvusClient` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Milvus', { database: 'milvus' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Milvus ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Collection management
+    // ---------------------------------------------------------------------
+    /** Create a collection with an explicit field schema (primary key + one or more vector fields + optional scalars). */
+    async createCollection(collectionName, fields, options = {}) {
+        return this.exec(async (c) => {
+            const req = {
+                collection_name: collectionName,
+                description: options.description,
+                shards_num: options.shardsNum,
+                consistency_level: options.consistencyLevel,
+                enable_dynamic_field: options.enableDynamicField,
+                fields: fields.map((f) => ({
+                    name: f.name,
+                    data_type: f.data_type,
+                    is_primary_key: f.is_primary_key,
+                    autoID: f.autoID,
+                    is_partition_key: f.is_partition_key,
+                    description: f.description,
+                    type_params: {
+                        ...(f.dim !== undefined ? { dim: f.dim } : {}),
+                        ...(f.max_length !== undefined ? { max_length: f.max_length } : {}),
+                    },
+                })),
+            };
+            const status = await c.createCollection(req);
+            checkStatus(status, `createCollection(${collectionName})`);
+        }, 'createCollection');
+    }
+    async dropCollection(collectionName) {
+        return this.exec(async (c) => {
+            const req = { collection_name: collectionName };
+            const status = await c.dropCollection(req);
+            checkStatus(status, `dropCollection(${collectionName})`);
+        }, 'dropCollection');
+    }
+    async hasCollection(collectionName) {
+        return this.exec(async (c) => {
+            const res = await c.hasCollection({ collection_name: collectionName });
+            checkStatus(res.status, `hasCollection(${collectionName})`);
+            return Boolean(res.value);
+        }, 'hasCollection');
+    }
+    async describeCollection(collectionName) {
+        return this.exec(async (c) => {
+            const res = await c.describeCollection({ collection_name: collectionName });
+            checkStatus(res.status, `describeCollection(${collectionName})`);
+            return res;
+        }, 'describeCollection');
+    }
+    /** List all collections. */
+    async listCollections() {
+        return this.exec(async (c) => {
+            const res = await c.showCollections();
+            checkStatus(res.status, 'listCollections');
+            return res.data;
+        }, 'listCollections');
+    }
+    /** Load a collection's data into query nodes' memory so it can be searched/queried. */
+    async loadCollection(collectionName, replicaNumber) {
+        return this.exec(async (c) => {
+            const req = { collection_name: collectionName, replica_number: replicaNumber };
+            const status = await c.loadCollection(req);
+            checkStatus(status, `loadCollection(${collectionName})`);
+        }, 'loadCollection');
+    }
+    /** Release a collection's data from memory (it remains persisted; reload with `loadCollection()` to search it again). */
+    async releaseCollection(collectionName) {
+        return this.exec(async (c) => {
+            const req = { collection_name: collectionName };
+            const status = await c.releaseCollection(req);
+            checkStatus(status, `releaseCollection(${collectionName})`);
+        }, 'releaseCollection');
+    }
+    async getCollectionStatistics(collectionName) {
+        return this.exec(async (c) => {
+            const res = await c.getCollectionStatistics({ collection_name: collectionName });
+            checkStatus(res.status, `getCollectionStatistics(${collectionName})`);
+            return res.data;
+        }, 'getCollectionStatistics');
+    }
+    // ---------------------------------------------------------------------
+    // Index management
+    // ---------------------------------------------------------------------
+    async createIndex(collectionName, options) {
+        return this.exec(async (c) => {
+            const req = {
+                collection_name: collectionName,
+                field_name: options.fieldName,
+                index_type: options.indexType,
+                metric_type: options.metricType,
+                index_name: options.indexName,
+                params: options.params,
+            };
+            const status = await c.createIndex(req);
+            checkStatus(status, `createIndex(${collectionName}.${options.fieldName})`);
+        }, 'createIndex');
+    }
+    async dropIndex(collectionName, fieldName, indexName) {
+        return this.exec(async (c) => {
+            const status = await c.dropIndex({ collection_name: collectionName, field_name: fieldName, index_name: indexName });
+            checkStatus(status, `dropIndex(${collectionName})`);
+        }, 'dropIndex');
+    }
+    async describeIndex(collectionName, fieldName) {
+        return this.exec(async (c) => {
+            const res = await c.describeIndex({ collection_name: collectionName, field_name: fieldName });
+            checkStatus(res.status, `describeIndex(${collectionName})`);
+            return res.index_descriptions.map(toIndexInfo);
+        }, 'describeIndex');
+    }
+    async listIndexes(collectionName) {
+        return this.exec(async (c) => {
+            const res = await c.listIndexes({ collection_name: collectionName });
+            checkStatus(res.status, `listIndexes(${collectionName})`);
+            return res.indexes;
+        }, 'listIndexes');
+    }
+    // ---------------------------------------------------------------------
+    // Data: insert / upsert
+    // ---------------------------------------------------------------------
+    async insert(collectionName, rows, options = {}) {
+        return this.exec(async (c) => {
+            const res = await c.insert({ collection_name: collectionName, data: rows, partition_name: options.partitionName });
+            checkStatus(res.status, `insert(${collectionName})`);
+            return res;
+        }, 'insert');
+    }
+    async upsert(collectionName, rows, options = {}) {
+        return this.exec(async (c) => {
+            const res = await c.upsert({ collection_name: collectionName, data: rows, partition_name: options.partitionName });
+            checkStatus(res.status, `upsert(${collectionName})`);
+            return res;
+        }, 'upsert');
+    }
+    // ---------------------------------------------------------------------
+    // Vector search
+    // ---------------------------------------------------------------------
+    /**
+     * Approximate-nearest-neighbor search against a vector field. Ranks by
+     * the collection's index metric (`L2`/`IP`/`COSINE`/...), optionally
+     * narrowed by a scalar `filter` expression evaluated alongside the
+     * vector comparison.
+     */
+    async search(collectionName, options) {
+        return this.exec(async (c) => {
+            const req = {
+                collection_name: collectionName,
+                data: options.vector,
+                anns_field: options.annsField,
+                limit: options.limit ?? 10,
+                filter: options.filter,
+                output_fields: options.outputFields,
+                partition_names: options.partitionNames,
+                metric_type: options.metricType,
+                offset: options.offset,
+            };
+            const res = await c.search(req);
+            checkStatus(res.status, `search(${collectionName})`);
+            const hits = res.results;
+            return hits.map((hit) => ({ ...hit, id: hit.id, score: hit.score }));
+        }, 'search');
+    }
+    // ---------------------------------------------------------------------
+    // Scalar query
+    // ---------------------------------------------------------------------
+    /** Scalar-only lookup (no vector similarity) via a filter expression and/or primary key list. */
+    async query(collectionName, options = {}) {
+        return this.exec(async (c) => {
+            const req = {
+                collection_name: collectionName,
+                filter: options.filter,
+                ids: options.ids,
+                output_fields: options.outputFields,
+                partition_names: options.partitionNames,
+                limit: options.limit,
+                offset: options.offset,
+            };
+            const res = await c.query(req);
+            checkStatus(res.status, `query(${collectionName})`);
+            return res.data;
+        }, 'query');
+    }
+    /** Fetch specific rows by primary key. Equivalent to `query()` with `ids` set, using Milvus's dedicated `Get` RPC. */
+    async get(collectionName, ids, outputFields) {
+        return this.exec(async (c) => {
+            const res = await c.get({
+                collection_name: collectionName,
+                ids: ids,
+                output_fields: outputFields,
+            });
+            checkStatus(res.status, `get(${collectionName})`);
+            return res.data;
+        }, 'get');
+    }
+    /** Count rows matching an optional filter expression (all rows if omitted). */
+    async count(collectionName, filter) {
+        return this.exec(async (c) => {
+            const res = await c.count({ collection_name: collectionName, expr: filter });
+            checkStatus(res.status, `count(${collectionName})`);
+            return res.data;
+        }, 'count');
+    }
+    // ---------------------------------------------------------------------
+    // Delete
+    // ---------------------------------------------------------------------
+    async deleteByIds(collectionName, ids, partitionName) {
+        return this.exec(async (c) => {
+            const res = await c.delete({
+                collection_name: collectionName,
+                ids: ids,
+                partition_name: partitionName,
+            });
+            checkStatus(res.status, `delete(${collectionName})`);
+            return res;
+        }, 'delete');
+    }
+    async deleteByFilter(collectionName, filter, partitionName) {
+        return this.exec(async (c) => {
+            const res = await c.delete({ collection_name: collectionName, filter, partition_name: partitionName });
+            checkStatus(res.status, `delete(${collectionName})`);
+            return res;
+        }, 'delete');
+    }
+    // ---------------------------------------------------------------------
+    // Partitions
+    // ---------------------------------------------------------------------
+    async createPartition(collectionName, partitionName) {
+        return this.exec(async (c) => {
+            const status = await c.createPartition({ collection_name: collectionName, partition_name: partitionName });
+            checkStatus(status, `createPartition(${collectionName}.${partitionName})`);
+        }, 'createPartition');
+    }
+    async dropPartition(collectionName, partitionName) {
+        return this.exec(async (c) => {
+            const status = await c.dropPartition({ collection_name: collectionName, partition_name: partitionName });
+            checkStatus(status, `dropPartition(${collectionName}.${partitionName})`);
+        }, 'dropPartition');
+    }
+    async hasPartition(collectionName, partitionName) {
+        return this.exec(async (c) => {
+            const res = await c.hasPartition({ collection_name: collectionName, partition_name: partitionName });
+            checkStatus(res.status, `hasPartition(${collectionName}.${partitionName})`);
+            return Boolean(res.value);
+        }, 'hasPartition');
+    }
+    async listPartitions(collectionName) {
+        return this.exec(async (c) => {
+            const res = await c.listPartitions({ collection_name: collectionName });
+            checkStatus(res.status, `listPartitions(${collectionName})`);
+            return res.partition_names;
+        }, 'listPartitions');
+    }
+    async loadPartitions(collectionName, partitionNames, replicaNumber) {
+        return this.exec(async (c) => {
+            const status = await c.loadPartitions({
+                collection_name: collectionName,
+                partition_names: partitionNames,
+                replica_number: replicaNumber,
+            });
+            checkStatus(status, `loadPartitions(${collectionName})`);
+        }, 'loadPartitions');
+    }
+    async releasePartitions(collectionName, partitionNames) {
+        return this.exec(async (c) => {
+            const status = await c.releasePartitions({ collection_name: collectionName, partition_names: partitionNames });
+            checkStatus(status, `releasePartitions(${collectionName})`);
+        }, 'releasePartitions');
+    }
+    async getPartitionStatistics(collectionName, partitionName) {
+        return this.exec(async (c) => {
+            const res = await c.getPartitionStatistics({ collection_name: collectionName, partition_name: partitionName });
+            checkStatus(res.status, `getPartitionStatistics(${collectionName}.${partitionName})`);
+            return res.data;
+        }, 'getPartitionStatistics');
+    }
+}
+exports.MilvusStore = MilvusStore;
+exports.default = MilvusStore;