ts-prorm-orm 1.1.0

package/dist/nosql/unqlite/index.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnqliteStore = void 0;
+/**
+ * UnQLite store.
+ *
+ * UnQLite is an embedded, in-process, serverless database engine with a simple
+ * key-value store layer (plus a document store, not modelled here). A database
+ * is opened against a filesystem path and exposes KV primitives — `store`,
+ * `fetch`, `delete`, and record iteration. It has no SQL-shaped surface, so it
+ * does not fit the `Dialect` interface used by the SQL dialects in this repo.
+ * Instead it implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and maps a common KV surface onto UnQLite's calls.
+ *
+ * Built on the `unqlite` npm driver (callback-based), 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 and never
+ * reach the `require`.
+ */
+const errors_1 = require("../../errors");
+/**
+ * `UnqliteStore` wraps an `unqlite` client and exposes its embedded KV
+ * surface: `put`/`get`/`del` (mapped to `store`/`fetch`/`delete`), `batch` for
+ * multi-key writes, and `list` for key iteration.
+ */
+class UnqliteStore {
+    constructor(options = {}) {
+        this.name = 'unqlite';
+        this.library = 'unqlite';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+        this.path = options.path ?? './data/unqlite.db';
+    }
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        try {
+            if (this.options.client) {
+                this.client = this.options.client;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const UnQLite = require('unqlite');
+                this.client = new UnQLite(this.path);
+            }
+            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 open UnQLite: ${parent.message}`, {
+                parent,
+                database: 'unqlite',
+            });
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            const client = this.client;
+            if (typeof client.close === 'function') {
+                try {
+                    await this.promisify((cb) => client.close(cb));
+                }
+                catch {
+                    // best-effort close
+                }
+            }
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `unqlite` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('UnQLite client is not connected. Call connect() first.', {
+                database: 'unqlite',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `UnQLite ${action} failed: ${parent.message}` });
+    }
+    /** Wrap a callback-style UnQLite call into a Promise. */
+    promisify(fn) {
+        return new Promise((resolve, reject) => {
+            fn((err, result) => (err ? reject(err) : resolve(result)));
+        });
+    }
+    /** Writes (or overwrites) the value at `key` (UnQLite `store`). */
+    async put(key, value) {
+        const client = this.requireClient();
+        try {
+            await this.promisify((cb) => client.store(key, value, cb));
+        }
+        catch (err) {
+            throw this.wrapError('put', err);
+        }
+    }
+    /** Reads the value at `key` (UnQLite `fetch`). */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            return await this.promisify((cb) => client.fetch(key, cb));
+        }
+        catch (err) {
+            throw this.wrapError('get', err);
+        }
+    }
+    /** Deletes the value at `key` (UnQLite `delete`). */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            await this.promisify((cb) => client.delete(key, cb));
+        }
+        catch (err) {
+            throw this.wrapError('del', err);
+        }
+    }
+    /** Applies a list of `put`/`del` operations sequentially. */
+    async batch(ops) {
+        for (const op of ops) {
+            if (op.type === 'put') {
+                await this.put(op.key, op.value);
+            }
+            else {
+                await this.del(op.key);
+            }
+        }
+    }
+    /** Lists all keys by iterating records with UnQLite's `each` cursor. */
+    async list() {
+        const client = this.requireClient();
+        try {
+            const keys = [];
+            await this.promisify((cb) => client.each((key) => {
+                keys.push(String(key));
+            }, cb));
+            return keys;
+        }
+        catch (err) {
+            throw this.wrapError('list', err);
+        }
+    }
+}
+exports.UnqliteStore = UnqliteStore;
+exports.default = UnqliteStore;

package/dist/nosql/upstash/index.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Upstash Redis store implementation.
+ *
+ * Upstash Redis is a serverless, globally-replicated Redis served over an
+ * HTTP/REST connection via the `@upstash/redis` client. It has no SQL query
+ * surface, so this class implements the minimal `NoSqlStore` marker
+ * interface and exposes an edge-KV `get`/`set`/`del`/`list`/`incr` surface
+ * mapped onto the `@upstash/redis` client.
+ *
+ * ## Driver
+ *
+ * Uses `@upstash/redis` (`new Redis({ url, token })`). The driver is loaded
+ * lazily inside `connect()` (or supplied pre-built via the `client` option)
+ * so importing this module never requires `@upstash/redis` to be installed
+ * unless a store is actually connected. Tests inject a mock `client`.
+ *
+ * ## Serialization
+ *
+ * String values are passed through verbatim; every other value is
+ * `JSON.stringify`'d before being written.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpstashStore = void 0;
+const errors_1 = require("../../errors");
+function serialize(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/**
+ * `UpstashStore` wraps an `@upstash/redis` client behind the `NoSqlStore`
+ * lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr` surface.
+ */
+class UpstashStore {
+    constructor(options = {}) {
+        this.name = 'upstash';
+        this.library = '@upstash/redis';
+        this.client = 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;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const mod = require('@upstash/redis');
+                const Redis = mod.Redis ?? mod.default ?? mod;
+                this.client = new Redis({
+                    url: this.options.url,
+                    token: this.options.token,
+                });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.url);
+        }
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `@upstash/redis` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Upstash Redis', {
+                database: 'upstash',
+                host: this.options.url,
+            });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Key-value operations
+    // ---------------------------------------------------------------------
+    /** Read a key. Returns whatever the client returns (`null` if missing). */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            return await client.get(key);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'GET');
+        }
+    }
+    /**
+     * Write `value` under `key`. Strings are stored verbatim; other values are
+     * JSON-serialized. `options.ttl` maps to Redis `EX` (seconds),
+     * `options.expiration` to `EXAT` (absolute Unix seconds).
+     */
+    async set(key, value, options = {}) {
+        const client = this.requireClient();
+        const setOptions = {};
+        if (options.ttl !== undefined)
+            setOptions.ex = options.ttl;
+        if (options.expiration !== undefined)
+            setOptions.exat = options.expiration;
+        try {
+            return await client.set(key, serialize(value), Object.keys(setOptions).length > 0 ? setOptions : undefined);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'SET');
+        }
+    }
+    /** Delete a key. Returns the number of keys removed. */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            return await client.del(key);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'DEL');
+        }
+    }
+    /** List key names, optionally filtered by `prefix` (matched as `<prefix>*`). */
+    async list(prefix) {
+        const client = this.requireClient();
+        try {
+            return await client.keys(prefix ? `${prefix}*` : '*');
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'LIST');
+        }
+    }
+    /** Atomically increment the numeric value at `key` by `by` (default `1`). */
+    async incr(key, by = 1) {
+        const client = this.requireClient();
+        try {
+            return by === 1 ? await client.incr(key) : await client.incrby(key, by);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'INCR');
+        }
+    }
+}
+exports.UpstashStore = UpstashStore;
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return new errors_1.ConnectionError(`Unable to connect to Upstash Redis: ${parent.message}`, {
+        parent,
+        database: 'upstash',
+        host,
+    });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, {
+        message: `Upstash Redis ${action} failed: ${parent.message}`,
+    });
+}
+exports.default = UpstashStore;

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

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Vercel KV store implementation.
+ *
+ * Vercel KV is a serverless, globally-replicated Redis-compatible key-value
+ * store fronted by the `@vercel/kv` client (a durable-HTTP Redis client). It
+ * has no SQL query surface, so this class implements the minimal
+ * `NoSqlStore` marker interface and exposes an edge-KV
+ * `get`/`set`/`del`/`list`/`incr` surface mapped onto the `@vercel/kv`
+ * client.
+ *
+ * ## Driver
+ *
+ * Uses `@vercel/kv` (`createClient({ url, token })`). The driver is loaded
+ * lazily inside `connect()` (or supplied pre-built via the `client` option)
+ * so importing this module never requires `@vercel/kv` to be installed
+ * unless a store is actually connected. Tests inject a mock `client`.
+ *
+ * ## Serialization
+ *
+ * String values are passed through verbatim; every other value is
+ * `JSON.stringify`'d before being written, so reads via `get()` return the
+ * serialized string.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VercelKvStore = void 0;
+const errors_1 = require("../../errors");
+function serialize(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
+}
+/**
+ * `VercelKvStore` wraps a `@vercel/kv` client behind the `NoSqlStore`
+ * lifecycle and an edge-KV `get`/`set`/`del`/`list`/`incr` surface.
+ */
+class VercelKvStore {
+    constructor(options = {}) {
+        this.name = 'vercel-kv';
+        this.library = '@vercel/kv';
+        this.client = 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;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const kv = require('@vercel/kv');
+                this.client = kv.createClient({
+                    url: this.options.url,
+                    token: this.options.token,
+                });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.url);
+        }
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `@vercel/kv` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Vercel KV', {
+                database: 'vercel-kv',
+                host: this.options.url,
+            });
+        }
+        return this.client;
+    }
+    // ---------------------------------------------------------------------
+    // Key-value operations
+    // ---------------------------------------------------------------------
+    /** Read a key. Returns whatever the client returns (`null` if missing). */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            return await client.get(key);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'GET');
+        }
+    }
+    /**
+     * Write `value` under `key`. Strings are stored verbatim; other values are
+     * JSON-serialized. `options.ttl` maps to Redis `EX` (seconds),
+     * `options.expiration` to `EXAT` (absolute Unix seconds).
+     */
+    async set(key, value, options = {}) {
+        const client = this.requireClient();
+        const setOptions = {};
+        if (options.ttl !== undefined)
+            setOptions.ex = options.ttl;
+        if (options.expiration !== undefined)
+            setOptions.exat = options.expiration;
+        try {
+            return await client.set(key, serialize(value), Object.keys(setOptions).length > 0 ? setOptions : undefined);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'SET');
+        }
+    }
+    /** Delete a key. Returns the number of keys removed. */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            return await client.del(key);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'DEL');
+        }
+    }
+    /** List key names, optionally filtered by `prefix` (matched as `<prefix>*`). */
+    async list(prefix) {
+        const client = this.requireClient();
+        try {
+            return await client.keys(prefix ? `${prefix}*` : '*');
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'LIST');
+        }
+    }
+    /** Atomically increment the numeric value at `key` by `by` (default `1`). */
+    async incr(key, by = 1) {
+        const client = this.requireClient();
+        try {
+            return by === 1 ? await client.incr(key) : await client.incrby(key, by);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, 'INCR');
+        }
+    }
+}
+exports.VercelKvStore = VercelKvStore;
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return new errors_1.ConnectionError(`Unable to connect to Vercel KV: ${parent.message}`, {
+        parent,
+        database: 'vercel-kv',
+        host,
+    });
+}
+function wrapDatabaseError(err, action) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    return errors_1.DatabaseError.from(parent, { message: `Vercel KV ${action} failed: ${parent.message}` });
+}
+exports.default = VercelKvStore;

package/dist/nosql/victoriametrics/index.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * VictoriaMetrics store implementation.
+ *
+ * VictoriaMetrics is a fast, cost-effective time-series database. Crucially
+ * it is **API-compatible with Prometheus**: it exposes the same
+ * `/api/v1/query` and `/api/v1/query_range` PromQL endpoints (plus MetricsQL
+ * extensions), so PromQL queries written against Prometheus work unchanged
+ * here. Unlike Prometheus, VictoriaMetrics also accepts client-side writes -
+ * it can ingest data pushed to it in several line formats, including the
+ * Prometheus text exposition format via `/api/v1/import/prometheus`.
+ *
+ * Because there is no SQL-shaped query surface, no row-level UPDATE/DELETE,
+ * and no identifier escaping, this engine does not fit the SQL `Dialect`
+ * interface (`src/dialects/dialect.ts`). This class implements the minimal
+ * `NoSqlStore` marker interface (`src/nosql/store.ts`) and exposes the
+ * Prometheus-compatible read API plus VictoriaMetrics's write API.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * VictoriaMetrics has no single canonical npm client; it is an HTTP/JSON
+ * (and text-ingest) API. This store talks to it with the global `fetch`.
+ * For tests (and custom transports) an alternative HTTP client can be
+ * injected via `VictoriaMetricsStoreOptions.client`; when omitted, a tiny
+ * internal client over `fetch` + `baseURL` is built at connect time.
+ *
+ * ## Endpoints wrapped
+ *
+ * Read (Prometheus-compatible, under `/api/v1`):
+ * - `instantQuery(promql, time?)`          -> `GET /api/v1/query`
+ * - `rangeQuery(promql, {start,end,step})` -> `GET /api/v1/query_range`
+ *
+ * Write (VictoriaMetrics-specific):
+ * - `importPrometheus(lines)`              -> `POST /api/v1/import/prometheus`
+ * - `write(metric, value, timestamp?, labels?)` builds one Prometheus
+ *   exposition line and POSTs it via `importPrometheus`.
+ *
+ * Read methods return the parsed `data` field of the response envelope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VictoriaMetricsStore = exports.DEFAULT_VICTORIAMETRICS_BASE_URL = void 0;
+exports.createFetchClient = createFetchClient;
+exports.buildPrometheusLine = buildPrometheusLine;
+const errors_1 = require("../../errors");
+/** Default VictoriaMetrics HTTP API base URL (single-node). */
+exports.DEFAULT_VICTORIAMETRICS_BASE_URL = 'http://localhost:8428';
+/** Build a `fetch`-backed client for the given base URL. */
+function createFetchClient(baseURL, headers) {
+    const buildUrl = (path, params) => {
+        const url = new URL(path, baseURL.endsWith('/') ? baseURL : `${baseURL}/`);
+        for (const [key, value] of Object.entries(params ?? {})) {
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    url.searchParams.append(key, item);
+            }
+            else {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url.toString();
+    };
+    return {
+        async get(path, params) {
+            const res = await fetch(buildUrl(path, params), { method: 'GET', headers });
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            }
+            return res.json();
+        },
+        async post(path, body, contentType) {
+            const res = await fetch(buildUrl(path), {
+                method: 'POST',
+                body,
+                headers: { ...(headers ?? {}), ...(contentType ? { 'Content-Type': contentType } : {}) },
+            });
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            }
+            const text = await res.text();
+            return text || undefined;
+        },
+    };
+}
+/**
+ * Build a single Prometheus text-exposition line:
+ *
+ *   metric{label="value",...} value [timestamp_ms]
+ *
+ * Label values are escaped per the exposition format (`\`, `"`, newline).
+ */
+function buildPrometheusLine(metric, value, timestamp, labels) {
+    const entries = Object.entries(labels ?? {});
+    const labelPart = entries.length
+        ? `{${entries
+            .map(([k, v]) => `${k}="${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`)
+            .join(',')}}`
+        : '';
+    const tsPart = timestamp === undefined ? '' : ` ${timestamp}`;
+    return `${metric}${labelPart} ${value}${tsPart}`;
+}
+/**
+ * `VictoriaMetricsStore` wraps VictoriaMetrics's Prometheus-compatible
+ * PromQL read API (instant/range queries) and its Prometheus-exposition
+ * write/import API behind the `NoSqlStore` lifecycle.
+ */
+class VictoriaMetricsStore {
+    constructor(options = {}) {
+        this.name = 'victoriametrics';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.baseURL = options.baseURL ?? exports.DEFAULT_VICTORIAMETRICS_BASE_URL;
+        this.injectedClient = options.client;
+        this.headers = options.headers;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        this.client = this.injectedClient ?? createFetchClient(this.baseURL, this.headers);
+        this.connected = true;
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying (internal or injected) HTTP client. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to VictoriaMetrics', {
+                database: 'victoriametrics',
+                host: this.baseURL,
+            });
+        }
+        return this.client;
+    }
+    async doGet(path, params, action) {
+        const client = this.requireClient();
+        try {
+            const body = await client.get(path, params);
+            return body?.data;
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, {
+                message: `VictoriaMetrics ${action ?? 'request'} failed: ${parent.message}`,
+            });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // PromQL query API (Prometheus-compatible, read-only)
+    // ---------------------------------------------------------------------
+    /**
+     * Runs a PromQL/MetricsQL instant query via `GET /api/v1/query`
+     * (identical to the Prometheus endpoint). Returns the `data` payload.
+     */
+    async instantQuery(promql, time) {
+        return this.doGet('/api/v1/query', { query: promql, time: time === undefined ? undefined : String(time) }, 'instantQuery');
+    }
+    /**
+     * Runs a PromQL/MetricsQL range query via `GET /api/v1/query_range`
+     * (identical to the Prometheus endpoint). Returns the `data` payload.
+     */
+    async rangeQuery(promql, options) {
+        return this.doGet('/api/v1/query_range', {
+            query: promql,
+            start: String(options.start),
+            end: String(options.end),
+            step: String(options.step),
+        }, 'rangeQuery');
+    }
+    // ---------------------------------------------------------------------
+    // Write API (VictoriaMetrics-specific)
+    // ---------------------------------------------------------------------
+    /**
+     * Imports raw data in Prometheus text-exposition format via
+     * `POST /api/v1/import/prometheus`. Accepts a single newline-delimited
+     * string or an array of lines (joined with newlines).
+     */
+    async importPrometheus(lines) {
+        const client = this.requireClient();
+        const body = Array.isArray(lines) ? lines.join('\n') : lines;
+        try {
+            return await client.post('/api/v1/import/prometheus', body, 'text/plain');
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, {
+                message: `VictoriaMetrics importPrometheus failed: ${parent.message}`,
+            });
+        }
+    }
+    /**
+     * Writes a single sample by building one Prometheus-exposition line
+     * (`metric{labels} value [timestamp_ms]`) and importing it via
+     * `importPrometheus`.
+     */
+    async write(metric, value, timestamp, labels) {
+        return this.importPrometheus(buildPrometheusLine(metric, value, timestamp, labels));
+    }
+}
+exports.VictoriaMetricsStore = VictoriaMetricsStore;