@lde/search-typesense 0.1.1 → 0.3.0

package/README.md

@@ -1,22 +1,51 @@
 # @lde/search-typesense
 
-[Typesense](https://typesense.org/) engine adapter for RDF-backed search
-pipelines. Engine-specific (Typesense) but domain-agnostic – the caller supplies
-the collection schema and documents.
+[Typesense](https://typesense.org/) engine adapter for the engine- and
+domain-agnostic [`@lde/search`](../search) core. **Engine-specific (Typesense) but
+domain-agnostic** – you supply a `SearchType`; this package never names your
+domain. It is the Typesense implementation of the `SearchEngine` port: it derives
+a collection schema from the field model, compiles the neutral `SearchQuery` into
+Typesense search params, runs it, reconstructs the engine-neutral `SearchResult`,
+and manages the search index lifecycle (blue/green rebuild).
 
-The engine-agnostic half of the pipeline – framing `CONSTRUCT` quads into a
-JSON-LD IR and projecting that IR into flat documents from a declarative field
-spec – lives in [`@lde/search`](../search). This package consumes those
-documents and writes them to Typesense.
+## Collection schema and engine
+
+`buildCollectionSchema(searchType, { name, defaultSortingField, … })` derives a
+Typesense collection from the unified `SearchField` model — the Typesense field
+type comes from each field’s `kind`, and the physical fanout (per-locale
+search/sort keys) matches what the projection writes, via
+`@lde/search`’s `physicalFields`, so the index and the documents cannot drift.
+
+`createTypesenseSearchEngine(client, { collection, labelsCollection })` is the
+`SearchEngine` implementation. Each search:
+
+- validates the query against the search type (the port contract — a
+  structurally invalid query is rejected, never sent);
+- compiles it into Typesense search params (`buildSearchParams`);
+- runs the search;
+- resolves reference (and reference-facet) labels from the sidecar `labels`
+  collection in a single lookup;
+- 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.
 
 ## Indexing
 
-`rebuild` blue/green-rebuilds a search index in one call: it creates a fresh
-versioned collection (`${schema.name}_<timestamp>`), streams the documents into
-it in batches, atomically repoints the `schema.name` alias to it, then drops the
-collection it superseded. The caller passes only the logical index name (as
-`schema.name`) and a stream of documents; the versioned collection and the alias
-are managed for them.
+`rebuild` blue/green-rebuilds a search index in one call, straight from the
+declaration: it derives the collection schema from your `SearchType` (via
+`buildCollectionSchema`), creates a fresh versioned collection
+(`${name}_<timestamp>`), streams the documents into it in batches, atomically
+repoints the `name` alias to it, then drops the collection it superseded. The
+caller passes the `SearchType`, the logical index `name` and a stream of
+documents; the versioned collection and the alias are managed for them.
 
 ```ts
 import { Client } from 'typesense';
@@ -30,9 +59,13 @@ const client = new Client({
 // `documents` is an async iterable (e.g. a streaming projection); only one
 // batch is held in memory at a time. `rebuild` returns the live collection name
 // and the imported count (or `null` if another rebuild was already running).
-const result = await rebuild(client, schema, documents);
+const result = await rebuild(client, documents, DATASET, { name: 'datasets' });
 ```
 
+The options accept everything `buildCollectionSchema` does (`defaultLocale`,
+`defaultSortingField`, `synonymSets`) plus the rebuild knobs (`batchSize`,
+`lockTtlMs`).
+
 `rebuild` takes a `Client` the caller owns (and reuses for queries), so this
 package adds no connection or document type of its own – any object with an `id`
 is a valid document, including the `SearchDocument`s `@lde/search` produces.

package/dist/adapter.d.ts

@@ -1,8 +1,21 @@
-import type { Client, CollectionCreateSchema } from 'typesense';
+import type { Client } from 'typesense';
+import type { SearchType } from '@lde/search';
+import { type CollectionSchemaOptions } from './collection-schema.js';
+/** {@link rebuild} options: the collection-schema options (`name` is the
+ *  logical index name the alias is kept on) plus the rebuild tuning knobs. */
+export interface RebuildOptions extends CollectionSchemaOptions {
+    /** Documents imported per Typesense request (default 1000). */
+    readonly batchSize?: number;
+    /** A held lock older than this (ms) is reclaimed (default 10 minutes). */
+    readonly lockTtlMs?: number;
+}
 /**
- * Blue/green-rebuild the search index `name`.
+ * Blue/green-rebuild the search index `options.name` from one declarative
+ * source: the collection schema is derived from `searchType`
+ * ({@link buildCollectionSchema}) and the documents are streamed in — one call
+ * from declaration to live index.
  *
- * 1. create a fresh versioned collection (`${name}_<timestamp>`) from `schema`
+ * 1. create a fresh versioned collection (`${name}_<timestamp>`)
  * 2. stream `documents` into it in batches
  * 3. atomically repoint the `name` alias to the new collection, then
  *    drop the collection it superseded. The caller passes only the logical
@@ -36,12 +49,7 @@ import type { Client, CollectionCreateSchema } from 'typesense';
  */
 export declare function rebuild<Document extends {
     id: string;
-}>(client: Client, schema: CollectionCreateSchema, documents: AsyncIterable<Document>, options?: {
-    /** Documents imported per Typesense request (default 1000). */
-    batchSize?: number;
-    /** A held lock older than this (ms) is reclaimed (default 10 minutes). */
-    lockTtlMs?: number;
-}): Promise<{
+}>(client: Client, documents: AsyncIterable<Document>, searchType: SearchType, options: RebuildOptions): Promise<{
     collection: string;
     imported: number;
 } | null>;

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAkB,MAAM,WAAW,CAAC;AAKhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,OAAO,CAAC,QAAQ,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAC3D,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,sBAAsB,EAC9B,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,EAClC,OAAO,GAAE;IACP,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAmC1D"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,WAAW,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,wBAAwB,CAAC;AAKhC;8EAC8E;AAC9E,MAAM,WAAW,cAAe,SAAQ,uBAAuB;IAC7D,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,OAAO,CAAC,QAAQ,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAC3D,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC,EAClC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAwC1D"}

package/dist/adapter.js

@@ -1,9 +1,13 @@
+import { buildCollectionSchema, } from './collection-schema.js';
 const LOCK_COLLECTION = 'rebuild_locks';
 const DEFAULT_LOCK_TTL_MS = 10 * 60 * 1000;
 /**
- * Blue/green-rebuild the search index `name`.
+ * Blue/green-rebuild the search index `options.name` from one declarative
+ * source: the collection schema is derived from `searchType`
+ * ({@link buildCollectionSchema}) and the documents are streamed in — one call
+ * from declaration to live index.
  *
- * 1. create a fresh versioned collection (`${name}_<timestamp>`) from `schema`
+ * 1. create a fresh versioned collection (`${name}_<timestamp>`)
  * 2. stream `documents` into it in batches
  * 3. atomically repoint the `name` alias to the new collection, then
  *    drop the collection it superseded. The caller passes only the logical
@@ -35,9 +39,10 @@ const DEFAULT_LOCK_TTL_MS = 10 * 60 * 1000;
  *   minutes) can be reclaimed by another caller and run concurrently; size the
  *   TTL above your longest rebuild.
  */
-export async function rebuild(client, schema, documents, options = {}) {
-    const { batchSize = 1000, lockTtlMs = DEFAULT_LOCK_TTL_MS } = options;
-    const name = schema.name;
+export async function rebuild(client, documents, searchType, options) {
+    const { batchSize = 1000, lockTtlMs = DEFAULT_LOCK_TTL_MS, ...schemaOptions } = options;
+    const schema = buildCollectionSchema(searchType, schemaOptions);
+    const name = schemaOptions.name;
     if (!(await acquireLock(client, name, lockTtlMs))) {
         return null;
     }

package/dist/collection-schema.d.ts

@@ -0,0 +1,30 @@
+import type { CollectionCreateSchema } from 'typesense';
+import { type SearchType } from '@lde/search';
+/** Deployment-specific options the generic field model does not carry. */
+export interface CollectionSchemaOptions {
+    /** The Typesense collection (or alias) name. */
+    readonly name: string;
+    /** Snowball stemming locale for non-localized searchable fields (e.g. `en`).
+     *  Unset, those fields are not stemmed — folding still applies — so no
+     *  language is ever assumed. Localized text search fields always stem in
+     *  their own locale. */
+    readonly defaultLocale?: string;
+    /** The field Typesense sorts by when a query imposes no order. */
+    readonly defaultSortingField?: string;
+    /** Synonym sets the collection references (synced separately). */
+    readonly synonymSets?: readonly string[];
+}
+/**
+ * Build a Typesense collection schema from the unified {@link SearchType}, so
+ * the index and the projection are driven by one declarative source and cannot
+ * drift. Each field fans out into the same physical fields the projection writes
+ * ({@link physicalFields}); the Typesense field type is derived from the field
+ * `kind`, never re-declared.
+ *
+ * Text stems each folded `*_search_${locale}` field in its own language; the
+ * untagged `und` locale (and any searchable keyword/reference companion)
+ * stems in `defaultLocale` when one is set, and is left unstemmed (folded
+ * only) otherwise.
+ */
+export declare function buildCollectionSchema(searchType: SearchType, options: CollectionSchemaOptions): CollectionCreateSchema;
+//# sourceMappingURL=collection-schema.d.ts.map

package/dist/collection-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-schema.d.ts","sourceRoot":"","sources":["../src/collection-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAGhE,0EAA0E;AAC1E,MAAM,WAAW,uBAAuB;IACtC,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;4BAGwB;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,uBAAuB,GAC/B,sBAAsB,CAexB"}

package/dist/collection-schema.js

@@ -0,0 +1,105 @@
+import { physicalFields } from '@lde/search/adapter';
+/**
+ * Build a Typesense collection schema from the unified {@link SearchType}, so
+ * the index and the projection are driven by one declarative source and cannot
+ * drift. Each field fans out into the same physical fields the projection writes
+ * ({@link physicalFields}); the Typesense field type is derived from the field
+ * `kind`, never re-declared.
+ *
+ * Text stems each folded `*_search_${locale}` field in its own language; the
+ * untagged `und` locale (and any searchable keyword/reference companion)
+ * stems in `defaultLocale` when one is set, and is left unstemmed (folded
+ * only) otherwise.
+ */
+export function buildCollectionSchema(searchType, options) {
+    const { defaultLocale } = options;
+    const collection = {
+        name: options.name,
+        fields: searchType.fields.flatMap((field) => typesenseFields(field, defaultLocale, options.defaultSortingField)),
+    };
+    if (options.defaultSortingField !== undefined) {
+        collection.default_sorting_field = options.defaultSortingField;
+    }
+    if (options.synonymSets !== undefined) {
+        collection.synonym_sets = [...options.synonymSets];
+    }
+    return collection;
+}
+/** The physical Typesense fields one declaration produces. */
+function typesenseFields(field, defaultLocale, defaultSortingField) {
+    const names = physicalFields(field);
+    if (field.kind === 'text') {
+        const locales = field.locales;
+        return [
+            // Display labels: stored, not indexed for search (search uses the folded
+            // companions), accents preserved.
+            ...names.display.map((name) => ({
+                name,
+                type: 'string',
+                index: false,
+                optional: true,
+            })),
+            // One folded search field per locale, each stemmed in its own
+            // language; the untagged `und` locale is folded but unstemmed unless
+            // the deployment opts in via `defaultLocale`.
+            ...names.search.map((name, index) => {
+                const locale = locales[index] === 'und' ? defaultLocale : locales[index];
+                return {
+                    name,
+                    type: 'string',
+                    optional: true,
+                    ...(locale !== undefined && { stem: true, locale }),
+                };
+            }),
+            ...names.sort.map((name) => ({
+                name,
+                type: 'string',
+                sort: true,
+                optional: true,
+            })),
+        ];
+    }
+    const valueType = typesenseValueType(field);
+    const fields = [
+        {
+            name: field.name,
+            type: valueType,
+            facet: field.facetable ?? false,
+            sort: field.sortable ?? false,
+            // A `required` field is non-optional; so is the `default_sorting_field`,
+            // which Typesense requires to be present. Everything else may be absent.
+            optional: field.required !== true && field.name !== defaultSortingField,
+        },
+    ];
+    // `names.search` is non-empty exactly when the field projects a folded
+    // search companion — physicalFields owns that rule.
+    for (const name of names.search) {
+        fields.push({
+            name,
+            type: valueType,
+            optional: true,
+            ...(defaultLocale !== undefined && {
+                stem: true,
+                locale: defaultLocale,
+            }),
+        });
+    }
+    return fields;
+}
+/** The Typesense field type for a non-localized field, from its `kind`. 64-bit
+ *  integers (and dates, stored as Unix seconds) so large counts never overflow. */
+function typesenseValueType(field) {
+    switch (field.kind) {
+        case 'integer':
+        case 'date':
+            return 'int64';
+        case 'number':
+            return 'float';
+        case 'boolean':
+            return 'bool';
+        case 'keyword':
+        case 'reference':
+        case 'text':
+            return field.array === true ? 'string[]' : 'string';
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,9 @@
 export { rebuild } from './adapter.js';
+export type { RebuildOptions } from './adapter.js';
+export { buildCollectionSchema } from './collection-schema.js';
+export type { CollectionSchemaOptions } from './collection-schema.js';
+export { buildSearchParams } from './query-compiler.js';
+export type { BuildSearchParamsOptions } from './query-compiler.js';
+export { createTypesenseSearchEngine, parseSearchResponse } from './search.js';
+export type { TypesenseSearchEngineOptions, TypesenseSearchResponse, } from './search.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC/E,YAAY,EACV,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1 +1,4 @@
 export { rebuild } from './adapter.js';
+export { buildCollectionSchema } from './collection-schema.js';
+export { buildSearchParams } from './query-compiler.js';
+export { createTypesenseSearchEngine, parseSearchResponse } from './search.js';

package/dist/query-compiler.d.ts

@@ -0,0 +1,42 @@
+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
+ * 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
+     * (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.
+     */
+    readonly maxFacetValues?: number;
+    /**
+     * Called for each `where` clause that compiles to nothing and is therefore
+     * skipped: an unknown field, an operator that does not match the field’s
+     * kind ({@link filterOperatorFor}), an empty `in` list, or a `range` with no
+     * usable bound. Skipping keeps a malformed clause from reaching the engine
+     * as garbage; supply this to log it instead of losing it silently. Through
+     * the engine, a structurally invalid query throws up front
+     * (`assertValidQuery`), so there only the vacuous clauses reach this.
+     */
+    readonly onIgnoredFilter?: (filter: Filter) => void;
+}
+/**
+ * Compile the engine-neutral {@link SearchQuery} into Typesense search
+ * 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.
+ */
+export declare function buildSearchParams(query: SearchQuery, searchType: SearchType, options?: BuildSearchParamsOptions): SearchParams<object>;
+/**
+ * Backtick-wrap a filter value so reserved characters in IRIs and media types
+ * (`:`, `/`, `&`, `,`, …) are taken literally instead of parsed as filter syntax.
+ * An embedded backtick is escaped.
+ */
+export declare function escapeFilterValue(value: string): string;
+//# sourceMappingURL=query-compiler.d.ts.map

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

@@ -0,0 +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"}

package/dist/query-compiler.js

@@ -0,0 +1,193 @@
+import { fold } from '@lde/text-normalization';
+import { fieldNamed, filterOperator, filterOperatorFor, 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),
+ * 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.
+ */
+export function buildSearchParams(query, searchType, options = {}) {
+    const folded = query.text !== undefined && query.text.length > 0
+        ? fold(query.text)
+        : undefined;
+    const { names, weights } = queryFields(searchType, query.locale);
+    const filterBy = compileFilterBy(query.where, searchType, options.onIgnoredFilter);
+    const sortBy = query.orderBy
+        .map((sort) => compileSort(sort, searchType, query.locale))
+        .join(',');
+    const params = {
+        q: folded ?? '*',
+        query_by: names.join(','),
+        query_by_weights: weights.join(','),
+        per_page: query.limit,
+        page: pageForOffset(query.offset, query.limit),
+    };
+    if (filterBy.length > 0) {
+        params.filter_by = filterBy;
+    }
+    if (sortBy.length > 0) {
+        params.sort_by = sortBy;
+    }
+    if (query.facets.length > 0) {
+        params.facet_by = compileFacetBy(query.facets, searchType);
+        if (options.maxFacetValues !== undefined) {
+            params.max_facet_values = options.maxFacetValues;
+        }
+    }
+    return params;
+}
+/**
+ * The `facet_by` clause. A facet on a numeric field that declares
+ * {@link SearchField.facetRanges} faceted into those fixed half-open `[min, max)`
+ * bins (a histogram); every other facet is a plain per-value facet on its field
+ * name. Typesense range syntax is already start-inclusive/end-exclusive, so the
+ * declared bounds pass straight through with no boundary fix-up.
+ */
+function compileFacetBy(facets, searchType) {
+    return facets
+        .map((name) => {
+        const field = fieldNamed(searchType, name);
+        return field !== undefined && isRangeFacet(field)
+            ? compileRangeFacet(field.name, field.facetRanges)
+            : name;
+    })
+        .join(',');
+}
+/** `name(key:[min, max], …)`; a blank bound is open-ended (Typesense `[75, ]`). */
+function compileRangeFacet(name, ranges) {
+    const bins = ranges
+        .map((range) => `${range.key}:[${range.min ?? ''}, ${range.max ?? ''}]`)
+        .join(', ');
+    return `${name}(${bins})`;
+}
+/**
+ * The `query_by` fields and aligned weights. Each searchable field expands to its
+ * folded `*_search` companion(s); a localized field’s active-locale companion
+ * keeps its full weight while the other locale is gently demoted (−1, floored at
+ * 1), so a match in the user’s language ranks higher while cross-language matches
+ * still surface.
+ */
+function queryFields(searchType, locale) {
+    const names = [];
+    const weights = [];
+    for (const field of searchableFields(searchType)) {
+        const search = physicalFields(field).search;
+        const baseWeight = field.searchable.weight;
+        if (field.kind === 'text') {
+            const locales = field.locales;
+            search.forEach((name, index) => {
+                names.push(name);
+                // The active locale keeps full weight; `und` is language-neutral, so
+                // it is never demoted (an untagged-only field would otherwise always
+                // rank below its declared weight).
+                weights.push(locales[index] === locale || locales[index] === 'und'
+                    ? baseWeight
+                    : Math.max(1, baseWeight - 1));
+            });
+        }
+        else {
+            for (const name of search) {
+                names.push(name);
+                weights.push(baseWeight);
+            }
+        }
+    }
+    return { names, weights };
+}
+/** AND-join the compiled `where` clauses; a clause that compiles to nothing is
+ *  skipped and reported to `onIgnoredFilter`. */
+function compileFilterBy(where, searchType, onIgnoredFilter) {
+    return where
+        .map((filter) => {
+        const clause = compileFilter(filter, searchType);
+        if (clause === undefined) {
+            onIgnoredFilter?.(filter);
+        }
+        return clause;
+    })
+        .filter((clause) => clause !== undefined)
+        .join(' && ');
+}
+function compileFilter(filter, searchType) {
+    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.
+    if (filterOperatorFor(field.kind) !== filterOperator(filter)) {
+        return undefined;
+    }
+    if ('in' in filter) {
+        return filter.in.length > 0
+            ? compileMembership(field, filter.in)
+            : undefined;
+    }
+    if ('range' in filter) {
+        return compileRange(field, filter.range);
+    }
+    return `${field.name}:=${filter.is}`;
+}
+/**
+ * A membership clause. A non-facet (tokenized) field uses the exact `:=`
+ * operator so an IRI cannot partial-match on a shared path segment.
+ */
+function compileMembership(field, values) {
+    const list = `[${values.map(escapeFilterValue).join(',')}]`;
+    return field.facetable !== true
+        ? `${field.name}:=${list}`
+        : `${field.name}:${list}`;
+}
+/** An inclusive Typesense range clause, or `undefined` when neither bound is set. */
+function compileRange(field, range) {
+    const name = field.name;
+    const min = storedBound(field, range.min);
+    const max = storedBound(field, range.max);
+    if (min !== undefined && max !== undefined) {
+        return `${name}:[${min}..${max}]`;
+    }
+    if (min !== undefined) {
+        return `${name}:>=${min}`;
+    }
+    if (max !== undefined) {
+        return `${name}:<=${max}`;
+    }
+    return undefined;
+}
+/** A range bound as stored: a `date` field’s ISO 8601 bound becomes the indexed
+ *  Unix seconds ({@link isoToUnixSeconds}); an unparseable bound is dropped. */
+function storedBound(field, bound) {
+    return field.kind === 'date' && typeof bound === 'string'
+        ? isoToUnixSeconds(bound)
+        : bound;
+}
+/**
+ * One `sort_by` term. `relevance` maps to Typesense’s `_text_match`; a localized
+ * text field sorts on its active-locale folded key; any other field (including a
+ * deployment tie-break like `status_rank`) sorts on its own name.
+ */
+function compileSort(sort, searchType, locale) {
+    if (sort.field === 'relevance') {
+        return `_text_match:${sort.direction}`;
+    }
+    const field = fieldNamed(searchType, sort.field);
+    if (field !== undefined && field.kind === 'text') {
+        // Sort on the active locale's key, falling back to the first declared
+        // locale (e.g. an und-only field sorted by a user in any language).
+        const index = field.locales.indexOf(locale);
+        const sortName = physicalFields(field).sort[index === -1 ? 0 : index];
+        if (sortName !== undefined) {
+            return `${sortName}:${sort.direction}`;
+        }
+    }
+    return `${sort.field}:${sort.direction}`;
+}
+/**
+ * Backtick-wrap a filter value so reserved characters in IRIs and media types
+ * (`:`, `/`, `&`, `,`, …) are taken literally instead of parsed as filter syntax.
+ * An embedded backtick is escaped.
+ */
+export function escapeFilterValue(value) {
+    return `\`${value.replace(/`/g, '\\`')}\``;
+}

package/dist/search.d.ts

@@ -0,0 +1,86 @@
+import type { Client } from 'typesense';
+import { type LocalizedValue, type SearchEngine, type SearchResult, type SearchSchema, type SearchType } from '@lde/search';
+import { type BuildSearchParamsOptions } from './query-compiler.js';
+/** Where the engine reads documents and (optionally) reference labels — plus
+ *  every query-compiler knob ({@link BuildSearchParamsOptions}), declared once
+ *  there and forwarded wholesale into each search. `TypeName` is the union of
+ *  the schema’s type names, so a literal schema makes the `collections` map
+ *  exhaustive at compile time. */
+export interface TypesenseSearchEngineOptions<TypeName extends string = string> extends BuildSearchParamsOptions {
+    /** The collection (or alias) per search type, keyed by the type’s `name` —
+     *  with a literal schema, omitting a type is a compile error. */
+    readonly collections: Readonly<Record<TypeName, string>>;
+    /** The sidecar `labels` collection (IRI → label); omit for id-only references. */
+    readonly labelsCollection?: string;
+    /**
+     * Called when reference-label resolution fails; the search then degrades to
+     * id-only references rather than failing. Optional — omit to swallow silently.
+     */
+    readonly onLabelError?: (error: unknown) => void;
+    /**
+     * Opt-in in-memory label cache. When set (and {@link labelsCollection} is
+     * set), the FULL sidecar `labels` collection is loaded once via the documents
+     * export endpoint and held in a process-lifetime cache for this many
+     * milliseconds; each `search` then resolves its reference labels by in-memory
+     * lookup instead of a per-search `multi_search` round-trip. Omit to keep the
+     * per-search {@link fetchLabels} behaviour unchanged.
+     */
+    readonly labelCacheTtlMs?: number;
+}
+/**
+ * A Typesense-backed {@link SearchEngine}, bound to the whole
+ * {@link SearchSchema} at construction — like every other schema consumer.
+ * Each type’s collection comes from `options.collections`; the label sidecar
+ * and its cache are shared across all types. `search` compiles the query
+ * ({@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}). `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
+ * facet/document keys per call — no caller-side generics.
+ */
+export declare function createTypesenseSearchEngine<const Types extends readonly SearchType[]>(client: Client, schema: SearchSchema<Types>, options: TypesenseSearchEngineOptions<Types[number]['name']>): SearchEngine<Types>;
+/**
+ * Resolve labels for `iris` from the sidecar `labels` collection. Each
+ * `label_${locale}` becomes a language-map entry; the default `label` is the
+ * untagged (`und`) fallback when no locale variant exists.
+ *
+ * Sent as one `multi_search` (POST) call, the id-list split over per-search
+ * batches: the id-list of a page or facet carrying many references — e.g. a
+ * dataset with dozens of classes — would overflow Typesense’s GET query-string
+ * limit (4000 chars, and IRIs URL-encode to several times their length) if it
+ * travelled in the URL. POST puts it in the body; each batch stays under
+ * Typesense’s `per_page` cap, and bundling the batches keeps it one round-trip
+ * regardless of IRI count. Exported for unit testing against a fake client.
+ */
+export declare function fetchLabels(client: Pick<Client, 'multiSearch'>, collection: string, iris: readonly string[]): Promise<Map<string, LocalizedValue>>;
+/** The subset of a Typesense search response this adapter reads. */
+export interface TypesenseSearchResponse {
+    readonly found: number;
+    readonly hits?: readonly {
+        readonly document: Record<string, unknown>;
+    }[];
+    readonly facet_counts?: readonly {
+        readonly field_name: string;
+        readonly counts: readonly {
+            readonly value: string;
+            readonly count: number;
+        }[];
+    }[];
+}
+/**
+ * Reconstruct a Typesense response into the engine-neutral {@link SearchResult}:
+ * the flat, fanned-out document is turned back into a logical one (per-locale
+ * display fields → a language map, reference IRIs → labelled references via the
+ * sidecar `labels` lookup, scalars passed through). `labels` maps a reference IRI
+ * to its resolved label; an IRI absent from it yields an id-only reference.
+ */
+export declare function parseSearchResponse(response: TypesenseSearchResponse, searchType: SearchType, labels: ReadonlyMap<string, LocalizedValue>): SearchResult;
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +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,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

@@ -0,0 +1,355 @@
+import { assertTypeInSchema, assertValidQuery, fieldNamed, isRangeFacet, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
+/**
+ * A Typesense-backed {@link SearchEngine}, bound to the whole
+ * {@link SearchSchema} at construction — like every other schema consumer.
+ * Each type’s collection comes from `options.collections`; the label sidecar
+ * and its cache are shared across all types. `search` compiles the query
+ * ({@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}). `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
+ * facet/document keys per call — no caller-side generics.
+ */
+export function createTypesenseSearchEngine(client, schema, options) {
+    // Resolve every type's collection ONCE at construction, so a
+    // misconfiguration fails at startup — never on the first search that
+    // happens to hit the unwired type.
+    const collections = new Map([...schema.values()].map((searchType) => {
+        const collection = options.collections[searchType.name];
+        if (collection === undefined) {
+            throw new Error(`No collection configured for search type “${searchType.name}”; set options.collections.${searchType.name}.`);
+        }
+        return [searchType.type, collection];
+    }));
+    // Process-lifetime cache for the FULL `labels` collection, held in the engine
+    // closure. Populated lazily on the first cached search; `loadAll` is the
+    // single-flight in-flight promise so concurrent first-loads share one export.
+    let cachedLabels;
+    let cacheExpiresAt = 0;
+    let inFlightLoad;
+    function cachedAllLabels(labelsCollection, ttlMs) {
+        if (cachedLabels !== undefined && Date.now() < cacheExpiresAt) {
+            return Promise.resolve(cachedLabels);
+        }
+        // Single-flight: a load already running serves every concurrent caller.
+        inFlightLoad ??= loadAllLabels(client, labelsCollection)
+            .then((loaded) => {
+            cachedLabels = loaded;
+            cacheExpiresAt = Date.now() + ttlMs;
+            return loaded;
+        })
+            // A failed load degrades to id-only references and is NOT cached, so the
+            // next search retries rather than serving an empty map for the whole TTL.
+            .catch((error) => {
+            options.onLabelError?.(error);
+            return new Map();
+        })
+            .finally(() => {
+            inFlightLoad = undefined;
+        });
+        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) {
+            // The port contract: a type outside the bound schema and a structurally
+            // invalid query (unknown field, wrong operator, unknown facet) are both
+            // rejected up front, for EVERY caller.
+            assertTypeInSchema(schema, searchType);
+            assertValidQuery(query, searchType);
+            const params = buildSearchParams(query, searchType, options);
+            const cachedLabelsPromise = startCachedLabels();
+            const response = (await client
+                .collections(collections.get(searchType.type))
+                .documents()
+                .search(params));
+            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);
+            }
+            if (queries.length === 0) {
+                return [];
+            }
+            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.
+    return engine;
+}
+/**
+ * Load the FULL `labels` collection into a label map via the documents export
+ * endpoint, which streams every document as JSONL (one JSON object per line).
+ * Each line is reconstructed by {@link labelToLocalizedValue}, exactly as the
+ * per-search {@link fetchLabels} path does for its `multi_search` hits.
+ */
+async function loadAllLabels(client, collection) {
+    const jsonl = await client.collections(collection).documents().export();
+    const labels = new Map();
+    for (const line of jsonl.split('\n')) {
+        if (line.length === 0) {
+            continue;
+        }
+        const document = JSON.parse(line);
+        labels.set(String(document.id), labelToLocalizedValue(document));
+    }
+    return labels;
+}
+/** Every distinct reference IRI whose label the result will actually use. */
+function referenceIris(response, searchType) {
+    const referenceFieldSet = new Set(referenceFields(searchType).map((field) => field.name));
+    // Hits only carry labels for OUTPUT reference fields: reconstructDocument skips
+    // non-output fields, so resolving a non-output reference's hit labels (e.g. a
+    // facet-only `class` with dozens of IRIs per hit) is pure waste.
+    const outputReferenceFields = referenceFields(searchType)
+        .filter((field) => field.output === true)
+        .map((field) => field.name);
+    const iris = new Set();
+    for (const hit of response.hits ?? []) {
+        for (const name of outputReferenceFields) {
+            const raw = hit.document[name];
+            if (Array.isArray(raw)) {
+                for (const value of raw) {
+                    iris.add(String(value));
+                }
+            }
+            else if (typeof raw === 'string') {
+                iris.add(raw);
+            }
+        }
+    }
+    // Reference-facet bucket values are IRIs too (incl. facet-only references like
+    // `class`); resolve them in the same lookup.
+    for (const facet of response.facet_counts ?? []) {
+        if (referenceFieldSet.has(facet.field_name)) {
+            for (const bucket of facet.counts) {
+                iris.add(bucket.value);
+            }
+        }
+    }
+    return [...iris];
+}
+/**
+ * Resolve labels for `iris` from the sidecar `labels` collection. Each
+ * `label_${locale}` becomes a language-map entry; the default `label` is the
+ * untagged (`und`) fallback when no locale variant exists.
+ *
+ * Sent as one `multi_search` (POST) call, the id-list split over per-search
+ * batches: the id-list of a page or facet carrying many references — e.g. a
+ * dataset with dozens of classes — would overflow Typesense’s GET query-string
+ * limit (4000 chars, and IRIs URL-encode to several times their length) if it
+ * travelled in the URL. POST puts it in the body; each batch stays under
+ * Typesense’s `per_page` cap, and bundling the batches keeps it one round-trip
+ * regardless of IRI count. Exported for unit testing against a fake client.
+ */
+export async function fetchLabels(client, collection, iris) {
+    const labels = new Map();
+    if (iris.length === 0) {
+        return labels;
+    }
+    const searches = [];
+    for (let start = 0; start < iris.length; start += LABEL_BATCH_SIZE) {
+        const batch = iris.slice(start, start + LABEL_BATCH_SIZE);
+        searches.push({
+            collection,
+            q: '*',
+            query_by: 'label',
+            filter_by: `id:[${batch.map(escapeFilterValue).join(',')}]`,
+            per_page: batch.length,
+        });
+    }
+    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));
+        }
+    }
+    return labels;
+}
+/** Typesense caps `per_page` at 250; the multi_search POST body holds the
+ *  id-list comfortably, so resolve references in batches of this size. */
+const LABEL_BATCH_SIZE = 200;
+/** Turn a `labels` document into a language map (`label_${locale}` → locale). */
+function labelToLocalizedValue(document) {
+    const map = {};
+    for (const [key, value] of Object.entries(document)) {
+        if (key.startsWith('label_') && typeof value === 'string') {
+            map[key.slice('label_'.length)] = [value];
+        }
+    }
+    if (Object.keys(map).length === 0 && typeof document.label === 'string') {
+        map.und = [document.label];
+    }
+    return map;
+}
+/**
+ * Reconstruct a Typesense response into the engine-neutral {@link SearchResult}:
+ * the flat, fanned-out document is turned back into a logical one (per-locale
+ * display fields → a language map, reference IRIs → labelled references via the
+ * sidecar `labels` lookup, scalars passed through). `labels` maps a reference IRI
+ * to its resolved label; an IRI absent from it yields an id-only reference.
+ */
+export function parseSearchResponse(response, searchType, labels) {
+    const hits = (response.hits ?? []).map((hit) => ({
+        id: String(hit.document.id),
+        document: reconstructDocument(hit.document, searchType, labels),
+    }));
+    // Reference facets are IRI-keyed; their buckets carry a resolved data label.
+    // Plain facets (tokens, free strings) carry no label — the consumer owns display.
+    const referenceFacets = new Set(referenceFields(searchType).map((field) => field.name));
+    const facets = {};
+    for (const facet of response.facet_counts ?? []) {
+        const labelled = referenceFacets.has(facet.field_name);
+        // A range facet echoes the declared range key as the bucket value; look the
+        // bin's half-open bounds back up by key so the bucket is self-describing.
+        const field = fieldNamed(searchType, facet.field_name);
+        const rangesByKey = field !== undefined && isRangeFacet(field)
+            ? new Map(field.facetRanges.map((range) => [range.key, range]))
+            : undefined;
+        facets[facet.field_name] = facet.counts.map((bucket) => {
+            const label = labelled ? labels.get(bucket.value) : undefined;
+            const range = rangesByKey?.get(bucket.value);
+            return {
+                value: bucket.value,
+                count: bucket.count,
+                ...(label !== undefined ? { label } : {}),
+                ...(range?.min !== undefined ? { min: range.min } : {}),
+                ...(range?.max !== undefined ? { max: range.max } : {}),
+            };
+        });
+    }
+    return { hits, total: response.found, facets };
+}
+/** Rebuild one logical document from a flat Typesense document. */
+function reconstructDocument(flat, searchType, labels) {
+    const document = {};
+    for (const field of outputFields(searchType)) {
+        const value = logicalValue(flat, field, labels);
+        if (value !== undefined) {
+            document[field.name] = value;
+        }
+    }
+    return document;
+}
+function logicalValue(flat, field, labels) {
+    switch (field.kind) {
+        case 'text':
+            return localizedValue(flat, field);
+        case 'reference':
+            return referenceValue(flat, field, labels);
+        case 'keyword': {
+            const value = flat[field.name];
+            return Array.isArray(value) || typeof value === 'string'
+                ? value
+                : undefined;
+        }
+        case 'integer':
+        case 'number':
+        case 'date': {
+            const value = flat[field.name];
+            return typeof value === 'number' ? value : undefined;
+        }
+        case 'boolean':
+            // A boolean is always present; an absent value means false.
+            return flat[field.name] === true;
+    }
+}
+/** Gather the per-locale display fields back into a language map. */
+function localizedValue(flat, field) {
+    const map = {};
+    const display = physicalFields(field).display;
+    field.locales.forEach((locale, index) => {
+        const value = flat[display[index]];
+        if (typeof value === 'string') {
+            map[locale] = [value];
+        }
+    });
+    return Object.keys(map).length > 0 ? map : undefined;
+}
+/** Map stored reference IRIs to labelled references; id-only when no label. */
+function referenceValue(flat, field, labels) {
+    const raw = flat[field.name];
+    if (raw === undefined) {
+        return undefined;
+    }
+    const iris = Array.isArray(raw) ? raw : [String(raw)];
+    const references = iris.map((iri) => {
+        const label = labels.get(iri);
+        return label === undefined ? { id: iri } : { id: iri, label };
+    });
+    return field.array === true ? references : references[0];
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.1.1",
-  "description": "Generic Typesense engine adapter for RDF-backed search pipelines: collection lifecycle, bulk upsert and blue/green alias swap",
+  "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",
     "directory": "packages/search-typesense"
@@ -25,6 +25,8 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
+    "@lde/search": "^0.3.0",
+    "@lde/text-normalization": "^0.1.1",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"
   },