feat(prez-lib): add Jena Lucene SHACL search parser mode (#261)

* feat(prez-lib): add Jena Lucene SHACL search parser mode

* add tests

Author: recalcitrantsupplant

docs/2026-04-15-jena-lucene-shacl-search-design.md

@@ -32,3 +32,19 @@ const store = new RDFStore();
 store.load(data);
 const data = store.getItem();
 ```
+
+## Search parser modes
+
+`search()` defaults to the existing flat Prez search result shape.
+
+The parser mode is strict: the mode you configure must match the backend search model. `prez-lib` does not do compatibility fallbacks between the flat and Jena Lucene SHACL shapes.
+
+To opt into Jena Lucene SHACL nested matches, pass the parser mode explicitly:
+
+```typescript
+import { search } from "prez-lib";
+
+const results = await search("https://example.com", "/search?q=rock", {
+    parserMode: "jena-lucene-shacl",
+});
+```

packages/prez-lib/README.md

@@ -29,6 +29,7 @@
     "scripts": {
         "dev": "vite",
         "build": "tsc && vite build",
+        "test": "node --test tests/**/*.test.mjs",
         "types": "tsc",
         "preview": "vite preview",
         "preinstall": "npx only-allow pnpm"

packages/prez-lib/package.json

@@ -38,6 +38,7 @@ export const PREZ_PREDICATES = {
     searchResultPredicate: "https://prez.dev/searchResultPredicate",
     searchResultURI: "https://prez.dev/searchResultURI",
     searchResultMatch: "https://prez.dev/searchResultMatch",
+    hasSearchMatch: "https://prez.dev/hasSearchMatch",
     hasChildren: "https://prez.dev/hasChildren",
     facetCount: "https://prez.dev/facetCount",
     facetName: "https://prez.dev/facetName",

packages/prez-lib/src/consts.ts

@@ -1,4 +1,19 @@
-import type { PrezBlankNode, PrezDataItem, PrezDataList, PrezDataSearch, PrezNodeList, PrezProfileHeader, PrezProfiles, PrezProperties, PrezProperty } from "./types";
+import type {
+    PrezBlankNode,
+    PrezDataItem,
+    PrezDataList,
+    PrezDataSearch,
+    PrezDataSearchDefault,
+    PrezDataSearchLuceneShacl,
+    PrezNodeList,
+    PrezProfileHeader,
+    PrezProfiles,
+    PrezProperties,
+    PrezProperty,
+    PrezSearchOptions,
+    PrezSearchOptionsDefault,
+    PrezSearchOptionsLuceneShacl
+} from "./types";
 import { RDFStore } from "./store";
 import { SYSTEM_PREDICATES } from "./consts";
 
@@ -150,19 +165,37 @@ export async function getItem(baseUrl: string, path: string): Promise<PrezDataIt
  * @param path Search path along with any query parameters
  * @returns 
  */
-export async function search(baseUrl: string, path: string): Promise<PrezDataSearch> {
+export async function search(baseUrl: string, path: string, options?: PrezSearchOptionsDefault): Promise<PrezDataSearchDefault>;
+export async function search(baseUrl: string, path: string, options: PrezSearchOptionsLuceneShacl): Promise<PrezDataSearchLuceneShacl>;
+export async function search(baseUrl: string, path: string, options: PrezSearchOptions = {}): Promise<PrezDataSearch> {
     const url = baseUrl + path;
-    const pathOnly = new URL(url).pathname
+    const pathOnly = new URL(url).pathname;
     const { data, profiles } = await apiGet(url);
     const store = new RDFStore();
     store.setBaseUrl(baseUrl);
     store.load(data);
+    const parserMode = options.parserMode ?? "default";
+
+    if (parserMode === "jena-lucene-shacl") {
+        return {
+            type: 'search',
+            parserMode,
+            data: store.search({ parserMode }),
+            profiles,
+            maxReached: store.getMaxReached(),
+            count: store.getCount(),
+            parents: store.getParents(pathOnly),
+            facets: store.getFacets()
+        };
+    }
+
     return {
-        type: 'search', 
-        data: store.search(), 
-        profiles, 
-        maxReached: store.getMaxReached(), 
-        count: store.getCount(), 
+        type: 'search',
+        parserMode: "default",
+        data: store.search(),
+        profiles,
+        maxReached: store.getMaxReached(),
+        count: store.getCount(),
         parents: store.getParents(pathOnly),
         facets: store.getFacets()
     };

packages/prez-lib/src/service.ts

@@ -1,5 +1,27 @@
 import { Store, Parser, DataFactory, type Quad_Object, type Quad_Subject, type Term, type Quad } from "n3";
-import type { PrezLiteral, PrezNode, PrezTerm, PrezProperties, PrezSearchResult, PrezFocusNode, PrezLink, PrezConceptSchemeNode, PrezConceptNode, PrezOntologyNode, PrezConceptSchemeOntologyNode, PrezBBlockNode, PrezLinkParent, PrezNodeList, PrezFacet } from "./types";
+import type {
+    PrezAnySearchResult,
+    PrezBBlockNode,
+    PrezConceptNode,
+    PrezConceptSchemeNode,
+    PrezConceptSchemeOntologyNode,
+    PrezFacet,
+    PrezFlatSearchResult,
+    PrezFocusNode,
+    PrezLink,
+    PrezLinkParent,
+    PrezLiteral,
+    PrezLuceneShaclSearchResult,
+    PrezNode,
+    PrezNodeList,
+    PrezOntologyNode,
+    PrezProperties,
+    PrezSearchMatch,
+    PrezSearchOptions,
+    PrezSearchOptionsDefault,
+    PrezSearchOptionsLuceneShacl,
+    PrezTerm
+} from "./types";
 import { DEFAULT_PREFIXES, PREZ_PREDICATES, SYSTEM_PREDICATES, BBLOCK_TYPES } from "./consts";
 import { defaultToIri, defaultFromIri } from "./helpers";
 import { node, literal, bnode } from "./factory";
@@ -163,6 +185,29 @@ export class RDFStore {
         return this.getObjects(iri, predicate).map(o => this.toPrezTerm(o) as PrezLiteral)[0] || undefined;
     }
 
+    private toSubjectTerm(subject: string | Quad_Subject | Quad_Object): Quad_Subject {
+        if (typeof subject === "string") {
+            return namedNode(subject);
+        }
+
+        if (subject.termType === "Literal") {
+            throw new Error(`Cannot use literal ${subject.value} as a subject.`);
+        }
+
+        return subject;
+    }
+
+    private getRequiredObject(subject: string | Quad_Subject | Quad_Object, predicate: string, description: string): Quad_Object {
+        const object = this.getObjects(subject, predicate)[0];
+
+        if (!object) {
+            const subjectValue = typeof subject === "string" ? subject : subject.value;
+            throw new Error(`Missing ${description} for ${subjectValue}.`);
+        }
+
+        return object;
+    }
+
     public getProperties(term: Term, options?: {excludePrefix?: string, includePrefix?: string}): PrezProperties {
         const props: PrezProperties = {};
 
@@ -326,13 +371,14 @@ export class RDFStore {
      * @param predicate a string or string array of predicate IRIs
      * @returns the array of objects
      */
-    public getObjects(subject: string, predicate: string | string[]): Quad_Object[] {
+    public getObjects(subject: string | Quad_Subject | Quad_Object, predicate: string | string[]): Quad_Object[] {
+        const subjectTerm = this.toSubjectTerm(subject);
         if (typeof predicate === "string") {
-            return this.store.getObjects(namedNode(subject), namedNode(predicate), null);
+            return this.store.getObjects(subjectTerm, namedNode(predicate), null);
         } else {
             const objs: Quad_Object[] = [];
             predicate.forEach(p => {
-                objs.push(...this.store.getObjects(namedNode(subject), namedNode(p), null));
+                objs.push(...this.store.getObjects(subjectTerm, namedNode(p), null));
             });
             return objs;
         }
@@ -628,19 +674,89 @@ export class RDFStore {
     /**
      * Returns search results
      */
-    public search(): PrezSearchResult[] {
+    private extractSearchResultHash(subject: Quad_Subject): string {
+        return subject.value.startsWith("urn:hash:") ? subject.value.slice("urn:hash:".length) : subject.value;
+    }
+
+    private getSearchResultBase(subject: Quad_Subject) {
+        const weightObject = this.getRequiredObject(subject, PREZ_PREDICATES.searchResultWeight, "search result weight");
+        const resourceObject = this.getRequiredObject(subject, PREZ_PREDICATES.searchResultURI, "search result URI");
+
+        return {
+            hash: this.extractSearchResultHash(subject),
+            weight: Number(weightObject.value),
+            resource: this.toPrezFocusNode(resourceObject)
+        };
+    }
+
+    private getOptionalFlatSearchMatch(subject: Quad_Subject): PrezSearchMatch | undefined {
+        const predicateObject = this.getObjects(subject, PREZ_PREDICATES.searchResultPredicate)[0];
+        const matchObject = this.getObjects(subject, PREZ_PREDICATES.searchResultMatch)[0];
+
+        if (!predicateObject && !matchObject) {
+            return undefined;
+        }
+
+        if (!predicateObject || !matchObject) {
+            throw new Error(`Incomplete flat search match for ${subject.value}.`);
+        }
+
+        return {
+            predicate: this.toPrezTerm(predicateObject) as PrezNode,
+            match: this.toPrezTerm(matchObject) as PrezLiteral
+        };
+    }
+
+    private parseSearchMatch(subject: Quad_Object): PrezSearchMatch {
+        const predicateObject = this.getRequiredObject(subject, PREZ_PREDICATES.searchResultPredicate, "search match predicate");
+        const matchObject = this.getRequiredObject(subject, PREZ_PREDICATES.searchResultMatch, "search match literal");
+
+        return {
+            predicate: this.toPrezTerm(predicateObject) as PrezNode,
+            match: this.toPrezTerm(matchObject) as PrezLiteral
+        };
+    }
+
+    private parseDefaultSearchResult(subject: Quad_Subject): PrezFlatSearchResult {
+        if (this.getObjects(subject, PREZ_PREDICATES.hasSearchMatch).length > 0) {
+            throw new Error(`Received Lucene SHACL search matches for ${subject.value} while parserMode is default.`);
+        }
+
+        const flatMatch = this.getOptionalFlatSearchMatch(subject);
+
+        if (!flatMatch) {
+            throw new Error(`Missing flat search match data for ${subject.value}.`);
+        }
+
+        return {
+            ...this.getSearchResultBase(subject),
+            ...flatMatch
+        };
+    }
+
+    private parseJenaLuceneShaclSearchResult(subject: Quad_Subject): PrezLuceneShaclSearchResult {
+        const nestedMatchNodes = this.getObjects(subject, PREZ_PREDICATES.hasSearchMatch);
+        if (this.getOptionalFlatSearchMatch(subject)) {
+            throw new Error(`Received flat search match fields for ${subject.value} while parserMode is jena-lucene-shacl.`);
+        }
+
+        return {
+            ...this.getSearchResultBase(subject),
+            matches: nestedMatchNodes.map(matchNode => this.parseSearchMatch(matchNode))
+        };
+    }
+
+    public search(options?: PrezSearchOptionsDefault): PrezFlatSearchResult[];
+    public search(options: PrezSearchOptionsLuceneShacl): PrezLuceneShaclSearchResult[];
+    public search(options: PrezSearchOptions = {}): PrezAnySearchResult[] {
+        const parserMode = options.parserMode ?? "default";
         const resultSubjects = this.getSubjects(SYSTEM_PREDICATES.a, PREZ_PREDICATES.searchResult);
-        const results: PrezSearchResult[] = resultSubjects.map(s => {
-            const result: PrezSearchResult = {
-                hash: s.value.split("urn:hash:").slice(-1)[0]!,
-                weight: Number(this.getObjects(s.value, PREZ_PREDICATES.searchResultWeight)[0]!.value),
-                predicate: this.toPrezTerm(this.getObjects(s.value, PREZ_PREDICATES.searchResultPredicate)[0]!) as PrezNode,
-                match: this.toPrezTerm(this.getObjects(s.value, PREZ_PREDICATES.searchResultMatch)[0]!) as PrezLiteral,
-                resource: this.toPrezFocusNode(this.getObjects(s.value, PREZ_PREDICATES.searchResultURI)[0]!)
-            };
-            return result;
-        });
-        return results;
+
+        if (parserMode === "jena-lucene-shacl") {
+            return resultSubjects.map(subject => this.parseJenaLuceneShaclSearchResult(subject));
+        }
+
+        return resultSubjects.map(subject => this.parseDefaultSearchResult(subject));
     }
 
 

packages/prez-lib/src/store.ts

@@ -211,17 +211,57 @@ export interface PrezProperties {
     [predicateIri: string]: PrezProperty;
 };
 
+export type PrezSearchParserMode = "default" | "jena-lucene-shacl";
+
+export type PrezSearchOptionsDefault = {
+    parserMode?: "default";
+};
+
+export type PrezSearchOptionsLuceneShacl = {
+    parserMode: "jena-lucene-shacl";
+};
+
+export type PrezSearchOptions = PrezSearchOptionsDefault | PrezSearchOptionsLuceneShacl;
+
 /**
- * Represents a search result
+ * Represents a single predicate/snippet pair inside a Lucene SHACL search result.
  */
-export type PrezSearchResult = {
+export type PrezSearchMatch = {
+    predicate: PrezNode;
+    match: PrezLiteral;
+};
+
+/**
+ * Represents the default flat Prez search result shape.
+ */
+export type PrezFlatSearchResult = {
     hash: string;
     weight: number;
     predicate: PrezNode;
     match: PrezLiteral;
     resource: PrezFocusNode;
 };
 
+/**
+ * Backwards-compatible alias for the default flat search result shape.
+ */
+export type PrezSearchResult = PrezFlatSearchResult;
+
+/**
+ * Represents the Jena Lucene SHACL search result shape.
+ */
+export type PrezLuceneShaclSearchResult = {
+    hash: string;
+    weight: number;
+    resource: PrezFocusNode;
+    matches: PrezSearchMatch[];
+};
+
+/**
+ * Represents any supported Prez search result shape.
+ */
+export type PrezAnySearchResult = PrezFlatSearchResult | PrezLuceneShaclSearchResult;
+
 /**
  * Represents an item in Prez that contains node info and its related properties
  */
@@ -270,7 +310,7 @@ export type PrezDataTypes = 'item' | 'list' | 'search';
 
 export interface PrezData {
     type: PrezDataTypes;
-    data: PrezFocusNode | PrezFocusNode[] | PrezSearchResult[];
+    data: PrezFocusNode | PrezFocusNode[] | PrezAnySearchResult[];
     profiles: PrezProfileHeader[];
     parents: PrezLinkParent[];
     facets: PrezFacet[];
@@ -289,13 +329,25 @@ export interface PrezDataItem extends PrezData {
     store: RDFStore;
 }
 
-export interface PrezDataSearch extends PrezData {
+export interface PrezDataSearchBase extends Omit<PrezData, "type" | "data"> {
     type: 'search';
+    parserMode: PrezSearchParserMode;
     count: number;
-    data: PrezSearchResult[];
     maxReached: boolean;
 }
 
+export interface PrezDataSearchDefault extends PrezDataSearchBase {
+    parserMode: "default";
+    data: PrezFlatSearchResult[];
+}
+
+export interface PrezDataSearchLuceneShacl extends PrezDataSearchBase {
+    parserMode: "jena-lucene-shacl";
+    data: PrezLuceneShaclSearchResult[];
+}
+
+export type PrezDataSearch = PrezDataSearchDefault | PrezDataSearchLuceneShacl;
+
 export type PrezFacetValue = {
     term: (PrezLiteral | PrezNode);
     count: number;

packages/prez-lib/src/types.ts

@@ -0,0 +1,16 @@
+PREFIX prez: <https://prez.dev/>
+PREFIX ex: <https://example.com/>
+PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+
+<urn:hash:flat-1> a prez:SearchResult ;
+    prez:searchResultWeight "2.5"^^xsd:float ;
+    prez:searchResultPredicate ex:title ;
+    prez:searchResultMatch "Flat result match" ;
+    prez:searchResultURI ex:item-1 .
+
+ex:item-1 a ex:Thing ;
+    prez:label "Flat Item" ;
+    prez:description "Flat item description" .
+
+ex:title prez:label "Title" .
+ex:Thing prez:label "Thing" .