@lde/search 0.0.0

package/README.md

@@ -0,0 +1,170 @@
+# @lde/search
+
+Engine-agnostic search projection for RDF-backed pipelines. **`projectGraph`**
+streams the result of a SPARQL `CONSTRUCT` into flat search documents, with no
+engine and no vocabulary baked in. Internally it does two things per subject of
+a root type: frame its one-hop subgraph into a JSON-LD IR node, then project
+that node into a flat document from a **declarative field spec**.
+
+An engine adapter (e.g. [`@lde/search-typesense`](../search-typesense)) then
+writes those documents to a search backend.
+
+```ts
+import { projectGraph, type Projection } from '@lde/search';
+
+const projection: Projection = {
+  /* type + field spec — see below */
+};
+
+for await (const document of projectGraph(quads, [projection])) {
+  // one flat search document per matching subject, streamed
+}
+```
+
+`projectGraph` is fully streaming: subjects are grouped and framed one at a time
+and documents are yielded as they are produced, so beyond a subject index memory
+stays flat at scale (framing the whole graph at once is roughly O(N²)). Duplicate
+triples are collapsed first, because some SPARQL engines (e.g. QLever) do not
+deduplicate `CONSTRUCT` output. The IR carries no `@context`, so a `derivation`
+reading it sees full predicate IRIs with language tags preserved.
+
+## Projection
+
+The mapping is data, not code. Each field declares the IR `path` to read and a
+`kind`; the conventions (per-locale split, diacritic folding via
+[`@lde/text-normalization`](../text-normalization), facet arrays, numeric
+coercion) are applied for you. Computed fields are `derivations` — hooks that
+read the node and set fields the kinds can't.
+
+```ts
+import { projectGraph, irisOf, type Projection } from '@lde/search';
+
+const projection: Projection = {
+  type: 'http://www.w3.org/ns/dcat#Dataset',
+  fields: [
+    // → title_nl, title_en, title_search_nl, title_search_en, title_sort_nl, title_sort_en
+    {
+      name: 'title',
+      path: 'http://purl.org/dc/terms/title',
+      kind: {
+        type: 'langText',
+        locales: ['nl', 'en'],
+        display: true,
+        search: true,
+        sort: true,
+      },
+    },
+    // → publisher (IRI facet)
+    {
+      name: 'publisher',
+      path: 'http://purl.org/dc/terms/publisher',
+      kind: { type: 'facet', iri: true },
+    },
+    // → size (int)
+    { name: 'size', path: 'urn:dr:size', kind: { type: 'number' } },
+  ],
+  derivations: [
+    (document, node) => {
+      document.class_count = irisOf(node, 'urn:dr:class').length;
+    },
+  ],
+};
+
+for await (const document of projectGraph(quads, [projection])) {
+  // …
+}
+```
+
+**Kinds**
+
+| kind       | emits                                                                                                                                                    |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `langText` | per locale (see below), each opt-in: `_${locale}` display with `display`, `_search_${locale}` folded with `search`, `_sort_${locale}` folded with `sort` |
+| `facet`    | the field as a deduped array; `iri` reads `@id`; `search` adds a folded `_search`; `transform` rewrites values                                           |
+| `number`   | a numeric scalar; `date` parses an ISO date-time to unix seconds                                                                                         |
+
+## Locales
+
+`locales` is the **single** list of languages a `langText` field projects;
+`display`, `search` and `sort` are independent opt-in families that each fan out
+over it (so a field emits exactly what it opts into):
+
+- `display` → `title_nl`/`title_en` (accents preserved);
+- `search` → `title_search_nl`/`title_search_en` (folded; one field per locale
+  lets a query `query_by` them and rank the user’s language higher via
+  `query_by_weights`, and lets a language that needs a dedicated tokenizer set
+  its own `locale` in the schema);
+- `sort` → `title_sort_nl`/`title_sort_en` (folded, so a locale-switching UI
+  sorts on the active language).
+
+A field with `search` but no `display` is **search-only** — folded and stemmed
+for retrieval but never rendered (e.g. a `publisher` searched here but shown via
+a separate label).
+
+Folding the search fields is what lets diacritic-insensitive matching and
+stemming coexist. A search engine on its **default** locale typically folds case
+and diacritics for you (Typesense v30, verified, even folds ø/æ/ß) — so there the
+folding here is belt-and-suspenders. But enabling a language’s **stemming**
+requires setting that language’s `locale` (e.g. `locale: 'nl'` + `stem: true` so
+`huizen` matches `huis`), and a non-default locale switches the engine to ICU
+tokenization, which **preserves** diacritics. At that point the engine no longer
+folds them, and `fold()` is what keeps matching diacritic-insensitive. Stemming
+is a per-field engine-schema choice (the consumer’s), and being rules-based it
+can mangle proper nouns and place names — e.g. the Dutch stemmer reduces the city
+`Bergen` to `berg`, colliding it with “mountain”.
+
+Recommended split: enable stemming on the **free-text** search fields
+(`*_search_${locale}`, descriptions, keywords) where morphological recall helps
+(`verhaal` ↔ `verhalen`), and keep **place names and other proper-noun facets on
+a separate, unstemmed field** (facets are exact-match anyway). That captures the
+recall without the `Bergen`/`berg` collision in the facet. A `stem_dictionary`
+can pin specific names if you need stemmed free-text without given collisions.
+
+**Only listed locales are indexed.** A literal whose language tag is not in
+`locales` is not projected at all — no display, no search, no sort field — so it
+is invisible to the index. To index a language, add it to `locales`.
+
+Per-locale fields are **omitted, never empty**, when a document lacks that
+language, so declare them `optional: true` in the engine schema. At query time,
+sort with `missing_values: last` to push documents lacking the active locale to
+the end, and `query_by` all the per-locale search fields (weighting the user’s
+locale higher) to keep cross-language recall.
+
+A literal with no `@language` tag matches no locale, so it is not projected. Tag
+your source literals (or pre-process them) for the languages you index.
+
+## Querying
+
+The search fields are stored already case- and diacritic-folded, so **the query
+must be folded the same way** with the same `fold()` from
+[`@lde/text-normalization`](../text-normalization) before it reaches the engine.
+Otherwise index and query are normalized differently and matches silently miss
+(the user sees no results, with no error). An engine on its default locale would
+fold a raw query for you, but one set to a stemming locale (which preserves
+diacritics) or a non-folding backend will not — so always fold, and matching
+stays correct on any engine.
+
+```ts
+import { fold } from '@lde/text-normalization';
+
+await client
+  .collections(collection)
+  .documents()
+  .search({
+    q: fold(userQuery),
+    query_by: 'title_search_nl,title_search_en',
+    query_by_weights: '2,1', // rank the user’s locale higher
+  });
+```
+
+This contract holds for **any** consumer, including a search API built on top of
+this package: index-time and query-time folding must use the same `fold()`, or
+non-decomposing terms silently miss.
+
+## Why a spec
+
+The field spec's vocabulary mirrors SHACL on purpose: `path` is `sh:path`, and
+the kind is derivable from `sh:datatype` / `sh:nodeKind` / `sh:maxCount` plus
+search annotations. So the same projection engine that runs a hand-written spec
+today will run a **SHACL-generated** spec tomorrow — the engine and the IR stay;
+only spec-authoring gets automated. Nothing is thrown away.

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

@@ -0,0 +1,16 @@
+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
+ * 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.
+ */
+export declare function frameByType(quads: readonly Quad[], rootType: string): AsyncIterable<FramedNode>;
+//# sourceMappingURL=frame-by-type.d.ts.map

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

@@ -0,0 +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,CAU3B"}

package/dist/frame-by-type.js

@@ -0,0 +1,63 @@
+import jsonld from 'jsonld';
+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.
+ */
+export async function* frameByType(quads, rootType) {
+    const frame = { '@type': rootType };
+    for (const subgraph of groupByRoot(quads, rootType)) {
+        const expanded = await jsonld.fromRDF(subgraph);
+        const framed = await jsonld.frame(expanded, frame, 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) {
+    const bySubject = new Map();
+    const rootIris = [];
+    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 : ''}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        const subject = quad.subject.value;
+        const owned = bySubject.get(subject);
+        if (owned === undefined) {
+            bySubject.set(subject, [quad]);
+        }
+        else {
+            owned.push(quad);
+        }
+        if (quad.predicate.value === RDF_TYPE && quad.object.value === rootType) {
+            rootIris.push(subject);
+        }
+    }
+    for (const iri of rootIris) {
+        const owned = bySubject.get(iri) ?? [];
+        const referenced = owned
+            .filter((quad) => quad.object.termType === 'NamedNode' ||
+            quad.object.termType === 'BlankNode')
+            .flatMap((quad) => bySubject.get(quad.object.value) ?? []);
+        yield [...owned, ...referenced];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { projectGraph, irisOf, literalsOf, firstLiteralOf } from './project.js';
+export type { SearchDocument, Projection, FieldSpec, FieldKind, LangTextKind, FacetKind, NumberKind, DateKind, Derivation, } from './project.js';
+export type { FramedNode } from './frame-by-type.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAChF,YAAY,EACV,cAAc,EACd,UAAU,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,SAAS,EACT,UAAU,EACV,QAAQ,EACR,UAAU,GACX,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { projectGraph, irisOf, literalsOf, firstLiteralOf } from './project.js';

package/dist/project.d.ts

@@ -0,0 +1,99 @@
+import type { Quad } from '@rdfjs/types';
+import { type FramedNode } from './frame-by-type.js';
+/** A flat search document. `id` is the engine document key. */
+export type SearchDocument = {
+    id: string;
+} & Record<string, unknown>;
+/**
+ * How one framed-IR property projects into search fields. The vocabulary mirrors
+ * SHACL so a generator can later emit it from shapes + search annotations:
+ * `path` is `sh:path`, and the kind is derivable from `sh:datatype`/`sh:nodeKind`
+ * /`sh:maxCount` plus the search annotations.
+ */
+export type FieldKind = LangTextKind | FacetKind | NumberKind | DateKind;
+/**
+ * Language-tagged text, projected per locale. `locales` is the single source of
+ * truth for which languages this field emits; `display`, `search` and `sort` are
+ * three independent opt-in families that each fan out over it:
+ * - `display` → `${name}_${locale}` display label, accents preserved;
+ * - `search` → `${name}_search_${locale}` folded match field (one per locale so
+ *   the engine can tokenize/stem each language and the query can rank the user’s
+ *   locale higher);
+ * - `sort` → `${name}_sort_${locale}` folded sort key (one per locale so a
+ *   locale-switching UI sorts on the active language).
+ *
+ * All three default off — a field emits exactly the families it opts into (e.g.
+ * `search` alone is a search-only field, shown via a separate label). Only listed
+ * locales are projected: a value whose language tag is not in `locales` (and is
+ * not mapped in by `untaggedLanguage`) is not indexed at all.
+ */
+export interface LangTextKind {
+    readonly type: 'langText';
+    /** The languages to project; drives whichever of the families are enabled. */
+    readonly locales: readonly string[];
+    /** Emit the per-locale display labels `${name}_${locale}` (accents preserved). */
+    readonly display?: boolean;
+    /** Emit a folded `${name}_search_${locale}` per locale (matchable). */
+    readonly search?: boolean;
+    /** Emit a folded `${name}_sort_${locale}` per locale (sortable). */
+    readonly sort?: boolean;
+}
+/** A faceted multi-value field, optionally also folded for search. */
+export interface FacetKind {
+    readonly type: 'facet';
+    /** Read IRI references (`@id`) rather than literal values. */
+    readonly iri?: boolean;
+    /** Also emit a folded `${name}_search` array. */
+    readonly search?: boolean;
+    /** Transform each value before faceting (e.g. strip a media-type prefix). */
+    readonly transform?: (value: string) => string;
+}
+/** A numeric scalar. */
+export interface NumberKind {
+    readonly type: 'number';
+}
+/** An ISO date-time, parsed into Unix seconds. */
+export interface DateKind {
+    readonly type: 'date';
+}
+/**
+ * One field of a projection: an output `name`, the framed-IR predicate `path` to
+ * read (the SHACL `sh:path`), and the kind-specific config discriminated by
+ * `type`.
+ */
+export type FieldSpec = {
+    /** Output field base name; per-kind suffixes are appended. */
+    readonly name: string;
+    /** Framed-IR predicate IRI to read (the SHACL `sh:path`). */
+    readonly path: string;
+} & FieldKind;
+/** A computed field that is not a direct projection of a single path
+ *  (e.g. a status rank, or a group derived from a code table). */
+export type Derivation = (document: SearchDocument, node: FramedNode) => void;
+/**
+ * One root type’s complete projection — the runtime form of a single SHACL
+ * NodeShape: `type` is its `sh:targetClass` (and the framed node’s `@type`),
+ * `fields` are its property shapes, and `derivations` are its `sh:rule`-shaped
+ * computed fields. A generator emits one of these per NodeShape.
+ */
+export interface Projection {
+    readonly type: string;
+    readonly fields: readonly FieldSpec[];
+    readonly derivations?: readonly Derivation[];
+}
+/**
+ * Project one framed JSON-LD node into a flat search document: apply each field
+ * spec, then run the derivations (which may read fields the specs already set).
+ */
+export declare function projectDocument(node: FramedNode, projection: Projection): SearchDocument;
+/**
+ * Frame `quads` for every projection’s root type and project each node with its
+ * type’s projection — the multi-shape pipeline. Streams one document at a time
+ * so memory stays flat. The IR maps to a projection by type, so adding a shape
+ * is adding a `Projection` (no engine change).
+ */
+export declare function projectGraph(quads: readonly Quad[], projections: readonly Projection[]): 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[];
+//# sourceMappingURL=project.d.ts.map

package/dist/project.d.ts.map

@@ -0,0 +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;AAElE,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAChD;AAED,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GAAG,SAAS,CAAC;AAEd;kEACkE;AAClE,MAAM,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,UAAU,GACrB,cAAc,CAehB;AAED;;;;;GAKG;AACH,wBAAuB,YAAY,CACjC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,WAAW,EAAE,SAAS,UAAU,EAAE,GACjC,aAAa,CAAC,cAAc,CAAC,CAS/B;AA+FD,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

@@ -0,0 +1,170 @@
+import { fold } from '@lde/text-normalization';
+import { frameByType } from './frame-by-type.js';
+/**
+ * Project one framed JSON-LD node into a flat search document: apply each field
+ * spec, then run the derivations (which may read fields the specs already set).
+ */
+export function projectDocument(node, projection) {
+    const id = node['@id'];
+    if (typeof id !== 'string') {
+        throw new Error(`Cannot project a ${projection.type} node without an @id: every search document needs a stable key, and an empty one would collide with other keyless nodes.`);
+    }
+    const document = { id };
+    for (const field of projection.fields) {
+        applyField(document, node, field);
+    }
+    for (const derive of projection.derivations ?? []) {
+        derive(document, node);
+    }
+    return document;
+}
+/**
+ * Frame `quads` for every projection’s root type and project each node with its
+ * type’s projection — the multi-shape pipeline. Streams one document at a time
+ * so memory stays flat. The IR maps to a projection by type, so adding a shape
+ * is adding a `Projection` (no engine change).
+ */
+export async function* projectGraph(quads, projections) {
+    const byType = new Map(projections.map((projection) => [projection.type, projection]));
+    for (const projection of byType.values()) {
+        for await (const node of frameByType(quads, projection.type)) {
+            yield projectDocument(node, projection);
+        }
+    }
+}
+function applyField(document, node, field) {
+    switch (field.type) {
+        case 'langText':
+            return applyLangText(document, langValuesOf(node, field.path), field);
+        case 'facet':
+            return applyFacet(document, node, field);
+        case 'number':
+            return setNumber(document, field.name, toInteger(firstLiteralOf(node, field.path)));
+        case 'date':
+            return setNumber(document, field.name, isoToUnix(firstLiteralOf(node, field.path)));
+    }
+}
+function applyLangText(document, values, { name, locales, display, search, sort }) {
+    if (locales.length === 0) {
+        throw new Error(`langText field “${name}” must declare at least one locale; nothing would be projected otherwise.`);
+    }
+    for (const locale of locales) {
+        const localeValues = values
+            .filter((value) => value.lang === locale)
+            .map((value) => value.value);
+        if (localeValues.length === 0) {
+            continue;
+        }
+        // Display shows one label (accents preserved); sort keys off that same
+        // primary value (folded); search folds every value of the locale so all
+        // are matchable. Absent locales emit nothing (the field stays optional).
+        const [primary] = localeValues;
+        if (display) {
+            setString(document, `${name}_${locale}`, primary);
+        }
+        if (search) {
+            setString(document, `${name}_search_${locale}`, fold(localeValues.join(' ')).trim());
+        }
+        if (sort) {
+            setString(document, `${name}_sort_${locale}`, fold(primary));
+        }
+    }
+}
+function applyFacet(document, node, { name, path, iri, search, transform }) {
+    const raw = iri ? irisOf(node, path) : literalsOf(node, path);
+    const values = dedupe(transform ? raw.map(transform) : raw);
+    setArray(document, name, values);
+    if (search) {
+        setArray(document, `${name}_search`, dedupe(values.map((value) => fold(value))));
+    }
+}
+function langValuesOf(node, path) {
+    return valuesOf(node, path)
+        .map(toLangValue)
+        .filter((value) => value !== undefined);
+}
+export function literalsOf(node, path) {
+    return valuesOf(node, path)
+        .map(literalString)
+        .filter((value) => value !== undefined);
+}
+export function firstLiteralOf(node, path) {
+    return literalsOf(node, path)[0];
+}
+export function irisOf(node, path) {
+    return valuesOf(node, path)
+        .map(iriString)
+        .filter((value) => value !== undefined);
+}
+function valuesOf(node, path) {
+    const value = node[path];
+    if (value === undefined) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+}
+function toLangValue(value) {
+    const literal = literalString(value);
+    if (literal === undefined) {
+        return undefined;
+    }
+    const lang = isObject(value) && typeof value['@language'] === 'string'
+        ? value['@language']
+        : '';
+    return { value: literal, lang };
+}
+function literalString(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (isObject(value)) {
+        const inner = value['@value'];
+        if (typeof inner === 'string') {
+            return inner;
+        }
+        if (typeof inner === 'number' || typeof inner === 'boolean') {
+            return String(inner);
+        }
+    }
+    return undefined;
+}
+function iriString(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (isObject(value) && typeof value['@id'] === 'string') {
+        return value['@id'];
+    }
+    return undefined;
+}
+function toInteger(literal) {
+    return literal === undefined ? undefined : Math.trunc(Number(literal));
+}
+function isoToUnix(iso) {
+    if (iso === undefined) {
+        return undefined;
+    }
+    const millis = new Date(iso).getTime();
+    return Number.isNaN(millis) ? undefined : Math.trunc(millis / 1000);
+}
+function setNumber(document, field, value) {
+    if (value !== undefined && !Number.isNaN(value)) {
+        document[field] = value;
+    }
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}
+function setString(document, field, value) {
+    if (value !== undefined && value !== '') {
+        document[field] = value;
+    }
+}
+function setArray(document, field, values) {
+    if (values.length > 0) {
+        document[field] = values;
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@lde/search",
+  "version": "0.0.0",
+  "description": "Engine-agnostic search projection for RDF-backed pipelines: frame CONSTRUCT quads into a JSON-LD IR, then project that IR into flat search documents from a declarative field spec (the artifact a SHACL generator would emit)",
+  "repository": {
+    "url": "git+https://github.com/ldelements/lde.git",
+    "directory": "packages/search"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@lde/text-normalization": "^0.0.0",
+    "@rdfjs/types": "^2.0.1",
+    "@tpluscode/rdf-ns-builders": "^5.0.0",
+    "jsonld": "^9.0.0",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/jsonld": "^1.5.15",
+    "n3": "^2.0.1"
+  }
+}