@lde/search-typesense 0.8.0 → 0.9.1

package/README.md

@@ -9,27 +9,87 @@ 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).
 
+## Collection naming
+
+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
+```
+
+`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
+`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) matches what the projection writes, via
-`@lde/search`’s `physicalFields`, so the index and the documents cannot drift.
+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
-fan out to `index: false` fields, stored on disk and fetched only for a hit, so
-they cost no RAM; 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
+`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
+- 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;
@@ -38,13 +98,13 @@ un-indexed is the lever for holding a large index’s RAM down.
   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
+- 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`) whose collection appears in
-`collections` – a typed entity collection and a ‘labels collection’ are the
-same kind of thing.
+`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
@@ -95,7 +155,8 @@ const client = new Client({
   apiKey,
 });
 
-const writer = new BlueGreenRebuild(client, DATASET, { name: 'datasets' });
+// The collection is named from the type: `Dataset` → `datasets`.
+const writer = new BlueGreenRebuild(client, DATASET);
 // Standalone use; under @lde/pipeline the Pipeline drives this lifecycle.
 const run = await writer.openRun(context);
 await run.write(dataset, documents);

package/dist/blue-green-rebuild.d.ts

@@ -3,7 +3,8 @@ import type { SearchType } from '@lde/search';
 import type { RunContext, RunWriter, Writer } from '@lde/pipeline';
 import { type RebuildOptions } from './rebuild-support.js';
 /** {@link BlueGreenRebuild} options: the collection-definition options (`name` is
- *  the logical index name the alias is kept on) plus the rebuild tuning knobs. */
+ *  the logical index name the alias is kept on – omit it to derive one from the
+ *  {@link SearchType}) plus the rebuild tuning knobs. */
 export type BlueGreenRebuildOptions = RebuildOptions;
 /**
  * Blue/green Rebuild (build a fresh index alongside the live one, then swap to
@@ -29,16 +30,27 @@ export type BlueGreenRebuildOptions = RebuildOptions;
  * - `abort` drops the half-built collection and releases the lock; the live
  *   index is untouched.
  *
- * The caller passes only the logical index `name`; the versioned collection
- * name and the alias are managed here.
+ * The caller passes at most the logical index `name` – omitted, it is derived
+ * from the {@link SearchType} ({@link deriveCollectionName}), the same
+ * convention the engine reads by; the versioned collection name and the alias
+ * are managed here.
  */
 export declare class BlueGreenRebuild<TDocument extends {
     id: string;
 }> implements Writer<TDocument> {
     private readonly client;
     private readonly searchType;
-    private readonly options;
-    constructor(client: Client, searchType: SearchType, options: BlueGreenRebuildOptions);
+    /**
+     * The live Typesense alias this writer keeps pointed at its newest build:
+     * the explicit `options.name`, or the name derived from the
+     * {@link SearchType}. Read-only and for observability (logging, health
+     * checks) – never an input, and the same name
+     * {@link createTypesenseSearchEngine} reads the type from. The versioned
+     * collections behind it (`${collectionName}_<timestamp>`) stay internal.
+     */
+    readonly collectionName: string;
+    private readonly resolved;
+    constructor(client: Client, searchType: SearchType, options?: BlueGreenRebuildOptions);
     openRun(context: RunContext): Promise<RunWriter<TDocument>>;
     /** The collection an alias currently points at, or `undefined` if unset. */
     private aliasTarget;

package/dist/blue-green-rebuild.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blue-green-rebuild.d.ts","sourceRoot":"","sources":["../src/blue-green-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AAMvB,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAE9B;kFACkF;AAClF,MAAM,MAAM,uBAAuB,GAAG,cAAc,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,gBAAgB,CAC3B,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,uBAAuB;IAM7C,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IA6FjE,4EAA4E;YAC9D,WAAW;CAW1B"}
+{"version":3,"file":"blue-green-rebuild.d.ts","sourceRoot":"","sources":["../src/blue-green-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AAMvB,OAAO,EAKL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAE9B;;yDAEyD;AACzD,MAAM,MAAM,uBAAuB,GAAG,cAAc,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,gBAAgB,CAC3B,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAa1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAb7B;;;;;;;OAOG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAG/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACvC,OAAO,GAAE,uBAA4B;IAQjC,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IA4FjE,4EAA4E;YAC9D,WAAW;CAW1B"}

package/dist/blue-green-rebuild.js

@@ -27,22 +27,34 @@ import { assertNoReservedFields, deleteByFilter, resolveRebuildOptions, stampDoc
  * - `abort` drops the half-built collection and releases the lock; the live
  *   index is untouched.
  *
- * The caller passes only the logical index `name`; the versioned collection
- * name and the alias are managed here.
+ * The caller passes at most the logical index `name` – omitted, it is derived
+ * from the {@link SearchType} ({@link deriveCollectionName}), the same
+ * convention the engine reads by; the versioned collection name and the alias
+ * are managed here.
  */
 export class BlueGreenRebuild {
     client;
     searchType;
-    options;
-    constructor(client, searchType, options) {
+    /**
+     * The live Typesense alias this writer keeps pointed at its newest build:
+     * the explicit `options.name`, or the name derived from the
+     * {@link SearchType}. Read-only and for observability (logging, health
+     * checks) – never an input, and the same name
+     * {@link createTypesenseSearchEngine} reads the type from. The versioned
+     * collections behind it (`${collectionName}_<timestamp>`) stay internal.
+     */
+    collectionName;
+    resolved;
+    constructor(client, searchType, options = {}) {
         this.client = client;
         this.searchType = searchType;
-        this.options = options;
         // `source` is stamped on every document for per-dataset rollback.
         assertNoReservedFields(searchType, [SOURCE_FIELD]);
+        this.resolved = resolveRebuildOptions(searchType, options);
+        this.collectionName = this.resolved.name;
     }
     async openRun(context) {
-        const { name, batchSize, lockTtlMs, definitionOptions } = resolveRebuildOptions(this.options);
+        const { name, batchSize, lockTtlMs, definitionOptions } = this.resolved;
         return openLockedRun(this.client, name, lockTtlMs, async () => {
             // Create the fresh (blue) collection up front, so a failure surfaces
             // before any dataset is processed. startedAt orders the versioned names;

package/dist/collection-definition.d.ts

@@ -2,10 +2,12 @@ import type { CollectionCreateSchema } from 'typesense';
 import { type SearchType } from '@lde/search';
 /** Deployment-specific options the generic field model does not carry. */
 export interface CollectionDefinitionOptions {
-    /** The Typesense collection (or alias) name. */
-    readonly name: string;
+    /** The Typesense collection (or alias) name. Omit to derive it from the
+     *  type’s `name` ({@link deriveCollectionName}); supply one to override that
+     *  (an env prefix, a multi-tenant name, an existing collection). */
+    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
+     *  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;
@@ -26,14 +28,19 @@ export interface CollectionDefinitionOptions {
  * stems in `defaultLocale` when one is set, and is left unstemmed (folded
  * only) otherwise.
  *
+ * The collection `name` is optional: omitted, it is derived from the type’s own
+ * `name` ({@link deriveCollectionName}), so a caller that has no naming opinion
+ * states none.
+ *
  * Memory lever: Typesense holds 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 whole document.
- * This builder keeps that surface minimal: the `output` display labels fan out
- * to `index: false` fields, kept on disk and read back only for a hit, so they
- * cost no RAM; 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.
+ * This builder keeps that surface minimal: the `output` display labels land in
+ * a single `index: false` regex field (`${name}_<lang>`, one value per present
+ * language), kept on disk and read back only for a hit, so they cost no RAM;
+ * 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.
  */
-export declare function buildCollectionDefinition(searchType: SearchType, options: CollectionDefinitionOptions): CollectionCreateSchema;
+export declare function buildCollectionDefinition(searchType: SearchType, options?: CollectionDefinitionOptions): CollectionCreateSchema;
 //# sourceMappingURL=collection-definition.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"collection-definition.d.ts","sourceRoot":"","sources":["../src/collection-definition.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,2BAA2B;IAC1C,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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,2BAA2B,GACnC,sBAAsB,CAexB"}
+{"version":3,"file":"collection-definition.d.ts","sourceRoot":"","sources":["../src/collection-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAIhE,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C;;wEAEoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;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;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CAexB"}

package/dist/collection-definition.js

@@ -1,4 +1,5 @@
-import { physicalFields } from '@lde/search/adapter';
+import { displayFieldPattern, physicalFields } from '@lde/search/adapter';
+import { deriveCollectionName } from './collection-name.js';
 /**
  * Build a Typesense collection definition from the unified {@link SearchType}, so
  * the index and the projection are driven by one declarative source and cannot
@@ -11,19 +12,24 @@ import { physicalFields } from '@lde/search/adapter';
  * stems in `defaultLocale` when one is set, and is left unstemmed (folded
  * only) otherwise.
  *
+ * The collection `name` is optional: omitted, it is derived from the type’s own
+ * `name` ({@link deriveCollectionName}), so a caller that has no naming opinion
+ * states none.
+ *
  * Memory lever: Typesense holds 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 whole document.
- * This builder keeps that surface minimal: the `output` display labels fan out
- * to `index: false` fields, kept on disk and read back only for a hit, so they
- * cost no RAM; 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.
+ * This builder keeps that surface minimal: the `output` display labels land in
+ * a single `index: false` regex field (`${name}_<lang>`, one value per present
+ * language), kept on disk and read back only for a hit, so they cost no RAM;
+ * 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.
  */
-export function buildCollectionDefinition(searchType, options) {
+export function buildCollectionDefinition(searchType, options = {}) {
     const { defaultLocale } = options;
     const collection = {
-        name: options.name,
+        name: options.name ?? deriveCollectionName(searchType),
         fields: searchType.fields.flatMap((field) => typesenseFields(field, defaultLocale, options.defaultSortingField)),
     };
     if (options.defaultSortingField !== undefined) {
@@ -39,17 +45,24 @@ function typesenseFields(field, defaultLocale, defaultSortingField) {
     const names = physicalFields(field);
     if (field.kind === 'text') {
         const locales = field.locales;
+        const displayPattern = displayFieldPattern(field);
         return [
-            // Display labels: stored but NOT indexed (`index: false`) – search hits
-            // the folded `*_search` companions, so the display copy stays on disk and
-            // off RAM (fetched only for a hit), accents preserved. This is the memory
-            // lever: RAM tracks the search surface, not the display text.
-            ...names.display.map((name) => ({
-                name,
-                type: 'string',
-                index: false,
-                optional: true,
-            })),
+            // Display labels: ONE regex field (`${name}_<lang>`) storing every
+            // present language’s value, NOT indexed (`index: false`) – search hits
+            // the folded `*_search` companions, so the display copies stay on disk and
+            // off RAM (fetched only for a hit), accents preserved, and a language
+            // outside `locales` still renders. This is the memory lever: RAM tracks
+            // the search surface, not the display text. Absent for a non-output field.
+            ...(displayPattern !== undefined
+                ? [
+                    {
+                        name: displayPattern,
+                        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`.
@@ -83,7 +96,7 @@ function typesenseFields(field, defaultLocale, defaultSortingField) {
         },
     ];
     // `names.search` is non-empty exactly when the field projects a folded
-    // search companion — physicalFields owns that rule.
+    // search companion – physicalFields owns that rule.
     for (const name of names.search) {
         fields.push({
             name,

package/dist/collection-name.d.ts

@@ -0,0 +1,24 @@
+import type { SearchType } from '@lde/search';
+/**
+ * The Typesense collection name for a {@link SearchType}, derived from its
+ * logical `name` – the default every writer and the engine fall back to when a
+ * deployment supplies none, so the write side and the read side share one
+ * convention and cannot drift.
+ *
+ * The convention is Typesense’s own, as its docs write collection names:
+ * snake_case, named after the plural of what the collection holds – `people`,
+ * `companies`, `blog_articles`
+ * ({@link https://typesense.org/docs/guide/organizing-collections.html |
+ * Organizing collections}, which frames a collection as ‘similar to a table in
+ * a relational database’). So `CreativeWork` → `creative_works`, `Person` →
+ * `people`, `TVSeries` → `tv_series`. The engine-neutral half – the word split
+ * and the inflection – is {@link physicalNameTokens}; only the `_` join and the
+ * validation below are Typesense’s.
+ *
+ * A deployment that needs another name (an env prefix, a multi-tenant name, an
+ * index that already exists) passes it explicitly instead; the override is
+ * never validated here, since an existing collection’s name is the
+ * deployment’s business.
+ */
+export declare function deriveCollectionName(searchType: SearchType): string;
+//# sourceMappingURL=collection-name.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collection-name.d.ts","sourceRoot":"","sources":["../src/collection-name.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAanE"}

package/dist/collection-name.js

@@ -0,0 +1,55 @@
+import { physicalNameTokens } from '@lde/search/adapter';
+/**
+ * The Typesense collection name for a {@link SearchType}, derived from its
+ * logical `name` – the default every writer and the engine fall back to when a
+ * deployment supplies none, so the write side and the read side share one
+ * convention and cannot drift.
+ *
+ * The convention is Typesense’s own, as its docs write collection names:
+ * snake_case, named after the plural of what the collection holds – `people`,
+ * `companies`, `blog_articles`
+ * ({@link https://typesense.org/docs/guide/organizing-collections.html |
+ * Organizing collections}, which frames a collection as ‘similar to a table in
+ * a relational database’). So `CreativeWork` → `creative_works`, `Person` →
+ * `people`, `TVSeries` → `tv_series`. The engine-neutral half – the word split
+ * and the inflection – is {@link physicalNameTokens}; only the `_` join and the
+ * validation below are Typesense’s.
+ *
+ * A deployment that needs another name (an env prefix, a multi-tenant name, an
+ * index that already exists) passes it explicitly instead; the override is
+ * never validated here, since an existing collection’s name is the
+ * deployment’s business.
+ */
+export function deriveCollectionName(searchType) {
+    if (!NAMEABLE_TYPE_NAME.test(searchType.name)) {
+        throw new Error(`Cannot derive a Typesense collection name from search type “${searchType.name}”: it carries characters the convention would silently drop rather than name. Rename the type, or pass an explicit name.`);
+    }
+    const name = physicalNameTokens(searchType).join('_');
+    if (!DERIVED_COLLECTION_NAME.test(name)) {
+        throw new Error(`Cannot derive a Typesense collection name from search type “${searchType.name}”: it yields “${name}”, which is not a legal collection name. Rename the type, or pass an explicit name.`);
+    }
+    return name;
+}
+/**
+ * A type name this convention can name a collection after without silently
+ * losing part of it. {@link physicalNameTokens} matches ASCII words and drops
+ * everything else, which is what lets a name already written `creative_work` or
+ * `creative-work` tokenize like `CreativeWork` – but it would just as quietly
+ * turn `Café` into `cafs` and `Musée` into `mus_es`: legal names for the wrong
+ * collection, which is worse than no name at all. So a name is nameable only
+ * when it is ASCII words and word separators; anything else is rejected rather
+ * than mangled. An explicit name still overrides, since a deployment may
+ * legitimately index a type whose name this cannot spell.
+ */
+const NAMEABLE_TYPE_NAME = /^[A-Za-z0-9 _-]+$/;
+/**
+ * What a *derived* name must look like. Typesense documents no collection-name
+ * rules, but a name travels in the URL path of every collection call
+ * (`/collections/:name`), so a character with URL meaning breaks that call
+ * rather than being rejected at creation – `#` and `+` silently strand a
+ * collection ({@link https://github.com/typesense/typesense/issues/548}). This
+ * charset is the safe subset {@link physicalNameTokens} can produce anyway, so
+ * the check is really a guard on the type name behind it: a `name` with no
+ * alphanumerics at all (tokens `[]`, name `''`) is the case that reaches it.
+ */
+const DERIVED_COLLECTION_NAME = /^[a-z][a-z0-9_]*$/;

package/dist/in-place-rebuild.d.ts

@@ -47,8 +47,16 @@ export declare class InPlaceRebuild<TDocument extends {
 }> implements Writer<TDocument> {
     private readonly client;
     private readonly searchType;
-    private readonly options;
-    constructor(client: Client, searchType: SearchType, options: InPlaceRebuildOptions);
+    /**
+     * The Typesense collection this writer maintains: the explicit
+     * `options.name`, or the name derived from the {@link SearchType}. Read-only
+     * and for observability (logging, health checks) – never an input, and the
+     * same name {@link createTypesenseSearchEngine} reads the type from.
+     */
+    readonly collectionName: string;
+    private readonly maxSweepableSources;
+    private readonly resolved;
+    constructor(client: Client, searchType: SearchType, options?: InPlaceRebuildOptions);
     openRun(context: RunContext): Promise<RunWriter<TDocument>>;
     /**
      * The distinct sources present in the collection, via a single `source`

package/dist/in-place-rebuild.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"in-place-rebuild.d.ts","sourceRoot":"","sources":["../src/in-place-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AAYvB,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAa9B;gCACgC;AAChC,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D;sEACkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,cAAc,CACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,qBAAqB;IAK3C,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IA0FjE;;;;;;OAMG;YACW,cAAc;CAsB7B"}
+{"version":3,"file":"in-place-rebuild.d.ts","sourceRoot":"","sources":["../src/in-place-rebuild.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAEV,UAAU,EACV,SAAS,EACT,MAAM,EACP,MAAM,eAAe,CAAC;AAYvB,OAAO,EAKL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAC;AAa9B;gCACgC;AAChC,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC3D;sEACkE;IAClE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,cAAc,CACzB,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAChC,YAAW,MAAM,CAAC,SAAS,CAAC;IAY1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAZ7B;;;;;OAKG;IACH,SAAgB,cAAc,EAAE,MAAM,CAAC;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;gBAG/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,UAAU,EACvC,OAAO,GAAE,qBAA0B;IAY/B,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAqFjE;;;;;;OAMG;YACW,cAAc;CAsB7B"}

package/dist/in-place-rebuild.js

@@ -49,16 +49,26 @@ const DEFAULT_MAX_SWEEPABLE_SOURCES = 10_000;
 export class InPlaceRebuild {
     client;
     searchType;
-    options;
-    constructor(client, searchType, options) {
+    /**
+     * The Typesense collection this writer maintains: the explicit
+     * `options.name`, or the name derived from the {@link SearchType}. Read-only
+     * and for observability (logging, health checks) – never an input, and the
+     * same name {@link createTypesenseSearchEngine} reads the type from.
+     */
+    collectionName;
+    maxSweepableSources;
+    resolved;
+    constructor(client, searchType, options = {}) {
         this.client = client;
         this.searchType = searchType;
-        this.options = options;
         assertNoReservedFields(searchType, [SOURCE_FIELD, LAST_SEEN_FIELD]);
+        const { maxSweepableSources = DEFAULT_MAX_SWEEPABLE_SOURCES, ...rebuildOptions } = options;
+        this.maxSweepableSources = maxSweepableSources;
+        this.resolved = resolveRebuildOptions(searchType, rebuildOptions);
+        this.collectionName = this.resolved.name;
     }
     async openRun(context) {
-        const { maxSweepableSources = DEFAULT_MAX_SWEEPABLE_SOURCES, ...rebuildOptions } = this.options;
-        const { name, batchSize, lockTtlMs, definitionOptions } = resolveRebuildOptions(rebuildOptions);
+        const { name, batchSize, lockTtlMs, definitionOptions } = this.resolved;
         return openLockedRun(this.client, name, lockTtlMs, async () => {
             // Create the collection on demand: SearchType schema + the bookkeeping
             // fields, `source` faceted so the membership sweep can enumerate the
@@ -101,7 +111,7 @@ export class InPlaceRebuild {
                 },
                 commit: async () => {
                     await importer.flush();
-                    const departed = departedSources(await this.indexedSources(name, maxSweepableSources), context.selectedSources());
+                    const departed = departedSources(await this.indexedSources(name, this.maxSweepableSources), context.selectedSources());
                     for (const filter of membershipSweepFilters(departed)) {
                         await deleteByFilter(this.client, name, filter);
                     }

package/dist/index.d.ts

@@ -6,8 +6,9 @@ export { RebuildAlreadyRunning } from './lock.js';
 export { departedSources, membershipSweepFilters, sourceDocumentsFilter, staleDocumentsFilter, } from './sweep.js';
 export { buildCollectionDefinition } from './collection-definition.js';
 export type { CollectionDefinitionOptions } from './collection-definition.js';
+export { deriveCollectionName } from './collection-name.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';
+export type { TypesenseSearchEngine, 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,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAC9E,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,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,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -3,5 +3,6 @@ export { InPlaceRebuild } from './in-place-rebuild.js';
 export { RebuildAlreadyRunning } from './lock.js';
 export { departedSources, membershipSweepFilters, sourceDocumentsFilter, staleDocumentsFilter, } from './sweep.js';
 export { buildCollectionDefinition } from './collection-definition.js';
+export { deriveCollectionName } from './collection-name.js';
 export { buildSearchParams } from './query-compiler.js';
 export { createTypesenseSearchEngine, parseSearchResponse } from './search.js';

package/dist/rebuild-support.d.ts

@@ -19,8 +19,17 @@ export interface ResolvedRebuildOptions {
     readonly lockTtlMs: number;
     readonly definitionOptions: CollectionDefinitionOptions;
 }
-/** Apply the shared defaults, once, so neither writer restates them. */
-export declare function resolveRebuildOptions(options: RebuildOptions): ResolvedRebuildOptions;
+/**
+ * Apply the shared defaults, once, so neither writer restates them – including
+ * the collection name, derived from the type ({@link deriveCollectionName})
+ * when the deployment supplies none. The resolved name is put back into
+ * `definitionOptions`, so the collection a writer talks to and the definition
+ * it creates are the same one name, resolved once.
+ *
+ * Writers resolve at construction rather than per run, so an underivable name
+ * throws when the writer is built, not on the first rebuild.
+ */
+export declare function resolveRebuildOptions(searchType: SearchType, options: RebuildOptions): ResolvedRebuildOptions;
 /**
  * Reject a {@link SearchType} that declares any of the bookkeeping field names
  * a writer stamps, so a domain field can never collide with `source` /

package/dist/rebuild-support.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rebuild-support.d.ts","sourceRoot":"","sources":["../src/rebuild-support.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAI9E;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,2BAA2B;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;0FAC0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,CAAC;CACzD;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAYxB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,IAAI,CAWN;AAED,4EAA4E;AAC5E,wBAAuB,cAAc,CAAC,SAAS,EAC7C,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,EACnC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACtC,aAAa,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAInD;AAED,mEAAmE;AACnE,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAKf"}
+{"version":3,"file":"rebuild-support.d.ts","sourceRoot":"","sources":["../src/rebuild-support.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAK9E;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,2BAA2B;IACjE,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;0FAC0F;AAC1F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,CAAC;CACzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAaxB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,IAAI,CAWN;AAED,4EAA4E;AAC5E,wBAAuB,cAAc,CAAC,SAAS,EAC7C,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,EACnC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACtC,aAAa,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAInD;AAED,mEAAmE;AACnE,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/rebuild-support.js

@@ -1,13 +1,24 @@
+import { deriveCollectionName } from './collection-name.js';
 import { DEFAULT_LOCK_TTL_MS } from './lock.js';
 import { DEFAULT_BATCH_SIZE } from './import.js';
-/** Apply the shared defaults, once, so neither writer restates them. */
-export function resolveRebuildOptions(options) {
+/**
+ * Apply the shared defaults, once, so neither writer restates them – including
+ * the collection name, derived from the type ({@link deriveCollectionName})
+ * when the deployment supplies none. The resolved name is put back into
+ * `definitionOptions`, so the collection a writer talks to and the definition
+ * it creates are the same one name, resolved once.
+ *
+ * Writers resolve at construction rather than per run, so an underivable name
+ * throws when the writer is built, not on the first rebuild.
+ */
+export function resolveRebuildOptions(searchType, options) {
     const { batchSize = DEFAULT_BATCH_SIZE, lockTtlMs = DEFAULT_LOCK_TTL_MS, ...definitionOptions } = options;
+    const name = definitionOptions.name ?? deriveCollectionName(searchType);
     return {
-        name: definitionOptions.name,
+        name,
         batchSize,
         lockTtlMs,
-        definitionOptions,
+        definitionOptions: { ...definitionOptions, name },
     };
 }
 /**

package/dist/search.d.ts

@@ -1,20 +1,25 @@
 import type { Client } from 'typesense';
 import { type LocalizedValue, type SearchEngine, type SearchResult, type SearchSchema, type SearchType, type TextField } from '@lde/search';
 import { type BuildSearchParamsOptions } from './query-compiler.js';
-/** Where the engine reads documents — plus every query-compiler knob
+/** Where the engine reads documents – 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. Reference labels resolve per field from the collection of
- *  the SearchType its `labelSource` names — a label source is just another
- *  entry in `collections`. */
+ *  wholesale into each search. Reference labels resolve per field from the
+ *  collection of the SearchType its `labelSource` names – a label source is
+ *  just another type, so it is named the same way. */
 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>>;
+    /**
+     * Overrides the collection (or alias) a search type reads, keyed by the
+     * type’s `name`. Every type not named here reads the collection derived from
+     * its own name ({@link deriveCollectionName}) – the same convention the
+     * writers create, so the read side and the write side cannot drift. Supply an
+     * entry only where a deployment needs another name (an env prefix, a
+     * multi-tenant name, an existing collection); `TypeName` is the union of the
+     * schema’s type names, so a typo is still a compile error.
+     */
+    readonly collections?: Partial<Readonly<Record<TypeName, string>>>;
     /**
      * Called when reference-label resolution fails; the search then degrades to
-     * id-only references rather than failing. Optional — omit to swallow silently.
+     * id-only references rather than failing. Optional – omit to swallow silently.
      */
     readonly onLabelError?: (error: unknown) => void;
     /**
@@ -27,6 +32,21 @@ export interface TypesenseSearchEngineOptions<TypeName extends string = string>
      */
     readonly labelCacheTtlMs?: number;
 }
+/**
+ * A {@link SearchEngine} backed by Typesense: the port, plus the one engine
+ * specific worth exposing – which collection each type actually reads.
+ */
+export interface TypesenseSearchEngine<Types extends readonly SearchType[] = readonly SearchType[]> extends SearchEngine<Types> {
+    /**
+     * The collection `searchType` reads: its {@link
+     * TypesenseSearchEngineOptions.collections} override, or the name derived
+     * from the type. Resolved at construction and read-only – for observability
+     * (logging a search’s target, a health check asserting the collection
+     * exists), never an input. Throws for a type outside this engine’s schema,
+     * like every other entry point.
+     */
+    collectionNameFor(searchType: Types[number]): string;
+}
 /**
  * One reference field’s resolved label source: the collection it reads, the
  * source type’s `label` declaration (for reconstructing localized labels) and
@@ -40,12 +60,13 @@ export interface LabelSource {
 }
 /**
  * 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`. `search` compiles
- * the query ({@link buildSearchParams}), runs it against the type’s
- * collection, resolves the reference labels for the page of hits — each
+ * {@link SearchSchema} at construction – like every other schema consumer.
+ * Each type’s collection is derived from the type ({@link
+ * deriveCollectionName}) unless `options.collections` overrides it. `search`
+ * compiles the query ({@link buildSearchParams}), runs it against the type’s
+ * collection, resolves the reference labels for the page of hits – each
  * reference field from its own label source’s collection, all sources bundled
- * into one lookup — and reconstructs the engine-neutral
+ * into one lookup – and reconstructs the engine-neutral
  * {@link SearchResult} ({@link parseSearchResponse}). `searchFacets` answers
  * a whole facet batch (e.g. a faceted listing’s skip-own-filter query variants) as a
  * single `multi_search` round-trip with one shared label lookup; a failed
@@ -55,22 +76,23 @@ export interface LabelSource {
  *
  * 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.
+ * 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>;
+export declare function createTypesenseSearchEngine<const Types extends readonly SearchType[]>(client: Client, schema: SearchSchema<Types>, options?: TypesenseSearchEngineOptions<Types[number]['name']>): TypesenseSearchEngine<Types>;
 /** One label lookup: a source and the distinct IRIs to resolve against it. */
 export interface LabelLookupGroup {
     readonly source: LabelSource;
     readonly iris: readonly string[];
 }
 /**
- * Resolve labels from each group’s label-source collection. Localized labels
- * are reconstructed from the source type’s `label` declaration; a bare
- * untagged `label` value is the `und` fallback when no locale variant exists.
+ * Resolve labels from each group’s label-source collection. Labels are
+ * reconstructed from the source type’s `label` declaration ({@link
+ * localizedValue}), carrying every present language – including ones outside
+ * the declared `locales` and untagged (`und`) values.
  *
  * All groups travel as ONE `multi_search` (POST) call, each group’s 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
+ * 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

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,EAGL,KAAK,cAAc,EAMnB,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEf,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAWrB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;8BAM8B;AAC9B,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;;;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;;;;;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;;;;;;;;;;;;;;;;;;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,CAsRrB;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AA0FD;;;;;;;;;;;;;GAaG;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;AAgDD,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"}
+{"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,EAEf,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAYrB,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,KAAK,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CACtD;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,CAgS9B;AAyCD,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AA0FD;;;;;;;;;;;;;;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,13 +1,15 @@
-import { assertTypeInSchema, assertValidQuery, fieldNamed, isRangeFacet, labelFieldOf, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isRangeFacet, labelFieldOf, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
 import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
+import { deriveCollectionName } from './collection-name.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`. `search` compiles
- * the query ({@link buildSearchParams}), runs it against the type’s
- * collection, resolves the reference labels for the page of hits — each
+ * {@link SearchSchema} at construction – like every other schema consumer.
+ * Each type’s collection is derived from the type ({@link
+ * deriveCollectionName}) unless `options.collections` overrides it. `search`
+ * compiles the query ({@link buildSearchParams}), runs it against the type’s
+ * collection, resolves the reference labels for the page of hits – each
  * reference field from its own label source’s collection, all sources bundled
- * into one lookup — and reconstructs the engine-neutral
+ * into one lookup – and reconstructs the engine-neutral
  * {@link SearchResult} ({@link parseSearchResponse}). `searchFacets` answers
  * a whole facet batch (e.g. a faceted listing’s skip-own-filter query variants) as a
  * single `multi_search` round-trip with one shared label lookup; a failed
@@ -17,22 +19,30 @@ import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
  *
  * 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.
+ * 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.class, collection];
-    }));
+export function createTypesenseSearchEngine(client, schema, options = {}) {
+    // Resolve every type's collection ONCE at construction – the override when
+    // the deployment named one, the derived name otherwise – so an underivable
+    // name fails at startup, never on the first search that happens to hit that
+    // type.
+    const resolved = [...schema.values()].map((searchType) => {
+        const override = options.collections?.[searchType.name];
+        return {
+            searchType,
+            collection: override ?? deriveCollectionName(searchType),
+            derived: override === undefined,
+        };
+    });
+    assertNoAccidentalSharing(resolved);
+    const collections = new Map(resolved.map(({ searchType, collection }) => [
+        searchType.class,
+        collection,
+    ]));
     // Resolve every reference field's label source ONCE at construction. The
     // schema already guarantees the named type exists and serves labels
-    // (`searchSchema`/`labelFieldOf`), and `collections` is exhaustive per type.
+    // (`searchSchema`/`labelFieldOf`), and every type resolved a collection
+    // above, so both lookups below always hit.
     const typesByName = new Map([...schema.values()].map((searchType) => [searchType.name, searchType]));
     const labelSources = new Map([...schema.values()].map((searchType) => [
         searchType.class,
@@ -156,6 +166,10 @@ export function createTypesenseSearchEngine(client, schema, options) {
     }
     const engine = {
         schema,
+        collectionNameFor(searchType) {
+            assertTypeInSchema(schema, searchType);
+            return collections.get(searchType.class);
+        },
         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
@@ -208,10 +222,40 @@ export function createTypesenseSearchEngine(client, schema, options) {
     // The runtime object is string-keyed; the literal-schema typing narrows it.
     return engine;
 }
+/**
+ * Reject two types landing in one collection *by accident*.
+ *
+ * A schema keeps type names distinct, but distinct names can still derive the
+ * same collection – English collapses them (`Medium` and `Media` both give
+ * `media`, `Person` and `People` both give `people`). Nothing downstream would
+ * complain: both writers would build the one collection, each type’s search
+ * would return the other’s documents, and the membership sweep would delete
+ * across them. Exactly the drift deriving names is meant to end, so it fails at
+ * construction with the override that resolves it.
+ *
+ * Sharing a collection *deliberately* stays allowed – several label-source
+ * types served by one `labels` collection is a reasonable deployment – so this
+ * fires only when at least one side was derived, i.e. when nobody chose it.
+ */
+function assertNoAccidentalSharing(resolved) {
+    const byCollection = new Map();
+    for (const entry of resolved) {
+        byCollection.set(entry.collection, [
+            ...(byCollection.get(entry.collection) ?? []),
+            entry,
+        ]);
+    }
+    for (const [collection, entries] of byCollection) {
+        if (entries.length > 1 && entries.some((entry) => entry.derived)) {
+            const names = entries.map((entry) => `“${entry.searchType.name}”`);
+            throw new Error(`Search types ${names.join(' and ')} would share the Typesense collection “${collection}”, which no deployment asked for: their names derive to it. Give ${names.join(' or ')} an explicit collections entry.`);
+        }
+    }
+}
 /**
  * Load a FULL label-source 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 labelValue}, exactly as the
+ * line). Each line is reconstructed by {@link localizedValue}, exactly as the
  * per-search {@link fetchLabels} path does for its `multi_search` hits.
  */
 async function loadAllLabels(client, source) {
@@ -225,7 +269,7 @@ async function loadAllLabels(client, source) {
             continue;
         }
         const document = JSON.parse(line);
-        const label = labelValue(document, source.labelField);
+        const label = localizedValue(document, source.labelField);
         if (label !== undefined) {
             labels.set(String(document.id), label);
         }
@@ -286,13 +330,14 @@ function labelLookupGroups(responses, sources, outputSources) {
     }));
 }
 /**
- * Resolve labels from each group’s label-source collection. Localized labels
- * are reconstructed from the source type’s `label` declaration; a bare
- * untagged `label` value is the `und` fallback when no locale variant exists.
+ * Resolve labels from each group’s label-source collection. Labels are
+ * reconstructed from the source type’s `label` declaration ({@link
+ * localizedValue}), carrying every present language – including ones outside
+ * the declared `locales` and untagged (`und`) values.
  *
  * All groups travel as ONE `multi_search` (POST) call, each group’s 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
+ * 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
@@ -331,7 +376,7 @@ export async function fetchLabels(client, groups, onError) {
             return;
         }
         for (const hit of result.hits ?? []) {
-            const label = labelValue(hit.document, groupPerSearch[index].source.labelField);
+            const label = localizedValue(hit.document, groupPerSearch[index].source.labelField);
             if (label !== undefined) {
                 labels.set(String(hit.document.id), label);
             }
@@ -342,21 +387,6 @@ export async function fetchLabels(client, groups, onError) {
 /** 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;
-/**
- * Reconstruct a label document into a language map via the source type’s
- * `label` declaration (its per-locale display fields), with a bare untagged
- * `label` value as the `und` fallback when no locale variant exists, or
- * `undefined` when the document carries no usable label – so the reference
- * stays id-only rather than gaining an empty label.
- */
-function labelValue(document, labelField) {
-    const localized = localizedValue(document, labelField);
-    if (localized !== undefined) {
-        return localized;
-    }
-    const untagged = document[labelField.name];
-    return typeof untagged === 'string' ? { und: [untagged] } : undefined;
-}
 /** Merge per-collection label maps into one IRI-keyed map (URI identity). */
 function mergeLabels(maps) {
     if (maps.length === 1) {
@@ -383,7 +413,7 @@ export function parseSearchResponse(response, searchType, labels) {
         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.
+    // Plain facets (tokens, free strings) carry no label – the consumer owns display.
     // Only reference facets with a label source get bucket labels; an id-only
     // reference facet stays id-only even when a cached full-collection map holds
     // its IRIs.
@@ -447,16 +477,24 @@ function logicalValue(flat, field, labels) {
             return flat[field.name] === true;
     }
 }
-/** Gather the per-locale display fields back into a language map. */
+/**
+ * Gather every present-language display field back into a language map. Display
+ * fields are pattern-based (`${name}_<lang>`, {@link displayLangOf}), so this
+ * recovers languages outside the declared `locales` too – a value tagged in an
+ * undeclared language, or untagged (`und`), still reconstructs rather than being
+ * dropped.
+ */
 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];
+    for (const [key, value] of Object.entries(flat)) {
+        if (typeof value !== 'string') {
+            continue;
         }
-    });
+        const lang = displayLangOf(field, key);
+        if (lang !== undefined) {
+            map[lang] = [value];
+        }
+    }
     return Object.keys(map).length > 0 ? map : undefined;
 }
 /** Map stored reference IRIs to labelled references; id-only when no label. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "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.6.0",
+    "@lde/search": "^0.7.1",
     "@lde/text-normalization": "^0.1.1",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"