ts-prorm-orm 1.1.0

package/dist/nosql/pinot/index.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * Apache Pinot store.
+ *
+ * Pinot is a real-time distributed OLAP datastore built for low-latency
+ * analytics on both streaming and batch data. Queries are issued against a
+ * *broker* over an HTTP/JSON API using Pinot SQL; results come back in a
+ * columnar `resultTable` envelope (a `dataSchema` plus positional `rows`).
+ * Pinot has no client-side row `INSERT` path (real-time ingestion is driven
+ * by Kafka/stream connectors configured server-side), so it does not fit the
+ * SQL-shaped `Dialect` interface (`src/dialects/dialect.ts`). This class
+ * implements the minimal `NoSqlStore` marker interface (`src/nosql/store.ts`)
+ * and exposes Pinot's read-only broker query API directly.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Pinot has no single canonical npm client; the broker is just an HTTP/JSON
+ * API. This store uses the global `fetch`. Tests (and callers wanting their
+ * own transport) inject an alternative client via `PinotStoreOptions.client`;
+ * when omitted a tiny `fetch`-based client is built against `endpoint` on
+ * `connect()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PinotStore = exports.DEFAULT_PINOT_ENDPOINT = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+/** Default Pinot broker HTTP endpoint. */
+exports.DEFAULT_PINOT_ENDPOINT = 'http://localhost:8000';
+/** Build a `fetch`-backed client for the given endpoint. */
+function createFetchClient(endpoint, headers) {
+    const base = endpoint.endsWith('/') ? endpoint.slice(0, -1) : endpoint;
+    return {
+        async post(path, body) {
+            const res = await fetch(`${base}${path}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...(headers ?? {}) },
+                body: JSON.stringify(body),
+            });
+            if (!res.ok) {
+                throw new Error(`HTTP ${res.status} ${res.statusText}`);
+            }
+            const text = await res.text();
+            return text ? JSON.parse(text) : undefined;
+        },
+    };
+}
+/**
+ * `PinotStore` wraps Pinot's broker query API (`POST /query/sql`) behind the
+ * `NoSqlStore` lifecycle. `query()` maps the columnar `resultTable` into an
+ * array of row objects; `queryTable()` returns the raw `resultTable` envelope
+ * for callers who need the schema or the positional rows.
+ */
+class PinotStore {
+    constructor(options = {}) {
+        this.name = 'pinot';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.endpoint = options.endpoint ?? exports.DEFAULT_PINOT_ENDPOINT;
+        this.injectedClient = options.client;
+        this.headers = options.headers;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        this.client = this.injectedClient ?? createFetchClient(this.endpoint, 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 || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to Pinot. Call connect() first.', {
+                database: 'pinot',
+                host: this.endpoint,
+            });
+        }
+        return this.client;
+    }
+    async runSql(sql) {
+        const client = this.requireClient();
+        try {
+            return await client.post('/query/sql', { sql });
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Pinot query failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Query API (read-only)
+    // ---------------------------------------------------------------------
+    /**
+     * Run a Pinot SQL query via `POST /query/sql` and return the rows as an
+     * array of objects keyed by the result column names. For the raw columnar
+     * envelope (schema + positional rows), use `queryTable()`.
+     */
+    async query(sql) {
+        const table = await this.queryTable(sql);
+        const columns = table.dataSchema?.columnNames ?? [];
+        const rows = table.rows ?? [];
+        return rows.map((row) => {
+            const obj = {};
+            columns.forEach((col, i) => {
+                obj[col] = row[i];
+            });
+            return obj;
+        });
+    }
+    /**
+     * Run a Pinot SQL query and return the raw `resultTable` envelope
+     * (`dataSchema` + positional `rows`), exactly as the broker returns it.
+     */
+    async queryTable(sql) {
+        const body = await this.runSql(sql);
+        return (body?.resultTable ?? { rows: [] });
+    }
+}
+exports.PinotStore = PinotStore;
+exports.default = PinotStore;

package/dist/nosql/pouchdb/index.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PouchdbStore = void 0;
+/**
+ * PouchDB store.
+ *
+ * PouchDB is an embedded, in-process document database (it can run purely in
+ * Node against a filesystem-backed adapter, with no server). Documents are
+ * addressed by an `_id` and versioned by a `_rev`, and the API is
+ * promise-based: `put`/`get`/`remove`/`allDocs`/`bulkDocs`. 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
+ * (`put`/`get`/`del` on `_id`) onto PouchDB's document API.
+ *
+ * Built on the `pouchdb` npm driver, 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");
+/**
+ * `PouchdbStore` wraps a `pouchdb` database and exposes both a common KV
+ * surface — `put`/`get`/`del` keyed on `_id`, `batch`, `list` — and PouchDB's
+ * native `insert`/`allDocs` operations.
+ */
+class PouchdbStore {
+    constructor(options = {}) {
+        this.name = 'pouchdb';
+        this.library = 'pouchdb';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+        this.dbName = options.name ?? './data/pouchdb';
+    }
+    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 PouchDB = require('pouchdb');
+                this.client = new PouchDB(this.dbName, this.options.config);
+            }
+            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 PouchDB: ${parent.message}`, {
+                parent,
+                database: 'pouchdb',
+            });
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.close();
+            }
+            catch {
+                // best-effort close
+            }
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `pouchdb` database for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('PouchDB database is not connected. Call connect() first.', {
+                database: 'pouchdb',
+            });
+        }
+        return this.client;
+    }
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : new Error(String(err));
+        return errors_1.DatabaseError.from(parent, { message: `PouchDB ${action} failed: ${parent.message}` });
+    }
+    /** Writes a document keyed by `_id = key` (PouchDB `put`), merging `key` in as its `_id`. */
+    async put(key, value) {
+        const client = this.requireClient();
+        try {
+            return await client.put({ _id: key, ...value });
+        }
+        catch (err) {
+            throw this.wrapError('put', err);
+        }
+    }
+    /** Native `insert`: stores a document as-is (must carry its own `_id`). */
+    async insert(doc) {
+        const client = this.requireClient();
+        try {
+            return await client.put(doc);
+        }
+        catch (err) {
+            throw this.wrapError('insert', err);
+        }
+    }
+    /** Reads a document by `_id` (PouchDB `get`). */
+    async get(key) {
+        const client = this.requireClient();
+        try {
+            return await client.get(key);
+        }
+        catch (err) {
+            throw this.wrapError('get', err);
+        }
+    }
+    /**
+     * Deletes a document by `_id`. PouchDB needs the current `_rev` to delete, so
+     * this first `get`s the document, then `remove`s it.
+     */
+    async del(key) {
+        const client = this.requireClient();
+        try {
+            const doc = await client.get(key);
+            return await client.remove(doc);
+        }
+        catch (err) {
+            throw this.wrapError('del', err);
+        }
+    }
+    /** Applies a list of `put`/`del` operations. Puts go through `bulkDocs`; deletes are resolved individually. */
+    async batch(ops) {
+        const client = this.requireClient();
+        try {
+            const puts = ops
+                .filter((op) => op.type === 'put')
+                .map((op) => ({ _id: op.key, ...op.value }));
+            if (puts.length > 0) {
+                await client.bulkDocs(puts);
+            }
+            for (const op of ops) {
+                if (op.type === 'del') {
+                    await this.del(op.key);
+                }
+            }
+        }
+        catch (err) {
+            throw this.wrapError('batch', err);
+        }
+    }
+    /**
+     * Lists document ids via `allDocs`. With `prefix`, restricts to ids
+     * `>= prefix` and `<= prefix + '￿'` (PouchDB's startkey/endkey range).
+     */
+    async list(prefix) {
+        const client = this.requireClient();
+        try {
+            const options = prefix !== undefined ? { startkey: prefix, endkey: `${prefix}￿` } : {};
+            const result = await client.allDocs(options);
+            return result.rows.map((row) => row.id);
+        }
+        catch (err) {
+            throw this.wrapError('list', err);
+        }
+    }
+}
+exports.PouchdbStore = PouchdbStore;
+exports.default = PouchdbStore;

package/dist/nosql/prometheus/index.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * Prometheus store implementation.
+ *
+ * Prometheus is a pull-based time-series monitoring system. It is queried
+ * over its HTTP API using PromQL (Prometheus Query Language). There is no
+ * SQL-shaped query surface, no row-level UPDATE/DELETE, and no client-side
+ * ingestion path (Prometheus scrapes targets itself), so it 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 Prometheus's read-only HTTP query API directly.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Prometheus has no single canonical npm client library; it is just an
+ * HTTP/JSON API. Rather than depend on any package, this store talks to
+ * the server with the global `fetch`. For tests (and for callers who want
+ * to route requests through their own transport), an alternative HTTP
+ * client can be injected via `PrometheusStoreOptions.client`; when omitted,
+ * a tiny internal client over `fetch` + `baseURL` is built at connect time.
+ *
+ * ## Endpoints wrapped (all read-only, all under `/api/v1`)
+ *
+ * - `instantQuery(promql, time?)`      -> `GET /api/v1/query`
+ * - `rangeQuery(promql, {start,end,step})` -> `GET /api/v1/query_range`
+ * - `series(match)`                    -> `GET /api/v1/series`
+ * - `labelValues(label)`               -> `GET /api/v1/label/<label>/values`
+ *
+ * Each method returns the parsed `data` field of the Prometheus response
+ * envelope (`{ status: 'success', data: ... }`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrometheusStore = exports.DEFAULT_PROMETHEUS_BASE_URL = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+/** Default Prometheus HTTP API base URL. */
+exports.DEFAULT_PROMETHEUS_BASE_URL = 'http://localhost:9090';
+/** 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;
+        },
+    };
+}
+/**
+ * `PrometheusStore` wraps Prometheus's read-only HTTP query API (PromQL
+ * instant/range queries plus series/label metadata lookups) behind the
+ * `NoSqlStore` lifecycle. It performs no writes - Prometheus ingests data
+ * by scraping targets, not by client-side pushes.
+ */
+class PrometheusStore {
+    constructor(options = {}) {
+        this.name = 'prometheus';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.baseURL = options.baseURL ?? exports.DEFAULT_PROMETHEUS_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 Prometheus', {
+                database: 'prometheus',
+                host: this.baseURL,
+            });
+        }
+        return this.client;
+    }
+    async get(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: `Prometheus ${action ?? 'request'} failed: ${parent.message}`,
+            });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // PromQL query API (read-only)
+    // ---------------------------------------------------------------------
+    /**
+     * Runs a PromQL instant query at a single point in time via
+     * `GET /api/v1/query`. Returns the `data` payload (result type + result).
+     */
+    async instantQuery(promql, time) {
+        return this.get('/api/v1/query', { query: promql, time: time === undefined ? undefined : String(time) }, 'instantQuery');
+    }
+    /**
+     * Runs a PromQL range query over `[start, end]` at `step` resolution via
+     * `GET /api/v1/query_range`. Returns the `data` payload (matrix result).
+     */
+    async rangeQuery(promql, options) {
+        return this.get('/api/v1/query_range', {
+            query: promql,
+            start: String(options.start),
+            end: String(options.end),
+            step: String(options.step),
+        }, 'rangeQuery');
+    }
+    /**
+     * Finds series matching one or more PromQL series selectors via
+     * `GET /api/v1/series`. Returns the array of matching label sets.
+     */
+    async series(match) {
+        const matches = Array.isArray(match) ? match : [match];
+        return this.get('/api/v1/series', { 'match[]': matches }, 'series');
+    }
+    /**
+     * Lists the distinct values of a label via
+     * `GET /api/v1/label/<label>/values`. Returns the array of values.
+     */
+    async labelValues(label) {
+        return this.get(`/api/v1/label/${encodeURIComponent(label)}/values`, undefined, 'labelValues');
+    }
+}
+exports.PrometheusStore = PrometheusStore;

package/dist/nosql/provendb/index.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * ProvenDB store implementation.
+ *
+ * ProvenDB is a MongoDB-compatible database that adds immutable, versioned
+ * documents plus cryptographic proofs: every write is captured at a
+ * monotonically increasing **version**, and ProvenDB can produce a Merkle
+ * proof that a document (or a whole query result) existed at a given version,
+ * anchored into a public blockchain. That makes it append-only/auditable on
+ * top of a familiar document API.
+ *
+ * ## HTTP proof API over `fetch`
+ *
+ * While ProvenDB exposes a Mongo wire protocol, its distinguishing feature -
+ * versioned documents and proofs - is surfaced here over its REST/HTTP proof
+ * API using the global `fetch` (so `library === 'fetch'`), matching the
+ * Prometheus store's injectable-client pattern. This class implements the
+ * minimal `NoSqlStore` marker interface plus the shared ledger surface:
+ *  - `append(collection, data)` -> `POST /collections/<c>/documents`.
+ *  - `get(collection, id)`      -> `GET /collections/<c>/documents/<id>`.
+ *  - `history(collection, id)`  -> `GET .../documents/<id>/versions`.
+ *  - `verify(collection, id)`   -> `POST .../documents/<id>/proof` (returns
+ *    the Merkle proof + blockchain anchor).
+ *  - `query(filter)`            -> `POST /collections/<c>/query`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProvendbStore = exports.DEFAULT_PROVENDB_BASE_URL = void 0;
+exports.createProvendbFetchClient = createProvendbFetchClient;
+const errors_1 = require("../../errors");
+/** Default ProvenDB HTTP API base URL. */
+exports.DEFAULT_PROVENDB_BASE_URL = 'http://localhost:8080';
+/** Build a `fetch`-backed JSON client for the given base URL. */
+function createProvendbFetchClient(baseURL, headers) {
+    const root = baseURL.endsWith('/') ? baseURL.slice(0, -1) : baseURL;
+    const json = async (res) => {
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status} ${res.statusText}`);
+        }
+        return res.json();
+    };
+    return {
+        async get(path) {
+            return json(await fetch(`${root}${path}`, { method: 'GET', headers }));
+        },
+        async post(path, body) {
+            return json(await fetch(`${root}${path}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...(headers ?? {}) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            }));
+        },
+    };
+}
+/**
+ * `ProvendbStore` wraps ProvenDB's HTTP proof/document API behind the shared
+ * ledger surface.
+ */
+class ProvendbStore {
+    constructor(options = {}) {
+        this.name = 'provendb';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.baseURL = options.baseURL ?? exports.DEFAULT_PROVENDB_BASE_URL;
+        this.injectedClient = options.client;
+        this.headers = options.headers;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        this.client = this.injectedClient ?? createProvendbFetchClient(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 ProvenDB', {
+                database: 'provendb',
+                host: this.baseURL,
+            });
+        }
+        return this.client;
+    }
+    async call(action, fn) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `ProvenDB ${action} failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Ledger surface
+    // ---------------------------------------------------------------------
+    /**
+     * Insert `data` into `collection` at a new version
+     * (`POST /collections/<c>/documents`). Returns the inserted document
+     * (including its `_id` and `_version`).
+     */
+    async append(collection, data) {
+        return this.call('append', (client) => client.post(`/collections/${encodeURIComponent(collection)}/documents`, data));
+    }
+    /** Read the current version of document `id` from `collection`. */
+    async get(collection, id) {
+        return this.call('get', (client) => client.get(`/collections/${encodeURIComponent(collection)}/documents/${encodeURIComponent(id)}`));
+    }
+    /** Return every version of document `id` (`GET .../documents/<id>/versions`). */
+    async history(collection, id) {
+        return this.call('history', (client) => client.get(`/collections/${encodeURIComponent(collection)}/documents/${encodeURIComponent(id)}/versions`));
+    }
+    /**
+     * Request a cryptographic proof for document `id`
+     * (`POST .../documents/<id>/proof`). The returned object contains the
+     * Merkle proof and the public-blockchain anchor that tamper-proofs the
+     * document's state at its version.
+     */
+    async verify(collection, id) {
+        return this.call('verify', (client) => client.post(`/collections/${encodeURIComponent(collection)}/documents/${encodeURIComponent(id)}/proof`));
+    }
+    /**
+     * Run a Mongo-style filter query against `collection`
+     * (`POST /collections/<c>/query`). `query` is the Mongo filter document;
+     * `options` carries projection/sort/limit and an optional historical
+     * `version`.
+     */
+    async query(collection, query = {}, options) {
+        return this.call('query', (client) => client.post(`/collections/${encodeURIComponent(collection)}/query`, { query, options }));
+    }
+}
+exports.ProvendbStore = ProvendbStore;
+exports.default = ProvendbStore;