@venizia/ignis 0.0.10-5 → 0.1.0

package/dist/connectors/meilisearch/connector.js

@@ -0,0 +1,821 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeilisearchConnector = void 0;
+const common_1 = require("../../common");
+const search_1 = require("../../connectors/search");
+const internal_1 = require("../../connectors/search/internal");
+const ignis_helpers_1 = require("@venizia/ignis-helpers");
+const ignis_helpers_2 = require("@venizia/ignis-helpers");
+const meilisearch_1 = require("meilisearch");
+const internal_2 = require("./internal");
+const types_1 = require("./types");
+const DEFAULT_TASK_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_TASK_INTERVAL_MS = 50;
+/** Ceiling for the exponential poll backoff - one poll per second once a task runs long. */
+const MAX_TASK_INTERVAL_MS = 1000;
+const isRecord = (value) => {
+    return typeof value === 'object' && value !== null;
+};
+/**
+ * Meilisearch's reserved RESPONSE keys - metadata the engine attaches to a hit. Listed explicitly
+ * rather than matched by `_` prefix, because `_geo` is a stored DOCUMENT field (the only name
+ * Meilisearch accepts for a geo field) and prefix-stripping would delete it from every hit.
+ */
+const RESERVED_HIT_KEYS = new Set([
+    '_formatted',
+    '_matchesPosition',
+    '_rankingScore',
+    '_rankingScoreDetails',
+    '_vectors',
+    '_federation',
+    '_geoDistance',
+]);
+/** Strips Meilisearch's reserved response metadata, leaving the caller's own document intact. */
+const extractDocument = (hit) => {
+    const document = {};
+    for (const [key, value] of Object.entries(hit)) {
+        if (RESERVED_HIT_KEYS.has(key)) {
+            continue;
+        }
+        document[key] = value;
+    }
+    return document;
+};
+/**
+ * Maps a Meilisearch search response onto the neutral `ISearchResult`. `totalHits` (the exhaustive
+ * page/hitsPerPage mode) is preferred; `estimatedTotalHits` is approximate, and saying so is what
+ * `isFoundExact` exists for. Wire keys are read via bracket string access, never as identifiers.
+ */
+const mapSearchResult = (raw) => {
+    if (!isRecord(raw)) {
+        return { found: 0, isFoundExact: true };
+    }
+    const totalHits = raw['totalHits'];
+    const isFoundExact = typeof totalHits === 'number';
+    const estimated = raw['estimatedTotalHits'];
+    const result = {
+        found: isFoundExact ? totalHits : typeof estimated === 'number' ? estimated : 0,
+        isFoundExact,
+    };
+    if (typeof raw['processingTimeMs'] === 'number') {
+        result.searchTimeMs = raw['processingTimeMs'];
+    }
+    if (isRecord(raw['facetDistribution'])) {
+        result.facetCounts = [raw['facetDistribution']];
+    }
+    if (Array.isArray(raw['hits'])) {
+        result.hits = raw['hits'].filter(isRecord).map(hit => {
+            const entry = { document: extractDocument(hit) };
+            if (hit['_formatted'] !== undefined) {
+                entry.highlight = hit['_formatted'];
+            }
+            if (typeof hit['_rankingScore'] === 'number') {
+                entry.score = hit['_rankingScore'];
+            }
+            return entry;
+        });
+    }
+    return result;
+};
+/** Adapts the SDK client onto the structural view this connector needs. */
+const adaptClient = (sdk) => {
+    // The SDK's task/index return types carry more detail than this connector reads, so each delegate
+    // widens to AnyType at the seam rather than restating the SDK's shapes.
+    const client = sdk;
+    return {
+        index: (uid) => client.index(uid),
+        createIndex: (uid, options) => client.createIndex(uid, options),
+        getIndex: (uid) => client.getIndex(uid),
+        getIndexes: () => client.getIndexes(),
+        deleteIndex: (uid) => client.deleteIndex(uid),
+        swapIndexes: (pairs) => client.swapIndexes(pairs),
+        // The one real divergence: the SDK exposes getTask under `client.tasks`, not at the root.
+        getTask: (taskUid) => client.tasks.getTask(taskUid),
+        health: () => client.health(),
+        multiSearch: (params) => client.multiSearch(params),
+    };
+};
+/** Meilisearch-backed search connector. Every write awaits its task, so `create()` resolves only once the document is retrievable. */
+class MeilisearchConnector extends search_1.BaseSearchConnector {
+    constructor(opts) {
+        super({
+            scope: opts.scope ?? MeilisearchConnector.name,
+            identifier: opts.identifier ?? opts.name,
+        });
+        this.primaryKeyByCollection = new Map();
+        this.collection = {
+            create: opts => this.createCollection(opts),
+            ensure: opts => this.ensureCollection(opts),
+            get: opts => this.getCollection(opts),
+            list: () => this.listCollections(),
+            exists: opts => this.collectionExists(opts),
+            patchSchema: () => this.patchCollectionSchema(),
+            delete: opts => this.deleteCollection(opts),
+        };
+        /** Meilisearch has no alias layer; a zero-downtime reindex swaps two index uids atomically. */
+        this.swap = {
+            indexes: opts => this.swapIndexes(opts),
+        };
+        /** A flat per-index dictionary. There is no named, linkable synonym-set resource. */
+        this.synonyms = {
+            set: opts => this.setSynonyms(opts),
+            get: opts => this.getSynonyms(opts),
+            reset: opts => this.resetSynonyms(opts),
+        };
+        this.document = {
+            get: (opts) => this.getDocument(opts),
+            count: opts => this.countDocuments(opts),
+            create: (opts) => this.createDocument(opts),
+            upsert: (opts) => this.upsertDocument(opts),
+            update: (opts) => this.updateDocument(opts),
+            updateBy: (opts) => this.updateByFilter(opts),
+            delete: opts => this.deleteDocument(opts),
+            deleteBy: opts => this.deleteByFilter(opts),
+            deleteAll: opts => this.deleteAllDocuments(opts),
+            import: (opts) => this.importDocuments(opts),
+            export: opts => this.exportDocuments(opts),
+        };
+        this.taskTimeoutMs = opts.taskTimeoutMs ?? DEFAULT_TASK_TIMEOUT_MS;
+        this.taskIntervalMs = opts.taskIntervalMs ?? DEFAULT_TASK_INTERVAL_MS;
+        try {
+            if (opts.client) {
+                this.client = opts.client;
+            }
+            else {
+                this.rawClient = new meilisearch_1.Meilisearch({ host: opts.host, apiKey: opts.apiKey });
+                this.client = adaptClient(this.rawClient);
+            }
+            opts.onInitialized?.({ name: opts.name });
+        }
+        catch (error) {
+            this.logger
+                .for('constructor')
+                .error('Failed to initialize Meilisearch client | error: %s', internal_1.SearchConnectorInternal.describeError({ error }));
+            opts.onError?.({ name: opts.name, error });
+            throw error;
+        }
+    }
+    /** The raw SDK client - the escape hatch for anything this connector does not model (fire-and-forget writes, federation, facet search). */
+    getClient() {
+        if (!this.rawClient) {
+            throw (0, ignis_helpers_2.getError)({
+                message: `[${MeilisearchConnector.name}] No raw client available - this connector was constructed with an injected client.`,
+            });
+        }
+        return this.rawClient;
+    }
+    isNotFoundError(opts) {
+        return internal_2.MeilisearchInternal.isNotFoundError(opts);
+    }
+    async getHealth() {
+        const rs = await this.runEngineCall({
+            method: this.getHealth.name,
+            run: async () => {
+                const health = await this.client.health();
+                return { ok: health.status === 'available' };
+            },
+        });
+        return rs;
+    }
+    /**
+     * Every Meilisearch write returns a task uid and is invisible to search until the task reaches
+     * `succeeded`. The SDK's own `waitForTask` defaults to a 5 s timeout - far too short for a bulk
+     * import - so the connector polls itself against a caller-configured ceiling.
+     */
+    async waitForTask(opts) {
+        const { taskUid, method } = opts;
+        const deadline = Date.now() + this.taskTimeoutMs;
+        // Exponential backoff: a fast task still resolves in the first poll or two, but a long-running
+        // one is not polled ~20x/s for its whole duration - the interval doubles up to a 1 s ceiling.
+        let intervalMs = this.taskIntervalMs;
+        for (;;) {
+            const task = await this.client.getTask(taskUid);
+            if (task.status === types_1.MeilisearchTaskStatuses.SUCCEEDED) {
+                return task;
+            }
+            if (types_1.MeilisearchTaskStatuses.isTerminal(task.status)) {
+                this.logger
+                    .for(method)
+                    .error('Task did not succeed | uid: %s | status: %s | error: %s', taskUid, task.status, internal_1.SearchConnectorInternal.describeError({ error: task.error }));
+                internal_1.SearchConnectorInternal.wrapDependencyError({
+                    method,
+                    error: task.error ?? task.status,
+                    logger: this.logger,
+                });
+            }
+            if (Date.now() >= deadline) {
+                throw (0, ignis_helpers_2.getError)({
+                    statusCode: ignis_helpers_2.HTTP.ResultCodes.RS_5.GatewayTimeout,
+                    messageCode: common_1.SearchErrorCodes.TASK_TIMEOUT,
+                    message: `[${method}] Search engine task timed out after ${this.taskTimeoutMs}ms.`,
+                });
+            }
+            await new Promise(resolve => setTimeout(resolve, intervalMs));
+            intervalMs = Math.min(intervalMs * 2, MAX_TASK_INTERVAL_MS);
+        }
+    }
+    /**
+     * Every Meilisearch write returns a task uid and only becomes visible once that task succeeds. This
+     * runs the write, awaits its task to completion, and returns the FINISHED task - callers that read
+     * `details` (e.g. deleteByFilter's `deletedDocuments`) get the terminal record.
+     */
+    async awaitWrite(opts) {
+        const { method, run } = opts;
+        const enqueued = await run();
+        return this.waitForTask({ taskUid: enqueued.taskUid, method });
+    }
+    async createCollection(opts) {
+        const { schema } = opts;
+        this.assertNonEmpty({ value: schema.uid, name: 'uid', method: this.createCollection.name });
+        await this.runEngineCall({
+            method: this.createCollection.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.createCollection.name,
+                    run: () => this.client.createIndex(schema.uid, { primaryKey: schema.primaryKey }),
+                });
+                this.logger.for(this.createCollection.name).info('Created index | uid: %s', schema.uid);
+            },
+            tolerate: {
+                when: error => internal_2.MeilisearchInternal.isAlreadyExistsError({ error }),
+                handle: () => {
+                    this.logger
+                        .for(this.createCollection.name)
+                        .info('Index already exists, skipping | uid: %s', schema.uid);
+                },
+            },
+        });
+        if (schema.primaryKey) {
+            this.primaryKeyByCollection.set(schema.uid, schema.primaryKey);
+        }
+    }
+    /** Create-if-absent, then apply settings. Both steps await their task, so the index is queryable on return. */
+    async ensureCollection(opts) {
+        const { schema } = opts;
+        await this.createCollection(opts);
+        await this.runEngineCall({
+            method: this.ensureCollection.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.ensureCollection.name,
+                    run: () => this.client.index(schema.uid).updateSettings(schema.settings),
+                });
+            },
+        });
+        return schema;
+    }
+    async getCollection(opts) {
+        const { name } = opts;
+        this.assertNonEmpty({ value: name, name: 'collection', method: this.getCollection.name });
+        const rs = await this.runEngineCall({
+            method: this.getCollection.name,
+            run: () => this.client.getIndex(name),
+            tolerate: this.notFoundTolerance({
+                method: this.getCollection.name,
+                subject: `Collection '${name}'`,
+            }),
+        });
+        return rs;
+    }
+    async listCollections() {
+        const rs = await this.runEngineCall({
+            method: this.listCollections.name,
+            run: async () => {
+                const page = await this.client.getIndexes();
+                return page.results;
+            },
+        });
+        return rs;
+    }
+    async collectionExists(opts) {
+        const { name } = opts;
+        const rs = await this.runEngineCall({
+            method: this.collectionExists.name,
+            run: async () => {
+                await this.client.getIndex(name);
+                return true;
+            },
+            tolerate: this.notFoundFallback({
+                method: this.collectionExists.name,
+                message: 'Index not found, treating as absent | uid: %s',
+                args: [name],
+                fallback: false,
+            }),
+        });
+        return rs;
+    }
+    /** Meilisearch is schemaless: there is no field schema to patch. Settings are applied by ensureCollection. */
+    patchCollectionSchema() {
+        throw (0, ignis_helpers_2.getError)({
+            statusCode: ignis_helpers_2.HTTP.ResultCodes.RS_5.NotImplemented,
+            messageCode: common_1.CoreErrorCodes.NOT_SUPPORTED,
+            message: `[${MeilisearchConnector.name}] Field-schema patching is not supported - Meilisearch is schemaless; change index settings via ensureCollection instead.`,
+        });
+    }
+    async deleteCollection(opts) {
+        const { name } = opts;
+        const rs = await this.runEngineCall({
+            method: this.deleteCollection.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.deleteCollection.name,
+                    run: () => this.client.deleteIndex(name),
+                });
+                return true;
+            },
+            tolerate: this.notFoundFallback({
+                method: this.deleteCollection.name,
+                message: 'Index not found, treating as already deleted | uid: %s',
+                args: [name],
+                fallback: false,
+            }),
+        });
+        return rs;
+    }
+    async swapIndexes(opts) {
+        const { pairs } = opts;
+        await this.runEngineCall({
+            method: this.swapIndexes.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.swapIndexes.name,
+                    run: () => this.client.swapIndexes(pairs.map(indexes => ({ indexes }))),
+                });
+                this.logger
+                    .for(this.swapIndexes.name)
+                    .info('Swapped index pair(s) | count: %s', pairs.length);
+            },
+        });
+    }
+    async setSynonyms(opts) {
+        const { collection, items } = opts;
+        const dictionary = {};
+        for (const entry of items) {
+            if (entry.root) {
+                dictionary[entry.root] = entry.synonyms;
+                continue;
+            }
+            for (const term of entry.synonyms) {
+                dictionary[term] = entry.synonyms.filter(other => other !== term);
+            }
+        }
+        await this.runEngineCall({
+            method: this.setSynonyms.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.setSynonyms.name,
+                    run: () => this.client.index(collection).updateSynonyms(dictionary),
+                });
+            },
+        });
+    }
+    async getSynonyms(opts) {
+        const { collection } = opts;
+        const rs = await this.runEngineCall({
+            method: this.getSynonyms.name,
+            run: async () => {
+                const settings = await this.client.index(collection).getSettings();
+                const dictionary = settings['synonyms'];
+                if (!isRecord(dictionary)) {
+                    return [];
+                }
+                return Object.entries(dictionary).map(([id, synonyms]) => ({
+                    id,
+                    synonyms: Array.isArray(synonyms) ? synonyms : [],
+                }));
+            },
+        });
+        return rs;
+    }
+    async resetSynonyms(opts) {
+        const { collection } = opts;
+        await this.runEngineCall({
+            method: this.resetSynonyms.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.resetSynonyms.name,
+                    run: () => this.client.index(collection).resetSynonyms(),
+                });
+            },
+        });
+    }
+    async getDocument(opts) {
+        const { collection, id } = opts;
+        this.assertNonEmpty({ value: collection, name: 'collection', method: this.getDocument.name });
+        this.assertNonEmpty({ value: id, name: 'document id', method: this.getDocument.name });
+        const rs = await this.runEngineCall({
+            method: this.getDocument.name,
+            run: async () => {
+                const document = (await this.client.index(collection).getDocument(id));
+                return document;
+            },
+            tolerate: this.notFoundTolerance({
+                method: this.getDocument.name,
+                subject: `Document '${id}' in collection '${collection}'`,
+            }),
+        });
+        return rs;
+    }
+    /**
+     * Exact and uncapped. `pagination.maxTotalHits` bounds the SEARCH route only - Meilisearch's own
+     * documentation states it "has no effect on the get documents" endpoints - so reading `total` from
+     * `documents/fetch` is what keeps `count()` from quietly lying on large filtered sets.
+     */
+    async countDocuments(opts) {
+        const { collection, filterBy } = opts;
+        this.assertNonEmpty({
+            value: collection,
+            name: 'collection',
+            method: this.countDocuments.name,
+        });
+        const rs = await this.runEngineCall({
+            method: this.countDocuments.name,
+            run: async () => {
+                const params = { limit: 0 };
+                if (filterBy) {
+                    params['filter'] = filterBy;
+                }
+                const page = await this.client.index(collection).getDocuments(params);
+                return page.total;
+            },
+        });
+        return rs;
+    }
+    /**
+     * Create-only, matching the neutral contract (and Typesense, whose `documents().create()` rejects a
+     * duplicate id). Meilisearch has no conditional insert - `addDocuments` is add-or-REPLACE - so the id
+     * is checked first. That check is NOT atomic: two concurrent creates of the same id can both pass it,
+     * and the second write wins. Callers needing last-write-wins should use `upsert` and say so.
+     */
+    async createDocument(opts) {
+        const { collection, document } = opts;
+        this.assertNonEmpty({
+            value: collection,
+            name: 'collection',
+            method: this.createDocument.name,
+        });
+        const primaryKey = await this.resolvePrimaryKey({ collection });
+        const id = document[primaryKey];
+        if (id !== undefined && (await this.documentExists({ collection, id: String(id) }))) {
+            throw (0, ignis_helpers_2.getError)({
+                statusCode: ignis_helpers_2.HTTP.ResultCodes.RS_4.Conflict,
+                messageCode: common_1.SearchErrorCodes.ALREADY_EXISTS,
+                message: `[${this.createDocument.name}] Document '${String(id)}' already exists in collection '${collection}'.`,
+            });
+        }
+        return this.upsertDocument(opts);
+    }
+    async documentExists(opts) {
+        const { collection, id } = opts;
+        const rs = await this.runEngineCall({
+            method: this.documentExists.name,
+            run: async () => {
+                await this.client.index(collection).getDocument(id);
+                return true;
+            },
+            tolerate: this.notFoundFallback({
+                method: this.documentExists.name,
+                message: 'Document not found, treating as absent | collection: %s | id: %s',
+                args: [collection, id],
+                fallback: false,
+            }),
+        });
+        return rs;
+    }
+    /** Add-or-replace by primary key. Awaits the task, so the document is retrievable when this resolves. */
+    async upsertDocument(opts) {
+        const { collection, document } = opts;
+        this.assertNonEmpty({
+            value: collection,
+            name: 'collection',
+            method: this.upsertDocument.name,
+        });
+        await this.runEngineCall({
+            method: this.upsertDocument.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.upsertDocument.name,
+                    run: () => this.client.index(collection).addDocuments([document]),
+                });
+            },
+        });
+        return document;
+    }
+    /**
+     * Merge-update by primary key: fields absent from the patch are preserved. Meilisearch's write
+     * returns only a task, never the row, so the merged document must be read back - one extra round
+     * trip versus Typesense, and NOT atomic: a concurrent write landing between the task succeeding and
+     * this read means the returned document is not necessarily what this call wrote.
+     */
+    async updateDocument(opts) {
+        const { collection, id, document } = opts;
+        this.assertNonEmpty({
+            value: collection,
+            name: 'collection',
+            method: this.updateDocument.name,
+        });
+        this.assertNonEmpty({ value: id, name: 'document id', method: this.updateDocument.name });
+        const primaryKey = await this.resolvePrimaryKey({ collection });
+        // Meilisearch's updateDocuments is add-or-update, so a missing id would silently upsert; the
+        // neutral contract (and Typesense) throws 404 instead. Existence is checked before any write.
+        if (!(await this.documentExists({ collection, id }))) {
+            internal_1.SearchConnectorInternal.throwNotFoundError({
+                method: this.updateDocument.name,
+                subject: `Document '${id}' in collection '${collection}'`,
+            });
+        }
+        await this.runEngineCall({
+            method: this.updateDocument.name,
+            // `[primaryKey]: id` last: the path id is authoritative, so a patch carrying its own primary
+            // key cannot redirect the write onto a different row.
+            run: () => this.awaitWrite({
+                method: this.updateDocument.name,
+                run: () => this.client.index(collection).updateDocuments([{ ...document, [primaryKey]: id }]),
+            }),
+        });
+        return this.getDocument({ collection, id });
+    }
+    /**
+     * Meilisearch has no update-by-filter endpoint. `documents/edit` would do it server-side, but it is
+     * gated behind an experimental flag, is documented as breaking between minor versions, and has an
+     * open correctness bug - so this pages ids out of the uncapped `documents/fetch` route and merges
+     * them back in batches. NOT atomic: a concurrent write to a matched document may be overwritten.
+     */
+    async updateByFilter(opts) {
+        const { collection, document, filterBy } = opts;
+        this.assertNonEmpty({
+            value: collection,
+            name: 'collection',
+            method: this.updateByFilter.name,
+        });
+        this.assertNonEmpty({ value: filterBy, name: 'filterBy', method: this.updateByFilter.name });
+        const primaryKey = await this.resolvePrimaryKey({ collection });
+        const rs = await this.runEngineCall({
+            method: this.updateByFilter.name,
+            run: async () => {
+                const ids = await this.collectMatchingIds({ collection, filterBy, primaryKey });
+                for (let index = 0; index < ids.length; index += types_1.MEILISEARCH_DEFAULT_UPDATE_BATCH_SIZE) {
+                    const batch = ids.slice(index, index + types_1.MEILISEARCH_DEFAULT_UPDATE_BATCH_SIZE);
+                    // `[primaryKey]: id` last: each matched row keeps its own id even if the patch carries one.
+                    const documents = batch.map(id => ({ ...document, [primaryKey]: id }));
+                    await this.awaitWrite({
+                        method: this.updateByFilter.name,
+                        run: () => this.client.index(collection).updateDocuments(documents),
+                    });
+                }
+                this.logger
+                    .for(this.updateByFilter.name)
+                    .info('Updated documents by filter | collection: %s | count: %s', collection, ids.length);
+                return { updatedCount: ids.length };
+            },
+        });
+        return rs;
+    }
+    /** Walks `documents/fetch` until exhausted. Not bounded by `pagination.maxTotalHits`. */
+    async fetchAllDocuments(opts) {
+        const { collection, filterBy, fields } = opts;
+        const rows = [];
+        let offset = 0;
+        for (;;) {
+            const params = {
+                limit: types_1.MEILISEARCH_DEFAULT_FETCH_PAGE_SIZE,
+                offset,
+            };
+            if (filterBy) {
+                params['filter'] = filterBy;
+            }
+            if (fields?.length) {
+                params['fields'] = fields;
+            }
+            const page = await this.client.index(collection).getDocuments(params);
+            rows.push(...page.results);
+            offset += types_1.MEILISEARCH_DEFAULT_FETCH_PAGE_SIZE;
+            if (offset >= page.total || page.results.length === 0) {
+                return rows;
+            }
+        }
+    }
+    async collectMatchingIds(opts) {
+        const { collection, filterBy, primaryKey } = opts;
+        const ids = [];
+        const rows = await this.fetchAllDocuments({
+            collection,
+            filterBy,
+            fields: [primaryKey],
+        });
+        for (const row of rows) {
+            if (isRecord(row) && row[primaryKey] !== undefined) {
+                ids.push(String(row[primaryKey]));
+            }
+        }
+        return ids;
+    }
+    async deleteDocument(opts) {
+        const { collection, id } = opts;
+        const rs = await this.runEngineCall({
+            method: this.deleteDocument.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.deleteDocument.name,
+                    run: () => this.client.index(collection).deleteDocument(id),
+                });
+                return true;
+            },
+            tolerate: this.notFoundFallback({
+                method: this.deleteDocument.name,
+                message: 'Document not found, returning false | collection: %s | id: %s',
+                args: [collection, id],
+                fallback: false,
+            }),
+        });
+        return rs;
+    }
+    /**
+     * Delete-by-filter IS native here (unlike update-by-filter). The count is read from the FINISHED
+     * task's `details.deletedDocuments` - a pre-count would be wrong in both directions if a concurrent
+     * write added or removed a matching document between counting and deleting.
+     */
+    async deleteByFilter(opts) {
+        const { collection, filterBy } = opts;
+        this.assertNonEmpty({ value: filterBy, name: 'filterBy', method: this.deleteByFilter.name });
+        const rs = await this.runEngineCall({
+            method: this.deleteByFilter.name,
+            run: async () => {
+                const task = await this.awaitWrite({
+                    method: this.deleteByFilter.name,
+                    run: () => this.client.index(collection).deleteDocuments({ filter: filterBy }),
+                });
+                const deleted = task.details?.['deletedDocuments'];
+                if (typeof deleted !== 'number') {
+                    throw (0, ignis_helpers_2.getError)({
+                        message: `[${this.deleteByFilter.name}] Task ${task.taskUid} reported no deletedDocuments count | collection: ${collection}`,
+                    });
+                }
+                return deleted;
+            },
+        });
+        return rs;
+    }
+    async deleteAllDocuments(opts) {
+        const { collection } = opts;
+        const rs = await this.runEngineCall({
+            method: this.deleteAllDocuments.name,
+            run: async () => {
+                await this.awaitWrite({
+                    method: this.deleteAllDocuments.name,
+                    run: () => this.client.index(collection).deleteAllDocuments(),
+                });
+                return true;
+            },
+        });
+        return rs;
+    }
+    /**
+     * Batches through addDocuments, awaiting each batch's task before starting the next. Meilisearch
+     * import is batch-atomic, so `count.fail` is structurally always 0: a batch either lands whole or
+     * throws. A thrown import means the batches after the failure point did not land - the error's
+     * `details` carry `processedCount` so callers can resume from there.
+     */
+    async importDocuments(opts) {
+        const { collection, documents, batchSize } = opts;
+        const size = batchSize ?? types_1.MEILISEARCH_DEFAULT_UPDATE_BATCH_SIZE;
+        const rs = await this.runEngineCall({
+            method: this.importDocuments.name,
+            run: async () => {
+                const responses = [];
+                let processedCount = 0;
+                for (let index = 0; index < documents.length; index += size) {
+                    const batch = documents.slice(index, index + size);
+                    try {
+                        const task = await this.awaitWrite({
+                            method: this.importDocuments.name,
+                            run: () => this.client.index(collection).addDocuments(batch),
+                        });
+                        responses.push(task);
+                        processedCount += batch.length;
+                    }
+                    catch (error) {
+                        // Earlier batches are already persisted server-side, so EVERY failure carries partial
+                        // progress - callers decide to resume from processedCount or retry the whole import.
+                        const details = { totalCount: documents.length, processedCount };
+                        // An error the framework already shaped (waitForTask's 504 task_timeout, its
+                        // task-failed 503, a sanitized 4xx) keeps its statusCode/messageCode - re-wrapping
+                        // would erase those semantics behind a generic 503. Progress is merged onto it.
+                        if ((0, ignis_helpers_1.isApplicationError)(error)) {
+                            error.extra = {
+                                ...error.extra,
+                                details: { ...error.extra?.['details'], ...details },
+                            };
+                            throw error;
+                        }
+                        internal_1.SearchConnectorInternal.wrapDependencyError({
+                            method: this.importDocuments.name,
+                            error,
+                            logger: this.logger,
+                            details,
+                        });
+                    }
+                }
+                this.logger
+                    .for(this.importDocuments.name)
+                    .info('Imported documents | collection: %s | ok: %s', collection, documents.length);
+                // A task that did not succeed already threw, so every document in a resolved import landed.
+                return { count: { success: documents.length, fail: 0 }, responses };
+            },
+        });
+        return rs;
+    }
+    /** Newline-delimited JSON, matching the Typesense connector's export contract. */
+    async exportDocuments(opts) {
+        const { collection, filterBy, includeFields } = opts;
+        const rs = await this.runEngineCall({
+            method: this.exportDocuments.name,
+            run: async () => {
+                // Pages to exhaustion. A single fetch would silently truncate at the page size, which for an
+                // export - the primitive people back up and reindex with - is data loss without an error.
+                const rows = await this.fetchAllDocuments({
+                    collection,
+                    ...(filterBy ? { filterBy } : {}),
+                    ...(includeFields?.length ? { fields: includeFields } : {}),
+                });
+                return rows.map(row => JSON.stringify(row)).join('\n');
+            },
+        });
+        return rs;
+    }
+    async search(opts) {
+        const { collection, params } = opts;
+        const rs = await this.runEngineCall({
+            method: this.search.name,
+            run: async () => {
+                const wire = isRecord(params) ? params : {};
+                const { q, ...rest } = wire;
+                const raw = await this.client
+                    .index(collection)
+                    .search(typeof q === 'string' && q !== '*' ? q : null, rest);
+                return mapSearchResult(raw);
+            },
+            tolerate: {
+                when: error => internal_2.MeilisearchInternal.isNotFoundError({ error }),
+                handle: () => {
+                    this.logger
+                        .for(this.search.name)
+                        .warn('Search on missing collection, returning empty | name: %s', collection);
+                    return { found: 0, isFoundExact: true, hits: [] };
+                },
+            },
+        });
+        return rs;
+    }
+    /**
+     * Batched, non-federated: N queries in one round trip, N result sets back. `commonParams` are
+     * defaults - a per-query param always wins over them, so a query's own `q` is never clobbered.
+     */
+    async multiSearch(opts) {
+        const { searches, union: isUnion, commonParams, options } = opts;
+        if (isUnion) {
+            throw (0, ignis_helpers_2.getError)({
+                statusCode: ignis_helpers_2.HTTP.ResultCodes.RS_5.NotImplemented,
+                messageCode: common_1.CoreErrorCodes.NOT_SUPPORTED,
+                message: `[${MeilisearchConnector.name}] Union multi-search is not supported - Meilisearch merges results through its federation option, which this connector does not model.`,
+            });
+        }
+        const rs = await this.runEngineCall({
+            method: this.multiSearch.name,
+            run: () => {
+                const common = isRecord(commonParams) ? commonParams : {};
+                const queries = searches.filter(isRecord).map(entry => {
+                    const { collection, ...rest } = entry;
+                    // `common` first: a per-query param overrides the shared default, never the reverse.
+                    return { indexUid: collection, q: '', ...common, ...rest };
+                });
+                return this.client.multiSearch({ queries, ...(isRecord(options) ? options : {}) });
+            },
+        });
+        return rs;
+    }
+    /** Meilisearch infers the primary key from the first document; the compiler pins it, and the index reports it. */
+    async resolvePrimaryKey(opts) {
+        const { collection } = opts;
+        const cached = this.primaryKeyByCollection.get(collection);
+        if (cached) {
+            return cached;
+        }
+        // Wrapped so a raw getIndex failure is sanitized here rather than escaping through whichever
+        // write (create/update/updateBy) triggered the lookup and leaking engine detail.
+        const index = await this.runEngineCall({
+            method: this.resolvePrimaryKey.name,
+            run: () => this.client.getIndex(collection),
+        });
+        const primaryKey = isRecord(index) ? index['primaryKey'] : undefined;
+        if (typeof primaryKey !== 'string' || primaryKey.length === 0) {
+            throw (0, ignis_helpers_2.getError)({
+                message: `[${this.resolvePrimaryKey.name}] Collection '${collection}' has no primary key - Meilisearch cannot merge-update without one.`,
+            });
+        }
+        this.primaryKeyByCollection.set(collection, primaryKey);
+        return primaryKey;
+    }
+}
+exports.MeilisearchConnector = MeilisearchConnector;
+//# sourceMappingURL=connector.js.map