ts-prorm-orm 1.1.0

package/dist/nosql/sumologic/index.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Sumo Logic store implementation.
+ *
+ * Sumo Logic is a cloud log-management and analytics platform. Logs are
+ * ingested by POSTing to an HTTP Source collector URL, and searched with the
+ * Search Job API (create a job, then poll for status/messages). There is no
+ * SQL-shaped query surface, no row-level UPDATE/DELETE, and no identifier
+ * escaping, so Sumo Logic 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 Sumo's
+ * ingest/search API.
+ *
+ * ## No canonical driver - HTTP over `fetch`
+ *
+ * Sumo Logic has no single canonical npm client; it is an HTTP/JSON API.
+ * This store talks to it with the global `fetch` (so `library` is
+ * `'fetch'`). For tests (and custom transports) an alternative HTTP client
+ * can be injected via `SumoLogicStoreOptions.client`.
+ *
+ * Ingest and search live on different hosts: ingest targets the per-source
+ * `collectorURL`, while search targets the regional `apiURL`. The internal
+ * client resolves absolute URLs verbatim, so `push()` posts to the full
+ * collector URL while the search/metadata methods use relative API paths.
+ *
+ * ## Endpoints wrapped
+ *
+ * - `push(lines)`     -> `POST <collectorURL>`             (HTTP Source ingest)
+ * - `query(q, opts?)` -> `POST /api/v1/search/jobs`         (create search job)
+ * - `messages(id)`    -> `GET  /api/v1/search/jobs/<id>/messages`
+ * - `labels()`        -> `GET  /api/v1/fields`              (field names)
+ * - `streams()`       -> `GET  /api/v1/collectors`          (collectors)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SumoLogicStore = exports.DEFAULT_SUMOLOGIC_API_URL = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+/** Default Sumo Logic API base URL. */
+exports.DEFAULT_SUMOLOGIC_API_URL = 'https://api.sumologic.com';
+/** Build a `fetch`-backed client for the given base URL. */
+function createFetchClient(baseURL, headers) {
+    const buildUrl = (path, params) => {
+        // Absolute URLs (the collector URL) override the base entirely.
+        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: { Accept: 'application/json', ...(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();
+            if (!text)
+                return undefined;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        },
+    };
+}
+/**
+ * `SumoLogicStore` wraps Sumo Logic's HTTP Source ingest and its Search Job
+ * API (create job + fetch messages) plus field/collector metadata behind the
+ * `NoSqlStore` lifecycle.
+ */
+class SumoLogicStore {
+    constructor(options = {}) {
+        this.name = 'sumologic';
+        this.library = 'fetch';
+        this.client = null;
+        this.connected = false;
+        this.apiURL = options.apiURL ?? exports.DEFAULT_SUMOLOGIC_API_URL;
+        this.collectorURL = options.collectorURL;
+        this.injectedClient = options.client;
+        this.headers = options.headers;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client)
+            return;
+        this.client = this.injectedClient ?? createFetchClient(this.apiURL, 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 Sumo Logic', {
+                database: 'sumologic',
+                host: this.apiURL,
+            });
+        }
+        return this.client;
+    }
+    async doGet(path, params, action) {
+        const client = this.requireClient();
+        try {
+            return await client.get(path, params);
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, {
+                message: `Sumo Logic ${action ?? 'request'} failed: ${parent.message}`,
+            });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Ingest (HTTP Source)
+    // ---------------------------------------------------------------------
+    /**
+     * Ingests raw log lines by POSTing them (newline-delimited) to the
+     * configured HTTP Source `collectorURL`. Accepts a single string or an
+     * array of lines (joined with newlines).
+     */
+    async push(lines) {
+        if (!this.collectorURL) {
+            throw new errors_1.DatabaseError('Sumo Logic push requires a collectorURL to be configured');
+        }
+        const client = this.requireClient();
+        const body = Array.isArray(lines) ? lines.join('\n') : lines;
+        try {
+            return await client.post(this.collectorURL, body, 'text/plain');
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Sumo Logic push failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Search Job API
+    // ---------------------------------------------------------------------
+    /**
+     * Creates a search job via `POST /api/v1/search/jobs`. Returns the parsed
+     * response (typically `{ id }`); use `messages(id)` to fetch results once
+     * the job completes.
+     */
+    async query(q, options = {}) {
+        const client = this.requireClient();
+        const payload = {
+            query: q,
+            from: options.from === undefined ? undefined : String(options.from),
+            to: options.to === undefined ? undefined : String(options.to),
+            timeZone: options.timeZone ?? 'UTC',
+            byReceiptTime: options.byReceiptTime,
+        };
+        try {
+            return await client.post('/api/v1/search/jobs', JSON.stringify(payload), 'application/json');
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Sumo Logic query failed: ${parent.message}` });
+        }
+    }
+    /** Fetches messages for a completed search job via `GET /api/v1/search/jobs/<id>/messages`. */
+    async messages(jobId, offset = 0, limit = 100) {
+        return this.doGet(`/api/v1/search/jobs/${encodeURIComponent(jobId)}/messages`, { offset: String(offset), limit: String(limit) }, 'messages');
+    }
+    /** Fetches the status of a search job via `GET /api/v1/search/jobs/<id>`. */
+    async jobStatus(jobId) {
+        return this.doGet(`/api/v1/search/jobs/${encodeURIComponent(jobId)}`, undefined, 'jobStatus');
+    }
+    // ---------------------------------------------------------------------
+    // Metadata
+    // ---------------------------------------------------------------------
+    /** Lists the configured fields via `GET /api/v1/fields`. */
+    async labels() {
+        return this.doGet('/api/v1/fields', undefined, 'labels');
+    }
+    /** Lists the collectors via `GET /api/v1/collectors`. */
+    async streams() {
+        return this.doGet('/api/v1/collectors', undefined, 'streams');
+    }
+}
+exports.SumoLogicStore = SumoLogicStore;
+exports.default = SumoLogicStore;

package/dist/nosql/surrealdb/index.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * SurrealDB store implementation for the Prorm NoSQL layer.
+ *
+ * SurrealDB is a multi-model database with its own record/graph model and
+ * the SurrealQL query language, so it does not fit the SQL-shaped `Dialect`
+ * interface (no identifier escaping, no SQL DDL). This class implements the
+ * minimal `NoSqlStore` marker interface for connection lifecycle and
+ * otherwise exposes SurrealDB's real API surface directly: record CRUD over
+ * "things" (table or `table:id` record identifiers) plus raw SurrealQL via
+ * `query()`.
+ *
+ * Uses the `surrealdb` driver. The driver is loaded lazily inside
+ * `connect()` (via `require`) so importing this module never forces the
+ * optional `surrealdb` dependency to be installed. For testing (or to reuse
+ * an already-configured connection) a pre-built `Surreal` instance can be
+ * injected through {@link SurrealStoreOptions.client}, in which case the
+ * `require` is skipped entirely.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SurrealStore = void 0;
+const errors_1 = require("../../errors");
+/**
+ * `SurrealStore` wraps the `surrealdb` driver's `Surreal` client, exposing
+ * record CRUD (`create`/`select`/`update`/`merge`/`delete`) and raw
+ * SurrealQL (`query`) as a small promise-based API.
+ */
+class SurrealStore {
+    constructor(options) {
+        this.name = 'surrealdb';
+        this.library = 'surrealdb';
+        this.db = null;
+        this.connected = false;
+        if (!options || !options.url) {
+            throw new errors_1.DatabaseError('SurrealStore requires a connection `url`', {
+                code: 'INVALID_CONNECTION',
+            });
+        }
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.db) {
+            return;
+        }
+        try {
+            let db = this.options.client;
+            if (!db) {
+                // Lazy-load the optional driver only when we actually need to build
+                // a connection, so importing this module never requires `surrealdb`.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { Surreal } = require('surrealdb');
+                db = new Surreal();
+            }
+            await db.connect(this.options.url);
+            if (this.options.username !== undefined || this.options.password !== undefined) {
+                await db.signin({
+                    username: this.options.username,
+                    password: this.options.password,
+                });
+            }
+            if (this.options.namespace !== undefined || this.options.database !== undefined) {
+                await db.use({
+                    namespace: this.options.namespace,
+                    database: this.options.database,
+                });
+            }
+            this.db = db;
+            this.connected = true;
+        }
+        catch (error) {
+            this.db = null;
+            this.connected = false;
+            throw new errors_1.ConnectionError('Failed to connect to SurrealDB', {
+                parent: error instanceof Error ? error : undefined,
+                database: this.options.database,
+            });
+        }
+    }
+    async disconnect() {
+        const db = this.db;
+        this.db = null;
+        this.connected = false;
+        if (!db) {
+            return;
+        }
+        try {
+            await db.close();
+        }
+        catch (error) {
+            throw new errors_1.DatabaseError('Failed to disconnect from SurrealDB', {
+                parent: error instanceof Error ? error : undefined,
+                original: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    isConnected() {
+        return this.connected && this.db !== null;
+    }
+    /** Returns the underlying native `Surreal` client. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.db || !this.connected) {
+            throw new errors_1.ConnectionError('SurrealStore is not connected. Call connect() first.', {
+                code: 'INVALID_CONNECTION',
+                database: this.options.database,
+            });
+        }
+        return this.db;
+    }
+    async exec(op, fn) {
+        const db = this.requireClient();
+        try {
+            return await fn(db);
+        }
+        catch (error) {
+            throw new errors_1.DatabaseError(`SurrealDB operation "${op}" failed`, {
+                code: 'QUERY_ERROR',
+                parent: error instanceof Error ? error : undefined,
+                original: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Record operations
+    // ---------------------------------------------------------------------
+    /**
+     * Create a record. `thing` may be a table name (`'user'`, id auto-
+     * generated) or a specific record id (`'user:jane'`). Passthrough to the
+     * driver's `Surreal.create()`.
+     */
+    async create(thing, data) {
+        return this.exec('create', (db) => db.create(thing, data));
+    }
+    /**
+     * Select a record or all records in a table. Passthrough to the driver's
+     * `Surreal.select()`.
+     */
+    async select(thing) {
+        return this.exec('select', (db) => db.select(thing));
+    }
+    /**
+     * Replace the content of a record (or every record in a table).
+     * Passthrough to the driver's `Surreal.update()`.
+     */
+    async update(thing, data) {
+        return this.exec('update', (db) => db.update(thing, data));
+    }
+    /**
+     * Merge the given data into a record (or every record in a table),
+     * leaving unspecified fields intact. Passthrough to the driver's
+     * `Surreal.merge()`.
+     */
+    async merge(thing, data) {
+        return this.exec('merge', (db) => db.merge(thing, data));
+    }
+    /**
+     * Delete a record (or every record in a table). Passthrough to the
+     * driver's `Surreal.delete()`.
+     */
+    async delete(thing) {
+        return this.exec('delete', (db) => db.delete(thing));
+    }
+    /**
+     * Run a raw SurrealQL statement (or several `;`-separated statements),
+     * optionally binding `vars` as `$name` parameters. Returns the driver's
+     * result array (one entry per statement). Passthrough to the driver's
+     * `Surreal.query()`.
+     */
+    async query(surql, vars) {
+        return this.exec('query', (db) => db.query(surql, vars));
+    }
+}
+exports.SurrealStore = SurrealStore;
+exports.default = SurrealStore;

package/dist/nosql/terminusdb/index.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * TerminusDB store implementation.
+ *
+ * TerminusDB is an immutable, versioned document/graph database with a
+ * git-like data model: every write produces a new commit on a branch, and
+ * the full commit history is retained, so past states are always
+ * reconstructable and the store is effectively append-only/auditable.
+ * Documents are typed JSON objects; queries are expressed in WOQL (the Web
+ * Object Query Language).
+ *
+ * TerminusDB is not a SQL `Dialect`, so this class implements the minimal
+ * `NoSqlStore` marker interface plus the shared ledger surface:
+ *  - `append(table, data)` -> `addDocument` of `{ '@type': table, ...data }`.
+ *  - `get(table, id)`      -> `getDocument` by `<table>/<id>`.
+ *  - `history(table, id)`  -> commit-log WOQL query for the document.
+ *  - `verify(table, id)`   -> fetch the document + report existence (its
+ *    presence in the immutable commit graph is its provenance).
+ *  - `query(woql)`         -> raw WOQL passthrough.
+ *
+ * ## Lazy driver loading
+ *
+ * `@terminusdb/terminusdb-client` is loaded lazily inside `connect()`. Tests
+ * inject a pre-built, already-connected `WOQLClient` via
+ * `TerminusdbStoreOptions.client`, bypassing the `require`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TerminusdbStore = void 0;
+const errors_1 = require("../../errors");
+/**
+ * `TerminusdbStore` wraps a `WOQLClient` behind the shared ledger surface.
+ */
+class TerminusdbStore {
+    constructor(options = {}) {
+        this.name = 'terminusdb';
+        this.library = '@terminusdb/terminusdb-client';
+        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('@terminusdb/terminusdb-client');
+                const WOQLClient = mod.WOQLClient ?? mod.default?.WOQLClient ?? mod.default;
+                this.client = new WOQLClient(this.options.url ?? 'http://localhost:6363', {
+                    user: this.options.user,
+                    key: this.options.key,
+                    organization: this.options.organization,
+                });
+                if (typeof this.client.connect === 'function') {
+                    await this.client.connect();
+                }
+            }
+            if (this.options.db && typeof this.client.db === 'function') {
+                this.client.db(this.options.db);
+            }
+            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 TerminusDB: ${parent.message}`, {
+                parent,
+                database: 'terminusdb',
+            });
+        }
+    }
+    async disconnect() {
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `WOQLClient` for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client || !this.connected) {
+            throw new errors_1.ConnectionError('Not connected to TerminusDB. Call connect() first.', {
+                database: 'terminusdb',
+            });
+        }
+        return this.client;
+    }
+    fullId(table, id) {
+        return id.includes('/') ? id : `${table}/${id}`;
+    }
+    async run(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: `TerminusDB ${action} failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Ledger surface
+    // ---------------------------------------------------------------------
+    /**
+     * Insert `data` as a new document of type `table` (a new commit). Returns
+     * whatever `addDocument` reports (typically the inserted document id(s)).
+     */
+    async append(table, data) {
+        return this.run('append', (client) => client.addDocument({ '@type': table, ...data }, undefined, undefined, `append ${table}`));
+    }
+    /** Fetch the current revision of document `<table>/<id>`. */
+    async get(table, id) {
+        return this.run('get', (client) => client.getDocument({ id: this.fullId(table, id) }));
+    }
+    /**
+     * Return the commit history for document `<table>/<id>` via a WOQL query
+     * over the commit graph. Every past revision lives in the immutable commit
+     * chain, so this surfaces the document's provenance.
+     */
+    async history(table, id) {
+        const docId = this.fullId(table, id);
+        return this.run('history', (client) => client.query({ '@type': 'CommitHistory', document: docId }));
+    }
+    /**
+     * Verify document `<table>/<id>` by reading it back from the immutable
+     * store. Returns `{ id, exists, document }` - existence in the commit graph
+     * is the provenance guarantee (TerminusDB never mutates past commits).
+     */
+    async verify(table, id) {
+        const docId = this.fullId(table, id);
+        const document = await this.run('verify', (client) => client.getDocument({ id: docId }).catch(() => null));
+        return { id: docId, exists: document != null, document };
+    }
+    /** Run a raw WOQL query object. */
+    async query(woql, commitMsg) {
+        return this.run('query', (client) => client.query(woql, commitMsg));
+    }
+}
+exports.TerminusdbStore = TerminusdbStore;
+exports.default = TerminusdbStore;