ochre-sdk 1.0.71 → 1.0.73

package/README.md

@@ -57,6 +57,8 @@ present and `error` is `null`; on failure, the parsed value is `null` and
   `category` lets the XQuery search only the matching OCHRE collection.
 - `fetchItemLinks(uuid, options)` fetches items linked from a source item and
   parses them as embedded OCHRE items.
+- `fetchItemOcrData(uuid, value, options)` fetches the positioned OCR strings of
+  an item that match a search value, for drawing hit boxes over a scanned page.
 - `fetchGallery(params, options)` fetches paginated resource galleries with an
   optional label filter.
 - `fetchWebsite(abbreviation, options)` fetches an OCHRE website presentation
@@ -119,6 +121,26 @@ const result = await fetchSetItems(
 Use `fetchSetPropertyValues` with the same query shape when you need facet data
 for a filtered result set.
 
+## OCR Data
+
+A Resource may carry an `<ocr>` layer holding the positioned output of an OCR run. The node hierarchy inside that layer is irregular and is not parsed, but any `<string>` node within it, at any depth, is read as one positioned OCR string.
+
+```ts
+import { fetchItemOcrData } from "ochre-sdk";
+
+const result = await fetchItemOcrData("<item-uuid>", "Artifact", {
+  matchMode: "exact",
+});
+
+for (const ocrString of result.ocrStrings ?? []) {
+  console.log(ocrString.content, ocrString.x, ocrString.y, ocrString.vertices);
+}
+```
+
+`x` and `y` come from `HPOS` and `VPOS` and give the top-left corner of the box, `width` and `height` its size, and `vertices` its full bounding polygon, which is not always rectangular. Each geometry field is null when the source attribute is absent or unparseable. `resourceUuid` names the Resource that owns the OCR layer, which differs from the requested item when the OCR lives on a child Resource.
+
+Matching defaults to case-insensitive `includes` and runs against each string's `CONTENT`. Because a `<string>` holds a single OCR word, a multi-word search value is split on whitespace and a string is returned when it matches any one term, which pairs with how the `ocrText` query target tokenizes. Requesting an item that does not exist is an error; an item with no OCR layer, or no matches, returns an empty array.
+
 ## Helpers And Types
 
 The root export includes the SDK's public TypeScript model, website component

package/dist/constants.mjs

@@ -30,11 +30,6 @@ const XML_ARRAY_TAGS = [
 	"reference",
 	"coord",
 	"area",
-	"Page",
-	"TextBlock",
-	"TextLine",
-	"ocrItem",
-	"ocrMatch",
 	"footnote",
 	"language",
 	"section",

package/dist/fetchers/gallery.mjs

@@ -1,5 +1,5 @@
 import { DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../constants.mjs";
-import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utilities.mjs";
+import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../utilities.mjs";
 import { gallerySchema, iso639_3Schema } from "../schemas.mjs";
 import { restoreXMLMetadata } from "../xml/metadata.mjs";
 import { parseGallery } from "../parsers/index.mjs";
@@ -37,7 +37,11 @@ function buildXQuery(parameters) {
 	const { uuid, filter, page, perPage } = parameters;
 	const start = (page - 1) * perPage + 1;
 	const filterLiteral = stringLiteral(filter?.trim() ?? "");
-	return `<ochre>{
+	return `xquery version "1.0-ml";
+
+${SUPPLEMENTAL_XQUERY_PROLOG}
+
+<ochre>{
   for $q in doc()/ochre[@uuid=${stringLiteral(uuid)}]
   let $filter := ${filterLiteral}
   let $resources := $q//items/resource
@@ -47,9 +51,11 @@ function buildXQuery(parameters) {
     else $resources[contains(lower-case(string-join(identification/label//text(), "")), lower-case($filter))]
   let $maxLength := count($filtered)
   return <gallery maxLength="{$maxLength}">{
-    $q/metadata/project,
-    $q/metadata/item,
-    subsequence($filtered, ${start}, ${perPage})
+    ${omitSupplemental(`(
+      $q/metadata/project,
+      $q/metadata/item,
+      subsequence($filtered, ${start}, ${perPage})
+    )`)}
   }</gallery>
 }</ochre>`;
 }

package/dist/fetchers/item-children.mjs

@@ -1,5 +1,5 @@
 import { DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../constants.mjs";
-import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utilities.mjs";
+import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../utilities.mjs";
 import { iso639_3Schema, uuidSchema } from "../schemas.mjs";
 import { restoreXMLMetadata } from "../xml/metadata.mjs";
 import { parseLinkedItems } from "../parsers/index.mjs";
@@ -51,6 +51,8 @@ function buildXQuery(uuid, category) {
 	const collectionQueries = Array.from(categories, (possibleCategory) => `cts:search(fn:collection("ochre/${possibleCategory}")/ochre, $uuid-query)`);
 	return `xquery version "1.0-ml";
 
+${SUPPLEMENTAL_XQUERY_PROLOG}
+
 declare function local:item-children($nodes as node()*) as node()* {
   for $node in $nodes
   return
@@ -89,7 +91,7 @@ let $children :=
   else ()
 return
   <ochre>
-    <items>{$children}</items>
+    <items>{${omitSupplemental("$children")}}</items>
   </ochre>`;
 }
 async function fetchItemChildren(uuid, options) {

package/dist/fetchers/item-links.mjs

@@ -1,5 +1,5 @@
 import { DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../constants.mjs";
-import { createSchemaValidationError, getErrorOutput } from "../utilities.mjs";
+import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../utilities.mjs";
 import { iso639_3Schema, uuidSchema } from "../schemas.mjs";
 import { restoreXMLMetadata } from "../xml/metadata.mjs";
 import { parseLinkedItems } from "../parsers/index.mjs";
@@ -40,7 +40,7 @@ function resolveItemLinksLanguages(data, requestedLanguages) {
 * @returns An XQuery string
 */
 function buildXQuery(uuid) {
-	return `<ochre>{${`let $item-uuid := "${uuid}"
+	const xquery = `let $item-uuid := ${stringLiteral(uuid)}
 
 let $source-items := (
   fn:collection("ochre/resource")/ochre[@uuid = $item-uuid]/resource,
@@ -64,7 +64,7 @@ let $link-nodes := (
 
 return
     <items>{
-      for $link at $position in $link-nodes
+      ${omitSupplemental(`for $link at $position in $link-nodes
       let $uuid := $link/@uuid/string()
       let $category := name($link)
       where $uuid ne "" and not($uuid = $link-nodes[position() lt $position]/@uuid/string())
@@ -80,8 +80,13 @@ return
         else if ($category = "set") then fn:collection("ochre/set")/ochre/set[@uuid = $uuid]
         else if ($category = "spatialUnit") then fn:collection("ochre/spatialUnit")/ochre/spatialUnit[@uuid = $uuid]
         else if ($category = "concept") then fn:collection("ochre/concept")/ochre/concept[@uuid = $uuid]
-        else ()
-    }</items>`}}</ochre>`;
+        else ()`)}
+    }</items>`;
+	return `xquery version "1.0-ml";
+
+${SUPPLEMENTAL_XQUERY_PROLOG}
+
+<ochre>{${xquery}}</ochre>`;
 }
 async function fetchItemLinks(uuid, options) {
 	try {

package/dist/fetchers/item-ocr-data.d.mts

@@ -0,0 +1,37 @@
+import { OcrString } from "../types/index.mjs";
+//#region src/fetchers/item-ocr-data.d.ts
+/**
+ * Fetches and parses the OCR strings of an OCHRE item that match a search value
+ *
+ * Resources may carry an `<ocr>` layer whose internal hierarchy is irregular
+ * and therefore not parsed. Only its `<string>` nodes are returned, wherever
+ * they occur in that subtree, in document order. Matching runs per string, and
+ * each `<string>` holds a single OCR word, so a multi-word search value is
+ * split on whitespace and a string is returned when it matches any one term.
+ * Nested child Resources are searched too, with `resourceUuid` naming the
+ * Resource each match belongs to.
+ *
+ * @param uuid - The UUID of the OCHRE item to read the OCR layer of
+ * @param value - The search value to match against each OCR string's content
+ * @param options - Options for the fetch
+ * @param options.matchMode - Whether a term has to be contained in a string's content ("includes", the default) or equal it ("exact")
+ * @param options.isCaseSensitive - Whether matching is case sensitive, defaulting to false
+ * @param options.fetch - The fetch function to use
+ * @returns The matching OCR strings, an empty array when the item has no OCR
+ * layer or nothing matches, and a null output on fetch/parse errors
+ */
+declare function fetchItemOcrData(uuid: string, value: string, options?: {
+  matchMode?: "includes" | "exact";
+  isCaseSensitive?: boolean;
+  fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
+}): Promise<{
+  ocrStrings: Array<OcrString>;
+  error: null;
+  detailedError: null;
+} | {
+  ocrStrings: null;
+  error: string;
+  detailedError: string;
+}>;
+//#endregion
+export { fetchItemOcrData };

package/dist/fetchers/item-ocr-data.mjs

@@ -0,0 +1,166 @@
+import { XML_PARSER_OPTIONS } from "../constants.mjs";
+import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utilities.mjs";
+import { itemOcrDataParametersSchema } from "../schemas.mjs";
+import * as v from "valibot";
+import { XMLParser } from "fast-xml-parser";
+//#region src/fetchers/item-ocr-data.ts
+const OCR_STRING_VERTEX_REGEX = /\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)/g;
+/**
+* Schema for a single matched OCR string in the OCHRE API response
+*/
+const ocrStringSchema = v.object({
+	resourceUuid: v.optional(v.string(), ""),
+	content: v.optional(v.string(), ""),
+	x: v.optional(v.string(), ""),
+	y: v.optional(v.string(), ""),
+	width: v.optional(v.string(), ""),
+	height: v.optional(v.string(), ""),
+	vertices: v.optional(v.string(), "")
+});
+/**
+* Schema for the item OCR data OCHRE API response
+*/
+const responseSchema = v.object({ result: v.object({ ochre: v.object({ ocrStrings: v.object({
+	found: v.optional(v.string(), "false"),
+	ocrString: v.optional(v.union([v.array(ocrStringSchema), ocrStringSchema]))
+}) }) }) });
+function getSearchTerms(parameters) {
+	const { value, isCaseSensitive } = parameters;
+	const terms = [];
+	for (const term of value.split(/\s+/u)) if (term !== "") terms.push(isCaseSensitive ? term : term.toLocaleLowerCase("en-US"));
+	return terms;
+}
+function parseOcrStringNumber(value) {
+	const trimmedValue = value.trim();
+	if (trimmedValue === "") return null;
+	const numericValue = Number(trimmedValue);
+	return Number.isFinite(numericValue) ? numericValue : null;
+}
+function parseOcrStringVertices(value) {
+	const vertices = [];
+	for (const match of value.matchAll(OCR_STRING_VERTEX_REGEX)) {
+		const x = Number(match[1]);
+		const y = Number(match[2]);
+		if (Number.isFinite(x) && Number.isFinite(y)) vertices.push({
+			x,
+			y
+		});
+	}
+	return vertices;
+}
+/**
+* Build an XQuery string to fetch matching OCR strings from the OCHRE API
+*
+* The `<ocr>` layer is marked supplemental, so it is deliberately read without
+* the supplemental stripping the other fetchers apply. Only the `<string>`
+* nodes are projected, at any depth, because OCHRE does not guarantee the shape
+* of the surrounding hierarchy.
+*
+* The matches are wrapped in an `<ocrStrings>` element rather than returned
+* directly under `<ochre>`: the API collapses an `<ochre>` element that has no
+* element children down to a bare `<ochre/>`, which would drop the `found`
+* flag and make "no such item" indistinguishable from "no matches".
+* @param parameters - The parameters for the fetch
+* @param parameters.uuid - The UUID of the OCHRE item to read the OCR layer of
+* @param parameters.terms - The whitespace-separated search terms to match against, already lowercased for case-insensitive matching
+* @param parameters.matchMode - Whether a term has to be contained in a string's content or equal it
+* @param parameters.isCaseSensitive - Whether matching is case sensitive
+* @returns An XQuery string
+*/
+function buildXQuery(parameters) {
+	const { uuid, terms, matchMode, isCaseSensitive } = parameters;
+	const termValues = terms.map((term) => stringLiteral(term));
+	const contentExpression = isCaseSensitive ? "string($string/@CONTENT)" : "lower-case(string($string/@CONTENT))";
+	const matchExpression = matchMode === "exact" ? `normalize-space(${contentExpression}) = $term` : `contains(${contentExpression}, $term)`;
+	return `xquery version "1.0-ml";
+
+declare variable $terms := (${termValues.join(", ")});
+
+let $ochre := doc(${stringLiteral(uuid)})/ochre
+let $ocrStrings :=
+  for $string in $ochre//ocr//string[@CONTENT]
+  where (some $term in $terms satisfies ${matchExpression})
+  return <ocrString
+    resourceUuid="{string($string/ancestor::resource[1]/@uuid)}"
+    content="{string($string/@CONTENT)}"
+    x="{string($string/@HPOS)}"
+    y="{string($string/@VPOS)}"
+    width="{string($string/@WIDTH)}"
+    height="{string($string/@HEIGHT)}"
+    vertices="{string($string/@VERTICES)}"/>
+
+return <ochre><ocrStrings found="{exists($ochre)}">{$ocrStrings}</ocrStrings></ochre>`;
+}
+/**
+* Fetches and parses the OCR strings of an OCHRE item that match a search value
+*
+* Resources may carry an `<ocr>` layer whose internal hierarchy is irregular
+* and therefore not parsed. Only its `<string>` nodes are returned, wherever
+* they occur in that subtree, in document order. Matching runs per string, and
+* each `<string>` holds a single OCR word, so a multi-word search value is
+* split on whitespace and a string is returned when it matches any one term.
+* Nested child Resources are searched too, with `resourceUuid` naming the
+* Resource each match belongs to.
+*
+* @param uuid - The UUID of the OCHRE item to read the OCR layer of
+* @param value - The search value to match against each OCR string's content
+* @param options - Options for the fetch
+* @param options.matchMode - Whether a term has to be contained in a string's content ("includes", the default) or equal it ("exact")
+* @param options.isCaseSensitive - Whether matching is case sensitive, defaulting to false
+* @param options.fetch - The fetch function to use
+* @returns The matching OCR strings, an empty array when the item has no OCR
+* layer or nothing matches, and a null output on fetch/parse errors
+*/
+async function fetchItemOcrData(uuid, value, options) {
+	try {
+		const parameters = v.parse(itemOcrDataParametersSchema, {
+			uuid,
+			value,
+			matchMode: options?.matchMode,
+			isCaseSensitive: options?.isCaseSensitive
+		});
+		const terms = getSearchTerms({
+			value: parameters.value,
+			isCaseSensitive: parameters.isCaseSensitive
+		});
+		const xquery = buildXQuery({
+			uuid: parameters.uuid,
+			terms,
+			matchMode: parameters.matchMode,
+			isCaseSensitive: parameters.isCaseSensitive
+		});
+		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
+			method: "POST",
+			body: xquery,
+			headers: { "Content-Type": "application/xquery" }
+		});
+		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`, { cause: response.statusText });
+		const dataRaw = await response.text();
+		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
+		const { success, issues, output } = v.safeParse(responseSchema, data);
+		if (!success) throw createSchemaValidationError("Failed to parse OCHRE item OCR data", issues);
+		const { found, ocrString } = output.result.ochre.ocrStrings;
+		if (found !== "true") throw new Error(`No OCHRE item found for UUID: ${parameters.uuid}`, { cause: parameters.uuid });
+		const parsedOcrStrings = ocrString == null ? [] : Array.isArray(ocrString) ? ocrString : [ocrString];
+		return {
+			ocrStrings: Array.from(parsedOcrStrings, (parsedOcrString) => ({
+				resourceUuid: parsedOcrString.resourceUuid !== "" ? parsedOcrString.resourceUuid : null,
+				content: parsedOcrString.content,
+				x: parseOcrStringNumber(parsedOcrString.x),
+				y: parseOcrStringNumber(parsedOcrString.y),
+				width: parseOcrStringNumber(parsedOcrString.width),
+				height: parseOcrStringNumber(parsedOcrString.height),
+				vertices: parseOcrStringVertices(parsedOcrString.vertices)
+			})),
+			error: null,
+			detailedError: null
+		};
+	} catch (error) {
+		return {
+			ocrStrings: null,
+			...getErrorOutput(error, "Failed to fetch item OCR data")
+		};
+	}
+}
+//#endregion
+export { fetchItemOcrData };

package/dist/fetchers/item.mjs

@@ -1,5 +1,5 @@
 import { XML_PARSER_OPTIONS } from "../constants.mjs";
-import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../utilities.mjs";
+import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../utilities.mjs";
 import { iso639_3Schema, uuidSchema } from "../schemas.mjs";
 import { restoreXMLMetadata } from "../xml/metadata.mjs";
 import { parseItem } from "../parsers/index.mjs";
@@ -31,27 +31,24 @@ function assertItemCategoryAllowed(category, containedItemCategory) {
 	for (const possibleCategory of categories) if (isItemContainerCategory(possibleCategory)) return;
 	throw new Error(`containedItemCategory can only be used when category is "tree" or "set"; received category "${categories.join(", ")}"`);
 }
-function buildOmitEmbeddedItemsXQuery(uuid, category) {
-	const collectionCategories = [];
-	const categories = category == null ? [
-		"tree",
-		"bibliography",
-		"concept",
-		"spatialUnit",
-		"period",
-		"resource",
-		"set"
-	] : typeof category === "string" ? [category] : category;
-	for (const possibleCategory of categories) if (!collectionCategories.includes(possibleCategory)) collectionCategories.push(possibleCategory);
-	const collectionQueries = Array.from(collectionCategories, (collectionCategory) => `cts:search(fn:collection("ochre/${collectionCategory}")/ochre, $uuid-query)`);
-	return `xquery version "1.0-ml";
-
-let $uuid := ${stringLiteral(uuid)}
-let $uuid-query := cts:element-attribute-value-query(xs:QName("ochre"), xs:QName("uuid"), $uuid, "exact")
-let $ochre := (
-  ${collectionQueries.join(",\n  ")}
-)[1]
-let $item := (
+/**
+* Build an XQuery string to fetch a single OCHRE item document by UUID.
+*
+* Nodes marked `supplemental="true"` are always dropped. `$item` only ever
+* binds the item categories that carry embedded items, so the omission branch
+* is a no-op for every other category.
+*
+* @param parameters - The parameters for the fetch
+* @param parameters.uuid - The UUID of the OCHRE item to fetch
+* @param parameters.shouldOmitEmbeddedItems - Whether to drop the embedded item hierarchy
+* @returns An XQuery string
+*/
+function buildXQuery(parameters) {
+	const { uuid, shouldOmitEmbeddedItems } = parameters;
+	const letClauses = [`let $ochre := doc(${stringLiteral(uuid)})/ochre`];
+	let itemNodesExpression = "$ochre/node()";
+	if (shouldOmitEmbeddedItems) {
+		letClauses.push(`let $item := (
   $ochre/tree,
   $ochre/bibliography,
   $ochre/concept,
@@ -59,17 +56,25 @@ let $item := (
   $ochre/period,
   $ochre/resource,
   $ochre/set
-)[1]
-let $embedded-child-name := if (local-name($item) = ("tree", "set")) then "items" else local-name($item)
+)[1]`, `let $embedded-child-name := if (local-name($item) = ("tree", "set")) then "items" else local-name($item)`);
+		itemNodesExpression = `(
+      for $node in $ochre/node()
+      return
+        if ($node is $item)
+        then element { node-name($item) } { $item/@*, $item/node()[not(self::*[local-name() = $embedded-child-name])] }
+        else $node
+    )`;
+	}
+	return `xquery version "1.0-ml";
+
+${SUPPLEMENTAL_XQUERY_PROLOG}
+
+${letClauses.join("\n")}
 return
-  if (empty($ochre) or empty($item)) then ()
+  if (empty($ochre)) then ()
   else element ochre {
     $ochre/@*,
-    for $node in $ochre/node()
-    return
-      if ($node is $item)
-      then element { node-name($item) } { $item/@*, $item/node()[not(self::*[local-name() = $embedded-child-name])] }
-      else $node
+    ${omitSupplemental(itemNodesExpression)}
   }`;
 }
 function omitEmbeddedItems(item) {
@@ -106,39 +111,19 @@ async function fetchItem(uuid, options) {
 		const parsedUuid = v.parse(uuidSchema, uuid);
 		assertItemCategoryAllowed(options?.category, options?.containedItemCategory);
 		const shouldOmitEmbeddedItems = options?.shouldOmitEmbeddedItems === true;
-		let shouldFetchOmittedEmbeddedItems = shouldOmitEmbeddedItems;
-		let omitEmbeddedItemsCategory;
-		if (options?.category != null) if (typeof options.category === "string") if (isItemCategoryWithEmbeddedItems(options.category)) omitEmbeddedItemsCategory = options.category;
-		else shouldFetchOmittedEmbeddedItems = false;
-		else {
-			const categories = [];
-			for (const possibleCategory of options.category) if (isItemCategoryWithEmbeddedItems(possibleCategory)) categories.push(possibleCategory);
-			omitEmbeddedItemsCategory = categories;
-			shouldFetchOmittedEmbeddedItems = shouldOmitEmbeddedItems && categories.length > 0;
-		}
 		const languages = options?.languages == null ? [] : parseLanguages(options.languages);
-		const fetcher = options?.fetch ?? fetch;
-		const regularItemUrl = `https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?uuid=${parsedUuid}&xsl=none&lang="*"`;
-		let response = shouldFetchOmittedEmbeddedItems ? await fetcher("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
+		const response = await (options?.fetch ?? fetch)("https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery&xsl=none&lang=\"*\"", {
 			method: "POST",
-			body: buildOmitEmbeddedItemsXQuery(parsedUuid, omitEmbeddedItemsCategory),
+			body: buildXQuery({
+				uuid: parsedUuid,
+				shouldOmitEmbeddedItems
+			}),
 			headers: { "Content-Type": "application/xquery" }
-		}) : await fetcher(regularItemUrl);
+		});
 		if (!response.ok) throw new Error("Failed to fetch OCHRE data", { cause: response.statusText });
 		const dataRaw = await response.text();
-		const parser = new XMLParser(XML_PARSER_OPTIONS);
-		let data = parser.parse(dataRaw);
-		if (shouldFetchOmittedEmbeddedItems && typeof data === "object" && data != null && "result" in data) {
-			const result = data.result;
-			if (typeof result === "object" && result != null && "ochre" in result) {
-				const ochre = result.ochre;
-				if (typeof ochre === "object" && ochre != null && (Object.keys(ochre).length === 0 || "payload" in ochre && ochre.payload === "" && Object.keys(ochre).length === 1)) {
-					response = await fetcher(regularItemUrl);
-					if (!response.ok) throw new Error("Failed to fetch OCHRE data", { cause: response.statusText });
-					data = parser.parse(await response.text());
-				}
-			}
-		}
+		const data = new XMLParser(XML_PARSER_OPTIONS).parse(dataRaw);
+		if (data.result?.ochre?.uuid == null) throw new Error(`No OCHRE item found for UUID "${parsedUuid}"`, { cause: dataRaw });
 		const { success, issues, output } = v.safeParse(XMLData, data);
 		if (!success) throw createSchemaValidationError("Failed to parse OCHRE data", issues);
 		restoreXMLMetadata(output, data);

package/dist/fetchers/set/items.mjs

@@ -1,10 +1,10 @@
 import { BELONGS_TO_COLLECTION_UUID, DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../../constants.mjs";
-import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../../utilities.mjs";
-import { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
+import { SUPPLEMENTAL_XQUERY_PROLOG, createSchemaValidationError, getErrorOutput, omitSupplemental, stringLiteral } from "../../utilities.mjs";
 import { iso639_3Schema, setItemsParametersSchema } from "../../schemas.mjs";
 import { restoreXMLMetadata } from "../../xml/metadata.mjs";
 import { parseSetItems } from "../../parsers/index.mjs";
 import { XMLSetItemsData } from "../../xml/schemas.mjs";
+import { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/set/items.ts
@@ -139,18 +139,32 @@ function buildXQuery(parameters) {
 	const startPosition = (page - 1) * pageSize + 1;
 	const setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
 	const compiledQueryPlan = buildQueryPlan({ queries });
-	const baseItemsExpression = `doc()/ochre/set[@uuid = $setScopeUuids]/items/*${compiledQueryPlan.itemPredicates}`;
-	const itemsQueryExpressions = [];
+	const baseItemsExpression = "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
 	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
-	if (compiledQueryPlan.queryExpression != null) itemsQueryExpressions.push(compiledQueryPlan.queryExpression);
-	if (belongsToCollectionQueryExpression != null) itemsQueryExpressions.push(belongsToCollectionQueryExpression);
-	const itemsQueryExpression = buildAndCtsQueryExpression(itemsQueryExpressions);
 	const orderedItemsClause = buildOrderedItemsClause(sort);
-	const xqueryDeclarations = ["xquery version \"1.0-ml\";", setScopeDeclaration];
+	const xqueryDeclarations = [
+		"xquery version \"1.0-ml\";",
+		setScopeDeclaration,
+		SUPPLEMENTAL_XQUERY_PROLOG
+	];
 	if (compiledQueryPlan.prolog !== "") xqueryDeclarations.push(compiledQueryPlan.prolog);
-	const letClauses = Array.from(compiledQueryPlan.ocrBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
-	if (itemsQueryExpression == null) letClauses.push(`let $items := ${baseItemsExpression}`);
-	else letClauses.push(`let $query := ${itemsQueryExpression}`, `let $items := cts:search(${baseItemsExpression}, $query)`);
+	const letClauses = Array.from(compiledQueryPlan.ocrTextBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
+	const branchExpressions = [];
+	for (const [index, branch] of compiledQueryPlan.branches.entries()) {
+		const branchQueryExpressions = [];
+		if (branch.queryExpression != null) branchQueryExpressions.push(branch.queryExpression);
+		if (belongsToCollectionQueryExpression != null) branchQueryExpressions.push(belongsToCollectionQueryExpression);
+		const branchQueryExpression = buildAndCtsQueryExpression(branchQueryExpressions);
+		const branchItemsExpression = `${baseItemsExpression}${branch.itemPredicates}`;
+		if (branchQueryExpression == null) {
+			branchExpressions.push(branchItemsExpression);
+			continue;
+		}
+		const queryVariableName = compiledQueryPlan.branches.length === 1 ? "$query" : `$query${index + 1}`;
+		letClauses.push(`let ${queryVariableName} := ${branchQueryExpression}`);
+		branchExpressions.push(`cts:search(${branchItemsExpression}, ${queryVariableName})`);
+	}
+	letClauses.push(`let $items := ${branchExpressions.length === 1 ? branchExpressions[0] : `(${branchExpressions.join(" | ")})`}`);
 	const itemsClause = letClauses.join("\n  ");
 	return `${xqueryDeclarations.join("\n\n")}
 
@@ -161,7 +175,7 @@ ${itemsClause}
   let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})
 
   return <items totalCount="{$totalCount}" page="${page}" pageSize="${pageSize}">{
-    $pagedItems
+    ${omitSupplemental("$pagedItems")}
   }</items>
 }</ochre>`;
 }

package/dist/fetchers/set/property-values.mjs

@@ -1,9 +1,9 @@
 import { BELONGS_TO_COLLECTION_UUID, DEFAULT_LANGUAGES, XML_PARSER_OPTIONS } from "../../constants.mjs";
-import { createSchemaValidationError, getErrorOutput, stringLiteral } from "../../utilities.mjs";
+import { NOT_SUPPLEMENTAL_PREDICATE, createSchemaValidationError, getErrorOutput, stringLiteral } from "../../utilities.mjs";
 import { MultilingualString } from "../../parsers/multilingual.mjs";
-import { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
 import { setPropertyValuesParametersSchema } from "../../schemas.mjs";
 import { parseXMLContent } from "../../parsers/string.mjs";
+import { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/set/property-values.ts
@@ -191,12 +191,8 @@ function buildXQuery(parameters) {
 	const { setScopeUuids, belongsToCollectionScopeUuids, queries, propertyFacetSelectors, attributes, isLimitedToLeafPropertyValues } = parameters;
 	const setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
 	const compiledQueryPlan = buildQueryPlan({ queries: getItemFilterQueriesFromPropertyValueQueries(queries) });
-	const baseItemsExpression = `doc()/ochre/set[@uuid = $setScopeUuids]/items/*${compiledQueryPlan.itemPredicates}`;
-	const itemsQueryExpressions = [];
+	const baseItemsExpression = "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
 	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
-	if (compiledQueryPlan.queryExpression != null) itemsQueryExpressions.push(compiledQueryPlan.queryExpression);
-	if (belongsToCollectionQueryExpression != null) itemsQueryExpressions.push(belongsToCollectionQueryExpression);
-	const itemsQueryExpression = buildAndCtsQueryExpression(itemsQueryExpressions);
 	const valueFilter = isLimitedToLeafPropertyValues ? "[not(@i)]" : "";
 	const queryBlocks = [];
 	const returnedSequences = [];
@@ -331,9 +327,9 @@ let $_property-aggregation := xdmp:eager(
   let $global-seen := map:map()
   let $variable-seen := map:map()
   return
-    for $p in $item/properties/property[${facetPropertyPredicate}]
+    for $p in $item/properties/property[${facetPropertyPredicate}]${NOT_SUPPLEMENTAL_PREDICATE}
     let $variable-uuid := string($p/label/@uuid)
-    for $v in $p/value${valueFilter}
+    for $v in $p/value${valueFilter}${NOT_SUPPLEMENTAL_PREDICATE}
     let $value-uuid := string($v/@uuid)
     let $raw-value := string($v/@rawValue)
     let $data-type := string($v/@dataType)
@@ -370,7 +366,7 @@ let $_bibliography-aggregation := xdmp:eager(
   for $item in $items
   let $seen := map:map()
   return
-    for $bibliography in $item/bibliographies/bibliography
+    for $bibliography in $item/bibliographies/bibliography${NOT_SUPPLEMENTAL_PREDICATE}
     let $label := string-join($bibliography/identification/label/content[@xml:lang="eng"]//text(), "")
     where string-length($label) gt 0
     return local:add-attribute-facet($bibliography-counts, $seen, $label)
@@ -390,7 +386,7 @@ let $_period-aggregation := xdmp:eager(
   for $item in $items
   let $seen := map:map()
   return
-    for $period in $item/periods/period
+    for $period in $item/periods/period${NOT_SUPPLEMENTAL_PREDICATE}
     let $label := string-join($period/identification/label/content[@xml:lang="eng"]//text(), "")
     where string-length($label) gt 0
     return local:add-attribute-facet($period-counts, $seen, $label)
@@ -404,9 +400,23 @@ let $period-values :=
   )`);
 		returnedSequences.push("$period-values");
 	}
-	const letClauses = Array.from(compiledQueryPlan.ocrBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
-	if (itemsQueryExpression == null) letClauses.push(`let $items := ${baseItemsExpression}`);
-	else letClauses.push(`let $query := ${itemsQueryExpression}`, `let $items := cts:search(${baseItemsExpression}, $query)`);
+	const letClauses = Array.from(compiledQueryPlan.ocrTextBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
+	const branchExpressions = [];
+	for (const [index, branch] of compiledQueryPlan.branches.entries()) {
+		const branchQueryExpressions = [];
+		if (branch.queryExpression != null) branchQueryExpressions.push(branch.queryExpression);
+		if (belongsToCollectionQueryExpression != null) branchQueryExpressions.push(belongsToCollectionQueryExpression);
+		const branchQueryExpression = buildAndCtsQueryExpression(branchQueryExpressions);
+		const branchItemsExpression = `${baseItemsExpression}${branch.itemPredicates}`;
+		if (branchQueryExpression == null) {
+			branchExpressions.push(branchItemsExpression);
+			continue;
+		}
+		const queryVariableName = compiledQueryPlan.branches.length === 1 ? "$query" : `$query${index + 1}`;
+		letClauses.push(`let ${queryVariableName} := ${branchQueryExpression}`);
+		branchExpressions.push(`cts:search(${branchItemsExpression}, ${queryVariableName})`);
+	}
+	letClauses.push(`let $items := ${branchExpressions.length === 1 ? branchExpressions[0] : `(${branchExpressions.join(" | ")})`}`);
 	const itemsClause = letClauses.join("\n  ");
 	return `${xqueryDeclarations.join("\n\n")}