@lde/search 0.3.1 → 0.4.1

package/README.md

@@ -203,6 +203,12 @@ A `reference` carries `labelOnly` today (id + display label); the `idOnly` and
 day one so that `inline` can later **add** fields to a reference type without
 breaking clients.
 
+A reference resolves its label from a **label source**: `labelSource` names
+the `SearchType` whose collection holds the referenced entities. The named
+type must declare an `output`, `searchable` text field called `label` –
+`searchSchema` validates this schema-wide, so a dangling or unsuitable label
+source fails at startup. A reference without a `labelSource` stays id-only.
+
 ## Projection
 
 `projectGraph` is fully streaming: subjects are grouped and framed one at a time
@@ -212,6 +218,21 @@ triples are collapsed first, because some SPARQL engines (e.g. QLever) do not
 deduplicate `CONSTRUCT` output. The IR carries no `@context`, so a `derive` function
 reading it sees full predicate IRIs with language tags preserved.
 
+`projectGraph` **consumes the quads once** – a single scan builds the subject
+index every type frames off – and so accepts any `Iterable<Quad>`, not just a
+materialized array. A caller merging several sources can pass a chained
+generator instead of building a third full array at the projection peak:
+
+```ts
+projectGraph(
+  (function* () {
+    yield* registerQuads;
+    yield* dkgQuads;
+  })(),
+  schema,
+);
+```
+
 ## Locales
 
 `locales` is the **single** list of locales a `text` field projects (`und` =
@@ -286,7 +307,7 @@ await engine.search(OTHER_TYPE, query); // compile error: not in this schema
 ```
 
 `searchFacets(type, queries)` is the port’s **batch entry point**: several
-facet-only queries – e.g. a faceted sidebar’s skip-own-filter variants –
+facet-only queries – e.g. a faceted listing’s skip-own-filter variants –
 answered in one engine round-trip (Typesense: a single `multi_search`), one
 outcome per query, positionally aligned – its facet map, or an in-place error,
 so one failed query never discards its siblings’ facets. The same schema

package/dist/adapter.d.ts

@@ -6,7 +6,7 @@
  * deployment author declaring a schema and running searches needs none of
  * this; the main entry point carries that (small) authoring surface.
  */
-export { assertTypeInSchema, physicalFields, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { assertTypeInSchema, physicalFields, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, labelFieldOf, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
 export type { PhysicalFields } from './schema.js';
 export { filterOperatorFor, filterOperator, validateQuery, assertValidQuery, pageForOffset, } from './query.js';
 export type { FilterOperator, QueryIssue } from './query.js';

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/adapter.js

@@ -6,5 +6,5 @@
  * deployment author declaring a schema and running searches needs none of
  * this; the main entry point carries that (small) authoring surface.
  */
-export { assertTypeInSchema, physicalFields, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
+export { assertTypeInSchema, physicalFields, searchableFields, facetableFields, filterableFields, sortableFields, outputFields, referenceFields, fieldNamed, labelFieldOf, isRangeFacet, isoToUnixSeconds, unixSecondsToIso, } from './schema.js';
 export { filterOperatorFor, filterOperator, validateQuery, assertValidQuery, pageForOffset, } from './query.js';

package/dist/engine.d.ts

@@ -40,7 +40,7 @@ export interface SearchEngine<Types extends readonly SearchType[] = readonly Sea
      * in a single engine round-trip (where the engine supports one, e.g.
      * Typesense `multi_search`), returning one {@link FacetsOutcome} per query,
      * positionally aligned with `queries`. This is what keeps a faceted
-     * sidebar – one skip-own-filter query variant per filtered facet – from
+     * listing – one skip-own-filter query variant per filtered facet – from
      * fanning out into per-facet engine calls. Only facet buckets come back: an
      * engine answers every query in the batch facet-only (as if `limit: 0` and
      * without ordering, whatever the query carries), so hits are never

package/dist/frame-by-type.d.ts

@@ -2,15 +2,45 @@ import type { Quad } from '@rdfjs/types';
 /** A framed JSON-LD node (full-IRI keys); the engine-agnostic search IR. */
 export type FramedNode = Record<string, unknown>;
 /**
- * Frame CONSTRUCT quads into one JSON-LD node per subject of `rootType`. Each
+ * A one-pass index of a quad source: every subject’s (deduplicated) triples,
+ * plus the root subjects of each requested type in appearance order. Built by
+ * {@link buildSubjectIndex} from a single iteration of the source, so a caller
+ * can pass a chained generator (`function* () { yield* a; yield* b; }`) rather
+ * than materialize a merged array; a multi-type projection then frames every
+ * type off this one index instead of re-scanning per type.
+ */
+export interface SubjectIndex {
+    /** Each subject IRI → its own deduplicated triples, in first-seen order. */
+    readonly bySubject: ReadonlyMap<string, readonly Quad[]>;
+    /** Each requested root type IRI → its root subjects, in appearance order. */
+    readonly rootsByType: ReadonlyMap<string, readonly string[]>;
+}
+/**
+ * Iterate `quads` once, grouping each subject’s triples and collecting the root
+ * subjects of every type in `rootTypes`. Duplicate triples are collapsed here
+ * because some SPARQL engines (e.g. QLever) do not deduplicate CONSTRUCT
+ * output. The source is consumed a single time, so it may be a one-shot
+ * iterable (a generator chaining several sources); the whole subject index is
+ * held, but never more than that plus one framed subgraph at a time
+ * downstream.
+ */
+export declare function buildSubjectIndex(quads: Iterable<Quad>, rootTypes: Iterable<string>): SubjectIndex;
+/**
+ * Frame every root subject of `rootType` from a prebuilt {@link SubjectIndex}
+ * into one JSON-LD node – the reusable core behind {@link frameByType}. Each
  * root subject’s own triples plus the one-hop nodes it references (e.g. nested
- * publisher/distribution resources) are grouped lazily and framed one at a
- * time, so beyond the subject index only a single subgraph is held — whole-graph
- * `jsonld.frame()` is ~O(N²). Duplicate triples are collapsed first because some
- * SPARQL engines
- * (e.g. QLever) do not dedupe CONSTRUCT output. The caller supplies the root
- * type, keeping the framing domain-agnostic; the frame carries no `@context`, so
- * framed keys are full predicate IRIs.
+ * publisher/distribution resources) are framed one subject at a time, so beyond
+ * the shared subject index only a single subgraph is held (whole-graph
+ * `jsonld.frame()` is ~O(N²)). The frame carries no `@context`, so framed keys
+ * are full predicate IRIs.
+ */
+export declare function frameSubjects(index: SubjectIndex, rootType: string): AsyncIterable<FramedNode>;
+/**
+ * Frame CONSTRUCT quads into one JSON-LD node per subject of `rootType`, for a
+ * single root type. Consumes `quads` once (see {@link buildSubjectIndex}), so
+ * it accepts any `Iterable` – a materialized array or a chained generator. For
+ * a multi-type schema, {@link buildSubjectIndex} + {@link frameSubjects} share
+ * one index across types rather than re-scanning per type.
  */
-export declare function frameByType(quads: readonly Quad[], rootType: string): AsyncIterable<FramedNode>;
+export declare function frameByType(quads: Iterable<Quad>, rootType: string): AsyncIterable<FramedNode>;
 //# sourceMappingURL=frame-by-type.d.ts.map

package/dist/frame-by-type.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frame-by-type.d.ts","sourceRoot":"","sources":["../src/frame-by-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAMzC,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAIjD;;;;;;;;;;GAUG;AACH,wBAAuB,WAAW,CAChC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,QAAQ,EAAE,MAAM,GACf,aAAa,CAAC,UAAU,CAAC,CAkB3B"}
+{"version":3,"file":"frame-by-type.d.ts","sourceRoot":"","sources":["../src/frame-by-type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAMzC,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAIjD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,CAAC,CAAC;IACzD,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CAC9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC1B,YAAY,CA8Bd;AAED;;;;;;;;GAQG;AACH,wBAAuB,aAAa,CAClC,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,GACf,aAAa,CAAC,UAAU,CAAC,CA+B3B;AAED;;;;;;GAMG;AACH,wBAAuB,WAAW,CAChC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,QAAQ,EAAE,MAAM,GACf,aAAa,CAAC,UAAU,CAAC,CAE3B"}

package/dist/frame-by-type.js

@@ -3,40 +3,20 @@ import { rdf } from '@tpluscode/rdf-ns-builders';
 const RDF_TYPE = rdf.type.value;
 const FRAME_OPTIONS = { omitGraph: false, embed: '@always' };
 /**
- * Frame CONSTRUCT quads into one JSON-LD node per subject of `rootType`. Each
- * root subject’s own triples plus the one-hop nodes it references (e.g. nested
- * publisher/distribution resources) are grouped lazily and framed one at a
- * time, so beyond the subject index only a single subgraph is held — whole-graph
- * `jsonld.frame()` is ~O(N²). Duplicate triples are collapsed first because some
- * SPARQL engines
- * (e.g. QLever) do not dedupe CONSTRUCT output. The caller supplies the root
- * type, keeping the framing domain-agnostic; the frame carries no `@context`, so
- * framed keys are full predicate IRIs.
+ * Iterate `quads` once, grouping each subject’s triples and collecting the root
+ * subjects of every type in `rootTypes`. Duplicate triples are collapsed here
+ * because some SPARQL engines (e.g. QLever) do not deduplicate CONSTRUCT
+ * output. The source is consumed a single time, so it may be a one-shot
+ * iterable (a generator chaining several sources); the whole subject index is
+ * held, but never more than that plus one framed subgraph at a time
+ * downstream.
  */
-export async function* frameByType(quads, rootType) {
-    for (const { rootIri, subgraph } of groupByRoot(quads, rootType)) {
-        const expanded = await jsonld.fromRDF(subgraph);
-        // Frame for THIS specific root subject by `@id`, not just by root type. A
-        // one-hop reference can itself be of `rootType` (e.g. a terminology source
-        // that is also a separately registered dataset), so framing by type alone
-        // returns several root nodes and `[0]` could be the referenced one — which
-        // would emit it twice and drop this subject entirely.
-        const framed = await jsonld.frame(expanded, { '@id': rootIri }, FRAME_OPTIONS);
-        const node = framed['@graph']?.[0];
-        if (node !== undefined) {
-            yield node;
-        }
-    }
-}
-/**
- * Yield one self-contained quad subgraph per root subject – its own (deduped)
- * triples plus the triples of the one-hop IRI or blank nodes it references –
- * lazily, so only the subject index and the current subgraph are held at once
- * (never the whole materialized list of subgraphs).
- */
-function* groupByRoot(quads, rootType) {
+export function buildSubjectIndex(quads, rootTypes) {
     const bySubject = new Map();
-    const rootIris = [];
+    const rootsByType = new Map();
+    for (const type of rootTypes) {
+        rootsByType.set(type, []);
+    }
     const seen = new Set();
     for (const quad of quads) {
         const key = `${quad.subject.value} ${quad.predicate.value} ${quad.object.value} ${quad.object.termType === 'Literal' ? quad.object.language || quad.object.datatype.value : ''}`;
@@ -52,16 +32,58 @@ function* groupByRoot(quads, rootType) {
         else {
             owned.push(quad);
         }
-        if (quad.predicate.value === RDF_TYPE && quad.object.value === rootType) {
-            rootIris.push(subject);
+        // `rootsByType` is keyed by exactly the requested root types, so the lookup
+        // doubles as the membership test: a hit means this subject is a root.
+        if (quad.predicate.value === RDF_TYPE) {
+            const roots = rootsByType.get(quad.object.value);
+            if (roots !== undefined) {
+                roots.push(subject);
+            }
         }
     }
-    for (const iri of rootIris) {
-        const owned = bySubject.get(iri) ?? [];
+    return { bySubject, rootsByType };
+}
+/**
+ * Frame every root subject of `rootType` from a prebuilt {@link SubjectIndex}
+ * into one JSON-LD node – the reusable core behind {@link frameByType}. Each
+ * root subject’s own triples plus the one-hop nodes it references (e.g. nested
+ * publisher/distribution resources) are framed one subject at a time, so beyond
+ * the shared subject index only a single subgraph is held (whole-graph
+ * `jsonld.frame()` is ~O(N²)). The frame carries no `@context`, so framed keys
+ * are full predicate IRIs.
+ */
+export async function* frameSubjects(index, rootType) {
+    const { bySubject } = index;
+    // A type the index was not built for has no roots, so it frames nothing; the
+    // `projectType`/`projectGraph` callers only pass types they registered.
+    const roots = index.rootsByType.get(rootType) ?? [];
+    for (const rootIri of roots) {
+        const owned = bySubject.get(rootIri) ?? [];
         const referenced = owned
             .filter((quad) => quad.object.termType === 'NamedNode' ||
             quad.object.termType === 'BlankNode')
             .flatMap((quad) => bySubject.get(quad.object.value) ?? []);
-        yield { rootIri: iri, subgraph: [...owned, ...referenced] };
+        const subgraph = [...owned, ...referenced];
+        const expanded = await jsonld.fromRDF(subgraph);
+        // Frame for THIS specific root subject by `@id`, not just by root type. A
+        // one-hop reference can itself be of `rootType` (e.g. a terminology source
+        // that is also a separately registered dataset), so framing by type alone
+        // returns several root nodes and `[0]` could be the referenced one — which
+        // would emit it twice and drop this subject entirely.
+        const framed = await jsonld.frame(expanded, { '@id': rootIri }, FRAME_OPTIONS);
+        const node = framed['@graph']?.[0];
+        if (node !== undefined) {
+            yield node;
+        }
     }
 }
+/**
+ * Frame CONSTRUCT quads into one JSON-LD node per subject of `rootType`, for a
+ * single root type. Consumes `quads` once (see {@link buildSubjectIndex}), so
+ * it accepts any `Iterable` – a materialized array or a chained generator. For
+ * a multi-type schema, {@link buildSubjectIndex} + {@link frameSubjects} share
+ * one index across types rather than re-scanning per type.
+ */
+export async function* frameByType(quads, rootType) {
+    yield* frameSubjects(buildSubjectIndex(quads, [rootType]), rootType);
+}

package/dist/project.d.ts

@@ -19,8 +19,13 @@ export declare function projectDocument(node: FramedNode, searchType: SearchType
  * type’s declaration — the multi-shape pipeline. Streams one document at a time
  * so memory stays flat. The IR maps to a declaration by type, so adding a shape
  * is adding a `SearchType` to the schema (no engine change).
+ *
+ * Consumes `quads` once (a single scan builds the shared subject index that
+ * every type frames off), so it accepts any `Iterable` – a materialized array or
+ * a chained generator merging several sources (`function* () { yield* a; yield* b; }`)
+ * with no intermediate copy at the projection peak.
  */
-export declare function projectGraph(quads: readonly Quad[], schema: SearchSchema): AsyncIterable<SearchDocument>;
+export declare function projectGraph(quads: Iterable<Quad>, schema: SearchSchema): AsyncIterable<SearchDocument>;
 export declare function literalsOf(node: FramedNode, path: string): string[];
 export declare function firstLiteralOf(node: FramedNode, path: string): string | undefined;
 export declare function irisOf(node: FramedNode, path: string): string[];

package/dist/project.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAErB,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,GACrB,cAAc,CAYhB;AAED;;;;;GAKG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,MAAM,EAAE,YAAY,GACnB,aAAa,CAAC,cAAc,CAAC,CAM/B;AAsID,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAInE;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D"}
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAErB,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtE;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,GACrB,cAAc,CAYhB;AAED;;;;;;;;;;GAUG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EACrB,MAAM,EAAE,YAAY,GACnB,aAAa,CAAC,cAAc,CAAC,CAW/B;AAsID,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAInE;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D"}

package/dist/project.js

@@ -1,5 +1,5 @@
 import { fold } from '@lde/text-normalization';
-import { frameByType } from './frame-by-type.js';
+import { buildSubjectIndex, frameSubjects, } from './frame-by-type.js';
 import { isoToUnixSeconds, physicalFields, } from './schema.js';
 /**
  * Project one framed JSON-LD node into a flat search document: apply each field
@@ -25,10 +25,17 @@ export function projectDocument(node, searchType) {
  * type’s declaration — the multi-shape pipeline. Streams one document at a time
  * so memory stays flat. The IR maps to a declaration by type, so adding a shape
  * is adding a `SearchType` to the schema (no engine change).
+ *
+ * Consumes `quads` once (a single scan builds the shared subject index that
+ * every type frames off), so it accepts any `Iterable` – a materialized array or
+ * a chained generator merging several sources (`function* () { yield* a; yield* b; }`)
+ * with no intermediate copy at the projection peak.
  */
 export async function* projectGraph(quads, schema) {
-    for (const searchType of schema.values()) {
-        for await (const node of frameByType(quads, searchType.type)) {
+    const types = [...schema.values()];
+    const index = buildSubjectIndex(quads, types.map((searchType) => searchType.type));
+    for (const searchType of types) {
+        for await (const node of frameSubjects(index, searchType.type)) {
             yield projectDocument(node, searchType);
         }
     }

package/dist/schema.d.ts

@@ -125,6 +125,15 @@ export interface ReferenceField extends SearchFieldBase, Searchable {
     /** Projection-time value transform. */
     readonly transform?: (value: string) => string;
     readonly facetRanges?: never;
+    /**
+     * The `name` of the {@link SearchType} whose collection resolves this
+     * reference’s labels – its ‘label source’. The named type must declare an
+     * `output`, `searchable` text field called `label` (validated by
+     * {@link searchSchema}), so an engine can both reconstruct the label and
+     * search it (typeahead). Omit for an id-only reference: no label
+     * resolution.
+     */
+    readonly labelSource?: string;
     /** The referenced entity’s shape and how much of it to carry. Required when
      *  the field is `output` (the API surfaces need the reference type name);
      *  optional for a facet- or filter-only reference. */
@@ -234,6 +243,15 @@ export interface SearchSchema<Types extends readonly SearchType[] = readonly Sea
  * schema fails at startup, not per document at index time or per query.
  */
 export declare function searchSchema<const Types extends readonly SearchType[]>(...types: Types): SearchSchema<Types>;
+/**
+ * The text field a label source serves labels from – the ‘label’ convention
+ * in one place: an `output` (something to reconstruct a label from),
+ * `searchable` (something to type ahead against) text field called `label`.
+ * Returns `undefined` when the type declares no such field; a schema built by
+ * {@link searchSchema} guarantees it for every type named as a
+ * {@link ReferenceField.labelSource}.
+ */
+export declare function labelFieldOf(searchType: SearchType): TextField | undefined;
 /**
  * One structural problem {@link validateSearchType} found: a field declares a
  * capability or property its `kind` cannot honour, or the declaration is
@@ -315,7 +333,7 @@ export declare function sortableFields(searchType: SearchType): readonly SearchF
 /** Fields that appear in the API output type, in declaration order. */
 export declare function outputFields(searchType: SearchType): readonly SearchField[];
 /** Fields of kind `reference` (IRI-valued, label-resolved), in declaration order. */
-export declare function referenceFields(searchType: SearchType): readonly SearchField[];
+export declare function referenceFields(searchType: SearchType): readonly ReferenceField[];
 /** Look up a field by its logical name. */
 export declare function fieldNamed(searchType: SearchType, name: string): SearchField | undefined;
 /**

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,SAAS,GACT,SAAS,GACT,QAAQ,GACR,SAAS,GACT,MAAM,GACN,WAAW,CAAC;AAEhB;oEACoE;AACpE,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC;AAcnD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,GAAG,SAAS,CAE7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,YAAY,GACZ,cAAc,GACd,YAAY,GACZ,YAAY,CAAC;AAEjB,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B;wCACoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;+EAC2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB;;yCAEqC;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,yBAAyB;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,iCAAiC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC;CAC3E;AAED;kEACkE;AAClE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAU,SAAQ,eAAe,EAAE,UAAU;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;CAC9B;AAED;gCACgC;AAChC,MAAM,WAAW,YAAa,SAAQ,eAAe,EAAE,UAAU;IAC/D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;CAC9B;AAED,gFAAgF;AAChF,MAAM,WAAW,cAAe,SAAQ,eAAe,EAAE,UAAU;IACjE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;IAC7B;;0DAEsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE;QACb;;;;;qCAK6B;QAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B;;;;6EAIqE;QACrE,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;KACtD,CAAC;CACH;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CAC9C;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAa,SAAQ,eAAe,EAAE,cAAc;IACnE,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC;CAC7B;AAED,0DAA0D;AAC1D,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB;;;;+CAI2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CACzC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,IAAI,SAAS,UAAU,EAC5D,UAAU,EAAE,IAAI,GACf,IAAI,CAEN;AAED;;;;;;GAMG;AACH;;;uCAGuC;AACvC,MAAM,CAAC,OAAO,CAAC,MAAM,iBAAiB,EAAE,OAAO,MAAM,CAAC;AAEtD,MAAM,WAAW,YAAY,CAC3B,KAAK,SAAS,SAAS,UAAU,EAAE,GAAG,SAAS,UAAU,EAAE,CAC3D,SAAQ,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,KAAK,SAAS,SAAS,UAAU,EAAE,EACpE,GAAG,KAAK,EAAE,KAAK,GACd,YAAY,CAAC,KAAK,CAAC,CAsBrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EACX,sBAAsB,GACtB,aAAa,GACb,iBAAiB,GACjB,uBAAuB,GACvB,qBAAqB,GACrB,0BAA0B,GAC1B,wBAAwB,GACxB,uBAAuB,GACvB,kBAAkB,GAClB,qBAAqB,GACrB,oBAAoB,CAAC;CAC1B;AAQD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,GACrB,SAAS,eAAe,EAAE,CAkE5B;AAWD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,UAAU,GACrB,IAAI,CAUN;AAED;+EAC+E;AAC/E,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAQlE;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;sEACkE;IAClE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;4EACwE;IACxE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,GACrB,SAAS,CAAC,WAAW,GAAG;IACzB,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD,CAAC,EAAE,CAOH;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,UAAU,EAAE,UAAU,GACrB,SAAS,WAAW,EAAE,CAExB;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,UAAU,GACrB,SAAS,WAAW,EAAE,CAExB;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,WAAW,EAAE,CAE7E;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,SAAS,WAAW,EAAE,CAE3E;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAC7B,UAAU,EAAE,UAAU,GACrB,SAAS,WAAW,EAAE,CAExB;AAED,2CAA2C;AAC3C,wBAAgB,UAAU,CACxB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,GACX,WAAW,GAAG,SAAS,CAEzB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,WAAW,GACjB,KAAK,IAAI,YAAY,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhE;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,cAAc,CAoBjE"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -51,9 +51,54 @@ export function searchSchema(...types) {
         typeIris.add(searchType.type);
         names.add(searchType.name);
     }
+    assertResolvableLabelSources(types);
     // The one blessed cast: only this validated constructor mints the brand.
     return new Map(types.map((searchType) => [searchType.type, searchType]));
 }
+/**
+ * The text field a label source serves labels from – the ‘label’ convention
+ * in one place: an `output` (something to reconstruct a label from),
+ * `searchable` (something to type ahead against) text field called `label`.
+ * Returns `undefined` when the type declares no such field; a schema built by
+ * {@link searchSchema} guarantees it for every type named as a
+ * {@link ReferenceField.labelSource}.
+ */
+export function labelFieldOf(searchType) {
+    const field = fieldNamed(searchType, 'label');
+    return field !== undefined &&
+        field.kind === 'text' &&
+        field.output === true &&
+        field.searchable !== undefined
+        ? field
+        : undefined;
+}
+/**
+ * Every {@link ReferenceField.labelSource} must name a declared type that can
+ * actually serve labels ({@link labelFieldOf}). Checked schema-wide, because
+ * a single declaration cannot see its siblings.
+ */
+function assertResolvableLabelSources(types) {
+    const byName = new Map(types.map((searchType) => [searchType.name, searchType]));
+    for (const searchType of types) {
+        for (const field of searchType.fields) {
+            const labelSource = field
+                .labelSource;
+            if (labelSource === undefined) {
+                continue;
+            }
+            if (field.kind !== 'reference') {
+                throw new Error(`Field “${searchType.name}.${field.name}” declares a label source but is a ${field.kind} field; only reference fields resolve labels from a source.`);
+            }
+            const source = byName.get(labelSource);
+            if (source === undefined) {
+                throw new Error(`Reference “${searchType.name}.${field.name}” names unknown label source “${field.labelSource}”; declare a SearchType with that name.`);
+            }
+            if (labelFieldOf(source) === undefined) {
+                throw new Error(`Reference “${searchType.name}.${field.name}” uses label source “${field.labelSource}”, which must declare an output, searchable text field “label”.`);
+            }
+        }
+    }
+}
 /** Kinds that can feed full-text search (project a folded search field). */
 const SEARCHABLE_KINDS = ['text', 'keyword', 'reference'];
 /** Kinds whose projection applies the {@link KeywordField.transform}. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Engine- and domain-agnostic core for RDF-backed search: a unified declarative field model (SearchField/SearchType/SearchSchema), a neutral query IR, the SearchEngine port with logical result types, and a streaming CONSTRUCT-to-document projection. Bakes in no engine, protocol, or domain.",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
@@ -45,7 +45,7 @@
   },
   "devDependencies": {
     "@types/jsonld": "^1.5.15",
-    "n3": "^2.1.0"
+    "n3": "^2.1.1"
   },
   "peerDependencies": {
     "vitest": "^4.0.0"