ts-prorm-orm 1.1.0

package/dist/nosql/solr/index.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * Apache Solr store implementation.
+ *
+ * Solr is a search engine built on Lucene: documents are schema-flexible
+ * JSON records indexed into a "core" (or "collection" in SolrCloud), and
+ * the primary operation is a Lucene/DisMax query (`q`, `fq`, `fl`, `sort`,
+ * `start`/`rows`, faceting) against that inverted index - not SQL, not
+ * joins, not a transaction log. Writes are buffered until an explicit
+ * `commit` makes them searchable. 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 Solr's real operations (add, search, delete, commit, optimize)
+ * directly.
+ *
+ * Uses the `solr-client` driver, lazy-loaded inside `connect()` via
+ * `require()` so the dependency is only needed when a Solr store is actually
+ * constructed (tests inject a pre-built mock `client` instead).
+ *
+ * ## Driver call shape (callback vs promise)
+ *
+ * The classic `solr-client` API is Node-style callbacks:
+ * `client.add(docs, (err, obj) => ...)`, `client.commit(cb)`,
+ * `client.search(query, cb)`, `client.deleteByID(id, cb)`,
+ * `client.deleteByQuery(q, cb)`, `client.optimize(cb)`. Some builds /
+ * forks instead return a Promise when no callback is passed. To work with
+ * either, every call goes through {@link invoke}, which passes a callback
+ * *and* inspects the return value: if the driver returned a thenable it is
+ * awaited directly (the callback is then ignored), otherwise the callback
+ * settles the Promise. `client.query()` (when present) builds a query
+ * object via a fluent builder; if the driver doesn't expose it, `search()`
+ * accepts a raw query object/string unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SolrStore = void 0;
+const errors_1 = require("../../errors");
+/**
+ * Bridge the driver's callback-or-promise call convention into a Promise.
+ * Passes a Node-style callback; if the method instead returns a thenable,
+ * that thenable wins and the callback is ignored.
+ */
+function invoke(fn) {
+    return new Promise((resolve, reject) => {
+        let settledByReturn = false;
+        const maybe = fn((err, result) => {
+            if (settledByReturn) {
+                return;
+            }
+            if (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+            else {
+                resolve(result);
+            }
+        });
+        if (maybe && typeof maybe.then === 'function') {
+            settledByReturn = true;
+            maybe.then(resolve, reject);
+        }
+    });
+}
+function wrapConnectionError(err, host) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused|connect failed/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Solr: ${parent.message}`;
+    return new errors_1.ConnectionError(message, { parent, database: 'solr', host });
+}
+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 });
+}
+/**
+ * `SolrStore` wraps a `solr-client` client and exposes Solr's document
+ * indexing, querying, deletion, and commit/optimize operations as a typed,
+ * promise-based API.
+ */
+class SolrStore {
+    constructor(options = {}) {
+        this.name = 'solr';
+        this.library = 'solr-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) {
+                // A client was injected (e.g. a test mock) - use it as-is and skip
+                // the driver require()/createClient() step.
+                this.client = this.options.client;
+            }
+            else {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const solr = require('solr-client');
+                this.client = solr.createClient({
+                    host: this.options.host,
+                    port: this.options.port,
+                    core: this.options.core,
+                    path: this.options.path,
+                    protocol: this.options.protocol,
+                    secure: this.options.secure,
+                });
+            }
+            this.connected = true;
+        }
+        catch (err) {
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.host);
+        }
+    }
+    async disconnect() {
+        // The solr-client is a stateless HTTP client - there is no socket to
+        // close, so "disconnecting" just drops the client reference.
+        this.client = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `solr-client` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Solr', { database: 'solr' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Solr ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Indexing
+    // ---------------------------------------------------------------------
+    /**
+     * Add (index) one or more documents, then `commit` so they become
+     * searchable. Solr buffers adds until a commit, so the two are done
+     * together here for the common "index and see it" case; call `add` via
+     * `getClient()` directly if you want to batch many adds before a single
+     * commit.
+     */
+    async add(docs) {
+        return this.exec(async (c) => {
+            const result = await invoke((cb) => c.add(docs, cb));
+            await invoke((cb) => c.commit(cb));
+            return result;
+        }, 'ADD');
+    }
+    // ---------------------------------------------------------------------
+    // Search
+    // ---------------------------------------------------------------------
+    /**
+     * Run a query. Pass either a raw query object/string (Solr query params,
+     * e.g. `'q=title:solr&rows=10'`) or a query built by
+     * {@link SolrStore.query}. Returns the driver's raw response object
+     * (`{ responseHeader, response: { numFound, docs, ... } }`).
+     */
+    async search(query) {
+        return this.exec((c) => invoke((cb) => c.search(query, cb)), 'SEARCH');
+    }
+    /**
+     * Build a query with the driver's fluent builder (`.q(...)`, `.start(...)`,
+     * `.rows(...)`, `.sort(...)`, ...), when the driver exposes `client.query()`.
+     * Throws if this driver build doesn't provide a builder - construct a raw
+     * query object/string and pass it straight to {@link SolrStore.search} in
+     * that case.
+     */
+    query() {
+        const client = this.requireClient();
+        if (typeof client.query !== 'function') {
+            throw new errors_1.DatabaseError('This solr-client build does not expose query(); pass a raw query to search()');
+        }
+        return client.query();
+    }
+    // ---------------------------------------------------------------------
+    // Delete
+    // ---------------------------------------------------------------------
+    /** Delete a single document by its unique-key value, then commit. */
+    async deleteByID(id) {
+        return this.exec(async (c) => {
+            const result = await invoke((cb) => c.deleteByID(id, cb));
+            await invoke((cb) => c.commit(cb));
+            return result;
+        }, 'DELETE BY ID');
+    }
+    /** Delete every document matching a Solr query (e.g. `'category:obsolete'`), then commit. */
+    async deleteByQuery(query) {
+        return this.exec(async (c) => {
+            const result = await invoke((cb) => c.deleteByQuery(query, cb));
+            await invoke((cb) => c.commit(cb));
+            return result;
+        }, 'DELETE BY QUERY');
+    }
+    // ---------------------------------------------------------------------
+    // Commit / optimize
+    // ---------------------------------------------------------------------
+    /** Commit buffered writes so they become visible to search. */
+    async commit() {
+        return this.exec((c) => invoke((cb) => c.commit(cb)), 'COMMIT');
+    }
+    /**
+     * Optimize the index (merge segments). Optional - not every `solr-client`
+     * build exposes `optimize`; throws a `DatabaseError` if this one doesn't.
+     */
+    async optimize() {
+        return this.exec((c) => {
+            if (typeof c.optimize !== 'function') {
+                throw new Error('This solr-client build does not expose optimize()');
+            }
+            return invoke((cb) => c.optimize({}, cb));
+        }, 'OPTIMIZE');
+    }
+}
+exports.SolrStore = SolrStore;
+exports.default = SolrStore;

package/dist/nosql/splunk/index.js

@@ -0,0 +1,227 @@
+"use strict";
+/**
+ * Splunk store implementation.
+ *
+ * Splunk is a log-ingestion and search platform. Data is ingested through
+ * the HTTP Event Collector (HEC) and searched with SPL (Search Processing
+ * Language) via the REST search API. There is no SQL-shaped query surface,
+ * no row-level UPDATE/DELETE, and no identifier escaping, so Splunk 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 Splunk's ingest/search API.
+ *
+ * ## Driver: `splunk-sdk` if present, else HTTP over `fetch`
+ *
+ * If the optional `splunk-sdk` package is installed it is lazily required at
+ * connect time and exposed via `getSdk()`; the ingest/search methods here
+ * always speak the REST/HEC HTTP API over the global `fetch` (so `library`
+ * is `'fetch'`). For tests (and custom transports) an alternative HTTP
+ * client can be injected via `SplunkStoreOptions.client`.
+ *
+ * ## Endpoints wrapped
+ *
+ * - `push(meta, events)` -> `POST /services/collector/event`  (HEC ingest)
+ * - `query(spl, opts?)`  -> `POST /services/search/jobs`       (SPL search)
+ * - `labels()`           -> `GET  /services/data/sourcetypes`  (sourcetypes)
+ * - `streams()`          -> `GET  /services/data/indexes`      (indexes)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SplunkStore = exports.DEFAULT_SPLUNK_BASE_URL = void 0;
+exports.createFetchClient = createFetchClient;
+const errors_1 = require("../../errors");
+/** Default Splunk management/REST base URL. */
+exports.DEFAULT_SPLUNK_BASE_URL = 'https://localhost:8088';
+/** 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();
+            if (!text)
+                return undefined;
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        },
+    };
+}
+/**
+ * `SplunkStore` wraps Splunk's HTTP Event Collector (ingest) and REST search
+ * API (SPL search jobs + index/sourcetype metadata) behind the `NoSqlStore`
+ * lifecycle.
+ */
+class SplunkStore {
+    constructor(options = {}) {
+        this.name = 'splunk';
+        this.library = 'fetch';
+        this.client = null;
+        this.sdk = null;
+        this.connected = false;
+        this.baseURL = options.baseURL ?? exports.DEFAULT_SPLUNK_BASE_URL;
+        this.token = options.token;
+        this.injectedClient = options.client;
+        this.headers = {
+            ...(options.headers ?? {}),
+            ...(options.token ? { Authorization: `Splunk ${options.token}` } : {}),
+        };
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client)
+            return;
+        this.client = this.injectedClient ?? createFetchClient(this.baseURL, this.headers);
+        // Lazily surface the optional official SDK if it happens to be installed.
+        if (!this.injectedClient) {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                this.sdk = require('splunk-sdk');
+            }
+            catch {
+                this.sdk = null;
+            }
+        }
+        this.connected = true;
+    }
+    async disconnect() {
+        this.client = null;
+        this.sdk = null;
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying (internal or injected) HTTP client. */
+    getClient() {
+        return this.requireClient();
+    }
+    /** Returns the lazily-required `splunk-sdk` module, or `null` if not installed. */
+    getSdk() {
+        return this.sdk;
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Splunk', {
+                database: 'splunk',
+                host: this.baseURL,
+            });
+        }
+        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: `Splunk ${action ?? 'request'} failed: ${parent.message}`,
+            });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Ingest (HEC)
+    // ---------------------------------------------------------------------
+    /**
+     * Sends a batch of events to the HTTP Event Collector via
+     * `POST /services/collector/event`. Each event is wrapped in a HEC
+     * envelope carrying the shared `meta` (index/sourcetype/source/host); the
+     * envelopes are newline-concatenated as HEC expects.
+     */
+    async push(meta, events) {
+        const client = this.requireClient();
+        const body = events
+            .map((event) => JSON.stringify({
+            event,
+            index: meta.index,
+            sourcetype: meta.sourcetype,
+            source: meta.source,
+            host: meta.host,
+        }))
+            .join('\n');
+        try {
+            return await client.post('/services/collector/event', body, 'application/json');
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Splunk push failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Search (SPL)
+    // ---------------------------------------------------------------------
+    /**
+     * Dispatches an SPL search via `POST /services/search/jobs`. The `search`
+     * string is normalized to start with `search ` when it isn't already a
+     * generating command. Returns the parsed response (job SID or, for a
+     * oneshot search, the results).
+     */
+    async query(spl, options = {}) {
+        const client = this.requireClient();
+        const search = /^\s*(search|\|)/.test(spl) ? spl : `search ${spl}`;
+        const params = new URLSearchParams();
+        params.set('search', search);
+        params.set('output_mode', options.outputMode ?? 'json');
+        if (options.earliest !== undefined)
+            params.set('earliest_time', options.earliest);
+        if (options.latest !== undefined)
+            params.set('latest_time', options.latest);
+        if (options.oneshot)
+            params.set('exec_mode', 'oneshot');
+        try {
+            return await client.post('/services/search/jobs', params.toString(), 'application/x-www-form-urlencoded');
+        }
+        catch (err) {
+            const parent = err instanceof Error ? err : new Error(String(err));
+            throw errors_1.DatabaseError.from(parent, { message: `Splunk query failed: ${parent.message}` });
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Metadata
+    // ---------------------------------------------------------------------
+    /** Lists the configured source types via `GET /services/data/sourcetypes`. */
+    async labels() {
+        return this.doGet('/services/data/sourcetypes', { output_mode: 'json' }, 'labels');
+    }
+    /** Lists the configured indexes via `GET /services/data/indexes`. */
+    async streams() {
+        return this.doGet('/services/data/indexes', { output_mode: 'json' }, 'streams');
+    }
+}
+exports.SplunkStore = SplunkStore;
+exports.default = SplunkStore;