@lde/search-typesense 0.15.6 → 0.16.0

package/dist/query-compiler.d.ts

@@ -1,14 +1,14 @@
 import type { SearchParams } from 'typesense/lib/Typesense/Documents.js';
 import { type Filter, type SearchQuery, type SearchType } from '@lde/search';
 /**
- * Options for {@link buildSearchParams} — the query half of the engine
+ * Options for {@link buildSearchParams} – the query half of the engine
  * adapter. {@link TypesenseSearchEngineOptions} extends this, so each knob is
  * declared once and the engine forwards its options wholesale.
  */
 export interface BuildSearchParamsOptions {
     /**
      * Cap on the number of buckets returned per facet (`max_facet_values`). Left
-     * unset, Typesense defaults to 10 — too few for high-cardinality facets
+     * unset, Typesense defaults to 10 – too few for high-cardinality facets
      * (publisher, keyword), so a deployment with such facets must raise it. Range
      * facets return one bucket per declared range regardless, but a value > the
      * range count is still safe.
@@ -27,7 +27,7 @@ export interface BuildSearchParamsOptions {
 }
 /**
  * Compile the engine-neutral {@link SearchQuery} into Typesense search
- * parameters — the query half of the engine adapter. Pure (no client, no env),
+ * parameters – the query half of the engine adapter. Pure (no client, no env),
  * so the mapping is asserted directly in unit tests. Field names come from
  * {@link physicalFields}, the same convention the projection and the collection
  * schema use, so a query can never reference a field the index does not carry.

package/dist/query-compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-compiler.d.ts","sourceRoot":"","sources":["../src/query-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAEL,KAAK,MAAM,EAEX,KAAK,WAAW,EAChB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAYrB;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,wBAA6B,GACrC,YAAY,CAAC,MAAM,CAAC,CAkCtB;AA2LD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"query-compiler.d.ts","sourceRoot":"","sources":["../src/query-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAEL,KAAK,MAAM,EAEX,KAAK,WAAW,EAChB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAarB;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,wBAA6B,GACrC,YAAY,CAAC,MAAM,CAAC,CAkCtB;AAqMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/query-compiler.js

@@ -1,8 +1,8 @@
 import { fold } from '@lde/text-normalization';
-import { fieldNamed, filterOperator, filterOperatorFor, isoToUnixSeconds, isRangeFacet, pageForOffset, physicalFields, searchableFields, } from '@lde/search/adapter';
+import { fieldNamed, filterOperator, filterOperatorFor, ID_FIELD, isoToUnixSeconds, isRangeFacet, pageForOffset, physicalFields, searchableFields, } from '@lde/search/adapter';
 /**
  * Compile the engine-neutral {@link SearchQuery} into Typesense search
- * parameters — the query half of the engine adapter. Pure (no client, no env),
+ * parameters – the query half of the engine adapter. Pure (no client, no env),
  * so the mapping is asserted directly in unit tests. Field names come from
  * {@link physicalFields}, the same convention the projection and the collection
  * schema use, so a query can never reference a field the index does not carry.
@@ -110,12 +110,22 @@ function compileFilterBy(where, searchType, onIgnoredFilter) {
         .join(' && ');
 }
 function compileFilter(filter, searchType) {
+    // `id` is the Typesense document key, not a declared field. Exact `:=`
+    // membership, like a non-facet field ({@link compileMembership}), so an IRI
+    // cannot partial-match on a shared path segment. (`fetchLabels` resolves
+    // labels with the looser `id:[…]`; these are deliberately not the same
+    // clause.)
+    if (filter.field === ID_FIELD) {
+        return 'in' in filter && filter.in.length > 0
+            ? `${ID_FIELD}:=[${filter.in.map(escapeFilterValue).join(',')}]`
+            : undefined;
+    }
     const field = fieldNamed(searchType, filter.field);
     if (field === undefined) {
         return undefined;
     }
     // A clause whose operator does not match the field's kind (e.g. `range` on a
-    // keyword) would reach the engine as garbage syntax — skip it instead.
+    // keyword) would reach the engine as garbage syntax – skip it instead.
     if (filterOperatorFor(field.kind) !== filterOperator(filter)) {
         return undefined;
     }

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAGL,KAAK,cAAc,EAKnB,KAAK,UAAU,EAGf,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEf,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAarB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAG7B;;;;sDAIsD;AACtD,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,MAAM,GAAG,MAAM,CAChC,SAAQ,wBAAwB;IAChC;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACnE;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB,CACpC,KAAK,SAAS,SAAS,UAAU,EAAE,GAAG,SAAS,UAAU,EAAE,CAC3D,SAAQ,YAAY,CAAC,KAAK,CAAC;IAC3B;;;;;;;OAOG;IACH,iBAAiB,CAAC,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,CAAC,KAAK,SAAS,SAAS,UAAU,EAAE,EAEzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,EAC3B,OAAO,GAAE,4BAA4B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAM,GAChE,qBAAqB,CAAC,KAAK,CAAC,CA+T9B;AAyCD,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AA0HD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAC/B,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAgDtC;AA6BD,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS;QAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS;YACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;SACxB,EAAE,CAAC;KACL,EAAE,CAAC;CACL;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,uBAAuB,EACjC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,GAC1C,YAAY,CAsCd"}

package/dist/search.js

@@ -1,4 +1,4 @@
-import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isRangeFacet, labelFieldOf, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isRangeFacet, isUnsatisfiable, labelFieldOf, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
 import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
 import { deriveCollectionName } from './collection-name.js';
 /**
@@ -176,12 +176,21 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // rejected up front, for EVERY caller.
             assertTypeInSchema(schema, searchType);
             assertValidQuery(query, searchType);
+            // Asks for no document (an empty `id` membership): answer it without a
+            // round-trip rather than dispatching a query whose only filter compiles
+            // away, which would hand back the whole collection.
+            if (isUnsatisfiable(query)) {
+                return { total: 0, hits: [], facets: {} };
+            }
             const params = buildSearchParams(query, searchType, options);
             const cachedLabelsPromise = startCachedLabels(searchType);
-            const response = (await client
-                .collections(collections.get(searchType.class))
-                .documents()
-                .search(params));
+            // ONE search, but through `multi_search` (POST) like the facet batch and
+            // the label lookup: `documents().search()` is a GET, so a long
+            // `filter_by` – a batch `id` lookup, or any membership over many IRIs –
+            // would overflow Typesense's 4000-char query-string limit. POST puts it
+            // in the body, so the filter is bounded by the caller's request, not by
+            // the URL.
+            const response = await performSingleSearch(client, collections.get(searchType.class), params);
             const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups([response], labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? []));
             return parseSearchResponse(response, searchType, labels);
         },
@@ -195,12 +204,23 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             }
             const collection = collections.get(searchType.class);
             const cachedLabelsPromise = startCachedLabels(searchType);
+            // A query asking for no document faces the same inversion as in
+            // `search()`: its only filter would compile away and it would count
+            // facets over the whole collection. Such a query is answered with empty
+            // facets and kept OUT of the batch, so `dispatched` maps each sent search
+            // back to its caller position.
+            const dispatched = queries
+                .map((query, index) => ({ query, index }))
+                .filter(({ query }) => !isUnsatisfiable(query));
+            if (dispatched.length === 0) {
+                return queries.map(() => ({ facets: {} }));
+            }
             // The whole batch travels as ONE multi_search round-trip. Each query
             // compiles as facet-only regardless of what it carries: no hits
             // (per_page 0) and no ordering – nothing is transferred or sorted that
             // this method cannot return.
             const { results } = (await client.multiSearch.perform({
-                searches: queries.map((query) => ({
+                searches: dispatched.map(({ query }) => ({
                     collection,
                     ...buildSearchParams({ ...query, orderBy: [], limit: 0, offset: 0 }, searchType, options),
                 })),
@@ -211,12 +231,22 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // multi_search reports a failed entry inline instead of rejecting the
             // call; pass that through as a per-query outcome – naming the facets,
             // not the position, since the batch order is the caller's internal –
-            // so one failed query never discards its siblings' facets.
-            return results.map((result, index) => 'error' in result
-                ? {
-                    error: new Error(`Typesense facet search for “${queries[index].facets.join('”, “')}” failed${result.code !== undefined ? ` (${result.code})` : ''}: ${result.error}`),
-                }
-                : { facets: parseSearchResponse(result, searchType, labels).facets });
+            // so one failed query never discards its siblings' facets. Every caller
+            // position is answered: a dispatched query by its entry, an
+            // unsatisfiable one by empty facets.
+            const outcomes = queries.map(() => ({ facets: {} }));
+            dispatched.forEach(({ index }, entry) => {
+                const result = results[entry];
+                outcomes[index] =
+                    result === undefined || 'error' in result
+                        ? {
+                            error: new Error(`Typesense facet search for “${queries[index].facets.join('”, “')}” failed${result?.code !== undefined ? ` (${result.code})` : ''}: ${result?.error ?? 'no result entry'}`),
+                        }
+                        : {
+                            facets: parseSearchResponse(result, searchType, labels).facets,
+                        };
+            });
+            return outcomes;
         },
     };
     // The runtime object is string-keyed; the literal-schema typing narrows it.
@@ -329,6 +359,25 @@ function labelLookupGroups(responses, sources, outputSources) {
         iris: [...iris],
     }));
 }
+/**
+ * Dispatch one search as a single-entry `multi_search` (POST). `multi_search`
+ * reports a failed entry inline instead of rejecting the call, so the entry is
+ * translated back into a throw: `search()` rejects on engine failure, and that
+ * contract must not weaken just because the transport moved off GET.
+ */
+async function performSingleSearch(client, collection, params) {
+    const { results } = (await client.multiSearch.perform({
+        searches: [{ collection, ...params }],
+    }));
+    const [result] = results;
+    if (result === undefined) {
+        throw new Error(`Typesense search of “${collection}” returned no result entry.`);
+    }
+    if ('error' in result) {
+        throw new Error(`Typesense search of “${collection}” failed${result.code !== undefined ? ` (${result.code})` : ''}: ${result.error}`);
+    }
+    return result;
+}
 /**
  * Resolve labels from each group’s label-source collection. Labels are
  * reconstructed from the source type’s `label` declaration ({@link

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.15.6",
+  "version": "0.16.0",
   "description": "Typesense implementation of the @lde/search SearchEngine port: collection-schema builder, query compiler, label-resolving result reconstruction, and blue/green index lifecycle. Engine-specific (Typesense) but domain-agnostic.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -25,7 +25,7 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/search": "^0.12.3",
+    "@lde/search": "^0.13.0",
     "@lde/text-normalization": "^0.1.2",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"