ochre-sdk 1.0.74 → 1.0.75

package/README.md

@@ -145,13 +145,13 @@ const queries: Query = {
 };
 ```
 
-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.
+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";
@@ -165,7 +165,7 @@ 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. Requesting an item that does not exist is an error; an item with no OCR layer, or no matches, returns an empty array.
 

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/query.mjs

@@ -472,16 +472,17 @@ function buildItemStringQueryExpression(parameters) {
 		language
 	})]);
 }
-function tokenizeOcrPhraseValue(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 an element word
-* query for `unstemmed` fails with `XDMP-WORDSEARCH`. Omitting the option
-* altogether resolves the term against the database default instead.
+* 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;
@@ -492,30 +493,39 @@ function buildOcrWordQueryExpression(parameters) {
 		"whitespace-insensitive"
 	];
 	if (hasWildcardCharacters(value)) options.push("wildcarded");
-	return `cts:element-word-query(xs:QName("string"), ${stringLiteral(value)}, (${options.map((option) => stringLiteral(option)).join(", ")}))`;
+	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
+	})})`;
 }
 /**
 * Compile an OCR text search into a query over the `<ocr>` layer of a Resource
 * document
 *
-* 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, and `exact`
-* matches the terms as a run of adjacent whole string values. A phrase cannot
-* be a word query here: word positions do not carry across the `<string>`
-* boundaries, which makes `cts:near-query` the only phrase mechanism, and its
-* distance is a total span rather than a pairwise gap.
+* 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 = tokenizeOcrPhraseValue(value);
+		const terms = tokenizeOcrExactValue(value);
 		if (terms.length === 0) return "cts:false-query()";
-		const termQueryExpressions = Array.from(terms, (term) => buildCtsElementValueQueryExpression({
-			elementName: "string",
+		return buildNestedElementQuery(["ocr"], buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildOcrValueQueryExpression({
 			value: term,
 			isCaseSensitive
-		}));
-		return buildNestedElementQuery(["ocr"], termQueryExpressions.length === 1 ? termQueryExpressions[0] ?? "cts:false-query()" : `cts:near-query((${termQueryExpressions.join(", ")}), ${termQueryExpressions.length - 1}, ("ordered"))`);
+		}))));
 	}
 	const terms = tokenizeIncludesSearchValue({
 		value,
@@ -528,6 +538,31 @@ function buildOcrQueryExpression(query) {
 	}))));
 }
 /**
+* 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 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;
+}
+/**
 * 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
 */
@@ -541,10 +576,15 @@ function registerOcrBinding(context, query) {
 	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()" ? "()" : `cts:search(/ochre/resource, ${queryExpression})/@uuid/string()`
+		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;
 }

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.74",
+  "version": "1.0.75",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",