@lde/search-typesense 0.24.1 → 0.25.0

package/dist/lookup.d.ts

@@ -0,0 +1,30 @@
+import type { Client } from 'typesense';
+import { type ReferenceProjection, type RootType, type SearchSchema, type SearchType } from '@lde/search';
+/**
+ * One resolved level of a {@link ReferenceProjection}: the referents fetched
+ * for it, keyed by IRI and still in the engine’s flat physical shape, plus the
+ * levels resolved *from* them.
+ *
+ * Kept flat rather than reconstructed here so one reconstruction path serves
+ * hits and referents alike – the surface never learns that a nested document
+ * arrived by a second round-trip rather than from the hit itself.
+ */
+export interface ResolvedReferents {
+    /** 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>;
+}
+/**
+ * Resolve a projection against the documents that name its referents: one
+ * batched `multi_search` **per level**, never per document, because the IRIs of
+ * a level are deduped across the whole page before the round-trip and grouped
+ * by the collection they live in.
+ *
+ * Failure degrades rather than throws: an unresolved level leaves its
+ * references as bare ids, exactly as an unresolved label does.
+ */
+export declare function resolveProjection(client: Pick<Client, 'multiSearch'>, projection: ReferenceProjection | undefined, searchType: SearchType, schema: SearchSchema, collections: ReadonlyMap<string, string>, parents: readonly Record<string, unknown>[], onError?: (error: unknown) => void): Promise<ReadonlyMap<string, ResolvedReferents>>;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/lookup.d.ts.map

@@ -0,0 +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;AAQrB;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC;sEACkE;IAClE,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;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,CAqEjD"}

package/dist/lookup.js

@@ -0,0 +1,141 @@
+import { displayFieldName, fieldNamed, labelFieldOf, } 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;
+/**
+ * Resolve a projection against the documents that name its referents: one
+ * batched `multi_search` **per level**, never per document, because the IRIs of
+ * a level are deduped across the whole page before the round-trip and grouped
+ * by the collection they live in.
+ *
+ * Failure degrades rather than throws: an unresolved level leaves its
+ * references as bare ids, exactly as an unresolved label does.
+ */
+export async function resolveProjection(client, projection, searchType, schema, collections, parents, onError) {
+    const resolved = new Map();
+    if (projection === undefined || parents.length === 0) {
+        return resolved;
+    }
+    const targetsByName = new Map([...schema.values()].map((rootType) => [rootType.name, rootType]));
+    // The level's fields resolve CONCURRENTLY: they read from different
+    // collections and nothing links them, so running them in turn would make the
+    // stated bound – one round-trip per level – one per field instead.
+    const levels = await Promise.all(Object.entries(projection).map(async ([name, level]) => {
+        const field = fieldNamed(searchType, name);
+        if (field === undefined ||
+            field.kind !== 'reference' ||
+            field.ref?.strategy !== 'lookup') {
+            // `assertValidQuery` rejects this for every caller; skipping keeps a
+            // hand-built query from throwing here rather than at the port’s guard.
+            return undefined;
+        }
+        const target = targetsByName.get(field.ref.target);
+        const collection = target === undefined ? undefined : collections.get(target.class);
+        if (target === undefined || collection === undefined) {
+            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) {
+            return undefined;
+        }
+        const documents = await fetchReferents(client, collection, iris, include, onError);
+        return [
+            name,
+            {
+                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),
+            },
+        ];
+    }));
+    for (const level of levels) {
+        if (level !== undefined) {
+            resolved.set(level[0], level[1]);
+        }
+    }
+    return resolved;
+}
+/** Every distinct IRI a page of documents carries under one reference field. */
+function distinctIris(documents, field) {
+    const iris = new Set();
+    for (const document of documents) {
+        const raw = document[field];
+        for (const value of Array.isArray(raw) ? raw : [raw]) {
+            if (typeof value === 'string' && value !== '') {
+                iris.add(value);
+            }
+        }
+    }
+    return [...iris];
+}
+/**
+ * The physical fields a level needs: the target’s `id`, the physical fanout of
+ * each logical field it asked for, and the reference fields the level below
+ * reads its IRIs from. Asking for a field set rather than the whole document is
+ * what keeps a lookup’s cost proportional to the query rather than to how wide
+ * the target happens to be.
+ *
+ * With no `fields`, a level carries the target’s label alone – what every
+ * reference carried before a projection could ask for more.
+ */
+function includeFields(target, wanted, below) {
+    const labelField = labelFieldOf(target);
+    const names = wanted ?? (labelField === undefined ? [] : [labelField.name]);
+    const physical = new Set(['id']);
+    for (const name of names) {
+        const field = fieldNamed(target, name);
+        if (field === undefined || field.output !== true) {
+            continue;
+        }
+        if (field.kind === 'text') {
+            for (const locale of field.locales) {
+                physical.add(displayFieldName(field, locale));
+            }
+        }
+        else {
+            physical.add(field.name);
+        }
+    }
+    for (const name of Object.keys(below ?? {})) {
+        physical.add(name);
+    }
+    return [...physical];
+}
+/** Fetch a level’s referents by IRI, batched, as flat engine documents. */
+async function fetchReferents(client, collection, iris, include, onError) {
+    const documents = new Map();
+    const searches = [];
+    for (let start = 0; start < iris.length; start += BATCH_SIZE) {
+        const batch = iris.slice(start, start + BATCH_SIZE);
+        searches.push({
+            collection,
+            q: '*',
+            filter_by: `id:[${batch.map(escapeFilterValue).join(',')}]`,
+            include_fields: include.join(','),
+            per_page: batch.length,
+        });
+    }
+    try {
+        const { results } = (await client.multiSearch.perform({ searches }));
+        for (const result of results) {
+            // multi_search reports a failed entry inline instead of rejecting;
+            // isolate it, so the other batches' referents still land.
+            if (result.error !== undefined) {
+                onError?.(new Error(`Typesense reference lookup in “${collection}” failed: ${result.error}`));
+                continue;
+            }
+            for (const hit of result.hits ?? []) {
+                documents.set(String(hit.document.id), hit.document);
+            }
+        }
+    }
+    catch (error) {
+        onError?.(error);
+    }
+    return documents;
+}

package/dist/search.d.ts

@@ -1,6 +1,7 @@
 import type { Client } from 'typesense';
 import { type LocalizedValue, type RootTypeOf, type SearchEngine, type SearchResult, type SearchSchema, type SearchType, type TextField } from '@lde/search';
 import { type BuildSearchParamsOptions } from './query-compiler.js';
+import { type ResolvedReferents } from './lookup.js';
 /** Where the engine reads documents – plus every query-compiler knob
  *  ({@link BuildSearchParamsOptions}), declared once there and forwarded
  *  wholesale into each search. Reference labels resolve per field from the
@@ -127,5 +128,5 @@ export interface TypesenseSearchResponse {
  * does not declare a field’s reference type reconstructs nothing for it rather
  * than the wrong shape, the same call the projection makes.
  */
-export declare function parseSearchResponse(response: TypesenseSearchResponse, searchType: SearchType, labels: ReadonlyMap<string, LocalizedValue>, schema: SearchSchema): SearchResult;
+export declare function parseSearchResponse(response: TypesenseSearchResponse, searchType: SearchType, labels: ReadonlyMap<string, LocalizedValue>, schema: SearchSchema, referents?: ReadonlyMap<string, ResolvedReferents>): SearchResult;
 //# sourceMappingURL=search.d.ts.map

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,6 +1,7 @@
-import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, nestedReferenceType, outputFields, physicalFields, referenceFields, } from '@lde/search/adapter';
+import { assertTypeInSchema, assertValidQuery, displayLangOf, fieldNamed, isInlineReference, isRangeFacet, isUnsatisfiable, joinGraph, labelFieldOf, labelSourceNameOf, 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';
 /**
  * A Typesense-backed {@link SearchEngine}, bound to the whole
  * {@link SearchSchema} at construction – like every other schema consumer.
@@ -66,9 +67,9 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
     const labelSources = new Map([...schema.values()].map((searchType) => [
         searchType.class,
         new Map(referenceFields(searchType)
-            .filter((field) => field.labelSource !== undefined)
+            .filter((field) => labelSourceNameOf(field) !== undefined)
             .map((field) => {
-            const source = typesByName.get(field.labelSource);
+            const source = typesByName.get(labelSourceNameOf(field));
             const labelField = labelFieldOf(source);
             return [
                 field.name,
@@ -194,7 +195,7 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // invalid query (unknown field, wrong operator, unknown facet) are both
             // rejected up front, for EVERY caller.
             assertTypeInSchema(schema, searchType);
-            assertValidQuery(query, searchType, joins);
+            assertValidQuery(query, searchType, schema, joins);
             // Asks for no document (an empty `id` membership): answer it without a
             // round-trip rather than dispatching a query whose only filter compiles
             // away, which would hand back the whole collection.
@@ -211,12 +212,16 @@ export function createTypesenseSearchEngine(client, schema, options = {}) {
             // the URL.
             const response = await performSingleSearch(client, collections.get(searchType.class), params);
             const labels = await resolveLabels(cachedLabelsPromise, () => labelLookupGroups([response], labelSources.get(searchType.class), outputReferenceSources.get(searchType.class) ?? []));
-            return parseSearchResponse(response, searchType, labels, schema);
+            // 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.
+            const referents = await resolveProjection(client, query.resolve, searchType, schema, collections, (response.hits ?? []).map((hit) => hit.document), options.onLabelError);
+            return parseSearchResponse(response, searchType, labels, schema, referents);
         },
         async searchFacets(searchType, queries) {
             assertTypeInSchema(schema, searchType);
             for (const query of queries) {
-                assertValidQuery(query, searchType, joins);
+                assertValidQuery(query, searchType, schema, joins);
             }
             if (queries.length === 0) {
                 return [];
@@ -482,10 +487,10 @@ function mergeLabels(maps) {
  * does not declare a field’s reference type reconstructs nothing for it rather
  * than the wrong shape, the same call the projection makes.
  */
-export function parseSearchResponse(response, searchType, labels, schema) {
+export function parseSearchResponse(response, searchType, labels, schema, referents) {
     const hits = (response.hits ?? []).map((hit) => ({
         id: String(hit.document.id),
-        document: reconstructDocument(hit.document, searchType, labels, schema),
+        document: reconstructDocument(hit.document, searchType, labels, schema, referents),
     }));
     // Reference facets are IRI-keyed; their buckets carry a resolved data label.
     // Plain facets (tokens, free strings) carry no label – the consumer owns display.
@@ -493,7 +498,7 @@ export function parseSearchResponse(response, searchType, labels, schema) {
     // reference facet stays id-only even when a cached full-collection map holds
     // its IRIs.
     const referenceFacets = new Set(referenceFields(searchType)
-        .filter((field) => field.labelSource !== undefined)
+        .filter((field) => labelSourceNameOf(field) !== undefined)
         .map((field) => field.name));
     const facets = {};
     for (const facet of response.facet_counts ?? []) {
@@ -523,17 +528,17 @@ export function parseSearchResponse(response, searchType, labels, schema) {
     return { hits, total: response.found, facets };
 }
 /** Rebuild one logical document from a flat Typesense document. */
-function reconstructDocument(flat, searchType, labels, schema) {
+function reconstructDocument(flat, searchType, labels, schema, referents) {
     const document = {};
     for (const field of outputFields(searchType)) {
-        const value = logicalValue(flat, field, labels, schema);
+        const value = logicalValue(flat, field, labels, schema, referents);
         if (value !== undefined) {
             document[field.name] = value;
         }
     }
     return document;
 }
-function logicalValue(flat, field, labels, schema) {
+function logicalValue(flat, field, labels, schema, referents) {
     switch (field.kind) {
         case 'text':
             return localizedValue(flat, field);
@@ -546,6 +551,13 @@ function logicalValue(flat, field, labels, schema) {
             if (nested !== undefined) {
                 return nestedValue(flat[field.name], field, nested, 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) {
+                return lookupValue(flat[field.name], field, resolved, labels, schema);
+            }
             // A surfaced inline reference stores nested documents, not IRIs, so a
             // schema that does not declare its reference type (a type parsed against
             // a foreign schema) reconstructs nothing rather than the wrong shape –
@@ -616,6 +628,30 @@ function nestedValue(raw, field, referenceType, labels, schema) {
     }
     return field.array === true ? documents : documents[0];
 }
+/**
+ * Rebuild a resolved `lookup` reference: each stored IRI becomes the referent’s
+ * own document, read through the **target’s** declaration and carrying whatever
+ * the projection asked for. A referent the lookup did not return – an IRI with
+ * no document in the target’s collection, or a level whose round-trip failed –
+ * degrades to its bare `id` rather than dropping out, so a dangling reference
+ * still says which IRI it pointed at.
+ */
+function lookupValue(raw, field, resolved, labels, schema) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const iris = Array.isArray(raw) ? raw : [String(raw)];
+    const documents = iris.map((iri) => {
+        const referent = resolved.documents.get(iri);
+        return referent === undefined
+            ? { id: iri }
+            : {
+                id: iri,
+                ...reconstructDocument(referent, resolved.target, labels, schema, resolved.children),
+            };
+    });
+    return field.array === true ? documents : documents[0];
+}
 /** Map stored reference IRIs to labelled references; id-only when no label. */
 function referenceValue(flat, field, labels) {
     const raw = flat[field.name];
@@ -624,10 +660,10 @@ function referenceValue(flat, field, labels) {
     }
     const iris = Array.isArray(raw) ? raw : [String(raw)];
     const references = iris.map((iri) => {
-        // A reference without a label source 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 = field.labelSource === undefined ? undefined : labels.get(iri);
+        // 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);
         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.24.1",
+  "version": "0.25.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.21.1",
+    "@lde/search": "^0.22.0",
     "@lde/text-normalization": "^0.1.2",
     "tslib": "^2.3.0",
     "typesense": "^3.0.6"