ochre-sdk 1.1.3 → 1.1.4

package/dist/fetchers/gallery.mjs

@@ -4,14 +4,14 @@ import { gallerySchema } from "../schemas.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseGallery } from "../parsers/index.mjs";
 import { XMLGalleryData } from "../xml/schemas.mjs";
-import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/gallery.ts
 function buildXQuery(parameters) {
 	const { uuid, filter, page, perPage } = parameters;
 	const start = (page - 1) * perPage + 1;
 	const filterLiteral = stringLiteral(filter?.trim() ?? "");
-	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>{
+	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>${OCHRE_RESPONSE_PADDING}{
   for $q in doc()/ochre[@uuid=${stringLiteral(uuid)}]
   let $filter := ${filterLiteral}
   let $resources := $q//items/resource

package/dist/fetchers/item-children.mjs

@@ -5,7 +5,7 @@ import { uuidSchema } from "../schemas.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseLinkedItems } from "../parsers/index.mjs";
 import { XMLItemLinksData } from "../xml/schemas.mjs";
-import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item-children.ts
 function buildXQuery(uuid, category) {
@@ -49,7 +49,7 @@ let $children :=
   else if ($category = "resource") then $item/resource
   else ()
 return
-  <ochre>
+  <ochre>${OCHRE_RESPONSE_PADDING}
     <items>{${omitSupplemental("$children")}}</items>
   </ochre>`
 	});

package/dist/fetchers/item-links.mjs

@@ -5,7 +5,7 @@ import { uuidSchema } from "../schemas.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseLinkedItems } from "../parsers/index.mjs";
 import { XMLItemLinksData } from "../xml/schemas.mjs";
-import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item-links.ts
 /**
@@ -24,7 +24,7 @@ function buildXQuery(uuid) {
 		return `if (${ITEM_CATEGORY_ALIASES[category].map((alias) => `$category = ${stringLiteral(alias)}`).join(" or ")}) then fn:collection("ochre/${category}")/ochre/${category}[@uuid = $uuid]`;
 	}).join("\n        else ")}
         else ()`;
-	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>{let $item-uuid := ${stringLiteral(uuid)}
+	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>${OCHRE_RESPONSE_PADDING}{let $item-uuid := ${stringLiteral(uuid)}
 
 let $source-items := (
 ${OCHRE_COLLECTION_CATEGORIES.map((category) => `  fn:collection("ochre/${category}")/ochre[@uuid = $item-uuid]/${category}`).join(",\n")}

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

@@ -1,7 +1,7 @@
 import { getErrorOutput } from "../errors.mjs";
 import { requestOchre } from "./request.mjs";
 import { itemOcrDataParametersSchema } from "../schemas.mjs";
-import { stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, stringLiteral } from "../xquery.mjs";
 import { buildOcrWordPath } from "../ocr.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item-ocr-data.ts
@@ -62,10 +62,8 @@ function parseOcrStringVertices(value) {
 * 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
-* element children down to a bare `<ochre/>`, which would drop the `found`
-* flag and make "no such item" indistinguishable from "no matches".
+* The matches are wrapped in an `<ocrStrings>` element carrying a `found`
+* flag, which tells "no such item" apart 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
@@ -95,7 +93,7 @@ let $ocrStrings :=
     height="{string($string/@HEIGHT)}"
     vertices="{string($string/@VERTICES)}"/>
 
-return <ochre><ocrStrings found="{exists($ochre)}">{$ocrStrings}</ocrStrings></ochre>`;
+return <ochre>${OCHRE_RESPONSE_PADDING}<ocrStrings found="{exists($ochre)}">{$ocrStrings}</ocrStrings></ochre>`;
 }
 /**
 * Fetches and parses the OCR strings of an OCHRE item that match a search value

package/dist/fetchers/item.mjs

@@ -5,7 +5,7 @@ import { uuidSchema } from "../schemas.mjs";
 import { parseRequestedLanguages } from "../parsers/languages.mjs";
 import { parseItem } from "../parsers/index.mjs";
 import { XMLData } from "../xml/schemas.mjs";
-import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import { parseWebpageView } from "../parsers/website/index.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item.ts
@@ -48,7 +48,7 @@ ${ITEM_CATEGORIES_WITH_EMBEDDED_ITEMS.map((category) => `  $ochre/${category}`).
 	}
 	return compileOchreQuery({ body: ({ omitSupplemental }) => `${letClauses.join("\n")}
 return
-  if (empty($ochre)) then ()
+  if (empty($ochre)) then <ochre>${OCHRE_RESPONSE_PADDING}</ochre>
   else element ochre {
     $ochre/@*,
     ${omitSupplemental(itemNodesExpression)}

package/dist/fetchers/request.d.mts

@@ -21,7 +21,7 @@ export type OchreRequestOptions = {
  * @param parameters.label - What is being decoded, used in failure messages
  * @param parameters.checkRawData - Guard run against the parsed XML before validation
  * @returns The validated response, with XML source metadata restored
- * @throws When the guard rejects or validation fails
+ * @throws When the query failed on the server, the guard rejects, or validation fails
  * @internal
  */
 export declare function decodeOchreResponse<TOutput>(parameters: {

package/dist/fetchers/request.mjs

@@ -27,11 +27,12 @@ function resolveSignal(options) {
 * @param parameters.label - What is being decoded, used in failure messages
 * @param parameters.checkRawData - Guard run against the parsed XML before validation
 * @returns The validated response, with XML source metadata restored
-* @throws When the guard rejects or validation fails
+* @throws When the query failed on the server, the guard rejects, or validation fails
 * @internal
 */
 function decodeOchreResponse(parameters) {
 	const { xml, schema, label, checkRawData } = parameters;
+	if (xml.trim() === "<result><ochre/></result>") throw new Error(`Failed to fetch ${label}: the OCHRE API could not run the query`);
 	const data = xmlParser.parse(xml);
 	checkRawData?.(data);
 	const { success, issues, output } = v.safeParse(schema, data);

package/dist/fetchers/website-metadata.mjs

@@ -4,7 +4,7 @@ import { parseStringLike } from "../parsers/helpers.mjs";
 import { parseMetadataLanguages, parseRequestedLanguages, resolveLanguages } from "../parsers/languages.mjs";
 import { parseIdentification, parseSimplifiedProperties } from "../parsers/index.mjs";
 import { XMLWebsiteData } from "../xml/schemas.mjs";
-import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import { websitePresentationReader } from "../parsers/website/reader.mjs";
 import { WEBSITE_WALK_DECLARATIONS } from "../parsers/website/walk.mjs";
 //#region src/fetchers/website-metadata.ts
@@ -118,6 +118,7 @@ return
     $website/@belongsTo,
     $website/@publicationDateTime,
     $website/@languages,
+    ${OCHRE_RESPONSE_PADDING},
     ${omitSupplemental(`(
       $website/metadata,
       local:metadata-tree($website/tree[1], $target-slug, "")

package/dist/fetchers/website.mjs

@@ -2,7 +2,7 @@ import { getErrorOutput } from "../errors.mjs";
 import { isOchreJsonAccepted, requestOchre } from "./request.mjs";
 import { parseLanguages } from "../parsers/languages.mjs";
 import { XMLWebsiteData } from "../xml/schemas.mjs";
-import { compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
 import { parseWebsite } from "../parsers/website/index.mjs";
 //#region src/fetchers/website.ts
 async function areWebsiteCredentialsValid(uuid, credentials, options) {
@@ -26,8 +26,10 @@ async function areWebsiteCredentialsValid(uuid, credentials, options) {
 * @returns An XQuery string
 */
 function buildXQuery(abbreviation) {
-	return compileOchreQuery({ body: ({ omitSupplemental }) => `for $ochre in collection("ochre/tree")/ochre[tree/identification/abbreviation/content/string = ${stringLiteral(abbreviation)}]
-return element ochre { $ochre/@*, ${omitSupplemental("$ochre/node()")} }` });
+	return compileOchreQuery({ body: ({ omitSupplemental }) => `let $ochre := collection("ochre/tree")/ochre[tree/identification/abbreviation/content/string = ${stringLiteral(abbreviation)}][1]
+return
+  if (empty($ochre)) then <ochre>${OCHRE_RESPONSE_PADDING}</ochre>
+  else element ochre { $ochre/@*, ${omitSupplemental("$ochre/node()")} }` });
 }
 /**
 * Fetches and parses a website configuration from the OCHRE API.

package/dist/query.mjs

@@ -1,5 +1,5 @@
 import { BELONGS_TO_COLLECTION_UUID } from "./constants.mjs";
-import { compileOchreQuery, stringLiteral } from "./xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "./xquery.mjs";
 import { OCR_WORD_CONTENT_ATTRIBUTE, OCR_WORD_QNAMES, buildOcrWordPath } from "./ocr.mjs";
 //#region src/query.ts
 const CTS_INCLUDES_STOP_WORDS = /* @__PURE__ */ new Set([
@@ -517,13 +517,15 @@ function buildOcrValueQueryExpression(parameters) {
 	})})`;
 }
 /**
-* Compile an OCR text search into a query over the `<ocr>` layer of a Resource
-* document
+* Compile an OCR text search into a query over the `<ocr>` layers of a
+* Resource document
 *
-* Each word node in that layer holds a single OCR word in its `CONTENT`
+* Each word node in a 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.
+* attribute, and `exact` requires every term to equal a whole `CONTENT` value.
+* A Resource carries one layer per page, so each term is its own element query
+* and the terms may fall on different pages, which is also all the indexes can
+* tell apart.
 *
 * The conjunction is only an index narrowing for `exact`. Attribute values
 * carry no word positions, so `cts:near-query` over them silently degenerates
@@ -533,20 +535,13 @@ function buildOcrValueQueryExpression(parameters) {
 */
 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: searchValue(term),
-			isCaseSensitive
-		}))));
-	}
-	const terms = tokenizeIncludesSearchValue({
+	const terms = matchMode === "exact" ? tokenizeOcrExactValue(value) : tokenizeIncludesSearchValue({
 		value,
 		isCaseSensitive
 	});
 	if (terms.length === 0) return "cts:false-query()";
-	return buildNestedElementQuery(["ocr"], buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildOcrWordQueryExpression({
+	const buildTermQueryExpression = matchMode === "exact" ? buildOcrValueQueryExpression : buildOcrWordQueryExpression;
+	return buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildNestedElementQuery(["ocr"], buildTermQueryExpression({
 		value: searchValue(term),
 		isCaseSensitive
 	}))));
@@ -592,12 +587,13 @@ function registerOcrBinding(context, query) {
 	const queryExpression = buildOcrQueryExpression(query);
 	const phraseTerms = query.matchMode === "exact" ? tokenizeOcrExactValue(query.value) : [];
 	context.ocrBindingNamesByKey.set(key, name);
-	const searchExpression = `cts:search(/ochre/resource, ${buildAndCtsQueryExpressionInternal([queryExpression, `cts:document-query(${context.baseItemsExpression}/@uuid/string())`])})`;
+	const scopedQueryExpression = buildAndCtsQueryExpressionInternal([queryExpression, `cts:document-query(${context.baseItemsExpression}/@uuid/string())`]);
 	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}
+		expression: queryExpression === "cts:false-query()" ? "()" : phraseHelperName != null ? `for $ocrResource in cts:search(/ochre/resource, ${scopedQueryExpression}, "unfiltered")
     where ${phraseHelperName}($ocrResource, (${phraseTerms.map((term) => stringLiteral(term)).join(", ")}), ${query.isCaseSensitive ? "true()" : "false()"})
+    return string($ocrResource/@uuid)` : query.matchMode === "includes" && !query.isCaseSensitive ? `cts:uris((), (), ${scopedQueryExpression})` : `for $ocrResource in cts:search(/ochre/resource, ${scopedQueryExpression})
     return string($ocrResource/@uuid)`
 	});
 	return name;
@@ -1226,7 +1222,7 @@ function compileContainerItemsQuery(parameters) {
 			`declare variable ${scopeVariable} := (${Array.from(scopeUuids, (uuid) => stringLiteral(uuid)).join(", ")});`,
 			...plan.prolog === "" ? [] : [plan.prolog]
 		],
-		body: (context) => `<ochre>{
+		body: (context) => `<ochre>${OCHRE_RESPONSE_PADDING}{
 ${plan.itemsClause}
 ${body({
 			...context,

package/dist/xquery.d.mts

@@ -6,6 +6,17 @@
  * @internal
  */
 export declare function stringLiteral(value: string): string;
+/**
+ * A comment every query puts inside the `<ochre>` element it returns
+ *
+ * The API answers a failed query with a bare `<result><ochre/></result>`, and
+ * sends the same response whenever the returned `<ochre>` element holds fewer
+ * than 25 characters. Padding keeps an empty or not-found result above that
+ * cutoff, so the bare response only ever means failure. The XML parser drops
+ * comments, so no schema sees it.
+ * @internal
+ */
+export declare const OCHRE_RESPONSE_PADDING = "<!--ochre-sdk: keeps an empty result distinct from a failed query-->";
 /**
  * What a query body can ask the surrounding document for
  *

package/dist/xquery.mjs

@@ -9,6 +9,17 @@ function stringLiteral(value) {
 	return `"${value.replaceAll("\"", "\"\"")}"`;
 }
 /**
+* A comment every query puts inside the `<ochre>` element it returns
+*
+* The API answers a failed query with a bare `<result><ochre/></result>`, and
+* sends the same response whenever the returned `<ochre>` element holds fewer
+* than 25 characters. Padding keeps an empty or not-found result above that
+* cutoff, so the bare response only ever means failure. The XML parser drops
+* comments, so no schema sees it.
+* @internal
+*/
+const OCHRE_RESPONSE_PADDING = "<!--ochre-sdk: keeps an empty result distinct from a failed query-->";
+/**
 * XQuery prolog declaring `local:omit-supplemental`, which drops every element
 * carrying `supplemental="true"` from a node sequence, at any depth.
 *
@@ -63,4 +74,4 @@ ${body({
 	})}`;
 }
 //#endregion
-export { compileOchreQuery, stringLiteral };
+export { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -45,23 +45,23 @@
     "dist"
   ],
   "dependencies": {
-    "fast-equals": "^6.0.3",
+    "fast-equals": "^6.0.4",
     "fast-xml-parser": "^5.11.1",
     "valibot": "^1.5.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.5.1",
-    "@types/node": "^24.13.4",
+    "@types/node": "^24.13.6",
     "bumpp": "^12.3.0",
-    "eslint": "^10.10.0",
-    "eslint-plugin-erasable-syntax-only": "^0.7.1",
+    "eslint": "^10.11.0",
+    "eslint-plugin-erasable-syntax-only": "^0.7.2",
     "eslint-plugin-slop": "^0.1.3",
-    "eslint-plugin-sonarjs": "^4.2.0",
-    "knip": "^6.35.1",
-    "oxfmt": "^0.67.0",
+    "eslint-plugin-sonarjs": "^4.2.1",
+    "knip": "^6.38.0",
+    "oxfmt": "^0.70.0",
     "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "dev": "tsdown src/index.ts --watch",