ts-prorm-orm 1.1.0

package/dist/nosql/cassandra/index.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CassandraStore = void 0;
+/**
+ * Apache Cassandra (CQL) store.
+ *
+ * Cassandra is a wide-column, partition-key-based distributed store queried
+ * with CQL (Cassandra Query Language). While CQL looks superficially like
+ * SQL, it deliberately omits joins, arbitrary WHERE-clause filtering, and
+ * subqueries: every query must be answerable from a single partition (or an
+ * explicitly designed secondary index / materialized view), and data is
+ * modelled query-first around partition and clustering keys. That model does
+ * not fit the SQL-shaped `Dialect` interface (`src/dialects/dialect.ts`), so
+ * this store implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes Cassandra's own CQL execution surface
+ * directly rather than pretending to be a relational dialect.
+ *
+ * Built on the `cassandra-driver` (DataStax Node.js driver). The driver is an
+ * optional peer dependency and is loaded lazily inside `connect()` (via
+ * `require`) so importing this module never forces the driver to be
+ * installed; tests inject a pre-built mock `Client` instead.
+ */
+const errors_1 = require("../../errors");
+/**
+ * `CassandraStore` wraps a `cassandra-driver` `Client` and exposes CQL
+ * execution (`execute`), atomic multi-statement batches (`batch`), and a few
+ * parameterized convenience helpers (`insert`, `selectAll`).
+ *
+ * Statements are prepared by default (`prepare: true`) so the driver can cache
+ * query metadata, infer parameter types, and route requests to replica nodes
+ * that own the partition — the recommended default for anything run more than
+ * once.
+ */
+class CassandraStore {
+    constructor(options = {}) {
+        this.name = 'cassandra';
+        this.library = 'cassandra-driver';
+        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) {
+                // Lazy-load the optional driver so importing this module never
+                // requires `cassandra-driver` to be installed. Tests inject a mock
+                // `client` above and never reach this branch.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const cql = require('cassandra-driver');
+                client = new cql.Client({
+                    contactPoints: this.options.contactPoints,
+                    localDataCenter: this.options.localDataCenter,
+                    keyspace: this.options.keyspace,
+                    credentials: this.options.credentials,
+                    ...this.options.clientOptions,
+                });
+            }
+            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 Cassandra: ${parent.message}`, {
+                parent,
+                database: 'cassandra',
+                host: this.options.contactPoints?.[0],
+            });
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.shutdown();
+            }
+            finally {
+                this.client = null;
+                this.connected = false;
+            }
+        }
+        else {
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `cassandra-driver` `Client` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Cassandra client is not connected. Call connect() first.', {
+                database: 'cassandra',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `Cassandra ${action} failed: ${parent.message}` });
+    }
+    // ---------------------------------------------------------------------
+    // CQL execution
+    // ---------------------------------------------------------------------
+    /**
+     * Execute a single CQL statement with optional bound `params`. Statements
+     * are prepared by default (`prepare: true`); pass `opts.prepare = false` to
+     * run a one-off unprepared. Any other driver query options (consistency,
+     * fetchSize, pageState, ...) are forwarded via `opts`. Returns the full
+     * driver result (with `.rows`).
+     */
+    async execute(query, params = [], opts = {}) {
+        const client = this.requireClient();
+        try {
+            return (await client.execute(query, params, { prepare: true, ...opts }));
+        }
+        catch (err) {
+            throw this.wrapError(`execute (${query})`, err);
+        }
+    }
+    /**
+     * Execute multiple statements as a single logged batch (atomic across the
+     * statements, though not isolated — Cassandra batches are not SQL
+     * transactions). Each entry is a `{ query, params }` pair. Prepared by
+     * default; forward other driver batch options via `opts`.
+     */
+    async batch(queries, opts = {}) {
+        const client = this.requireClient();
+        try {
+            return await client.batch(queries, { prepare: true, ...opts });
+        }
+        catch (err) {
+            throw this.wrapError('batch', err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Convenience helpers
+    // ---------------------------------------------------------------------
+    /**
+     * Convenience `INSERT`: builds a parameterized
+     * `INSERT INTO table (cols...) VALUES (?, ?, ...)` from `obj`'s keys and
+     * executes it (prepared). For upserts with TTL, IF NOT EXISTS, or other
+     * clauses, write the CQL yourself and call `execute()`.
+     */
+    async insert(table, obj, opts = {}) {
+        const columns = Object.keys(obj);
+        if (columns.length === 0) {
+            throw new errors_1.DatabaseError('insert() requires at least one column', {
+                original: 'empty insert object',
+            });
+        }
+        const placeholders = columns.map(() => '?').join(', ');
+        const query = `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${placeholders})`;
+        const params = columns.map((c) => obj[c]);
+        return this.execute(query, params, opts);
+    }
+    /** Convenience `SELECT * FROM table`. Returns the full driver result (with `.rows`). */
+    async selectAll(table, opts = {}) {
+        return this.execute(`SELECT * FROM ${table}`, [], opts);
+    }
+}
+exports.CassandraStore = CassandraStore;
+exports.default = CassandraStore;

package/dist/nosql/chroma/index.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Chroma (ChromaDB) vector-database store.
+ *
+ * Chroma is an embedding database organized around *collections*: a
+ * collection holds records that are `{ id, embedding, metadata?, document? }`
+ * tuples, and the core operation is an approximate-nearest-neighbor `query`
+ * over a collection's embeddings (optionally narrowed by a metadata `where`
+ * filter) - not SQL, not joins, not a transaction log. None of that fits
+ * the SQL-shaped `Dialect` interface used by the SQL dialects in this repo,
+ * so this class implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes Chroma's real collection- and
+ * embedding-level operations directly.
+ *
+ * Uses the `chromadb` driver, lazy-loaded inside `connect()` via `require()`
+ * so the dependency is only needed when a Chroma store is actually
+ * constructed (tests inject a pre-built mock `client` instead). The client
+ * talks to Chroma's HTTP API and is stateless, so `connect()`/`disconnect()`
+ * construct/discard the client rather than opening a real socket.
+ *
+ * Every embedding-level method takes a collection *name*; the underlying
+ * `Collection` handle is resolved (and cached) via
+ * `client.getOrCreateCollection(...)` so callers never have to thread a
+ * collection object through by hand.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChromaStore = void 0;
+const errors_1 = require("../../errors");
+function wrapConnectionError(err, path) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused|fetch failed/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Chroma: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'chroma', host: path });
+}
+function wrapDatabaseError(err, message) {
+    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 });
+}
+/**
+ * `ChromaStore` wraps a `chromadb` `ChromaClient` and exposes Chroma's
+ * collection management plus the embedding data-plane operations
+ * (add/query/get/delete) as a typed, promise-based API.
+ */
+class ChromaStore {
+    constructor(options = {}) {
+        this.name = 'chroma';
+        this.library = 'chromadb';
+        this.client = null;
+        this.connected = false;
+        /** One `Collection` handle per collection name, reused across calls. */
+        this.collectionCache = new Map();
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                // A client was injected (e.g. a test mock) - use it as-is and skip
+                // the driver require()/new ChromaClient() step.
+                this.client = this.options.client;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { ChromaClient } = require('chromadb');
+                this.client = new ChromaClient({ path: this.options.path });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.path);
+        }
+    }
+    async disconnect() {
+        // The Chroma client is a stateless HTTP client - there is no socket to
+        // close, so "disconnecting" just drops the client + cached handles.
+        this.client = null;
+        this.connected = false;
+        this.collectionCache.clear();
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `ChromaClient` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Chroma', { database: 'chroma' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Chroma ${action} failed`);
+        }
+    }
+    /** Resolve (and cache) a `Collection` handle for `name` via `getOrCreateCollection`. */
+    async resolveCollection(name) {
+        const cached = this.collectionCache.get(name);
+        if (cached) {
+            return cached;
+        }
+        const collection = await this.requireClient().getOrCreateCollection({ name });
+        this.collectionCache.set(name, collection);
+        return collection;
+    }
+    // ---------------------------------------------------------------------
+    // Collection management
+    // ---------------------------------------------------------------------
+    /** Create a new collection. Fails if a collection with `name` already exists. */
+    async createCollection(name, options = {}) {
+        return this.exec(async (c) => {
+            const collection = await c.createCollection({ name, ...options });
+            this.collectionCache.set(name, collection);
+            return collection;
+        }, 'CREATE COLLECTION');
+    }
+    /** Get an existing collection, creating it if it doesn't exist. Idempotent. */
+    async getOrCreateCollection(name, options = {}) {
+        return this.exec(async (c) => {
+            const collection = await c.getOrCreateCollection({ name, ...options });
+            this.collectionCache.set(name, collection);
+            return collection;
+        }, 'GET OR CREATE COLLECTION');
+    }
+    /** Delete a collection and all of its embeddings. */
+    async deleteCollection(name) {
+        return this.exec(async (c) => {
+            const result = await c.deleteCollection({ name });
+            this.collectionCache.delete(name);
+            return result;
+        }, 'DELETE COLLECTION');
+    }
+    // ---------------------------------------------------------------------
+    // Embedding data plane
+    // ---------------------------------------------------------------------
+    /**
+     * Add embeddings to a collection. `ids`/`embeddings` (and optional
+     * `metadatas`/`documents`) are index-aligned parallel arrays - the i-th
+     * id/embedding/metadata/document all describe the same record.
+     */
+    async addEmbeddings(collection, params) {
+        return this.exec(async () => {
+            const col = await this.resolveCollection(collection);
+            return col.add(params);
+        }, 'ADD');
+    }
+    /**
+     * Find, for each query embedding, the `nResults` closest records in a
+     * collection (optionally narrowed by a metadata `where` filter). Returns
+     * the driver's raw response (`{ ids, distances, metadatas, documents, ... }`,
+     * each an array-per-query-embedding).
+     */
+    async query(collection, params) {
+        return this.exec(async () => {
+            const col = await this.resolveCollection(collection);
+            return col.query(params);
+        }, 'QUERY');
+    }
+    /** Fetch records by id (and/or a metadata `where` filter) from a collection. */
+    async get(collection, params) {
+        return this.exec(async () => {
+            const col = await this.resolveCollection(collection);
+            return col.get(params);
+        }, 'GET');
+    }
+    /** Delete records from a collection by id (and/or a metadata `where` filter). */
+    async deleteEmbeddings(collection, params) {
+        return this.exec(async () => {
+            const col = await this.resolveCollection(collection);
+            return col.delete(params);
+        }, 'DELETE');
+    }
+}
+exports.ChromaStore = ChromaStore;
+exports.default = ChromaStore;

package/dist/nosql/cloudflare-kv/index.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Cloudflare Workers KV store implementation.
+ *
+ * Cloudflare Workers KV is a globally-distributed, eventually-consistent
+ * key-value store exposed over Cloudflare's REST API. It has no query
+ * language and does not fit the SQL-shaped `Dialect` interface, so this
+ * class implements the minimal `NoSqlStore` marker interface and exposes a
+ * small edge-KV surface (`get`/`set`/`del`/`list`/`incr`) mapped onto the
+ * REST endpoints.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Workers KV has no first-party Node client; it is just an HTTP/JSON API.
+ * This store talks to it with the global `fetch` (so `library` is
+ * `'fetch'`). For tests (and callers who want their own transport) an
+ * alternative HTTP client can be injected via `client`; when omitted a tiny
+ * internal `fetch`-based client is built at `connect()` time using the
+ * account/namespace/token options.
+ *
+ * ## Endpoints wrapped
+ *
+ * All under `/accounts/<accountId>/storage/kv/namespaces/<namespaceId>`:
+ * - `get(key)`    -> `GET    .../values/<key>`   (404 => `null`)
+ * - `set(k,v)`    -> `PUT    .../values/<key>`   (body + optional expiration)
+ * - `del(key)`    -> `DELETE .../values/<key>`
+ * - `list(pref?)` -> `GET    .../keys?prefix=`   (returns the key names)
+ * - `incr(k,by?)` -> read-modify-write over `get`/`set` (KV has no atomic
+ *   increment; documented as non-atomic).
+ *
+ * ## Serialization
+ *
+ * String values are stored verbatim; every other value is `JSON.stringify`'d
+ * before being written.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CloudflareKvStore = exports.DEFAULT_CLOUDFLARE_API_BASE_URL = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+/** Default Cloudflare API base URL. */
+exports.DEFAULT_CLOUDFLARE_API_BASE_URL = 'https://api.cloudflare.com/client/v4';
+function serialize(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/** Build a `fetch`-backed HTTP client for the Cloudflare KV REST API. */
+function createFetchClient(baseURL, apiToken) {
+    const root = baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL;
+    return {
+        async request(method, path, init) {
+            const url = new URL(root + path);
+            for (const [key, value] of Object.entries(init?.query ?? {})) {
+                if (value !== undefined)
+                    url.searchParams.set(key, value);
+            }
+            const headers = {};
+            if (apiToken)
+                headers.Authorization = `Bearer ${apiToken}`;
+            if (init?.body !== undefined)
+                headers['Content-Type'] = 'text/plain';
+            return fetch(url.toString(), { method, headers, body: init?.body });
+        },
+    };
+}
+/**
+ * `CloudflareKvStore` wraps the Cloudflare Workers KV REST API behind the
+ * `NoSqlStore` lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr`
+ * surface.
+ */
+class CloudflareKvStore {
+    constructor(options = {}) {
+        this.name = 'cloudflare-kv';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+        this.baseURL = options.baseURL ?? exports.DEFAULT_CLOUDFLARE_API_BASE_URL;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            this.client =
+                this.options.client ?? createFetchClient(this.baseURL, this.options.apiToken);
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.baseURL);
+        }
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying (internal or injected) HTTP client. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Cloudflare KV', {
+                database: 'cloudflare-kv',
+                host: this.baseURL,
+            });
+        }
+        return this.client;
+    }
+    namespacePath() {
+        const { accountId, namespaceId } = this.options;
+        return `/accounts/${accountId}/storage/kv/namespaces/${namespaceId}`;
+    }
+    valuePath(key) {
+        return `${this.namespacePath()}/values/${encodeURIComponent(key)}`;
+    }
+    // ---------------------------------------------------------------------
+    // Key-value operations
+    // ---------------------------------------------------------------------
+    /** Read a key. Returns `null` on a 404 (missing key). */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            const res = await client.request('GET', this.valuePath(key));
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            return await res.text();
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'GET');
+        }
+    }
+    /**
+     * Write `value` under `key`. Strings are stored verbatim; other values are
+     * JSON-serialized. `options.ttl` maps to `expiration_ttl` (seconds),
+     * `options.expiration` to `expiration` (absolute Unix seconds).
+     */
+    async set(key, value, options = {}) {
+        const client = this.requireClient();
+        const query = {};
+        if (options.ttl !== undefined)
+            query.expiration_ttl = String(options.ttl);
+        if (options.expiration !== undefined)
+            query.expiration = String(options.expiration);
+        try {
+            const res = await client.request('PUT', this.valuePath(key), {
+                body: serialize(value),
+                query,
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'SET');
+        }
+    }
+    /** Delete a key. */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            const res = await client.request('DELETE', this.valuePath(key));
+            if (!res.ok && res.status !== 404)
+                throw new Error(`HTTP ${res.status}`);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'DEL');
+        }
+    }
+    /** List key names, optionally filtered by `prefix`. */
+    async list(prefix) {
+        const client = this.requireClient();
+        try {
+            const res = await client.request('GET', `${this.namespacePath()}/keys`, {
+                query: { prefix },
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            const body = await res.json();
+            const result = body?.result ?? [];
+            return result.map((entry) => entry.name);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'LIST');
+        }
+    }
+    /**
+     * Increment the numeric value at `key` by `by` (default `1`). Workers KV
+     * has no atomic increment, so this is a non-atomic read-modify-write.
+     */
+    async incr(key, by = 1) {
+        const current = await this.get(key);
+        const next = (current === null ? 0 : Number(current)) + by;
+        await this.set(key, String(next));
+        return next;
+    }
+}
+exports.CloudflareKvStore = CloudflareKvStore;
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return new errors_1.ConnectionError(`Unable to connect to Cloudflare KV: ${parent.message}`, {
+        parent,
+        database: 'cloudflare-kv',
+        host,
+    });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, {
+        message: `Cloudflare KV ${action} failed: ${parent.message}`,
+    });
+}
+exports.default = CloudflareKvStore;