@lde/search-typesense 0.9.0 → 0.10.0

package/README.md

@@ -9,9 +9,66 @@ 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
+`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
@@ -29,7 +86,7 @@ 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
+`createTypesenseSearchEngine(client, schema, { collections? })` is the
 `SearchEngine` implementation. Each search:
 
 - validates the query against the search type (the port contract – a
@@ -45,9 +102,9 @@ down.
   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
@@ -63,7 +120,8 @@ direct use and testing.
 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;
+- [**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.
 
@@ -98,7 +156,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;IA6FjE,4EAA4E;YAC9D,WAAW;CAW1B"}

package/dist/blue-green-rebuild.js

@@ -27,22 +27,35 @@ 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.definitionOptions.name;
     }
     async openRun(context) {
-        const { name, batchSize, lockTtlMs, definitionOptions } = resolveRebuildOptions(this.options);
+        const { batchSize, lockTtlMs, definitionOptions } = this.resolved;
+        const name = this.collectionName;
         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,8 +2,10 @@ 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
      *  language is ever assumed. Localized text search fields always stem in
@@ -26,6 +28,10 @@ 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.
@@ -36,5 +42,5 @@ export interface CollectionDefinitionOptions {
  * 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;;;;;;;;;;;;;;;;;;;;;GAqBG;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 { 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,6 +12,10 @@ import { displayFieldPattern, 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.
@@ -21,10 +26,10 @@ import { displayFieldPattern, physicalFields } from '@lde/search/adapter';
  * 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) {

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,CAWnE"}

package/dist/collection-name.js

@@ -0,0 +1,43 @@
+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) {
+    // A name the split cannot spell at all throws in physicalNameTokens, which
+    // owns that engine-neutral rule; what is left to check here is whether the
+    // formatted result is legal for THIS engine.
+    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;
+}
+/**
+ * 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}).
+ * {@link physicalNameTokens} already guarantees lowercase ASCII words, so what
+ * this still rules on is the leading character: a type named `123` derives
+ * `123s`, and a name should open with a letter rather than read as a number.
+ */
+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;IAsFjE;;;;;;OAMG;YACW,cAAc;CAsB7B"}

package/dist/in-place-rebuild.js

@@ -49,16 +49,27 @@ 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.definitionOptions.name;
     }
     async openRun(context) {
-        const { maxSweepableSources = DEFAULT_MAX_SWEEPABLE_SOURCES, ...rebuildOptions } = this.options;
-        const { name, batchSize, lockTtlMs, definitionOptions } = resolveRebuildOptions(rebuildOptions);
+        const { batchSize, lockTtlMs, definitionOptions } = this.resolved;
+        const name = this.collectionName;
         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 +112,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

@@ -14,13 +14,24 @@ export interface RebuildOptions extends CollectionDefinitionOptions {
 /** The shared options resolved to concrete values plus the residual
  *  collection-definition options a writer passes to {@link buildCollectionDefinition}. */
 export interface ResolvedRebuildOptions {
-    readonly name: string;
     readonly batchSize: number;
     readonly lockTtlMs: number;
-    readonly definitionOptions: CollectionDefinitionOptions;
+    /** The collection-definition options with the `name` resolved – the one place
+     *  the resolved name lives, so the collection a writer talks to and the
+     *  definition it creates cannot say different things. */
+    readonly definitionOptions: CollectionDefinitionOptions & {
+        readonly name: string;
+    };
 }
-/** 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.
+ *
+ * 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,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;6DAEyD;IACzD,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAcxB;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,23 @@
+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.
+ *
+ * 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;
     return {
-        name: definitionOptions.name,
         batchSize,
         lockTtlMs,
-        definitionOptions,
+        definitionOptions: {
+            ...definitionOptions,
+            name: definitionOptions.name ?? deriveCollectionName(searchType),
+        },
     };
 }
 /**

package/dist/search.d.ts

@@ -3,15 +3,20 @@ import { type LocalizedValue, type SearchEngine, type SearchResult, type SearchS
 import { type BuildSearchParamsOptions } from './query-compiler.js';
 /** 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.
@@ -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
@@ -41,8 +61,9 @@ 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
+ * 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
@@ -57,7 +78,7 @@ export interface LabelSource {
  * `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>;
+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;

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;AAYrB,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;;;;;;;;;;;;;;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"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/search.js

@@ -1,10 +1,12 @@
 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
+ * 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
@@ -19,20 +21,28 @@ import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
  * `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.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,6 +222,36 @@ 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

package/package.json

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