ochre-sdk 1.3.2 → 1.3.3

package/dist/fetchers/container-items.mjs

@@ -2,7 +2,7 @@ import { requestOchre } from "./request.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
 import { parseSetItems } from "../parsers/index.mjs";
 import { XMLSetItemsData } from "../xml/schemas.mjs";
-import { stringLiteral } from "../xquery.mjs";
+import { getContentLanguage, stringLiteral } from "../xquery.mjs";
 import { compileContainerItemsQuery } from "../query.mjs";
 //#region src/fetchers/container-items.ts
 function hasArray(items) {
@@ -149,6 +149,7 @@ async function fetchContainerItems(parameters) {
 			scopeUuids,
 			belongsToCollectionScopeUuids,
 			queries,
+			contentLanguage: getContentLanguage(options),
 			body: ({ items, omitSupplemental }) => `  let $totalCount := count(${items})
   ${buildOrderedItemsClause(sort)}
   let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})

package/dist/fetchers/gallery.mjs

@@ -4,14 +4,16 @@ 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 { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/gallery.ts
 function buildXQuery(parameters) {
-	const { uuid, filter, page, perPage } = parameters;
+	const { uuid, filter, page, perPage, contentLanguage } = parameters;
 	const start = (page - 1) * perPage + 1;
 	const filterLiteral = stringLiteral(filter?.trim() ?? "");
-	return compileOchreQuery({ body: ({ omitSupplemental }) => `<ochre>${OCHRE_RESPONSE_PADDING}{
+	return compileOchreQuery({
+		contentLanguage,
+		body: ({ omitSupplemental }) => `<ochre>${OCHRE_RESPONSE_PADDING}{
   for $q in doc()/ochre[@uuid=${stringLiteral(uuid)}]
   let $filter := ${filterLiteral}
   let $resources := $q//items/resource
@@ -27,7 +29,8 @@ function buildXQuery(parameters) {
       subsequence($filtered, ${start}, ${perPage})
     )`)}
   }</gallery>
-}</ochre>` });
+}</ochre>`
+	});
 }
 async function fetchGallery(parameters, options) {
 	try {
@@ -38,7 +41,8 @@ async function fetchGallery(parameters, options) {
 				uuid,
 				filter,
 				page,
-				perPage
+				perPage,
+				contentLanguage: getContentLanguage(options)
 			}),
 			schema: XMLGalleryData,
 			label: "OCHRE gallery",

package/dist/fetchers/item-children.mjs

@@ -5,13 +5,14 @@ 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 { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item-children.ts
-function buildXQuery(uuid, category) {
+function buildXQuery(uuid, category, contentLanguage) {
 	const categories = category == null ? OCHRE_COLLECTION_CATEGORIES : typeof category === "string" ? [category] : category;
 	const collectionQueries = Array.from(categories, (possibleCategory) => `cts:search(fn:collection("ochre/${possibleCategory}")/ochre, $uuid-query)`);
 	return compileOchreQuery({
+		contentLanguage,
 		declarations: [`declare function local:item-children($nodes as node()*) as node()* {
   for $node in $nodes
   return
@@ -59,7 +60,7 @@ async function fetchItemChildren(uuid, options) {
 		const parsedUuid = v.parse(uuidSchema, uuid);
 		const requestedLanguages = parseRequestedLanguages(options?.languages);
 		const output = await requestOchre({
-			xquery: buildXQuery(parsedUuid, options?.category),
+			xquery: buildXQuery(parsedUuid, options?.category, getContentLanguage(options)),
 			schema: XMLItemLinksData,
 			label: "OCHRE item children",
 			options

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 { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item-links.ts
 /**
@@ -14,7 +14,7 @@ import * as v from "valibot";
 * @param uuid - The UUID of the OCHRE item whose links should be fetched
 * @returns An XQuery string
 */
-function buildXQuery(uuid) {
+function buildXQuery(uuid, contentLanguage) {
 	const linkedItems = `for $link at $position in $link-nodes
       let $uuid := $link/@uuid/string()
       let $category := name($link)
@@ -24,7 +24,9 @@ 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>${OCHRE_RESPONSE_PADDING}{let $item-uuid := ${stringLiteral(uuid)}
+	return compileOchreQuery({
+		contentLanguage,
+		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")}
@@ -39,14 +41,15 @@ let $link-nodes := (
 return
     <items>{
       ${omitSupplemental(linkedItems)}
-    }</items>}</ochre>` });
+    }</items>}</ochre>`
+	});
 }
 async function fetchItemLinks(uuid, options) {
 	try {
 		const parsedUuid = v.parse(uuidSchema, uuid);
 		const requestedLanguages = parseRequestedLanguages(options?.languages);
 		const output = await requestOchre({
-			xquery: buildXQuery(parsedUuid),
+			xquery: buildXQuery(parsedUuid, getContentLanguage(options)),
 			schema: XMLItemLinksData,
 			label: "OCHRE item links",
 			options

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 { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral } from "../xquery.mjs";
+import { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral } from "../xquery.mjs";
 import { parseWebpageView } from "../parsers/website/index.mjs";
 import * as v from "valibot";
 //#region src/fetchers/item.ts
@@ -28,10 +28,11 @@ function assertItemCategoryAllowed(category, containedItemCategory) {
 * @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
+* @param parameters.contentLanguage - Keep only this language of every multilingual field
 * @returns An XQuery string
 */
 function buildXQuery(parameters) {
-	const { uuid, shouldOmitEmbeddedItems } = parameters;
+	const { uuid, shouldOmitEmbeddedItems, contentLanguage } = parameters;
 	const letClauses = [`let $ochre := doc(${stringLiteral(uuid)})/ochre`];
 	let itemNodesExpression = "$ochre/node()";
 	if (shouldOmitEmbeddedItems) {
@@ -46,13 +47,16 @@ ${ITEM_CATEGORIES_WITH_EMBEDDED_ITEMS.map((category) => `  $ochre/${category}`).
         else $node
     )`;
 	}
-	return compileOchreQuery({ body: ({ omitSupplemental }) => `${letClauses.join("\n")}
+	return compileOchreQuery({
+		contentLanguage,
+		body: ({ omitSupplemental }) => `${letClauses.join("\n")}
 return
   if (empty($ochre)) then <ochre>${OCHRE_RESPONSE_PADDING}</ochre>
   else element ochre {
     $ochre/@*,
     ${omitSupplemental(itemNodesExpression)}
-  }` });
+  }`
+	});
 }
 function omitEmbeddedItems(item) {
 	const { items: _items, ...itemWithoutEmbeddedItems } = item;
@@ -67,7 +71,8 @@ async function fetchItem(uuid, options) {
 		const output = await requestOchre({
 			xquery: buildXQuery({
 				uuid: parsedUuid,
-				shouldOmitEmbeddedItems
+				shouldOmitEmbeddedItems,
+				contentLanguage: getContentLanguage(options)
 			}),
 			schema: XMLData,
 			label: "OCHRE item",

package/dist/fetchers/set/item-locations.mjs

@@ -6,7 +6,7 @@ import { parseRequiredContentLike } from "../../parsers/helpers.mjs";
 import { parseRequestedLanguages, resolveContentLanguages } from "../../parsers/languages.mjs";
 import { parseCoordinates, parseIdentification } from "../../parsers/index.mjs";
 import { XMLSetItemLocationsData } from "../../xml/schemas.mjs";
-import { stringLiteral } from "../../xquery.mjs";
+import { getContentLanguage, stringLiteral } from "../../xquery.mjs";
 import { compileContainerItemsQuery } from "../../query.mjs";
 import * as v from "valibot";
 //#region src/fetchers/set/item-locations.ts
@@ -19,6 +19,7 @@ async function fetchSetItemLocations(parameters, options) {
 				scopeUuids: setScopeUuids,
 				belongsToCollectionScopeUuids,
 				queries,
+				contentLanguage: getContentLanguage(options),
 				body: ({ items }) => `  let $propertyVariableUuids := (${Array.from(propertyVariableUuids, (uuid) => stringLiteral(uuid)).join(", ")})
 
   return <items totalCount="{count(${items})}">{

package/dist/parsers/helpers.d.mts

@@ -5,6 +5,17 @@ import { XMLContent, XMLString } from "../xml/types.mjs";
 export type FetchFunction = (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
 export type FetchBaseOptions<TLanguages extends ReadonlyArray<string> | undefined = undefined> = {
   languages?: TLanguages;
+  /**
+   * Fetch only this language of every multilingual field, instead of every
+   * language OCHRE holds. A field without it keeps its `fallbackLanguage`
+   * content, else its content in any language; aliases are always kept.
+   */
+  language?: string;
+  /**
+   * The language shown for fields that have no `language` content, typically
+   * the website's default language (defaults to `"eng"`)
+   */
+  fallbackLanguage?: string;
   fetch?: FetchFunction;
   signal?: AbortSignal;
   timeoutMilliseconds?: number;

package/dist/query.d.mts

@@ -1,5 +1,5 @@
 import { PropertyRelation, Query } from "./types/index.mjs";
-import { OchreQueryContext } from "./xquery.mjs";
+import { OchreContentLanguage, OchreQueryContext } from "./xquery.mjs";
 //#region src/query.d.ts
 export declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: ReadonlyArray<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
 /**
@@ -75,6 +75,7 @@ export type ItemsContainer = keyof typeof ITEMS_CONTAINERS;
  * @param parameters.queries - The query tree to compile, or null to match every item
  * @param parameters.declarations - Extra prolog declarations, placed before the compiled prolog
  * @param parameters.body - Builds the body from the name of the variable holding the items
+ * @param parameters.contentLanguage - Keep only this language of every multilingual field in the result
  * @returns A complete XQuery document
  * @internal
  */
@@ -87,6 +88,7 @@ export declare function compileContainerItemsQuery(parameters: {
   body: (context: OchreQueryContext & {
     items: string;
   }) => string;
+  contentLanguage?: OchreContentLanguage | null;
 }): string;
 /**
  * Reduce a property-value facet query tree to the leaves that filter items

package/dist/query.mjs

@@ -14,32 +14,25 @@ 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 CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
-	title: [
-		"identification",
-		"label",
-		"content"
-	],
-	description: ["description", "content"],
+const CONTENT_TARGET_FIELD_ELEMENT_PATHS = {
+	title: ["identification", "label"],
+	description: ["description"],
 	image: [
 		"image",
 		"identification",
-		"label",
-		"content"
+		"label"
 	],
 	periods: [
 		"periods",
 		"period",
 		"identification",
-		"label",
-		"content"
+		"label"
 	],
 	bibliography: [
 		"bibliographies",
 		"bibliography",
 		"identification",
-		"label",
-		"content"
+		"label"
 	]
 };
 const HELPER_SEARCH_VALUE_REFERENCE = "$value";
@@ -246,36 +239,51 @@ function buildValueNotIdReferenceQuery() {
 		value: searchValue("IDREF")
 	}));
 }
-function buildRichTextContentQueryExpression(parameters) {
-	const { value, matchMode, isCaseSensitive, language } = parameters;
-	return buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), matchMode === "exact" ? buildRichTextExactQueryExpression({
-		value,
-		isCaseSensitive,
-		language
-	}) : buildCtsWordQueryExpression({
-		value,
-		matchMode,
-		isCaseSensitive,
-		queryFamily: "text",
-		language
-	})]);
+/**
+* Match a field's `content` in a language, falling back to another language
+* only for fields that carry no content in the first one
+*
+* Placed inside the field element (a label, a note, a property value), so the
+* missing-language check is scoped to that one field. Without a distinct
+* fallback it is the single-language query this always compiled to.
+*/
+function buildLocalizedContentQueryExpression(parameters) {
+	const { language, fallbackLanguage, buildMatchQuery } = parameters;
+	function buildContentQuery(contentLanguage) {
+		return buildNestedElementQuery(["content"], buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(contentLanguage), buildMatchQuery(contentLanguage)]));
+	}
+	if (fallbackLanguage == null || fallbackLanguage === language) return buildContentQuery(language);
+	return buildOrCtsQueryExpressionInternal([buildContentQuery(language), buildAndCtsQueryExpressionInternal([buildNotCtsQueryExpression(buildNestedElementQuery(["content"], buildContentLanguageQuery(language))), buildContentQuery(fallbackLanguage)])]);
 }
-function buildValueContentInnerQuery(parameters) {
-	const { language, value, matchMode, isCaseSensitive } = parameters;
-	return buildNestedElementQuery(["content"], buildRichTextContentQueryExpression({
+function buildRichTextContentQueryExpression(parameters) {
+	const { value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
+	return buildLocalizedContentQueryExpression({
 		language,
-		value,
-		matchMode,
-		isCaseSensitive
-	}));
+		fallbackLanguage,
+		buildMatchQuery: (contentLanguage) => matchMode === "exact" ? buildRichTextExactQueryExpression({
+			value,
+			isCaseSensitive,
+			language: contentLanguage
+		}) : buildCtsWordQueryExpression({
+			value,
+			matchMode,
+			isCaseSensitive,
+			queryFamily: "text",
+			language: contentLanguage
+		})
+	});
 }
 function buildValueContentExactInnerQuery(parameters) {
-	const { language, value, isCaseSensitive } = parameters;
-	return buildNestedElementQuery(["content"], buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), buildCtsElementValueQueryExpression({
-		elementName: "string",
-		value,
-		isCaseSensitive
-	})]));
+	const { language, fallbackLanguage, value, isCaseSensitive } = parameters;
+	return buildLocalizedContentQueryExpression({
+		language,
+		fallbackLanguage,
+		buildMatchQuery: () => buildCtsElementValueQueryExpression({
+			elementName: "string",
+			value,
+			isCaseSensitive
+		})
+	});
 }
 function buildValueDirectTextInnerQuery(parameters) {
 	const { value, matchMode, isCaseSensitive } = parameters;
@@ -310,26 +318,23 @@ function buildValueRawValueInnerQuery(parameters) {
 	});
 }
 function buildNotesQueryExpression(parameters) {
-	const { value, matchMode, isCaseSensitive, language } = parameters;
-	return buildNestedElementQuery([
-		"notes",
-		"note",
-		"content"
-	], buildRichTextContentQueryExpression({
+	const { value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
+	return buildNestedElementQuery(["notes", "note"], buildRichTextContentQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
-		language
+		language,
+		fallbackLanguage
 	}));
 }
 function buildContentTargetQueryExpression(parameters) {
-	const { target, value, matchMode, isCaseSensitive, language } = parameters;
-	const contentElementPath = CONTENT_TARGET_CONTENT_ELEMENT_PATHS[target];
-	return buildNestedElementQuery(contentElementPath, buildRichTextContentQueryExpression({
+	const { target, value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
+	return buildNestedElementQuery(CONTENT_TARGET_FIELD_ELEMENT_PATHS[target], buildRichTextContentQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
-		language
+		language,
+		fallbackLanguage
 	}));
 }
 function buildPropertyQueryExpression(parameters) {
@@ -381,16 +386,18 @@ function buildPropertyPresenceQueryExpression(parameters) {
 	});
 }
 function buildPropertyStringQueryExpression(parameters) {
-	const { propertyVariable, propertyRelation, value, matchMode, isCaseSensitive, language } = parameters;
+	const { propertyVariable, propertyRelation, value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
 	return buildPropertyTextMatchQueryExpression({
 		propertyVariable,
 		propertyRelation,
 		contentQueryExpression: matchMode === "exact" ? buildValueContentExactInnerQuery({
 			language,
+			fallbackLanguage,
 			value,
 			isCaseSensitive
-		}) : buildValueContentInnerQuery({
+		}) : buildRichTextContentQueryExpression({
 			language,
+			fallbackLanguage,
 			value,
 			matchMode,
 			isCaseSensitive
@@ -429,8 +436,9 @@ function buildPropertyAllQueryExpression(parameters) {
 		propertyVariable: query.propertyVariable,
 		propertyRelation: query.propertyRelation,
 		valueFilters: [buildValueNotIdReferenceQuery()],
-		contentQueryExpression: buildValueContentInnerQuery({
+		contentQueryExpression: buildRichTextContentQueryExpression({
 			language: query.language,
+			fallbackLanguage: query.fallbackLanguage,
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive
@@ -470,18 +478,20 @@ function buildPropertyDateRangeQueryExpression(query) {
 	});
 }
 function buildItemStringQueryExpression(parameters) {
-	const { value, matchMode, isCaseSensitive, language } = parameters;
+	const { value, matchMode, isCaseSensitive, language, fallbackLanguage } = parameters;
 	return buildOrCtsQueryExpressionInternal([buildContentTargetQueryExpression({
 		target: "title",
 		value,
 		matchMode,
 		isCaseSensitive,
-		language
+		language,
+		fallbackLanguage
 	}), buildPropertyStringQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
-		language
+		language,
+		fallbackLanguage
 	})]);
 }
 function tokenizeOcrExactValue(value) {
@@ -614,13 +624,15 @@ function buildLeafValueQueryExpression(parameters) {
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive,
-			language: query.language
+			language: query.language,
+			fallbackLanguage: query.fallbackLanguage
 		});
 		case "notes": return buildNotesQueryExpression({
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive,
-			language: query.language
+			language: query.language,
+			fallbackLanguage: query.fallbackLanguage
 		});
 		case "title":
 		case "description":
@@ -631,7 +643,8 @@ function buildLeafValueQueryExpression(parameters) {
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive,
-			language: query.language
+			language: query.language,
+			fallbackLanguage: query.fallbackLanguage
 		});
 		case "property": switch (query.dataType) {
 			case "all": return buildPropertyAllQueryExpression({
@@ -650,7 +663,8 @@ function buildLeafValueQueryExpression(parameters) {
 				value,
 				matchMode,
 				isCaseSensitive: query.isCaseSensitive,
-				language: query.language
+				language: query.language,
+				fallbackLanguage: query.fallbackLanguage
 			});
 			case "integer":
 			case "decimal":
@@ -728,7 +742,8 @@ function getLeafHelperKey(parameters) {
 			query.target,
 			value,
 			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
-			query.language
+			query.language,
+			query.fallbackLanguage ?? ""
 		].join("|");
 		case "property": return [
 			"leaf",
@@ -739,7 +754,8 @@ function getLeafHelperKey(parameters) {
 			query.propertyRelation ?? "",
 			value,
 			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
-			query.language
+			query.language,
+			query.fallbackLanguage ?? ""
 		].join("|");
 	}
 }
@@ -775,6 +791,7 @@ function getIncludesLeafHelperKey(parameters) {
 			query.target,
 			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
 			query.language,
+			query.fallbackLanguage ?? "",
 			isWildcarded ? "wildcarded" : "unwildcarded",
 			isStemmed ? "stemmed" : "unstemmed"
 		].join("|");
@@ -786,6 +803,7 @@ function getIncludesLeafHelperKey(parameters) {
 			query.propertyRelation ?? "",
 			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
 			query.language,
+			query.fallbackLanguage ?? "",
 			isWildcarded ? "wildcarded" : "unwildcarded",
 			isStemmed ? "stemmed" : "unstemmed"
 		].join("|");
@@ -876,7 +894,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 === "ocr") return null;
+		if (!isQueryLeaf(childQuery) || childQuery.target === "ocr" || childQuery.fallbackLanguage != null && childQuery.fallbackLanguage !== childQuery.language) return null;
 		leafQueries.push(childQuery);
 	}
 	const firstQuery = leafQueries[0];
@@ -941,7 +959,26 @@ function buildCtsItemsPlan(queryExpression) {
 	return {
 		kind: "search",
 		itemPredicates: [],
-		queryExpressions: [queryExpression]
+		queryExpressions: [queryExpression],
+		resultPredicates: []
+	};
+}
+/**
+* Plan a leaf that falls back to a second language for fields missing the first
+*
+* The strict query needs a `cts:not-query` scoped to one field, which CTS
+* resolves against the Set's single fragment and so rules out every item the
+* moment any item holds the first language. The search therefore runs a
+* superset (the leaf in either language), and `cts:contains` then applies the
+* strict query to each matched item projection, where the negation is exact.
+*/
+function buildFallbackItemsPlan(parameters) {
+	const { supersetQueryExpression, strictQueryExpression } = parameters;
+	return {
+		kind: "search",
+		itemPredicates: [],
+		queryExpressions: [supersetQueryExpression],
+		resultPredicates: [`[cts:contains(., ${strictQueryExpression})]`]
 	};
 }
 /**
@@ -958,7 +995,8 @@ function buildNegatedItemsPlan(queryExpression) {
 	return {
 		kind: "search",
 		itemPredicates: [`[not(cts:contains(., ${queryExpression}))]`],
-		queryExpressions: []
+		queryExpressions: [],
+		resultPredicates: []
 	};
 }
 /**
@@ -976,6 +1014,9 @@ function flattenItemsPlans(childPlans, kind) {
 	}
 	return flattenedPlans;
 }
+function appendUniquePredicates(predicates, addedPredicates) {
+	for (const predicate of addedPredicates) if (!predicates.includes(predicate)) predicates.push(predicate);
+}
 /**
 * Fold the children of an `and` group into one plan
 *
@@ -987,7 +1028,8 @@ function buildAndItemsPlan(childPlans) {
 	const mergedPlan = {
 		kind: "search",
 		itemPredicates: [],
-		queryExpressions: []
+		queryExpressions: [],
+		resultPredicates: []
 	};
 	const unfoldablePlans = [];
 	for (const childPlan of flattenItemsPlans(childPlans, "intersect")) {
@@ -995,11 +1037,12 @@ function buildAndItemsPlan(childPlans) {
 			unfoldablePlans.push(childPlan);
 			continue;
 		}
-		for (const itemPredicate of childPlan.itemPredicates) if (!mergedPlan.itemPredicates.includes(itemPredicate)) mergedPlan.itemPredicates.push(itemPredicate);
+		appendUniquePredicates(mergedPlan.itemPredicates, childPlan.itemPredicates);
+		appendUniquePredicates(mergedPlan.resultPredicates, childPlan.resultPredicates);
 		mergedPlan.queryExpressions.push(...childPlan.queryExpressions);
 	}
 	if (unfoldablePlans.length === 0) return mergedPlan;
-	const intersectedPlans = mergedPlan.itemPredicates.length === 0 && mergedPlan.queryExpressions.length === 0 ? unfoldablePlans : [mergedPlan, ...unfoldablePlans];
+	const intersectedPlans = mergedPlan.itemPredicates.length === 0 && mergedPlan.queryExpressions.length === 0 && mergedPlan.resultPredicates.length === 0 ? unfoldablePlans : [mergedPlan, ...unfoldablePlans];
 	return intersectedPlans.length === 1 ? intersectedPlans[0] ?? mergedPlan : {
 		kind: "intersect",
 		children: intersectedPlans
@@ -1015,7 +1058,7 @@ function buildOrItemsPlan(childPlans) {
 	const mergedQueryExpressions = [];
 	const unionedPlans = [];
 	for (const childPlan of flattenItemsPlans(childPlans, "union")) {
-		if (childPlan.kind === "search" && childPlan.itemPredicates.length === 0) {
+		if (childPlan.kind === "search" && childPlan.itemPredicates.length === 0 && childPlan.resultPredicates.length === 0) {
 			mergedQueryExpressions.push(buildAndCtsQueryExpressionInternal(childPlan.queryExpressions));
 			continue;
 		}
@@ -1024,7 +1067,8 @@ function buildOrItemsPlan(childPlans) {
 	if (mergedQueryExpressions.length > 0) unionedPlans.unshift({
 		kind: "search",
 		itemPredicates: [],
-		queryExpressions: [buildOrCtsQueryExpressionInternal(mergedQueryExpressions)]
+		queryExpressions: [buildOrCtsQueryExpressionInternal(mergedQueryExpressions)],
+		resultPredicates: []
 	});
 	if (unionedPlans.length === 0) return buildCtsItemsPlan("cts:false-query()");
 	return unionedPlans.length === 1 ? unionedPlans[0] ?? buildCtsItemsPlan("cts:false-query()") : {
@@ -1039,11 +1083,24 @@ function buildItemsPlan(context, query) {
 			return {
 				kind: "search",
 				itemPredicates: [query.isNegated === true ? `[not(@uuid = ${bindingName})]` : `[@uuid = ${bindingName}]`],
-				queryExpressions: []
+				queryExpressions: [],
+				resultPredicates: []
 			};
 		}
 		const queryExpression = buildLeafQueryExpression(context, query);
-		return query.isNegated === true ? buildNegatedItemsPlan(queryExpression) : buildCtsItemsPlan(queryExpression);
+		if (query.isNegated === true) return buildNegatedItemsPlan(queryExpression);
+		if (query.fallbackLanguage == null || query.fallbackLanguage === query.language) return buildCtsItemsPlan(queryExpression);
+		return buildFallbackItemsPlan({
+			supersetQueryExpression: buildOrCtsQueryExpressionInternal([buildLeafQueryExpression(context, {
+				...query,
+				fallbackLanguage: void 0
+			}), buildLeafQueryExpression(context, {
+				...query,
+				language: query.fallbackLanguage,
+				fallbackLanguage: void 0
+			})]),
+			strictQueryExpression: queryExpression
+		});
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
 	if (optimizedIncludesGroupQueries != null) return buildCtsItemsPlan(buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries));
@@ -1062,7 +1119,8 @@ function buildItemsPlanExpression(parameters) {
 	if (plan.kind === "search") {
 		const itemsExpression = `${baseItemsExpression}${plan.itemPredicates.join("")}`;
 		const queryName = queryNamesByPlan.get(plan);
-		return queryName == null ? itemsExpression : `cts:search(${itemsExpression}, ${queryName})`;
+		const searchedExpression = queryName == null ? itemsExpression : `cts:search(${itemsExpression}, ${queryName})`;
+		return plan.resultPredicates.length === 0 ? searchedExpression : `(${searchedExpression})${plan.resultPredicates.join("")}`;
 	}
 	return `(${Array.from(plan.children, (childPlan) => buildItemsPlanExpression({
 		plan: childPlan,
@@ -1150,7 +1208,8 @@ function buildQueryPlan(parameters) {
 	const plan = queries == null ? {
 		kind: "search",
 		itemPredicates: [],
-		queryExpressions: []
+		queryExpressions: [],
+		resultPredicates: []
 	} : buildItemsPlan(context, queries);
 	const searchPlans = [];
 	collectItemsSearchPlans(plan, searchPlans);
@@ -1202,11 +1261,12 @@ function buildQueryPlan(parameters) {
 * @param parameters.queries - The query tree to compile, or null to match every item
 * @param parameters.declarations - Extra prolog declarations, placed before the compiled prolog
 * @param parameters.body - Builds the body from the name of the variable holding the items
+* @param parameters.contentLanguage - Keep only this language of every multilingual field in the result
 * @returns A complete XQuery document
 * @internal
 */
 function compileContainerItemsQuery(parameters) {
-	const { container, scopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body } = parameters;
+	const { container, scopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body, contentLanguage } = parameters;
 	const { scopeVariable, itemsExpression } = ITEMS_CONTAINERS[container];
 	const plan = buildQueryPlan({
 		queries,
@@ -1225,7 +1285,8 @@ ${body({
 			...context,
 			items: plan.itemsVariable
 		})}
-}</ochre>`
+}</ochre>`,
+		contentLanguage
 	});
 }
 /**

package/dist/schemas.mjs

@@ -84,6 +84,7 @@ const standardQueryFields = {
 	matchMode: v.picklist(["includes", "exact"]),
 	isCaseSensitive: v.boolean(),
 	language: defaultString("eng"),
+	fallbackLanguage: v.optional(v.string()),
 	isNegated: defaultBoolean(false)
 };
 const propertyRelationSchema = v.picklist(["related", "inverse"]);

package/dist/types/index.d.mts

@@ -853,6 +853,10 @@ export type SetItemsSort = {
  * 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`.
+ *
+ * `fallbackLanguage` searches a field in that language only when the field has
+ * no content in `language`, so a match follows the text a reader of `language`
+ * is shown. Leave it unset to search `language` alone.
  */
 export type QueryLeaf = {
   target: "property";
@@ -865,6 +869,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "property";
@@ -877,6 +882,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "property";
@@ -889,6 +895,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "property";
@@ -901,6 +908,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "property";
@@ -911,6 +919,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "string";
@@ -918,6 +927,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 } | {
   target: "ocr";
@@ -931,6 +941,7 @@ export type QueryLeaf = {
   matchMode: "includes" | "exact";
   isCaseSensitive: boolean;
   language: string;
+  fallbackLanguage?: string;
   isNegated?: boolean;
 };
 /**

package/dist/xquery.d.mts

@@ -17,6 +17,25 @@ export declare function stringLiteral(value: string): string;
  * @internal
  */
 export declare const OCHRE_RESPONSE_PADDING = "<!--ochre-sdk: keeps an empty result distinct from a failed query-->";
+/**
+ * Which language a query should return, and what to show where it is missing
+ */
+export type OchreContentLanguage = {
+  language: string;
+  fallbackLanguage: string;
+};
+/**
+ * Resolve the content language a fetch asked for
+ * @param options - The fetch options
+ * @param options.language - The language to keep
+ * @param options.fallbackLanguage - The language shown where `language` is missing
+ * @returns The content language, or null to keep every language
+ * @internal
+ */
+export declare function getContentLanguage(options?: {
+  language?: string;
+  fallbackLanguage?: string;
+}): OchreContentLanguage | null;
 /**
  * What a query body can ask the surrounding document for
  *
@@ -47,11 +66,13 @@ export type OchreQueryContext = {
  * @param parameters - The document parameters
  * @param parameters.declarations - Prolog declarations, emitted in order before the supplemental helper
  * @param parameters.body - Builds the query body
+ * @param parameters.contentLanguage - Keep only this language of every multilingual field in the result
  * @returns A complete XQuery document
  * @internal
  */
 export declare function compileOchreQuery(parameters: {
   declarations?: ReadonlyArray<string>;
   body: (context: OchreQueryContext) => string;
+  contentLanguage?: OchreContentLanguage | null;
 }): string;
 //#endregion

package/dist/xquery.mjs

@@ -1,3 +1,4 @@
+import { DEFAULT_LANGUAGES } from "./constants.mjs";
 //#region src/xquery.ts
 /**
 * Build a string literal for an XQuery string
@@ -46,6 +47,63 @@ const SUPPLEMENTAL_XQUERY_PROLOG = `declare function local:omit-supplemental($no
       }
     else $node
 };`;
+/**
+* XQuery prolog declaring `local:select-language`, which keeps one language of
+* every multilingual field in a node sequence
+*
+* A field's `content` children are reduced to the one in `$language`, else the
+* one in `$fallback`, else the first in any language, which is the choice the
+* API's own `lang` parameter makes. `zxx` content is always kept, since it holds
+* a field's aliases rather than a translation; the API's `lang` parameter drops
+* it, which is why the SDK selects languages itself. Leaf elements are
+* returned by reference; testing for multilingual descendants before copying a
+* subtree measured slower than copying it.
+*/
+const LANGUAGE_XQUERY_PROLOG = `declare function local:select-language($nodes as node()*, $language as xs:string, $fallback as xs:string) as node()* {
+  for $node in $nodes
+  return
+    typeswitch ($node)
+    case element() return
+      if (empty($node/*))
+      then $node
+      else
+        let $contents := $node/content[@xml:lang]
+        let $selected :=
+          if (empty($contents))
+          then ()
+          else (
+            $contents[@xml:lang = $language],
+            $contents[@xml:lang = $fallback],
+            $contents[@xml:lang != "zxx"]
+          )[1]
+        return element { node-name($node) } {
+          $node/@*,
+          for $child in $node/node()
+          return
+            if ($child instance of element(content) and exists($child/@xml:lang))
+            then
+              if ($child is $selected or $child/@xml:lang = "zxx")
+              then $child
+              else ()
+            else local:select-language($child, $language, $fallback)
+        }
+    default return $node
+};`;
+/**
+* Resolve the content language a fetch asked for
+* @param options - The fetch options
+* @param options.language - The language to keep
+* @param options.fallbackLanguage - The language shown where `language` is missing
+* @returns The content language, or null to keep every language
+* @internal
+*/
+function getContentLanguage(options) {
+	if (options?.language == null) return null;
+	return {
+		language: options.language,
+		fallbackLanguage: options.fallbackLanguage ?? DEFAULT_LANGUAGES[0]
+	};
+}
 const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"true\"])]";
 /**
 * Compile a complete XQuery document for the OCHRE API
@@ -57,21 +115,27 @@ const NOT_SUPPLEMENTAL_PREDICATE = "[not(ancestor-or-self::*[@supplemental = \"t
 * @param parameters - The document parameters
 * @param parameters.declarations - Prolog declarations, emitted in order before the supplemental helper
 * @param parameters.body - Builds the query body
+* @param parameters.contentLanguage - Keep only this language of every multilingual field in the result
 * @returns A complete XQuery document
 * @internal
 */
 function compileOchreQuery(parameters) {
-	const { declarations = [], body } = parameters;
-	return `${[
+	const { declarations = [], body, contentLanguage } = parameters;
+	const prologDeclarations = [
 		"xquery version \"1.0-ml\";",
 		...declarations,
-		SUPPLEMENTAL_XQUERY_PROLOG
-	].join("\n\n")}
-
-${body({
+		SUPPLEMENTAL_XQUERY_PROLOG,
+		...contentLanguage == null ? [] : [LANGUAGE_XQUERY_PROLOG]
+	];
+	const bodyExpression = body({
 		omitSupplemental: (expression) => `local:omit-supplemental(${expression})`,
 		notSupplemental: NOT_SUPPLEMENTAL_PREDICATE
-	})}`;
+	});
+	return `${prologDeclarations.join("\n\n")}
+
+${contentLanguage == null ? bodyExpression : `local:select-language((
+${bodyExpression}
+), ${stringLiteral(contentLanguage.language)}, ${stringLiteral(contentLanguage.fallbackLanguage)})`}`;
 }
 //#endregion
-export { OCHRE_RESPONSE_PADDING, compileOchreQuery, stringLiteral };
+export { OCHRE_RESPONSE_PADDING, compileOchreQuery, getContentLanguage, stringLiteral };

package/package.json

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