@lde/search-typesense 0.33.1 → 0.35.0

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,EAEL,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAcrB,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;IAChE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CA2BxB"}
+{"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,EAEL,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAerB,0EAA0E;AAC1E,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,MAAM,CAAC;IAChE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,2BAAgC,GACxC,sBAAsB,CA2BxB"}

package/dist/collection-definition.js

@@ -1,4 +1,4 @@
-import { displayFieldPattern, ID_FIELD, isInlineReference, isInternalField, joinGraph, localLookupTypeOf, nestedFieldName, nestedReferenceType, physicalFields, } from '@lde/search/adapter';
+import { displayFieldPattern, ID_FIELD, isInlineReference, isInternalField, joinGraph, localLookupTargetsOf, TARGET_FIELD, nestedFieldName, nestedReferenceType, physicalFields, } from '@lde/search/adapter';
 import { deriveCollectionName } from './collection-name.js';
 /**
  * Build a Typesense collection definition from the unified {@link SearchType}, so
@@ -70,20 +70,19 @@ export function buildCollectionDefinition(searchType, options = {}) {
     return collection;
 }
 /**
- * The type a field nests, or `undefined` when it nests nothing. Throws when the
- * type carries an inline reference the caller gave no schema to resolve: the
- * collection would silently store the reference as a string the projection
- * never writes, so every document would fail to import.
+ * The types a field nests – one for an inline reference or a single-target
+ * `local` lookup, several for a `local` lookup naming several targets – or
+ * none when it nests nothing. Throws when the type carries an inline reference
+ * the caller gave no schema to resolve: the collection would silently store
+ * the reference as a string the projection never writes, so every document
+ * would fail to import.
  */
-function nestedTypeOf(searchType, field, schema) {
-    const nested = schema === undefined
-        ? undefined
-        : (nestedReferenceType(schema, field) ??
-            localLookupTypeOf(field, schema));
+function nestedTypesOf(searchType, field, schema) {
+    const nested = schema === undefined ? [] : nestedTypesOfNestedField(field, schema);
     // Reached only for a field carrying a Role, so an inline reference here
     // stores entries: a Role-less one is an internal reading device, pruned
     // before the writer.
-    if (nested === undefined && isInlineReference(field)) {
+    if (nested.length === 0 && isInlineReference(field)) {
         throw new Error(`Building the collection for “${searchType.name}” needs the search schema its surfaced inline reference “${field.name}” resolves against; pass it as the collection-definition option “schema”.`);
     }
     return nested;
@@ -143,10 +142,10 @@ function typesenseFields(searchType, field, defaultLocale, defaultSortingField,
     if (isInternalField(field)) {
         return [];
     }
-    const nested = nestedTypeOf(searchType, field, schema);
-    if (nested !== undefined) {
+    const nested = nestedTypesOf(searchType, field, schema);
+    if (nested.length > 0) {
         return [
-            ...nestedFields(field.name, field, nested, schema, defaultLocale, false, 
+            ...nestedObjectFields(field.name, field, nested, nested.length > 1, schema, defaultLocale, false, 
             // The declaring type is already on the path, exactly as the frame and
             // the extraction seed theirs, so a lookup back to it is cut at the
             // same depth here as it is there.
@@ -260,6 +259,39 @@ function typesenseFields(searchType, field, defaultLocale, defaultSortingField,
  * the children rather than declared, and this is the one place that invariant
  * can be got wrong.
  */
+function nestedObjectFields(prefix, reference, nestedTypes, polymorphic, schema, defaultLocale, withinArray, onPath) {
+    // `polymorphic` is about the DECLARATION, `nestedTypes` about what is
+    // descended into here: a lookup naming several targets of which only one is
+    // still off the path stores a discriminator all the same.
+    if (!polymorphic) {
+        return nestedFields(prefix, reference, nestedTypes[0], schema, defaultLocale, withinArray, onPath);
+    }
+    // A lookup naming several targets stores a referent of whichever kind it
+    // turns out to be under ONE nested object, so the object declares the union
+    // of the targets’ fields – each declared once, and `searchSchema` has
+    // already refused two targets declaring one name differently – plus the
+    // discriminator the projection writes to say which kind an entry is.
+    const byName = new Map();
+    for (const nestedType of nestedTypes) {
+        for (const declared of nestedFields(prefix, reference, nestedType, schema, defaultLocale, withinArray, onPath)) {
+            if (!byName.has(declared.name)) {
+                byName.set(declared.name, declared);
+            }
+        }
+    }
+    const flattensToArray = withinArray || reference.array === true;
+    const children = [...byName.values()].filter((declared) => declared.name !== prefix);
+    children.push(targetField(prefix, flattensToArray));
+    return [
+        {
+            name: prefix,
+            type: flattensToArray ? 'object[]' : 'object',
+            index: children.some((child) => child.index !== false),
+            optional: reference.required !== true,
+        },
+        ...children,
+    ];
+}
 function nestedFields(prefix, reference, nestedType, schema, defaultLocale, withinArray = false, onPath = new Set()) {
     const array = reference.array === true;
     // A type already on this path is not descended into again. `searchSchema`
@@ -292,8 +324,11 @@ function nestedFields(prefix, reference, nestedType, schema, defaultLocale, with
         if (isInternalField(field)) {
             continue;
         }
-        const deeper = nestedTypeOfNestedField(field, schema);
-        if (deeper !== undefined && walked.has(deeper.name)) {
+        const deeper = nestedTypesOfNestedField(field, schema);
+        // Descend into the types not yet on the path; where every one is, the
+        // cycle stops here.
+        const descend = deeper.filter((type) => !walked.has(type.name));
+        if (deeper.length > 0 && descend.length === 0) {
             // The cycle stops here, and so does the frame – but a value is still
             // stored: the extraction falls back to the target's key hop, and the
             // projection writes the referent as an `{id}` object beside its identity
@@ -309,7 +344,10 @@ function nestedFields(prefix, reference, nestedType, schema, defaultLocale, with
                 // leaf a filter welds on sits beside the object, not inside it.
                 index: false,
                 optional: true,
-            }, {
+            }, 
+            // A cut lookup naming several targets still says which one it
+            // stored, exactly as an expanded one does.
+            ...(deeper.length > 1 ? [targetField(boundary, boundaryArray)] : []), {
                 // Always a Root Type, so always identified: `searchSchema` rejects
                 // inline cycles, so the only way to arrive at a type already on the
                 // path is a `local` lookup, whose target declares a class.
@@ -320,8 +358,8 @@ function nestedFields(prefix, reference, nestedType, schema, defaultLocale, with
             }, ...nestedIdentityFields(prefix, field, schema, flattensToArray));
             continue;
         }
-        if (deeper !== undefined) {
-            children.push(...nestedFields(nestedFieldName(prefix, field.name), field, deeper, schema, defaultLocale, flattensToArray, walked), 
+        if (descend.length > 0) {
+            children.push(...nestedObjectFields(nestedFieldName(prefix, field.name), field, descend, deeper.length > 1, schema, defaultLocale, flattensToArray, walked), 
             // A nested field that stores an object cannot be filtered as itself,
             // and its own id is a level deeper than a condition can be welded to –
             // an engine welds conditions on an entry's LEAF fields only. Its
@@ -414,11 +452,24 @@ function nestedIdentityFields(prefix, field, schema, flattensToArray) {
         },
     ];
 }
-/** The type a *nested* field itself nests: another inline reference’s type, or
- *  the Root Type a {@link ReferenceStrategy.local local} lookup projects its
- *  endpoint through. */
-function nestedTypeOfNestedField(field, schema) {
-    return nestedReferenceType(schema, field) ?? localLookupTypeOf(field, schema);
+/** The stored discriminator of a lookup naming several targets
+ *  ({@link TARGET_FIELD}): a stored value, never indexed. */
+function targetField(prefix, array) {
+    return {
+        name: nestedFieldName(prefix, TARGET_FIELD),
+        type: array ? 'string[]' : 'string',
+        index: false,
+        optional: true,
+    };
+}
+/** The types a field nests: another inline reference’s type, or the Root
+ *  Types a {@link ReferenceStrategy.local local} lookup projects its endpoint
+ *  through. */
+function nestedTypesOfNestedField(field, schema) {
+    const referenceType = nestedReferenceType(schema, field);
+    return referenceType === undefined
+        ? localLookupTargetsOf(field, schema)
+        : [referenceType];
 }
 /**
  * The Physical Fields one non-nesting nested field contributes: exactly what

package/dist/lookup.d.ts

@@ -16,16 +16,26 @@ import { type ReferenceProjection, type RootType, type SearchSchema, type Search
  */
 export type ResolvedReferents = {
     readonly via: 'lookup';
-    /** The Root Type these referents are declared by – reconstruction reads
-     *  them through the target’s own declaration, never the referrer’s. */
-    readonly target: RootType;
-    readonly documents: ReadonlyMap<string, Record<string, unknown>>;
-    /** Keyed by the reference field’s name on the type this level carries. */
-    readonly children: ReadonlyMap<string, ResolvedReferents>;
+    /** By IRI. A lookup naming several targets holds referents of any of
+     *  them here, each saying which. */
+    readonly documents: ReadonlyMap<string, ResolvedReferent>;
+    /** The levels below, by target name – what a stored referent no
+     *  collection answered for is reconstructed against. */
+    readonly childrenByTarget: ReadonlyMap<string, ReadonlyMap<string, ResolvedReferents>>;
 } | {
     readonly via: 'nested';
     readonly children: ReadonlyMap<string, ResolvedReferents>;
 };
+/** One referent a lookup level fetched. */
+export interface ResolvedReferent {
+    /** The Root Type this referent is declared by – the target whose collection
+     *  answered for it. Reconstruction reads it through that target’s own
+     *  declaration, never the referrer’s. */
+    readonly target: RootType;
+    readonly document: Record<string, unknown>;
+    /** The levels below, keyed by the reference field’s name on `target`. */
+    readonly children: ReadonlyMap<string, ResolvedReferents>;
+}
 /**
  * Resolve a projection against the documents that name its referents: one
  * batched `multi_search` **per level**, never per document, because the IRIs of

package/dist/lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAUrB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GACzB;IACE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB;2EACuE;IACvE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjE,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3D,GACD;IACE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3D,CAAC;AAKN;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,UAAU,EAAE,mBAAmB,GAAG,SAAS,EAC3C,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAwFjD"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../src/lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAUrB;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GACzB;IACE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB;wCACoC;IACpC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC1D;4DACwD;IACxD,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CACpC,MAAM,EACN,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CACvC,CAAC;CACH,GACD;IACE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3D,CAAC;AAEN,2CAA2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B;;6CAEyC;IACzC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC3D;AAKD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,UAAU,EAAE,mBAAmB,GAAG,SAAS,EAC3C,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,YAAY,EACpB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACxC,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GACjC,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAmHjD"}

package/dist/lookup.js

@@ -1,4 +1,4 @@
-import { displayFieldName, fieldNamed, labelFieldOf, nestedReferenceType, rootTypeNamed, } from '@lde/search/adapter';
+import { displayFieldName, fieldNamed, labelFieldOf, nestedReferenceType, referencedTargetsOf, } from '@lde/search/adapter';
 import { escapeFilterValue } from './query-compiler.js';
 /** Typesense caps a filter list; the same batch size the label lookup uses. */
 const BATCH_SIZE = 200;
@@ -43,30 +43,51 @@ export async function resolveProjection(client, projection, searchType, schema,
             // hand-built query from throwing here rather than at the port’s guard.
             return undefined;
         }
-        const target = rootTypeNamed(schema, field.ref.target);
-        const collection = target === undefined ? undefined : collections.get(target.class);
-        if (target === undefined || collection === undefined) {
+        const targets = referencedTargetsOf(field, schema).filter((target) => collections.has(target.class));
+        const iris = distinctIris(parents, name);
+        if (targets.length === 0 || iris.length === 0) {
             return undefined;
         }
-        const include = includeFields(target, level.fields, level.resolve);
-        const iris = distinctIris(parents, name);
-        // Nothing to read: no referent named, or the selection reduced to the
-        // `id` the referring document already carries.
-        if (iris.length === 0 || include.length <= 1) {
+        // One fetch per target, concurrently: a referent lives in one of the
+        // collections, and which one is what a lookup naming several targets
+        // exists to find out – so with several, every collection is asked even
+        // for a selection reduced to `id`, since the answer types the referent.
+        // With one target, a selection reduced to the `id` the referring
+        // document already carries reads nothing.
+        const perTarget = await Promise.all(targets.map(async (target) => {
+            const include = includeFields(target, level.fields, level.resolve);
+            if (targets.length === 1 && include.length <= 1) {
+                return undefined;
+            }
+            const fetched = await fetchReferents(client, collections.get(target.class), iris, include, onError);
+            // The level below reads the IRIs off the documents this one just
+            // fetched – one more round-trip for the page, whatever its size.
+            const children = await resolveProjection(client, level.resolve, target, schema, collections, [...fetched.values()], onError);
+            return { target, fetched, children };
+        }));
+        // Declaration order is precedence: an IRI two collections hold belongs
+        // to the target declared first.
+        const documents = new Map();
+        const childrenByTarget = new Map();
+        for (const resolved of perTarget) {
+            if (resolved === undefined) {
+                continue;
+            }
+            childrenByTarget.set(resolved.target.name, resolved.children);
+            for (const [iri, document] of resolved.fetched) {
+                if (!documents.has(iri)) {
+                    documents.set(iri, {
+                        target: resolved.target,
+                        document,
+                        children: resolved.children,
+                    });
+                }
+            }
+        }
+        if (perTarget.every((resolved) => resolved === undefined)) {
             return undefined;
         }
-        const documents = await fetchReferents(client, collection, iris, include, onError);
-        return [
-            name,
-            {
-                via: 'lookup',
-                target,
-                documents,
-                // The level below reads the IRIs off the documents this one just
-                // fetched – one more round-trip for the page, whatever its size.
-                children: await resolveProjection(client, level.resolve, target, schema, collections, [...documents.values()], onError),
-            },
-        ];
+        return [name, { via: 'lookup', documents, childrenByTarget }];
     }));
     for (const level of levels) {
         if (level !== undefined) {
@@ -142,8 +163,12 @@ function includeFields(target, wanted, below) {
             physical.add(field.name);
         }
     }
+    // With several targets the level below merges every target’s selection,
+    // so ask each collection only for the reference fields it declares.
     for (const name of Object.keys(below ?? {})) {
-        physical.add(name);
+        if (fieldNamed(target, name) !== undefined) {
+            physical.add(name);
+        }
     }
     return [...physical];
 }

package/dist/query-compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-compiler.d.ts","sourceRoot":"","sources":["../src/query-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,QAAQ,EAEb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EAIhB,MAAM,aAAa,CAAC;AAoBrB;mDACmD;AACnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB,UAAU,GAAG,SAAS,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,wBAA6B,GACrC,YAAY,CAAC,MAAM,CAAC,CAkCtB;AAggBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"query-compiler.d.ts","sourceRoot":"","sources":["../src/query-compiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAEzE,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,QAAQ,EAEb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,UAAU,EAIhB,MAAM,aAAa,CAAC;AAoBrB;mDACmD;AACnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CACvB,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB,UAAU,GAAG,SAAS,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,UAAU,EACtB,OAAO,GAAE,wBAA6B,GACrC,YAAY,CAAC,MAAM,CAAC,CAkCtB;AAwgBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/query-compiler.js

@@ -1,5 +1,5 @@
 import { fold } from '@lde/text-normalization';
-import { fieldNamed, filterOperator, filterOperatorFor, ID_FIELD, isoToUnixSeconds, isInternalField, isRangeFacet, isWelded, joinGraph, localLookupTypeOf, matchLanguage, pageForOffset, physicalFields, nestedReferenceType, resolvePath, searchableFields, } from '@lde/search/adapter';
+import { fieldNamed, filterOperator, filterOperatorFor, ID_FIELD, isoToUnixSeconds, isInternalField, isRangeFacet, isWelded, joinGraph, localLookupTargetsOf, matchLanguage, 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),
@@ -138,14 +138,22 @@ function collectSearchable(searchType, locale, schema, prefix, onPath, names, we
         if (isInternalField(field)) {
             continue;
         }
-        const nested = nestedReferenceType(schema, field) ?? localLookupTypeOf(field, schema);
+        const referenceType = nestedReferenceType(schema, field);
+        const nested = referenceType === undefined
+            ? localLookupTargetsOf(field, schema)
+            : [referenceType];
         // Cut on the CHILD, not on entry, and against the set this level was
         // reached with – the same boundary the collection's own walk cuts at
         // (`nestedFields`). Returning on entry instead skipped the companions of
         // the level the collection HAD declared, leaving them indexed and absent
-        // from `query_by` wherever a type reached itself.
-        if (nested !== undefined && !onPath.has(nested.name)) {
-            collectSearchable(nested, locale, schema, qualify(prefix, field.name), walked, names, weights);
+        // from `query_by` wherever a type reached itself. Several targets each
+        // contribute their searchable fields: the one nested object declares them
+        // all, and free text has to reach a referent of either kind.
+        for (const nestedType of nested) {
+            if (onPath.has(nestedType.name)) {
+                continue;
+            }
+            collectSearchable(nestedType, locale, schema, qualify(prefix, field.name), walked, names, weights);
         }
     }
 }

package/dist/search.d.ts.map

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

package/dist/search.js

@@ -1,7 +1,8 @@
-import { assertTypeInSchema, assertValidQuery, displayLangOf, facetableFields, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNameOf, labelTargetNameOf, localLookupTypeOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { NESTED_DOCUMENT_TYPE, } from '@lde/search';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, facetableFields, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNamesOf, labelTargetNamesOf, localLookupTargetsOf, nestedReferenceType, outputFields, physicalFields, referencedTargetsOf, referenceFields, storedTargetOf, } from '@lde/search/adapter';
 import { buildSearchParams, escapeFilterValue, } from './query-compiler.js';
 import { deriveCollectionName } from './collection-name.js';
-import { resolveProjection } from './lookup.js';
+import { resolveProjection, } from './lookup.js';
 /**
  * A Typesense-backed {@link SearchEngine}, bound to the whole
  * {@link SearchSchema} at construction – like every other schema consumer.
@@ -65,25 +66,27 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
     // (`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]));
+    // Per field, one source per target it names, in order of precedence – a
+    // reference naming several targets reads labels from every one of them.
     const labelSources = new Map([...schema.values()].map((searchType) => [
         searchType.class,
         new Map(referenceFields(searchType)
             // 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(labelTargetNameOf(field, schema));
-            const labelField = labelFieldOf(source);
-            return [
-                field.name,
-                {
+            .filter((field) => labelTargetNamesOf(field, schema).length > 0)
+            .map((field) => [
+            field.name,
+            labelTargetNamesOf(field, schema).map((targetName) => {
+                const source = typesByName.get(targetName);
+                const labelField = labelFieldOf(source);
+                return {
                     collection: collections.get(source.class),
                     labelField,
                     queryBy: physicalFields(labelField).search.join(','),
-                },
-            ];
-        })),
+                };
+            }),
+        ])),
     ]));
     // Typesense reports a facet under the field it faceted, which for a reference
     // inheriting a facet policy is the `${name}_facet` companion, not the
@@ -106,7 +109,9 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
     const distinctLabelSources = new Map([...labelSources].map(([type, sources]) => [
         type,
         [
-            ...new Map([...sources.values()].map((source) => [source.collection, source])).values(),
+            ...new Map([...sources.values()]
+                .flat()
+                .map((source) => [source.collection, source])).values(),
         ],
     ]));
     // The output reference fields that carry hit labels, each paired with its
@@ -128,10 +133,10 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
                 // the entry – and their FACET buckets are labelled by a separate
                 // path that reads the companion.
                 nestedReferenceType(schema, field) === undefined &&
-                localLookupTypeOf(field, schema) === undefined)
+                localLookupTargetsOf(field, schema).length === 0)
                 .map((field) => ({
                 name: field.name,
-                source: sources.get(field.name),
+                sources: sources.get(field.name),
             })),
         ];
     }));
@@ -242,7 +247,7 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // in the body, so the filter is bounded by the caller's request, not by
             // the URL.
             const response = withDeclaredFacetNames(await performSingleSearch(client, collections.get(searchType.class), params), declaredFacetNames.get(searchType.class));
-            const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups([response], labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? []));
+            const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups([response], labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? [], distinctLabelSources.get(searchType.class) ?? []));
             // What the caller asked to resolve, level by level. Independent of the
             // label lookup above: that one serves facet buckets and unprojected
             // references, and stays cacheable because a label is one small value.
@@ -286,7 +291,7 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
                 : withDeclaredFacetNames(result, declaredNames));
             // One label lookup serves every successful facet result in the batch.
             const responses = results.filter((result) => !('error' in result));
-            const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups(responses, labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? []));
+            const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups(responses, labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? [], distinctLabelSources.get(searchType.class) ?? []));
             // 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 –
@@ -371,33 +376,40 @@ async function loadAllLabels(client, source) {
  * source, one group per source collection. Fields without a `labelSource`
  * stay id-only, so their IRIs never travel.
  */
-function labelLookupGroups(responses, sources, outputSources) {
+function labelLookupGroups(responses, sources, outputSources, ordered) {
     if (sources === undefined || sources.size === 0) {
         return [];
     }
-    const irisByCollection = new Map();
-    const add = (source, iri) => {
-        let group = irisByCollection.get(source.collection);
-        if (group === undefined) {
-            group = { source, iris: new Set() };
-            irisByCollection.set(source.collection, group);
+    // One group per collection, in the order the TYPE’s fields first name them
+    // – seeded up front rather than in the order the hits happen to mention
+    // them, because `fetchLabels` reads group order as precedence and a label
+    // is resolved per type, not per field: an IRI two collections hold gets the
+    // label of the one the type declares first, whichever field carried it.
+    const irisByCollection = new Map(ordered.map((source) => [
+        source.collection,
+        { source, iris: new Set() },
+    ]));
+    // An IRI of a field naming several targets travels to EVERY one of their
+    // collections: which holds it is not known until one answers.
+    const add = (fieldSources, iri) => {
+        for (const source of fieldSources) {
+            irisByCollection.get(source.collection)?.iris.add(iri);
         }
-        group.iris.add(iri);
     };
     for (const response of responses) {
         // Hits only carry labels for OUTPUT reference fields (reconstructDocument
         // skips non-output fields); `outputSources` pairs each with its resolved
         // source, precomputed per type.
         for (const hit of response.hits ?? []) {
-            for (const { name, source } of outputSources) {
+            for (const { name, sources: fieldSources } of outputSources) {
                 const raw = hit.document[name];
                 if (Array.isArray(raw)) {
                     for (const value of raw) {
-                        add(source, String(value));
+                        add(fieldSources, String(value));
                     }
                 }
                 else if (typeof raw === 'string') {
-                    add(source, raw);
+                    add(fieldSources, raw);
                 }
             }
         }
@@ -405,19 +417,18 @@ function labelLookupGroups(responses, sources, outputSources) {
         // like `class`); resolve them in the same lookup. Skip a non-source facet
         // (e.g. a keyword facet) in one check instead of probing every bucket.
         for (const facet of response.facet_counts ?? []) {
-            const source = sources.get(facet.field_name);
-            if (source === undefined) {
+            const facetSources = sources.get(facet.field_name);
+            if (facetSources === undefined) {
                 continue;
             }
             for (const bucket of facet.counts) {
-                add(source, bucket.value);
+                add(facetSources, bucket.value);
             }
         }
     }
-    return [...irisByCollection.values()].map(({ source, iris }) => ({
-        source,
-        iris: [...iris],
-    }));
+    return [...irisByCollection.values()]
+        .filter(({ iris }) => iris.size > 0)
+        .map(({ source, iris }) => ({ source, iris: [...iris] }));
 }
 /**
  * The response with each facet filed under the declared field name its engine
@@ -504,9 +515,17 @@ export async function fetchLabels(client, groups, onError) {
             return;
         }
         for (const hit of result.hits ?? []) {
+            const id = String(hit.document.id);
+            // First group wins: the groups arrive in the order a field declares its
+            // targets, so an IRI two collections hold is labelled by the target
+            // declared first – the same precedence the lookup and the projection
+            // apply.
+            if (labels.has(id)) {
+                continue;
+            }
             const label = localizedValue(hit.document, groupPerSearch[index].source.labelField);
             if (label !== undefined) {
-                labels.set(String(hit.document.id), label);
+                labels.set(id, label);
             }
         }
     });
@@ -523,7 +542,10 @@ function mergeLabels(maps) {
     const merged = new Map();
     for (const map of maps) {
         for (const [iri, label] of map) {
-            merged.set(iri, label);
+            // First source wins, as it does for a fetched lookup (`fetchLabels`).
+            if (!merged.has(iri)) {
+                merged.set(iri, label);
+            }
         }
     }
     return merged;
@@ -552,7 +574,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) => labelTargetNameOf(field, schema) !== undefined)
+        .filter((field) => labelTargetNamesOf(field, schema).length > 0)
         .map((field) => field.name));
     const facets = {};
     for (const facet of response.facet_counts ?? []) {
@@ -606,15 +628,15 @@ function logicalValue(flat, field, labels, schema, referents) {
             if (nested !== undefined) {
                 // 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);
+                return nestedValue(flat[field.name], field, nested, labels, schema, resolved?.via === 'nested' ? resolved.children : undefined);
             }
             // 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);
+            const localTargets = localLookupTargetsOf(field, schema);
+            if (localTargets.length > 0) {
+                return localLookupValue(flat[field.name], field, localTargets, 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,
@@ -687,12 +709,7 @@ function localizedValue(flat, field) {
  */
 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, children);
-        return typeof referent.id === 'string'
-            ? { id: referent.id, ...document }
-            : document;
-    });
+    const documents = referents.map((referent) => nestedDocument(referent, referenceType, labels, schema, children));
     if (documents.length === 0) {
         return undefined;
     }
@@ -717,16 +734,51 @@ function nestedValue(raw, field, referenceType, labels, schema, children) {
  *   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 entries = (Array.isArray(raw) ? raw : [raw])
+function localLookupValue(raw, field, targets, resolved, labels, schema) {
+    const fetched = resolved?.via === 'lookup'
+        ? resolved.documents
+        : new Map();
+    const documents = (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 ?? entry;
+        // An entry no collection answered for is read through the declaration
+        // it was stored under – which it says itself where there were several
+        // to choose from, and the only one otherwise.
+        if (authoritative !== undefined) {
+            return typedDocument(targets.length > 1, authoritative.target, nestedDocument(authoritative.document, authoritative.target, labels, schema, authoritative.children));
+        }
+        // Its own lookups resolve against the level its target’s fetch carried
+        // down, so a nested IRI it shares with a fetched referent still nests.
+        const target = storedTargetOf(entry, targets);
+        return typedDocument(targets.length > 1, target, nestedDocument(entry, target, labels, schema, resolved?.via === 'lookup'
+            ? resolved.childrenByTarget.get(target.name)
+            : undefined));
     });
-    return nestedValue(entries, field, target, labels, schema, resolved?.children);
+    if (documents.length === 0) {
+        return undefined;
+    }
+    return field.array === true ? documents : documents[0];
+}
+/**
+ * A nested document read through one of a lookup’s **several** targets, marked
+ * with that type’s name ({@link NESTED_DOCUMENT_TYPE}) so a surface can tell
+ * which it is – the marker is a symbol, so it never surfaces as a field. A
+ * single-target lookup marks nothing: there is nothing to tell apart.
+ */
+function typedDocument(polymorphic, target, document) {
+    return polymorphic
+        ? { ...document, [NESTED_DOCUMENT_TYPE]: target.name }
+        : document;
+}
+/** One nested document rebuilt from a flat referent, carrying its `id` where
+ *  it has one – the shared body of every nesting that reads a referent. */
+function nestedDocument(referent, searchType, labels, schema, children) {
+    const document = reconstructDocument(referent, searchType, labels, schema, children);
+    return typeof referent.id === 'string'
+        ? { id: referent.id, ...document }
+        : document;
 }
 /**
  * Rebuild a resolved `lookup` reference: each stored IRI becomes the referent’s
@@ -741,14 +793,15 @@ function lookupValue(raw, field, resolved, labels, schema) {
         return undefined;
     }
     const iris = Array.isArray(raw) ? raw : [String(raw)];
+    const polymorphic = referencedTargetsOf(field, schema).length > 1;
     const documents = iris.map((iri) => {
         const referent = resolved.documents.get(iri);
         return referent === undefined
             ? { id: iri }
-            : {
+            : typedDocument(polymorphic, referent.target, {
                 id: iri,
-                ...reconstructDocument(referent, resolved.target, labels, schema, resolved.children),
-            };
+                ...reconstructDocument(referent.document, referent.target, labels, schema, referent.children),
+            });
     });
     return field.array === true ? documents : documents[0];
 }
@@ -763,7 +816,7 @@ function referenceValue(flat, field, labels) {
         // A reference that resolves nothing is id-only by declaration; never attach
         // a label, even if the (cached, full-collection) map happens to hold this
         // IRI from another source.
-        const label = labelSourceNameOf(field) === undefined ? undefined : labels.get(iri);
+        const label = labelSourceNamesOf(field).length === 0 ? undefined : labels.get(iri);
         return label === undefined ? { id: iri } : { id: iri, label };
     });
     return field.array === true ? references : references[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search-typesense",
-  "version": "0.33.1",
+  "version": "0.35.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.28.1",
+    "@lde/search": "^0.29.0",
     "@lde/text-normalization": "^0.2.0",
     "tslib": "^2.3.0",
     "typesense": "^3.1.1"
@@ -36,6 +36,6 @@
   },
   "peerDependencies": {
     "@lde/dataset": "^0.8.0",
-    "@lde/pipeline": "^0.37.0"
+    "@lde/pipeline": "^0.38.0"
   }
 }