@lde/search-typesense 0.15.5 → 0.16.0

package/README.md

@@ -3,150 +3,14 @@
 [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 definition 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 as transactional `@lde/pipeline`
-writers (Blue/green Rebuild and In-place Rebuild).
+domain.
 
-## Collection naming
+## Installation
 
-You pass `SearchType`s; this package names the collections. `deriveCollectionName`
-turns a type’s logical `name` into a Typesense collection name by Typesense’s own
-convention – snake_case, named after the plural of what the collection holds, as
-its [collection guide](https://typesense.org/docs/guide/organizing-collections.html)
-writes them (`people`, `companies`, `blog_articles`):
-
-| `SearchType.name` | collection       |
-| ----------------- | ---------------- |
-| `Dataset`         | `datasets`       |
-| `CreativeWork`    | `creative_works` |
-| `Person`          | `people`         |
-| `TVSeries`        | `tv_series`      |
-| `DCATDataset`     | `dcat_datasets`  |
-
-The writers and the engine all fall back to this one convention, so documents
-cannot be written to `creative_works` and queried from `creativeWorks` – and a
-reference’s `labelSource` resolves to its label type’s collection the same way.
-Every naming input is therefore optional: `buildCollectionDefinition(type)`,
-`new BlueGreenRebuild(client, type)`, `createTypesenseSearchEngine(client, schema)`.
-
-Naming lives here rather than in `@lde/search` because it is engine-specific:
-Elasticsearch/OpenSearch index names are kebab-case and
-[constrained](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html)
-(lowercase only, no `\ / * ? " < > | space , #`, no leading `-` `_` `+`, ≤ 255
-bytes), so a future `@lde/search-elasticsearch` formats the same neutral tokens
-(`@lde/search`’s `physicalNameTokens`) its own way. The core stays engine-neutral.
-
-Pass an explicit name to **override** the convention – an env prefix, a
-multi-tenant name, a collection that already exists, a migration:
-
-```ts
-const writer = new BlueGreenRebuild(client, CREATIVE_WORK, {
-  name: 'staging_creative_works',
-});
-const engine = createTypesenseSearchEngine(client, schema, {
-  collections: { CreativeWork: 'staging_creative_works' },
-});
-writer.collectionName; // 'staging_creative_works' – read-only, for logs/health checks
-engine.collectionNameFor(CREATIVE_WORK); // the same name, resolved once at construction
+```sh
+npm install @lde/search-typesense
 ```
 
-`collections` overrides only the types it names; the rest stay derived.
-
-Everything the convention cannot do, it refuses to guess at, when the writer or
-engine is constructed rather than on the first rebuild or search:
-
-- a name it cannot spell (`Café` would quietly become `cafs`) or turn into a
-  legal collection name;
-- two types whose names **derive to the same collection** – English collapses
-  `Medium` and `Media` onto `media`, `Person` and `People` onto `people` – which
-  would land both types’ documents in one collection, each search returning the
-  other’s. Name either one explicitly to resolve it. Types that share a
-  collection _deliberately_ (say, several label sources in one `labels`
-  collection) are fine: name both, and it is your call, not an accident.
-
-## Collection schema and engine
-
-`buildCollectionDefinition(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, plus one regex display field per output text field) matches
-what the projection writes, via `@lde/search`’s `physicalFields` and its display
-helpers, so the index and the documents cannot drift.
-
-**Memory lever.** Typesense keeps the index in RAM (with a raw copy of each
-document on disk), so RAM tracks the _indexed_ surface – roughly 2–3× the size
-of the fields you search, facet or sort on – not the full document.
-`buildCollectionDefinition` keeps that surface minimal: the `output` display
-labels land in one `index: false` regex field (`${name}_<lang>`, one value per
-present language), stored on disk and fetched only for a hit, so they cost no RAM
-and preserve every language; only the folded `*_search_${locale}`,
-facet/reference and `*_sort_${locale}` companions are indexed. Keeping
-retrieval-only fields un-indexed is the lever for holding a large index’s RAM
-down.
-
-`createTypesenseSearchEngine(client, schema, { collections? })` 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 **per reference field**
-  from the collection of the `SearchType` its `labelSource` names – all
-  sources bundled into a single lookup. A reference without a `labelSource`
-  stays id-only. With `labelCacheTtlMs` set, each label-source collection is
-  instead loaded once into an in-memory cache;
-- reconstructs the logical `SearchResult` (`parseSearchResponse`) – language
-  maps, labelled references, labelled facet buckets.
-
-A label source is just another `SearchType` in the schema (with an `output`,
-`searchable` text field called `label`), so its collection is named by the same
-convention as any other type’s – a typed entity collection and a ‘labels
-collection’ are the same kind of thing.
-
-`searchFacets` – the port’s batch entry point – answers a whole batch of
-facet-only queries (e.g. a faceted listing’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
-
-Indexing runs through two transactional writers, one per update mode – the
-[NDE Stack](https://docs.nde.nl/stack/patterns) patterns of the same names:
-
-- [**Blue/green Rebuild**](#bluegreen-rebuild): build a fresh index, then swap to
-  it atomically;
-- [**In-place Rebuild**](#in-place-rebuild): update the live index directly by
-  upserting changed sources and sweeping the rest.
-
-Both implement `@lde/pipeline`’s `Writer` – each run is
-`openRun(context)` → `write` per dataset → `commit()` or `abort(error)` – so
-an `@lde/pipeline` `Pipeline` drives them without branching on the mode. Both
-derive the collection definition from your `SearchType` (via
-`buildCollectionDefinition`), and their options accept everything
-`buildCollectionDefinition` does (`defaultLocale`, `defaultSortingField`,
-`synonymSets`) plus the tuning knobs (`batchSize`, `lockTtlMs`).
-
-### Blue/green Rebuild
-
-`BlueGreenRebuild` rebuilds the index from zero and goes live atomically:
-`openRun` creates a fresh versioned collection (`${name}_<timestamp>`),
-`write` streams documents into it in batches (each stamped with its `source`
-dataset IRI), and `commit` atomically repoints the `name` alias and drops the
-collection it superseded. Until commit, the live alias never points at a
-partial build; `abort` drops the half-built collection. Deletion is implicit –
-whatever a run does not write does not exist in the new collection. A dataset
-that fails (or is reset before a dump re-run) is rolled back out of the
-not-yet-live collection by `source`, so the swap never ships a half-processed
-dataset. Right-sized for small collections (e.g. one document per dataset
-description).
-
 ```ts
 import { Client } from 'typesense';
 import { BlueGreenRebuild } from '@lde/search-typesense';
@@ -164,55 +28,6 @@ await run.write(dataset, documents);
 await run.commit();
 ```
 
-### In-place Rebuild
-
-`InPlaceRebuild` maintains one long-lived collection with per-source
-atomicity – no swap, no staging – for large, mostly-static corpora (e.g.
-millions of objects across many datasets, where a daily run touches only the
-changed ones). Every document is stamped with its `source` (the dataset IRI)
-and `last_seen` (the run id); deletion is a sweep, never special-cased:
-
-- a successful dataset flush deletes the source’s documents the run did not
-  rewrite (`source = dataset && last_seen != runId`); a failed dataset is not
-  swept – its output is incomplete – and the next successful run reconciles;
-- `commit` deletes every document whose source left the run’s selection (the
-  registry-membership sweep over `RunContext.selectedSources()`, which
-  includes datasets skipped as unchanged);
-- `abort` only releases the lock: upserts are idempotent, so whatever landed
-  stays until the next run reconciles.
-
-Document ids must be unique per (source, entity) – the caller keys them.
-
-Both writers take 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.
-
-## Concurrency
-
-Rebuilds are **single-flight per index**: `openRun` takes a lock (a marker
-document in a `rebuild_locks` collection, created on demand) via Typesense’s
-atomic create, so concurrent runs across pods never rebuild the same index at
-once – a run opened while another holds the lock throws
-`RebuildAlreadyRunning` (catch it to treat a concurrent rebuild as a graceful
-skip). This keeps blue/green safe under replication: without it, two
-same-millisecond rebuilds would collide on the versioned collection name and
-one would delete the other’s in-flight build.
-
-Limitations to design around:
+## Documentation
 
-- **Advisory, not a strict mutex.** The lock is built on Typesense, not a
-  consensus store. Under a TTL-reclaim race two rebuilds can briefly run at
-  once; this is safe because blue/green is idempotent (worst case: redundant
-  work and a transient orphaned collection) and in-place upserts are
-  idempotent.
-- **Single-flight, not coalescing.** A run refused with `RebuildAlreadyRunning`
-  is _not_ queued. If you must capture state that changed mid-build,
-  re-trigger after the running rebuild finishes.
-- **Lock TTL.** A rebuild running longer than `lockTtlMs` (default 10 minutes)
-  can be reclaimed by another caller and run concurrently; size the TTL above
-  your longest rebuild.
-- **Membership-sweep cap.** The in-place membership sweep enumerates distinct
-  sources via a single facet, capped at `maxSweepableSources` (default
-  10 000); beyond that the commit throws rather than sweeping blind. Raise the
-  option (up to the engine’s `max_facet_values` limit) before an index nears
-  the cap so it stays a tunable guard rather than a hard wall.
+See the [full documentation](https://ldelements.org/reference/search-typesense).

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":"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"}

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.5",
+  "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.2",
+    "@lde/search": "^0.13.0",
     "@lde/text-normalization": "^0.1.2",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"