ochre-sdk 1.0.72 → 1.0.74

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,54 @@ const result = await fetchSetItems(
 Use `fetchSetPropertyValues` with the same query shape when you need facet data
 for a filtered result set.
 
+### OCR Text Queries
+
+The `ocr` target searches the OCR text layer of the Resource items in a Set. It takes no `language`, because OCR text carries none.
+
+```ts
+const queries: Query = {
+  and: [
+    {
+      target: "ocr",
+      value: "Cappaert",
+      matchMode: "includes",
+      isCaseSensitive: false,
+    },
+    {
+      target: "title",
+      value: "Convocation",
+      matchMode: "includes",
+      isCaseSensitive: false,
+      language: "eng",
+    },
+  ],
+};
+```
+
+Every `<string>` node in that layer holds a single OCR word, so `includes` matches each search term as its own word anywhere in the layer, in any order, with `*` and `?` wildcards supported. `exact` instead matches the terms as a run of adjacent whole words, so `"THE COLLEGE"` matches a page carrying that phrase but not one where the two words merely appear apart. An item matches when the OCR layer of the item itself or of any of its child Resources matches.
+
+Set item projections do not carry the OCR layer, so an `ocr` leaf is resolved by an extra index-only search over the Resource documents whose matching UUIDs are then joined back onto the Set items. It still composes with `and`, `or`, and `isNegated` like any other leaf, and repeating the same OCR search inside one tree only costs one search.
+
+## 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. 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 { buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/set/items.ts
@@ -138,30 +138,28 @@ function buildXQuery(parameters) {
 	const { queries, sort, setScopeUuids, belongsToCollectionScopeUuids, page, pageSize } = 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 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 compiledQueryPlan = buildQueryPlan({
+		queries,
+		baseItemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*",
+		scopeQueryExpression: buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID)
+	});
 	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 itemsClause = letClauses.join("\n  ");
 	return `${xqueryDeclarations.join("\n\n")}
 
 <ochre>{
-${itemsClause}
+${compiledQueryPlan.itemsClause}
   let $totalCount := count($items)
   ${orderedItemsClause}
   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 { buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/set/property-values.ts
@@ -190,13 +190,11 @@ const responseSchema = v.object({ result: v.object({ ochre: v.object({
 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 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 compiledQueryPlan = buildQueryPlan({
+		queries: getItemFilterQueriesFromPropertyValueQueries(queries),
+		baseItemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*",
+		scopeQueryExpression: buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID)
+	});
 	const valueFilter = isLimitedToLeafPropertyValues ? "[not(@i)]" : "";
 	const queryBlocks = [];
 	const returnedSequences = [];
@@ -331,9 +329,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 +368,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 +388,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,14 +402,10 @@ 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 itemsClause = letClauses.join("\n  ");
 	return `${xqueryDeclarations.join("\n\n")}
 
 <ochre>{
-${itemsClause}
+${compiledQueryPlan.itemsClause}
 ${queryBlocks.join("\n\n")}
 
 return (${returnedSequences.join(", ")})