@lde/search-typesense 0.2.0 → 0.3.0

package/README.md

@@ -28,6 +28,12 @@ search/sort keys) matches what the projection writes, via
 - reconstructs the logical `SearchResult` (`parseSearchResponse`) — language
   maps, labelled references, labelled facet buckets.
 
+`searchFacets` – the port’s batch entry point – answers a whole batch of
+facet-only queries (e.g. a faceted sidebar’s skip-own-filter variants) as a
+**single `multi_search` round-trip**, with one bundled label lookup shared by
+every facet result in the batch. A failed entry is reported in place as a
+per-query outcome, so its siblings’ facets survive.
+
 The pure halves `buildSearchParams` and `parseSearchResponse` are exported for
 direct use and testing.
 

package/dist/search.d.ts

@@ -35,8 +35,12 @@ export interface TypesenseSearchEngineOptions<TypeName extends string = string>
  * ({@link buildSearchParams}), runs it against the type’s collection,
  * resolves the reference labels for the page of hits from the sidecar
  * `labels` collection in one lookup, and reconstructs the engine-neutral
- * {@link SearchResult} ({@link parseSearchResponse}). Every engine specific
- * stays here; consumers see only logical documents.
+ * {@link SearchResult} ({@link parseSearchResponse}). `searchFacets` answers
+ * a whole facet batch (e.g. a sidebar’s skip-own-filter query variants) as a
+ * single `multi_search` round-trip with one shared label lookup; a failed
+ * entry is reported in place as a per-query outcome, so it never discards
+ * its siblings’ facets. Every engine specific stays here; consumers see only
+ * logical documents.
  *
  * With a schema built by `searchSchema` over `defineSearchType` literals,
  * `search()` accepts only the deployment’s own types and returns typo-safe

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAEL,KAAK,cAAc,EAMnB,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAE7B;;;;kCAIkC;AAClC,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,MAAM,GAAG,MAAM,CAChC,SAAQ,wBAAwB;IAChC;qEACiE;IACjE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;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;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,CAAC,KAAK,SAAS,SAAS,UAAU,EAAE,EAEzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,EAC3B,OAAO,EAAE,4BAA4B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAC3D,YAAY,CAAC,KAAK,CAAC,CAkGrB;AA+DD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAyBtC;AAsBD,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,CAiCd"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAGL,KAAK,cAAc,EAMnB,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAE7B;;;;kCAIkC;AAClC,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,MAAM,GAAG,MAAM,CAChC,SAAQ,wBAAwB;IAChC;qEACiE;IACjE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;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;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,CAAC,KAAK,SAAS,SAAS,UAAU,EAAE,EAEzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,EAC3B,OAAO,EAAE,4BAA4B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAC3D,YAAY,CAAC,KAAK,CAAC,CAwKrB;AA+DD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAmCtC;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,CAiCd"}

package/dist/search.js

@@ -8,8 +8,12 @@ import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
  * ({@link buildSearchParams}), runs it against the type’s collection,
  * resolves the reference labels for the page of hits from the sidecar
  * `labels` collection in one lookup, and reconstructs the engine-neutral
- * {@link SearchResult} ({@link parseSearchResponse}). Every engine specific
- * stays here; consumers see only logical documents.
+ * {@link SearchResult} ({@link parseSearchResponse}). `searchFacets` answers
+ * a whole facet batch (e.g. a sidebar’s skip-own-filter query variants) as a
+ * single `multi_search` round-trip with one shared label lookup; a failed
+ * entry is reported in place as a per-query outcome, so it never discards
+ * its siblings’ facets. Every engine specific stays here; consumers see only
+ * logical documents.
  *
  * With a schema built by `searchSchema` over `defineSearchType` literals,
  * `search()` accepts only the deployment’s own types and returns typo-safe
@@ -54,6 +58,37 @@ export function createTypesenseSearchEngine(client, schema, options) {
         });
         return inFlightLoad;
     }
+    // Cached path: the once-loaded full collection serves labels by in-memory
+    // lookup (no per-search round-trip). The load does not depend on the
+    // response, so it is started BEFORE awaiting the search and runs alongside
+    // it; it never rejects (a failed load degrades to an empty map), so it
+    // cannot leave an unhandled rejection behind if the search itself fails.
+    // `undefined` when the cache (or the sidecar) is not configured.
+    function startCachedLabels() {
+        return options.labelsCollection !== undefined &&
+            options.labelCacheTtlMs !== undefined
+            ? cachedAllLabels(options.labelsCollection, options.labelCacheTtlMs)
+            : undefined;
+    }
+    // Labels are supplementary: a failed lookup (e.g. the sidecar collection
+    // mid-rebuild) degrades to id-only references rather than failing the whole
+    // search, so the listing still renders with bare IRIs. `iris` is a thunk so
+    // the cached and no-sidecar paths never pay for collecting them.
+    async function resolveLabels(cachedLabelsPromise, iris) {
+        if (cachedLabelsPromise !== undefined) {
+            return cachedLabelsPromise;
+        }
+        if (options.labelsCollection === undefined) {
+            return new Map();
+        }
+        try {
+            return await fetchLabels(client, options.labelsCollection, iris());
+        }
+        catch (error) {
+            options.onLabelError?.(error);
+            return new Map();
+        }
+    }
     const engine = {
         schema,
         async search(searchType, query) {
@@ -63,35 +98,48 @@ export function createTypesenseSearchEngine(client, schema, options) {
             assertTypeInSchema(schema, searchType);
             assertValidQuery(query, searchType);
             const params = buildSearchParams(query, searchType, options);
-            // Cached path: the once-loaded full collection serves labels by in-memory
-            // lookup (no per-search round-trip). The load does not depend on the
-            // response, so it runs alongside the search; it never rejects (a failed
-            // load degrades to an empty map), so it cannot leave an unhandled
-            // rejection behind if the search itself fails.
-            const cachedLabelsPromise = options.labelsCollection !== undefined &&
-                options.labelCacheTtlMs !== undefined
-                ? cachedAllLabels(options.labelsCollection, options.labelCacheTtlMs)
-                : undefined;
+            const cachedLabelsPromise = startCachedLabels();
             const response = (await client
                 .collections(collections.get(searchType.type))
                 .documents()
                 .search(params));
-            // Labels are supplementary: a failed lookup (e.g. the sidecar collection
-            // mid-rebuild) degrades to id-only references rather than failing the whole
-            // search, so the listing still renders with bare IRIs.
-            let labels = new Map();
-            if (cachedLabelsPromise !== undefined) {
-                labels = await cachedLabelsPromise;
+            const labels = await resolveLabels(cachedLabelsPromise, () => referenceIris(response, searchType));
+            return parseSearchResponse(response, searchType, labels);
+        },
+        async searchFacets(searchType, queries) {
+            assertTypeInSchema(schema, searchType);
+            for (const query of queries) {
+                assertValidQuery(query, searchType);
             }
-            else if (options.labelsCollection !== undefined) {
-                try {
-                    labels = await fetchLabels(client, options.labelsCollection, referenceIris(response, searchType));
-                }
-                catch (error) {
-                    options.onLabelError?.(error);
-                }
+            if (queries.length === 0) {
+                return [];
             }
-            return parseSearchResponse(response, searchType, labels);
+            const collection = collections.get(searchType.type);
+            const cachedLabelsPromise = startCachedLabels();
+            // 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) => ({
+                    collection,
+                    ...buildSearchParams({ ...query, orderBy: [], limit: 0, offset: 0 }, searchType, options),
+                })),
+            }));
+            // One label lookup serves every successful facet result in the batch.
+            const responses = results.filter((result) => !('error' in result));
+            const labels = await resolveLabels(cachedLabelsPromise, () => [
+                ...new Set(responses.flatMap((response) => referenceIris(response, searchType))),
+            ]);
+            // 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 });
         },
     };
     // The runtime object is string-keyed; the literal-schema typing narrows it.
@@ -180,6 +228,12 @@ export async function fetchLabels(client, collection, iris) {
     }
     const { results } = (await client.multiSearch.perform({ searches }));
     for (const result of results) {
+        // multi_search reports a failed entry inline instead of rejecting; throw
+        // so the caller's degradation path (onLabelError, id-only references)
+        // engages rather than mistaking the failure for absent labels.
+        if ('error' in result) {
+            throw new Error(`Typesense label lookup failed${result.code !== undefined ? ` (${result.code})` : ''}: ${result.error}`);
+        }
         for (const hit of result.hits ?? []) {
             labels.set(String(hit.document.id), labelToLocalizedValue(hit.document));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.2.0",
+  "version": "0.3.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.2.0",
+    "@lde/search": "^0.3.0",
     "@lde/text-normalization": "^0.1.1",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"