ochre-sdk 1.0.73 → 1.0.75

package/README.md

@@ -121,9 +121,37 @@ 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 word node in that layer holds a single OCR word in its `CONTENT` attribute, 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.
+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 word node within it, at any depth, is read as one positioned OCR string. A word node is any element named `string` in any casing and any namespace, and its text comes from the `CONTENT` attribute rather than from the element's text content.
 
 ```ts
 import { fetchItemOcrData } from "ochre-sdk";
@@ -137,9 +165,9 @@ for (const ocrString of result.ocrStrings ?? []) {
 }
 ```
 
-`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.
+`x` and `y` come from `HPOS` and `VPOS` and give the top-left corner of the box, `width` and `height` its size, and `vertices` comes from `VERTICES` and is its full bounding polygon, which is not always rectangular. Each geometry field is null when the source attribute is absent or unparseable, and `vertices` is then empty. `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.
+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
 

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

@@ -4,12 +4,15 @@ import { OcrString } from "../types/index.mjs";
  * 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.
+ * and therefore not parsed. Only its word nodes are returned, wherever they
+ * occur in that subtree, in document order. A word node is any element whose
+ * name is `string` in any casing and any namespace, and matching reads its
+ * `CONTENT` attribute rather than its text content.
+ *
+ * Each word node holds a single OCR word, so a multi-word search value is split
+ * on whitespace and a node 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

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

@@ -52,9 +52,14 @@ function parseOcrStringVertices(value) {
 * 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 supplemental stripping the other fetchers apply. Word nodes are projected
+* at any depth, because OCHRE does not guarantee the shape of the surrounding
+* hierarchy.
+*
+* Both the container and the word nodes are matched on a case-folded
+* `local-name()` rather than a name test, because OCHRE varies the casing of
+* these elements and may serve them in a namespace. A plain `//ocr//string`
+* name test silently matches nothing in either of those cases.
 *
 * The matches are wrapped in an `<ocrStrings>` element rather than returned
 * directly under `<ochre>`: the API collapses an `<ochre>` element that has no
@@ -78,10 +83,10 @@ declare variable $terms := (${termValues.join(", ")});
 
 let $ochre := doc(${stringLiteral(uuid)})/ochre
 let $ocrStrings :=
-  for $string in $ochre//ocr//string[@CONTENT]
+  for $string in $ochre//*[lower-case(local-name(.)) = "ocr"]//*[lower-case(local-name(.)) = "string"][@CONTENT]
   where (some $term in $terms satisfies ${matchExpression})
   return <ocrString
-    resourceUuid="{string($string/ancestor::resource[1]/@uuid)}"
+    resourceUuid="{string($string/ancestor::*[local-name(.) = "resource"][1]/@uuid)}"
     content="{string($string/@CONTENT)}"
     x="{string($string/@HPOS)}"
     y="{string($string/@VPOS)}"
@@ -95,12 +100,15 @@ return <ochre><ocrStrings found="{exists($ochre)}">{$ocrStrings}</ocrStrings></o
 * 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.
+* and therefore not parsed. Only its word nodes are returned, wherever they
+* occur in that subtree, in document order. A word node is any element whose
+* name is `string` in any casing and any namespace, and matching reads its
+* `CONTENT` attribute rather than its text content.
+*
+* Each word node holds a single OCR word, so a multi-word search value is split
+* on whitespace and a node 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

package/dist/fetchers/set/items.mjs

@@ -4,7 +4,7 @@ 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 { buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/set/items.ts
@@ -138,9 +138,11 @@ 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/*";
-	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
+	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\";",
@@ -148,28 +150,10 @@ function buildXQuery(parameters) {
 		SUPPLEMENTAL_XQUERY_PROLOG
 	];
 	if (compiledQueryPlan.prolog !== "") xqueryDeclarations.push(compiledQueryPlan.prolog);
-	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")}
 
 <ochre>{
-${itemsClause}
+${compiledQueryPlan.itemsClause}
   let $totalCount := count($items)
   ${orderedItemsClause}
   let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})

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

@@ -3,7 +3,7 @@ import { NOT_SUPPLEMENTAL_PREDICATE, createSchemaValidationError, getErrorOutput
 import { MultilingualString } from "../../parsers/multilingual.mjs";
 import { setPropertyValuesParametersSchema } from "../../schemas.mjs";
 import { parseXMLContent } from "../../parsers/string.mjs";
-import { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan } from "../../query.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,9 +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/*";
-	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
+	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 = [];
@@ -400,28 +402,10 @@ let $period-values :=
   )`);
 		returnedSequences.push("$period-values");
 	}
-	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")}
 
 <ochre>{
-${itemsClause}
+${compiledQueryPlan.itemsClause}
 ${queryBlocks.join("\n\n")}
 
 return (${returnedSequences.join(", ")})

package/dist/fetchers/website.mjs

@@ -6,7 +6,7 @@ import { parseWebsite } from "../parsers/website/index.mjs";
 import * as v from "valibot";
 import { XMLParser } from "fast-xml-parser";
 //#region src/fetchers/website.ts
-async function validateWebsiteCredentials(uuid, credentials, fetcher) {
+async function areWebsiteCredentialsValid(uuid, credentials, fetcher) {
 	const security = typeof credentials === "string" ? { validate: credentials } : {
 		validate: credentials.password,
 		userOCHRE: credentials.username
@@ -69,7 +69,7 @@ async function fetchWebsite(abbreviation, options) {
 				error: null,
 				detailedError: null
 			};
-			if (!await validateWebsiteCredentials(website.uuid, options.credentials, fetcher)) throw new Error("Invalid credentials for protected website");
+			if (!await areWebsiteCredentialsValid(website.uuid, options.credentials, fetcher)) throw new Error("Invalid credentials for protected website");
 		}
 		return {
 			website,

package/dist/getters.d.mts

@@ -4,9 +4,13 @@ import { LanguageCodes, Property, PropertyLike, PropertyValueContent, SetItemPro
  * Options for property search operations.
  */
 type PropertyOptions = {
-  /** Whether to recursively search through nested properties. */
+  /**
+    Whether to recursively search through nested properties.
+    */
   includeNestedProperties?: boolean;
-  /** Whether to limit property values to leaf values. */
+  /**
+    Whether to limit property values to leaf values.
+    */
   limitToLeafPropertyValues?: boolean;
 };
 type PropertyContent<T extends LanguageCodes> = PropertyValueContent<T>["content"];

package/dist/parsers/multilingual.d.mts

@@ -26,11 +26,17 @@ type MultilingualStringEntries<T extends ReadonlyArray<string> = ReadonlyArray<s
  * Options for creating and working with multilingual strings
  */
 type MultilingualOptions = {
-  /** Default language to use for fallbacks */
+  /**
+    Default language to use for fallbacks
+    */
   defaultLanguage?: string;
-  /** Available languages for this string */
+  /**
+    Available languages for this string
+    */
   availableLanguages?: ReadonlyArray<string>;
-  /** Alias values carried by OCHRE as zxx content */
+  /**
+    Alias values carried by OCHRE as zxx content
+    */
   aliases?: ReadonlyArray<string>;
 };
 type MultilingualContent<T extends ReadonlyArray<string>> = Partial<Record<T[number], ReadonlyArray<MultilingualStringEntry>>>;
@@ -78,7 +84,9 @@ declare class MultilingualString<T extends ReadonlyArray<string> = ReadonlyArray
   /**
    * Create a new multilingual string from an object of language codes to text.
    */
-  /** @internal */
+  /**
+    @internal
+    */
   constructor(init: MultilingualStringInternalInit<T>);
   constructor(content: MultilingualStringObject<T>, languages: T, options?: MultilingualOptions);
   constructor(content?: Partial<Record<string, MultilingualStringInput>>, languages?: undefined, options?: MultilingualOptions);

package/dist/parsers/website/index.mjs

@@ -907,17 +907,18 @@ function parseWebpage(webpageResource, options, context, slugPrefix) {
 		returnWebpage.properties.isNavbarSearchBarDisplayed = pageReader.valueOr("navbar-search-bar-displayed", true);
 		const redirectValue = pageReader.valueNode("redirect-to");
 		const redirectTarget = parseWebsiteLinkTarget(redirectValue, context);
-		if (redirectTarget != null) if (redirectValue?.href == null && redirectValue?.uuid != null) returnWebpage.properties.redirect = {
-			type: "page",
-			slug: redirectTarget,
-			uuid: redirectValue.uuid
-		};
-		else returnWebpage.properties.redirect = {
-			type: "url",
-			href: redirectTarget,
-			isExternal: redirectTarget.startsWith("http")
-		};
-		else if (redirectValue?.uuid != null) returnWebpage.properties.redirect = {
+		if (redirectTarget != null) {
+			if (redirectValue?.href == null && redirectValue?.uuid != null) returnWebpage.properties.redirect = {
+				type: "page",
+				slug: redirectTarget,
+				uuid: redirectValue.uuid
+			};
+			else returnWebpage.properties.redirect = {
+				type: "url",
+				href: redirectTarget,
+				isExternal: redirectTarget.startsWith("http")
+			};
+		} else if (redirectValue?.uuid != null) returnWebpage.properties.redirect = {
 			type: "item",
 			uuid: redirectValue.uuid,
 			pageType: "item"
@@ -1015,7 +1016,7 @@ function parseSidebar(resources, options, context) {
 			}
 		}
 	}
-	if (items.length > 0 && title != null) returnSidebar = {
+	if (title != null && items.length > 0) returnSidebar = {
 		isDisplayed: true,
 		items,
 		title,

package/dist/query.d.mts

@@ -1,31 +1,32 @@
 import { Query } from "./types/index.mjs";
 //#region src/query.d.ts
-declare function buildAndCtsQueryExpression(queryExpressions: Array<string>): string | null;
 declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: Array<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
 /**
- * Compile a query tree into the CTS searches that resolve it
+ * Compile a query tree into the XQuery `let` clauses that bind `$items` to the
+ * matching Set items
  *
- * OCR text is not carried by Set item projections, so an `ocrText` leaf cannot
- * be a CTS term: it resolves to a document join whose UUID list can only be
- * applied as an item path predicate, and path predicates only ever AND. To keep
- * `ocrText` composable with `or` anyway, the tree is split on each distinct OCR
- * text condition, one branch per assignment of "this item is in that match
- * set". Every branch is a plain CTS search, and their union is the result.
- * Branches that the assignment already rules out are dropped, so a query whose
- * OCR text leaves are all conjunctive still compiles to a single search.
+ * Most queries compile to a single `cts:search` over the Set item projections.
+ * An `ocr` leaf cannot: the projections drop the `<ocr>` layer, so it resolves
+ * to a search over the Resource documents whose matching UUIDs are joined back
+ * in as an item path predicate. Path predicates only ever AND, so an `ocr` leaf
+ * that sits under an `or` becomes its own arm of a node union instead, and one
+ * that sits under an `and` alongside a union becomes an intersection.
+ *
+ * The searchable path has to stay inline in `cts:search`: binding it to a
+ * variable first makes every query XDMP-UNSEARCHABLE.
+ * @param parameters - The parameters for the compilation
+ * @param parameters.queries - Recursive query tree to compile, if any
+ * @param parameters.baseItemsExpression - The inline XQuery path selecting the items to search
+ * @param parameters.scopeQueryExpression - An optional CTS query ANDed into every compiled search
+ * @returns The prolog declaring the query helpers, and the `let` clauses binding `$items`
  */
 declare function buildQueryPlan(parameters: {
   queries: Query | null;
+  baseItemsExpression: string;
+  scopeQueryExpression?: string | null;
 }): {
   prolog: string;
-  ocrTextBindings: Array<{
-    name: string;
-    expression: string;
-  }>;
-  branches: Array<{
-    itemPredicates: string;
-    queryExpression: string | null;
-  }>;
+  itemsClause: string;
 };
 //#endregion
-export { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan };
+export { buildBelongsToCollectionQueryExpression, buildQueryPlan };

package/dist/query.mjs

@@ -12,7 +12,6 @@ const CTS_INCLUDES_STOP_WORDS = /* @__PURE__ */ new Set([
 const CTS_INCLUDES_TOKEN_WORD_REGEX = /^\p{L}+$/u;
 const CTS_INCLUDES_TOKEN_REGEX = /[\p{L}\p{N}*?]+/gu;
 const CTS_EXACT_TEXT_TOKEN_REGEX = /[\p{L}\p{N}]+/gu;
-const MAX_OCR_TEXT_CONDITIONS = 4;
 const CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
 	title: [
 		"identification",
@@ -239,7 +238,8 @@ function buildRichTextContentQueryExpression(parameters) {
 	const { value, matchMode, isCaseSensitive, language } = parameters;
 	return buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), matchMode === "exact" ? buildRichTextExactQueryExpression({
 		value,
-		isCaseSensitive
+		isCaseSensitive,
+		language
 	}) : buildCtsWordQueryExpression({
 		value,
 		matchMode,
@@ -472,83 +472,121 @@ function buildItemStringQueryExpression(parameters) {
 		language
 	})]);
 }
-function buildOcrTextQueryExpression(query) {
-	const { value, matchMode, isCaseSensitive } = query;
-	const phraseQueryExpression = buildRichTextPhraseQueryExpression({
-		value,
+const OCR_STRING_QNAMES = `(xs:QName("String"), fn:QName("http://www.loc.gov/standards/alto/ns-v2#", "string"))`;
+function tokenizeOcrExactValue(value) {
+	const terms = [];
+	for (const term of value.split(/\s+/u)) if (term !== "") terms.push(term);
+	return terms;
+}
+/**
+* Word queries against the OCR layer cannot carry a stemming option: the OCHRE
+* database has unstemmed word searches turned off, and asking a word query for
+* `unstemmed` fails with `XDMP-WORDSEARCH`. Omitting the option altogether
+* resolves the term against the database default instead.
+*/
+function buildOcrWordQueryExpression(parameters) {
+	const { value, isCaseSensitive } = parameters;
+	const options = [
+		isCaseSensitive ? "case-sensitive" : "case-insensitive",
+		"diacritic-insensitive",
+		"punctuation-insensitive",
+		"whitespace-insensitive"
+	];
+	if (hasWildcardCharacters(value)) options.push("wildcarded");
+	return `cts:element-attribute-word-query(${OCR_STRING_QNAMES}, xs:QName("CONTENT"), ${stringLiteral(value)}, (${options.map((option) => stringLiteral(option)).join(", ")}))`;
+}
+function buildOcrValueQueryExpression(parameters) {
+	const { value, isCaseSensitive } = parameters;
+	return `cts:element-attribute-value-query(${OCR_STRING_QNAMES}, xs:QName("CONTENT"), ${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
+		matchMode: "exact",
 		isCaseSensitive
-	});
-	if (matchMode === "exact") return buildNestedElementQuery(["ocrText"], phraseQueryExpression);
+	})})`;
+}
+/**
+* Compile an OCR text search into a query over the `<ocr>` layer of a Resource
+* document
+*
+* Each word node in that layer holds a single OCR word in its `CONTENT`
+* attribute, so `includes` matches every search term as a word inside that
+* attribute anywhere in the layer, and `exact` requires every term to equal a
+* whole `CONTENT` value.
+*
+* The conjunction is only an index narrowing for `exact`. Attribute values
+* carry no word positions, so `cts:near-query` over them silently degenerates
+* into a conjunction and cannot express a phrase at all. Word order and
+* adjacency are instead enforced by {@link registerOcrPhraseHelper} over the
+* documents this narrowing returns.
+*/
+function buildOcrQueryExpression(query) {
+	const { value, matchMode, isCaseSensitive } = query;
+	if (matchMode === "exact") {
+		const terms = tokenizeOcrExactValue(value);
+		if (terms.length === 0) return "cts:false-query()";
+		return buildNestedElementQuery(["ocr"], buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildOcrValueQueryExpression({
+			value: term,
+			isCaseSensitive
+		}))));
+	}
 	const terms = tokenizeIncludesSearchValue({
 		value,
 		isCaseSensitive
 	});
 	if (terms.length === 0) return "cts:false-query()";
-	const tokenizedQueryExpression = buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildCtsWordQueryExpression({
+	return buildNestedElementQuery(["ocr"], buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildOcrWordQueryExpression({
 		value: term,
-		matchMode,
-		isCaseSensitive,
-		queryFamily: "text"
-	})));
-	return buildNestedElementQuery(["ocrText"], shouldUseFullValueFallbackForIncludes({
-		value,
-		isCaseSensitive,
-		terms
-	}) ? buildOrCtsQueryExpressionInternal([phraseQueryExpression, tokenizedQueryExpression]) : tokenizedQueryExpression);
-}
-function getOcrTextConditionKey(query) {
-	return [
-		query.value,
-		query.matchMode,
-		query.isCaseSensitive ? "case-sensitive" : "case-insensitive"
-	].join("|");
-}
-function registerOcrTextCondition(context, query) {
-	const key = getOcrTextConditionKey(query);
-	if (context.ocrTextConditionIndexesByKey.has(key)) return;
-	context.ocrTextConditionIndexesByKey.set(key, context.ocrTextConditions.length);
-	context.ocrTextConditions.push({
-		variableName: `$ocrTextUuids${context.ocrTextConditions.length + 1}`,
-		bindingExpression: `for $ocrTextDocument in cts:search(doc(), ${buildOcrTextQueryExpression(query)})\n    return document-uri($ocrTextDocument)`
-	});
-}
-function collectOcrTextConditions(context, query) {
-	if (isQueryLeaf(query)) {
-		if (query.target === "ocrText") registerOcrTextCondition(context, query);
-		return;
-	}
-	for (const childQuery of getQueryGroupChildren(query)) collectOcrTextConditions(context, childQuery);
-}
-function isOcrTextLeafMatched(context, query, ocrTextValues) {
-	const conditionIndex = context.ocrTextConditionIndexesByKey.get(getOcrTextConditionKey(query));
-	const isMatched = conditionIndex != null && ocrTextValues[conditionIndex] === true;
-	return query.isNegated === true ? !isMatched : isMatched;
+		isCaseSensitive
+	}))));
 }
 /**
-* Enumerate every assignment of "this item is in the OCR text match set" across
-* the compiled conditions, least significant position first
+* Declare the filter that holds an `exact` multi-term search to a run of
+* adjacent OCR words, which no CTS query over the layer can express
 */
-function getOcrTextValueCombinations(count) {
-	return Array.from({ length: 2 ** count }, (_, index) => Array.from({ length: count }, (_, position) => (index >> position & 1) === 1));
+function registerOcrPhraseHelper(context) {
+	const helperName = "local:ocrHasPhrase";
+	if (context.helperNamesByKey.has(helperName)) return helperName;
+	context.helperNamesByKey.set(helperName, helperName);
+	context.helperDeclarations.push(`declare function ${helperName}($resource as node(), $terms as xs:string*, $isCaseSensitive as xs:boolean) as xs:boolean {
+  let $contents :=
+    for $word in $resource//*[lower-case(local-name(.)) = "ocr"]//*[lower-case(local-name(.)) = "string"][@CONTENT]
+    return if ($isCaseSensitive) then string($word/@CONTENT) else lower-case(string($word/@CONTENT))
+  let $needles :=
+    for $term in $terms
+    return if ($isCaseSensitive) then $term else lower-case($term)
+  let $length := count($needles)
+  return
+    some $start in (1 to (count($contents) - $length + 1))
+    satisfies (
+      every $offset in (1 to $length)
+      satisfies $contents[$start + $offset - 1] = $needles[$offset]
+    )
+};`);
+	return helperName;
 }
 /**
-* Resolve a query tree against one OCR text assignment, treating every CTS leaf
-* as unknown. Only a definite `false` is actionable: it means the branch cannot
-* match anything and can be dropped before it costs a `cts:search`.
+* Bind the UUIDs of the Resource documents whose OCR layer matches a query,
+* reusing the binding when the same search is requested more than once
 */
-function evaluateOcrTextBranch(context, query, ocrTextValues) {
-	if (isQueryLeaf(query)) return query.target === "ocrText" ? isOcrTextLeafMatched(context, query, ocrTextValues) : null;
-	const isAndGroup = "and" in query;
-	let result = isAndGroup;
-	for (const childQuery of getQueryGroupChildren(query)) {
-		const childResult = evaluateOcrTextBranch(context, childQuery, ocrTextValues);
-		if (childResult === !isAndGroup) return !isAndGroup;
-		if (childResult == null) result = null;
-	}
-	return result;
-}
-function buildOcrTextItemPredicates(context, ocrTextValues) {
-	return Array.from(context.ocrTextConditions, (condition, index) => ocrTextValues[index] === true ? `[@uuid = ${condition.variableName}]` : `[not(@uuid = ${condition.variableName})]`).join("");
+function registerOcrBinding(context, query) {
+	const key = [
+		query.value,
+		query.matchMode,
+		query.isCaseSensitive ? "case-sensitive" : "case-insensitive"
+	].join("|");
+	const existingName = context.ocrBindingNamesByKey.get(key);
+	if (existingName != null) return existingName;
+	const name = `$ocrItemUuids${context.ocrBindings.length + 1}`;
+	const queryExpression = buildOcrQueryExpression(query);
+	const phraseTerms = query.matchMode === "exact" ? tokenizeOcrExactValue(query.value) : [];
+	context.ocrBindingNamesByKey.set(key, name);
+	const searchExpression = `cts:search(/ochre/resource, ${queryExpression})`;
+	const phraseHelperName = phraseTerms.length > 1 ? registerOcrPhraseHelper(context) : null;
+	context.ocrBindings.push({
+		name,
+		expression: queryExpression === "cts:false-query()" ? "()" : phraseHelperName == null ? `${searchExpression}/@uuid/string()` : `for $ocrResource in ${searchExpression}
+    where ${phraseHelperName}($ocrResource, (${phraseTerms.map((term) => stringLiteral(term)).join(", ")}), ${query.isCaseSensitive ? "true()" : "false()"})
+    return string($ocrResource/@uuid)`
+	});
+	return name;
 }
 function getLeafSearchValue(query) {
 	switch (query.target) {
@@ -631,8 +669,8 @@ function createQueryCompilerContext() {
 		nextHelperSerial: 1,
 		helperNamesByKey: /* @__PURE__ */ new Map(),
 		helperDeclarations: [],
-		ocrTextConditions: [],
-		ocrTextConditionIndexesByKey: /* @__PURE__ */ new Map()
+		ocrBindingNamesByKey: /* @__PURE__ */ new Map(),
+		ocrBindings: []
 	};
 }
 function registerConstantHelper(parameters) {
@@ -833,7 +871,7 @@ function getCompatibleIncludesGroupLeaves(query) {
 	if (!("or" in query) || query.or.length <= 1) return null;
 	const leafQueries = [];
 	for (const childQuery of query.or) {
-		if (!isQueryLeaf(childQuery) || childQuery.target === "ocrText") return null;
+		if (!isQueryLeaf(childQuery) || childQuery.target === "ocr") return null;
 		leafQueries.push(childQuery);
 	}
 	const firstQuery = leafQueries[0];
@@ -894,16 +932,121 @@ function buildIncludesGroupQueryExpression(context, queries) {
 		bodyExpression: buildOrCtsQueryExpressionInternal(exactMemberHelpers.map((helper) => helper.callExpression))
 	}).callExpression, tokenizedQueryExpression]);
 }
-function buildQueryNode(context, query, ocrTextValues) {
+function buildCtsItemsPlan(queryExpression) {
+	return {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: [queryExpression]
+	};
+}
+/**
+* Splice the children of same-kind child plans into their parent, so that a
+* nested group of the same operator does not cost an extra search
+*/
+function flattenItemsPlans(childPlans, kind) {
+	const flattenedPlans = [];
+	for (const childPlan of childPlans) {
+		if (childPlan.kind === kind) {
+			flattenedPlans.push(...childPlan.children);
+			continue;
+		}
+		flattenedPlans.push(childPlan);
+	}
+	return flattenedPlans;
+}
+/**
+* Fold the children of an `and` group into one plan
+*
+* Conjunction is the direction the item path predicates already run in, so
+* every child that is a plain search collapses into a single search, and only
+* the children that resolved to a union stay separate.
+*/
+function buildAndItemsPlan(childPlans) {
+	const mergedPlan = {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: []
+	};
+	const unfoldablePlans = [];
+	for (const childPlan of flattenItemsPlans(childPlans, "intersect")) {
+		if (childPlan.kind !== "search") {
+			unfoldablePlans.push(childPlan);
+			continue;
+		}
+		for (const itemPredicate of childPlan.itemPredicates) if (!mergedPlan.itemPredicates.includes(itemPredicate)) mergedPlan.itemPredicates.push(itemPredicate);
+		mergedPlan.queryExpressions.push(...childPlan.queryExpressions);
+	}
+	if (unfoldablePlans.length === 0) return mergedPlan;
+	const intersectedPlans = mergedPlan.itemPredicates.length === 0 && mergedPlan.queryExpressions.length === 0 ? unfoldablePlans : [mergedPlan, ...unfoldablePlans];
+	return intersectedPlans.length === 1 ? intersectedPlans[0] ?? mergedPlan : {
+		kind: "intersect",
+		children: intersectedPlans
+	};
+}
+/**
+* Fold the children of an `or` group into one plan
+*
+* Item path predicates cannot be disjoined, so a child carrying one becomes its
+* own arm of a node union. Everything else is still a single CTS query.
+*/
+function buildOrItemsPlan(childPlans) {
+	const mergedQueryExpressions = [];
+	const unionedPlans = [];
+	for (const childPlan of flattenItemsPlans(childPlans, "union")) {
+		if (childPlan.kind === "search" && childPlan.itemPredicates.length === 0) {
+			mergedQueryExpressions.push(buildAndCtsQueryExpressionInternal(childPlan.queryExpressions));
+			continue;
+		}
+		unionedPlans.push(childPlan);
+	}
+	if (mergedQueryExpressions.length > 0) unionedPlans.unshift({
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: [buildOrCtsQueryExpressionInternal(mergedQueryExpressions)]
+	});
+	if (unionedPlans.length === 0) return buildCtsItemsPlan("cts:false-query()");
+	return unionedPlans.length === 1 ? unionedPlans[0] ?? buildCtsItemsPlan("cts:false-query()") : {
+		kind: "union",
+		children: unionedPlans
+	};
+}
+function buildItemsPlan(context, query) {
 	if (isQueryLeaf(query)) {
-		if (query.target === "ocrText") return isOcrTextLeafMatched(context, query, ocrTextValues) ? "cts:true-query()" : "cts:false-query()";
+		if (query.target === "ocr") {
+			const bindingName = registerOcrBinding(context, query);
+			return {
+				kind: "search",
+				itemPredicates: [query.isNegated === true ? `[not(@uuid = ${bindingName})]` : `[@uuid = ${bindingName}]`],
+				queryExpressions: []
+			};
+		}
 		const queryExpression = buildLeafQueryExpression(context, query);
-		return query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression;
+		return buildCtsItemsPlan(query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression);
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
-	if (optimizedIncludesGroupQueries != null) return buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries);
-	const childQueryExpressions = Array.from(getQueryGroupChildren(query), (childQuery) => buildQueryNode(context, childQuery, ocrTextValues));
-	return (getQueryGroupOperator(query) === "and" ? buildAndCtsQueryExpressionInternal : buildOrCtsQueryExpressionInternal)(childQueryExpressions);
+	if (optimizedIncludesGroupQueries != null) return buildCtsItemsPlan(buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries));
+	const childPlans = Array.from(getQueryGroupChildren(query), (childQuery) => buildItemsPlan(context, childQuery));
+	return getQueryGroupOperator(query) === "and" ? buildAndItemsPlan(childPlans) : buildOrItemsPlan(childPlans);
+}
+function collectItemsSearchPlans(plan, searchPlans) {
+	if (plan.kind === "search") {
+		searchPlans.push(plan);
+		return;
+	}
+	for (const childPlan of plan.children) collectItemsSearchPlans(childPlan, searchPlans);
+}
+function buildItemsPlanExpression(parameters) {
+	const { plan, baseItemsExpression, queryNamesByPlan } = parameters;
+	if (plan.kind === "search") {
+		const itemsExpression = `${baseItemsExpression}${plan.itemPredicates.join("")}`;
+		const queryName = queryNamesByPlan.get(plan);
+		return queryName == null ? itemsExpression : `cts:search(${itemsExpression}, ${queryName})`;
+	}
+	return `(${Array.from(plan.children, (childPlan) => buildItemsPlanExpression({
+		plan: childPlan,
+		baseItemsExpression,
+		queryNamesByPlan
+	})).join(plan.kind === "union" ? " | " : " intersect ")})`;
 }
 function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, belongsToCollectionPropertyVariableUuid) {
 	if (belongsToCollectionScopeUuids.length === 0) return null;
@@ -917,46 +1060,58 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 	});
 }
 /**
-* Compile a query tree into the CTS searches that resolve it
+* Compile a query tree into the XQuery `let` clauses that bind `$items` to the
+* matching Set items
+*
+* Most queries compile to a single `cts:search` over the Set item projections.
+* An `ocr` leaf cannot: the projections drop the `<ocr>` layer, so it resolves
+* to a search over the Resource documents whose matching UUIDs are joined back
+* in as an item path predicate. Path predicates only ever AND, so an `ocr` leaf
+* that sits under an `or` becomes its own arm of a node union instead, and one
+* that sits under an `and` alongside a union becomes an intersection.
 *
-* OCR text is not carried by Set item projections, so an `ocrText` leaf cannot
-* be a CTS term: it resolves to a document join whose UUID list can only be
-* applied as an item path predicate, and path predicates only ever AND. To keep
-* `ocrText` composable with `or` anyway, the tree is split on each distinct OCR
-* text condition, one branch per assignment of "this item is in that match
-* set". Every branch is a plain CTS search, and their union is the result.
-* Branches that the assignment already rules out are dropped, so a query whose
-* OCR text leaves are all conjunctive still compiles to a single search.
+* The searchable path has to stay inline in `cts:search`: binding it to a
+* variable first makes every query XDMP-UNSEARCHABLE.
+* @param parameters - The parameters for the compilation
+* @param parameters.queries - Recursive query tree to compile, if any
+* @param parameters.baseItemsExpression - The inline XQuery path selecting the items to search
+* @param parameters.scopeQueryExpression - An optional CTS query ANDed into every compiled search
+* @returns The prolog declaring the query helpers, and the `let` clauses binding `$items`
 */
 function buildQueryPlan(parameters) {
-	const { queries } = parameters;
-	if (queries == null) return {
-		prolog: "",
-		ocrTextBindings: [],
-		branches: [{
-			itemPredicates: "",
-			queryExpression: null
-		}]
-	};
+	const { queries, baseItemsExpression, scopeQueryExpression } = parameters;
 	const context = createQueryCompilerContext();
-	collectOcrTextConditions(context, queries);
-	if (context.ocrTextConditions.length > MAX_OCR_TEXT_CONDITIONS) throw new Error(`A query cannot contain more than ${MAX_OCR_TEXT_CONDITIONS} distinct OCR text searches`, { cause: context.ocrTextConditions.length });
-	const branches = [];
-	for (const ocrTextValues of getOcrTextValueCombinations(context.ocrTextConditions.length)) {
-		if (evaluateOcrTextBranch(context, queries, ocrTextValues) === false) continue;
-		branches.push({
-			itemPredicates: buildOcrTextItemPredicates(context, ocrTextValues),
-			queryExpression: buildQueryNode(context, queries, ocrTextValues)
+	const plan = queries == null ? {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: []
+	} : buildItemsPlan(context, queries);
+	const searchPlans = [];
+	collectItemsSearchPlans(plan, searchPlans);
+	const boundSearchPlans = [];
+	for (const searchPlan of searchPlans) {
+		const queryExpression = buildAndCtsQueryExpression([...searchPlan.queryExpressions, ...scopeQueryExpression == null ? [] : [scopeQueryExpression]]);
+		if (queryExpression != null) boundSearchPlans.push({
+			plan: searchPlan,
+			queryExpression
 		});
 	}
+	const queryNamesByPlan = /* @__PURE__ */ new Map();
+	const letClauses = Array.from(context.ocrBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
+	for (const [index, boundSearchPlan] of boundSearchPlans.entries()) {
+		const queryName = boundSearchPlans.length === 1 ? "$query" : `$query${index + 1}`;
+		queryNamesByPlan.set(boundSearchPlan.plan, queryName);
+		letClauses.push(`let ${queryName} := ${boundSearchPlan.queryExpression}`);
+	}
+	letClauses.push(`let $items := ${buildItemsPlanExpression({
+		plan,
+		baseItemsExpression,
+		queryNamesByPlan
+	})}`);
 	return {
 		prolog: context.helperDeclarations.join("\n\n"),
-		ocrTextBindings: Array.from(context.ocrTextConditions, (condition) => ({
-			name: condition.variableName,
-			expression: condition.bindingExpression
-		})),
-		branches
+		itemsClause: letClauses.join("\n  ")
 	};
 }
 //#endregion
-export { buildAndCtsQueryExpression, buildBelongsToCollectionQueryExpression, buildQueryPlan };
+export { buildBelongsToCollectionQueryExpression, buildQueryPlan };

package/dist/schemas.mjs

@@ -142,7 +142,7 @@ const setQueryLeafSchema = v.union([
 		...standardQueryFields
 	}),
 	v.strictObject({
-		target: v.literal("ocrText"),
+		target: v.literal("ocr"),
 		value: v.string(),
 		matchMode: standardQueryFields.matchMode,
 		isCaseSensitive: standardQueryFields.isCaseSensitive,

package/dist/types/index.d.mts

@@ -266,11 +266,15 @@ type ImageMap = {
  *  Positioned OCR string in OCHRE
  *
  *  OCHRE gives no guarantee about the node hierarchy inside a Resource's
- *  `<ocr>` layer, so only `<string>` nodes are parsed, at whatever depth they
- *  occur. `x` and `y` come from `HPOS` and `VPOS` and locate the top-left
- *  corner of the string's box, while `vertices` is its full bounding polygon,
- *  which is not necessarily rectangular. Every geometry attribute is optional
- *  in the source, so each one is null when absent or unparseable.
+ *  `<ocr>` layer, so only its word nodes are parsed, at whatever depth they
+ *  occur. A word node is any element named `string` in any casing and any
+ *  namespace, and its text is read from the `CONTENT` attribute.
+ *
+ *  `x` and `y` come from `HPOS` and `VPOS` and locate the top-left corner of
+ *  the word's box, while `vertices` comes from `VERTICES` and is its full
+ *  bounding polygon, which is not necessarily rectangular. Every geometry
+ *  attribute is optional in the source, so each one is null when absent or
+ *  unparseable, and `vertices` is then empty.
  *
  *  `resourceUuid` is the Resource that owns the OCR layer, which differs from
  *  the requested item when the OCR lives on a child Resource.
@@ -815,12 +819,13 @@ type SetItemsSort = {
 /**
  * Represents a leaf query for Set items
  *
- * The `ocrText` target matches the OCR text layer of Resource items. Because
- * Set item projections do not carry `<ocrText>`, it is resolved by a document
- * join rather than a CTS term, so it composes with `and`, `or`, and `isNegated`
- * at the cost of one extra search branch per distinct OCR text value in a
- * disjunction. OCR text carries no language, so `ocrText` leaves take no
- * `language`.
+ * The `ocr` target matches the OCR text layer of Resource items. Set item
+ * projections do not carry `<ocr>`, so it is resolved by a document join rather
+ * than by a CTS term, and it composes with `and`, `or`, and `isNegated` at the
+ * cost of one extra search per distinct OCR value. Each `<string>` in that
+ * layer holds a single OCR word, so `includes` matches every search term as its
+ * own word and `exact` matches the terms as an adjacent run of whole words. OCR
+ * text carries no language, so `ocr` leaves take no `language`.
  */
 type QueryLeaf = {
   target: "property";
@@ -888,7 +893,7 @@ type QueryLeaf = {
   language: string;
   isNegated?: boolean;
 } | {
-  target: "ocrText";
+  target: "ocr";
   value: string;
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.73",
+  "version": "1.0.75",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -51,11 +51,12 @@
     "valibot": "^1.4.2"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^9.2.0",
+    "@antfu/eslint-config": "^9.3.0",
     "@types/node": "^24.13.3",
     "bumpp": "^12.2.0",
     "eslint": "^10.8.0",
-    "knip": "^6.31.0",
+    "eslint-plugin-erasable-syntax-only": "^0.4.2",
+    "knip": "^6.32.0",
     "oxfmt": "^0.62.0",
     "tsdown": "^0.22.14",
     "typescript": "^6.0.3",