@lde/search-typesense 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,4 +1,7 @@
-export { rebuild } from './adapter.js';
+export { BlueGreenRebuild } from './blue-green-rebuild.js';
+export { InPlaceRebuild } from './in-place-rebuild.js';
+export { RebuildAlreadyRunning } from './lock.js';
+export { departedSources, membershipSweepFilters, sourceDocumentsFilter, staleDocumentsFilter, } from './sweep.js';
 export { buildCollectionSchema } from './collection-schema.js';
 export { buildSearchParams } from './query-compiler.js';
 export { createTypesenseSearchEngine, parseSearchResponse } from './search.js';

package/dist/lock.d.ts

@@ -0,0 +1,42 @@
+import type { Client, CollectionCreateSchema } from 'typesense';
+/** A held lock older than this (ms) is reclaimed. */
+export declare const DEFAULT_LOCK_TTL_MS: number;
+/**
+ * Another run already holds the index’s rebuild lock, so this run refuses to
+ * open. Rebuilds are single-flight per index across pods; catch this to treat
+ * a concurrent rebuild as a graceful skip rather than a failure.
+ */
+export declare class RebuildAlreadyRunning extends Error {
+    constructor(name: string);
+}
+/**
+ * Open a run under the index’s single-flight lock: acquire it (throwing
+ * {@link RebuildAlreadyRunning} when another rebuild holds it), run the
+ * writer-specific `setup`, and release the lock again if the setup fails –
+ * so a failed opening never leaves the index locked. The lock choreography
+ * lives here once, shared by every rebuild writer.
+ */
+export declare function openLockedRun<Run>(client: Client, name: string, ttlMs: number, setup: () => Promise<Run>): Promise<Run>;
+/**
+ * Take the per-index rebuild lock via an atomic create, reclaiming it if the
+ * current holder is older than `ttlMs`. Returns `false` if another caller
+ * holds a fresh lock. The lock collection is created on demand, so the happy
+ * path costs a single request.
+ *
+ * Advisory, not a strict mutex: the lock is built on Typesense, not a
+ * consensus store. Under a TTL-reclaim race two rebuilds can briefly run at
+ * once; Blue/green tolerates this because it is idempotent (worst case:
+ * redundant work and a transient orphaned collection), In-place because its
+ * upserts are idempotent.
+ */
+export declare function acquireLock(client: Client, name: string, ttlMs: number): Promise<boolean>;
+/** Release the per-index lock; a no-op when it is not currently held. */
+export declare function releaseLock(client: Client, name: string): Promise<void>;
+/**
+ * Create a collection on demand: retrieve it, and only on a 404 create it
+ * from the lazily built `schema`, tolerating a concurrent creator (409).
+ */
+export declare function ensureCollectionExists(client: Client, name: string, schema: () => CollectionCreateSchema): Promise<void>;
+/** The HTTP status a Typesense client error carries, if any. */
+export declare function httpStatus(error: unknown): number | undefined;
+//# sourceMappingURL=lock.d.ts.map

package/dist/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAIhE,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,QAAiB,CAAC;AAElD;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,IAAI,EAAE,MAAM;CAIzB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,GAAG,EACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GACxB,OAAO,CAAC,GAAG,CAAC,CAUd;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAwBlB;AAED,yEAAyE;AACzE,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ7E;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,sBAAsB,GACnC,OAAO,CAAC,IAAI,CAAC,CAgBf;AA+BD,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE7D"}

package/dist/lock.js

@@ -0,0 +1,134 @@
+const LOCK_COLLECTION = 'rebuild_locks';
+/** A held lock older than this (ms) is reclaimed. */
+export const DEFAULT_LOCK_TTL_MS = 10 * 60 * 1000;
+/**
+ * Another run already holds the index’s rebuild lock, so this run refuses to
+ * open. Rebuilds are single-flight per index across pods; catch this to treat
+ * a concurrent rebuild as a graceful skip rather than a failure.
+ */
+export class RebuildAlreadyRunning extends Error {
+    constructor(name) {
+        super(`Another rebuild of “${name}” is already running`);
+        this.name = 'RebuildAlreadyRunning';
+    }
+}
+/**
+ * Open a run under the index’s single-flight lock: acquire it (throwing
+ * {@link RebuildAlreadyRunning} when another rebuild holds it), run the
+ * writer-specific `setup`, and release the lock again if the setup fails –
+ * so a failed opening never leaves the index locked. The lock choreography
+ * lives here once, shared by every rebuild writer.
+ */
+export async function openLockedRun(client, name, ttlMs, setup) {
+    if (!(await acquireLock(client, name, ttlMs))) {
+        throw new RebuildAlreadyRunning(name);
+    }
+    try {
+        return await setup();
+    }
+    catch (error) {
+        await releaseLock(client, name);
+        throw error;
+    }
+}
+/**
+ * Take the per-index rebuild lock via an atomic create, reclaiming it if the
+ * current holder is older than `ttlMs`. Returns `false` if another caller
+ * holds a fresh lock. The lock collection is created on demand, so the happy
+ * path costs a single request.
+ *
+ * Advisory, not a strict mutex: the lock is built on Typesense, not a
+ * consensus store. Under a TTL-reclaim race two rebuilds can briefly run at
+ * once; Blue/green tolerates this because it is idempotent (worst case:
+ * redundant work and a transient orphaned collection), In-place because its
+ * upserts are idempotent.
+ */
+export async function acquireLock(client, name, ttlMs) {
+    try {
+        await client
+            .collections(LOCK_COLLECTION)
+            .documents()
+            .create({ id: name, acquired_at: Date.now() });
+        return true;
+    }
+    catch (error) {
+        const status = httpStatus(error);
+        if (status === 409) {
+            return reclaimIfStale(client, name, ttlMs);
+        }
+        if (status === 404) {
+            // First lock ever: the collection does not exist yet. Create it, then
+            // retake from the top – the atomic create still guards a concurrent
+            // taker, and the collection cannot 404 again.
+            await ensureCollectionExists(client, LOCK_COLLECTION, () => ({
+                name: LOCK_COLLECTION,
+                fields: [{ name: 'acquired_at', type: 'int64' }],
+            }));
+            return acquireLock(client, name, ttlMs);
+        }
+        throw error;
+    }
+}
+/** Release the per-index lock; a no-op when it is not currently held. */
+export async function releaseLock(client, name) {
+    try {
+        await client.collections(LOCK_COLLECTION).documents(name).delete();
+    }
+    catch (error) {
+        if (httpStatus(error) !== 404) {
+            throw error;
+        }
+    }
+}
+/**
+ * Create a collection on demand: retrieve it, and only on a 404 create it
+ * from the lazily built `schema`, tolerating a concurrent creator (409).
+ */
+export async function ensureCollectionExists(client, name, schema) {
+    try {
+        await client.collections(name).retrieve();
+        return;
+    }
+    catch (error) {
+        if (httpStatus(error) !== 404) {
+            throw error;
+        }
+    }
+    try {
+        await client.collections().create(schema());
+    }
+    catch (error) {
+        if (httpStatus(error) !== 409) {
+            throw error;
+        }
+    }
+}
+/** Take over the lock if its holder has not refreshed it within `ttlMs`. */
+async function reclaimIfStale(client, name, ttlMs) {
+    let held;
+    try {
+        held = (await client
+            .collections(LOCK_COLLECTION)
+            .documents(name)
+            .retrieve());
+    }
+    catch (error) {
+        // Released between our create and this read — leave it for the next try.
+        if (httpStatus(error) === 404) {
+            return false;
+        }
+        throw error;
+    }
+    if (Date.now() - held.acquired_at <= ttlMs) {
+        return false;
+    }
+    await client
+        .collections(LOCK_COLLECTION)
+        .documents()
+        .upsert({ id: name, acquired_at: Date.now() });
+    return true;
+}
+/** The HTTP status a Typesense client error carries, if any. */
+export function httpStatus(error) {
+    return error.httpStatus;
+}

package/dist/rebuild-support.d.ts

@@ -0,0 +1,34 @@
+import type { Client } from 'typesense';
+import type { SearchType } from '@lde/search';
+import type { CollectionSchemaOptions } from './collection-schema.js';
+/**
+ * The tuning knobs both rebuild writers share, on top of the collection-schema
+ * options. Each writer may add its own (In-place adds `maxSweepableSources`).
+ */
+export interface RebuildOptions extends CollectionSchemaOptions {
+    /** Documents imported per Typesense request (default 1000). */
+    readonly batchSize?: number;
+    /** A held lock older than this (ms) is reclaimed (default 10 minutes). */
+    readonly lockTtlMs?: number;
+}
+/** The shared options resolved to concrete values plus the residual
+ *  collection-schema options a writer passes to {@link buildCollectionSchema}. */
+export interface ResolvedRebuildOptions {
+    readonly name: string;
+    readonly batchSize: number;
+    readonly lockTtlMs: number;
+    readonly schemaOptions: CollectionSchemaOptions;
+}
+/** Apply the shared defaults, once, so neither writer restates them. */
+export declare function resolveRebuildOptions(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` /
+ * `last_seen`.
+ */
+export declare function assertNoReservedFields(searchType: SearchType, reserved: readonly string[]): void;
+/** Stamp each document with fixed bookkeeping fields as it streams past. */
+export declare function stampDocuments<TDocument>(documents: AsyncIterable<TDocument>, stamp: Readonly<Record<string, string>>): AsyncIterable<TDocument & Record<string, string>>;
+/** Delete a collection’s documents matching a Typesense filter. */
+export declare function deleteByFilter(client: Client, collection: string, filterBy: string): Promise<void>;
+//# sourceMappingURL=rebuild-support.d.ts.map

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

@@ -0,0 +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,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAItE;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,uBAAuB;IAC7D,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;kFACkF;AAClF,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,aAAa,EAAE,uBAAuB,CAAC;CACjD;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAOxB;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

@@ -0,0 +1,33 @@
+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) {
+    const { batchSize = DEFAULT_BATCH_SIZE, lockTtlMs = DEFAULT_LOCK_TTL_MS, ...schemaOptions } = options;
+    return { name: schemaOptions.name, batchSize, lockTtlMs, schemaOptions };
+}
+/**
+ * Reject a {@link SearchType} that declares any of the bookkeeping field names
+ * a writer stamps, so a domain field can never collide with `source` /
+ * `last_seen`.
+ */
+export function assertNoReservedFields(searchType, reserved) {
+    const clashing = searchType.fields.filter((field) => reserved.includes(field.name));
+    if (clashing.length > 0) {
+        throw new Error(`SearchType “${searchType.name}” declares reserved bookkeeping field(s) ${clashing
+            .map((field) => `“${field.name}”`)
+            .join(', ')}`);
+    }
+}
+/** Stamp each document with fixed bookkeeping fields as it streams past. */
+export async function* stampDocuments(documents, stamp) {
+    for await (const document of documents) {
+        yield { ...document, ...stamp };
+    }
+}
+/** Delete a collection’s documents matching a Typesense filter. */
+export async function deleteByFilter(client, collection, filterBy) {
+    await client
+        .collections(collection)
+        .documents()
+        .delete({ filter_by: filterBy });
+}

package/dist/search.d.ts

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

package/dist/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAEL,KAAK,cAAc,EAMnB,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAE7B;;;;kCAIkC;AAClC,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,MAAM,GAAG,MAAM,CAChC,SAAQ,wBAAwB;IAChC;qEACiE;IACjE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,CAAC,KAAK,SAAS,SAAS,UAAU,EAAE,EAEzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,EAC3B,OAAO,EAAE,4BAA4B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAC3D,YAAY,CAAC,KAAK,CAAC,CAkGrB;AA+DD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAyBtC;AAsBD,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS;QAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS;YACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;SACxB,EAAE,CAAC;KACL,EAAE,CAAC;CACL;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,uBAAuB,EACjC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,GAC1C,YAAY,CAiCd"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAGL,KAAK,cAAc,EAMnB,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAE7B;;;;kCAIkC;AAClC,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,MAAM,GAAG,MAAM,CAChC,SAAQ,wBAAwB;IAChC;qEACiE;IACjE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,CAAC,KAAK,SAAS,SAAS,UAAU,EAAE,EAEzC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,EAC3B,OAAO,EAAE,4BAA4B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAC3D,YAAY,CAAC,KAAK,CAAC,CAwKrB;AA+DD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAmCtC;AA6BD,oEAAoE;AACpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,CAAC;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS;QAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS;YACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;SACxB,EAAE,CAAC;KACL,EAAE,CAAC;CACL;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,uBAAuB,EACjC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,GAC1C,YAAY,CAiCd"}

package/dist/search.js

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

package/dist/sweep.d.ts

@@ -0,0 +1,50 @@
+/** The document field carrying the dataset IRI a document came from. */
+export declare const SOURCE_FIELD = "source";
+/** The document field carrying the id of the run that last wrote a document. */
+export declare const LAST_SEEN_FIELD = "last_seen";
+/**
+ * Sources whose documents must leave the index: indexed, but no longer part
+ * of the run’s selection. Selection is membership, not processing – a dataset
+ * skipped as unchanged is still selected, so its documents survive.
+ *
+ * @param indexedSources Source IRIs present in the collection
+ * @param selectedSources Source IRIs the run’s selector produced
+ */
+export declare function departedSources(indexedSources: Iterable<string>, selectedSources: Iterable<string>): string[];
+/**
+ * Typesense filter matching a source’s documents that this run did not touch:
+ * everything the source no longer contains, ready for a per-source sweep.
+ *
+ * @param sourceIri The dataset IRI stamped on the documents as `source`
+ * @param runId The current run; documents it wrote carry it as `last_seen`
+ */
+export declare function staleDocumentsFilter(sourceIri: string, runId: string): string;
+/**
+ * Typesense filter matching all of a source’s documents, ready to drop a whole
+ * source (a departed source’s membership sweep, or a Blue/green writer rolling
+ * a failed dataset out of its not-yet-live collection).
+ *
+ * @param sourceIri The dataset IRI stamped on the documents as `source`
+ */
+export declare function sourceDocumentsFilter(sourceIri: string): string;
+/**
+ * Typesense filter matching the documents **this run** wrote for a source: the
+ * inverse of {@link staleDocumentsFilter}. An In-place writer deletes these to
+ * discard a source’s in-progress writes (the dump-fallback reset) without
+ * touching its prior-run documents, which the success sweep or a failed run
+ * still owns.
+ *
+ * @param sourceIri The dataset IRI stamped on the documents as `source`
+ * @param runId The current run, stamped on its documents as `last_seen`
+ */
+export declare function thisRunDocumentsFilter(sourceIri: string, runId: string): string;
+/**
+ * Typesense filters deleting every departed source’s documents, combined into
+ * as few filters as fit: deletes travel in the URL query string, so each
+ * filter stays under a conservative length budget rather than listing every
+ * source in one string.
+ *
+ * @param departed The departed source IRIs ({@link departedSources})
+ */
+export declare function membershipSweepFilters(departed: readonly string[]): string[];
+//# sourceMappingURL=sweep.d.ts.map

package/dist/sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep.d.ts","sourceRoot":"","sources":["../src/sweep.ts"],"names":[],"mappings":"AAQA,wEAAwE;AACxE,eAAO,MAAM,YAAY,WAAW,CAAC;AAErC,gFAAgF;AAChF,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,EAChC,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,GAChC,MAAM,EAAE,CAGV;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAqB5E"}

package/dist/sweep.js

@@ -0,0 +1,87 @@
+// Pure deletion planning shared by the rebuild writers: which documents leave
+// a collection, expressed as source sets and Typesense filter strings. Kept
+// free of the Typesense client so the logic is unit-testable. This module owns
+// the bookkeeping field names, so stamping and every filter that reads them
+// can never disagree.
+import { escapeFilterValue } from './query-compiler.js';
+/** The document field carrying the dataset IRI a document came from. */
+export const SOURCE_FIELD = 'source';
+/** The document field carrying the id of the run that last wrote a document. */
+export const LAST_SEEN_FIELD = 'last_seen';
+/**
+ * Sources whose documents must leave the index: indexed, but no longer part
+ * of the run’s selection. Selection is membership, not processing – a dataset
+ * skipped as unchanged is still selected, so its documents survive.
+ *
+ * @param indexedSources Source IRIs present in the collection
+ * @param selectedSources Source IRIs the run’s selector produced
+ */
+export function departedSources(indexedSources, selectedSources) {
+    const selected = new Set(selectedSources);
+    return [...indexedSources].filter((source) => !selected.has(source));
+}
+/**
+ * Typesense filter matching a source’s documents that this run did not touch:
+ * everything the source no longer contains, ready for a per-source sweep.
+ *
+ * @param sourceIri The dataset IRI stamped on the documents as `source`
+ * @param runId The current run; documents it wrote carry it as `last_seen`
+ */
+export function staleDocumentsFilter(sourceIri, runId) {
+    return `${sourceDocumentsFilter(sourceIri)} && ${LAST_SEEN_FIELD}:!=${escapeFilterValue(runId)}`;
+}
+/**
+ * Typesense filter matching all of a source’s documents, ready to drop a whole
+ * source (a departed source’s membership sweep, or a Blue/green writer rolling
+ * a failed dataset out of its not-yet-live collection).
+ *
+ * @param sourceIri The dataset IRI stamped on the documents as `source`
+ */
+export function sourceDocumentsFilter(sourceIri) {
+    return `${SOURCE_FIELD}:=${escapeFilterValue(sourceIri)}`;
+}
+/**
+ * Typesense filter matching the documents **this run** wrote for a source: the
+ * inverse of {@link staleDocumentsFilter}. An In-place writer deletes these to
+ * discard a source’s in-progress writes (the dump-fallback reset) without
+ * touching its prior-run documents, which the success sweep or a failed run
+ * still owns.
+ *
+ * @param sourceIri The dataset IRI stamped on the documents as `source`
+ * @param runId The current run, stamped on its documents as `last_seen`
+ */
+export function thisRunDocumentsFilter(sourceIri, runId) {
+    return `${sourceDocumentsFilter(sourceIri)} && ${LAST_SEEN_FIELD}:=${escapeFilterValue(runId)}`;
+}
+/**
+ * Typesense filters deleting every departed source’s documents, combined into
+ * as few filters as fit: deletes travel in the URL query string, so each
+ * filter stays under a conservative length budget rather than listing every
+ * source in one string.
+ *
+ * @param departed The departed source IRIs ({@link departedSources})
+ */
+export function membershipSweepFilters(departed) {
+    const filters = [];
+    let chunk = [];
+    let chunkLength = 0;
+    const flush = () => {
+        if (chunk.length > 0) {
+            filters.push(`${SOURCE_FIELD}:=[${chunk.join(',')}]`);
+            chunk = [];
+            chunkLength = 0;
+        }
+    };
+    for (const source of departed) {
+        const escaped = escapeFilterValue(source);
+        if (chunkLength + escaped.length > MAX_FILTER_VALUES_LENGTH) {
+            flush();
+        }
+        chunk.push(escaped);
+        chunkLength += escaped.length + 1;
+    }
+    flush();
+    return filters;
+}
+/** Stay well under Typesense’s ~4000-char URL query-string limit per delete. */
+const MAX_FILTER_VALUES_LENGTH = 3000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.2.0",
+  "version": "0.4.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,12 +25,16 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/search": "^0.2.0",
+    "@lde/search": "^0.3.0",
     "@lde/text-normalization": "^0.1.1",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"
   },
   "devDependencies": {
     "testcontainers": "^12.0.3"
+  },
+  "peerDependencies": {
+    "@lde/dataset": "^0.7.8",
+    "@lde/pipeline": "^0.33.0"
   }
 }

package/dist/adapter.d.ts

@@ -1,56 +0,0 @@
-import type { Client } from 'typesense';
-import type { SearchType } from '@lde/search';
-import { type CollectionSchemaOptions } from './collection-schema.js';
-/** {@link rebuild} options: the collection-schema options (`name` is the
- *  logical index name the alias is kept on) plus the rebuild tuning knobs. */
-export interface RebuildOptions extends CollectionSchemaOptions {
-    /** Documents imported per Typesense request (default 1000). */
-    readonly batchSize?: number;
-    /** A held lock older than this (ms) is reclaimed (default 10 minutes). */
-    readonly lockTtlMs?: number;
-}
-/**
- * Blue/green-rebuild the search index `options.name` from one declarative
- * source: the collection schema is derived from `searchType`
- * ({@link buildCollectionSchema}) and the documents are streamed in — one call
- * from declaration to live index.
- *
- * 1. create a fresh versioned collection (`${name}_<timestamp>`)
- * 2. stream `documents` into it in batches
- * 3. atomically repoint the `name` alias to the new collection, then
- *    drop the collection it superseded. The caller passes only the logical
- *    index `name`; the versioned collection name and the alias are managed here.
- *
- * The rebuild is **single-flight per index**: it first takes a lock (a marker
- * document in a `rebuild_locks` collection, created on demand) via Typesense’s
- * atomic create, so concurrent callers across pods never rebuild the same index
- * at once. This keeps blue/green safe under replication.
- *
- * `documents` is an async iterable (e.g. a streaming projection); only one
- * `batchSize`-sized chunk is held in memory at a time. On any failure before the
- * swap nothing is repointed, so the live alias never points at a partial build,
- * and the orphaned half-built collection is dropped.
- *
- * @returns the live collection name and the number of documents imported, or
- * `null` when the rebuild was skipped because another rebuild for the same index
- * was already running.
- *
- * Limitations:
- * - **Advisory, not a strict mutex.** The lock is built on Typesense, not a
- *   consensus store. Under a TTL-reclaim race two rebuilds can briefly run at
- *   once; this is safe because blue/green is idempotent (worst case: redundant
- *   work and a transient orphaned collection).
- * - **Single-flight, not coalescing.** A call made while a rebuild is in flight
- *   is skipped (returns `null`), not queued. If you must capture state that
- *   changed mid-build, re-trigger after the running rebuild finishes.
- * - **Lock TTL.** A rebuild that runs longer than `lockTtlMs` (default 10
- *   minutes) can be reclaimed by another caller and run concurrently; size the
- *   TTL above your longest rebuild.
- */
-export declare function rebuild<Document extends {
-    id: string;
-}>(client: Client, documents: AsyncIterable<Document>, searchType: SearchType, options: RebuildOptions): Promise<{
-    collection: string;
-    imported: number;
-} | null>;
-//# sourceMappingURL=adapter.d.ts.map