@lde/search-typesense 0.27.4 → 0.29.0

package/dist/query-compiler.js

@@ -1,5 +1,5 @@
 import { fold } from '@lde/text-normalization';
-import { fieldNamed, filterOperator, filterOperatorFor, ID_FIELD, isoToUnixSeconds, isRangeFacet, pageForOffset, physicalFields, searchableFields, } from '@lde/search/adapter';
+import { fieldNamed, filterOperator, filterOperatorFor, ID_FIELD, isoToUnixSeconds, isInternalField, isRangeFacet, isWelded, joinGraph, localLookupTypeOf, pageForOffset, physicalFields, nestedReferenceType, resolvePath, searchableFields, } from '@lde/search/adapter';
 /**
  * Compile the engine-neutral {@link SearchQuery} into Typesense search
  * parameters – the query half of the engine adapter. Pure (no client, no env),
@@ -16,7 +16,7 @@ export function buildSearchParams(query, searchType, options = {}) {
     const folded = query.text !== undefined && query.text.length > 0
         ? fold(query.text)
         : undefined;
-    const { names, weights } = queryFields(searchType, query.locale);
+    const { names, weights } = queryFields(searchType, query.locale, options.schema);
     const filterBy = compileFilterBy(query.where, searchType, options);
     const sortBy = query.orderBy
         .map((sort) => compileSort(sort, searchType, query.locale))
@@ -78,16 +78,41 @@ function compileRangeFacet(name, ranges) {
  * 1), so a match in the user’s language ranks higher while cross-language matches
  * still surface.
  */
-function queryFields(searchType, locale) {
+function queryFields(searchType, locale, schema) {
     const names = [];
     const weights = [];
+    collectSearchable(searchType, locale, schema, '', new Set(), names, weights);
+    return { names, weights };
+}
+/**
+ * Collect the searchable physical fields of a type and of everything it nests,
+ * each under the path an engine addresses it by.
+ *
+ * Nested fields are walked because a nested field may declare `searchable`
+ * (ADR 24) – and a companion that is indexed but absent from `query_by` is the
+ * worst of both: it costs the RAM of an indexed field and matches nothing, in
+ * silence. So the walk here is what makes that Role mean anything.
+ *
+ * `onPath` guards the walk, and is scoped to the PATH rather than to the walk
+ * as a whole: two fields may nest one type – `creator` and `contributor` over
+ * the same edge – and each reaches it under its own prefix, so each must
+ * contribute its own companions. A set shared across the walk would let the
+ * first field claim the type and leave the second's companions indexed but
+ * unqueried. What it does guard is a type reached from ITSELF, which a
+ * {@link ReferenceStrategy.local local} lookup can do.
+ */
+function collectSearchable(searchType, locale, schema, prefix, onPath, names, weights) {
+    if (onPath.has(searchType.name)) {
+        return;
+    }
+    const walked = new Set(onPath).add(searchType.name);
     for (const field of searchableFields(searchType)) {
         const search = physicalFields(field).search;
         const baseWeight = field.searchable.weight;
         if (field.kind === 'text') {
             const locales = field.locales;
             search.forEach((name, index) => {
-                names.push(name);
+                names.push(qualify(prefix, name));
                 // The active locale keeps full weight; `und` is language-neutral, so
                 // it is never demoted (an untagged-only field would otherwise always
                 // rank below its declared weight).
@@ -98,12 +123,26 @@ function queryFields(searchType, locale) {
         }
         else {
             for (const name of search) {
-                names.push(name);
+                names.push(qualify(prefix, name));
                 weights.push(baseWeight);
             }
         }
     }
-    return { names, weights };
+    if (schema === undefined) {
+        return;
+    }
+    for (const field of searchType.fields) {
+        // An internal field is pruned before the writer and declared in no
+        // collection, so its target's companions exist nowhere – asking `query_by`
+        // for one makes the ENGINE reject every search on the collection.
+        if (isInternalField(field)) {
+            continue;
+        }
+        const nested = nestedReferenceType(schema, field) ?? localLookupTypeOf(field, schema);
+        if (nested !== undefined) {
+            collectSearchable(nested, locale, schema, qualify(prefix, field.name), walked, names, weights);
+        }
+    }
 }
 /** AND-join the compiled `where` clauses. A clause that states no constraint is
  *  skipped; one that can match nothing compiles to {@link MATCHES_NOTHING}
@@ -201,16 +240,31 @@ const UNUSABLE = Symbol('unusable');
 function compileCriterion(criterion, searchType, options) {
     const on = criterion.on ?? [];
     if (on.length === 0) {
-        return compileLeaf(criterion, searchType, options.schema);
+        return isWelded(criterion)
+            ? compileWelded(criterion, searchType, options.schema, '')
+            : compileLeaf(criterion, searchType, options.schema);
     }
+    // The path carries two kinds of hop, and they compile differently: a JOIN
+    // crosses into another collection and wraps the leaf in `$collection(…)`; a
+    // NESTING stays in this document and qualifies the leaf’s field name. The
+    // schema is what tells them apart, so without one every hop is read as a
+    // join – exactly the behaviour before nesting existed.
+    const resolvedPath = options.schema === undefined
+        ? undefined
+        : resolvePath(searchType, on, options.schema, joinGraph(options.schema));
+    if (typeof resolvedPath === 'string') {
+        return UNUSABLE;
+    }
+    const joinHops = resolvedPath?.joinPath ?? on;
+    const nestedHops = resolvedPath?.nestedPath ?? [];
     // A joined criterion constrains a document in ANOTHER collection, so the leaf
     // is compiled against the type that path reaches and then wrapped, one
     // `$collection(…)` per hop, outermost hop first:
     // `['dataset', 'publisher']` → `$datasets($publishers(id:=…))`.
     const collections = [];
     let target = searchType;
-    for (let hop = 1; hop <= on.length; hop++) {
-        const resolved = options.joinTargetFor?.(searchType, on.slice(0, hop));
+    for (let hop = 1; hop <= joinHops.length; hop++) {
+        const resolved = options.joinTargetFor?.(searchType, joinHops.slice(0, hop));
         if (resolved === undefined) {
             // An unresolvable path is a criterion that cannot be compiled at all –
             // false, so it drops out and its siblings still stand. Through the
@@ -220,7 +274,11 @@ function compileCriterion(criterion, searchType, options) {
         collections.push(resolved.collection);
         target = resolved.searchType;
     }
-    const leaf = compileLeaf(criterion, target, options.schema);
+    const leafType = resolvedPath?.leafType ?? target;
+    const prefix = nestedHops.join('.');
+    const leaf = isWelded(criterion)
+        ? compileWelded(criterion, leafType, options.schema, prefix)
+        : compileLeaf(criterion, leafType, options.schema, prefix);
     // A vacuous leaf states no constraint on the referent, so the join as a whole
     // states none either – the reading, and so the outcome, passes straight
     // through the hops.
@@ -229,9 +287,16 @@ function compileCriterion(criterion, searchType, options) {
     }
     return collections.reduceRight((inner, collection) => `$${collection}(${inner})`, leaf);
 }
-/** The criterion’s own term, against the type it actually constrains – the
- *  searched type, or the one its join path reaches. */
-function compileLeaf(criterion, searchType, schema) {
+/**
+ * The criterion’s own term, against the type it actually constrains – the
+ * searched type, the one its join path reaches, or the reference type its
+ * nesting path walks into.
+ *
+ * `prefix` is that nesting path, dotted: an engine addresses a stored nested
+ * document by qualifying the field name, so `role` inside `creator` becomes
+ * `creator.role`. Empty for every unnested criterion.
+ */
+function compileLeaf(criterion, searchType, schema, prefix = '') {
     // `id` is the Typesense document key, not a declared field. Exact `:=`
     // membership, like a non-facet field ({@link compileMembership}), so an IRI
     // cannot partial-match on a shared path segment. (`fetchLabels` resolves
@@ -239,7 +304,12 @@ function compileLeaf(criterion, searchType, schema) {
     // clause.) An empty identity membership enumerates NO document, so it is
     // unusable rather than vacuous – the one place the two readings diverge.
     if (criterion.field === ID_FIELD) {
-        return 'in' in criterion && criterion.in.length > 0
+        // `id` names the DOCUMENT key, which exists only at the top level: inside a
+        // nested reference there is no document to key. Compiling it under a prefix
+        // would filter the root collection's `id` instead – a different question,
+        // silently answered. `assertValidQuery` rejects it first; this is the guard
+        // for a hand-built query.
+        return prefix === '' && 'in' in criterion && criterion.in.length > 0
             ? `${ID_FIELD}:=[${criterion.in.map(escapeFilterValue).join(',')}]`
             : UNUSABLE;
     }
@@ -254,13 +324,57 @@ function compileLeaf(criterion, searchType, schema) {
     }
     if ('in' in criterion) {
         return criterion.in.length > 0
-            ? compileMembership(field, criterion.in, schema)
+            ? compileMembership(field, criterion.in, schema, prefix)
             : VACUOUS;
     }
     if ('range' in criterion) {
-        return compileRange(field, criterion.range) ?? VACUOUS;
+        return compileRange(field, criterion.range, prefix) ?? VACUOUS;
+    }
+    // Every other shape returned above; a welded criterion never reaches here
+    // (compileWelded handles it before the leaf compiler is called).
+    return `${qualify(prefix, field.name)}:=${criterion.is}`;
+}
+/** A field name under its nesting path, if any – the one place the dotted
+ *  addressing an engine uses for a stored nested document is spelled. */
+function qualify(prefix, name) {
+    return prefix === '' ? name : `${prefix}.${name}`;
+}
+/**
+ * A **welded** criterion: `path.{a && b}`, matching a document with ONE entry
+ * that satisfies every condition – as against `path.a && path.b`, which two
+ * different entries can satisfy between them.
+ *
+ * Each condition is compiled against the reference type with an EMPTY prefix,
+ * so what goes inside the braces is always a leaf name. That is a correctness
+ * requirement, not tidiness: Typesense 30.2 **hangs** on a dotted path inside a
+ * group (`creator.{creator.name:=…}` never returns – no error, no result), so
+ * the compiler must be structurally incapable of emitting one. A field whose
+ * value is itself nested is reached through its identity companion, which is a
+ * leaf ({@link physicalFields}).
+ *
+ * A condition that states no constraint drops out, and the weld is whatever
+ * remains; a weld left with nothing is vacuous like any other empty clause.
+ */
+function compileWelded(criterion, searchType, schema, prefix) {
+    const entryType = schema &&
+        nestedReferenceType(schema, fieldNamed(searchType, criterion.field) ?? {});
+    if (entryType === undefined) {
+        return UNUSABLE;
+    }
+    const conditions = [];
+    for (const condition of criterion.entry) {
+        const compiled = compileLeaf(condition, entryType, schema);
+        if (compiled === UNUSABLE) {
+            return UNUSABLE;
+        }
+        if (compiled !== VACUOUS) {
+            conditions.push(compiled);
+        }
+    }
+    if (conditions.length === 0) {
+        return VACUOUS;
     }
-    return `${field.name}:=${criterion.is}`;
+    return `${qualify(prefix, criterion.field)}.{${conditions.join(' && ')}}`;
 }
 /**
  * A membership clause. A non-facet (tokenized) field uses the exact `:=`
@@ -272,11 +386,15 @@ function compileLeaf(criterion, searchType, schema) {
  * filter on such a field is exactly what the policy promises stays whole, so
  * it must compile exact, not tokenized.
  */
-function compileMembership(field, values, schema) {
+function compileMembership(field, values, schema, prefix = '') {
     const list = `[${values.map(escapeFilterValue).join(',')}]`;
-    return physicalFields(field, schema).facet === field.name
-        ? `${field.name}:${list}`
-        : `${field.name}:=${list}`;
+    const names = physicalFields(field, schema);
+    // An inline reference stores a nested object, which an engine cannot filter.
+    // Its identity companion is the flat id field standing in for it – so the
+    // logical name a consumer writes and the physical name the engine reads
+    // differ here, and only here.
+    const name = qualify(prefix, names.identity ?? field.name);
+    return names.facet === name ? `${name}:${list}` : `${name}:=${list}`;
 }
 /** An inclusive Typesense range clause, or `undefined` when neither bound is
  *  usable. Which of the two readings that is – the caller set no bounds, or the
@@ -285,8 +403,8 @@ function compileMembership(field, values, schema) {
  *  from the conjunction widens it, so the same reading cannot be right in both
  *  positions. `validateQuery` rejects an unreadable bound outright instead,
  *  which is the only answer that neither widens nor narrows. */
-function compileRange(field, range) {
-    const name = field.name;
+function compileRange(field, range, prefix = '') {
+    const name = qualify(prefix, field.name);
     // A bound a caller sent as `null` – a GraphQL variable left unfilled, which
     // the surface passes through – is a bound NOT SET, not a bound of `null`.
     // Read literally it reaches the engine as `datePosted:[null..…]`, which

package/dist/rebuild-support.d.ts

@@ -1,5 +1,4 @@
-import type { Client } from 'typesense';
-import type { SearchSchema, SearchType } from '@lde/search';
+import type { SearchType } from '@lde/search';
 import { type CollectionDefinitionOptions } from './collection-definition.js';
 /**
  * The tuning knobs both rebuild writers share, on top of the collection-definition
@@ -39,43 +38,4 @@ export interface ResolvedRebuildOptions {
  * been paid for.
  */
 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` /
- * `last_seen`.
- */
-export declare function assertNoReservedFields(searchType: SearchType, reserved: readonly string[]): void;
-/**
- * Reject a declared dataset field the provenance bookkeeping cannot be kept on.
- * A type declaring one makes it the collection’s provenance field – the column
- * the membership sweep enumerates and deletes by – so the declaration has to answer
- * *which single dataset is this document’s* the way the private `source` field
- * did:
- *
- * - **not `array`**: Typesense reads `field:=[a,b]` over a `string[]` as
- *   *contains any*, so a departed source would take every document that merely
- *   mentions it – including entities another selected dataset still
- *   contributes;
- * - **no `transform`**: the sweep compares the stored value against the run’s
- *   selection, which carries raw dataset IRIs, so a transformed value would
- *   match nothing and the sweep would silently stop deleting;
- * - **`facetable`** where the writer enumerates the indexed sources by faceting
- *   it (the In-place writer does; Blue/green only ever filters by a known IRI)
- *   – and faceted **on its own name**: a reference inheriting a facet policy
- *   from the type it names facets a companion holding only the admitted keys
- *   (`physicalFields(field, schema).facet`), so enumerating the sources
- *   through it would miss every dataset the policy excludes. `schema` is what
- *   resolves that; without one no policy is visible, as nowhere else.
- *
- * Thrown at writer construction, so a declaration that cannot be swept fails
- * before a run touches the index rather than at the sweep, after the writes.
- */
-export declare function assertSweepableProvenanceField(searchType: SearchType, options: {
-    readonly requireFacetable: boolean;
-    readonly schema?: SearchSchema;
-}): 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

@@ -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,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQ5D,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAKpC;;;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;;;uEAGmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;KAChE,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAkBxB;AAsCD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,GAC1B,IAAI,CAWN;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE;IACP,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC,GACA,IAAI,CAiCN;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,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAOpC;;;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;;;uEAGmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,2BAA2B,GAAG;QACxD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;KAChE,CAAC;CACH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,sBAAsB,CAkBxB"}

package/dist/rebuild-support.js

@@ -1,8 +1,9 @@
-import { datasetField, isInternalField, joinGraph, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { joinGraph, referenceFields } from '@lde/search/adapter';
 import { buildCollectionDefinition, } from './collection-definition.js';
 import { deriveCollectionName } from './collection-name.js';
 import { DEFAULT_LOCK_TTL_MS } from './lock.js';
-import { DEFAULT_BATCH_SIZE } from './import.js';
+/** Documents imported per Typesense request unless a writer is told otherwise. */
+const DEFAULT_BATCH_SIZE = 1000;
 /**
  * Apply the shared defaults, once, so neither writer restates them – including
  * the collection naming, derived from each type ({@link deriveCollectionName})
@@ -59,77 +60,3 @@ function assertDistinctJoinTargetNames(searchType, options) {
         }
     }
 }
-/**
- * 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(', ')}`);
-    }
-}
-/**
- * Reject a declared dataset field the provenance bookkeeping cannot be kept on.
- * A type declaring one makes it the collection’s provenance field – the column
- * the membership sweep enumerates and deletes by – so the declaration has to answer
- * *which single dataset is this document’s* the way the private `source` field
- * did:
- *
- * - **not `array`**: Typesense reads `field:=[a,b]` over a `string[]` as
- *   *contains any*, so a departed source would take every document that merely
- *   mentions it – including entities another selected dataset still
- *   contributes;
- * - **no `transform`**: the sweep compares the stored value against the run’s
- *   selection, which carries raw dataset IRIs, so a transformed value would
- *   match nothing and the sweep would silently stop deleting;
- * - **`facetable`** where the writer enumerates the indexed sources by faceting
- *   it (the In-place writer does; Blue/green only ever filters by a known IRI)
- *   – and faceted **on its own name**: a reference inheriting a facet policy
- *   from the type it names facets a companion holding only the admitted keys
- *   (`physicalFields(field, schema).facet`), so enumerating the sources
- *   through it would miss every dataset the policy excludes. `schema` is what
- *   resolves that; without one no policy is visible, as nowhere else.
- *
- * Thrown at writer construction, so a declaration that cannot be swept fails
- * before a run touches the index rather than at the sweep, after the writes.
- */
-export function assertSweepableProvenanceField(searchType, options) {
-    const field = datasetField(searchType);
-    if (field === undefined || isInternalField(field)) {
-        return;
-    }
-    const problems = [];
-    if (field.array === true) {
-        problems.push('it is an array, and a membership sweep over one would delete every document merely mentioning a departed dataset');
-    }
-    if (field.transform !== undefined) {
-        problems.push('it declares a transform, and the sweep matches the stored value against the run’s raw dataset IRIs');
-    }
-    if (options.requireFacetable && field.facetable !== true) {
-        problems.push('it is not facetable, and the membership sweep enumerates the indexed datasets by faceting it');
-    }
-    else if (options.requireFacetable &&
-        physicalFields(field, options.schema).facet !== field.name) {
-        problems.push('it inherits a facet policy from the type it names, so the engine facets only the datasets the policy admits, and the membership sweep enumerates the indexed datasets by faceting it');
-    }
-    if (problems.length > 0) {
-        throw new Error(`SearchType “${searchType.name}” declares “${field.name}” over the indexed dataset, which this writer keeps its provenance bookkeeping on, but ${problems.join('; and ')}.`);
-    }
-}
-/** 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.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAGL,KAAK,cAAc,EAMnB,KAAK,UAAU,EAGf,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEf,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAoBrB,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAExE;;;;sDAIsD;AACtD,MAAM,WAAW,4BAA4B,CAC3C,QAAQ,SAAS,MAAM,GAAG,MAAM,CAIhC,SAAQ,IAAI,CAAC,wBAAwB,EAAE,eAAe,CAAC;IACvD;;;;;;;;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,UAAU,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC;CAC1D;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,CA0Z9B;AAyCD,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAiJD;;;;;;;;;;;;;;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;;2EAEmE;QACnE,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;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,uBAAuB,EACjC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,EAC3C,MAAM,EAAE,YAAY,EACpB,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,GACjD,YAAY,CAgDd"}

package/dist/search.js

@@ -1,4 +1,4 @@
-import { assertTypeInSchema, assertValidQuery, displayLangOf, facetableFields, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNameOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, facetableFields, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNameOf, labelTargetNameOf, localLookupTypeOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
 import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
 import { deriveCollectionName } from './collection-name.js';
 import { resolveProjection } from './lookup.js';
@@ -68,9 +68,12 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
     const labelSources = new Map([...schema.values()].map((searchType) => [
         searchType.class,
         new Map(referenceFields(searchType)
-            .filter((field) => labelSourceNameOf(field) !== undefined)
+            // An INLINE reference names its label target one level in, through
+            // its identity companion: the companion holds that field's ids, so
+            // that field's target is what can label them.
+            .filter((field) => labelTargetNameOf(field, schema) !== undefined)
             .map((field) => {
-            const source = typesByName.get(labelSourceNameOf(field));
+            const source = typesByName.get(labelTargetNameOf(field, schema));
             const labelField = labelFieldOf(source);
             return [
                 field.name,
@@ -114,7 +117,18 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
         return [
             searchType.class,
             referenceFields(searchType)
-                .filter((field) => field.output === true && sources?.has(field.name))
+                .filter((field) => field.output === true &&
+                sources?.has(field.name) === true &&
+                // A field storing NESTED DOCUMENTS is excluded, and must be: this
+                // list drives the per-hit label lookup, which reads each stored
+                // value as an id. An inline reference and a `local` lookup store
+                // objects, so every entry would contribute the string
+                // `"[object Object]"` to the batched `id:[…]` filter. Neither
+                // needs entry labels anyway – the referent's own fields are in
+                // the entry – and their FACET buckets are labelled by a separate
+                // path that reads the companion.
+                nestedReferenceType(schema, field) === undefined &&
+                localLookupTypeOf(field, schema) === undefined)
                 .map((field) => ({
                 name: field.name,
                 source: sources.get(field.name),
@@ -538,7 +552,7 @@ export function parseSearchResponse(response, searchType, labels, schema, refere
     // reference facet stays id-only even when a cached full-collection map holds
     // its IRIs.
     const referenceFacets = new Set(referenceFields(searchType)
-        .filter((field) => labelSourceNameOf(field) !== undefined)
+        .filter((field) => labelTargetNameOf(field, schema) !== undefined)
         .map((field) => field.name));
     const facets = {};
     for (const facet of response.facet_counts ?? []) {
@@ -587,15 +601,25 @@ function logicalValue(flat, field, labels, schema, referents) {
             // reconstructs as a nested Search Document rather than as an IRI plus a
             // label. Nesting is rebuilt HERE, below every surface, so a second
             // surface inherits it instead of reimplementing it (ADR 11).
+            const resolved = referents?.get(field.name);
             const nested = nestedReferenceType(schema, field);
             if (nested !== undefined) {
-                return nestedValue(flat[field.name], field, nested, labels, schema);
+                // A nested level resolves nothing itself; what it carries are the
+                // levels below it, which the entries are reconstructed against.
+                return nestedValue(flat[field.name], field, nested, labels, schema, resolved?.children);
+            }
+            // Checked BEFORE the plain lookup below, because a `local` lookup
+            // resolves through the same kind of level while storing a different
+            // shape: its stored value is the endpoint's own document, not an id, so
+            // reading it as one would stringify the object into a bogus `id`.
+            const localType = localLookupTypeOf(field, schema);
+            if (localType !== undefined) {
+                return localLookupValue(flat[field.name], field, localType, resolved, labels, schema);
             }
             // A resolved lookup carries the referent's own fields, fetched from the
             // target's collection. It reconstructs through the SAME path a hit does,
             // so a consumer cannot tell a projected referent from an inline one.
-            const resolved = referents?.get(field.name);
-            if (resolved !== undefined) {
+            if (resolved !== undefined && resolved.via === 'lookup') {
                 return lookupValue(flat[field.name], field, resolved, labels, schema);
             }
             // A surfaced inline reference stores nested documents, not IRIs, so a
@@ -655,10 +679,10 @@ function localizedValue(flat, field) {
  * a nested document is read, not addressed. A nested reference type may itself
  * surface an inline reference, which recurses through {@link reconstructDocument}.
  */
-function nestedValue(raw, field, referenceType, labels, schema) {
+function nestedValue(raw, field, referenceType, labels, schema, children) {
     const referents = (Array.isArray(raw) ? raw : [raw]).filter((referent) => typeof referent === 'object' && referent !== null);
     const documents = referents.map((referent) => {
-        const document = reconstructDocument(referent, referenceType, labels, schema);
+        const document = reconstructDocument(referent, referenceType, labels, schema, children);
         return typeof referent.id === 'string'
             ? { id: referent.id, ...document }
             : document;
@@ -668,6 +692,34 @@ function nestedValue(raw, field, referenceType, labels, schema) {
     }
     return field.array === true ? documents : documents[0];
 }
+/**
+ * Rebuild a {@link ReferenceStrategy.local local} lookup: the endpoint’s own
+ * document as this document stated it, with the **resolved** document overlaid
+ * where the lookup found one.
+ *
+ * Both sides are the target type’s flat physical shape, so the merge is a plain
+ * override and the authoritative value wins field by field. Three cases fall
+ * out of one expression, which is the point of storing local fields
+ * unconditionally:
+ *
+ * - identified and indexed → the target’s own record, over what was stated here;
+ * - identified but not indexed → what was stated here, plus the `id`, rather
+ *   than a bare IRI;
+ * - not identified → what was stated here, with no `id` at all.
+ */
+function localLookupValue(raw, field, target, resolved, labels, schema) {
+    const fetched = resolved?.via === 'lookup' ? resolved.documents : new Map();
+    const merged = (Array.isArray(raw) ? raw : [raw])
+        .filter((entry) => typeof entry === 'object' && entry !== null)
+        .map((entry) => {
+        const id = typeof entry.id === 'string' ? entry.id : undefined;
+        const authoritative = id === undefined ? undefined : fetched.get(id);
+        return authoritative === undefined
+            ? entry
+            : { ...entry, ...authoritative };
+    });
+    return nestedValue(merged, field, target, labels, schema, resolved?.children);
+}
 /**
  * Rebuild a resolved `lookup` reference: each stored IRI becomes the referent’s
  * own document, read through the **target’s** declaration and carrying whatever

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.27.4",
+  "version": "0.29.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,17 +25,17 @@
     "!**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@lde/search": "^0.23.2",
+    "@lde/search": "^0.24.0",
     "@lde/text-normalization": "^0.1.2",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"
   },
   "devDependencies": {
-    "n3": "^2.1.2",
+    "n3": "^2.4.0",
     "testcontainers": "^12.1.0"
   },
   "peerDependencies": {
     "@lde/dataset": "^0.7.9",
-    "@lde/pipeline": "^0.36.3"
+    "@lde/pipeline": "^0.36.4"
   }
 }

package/dist/import.d.ts

@@ -1,31 +0,0 @@
-import type { Client } from 'typesense';
-/** Documents imported per Typesense request unless a writer is told otherwise. */
-export declare const DEFAULT_BATCH_SIZE = 1000;
-/**
- * Accumulates documents across writes and upserts them into a collection in
- * fixed-size batches, so many small writes (one dataset at a time) still land
- * as few Typesense requests. Call {@link flush} to import the remainder.
- */
-export declare class BatchImporter<TDocument extends {
-    id: string;
-}> {
-    private readonly client;
-    private readonly collection;
-    private readonly batchSize;
-    private buffer;
-    constructor(client: Client, collection: string, batchSize: number);
-    /** Add a stream of documents, importing a batch whenever one fills up. */
-    add(documents: AsyncIterable<TDocument>): Promise<void>;
-    /** Import any remaining documents. */
-    flush(): Promise<void>;
-    private importBuffer;
-}
-/**
- * Create-or-replace one batch of whole documents, keyed on `id`, throwing if any
- * individual document fails (Typesense’s bulk import otherwise reports
- * per-document failures without rejecting).
- */
-export declare function importBatch(client: Client, collection: string, batch: readonly {
-    id: string;
-}[]): Promise<void>;
-//# sourceMappingURL=import.d.ts.map

package/dist/import.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../src/import.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,WAAW,CAAC;AAExD,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;GAIG;AACH,qBAAa,aAAa,CAAC,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE;IAIvD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL5B,OAAO,CAAC,MAAM,CAAmB;gBAGd,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM;IAGpC,0EAA0E;IACpE,GAAG,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D,sCAAsC;IAChC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAMd,YAAY;CAK3B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,GAC/B,OAAO,CAAC,IAAI,CAAC,CAkBf"}