@lde/search 0.4.0 → 0.4.1

package/README.md

@@ -218,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` =

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/search",
-  "version": "0.4.0",
+  "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"