@venizia/ignis 0.1.1 → 0.2.0-1

package/dist/connectors/typesense/connector.js

@@ -1,936 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TypesenseConnector = void 0;
-const common_1 = require("../../connectors/search/common");
-const search_1 = require("../../connectors/search");
-const internal_1 = require("../../connectors/search/internal");
-const ignis_helpers_1 = require("@venizia/ignis-helpers");
-const typesense_1 = require("typesense");
-const connector_internal_1 = require("./internal/connector-internal");
-const types_1 = require("./types");
-// Narrow runtime readers for the `unknown` payloads ITypesenseClientLike hands back - the narrowest cast per field, isolated here instead of repeated ad hoc at every call site.
-const isRecord = (value) => {
-    return typeof value === 'object' && value !== null;
-};
-const readBooleanFlag = (opts) => {
-    const { value, key } = opts;
-    return isRecord(value) ? Boolean(value[key]) : false;
-};
-const readNumberField = (opts) => {
-    const { value, key } = opts;
-    if (!isRecord(value) || typeof value[key] !== 'number') {
-        return 0;
-    }
-    return value[key];
-};
-const readStringField = (opts) => {
-    const { value, key } = opts;
-    if (!isRecord(value) || typeof value[key] !== 'string') {
-        return undefined;
-    }
-    return value[key];
-};
-/** Maps a raw Typesense search hit (snake_case `text_match`) onto the camelCase `ISearchResult` hit shape; read via bracket string access so no snake_case identifier is declared here. */
-const mapSearchHit = (hit) => {
-    if (!isRecord(hit)) {
-        return { document: {} };
-    }
-    const mapped = {
-        document: hit['document'],
-    };
-    if (hit['highlight'] !== undefined) {
-        mapped.highlight = hit['highlight'];
-    }
-    if (Array.isArray(hit['highlights'])) {
-        mapped.highlights = hit['highlights'];
-    }
-    if (typeof hit['text_match'] === 'number') {
-        mapped.score = hit['text_match'];
-    }
-    return mapped;
-};
-/** Maps a raw Typesense search response onto the camelCase `ISearchResult`; snake_case wire fields (`out_of`/`search_time_ms`/`facet_counts`/`grouped_hits`) are read only via bracket string access, never as identifiers, and absent fields are omitted rather than mapped as `undefined`. */
-const mapSearchResult = (raw) => {
-    if (!isRecord(raw)) {
-        return { found: 0, isFoundExact: true };
-    }
-    // `found` is exhaustive UNLESS the engine ran out of its search-time budget: `search_cutoff`
-    // means it stopped early and reported what it had, so the count is an estimate. Hardcoding
-    // `true` told every caller that a truncated count was authoritative.
-    const result = {
-        found: readNumberField({ value: raw, key: 'found' }),
-        isFoundExact: raw['search_cutoff'] !== true,
-    };
-    if (typeof raw['out_of'] === 'number') {
-        result.outOf = raw['out_of'];
-    }
-    if (typeof raw['search_time_ms'] === 'number') {
-        result.searchTimeMs = raw['search_time_ms'];
-    }
-    if (Array.isArray(raw['facet_counts'])) {
-        result.facetCounts = raw['facet_counts'];
-    }
-    if (Array.isArray(raw['grouped_hits'])) {
-        result.groupedHits = raw['grouped_hits'];
-    }
-    if (Array.isArray(raw['hits'])) {
-        result.hits = raw['hits'].map(hit => mapSearchHit(hit));
-    }
-    return result;
-};
-/** `--max-per-page`: Typesense refuses a page larger than this, so a bigger caller limit is served as consecutive windows of one multi_search call rather than as several calls. */
-const MAX_HITS_PER_PAGE = 250;
-/** `limit_multi_searches`: entries permitted in ONE multi_search call, which bounds windowing at 50 x 250 = 12,500 hits. Exceeding it is refused, never silently truncated. */
-const MAX_MULTI_SEARCH_ENTRIES = 50;
-/**
- * Splits a requested page into windows the engine will accept.
- *
- * Windows are expressed as `offset`/`limit` rather than `page`/`per_page` because only offset
- * arithmetic can start a window anywhere - which is also what lets a caller's `skip` land off a
- * page boundary. Exactly one pagination pair is ever sent: Typesense documents `offset`/`limit`
- * and `page`/`per_page` as alternatives and does not state which wins if both appear, so the
- * question is designed out rather than answered.
- */
-const toSearchWindows = (opts) => {
-    const { offset, limit } = opts;
-    if (limit <= MAX_HITS_PER_PAGE) {
-        return [{ offset, limit }];
-    }
-    const windows = [];
-    for (let start = 0; start < limit; start += MAX_HITS_PER_PAGE) {
-        windows.push({ offset: offset + start, limit: Math.min(MAX_HITS_PER_PAGE, limit - start) });
-    }
-    return windows;
-};
-/**
- * Folds windowed responses into the single result the caller asked for.
- *
- * `found`/`outOf` come from the first window because every window ran the same filter and reports
- * the same total. `facetCounts` likewise: facets are computed over the whole result set, not the
- * page, so concatenating them would multiply every count by the window count.
- */
-const mergeWindowedResults = (results) => {
-    const [first] = results;
-    if (results.length === 1) {
-        return first;
-    }
-    const merged = {
-        found: first.found,
-        // AND-folded: the total is only exact if EVERY window ran to completion. One cut-off window
-        // makes the merged count an estimate, and saying otherwise would relaunch the bug above.
-        isFoundExact: results.every(result => result.isFoundExact),
-    };
-    if (first.outOf !== undefined) {
-        merged.outOf = first.outOf;
-    }
-    // MAX, not sum: this field is read as latency, and the windows travel in ONE round trip. Summing
-    // would make a windowed query graph at several times its actual wall-clock.
-    const timings = results
-        .map(result => result.searchTimeMs)
-        .filter((value) => typeof value === 'number');
-    if (timings.length > 0) {
-        merged.searchTimeMs = Math.max(...timings);
-    }
-    if (first.facetCounts) {
-        merged.facetCounts = first.facetCounts;
-    }
-    const hits = results.flatMap(result => result.hits ?? []);
-    if (hits.length > 0) {
-        merged.hits = hits;
-    }
-    return merged;
-};
-/**
- * Reads the requested page out of engine-native params, whichever pair the caller used.
- *
- * `mode: 'raw'` hands these params through untouched, so both spellings have to be understood
- * here; the caller is never asked to normalize.
- */
-const readRequestedPage = (params) => {
-    const limit = typeof params['limit'] === 'number' ? params['limit'] : undefined;
-    const perPage = typeof params['per_page'] === 'number' ? params['per_page'] : undefined;
-    const effectiveLimit = limit ?? perPage;
-    if (effectiveLimit === undefined) {
-        return undefined;
-    }
-    const offset = typeof params['offset'] === 'number' ? params['offset'] : undefined;
-    const page = typeof params['page'] === 'number' ? params['page'] : undefined;
-    const effectiveOffset = offset ?? (page !== undefined ? (page - 1) * effectiveLimit : 0);
-    return { offset: effectiveOffset, limit: effectiveLimit };
-};
-/** Empty TSearchResponse shape returned when search() tolerates a missing collection; built via bracket assignment so no snake_case identifier is declared here. */
-const buildEmptySearchResponse = () => {
-    const response = { found: 0, page: 1, hits: [] };
-    response['out_of'] = 0;
-    response['search_time_ms'] = 0;
-    response['request_params'] = {};
-    return response;
-};
-// Typesense's wire shape for a synonym set; `root` is only present for one-way synonyms.
-const isSynonymResponse = (value) => {
-    return isRecord(value) && typeof value.id === 'string' && Array.isArray(value.synonyms);
-};
-const toSynonym = (value) => {
-    const { id, synonyms, root } = value;
-    // Multi-way sets come back with root: "" - treat empty/absent alike so only one-way keeps a root.
-    return root ? { id, synonyms, root } : { id, synonyms };
-};
-/** Typesense engine connector - built/injected by TypesenseDataSource, which exposes the raw client via getClient(). */
-class TypesenseConnector extends search_1.BaseSearchConnector {
-    constructor(opts) {
-        super({
-            scope: opts.scope ?? TypesenseConnector.name,
-            identifier: opts.identifier ?? opts.name,
-        });
-        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: opts => this.patchCollectionSchema(opts),
-            delete: opts => this.deleteCollection(opts),
-        };
-        this.alias = {
-            upsert: opts => this.upsertAlias(opts),
-            get: opts => this.getAlias(opts),
-        };
-        this.synonymSet = {
-            upsert: opts => this.upsertSynonymSet(opts),
-            get: opts => this.getSynonymSet(opts),
-            list: () => this.listSynonymSets(),
-            delete: opts => this.deleteSynonymSet(opts),
-            link: opts => this.linkSynonymSets(opts),
-        };
-        this.document = {
-            create: (opts) => this.createDocument(opts),
-            get: (opts) => this.getDocument(opts),
-            count: opts => this.countDocuments(opts),
-            upsert: (opts) => this.upsertDocument(opts),
-            update: (opts) => this.updateDocument(opts),
-            delete: opts => this.deleteDocument(opts),
-            import: (opts) => this.importDocuments(opts),
-            updateBy: (opts) => this.updateByFilter(opts),
-            deleteBy: opts => this.deleteByFilter(opts),
-            deleteAll: opts => this.deleteAllDocuments(opts),
-            export: opts => this.exportDocuments(opts),
-        };
-        try {
-            this.client =
-                opts.client ??
-                    new typesense_1.Client({
-                        apiKey: opts.apiKey,
-                        // NodeConfiguration.protocol is required upstream though ITypesenseNode.protocol is optional; default 'http', cloud users pass 'https'.
-                        nodes: opts.nodes.map(node => ({ ...node, protocol: node.protocol ?? 'http' })),
-                        connectionTimeoutSeconds: opts.connectionTimeoutSeconds ?? 5,
-                        numRetries: opts.numRetries,
-                    });
-            opts.onInitialized?.({ name: opts.name });
-        }
-        catch (error) {
-            this.logger
-                .for('constructor')
-                .error('Failed to initialize Typesense client | error: %s', internal_1.SearchConnectorInternal.describeError({ error }));
-            opts.onError?.({ name: opts.name, error });
-            throw error;
-        }
-    }
-    getClient() {
-        return this.client;
-    }
-    isNotFoundError(opts) {
-        return connector_internal_1.TypesenseInternal.isNotFoundError(opts);
-    }
-    async getHealth() {
-        try {
-            const health = await this.client.health.retrieve();
-            return { ok: readBooleanFlag({ value: health, key: 'ok' }) };
-        }
-        catch (error) {
-            this.logger
-                .for(this.getHealth.name)
-                .warn('Health probe failed | error: %s', internal_1.SearchConnectorInternal.describeError({ error }));
-            return { ok: false };
-        }
-    }
-    async createCollection(opts) {
-        const { schema } = opts;
-        const logger = this.logger.for(this.createCollection.name);
-        const rs = await this.runEngineCall({
-            method: this.createCollection.name,
-            run: async () => {
-                const created = (await this.client.collections().create(schema));
-                logger.info('Created collection | name: %s', schema.name);
-                return created;
-            },
-            tolerate: {
-                when: error => connector_internal_1.TypesenseInternal.isAlreadyExistsError({ error }),
-                handle: () => {
-                    logger.info('Collection already exists, skipping | name: %s', schema.name);
-                },
-            },
-        });
-        return rs;
-    }
-    async ensureCollection(opts) {
-        const { schema } = opts;
-        const isExists = await this.collectionExists({ name: schema.name });
-        if (isExists) {
-            return this.getCollection({ name: schema.name });
-        }
-        // The create response IS the collection schema; reading it back instead is a read-after-write race on multi-node clusters (a follower may 404 before the raft log catches up), so only the tolerated already-exists path re-reads.
-        const created = await this.createCollection({ schema });
-        if (created) {
-            return created;
-        }
-        return this.getCollection({ name: schema.name });
-    }
-    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: async () => {
-                const collection = (await this.client.collections(name).retrieve());
-                return collection;
-            },
-            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 collections = (await this.client.collections().retrieve());
-                return collections;
-            },
-        });
-        return rs;
-    }
-    async collectionExists(opts) {
-        const { name } = opts;
-        if (!name || name.trim().length === 0) {
-            return false;
-        }
-        try {
-            const isExists = await this.client.collections(name).exists();
-            return isExists;
-        }
-        catch (error) {
-            this.logger
-                .for(this.collectionExists.name)
-                .warn('Existence check failed, treating as absent | name: %s | error: %s', name, internal_1.SearchConnectorInternal.describeError({ error }));
-            return false;
-        }
-    }
-    async patchCollectionSchema(opts) {
-        const { name, fields } = opts;
-        this.assertNonEmpty({
-            value: name,
-            name: 'collection',
-            method: this.patchCollectionSchema.name,
-        });
-        const logger = this.logger.for(this.patchCollectionSchema.name);
-        await this.runEngineCall({
-            method: this.patchCollectionSchema.name,
-            run: async () => {
-                await this.client.collections(name).update({ fields });
-                logger.info('Patched schema | name: %s | fields: %d', name, fields.length);
-            },
-            tolerate: this.notFoundTolerance({
-                method: this.patchCollectionSchema.name,
-                subject: `Collection '${name}'`,
-            }),
-        });
-    }
-    async deleteCollection(opts) {
-        const { name } = opts;
-        this.assertNonEmpty({ value: name, name: 'collection', method: this.deleteCollection.name });
-        const logger = this.logger.for(this.deleteCollection.name);
-        const rs = await this.runEngineCall({
-            method: this.deleteCollection.name,
-            run: async () => {
-                await this.client.collections(name).delete();
-                logger.info('Deleted collection | name: %s', name);
-                return true;
-            },
-            tolerate: this.notFoundFallback({
-                method: this.deleteCollection.name,
-                message: 'Collection not found, treating as already deleted | name: %s',
-                args: [name],
-                fallback: false,
-            }),
-        });
-        return rs;
-    }
-    async upsertAlias(opts) {
-        const { name, collection } = opts;
-        this.assertNonEmpty({ value: name, name: 'alias', method: this.upsertAlias.name });
-        this.assertNonEmpty({ value: collection, name: 'collection', method: this.upsertAlias.name });
-        const logger = this.logger.for(this.upsertAlias.name);
-        await this.runEngineCall({
-            method: this.upsertAlias.name,
-            run: async () => {
-                const mapping = {};
-                mapping['collection_name'] = collection;
-                await this.client.aliases().upsert(name, mapping);
-                logger.info('Upserted alias | %s -> %s', name, collection);
-            },
-        });
-    }
-    async getAlias(opts) {
-        const { name } = opts;
-        this.assertNonEmpty({ value: name, name: 'alias', method: this.getAlias.name });
-        const rs = await this.runEngineCall({
-            method: this.getAlias.name,
-            run: async () => {
-                const alias = await this.client.aliases(name).retrieve();
-                const aliasName = readStringField({ value: alias, key: 'name' });
-                const collectionName = readStringField({ value: alias, key: 'collection_name' });
-                if (aliasName === undefined || collectionName === undefined) {
-                    internal_1.SearchConnectorInternal.throwNotFoundError({
-                        method: this.getAlias.name,
-                        subject: `Alias '${name}'`,
-                    });
-                }
-                return { name: aliasName, collection: collectionName };
-            },
-            tolerate: this.notFoundFallback({
-                method: this.getAlias.name,
-                message: 'Alias not found | name: %s',
-                args: [name],
-                fallback: null,
-            }),
-        });
-        return rs;
-    }
-    async upsertSynonymSet(opts) {
-        const { name, items } = opts;
-        this.assertNonEmpty({
-            value: name,
-            name: 'synonym set name',
-            method: this.upsertSynonymSet.name,
-        });
-        const logger = this.logger.for(this.upsertSynonymSet.name);
-        await this.runEngineCall({
-            method: this.upsertSynonymSet.name,
-            run: async () => {
-                const payload = items.map(item => item.root
-                    ? { id: item.id, synonyms: item.synonyms, root: item.root }
-                    : { id: item.id, synonyms: item.synonyms });
-                await this.client.synonymSets(name).upsert({ items: payload });
-                logger.info('Upserted synonym set | name: %s | items: %s', name, items.length);
-            },
-        });
-    }
-    async getSynonymSet(opts) {
-        const { name } = opts;
-        this.assertNonEmpty({ value: name, name: 'synonym set name', method: this.getSynonymSet.name });
-        const rs = await this.runEngineCall({
-            method: this.getSynonymSet.name,
-            run: async () => {
-                const result = await this.client.synonymSets(name).retrieve();
-                const items = isRecord(result) && Array.isArray(result.items) ? result.items : [];
-                return items.filter(isSynonymResponse).map(toSynonym);
-            },
-            tolerate: this.notFoundFallback({
-                method: this.getSynonymSet.name,
-                message: 'Synonym set not found | name: %s',
-                args: [name],
-                fallback: null,
-            }),
-        });
-        return rs;
-    }
-    async listSynonymSets() {
-        const rs = await this.runEngineCall({
-            method: this.listSynonymSets.name,
-            run: async () => {
-                const result = await this.client.synonymSets().retrieve();
-                const sets = Array.isArray(result) ? result : [];
-                return sets
-                    .filter(isRecord)
-                    .map(set => set.name)
-                    .filter((setName) => typeof setName === 'string');
-            },
-        });
-        return rs;
-    }
-    async deleteSynonymSet(opts) {
-        const { name } = opts;
-        this.assertNonEmpty({
-            value: name,
-            name: 'synonym set name',
-            method: this.deleteSynonymSet.name,
-        });
-        const logger = this.logger.for(this.deleteSynonymSet.name);
-        const rs = await this.runEngineCall({
-            method: this.deleteSynonymSet.name,
-            run: async () => {
-                await this.client.synonymSets(name).delete();
-                logger.info('Deleted synonym set | name: %s', name);
-                return true;
-            },
-            tolerate: this.notFoundFallback({
-                method: this.deleteSynonymSet.name,
-                message: 'Synonym set not found, treating as already deleted | name: %s',
-                args: [name],
-                fallback: false,
-            }),
-        });
-        return rs;
-    }
-    async linkSynonymSets(opts) {
-        const { collection, synonymSets } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.linkSynonymSets.name,
-        });
-        const logger = this.logger.for(this.linkSynonymSets.name);
-        await this.runEngineCall({
-            method: this.linkSynonymSets.name,
-            run: async () => {
-                await this.client.collections(collection).update({ ['synonym_sets']: synonymSets });
-                logger.info('Linked synonym set(s) | collection: %s | sets: %j', collection, synonymSets);
-            },
-        });
-    }
-    async createDocument(opts) {
-        const { collection, document } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.createDocument.name,
-        });
-        const id = document['id'];
-        const rs = await this.runEngineCall({
-            method: this.createDocument.name,
-            run: async () => {
-                const created = (await this.client
-                    .collections(collection)
-                    .documents()
-                    .create(document));
-                return created;
-            },
-            // Typesense rejects a duplicate id with 409; surfaced as the neutral already_exists conflict rather than the generic sanitized 503 - same contract Meilisearch's createDocument throws.
-            tolerate: {
-                when: error => connector_internal_1.TypesenseInternal.isAlreadyExistsError({ error }),
-                handle: () => {
-                    throw (0, ignis_helpers_1.getError)({
-                        error: common_1.SearchErrors.ALREADY_EXISTS,
-                        message: `[${this.createDocument.name}] Document '${String(id)}' already exists in collection '${collection}'.`,
-                    });
-                },
-            },
-        });
-        return rs;
-    }
-    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.collections(collection).documents(id).retrieve());
-                return document;
-            },
-            tolerate: this.notFoundTolerance({
-                method: this.getDocument.name,
-                subject: `Document '${id}' in collection '${collection}'`,
-            }),
-        });
-        return rs;
-    }
-    /** Typesense's `found` is exhaustive, so a `per_page: 0` search is already an exact count - no separate endpoint needed. */
-    async countDocuments(opts) {
-        const { collection, filterBy } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.countDocuments.name,
-        });
-        const params = { q: '*' };
-        params['per_page'] = 0;
-        if (filterBy) {
-            params['filter_by'] = filterBy;
-        }
-        const result = await this.search({ collection, params });
-        return result.found;
-    }
-    async upsertDocument(opts) {
-        const { collection, document } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.upsertDocument.name,
-        });
-        const rs = await this.runEngineCall({
-            method: this.upsertDocument.name,
-            run: async () => {
-                const upserted = (await this.client
-                    .collections(collection)
-                    .documents()
-                    .upsert(document));
-                return upserted;
-            },
-        });
-        return rs;
-    }
-    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 rs = await this.runEngineCall({
-            method: this.updateDocument.name,
-            run: async () => {
-                const updated = (await this.client
-                    .collections(collection)
-                    .documents(id)
-                    .update(document));
-                return updated;
-            },
-            tolerate: this.notFoundTolerance({
-                method: this.updateDocument.name,
-                subject: `Document '${id}' in collection '${collection}'`,
-            }),
-        });
-        return rs;
-    }
-    async deleteDocument(opts) {
-        const { collection, id } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.deleteDocument.name,
-        });
-        this.assertNonEmpty({ value: id, name: 'document id', method: this.deleteDocument.name });
-        const rs = await this.runEngineCall({
-            method: this.deleteDocument.name,
-            run: async () => {
-                await this.client.collections(collection).documents(id).delete();
-                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;
-    }
-    /** Appends one batch's per-row responses to `responses` and returns that batch's success/fail split. */
-    tallyImportResponses(opts) {
-        const { batchResult, responses } = opts;
-        let successCount = 0;
-        let failCount = 0;
-        for (const row of batchResult) {
-            responses.push(row);
-            if (row.success) {
-                successCount += 1;
-                continue;
-            }
-            failCount += 1;
-        }
-        return { successCount, failCount };
-    }
-    async importDocuments(opts) {
-        const { collection, documents, dirtyValues } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.importDocuments.name,
-        });
-        // typesense's own default action is 'create'; keep runtime validation for untyped callers.
-        const action = opts.action ?? types_1.TypesenseImportActions.CREATE;
-        if (!types_1.TypesenseImportActions.isValid(action)) {
-            throw (0, ignis_helpers_1.getError)({
-                message: `[importDocuments] Invalid action | action: ${action} | valids: ${[...types_1.TypesenseImportActions.SCHEME_SET]}`,
-            });
-        }
-        if (dirtyValues && !types_1.TypesenseDirtyValues.isValid(dirtyValues)) {
-            throw (0, ignis_helpers_1.getError)({
-                message: `[importDocuments] Invalid dirtyValues | value: ${dirtyValues} | valids: ${[...types_1.TypesenseDirtyValues.SCHEME_SET]}`,
-            });
-        }
-        const logger = this.logger.for(this.importDocuments.name);
-        const batchSize = opts.batchSize && opts.batchSize > 0 ? opts.batchSize : 100;
-        const responses = [];
-        let successCount = 0;
-        let failCount = 0;
-        try {
-            for (let start = 0; start < documents.length; start += batchSize) {
-                const batch = documents.slice(start, start + batchSize);
-                // opt out of typesense's default throwOnFail:true so import() returns per-row responses to aggregate below.
-                const importParams = dirtyValues
-                    ? { action, throwOnFail: false, ['dirty_values']: dirtyValues }
-                    : { action, throwOnFail: false };
-                const batchResult = (await this.client
-                    .collections(collection)
-                    .documents()
-                    .import(batch, importParams));
-                const tally = this.tallyImportResponses({ batchResult, responses });
-                successCount += tally.successCount;
-                failCount += tally.failCount;
-            }
-        }
-        catch (error) {
-            // A framework ApplicationError is already sanitized and carries its own statusCode/messageCode, so it surfaces as-is; only raw engine failures get wrapped as a 503, mirroring runEngineCall's guard.
-            if ((0, ignis_helpers_1.isApplicationError)(error)) {
-                throw error;
-            }
-            // Batches before the failure are already persisted server-side; attach partial progress so callers can decide to resume or retry.
-            internal_1.SearchConnectorInternal.wrapDependencyError({
-                method: this.importDocuments.name,
-                error,
-                logger: this.logger,
-                details: {
-                    totalCount: documents.length,
-                    processedCount: successCount + failCount,
-                    successCount,
-                    failCount,
-                },
-            });
-        }
-        logger.info('Imported documents | collection: %s | ok: %d | fail: %d', collection, successCount, failCount);
-        return { count: { success: successCount, fail: failCount }, responses };
-    }
-    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 rs = await this.runEngineCall({
-            method: this.updateByFilter.name,
-            run: async () => {
-                const updateOptions = {};
-                updateOptions['filter_by'] = filterBy;
-                const result = await this.client
-                    .collections(collection)
-                    .documents()
-                    .update(document, updateOptions);
-                return { updatedCount: readNumberField({ value: result, key: 'num_updated' }) };
-            },
-        });
-        return rs;
-    }
-    async deleteByFilter(opts) {
-        const { collection, filterBy, batchSize, ignoreNotFound } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.deleteByFilter.name,
-        });
-        this.assertNonEmpty({ value: filterBy, name: 'filterBy', method: this.deleteByFilter.name });
-        const rs = await this.runEngineCall({
-            method: this.deleteByFilter.name,
-            run: async () => {
-                const deleteParams = {};
-                deleteParams['filter_by'] = filterBy;
-                if (batchSize && batchSize > 0) {
-                    deleteParams['batch_size'] = batchSize;
-                }
-                if (ignoreNotFound !== undefined) {
-                    deleteParams['ignore_not_found'] = ignoreNotFound;
-                }
-                const result = await this.client.collections(collection).documents().delete(deleteParams);
-                return readNumberField({ value: result, key: 'num_deleted' });
-            },
-        });
-        return rs;
-    }
-    async deleteAllDocuments(opts) {
-        const { collection } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.deleteAllDocuments.name,
-        });
-        const logger = this.logger.for(this.deleteAllDocuments.name);
-        const rs = await this.runEngineCall({
-            method: this.deleteAllDocuments.name,
-            run: async () => {
-                // truncate:true is typesense's purpose-built full wipe; a hand-rolled filter_by can't reliably match everything and scans O(n).
-                const result = await this.client
-                    .collections(collection)
-                    .documents()
-                    .delete({ truncate: true });
-                logger.info('Truncated collection | name: %s | deleted: %d', collection, readNumberField({ value: result, key: 'num_deleted' }));
-                return true;
-            },
-        });
-        return rs;
-    }
-    async exportDocuments(opts) {
-        const { collection, filterBy, includeFields } = opts;
-        this.assertNonEmpty({
-            value: collection,
-            name: 'collection',
-            method: this.exportDocuments.name,
-        });
-        const rs = await this.runEngineCall({
-            method: this.exportDocuments.name,
-            run: async () => {
-                const exportParams = {};
-                if (filterBy) {
-                    exportParams['filter_by'] = filterBy;
-                }
-                if (includeFields && includeFields.length > 0) {
-                    exportParams['include_fields'] = includeFields.join(',');
-                }
-                const exported = (await this.client
-                    .collections(collection)
-                    .documents()
-                    .export(exportParams));
-                return exported;
-            },
-        });
-        return rs;
-    }
-    /**
-     * The single transport. Every engine search - one collection or many - is one POST to
-     * `/multi_search`.
-     *
-     * `/multi_search` is a strict superset of GET single-search: it accepts the same per-entry
-     * params, and it carries them in the BODY. GET is capped near 4000 characters of query string,
-     * which a `filter_by` built from an authorization scope exceeds at roughly ninety ids - so a
-     * user with many permitted scopes could not search at all. Choosing between the two at runtime
-     * would mean deciding on URL length, which is only knowable after building the query; there is
-     * no decision point here, so there is nothing to decide wrongly.
-     */
-    async executeMultiSearch(opts) {
-        const { method, entries, union: isUnion, commonParams, options, tolerate } = opts;
-        return this.runEngineCall({
-            method,
-            run: async () => {
-                const result = await this.client.multiSearch.perform(isUnion ? { union: true, searches: entries } : { searches: entries }, commonParams ?? {}, options);
-                return result;
-            },
-            tolerate,
-        });
-    }
-    async search(opts) {
-        const { collection, params, options } = opts;
-        this.assertNonEmpty({ value: collection, name: 'collection', method: this.search.name });
-        const logger = this.logger.for(this.search.name);
-        const paramsRecord = params;
-        const requested = readRequestedPage(paramsRecord);
-        const windows = requested ? toSearchWindows(requested) : [{ offset: 0, limit: 0 }];
-        if (windows.length > 1 && requested) {
-            this.assertSplittablePage({ paramsRecord, requested, windows, collection });
-        }
-        // A single window passes the caller's params through UNCHANGED - `mode: 'raw'` reaches the
-        // engine byte-identical, and only a page the engine would have rejected outright gets rewritten.
-        const entries = windows.length === 1
-            ? [{ ...params, collection }]
-            : windows.map(window => {
-                const entry = {
-                    ...paramsRecord,
-                    collection,
-                    offset: window.offset,
-                    limit: window.limit,
-                };
-                delete entry['page'];
-                delete entry['per_page'];
-                return entry;
-            });
-        const response = (await this.executeMultiSearch({
-            method: this.search.name,
-            entries,
-            commonParams: {},
-            options,
-        }));
-        const results = Array.isArray(response?.results) ? response.results : [];
-        const mapped = [];
-        for (const entry of results) {
-            const classification = connector_internal_1.TypesenseInternal.classifyEntry({ entry });
-            switch (classification.kind) {
-                // Preserves the tolerance the GET path had: an unprovisioned collection answers empty with
-                // a warning rather than a 500.
-                case connector_internal_1.EntryOutcomes.MISSING_COLLECTION: {
-                    logger.warn('Search on missing collection, returning empty | name: %s', collection);
-                    return mapSearchResult(buildEmptySearchResponse());
-                }
-                // A failed entry arrives inside an HTTP 200. Answering empty here would make a rejected
-                // filter indistinguishable from a genuine no-match, and `ISearchResult` has nowhere to put
-                // the error - so this throws rather than returning a plausible zero.
-                case connector_internal_1.EntryOutcomes.FAILED: {
-                    throw (0, ignis_helpers_1.getError)({
-                        message: `[${TypesenseConnector.name}][search] Engine rejected the search | collection: '${collection}' | code: ${classification.code} | ${classification.message}`,
-                    });
-                }
-                // A real result - map it and let the loop collect the remaining windows.
-                case connector_internal_1.EntryOutcomes.OK:
-                default: {
-                    mapped.push(mapSearchResult(entry));
-                    break;
-                }
-            }
-        }
-        if (mapped.length === 0) {
-            return mapSearchResult(buildEmptySearchResponse());
-        }
-        return mergeWindowedResults(mapped);
-    }
-    /**
-     * Refuses a page that cannot be served honestly, rather than serving part of it.
-     *
-     * Grouped results are refused outright: groups span windows, so concatenating duplicates them
-     * and taking the first window drops the rest. Merging by key would mean re-deriving `group_limit`
-     * ordering the engine never produced - inventing an answer, which is the failure class this
-     * whole change exists to remove.
-     */
-    assertSplittablePage(opts) {
-        const { paramsRecord, requested, windows, collection } = opts;
-        // Every PAGE_TOO_LARGE throw names the REQUESTED value and the ceiling that applies to it. One
-        // code is right, since the remedy is always "ask for a smaller page" - but the ceilings differ
-        // (250 grouped, 12,500 windowed, the model's own limit at the repository tier), so a client
-        // branching on the code alone could not tell what to retry with.
-        if (paramsRecord['group_by'] !== undefined) {
-            throw (0, ignis_helpers_1.getError)({
-                error: common_1.SearchErrors.PAGE_TOO_LARGE,
-                message: `[${TypesenseConnector.name}][search] A grouped search cannot be split across pages | collection: '${collection}' | group_by: '${String(paramsRecord['group_by'])}' | requested: ${requested.limit} | maximum: ${MAX_HITS_PER_PAGE}`,
-            });
-        }
-        if (windows.length > MAX_MULTI_SEARCH_ENTRIES) {
-            throw (0, ignis_helpers_1.getError)({
-                error: common_1.SearchErrors.PAGE_TOO_LARGE,
-                message: `[${TypesenseConnector.name}][search] Requested page needs ${windows.length} windows but one multi_search call carries at most ${MAX_MULTI_SEARCH_ENTRIES} | collection: '${collection}' | requested: ${requested.limit} | maximum: ${MAX_MULTI_SEARCH_ENTRIES * MAX_HITS_PER_PAGE}`,
-            });
-        }
-    }
-    async multiSearch(opts) {
-        const { searches, union: isUnion, commonParams, options } = opts;
-        // Shares `search()`'s transport but NOT its policy. This method's contract is the raw envelope:
-        // callers index `results[i]` against `searches[i]` and inspect entries themselves, so error
-        // entries pass through untouched - throwing here would break callers who already handle them.
-        //
-        // It also does not window-split. Merging windows would mean synthesizing a SearchResponse the
-        // engine never returned, with no honest value for `request_params` or `page`, and it would
-        // destroy the 1:1 correspondence that indexing depends on. `search()` can merge because it maps
-        // to a neutral ISearchResult; here the caller is handed engine-shaped objects.
-        const rs = (await this.executeMultiSearch({
-            method: this.multiSearch.name,
-            entries: searches,
-            union: isUnion,
-            commonParams,
-            options,
-        }));
-        return rs;
-    }
-}
-exports.TypesenseConnector = TypesenseConnector;
-//# sourceMappingURL=connector.js.map