ts-prorm-orm 1.1.0

package/dist/nosql/elasticsearch/index.js

@@ -0,0 +1,377 @@
+"use strict";
+/**
+ * Elasticsearch store implementation.
+ *
+ * Elasticsearch is a distributed document store built around an inverted
+ * index and a JSON-based Query DSL (`match`/`term`/`bool`/`range` queries,
+ * aggregations, sorting) rather than SQL. It has no `JOIN`, no transaction
+ * log, and documents are schema-flexible (mappings describe *how* fields
+ * are indexed, not a hard constraint like a SQL column type), so it does
+ * not fit the SQL-shaped `Dialect` interface used by the SQL dialects in
+ * this repo. Instead it implements the minimal `NoSqlStore` marker
+ * interface (`src/nosql/store.ts`) and exposes Elasticsearch's real
+ * capabilities grouped by concern: connection lifecycle, index management,
+ * document CRUD (single + bulk), search, and alias management.
+ *
+ * Uses the official `@elastic/elasticsearch` driver (v9). This client
+ * speaks the Elasticsearch REST API and is also broadly compatible with
+ * OpenSearch clusters (which forked from Elasticsearch 7.10) for the
+ * subset of the API surface wrapped here - see the README for details and
+ * caveats.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElasticsearchStore = void 0;
+exports.isElasticsearchNotFoundError = isNotFoundError;
+exports.isElasticsearchConflictError = isConflictError;
+const elasticsearch_1 = require("@elastic/elasticsearch");
+const errors_1 = require("../../errors");
+function isNotFoundError(err) {
+    const meta = err?.meta;
+    return meta?.statusCode === 404;
+}
+function isConflictError(err) {
+    const meta = err?.meta;
+    return meta?.statusCode === 409;
+}
+function statusCodeOf(err) {
+    return err?.meta?.statusCode;
+}
+function wrapConnectionError(err, node) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const message = /econnrefused/i.test(parent.message)
+        ? 'Connection refused'
+        : `Unable to connect to Elasticsearch: ${parent.message}`;
+    return new errors_1.ConnectionError(message, {
+        parent,
+        database: 'elasticsearch',
+        host: typeof node === 'string' ? node : undefined,
+    });
+}
+function wrapDatabaseError(err, message) {
+    const parent = err instanceof Error ? err : new Error(String(err));
+    const statusCode = statusCodeOf(err);
+    const detail = statusCode ? `${parent.message} (HTTP ${statusCode})` : parent.message;
+    const combined = message ? `${message}: ${detail}` : detail;
+    return errors_1.DatabaseError.from(parent, { message: combined });
+}
+/**
+ * `ElasticsearchStore` wraps the official `@elastic/elasticsearch` v9
+ * client and exposes index management, document CRUD (single + bulk),
+ * Query-DSL search, and alias management as a typed, promise-based API.
+ */
+class ElasticsearchStore {
+    constructor(options) {
+        this.name = 'elasticsearch';
+        this.library = '@elastic/elasticsearch';
+        this.client = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // Connection lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        if (this.connected && this.client) {
+            return;
+        }
+        const client = new elasticsearch_1.Client(this.options);
+        try {
+            // The driver connects lazily on first request; `ping()` surfaces
+            // connection failures (bad host, refused connection, TLS errors)
+            // immediately instead of on the caller's first real operation.
+            await client.ping();
+            this.client = client;
+            this.connected = true;
+        }
+        catch (err) {
+            await client.close().catch(() => undefined);
+            this.client = null;
+            this.connected = false;
+            throw wrapConnectionError(err, this.options.node);
+        }
+    }
+    async disconnect() {
+        if (this.client) {
+            await this.client.close();
+            this.client = null;
+        }
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected && this.client !== null;
+    }
+    /** Returns the underlying `@elastic/elasticsearch` client for anything not wrapped here. */
+    getClient() {
+        return this.requireClient();
+    }
+    requireClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('Not connected to Elasticsearch', { database: 'elasticsearch' });
+        }
+        return this.client;
+    }
+    async exec(fn, action) {
+        const client = this.requireClient();
+        try {
+            return await fn(client);
+        }
+        catch (err) {
+            throw wrapDatabaseError(err, `Elasticsearch ${action} failed`);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Index management
+    // ---------------------------------------------------------------------
+    /** Create an index, optionally with mappings/settings/aliases. */
+    async createIndex(index, options = {}) {
+        await this.exec((c) => c.indices.create({
+            index,
+            mappings: options.mappings,
+            settings: options.settings,
+            aliases: options.aliases,
+        }), 'CREATE INDEX');
+    }
+    /** Delete an index. Resolves without error if the index doesn't exist. */
+    async deleteIndex(index) {
+        try {
+            await this.exec((c) => c.indices.delete({ index }), 'DELETE INDEX');
+        }
+        catch (err) {
+            if (!isNotFoundError(err.parent)) {
+                throw err;
+            }
+        }
+    }
+    /** Whether an index exists. */
+    async indexExists(index) {
+        return this.exec((c) => c.indices.exists({ index }), 'INDICES EXISTS');
+    }
+    /** Get the field mappings for an index. */
+    async getMapping(index) {
+        const result = await this.exec((c) => c.indices.getMapping({ index }), 'GET MAPPING');
+        return result[index]?.mappings;
+    }
+    /** Add/update field mappings on an existing index. Mapping updates are additive - existing field mappings cannot be changed, only new fields added. */
+    async putMapping(index, mappings) {
+        await this.exec((c) => c.indices.putMapping({ index, ...mappings }), 'PUT MAPPING');
+    }
+    /** Get an index's settings. */
+    async getSettings(index) {
+        const result = await this.exec((c) => c.indices.getSettings({ index }), 'GET SETTINGS');
+        return result[index]?.settings?.index;
+    }
+    /** Update dynamic index settings (e.g. `number_of_replicas`, `refresh_interval`). Static settings like `number_of_shards` require closing the index first (not wrapped here - use `getClient()`). */
+    async putSettings(index, settings) {
+        await this.exec((c) => c.indices.putSettings({ index, settings }), 'PUT SETTINGS');
+    }
+    /** Refresh an index so recently-written documents become visible to search immediately, rather than waiting for the automatic refresh interval. */
+    async refreshIndex(index) {
+        await this.exec((c) => c.indices.refresh({ index }), 'REFRESH');
+    }
+    // ---------------------------------------------------------------------
+    // Document CRUD
+    // ---------------------------------------------------------------------
+    /**
+     * Index (create or overwrite) a document. Omit `id` to let Elasticsearch
+     * auto-generate one. Returns the assigned `_id`.
+     */
+    async indexDocument(index, document, options = {}) {
+        const { id, ...rest } = options;
+        const result = await this.exec((c) => c.index({
+            index,
+            id,
+            document,
+            op_type: rest.opType,
+            refresh: rest.refresh,
+            routing: rest.routing,
+        }), 'INDEX');
+        return result._id;
+    }
+    /** Get a document by ID. Returns `null` if it doesn't exist. */
+    async getDocument(index, id) {
+        try {
+            const result = await this.exec((c) => c.get({ index, id }), 'GET');
+            return (result._source ?? null);
+        }
+        catch (err) {
+            if (err instanceof errors_1.DatabaseError && isNotFoundError(err.parent)) {
+                return null;
+            }
+            throw err;
+        }
+    }
+    /** Whether a document exists. */
+    async documentExists(index, id) {
+        return this.exec((c) => c.exists({ index, id }), 'EXISTS');
+    }
+    /**
+     * Partially update a document by merging `partial` into the stored
+     * `_source`. Pass `options.upsert` to insert that document if `id`
+     * doesn't already exist yet. Throws `EmptyResultError` if the document
+     * doesn't exist and no `upsert` was provided.
+     */
+    async updateDocument(index, id, partial, options = {}) {
+        try {
+            await this.exec((c) => c.update({
+                index,
+                id,
+                doc: partial,
+                upsert: options.upsert,
+                refresh: options.refresh,
+                retry_on_conflict: options.retryOnConflict,
+            }), 'UPDATE');
+        }
+        catch (err) {
+            if (err instanceof errors_1.DatabaseError && isNotFoundError(err.parent)) {
+                throw new errors_1.EmptyResultError(`Document "${id}" not found in index "${index}"`, {
+                    model: index,
+                    primaryKey: id,
+                    parent: err.parent,
+                });
+            }
+            throw err;
+        }
+    }
+    /**
+     * Delete a document by ID. Returns `true` if a document was deleted,
+     * `false` if it didn't exist (rather than throwing, since "already
+     * gone" is a common, non-exceptional outcome for a delete).
+     */
+    async deleteDocument(index, id, options = {}) {
+        try {
+            await this.exec((c) => c.delete({ index, id, refresh: options.refresh, routing: options.routing }), 'DELETE');
+            return true;
+        }
+        catch (err) {
+            if (err instanceof errors_1.DatabaseError && isNotFoundError(err.parent)) {
+                return false;
+            }
+            throw err;
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Bulk operations
+    // ---------------------------------------------------------------------
+    /**
+     * Run a batch of index/create/update/delete operations in a single
+     * request. Unlike a SQL transaction, this is not atomic - each item
+     * succeeds or fails independently; check `result.errors` and each
+     * item's `error` field rather than assuming all-or-nothing.
+     */
+    async bulk(actions) {
+        // The real `_bulk` API rejects an empty request body outright
+        // (`parse_exception: request body is required`, HTTP 400) rather than
+        // treating zero operations as a trivial no-op, so short-circuit before
+        // making the request instead of surfacing that as a DatabaseError for
+        // what is a completely valid (if pointless) caller input.
+        if (actions.length === 0) {
+            return { errors: false, items: [], took: 0 };
+        }
+        const operations = [];
+        for (const action of actions) {
+            if (action.action === 'index' || action.action === 'create') {
+                operations.push({ [action.action]: { _index: action.index, _id: action.id } });
+                operations.push(action.document);
+            }
+            else if (action.action === 'update') {
+                operations.push({ update: { _index: action.index, _id: action.id } });
+                operations.push({ doc: action.document, upsert: action.upsert });
+            }
+            else {
+                operations.push({ delete: { _index: action.index, _id: action.id } });
+            }
+        }
+        const result = await this.exec((c) => c.bulk({ operations }), 'BULK');
+        const items = result.items.map((item) => {
+            const [actionName, detail] = Object.entries(item)[0];
+            return {
+                action: actionName,
+                id: detail._id ?? undefined,
+                status: detail.status ?? 0,
+                error: detail.error
+                    ? { type: detail.error.type ?? 'unknown', reason: detail.error.reason ?? 'unknown error' }
+                    : undefined,
+            };
+        });
+        return { errors: result.errors, items, took: result.took };
+    }
+    /** Convenience wrapper around `bulk()` for indexing many documents into one index at once. */
+    async bulkIndex(index, documents) {
+        return this.bulk(documents.map((d) => ({ action: 'index', index, id: d.id, document: d.document })));
+    }
+    /** Convenience wrapper around `bulk()` for deleting many documents from one index at once. */
+    async bulkDelete(index, ids) {
+        return this.bulk(ids.map((id) => ({ action: 'delete', index, id })));
+    }
+    // ---------------------------------------------------------------------
+    // Search
+    // ---------------------------------------------------------------------
+    /**
+     * Run a Query DSL search (`match`/`term`/`bool`/`range`/etc.) against
+     * one or more indices (comma-separated, or a wildcard pattern). Supports
+     * `from`/`size` pagination, `sort`, and named `aggs`.
+     */
+    async search(index, params = {}) {
+        const result = await this.exec((c) => c.search({
+            index,
+            query: params.query,
+            from: params.from,
+            size: params.size,
+            sort: params.sort,
+            aggs: params.aggs,
+            _source: params.source,
+            track_total_hits: params.trackTotalHits,
+        }), 'SEARCH');
+        const totalRaw = result.hits.total;
+        const total = typeof totalRaw === 'number'
+            ? { value: totalRaw, relation: 'eq' }
+            : { value: totalRaw?.value ?? 0, relation: (totalRaw?.relation ?? 'eq') };
+        return {
+            hits: result.hits.hits.map((hit) => ({
+                id: hit._id,
+                index: hit._index,
+                score: hit._score ?? null,
+                source: hit._source,
+                sort: hit.sort,
+            })),
+            total,
+            maxScore: result.hits.max_score ?? null,
+            tookMs: result.took ?? 0,
+            aggregations: result.aggregations,
+        };
+    }
+    /** Count documents matching a query (or all documents, if `query` is omitted) without fetching them. */
+    async count(index, query) {
+        const result = await this.exec((c) => c.count({ index, query }), 'COUNT');
+        return result.count;
+    }
+    // ---------------------------------------------------------------------
+    // Alias management
+    // ---------------------------------------------------------------------
+    /** Point an alias at an index, creating the alias if it doesn't exist. */
+    async putAlias(index, alias) {
+        await this.exec((c) => c.indices.putAlias({ index, name: alias }), 'PUT ALIAS');
+    }
+    /** Remove an alias from an index. */
+    async deleteAlias(index, alias) {
+        await this.exec((c) => c.indices.deleteAlias({ index, name: alias }), 'DELETE ALIAS');
+    }
+    /** List the indices an alias currently points at. */
+    async getAlias(alias) {
+        const result = await this.exec((c) => c.indices.getAlias({ name: alias }), 'GET ALIAS');
+        return Object.keys(result);
+    }
+    /**
+     * Atomically repoint an alias from one index to another - the standard
+     * zero-downtime reindex pattern (build the new index, then swap the
+     * alias in one request so readers never see a moment with no index
+     * behind the alias).
+     */
+    async swapAlias(alias, fromIndex, toIndex) {
+        await this.exec((c) => c.indices.updateAliases({
+            actions: [{ remove: { index: fromIndex, alias } }, { add: { index: toIndex, alias } }],
+        }), 'UPDATE ALIASES');
+    }
+}
+exports.ElasticsearchStore = ElasticsearchStore;
+exports.default = ElasticsearchStore;