ochre-sdk 0.22.16 → 0.22.19

package/dist/index.d.mts

@@ -300,6 +300,7 @@ type Event = {
 type Interpretation = {
   date: string | null;
   number: number;
+  notes: Array<Note>;
   links: Array<Link>;
   properties: Array<Property>;
   bibliographies: Array<Bibliography>;

package/dist/index.mjs

@@ -1292,7 +1292,7 @@ function parseObservation(observation) {
 * @returns Array of parsed Observation objects
 */
 function parseObservations(observations) {
-	return observations.map((obs) => parseObservation(obs));
+	return observations.map((observation) => parseObservation(observation));
 }
 /**
 * Parses an array of raw events into standardized Event objects
@@ -1435,12 +1435,13 @@ function parseProperties(properties, language = "eng") {
 * @returns Array of parsed Interpretation objects
 */
 function parseInterpretations(interpretations) {
-	return interpretations.map((interp) => ({
-		date: interp.date ?? null,
-		number: interp.interpretationNo,
-		links: interp.links ? parseLinks(ensureArray(interp.links)) : [],
-		properties: interp.properties ? parseProperties(ensureArray(interp.properties.property)) : [],
-		bibliographies: interp.bibliographies ? parseBibliographies(ensureArray(interp.bibliographies.bibliography)) : []
+	return interpretations.map((interpretation) => ({
+		date: interpretation.date ?? null,
+		number: interpretation.interpretationNo,
+		notes: interpretation.notes ? parseNotes(ensureArray(interpretation.notes.note)) : [],
+		links: interpretation.links ? parseLinks(ensureArray(interpretation.links)) : [],
+		properties: interpretation.properties ? parseProperties(ensureArray(interpretation.properties.property)) : [],
+		bibliographies: interpretation.bibliographies ? parseBibliographies(ensureArray(interpretation.bibliographies.bibliography)) : []
 	}));
 }
 /**
@@ -2155,7 +2156,7 @@ const CTS_INCLUDES_STOP_WORDS = new Set([
 ]);
 const CTS_INCLUDES_TOKEN_WORD_REGEX = /^\p{L}+$/u;
 const CTS_INCLUDES_TOKEN_REGEX = /[\p{L}\p{N}*?]+/gu;
-const CTS_INCLUDES_TOKEN_SPLIT_REGEX = /\W+/u;
+const CTS_EXACT_TEXT_TOKEN_REGEX = /[\p{L}\p{N}]+/gu;
 const CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
 	title: [
 		"identification",
@@ -2198,9 +2199,9 @@ function tokenizeIncludesSearchValue(params) {
 	}
 	return terms;
 }
-function tokenizeExactPhraseSearchValue(params) {
+function tokenizeExactTextSearchValue(params) {
 	const { value, isCaseSensitive } = params;
-	const rawTerms = (isCaseSensitive ? value : value.toLowerCase()).split(CTS_INCLUDES_TOKEN_SPLIT_REGEX);
+	const rawTerms = (isCaseSensitive ? value : value.toLowerCase()).match(CTS_EXACT_TEXT_TOKEN_REGEX) ?? [];
 	const terms = [];
 	for (const term of rawTerms) if (term !== "") terms.push(term);
 	return terms;
@@ -2215,7 +2216,23 @@ function shouldUseStemmedTextSearch(value) {
 	const wildcardStrippedValue = getWildcardStrippedValue(value);
 	return wildcardStrippedValue.length >= 3 && CTS_INCLUDES_TOKEN_WORD_REGEX.test(wildcardStrippedValue);
 }
-function buildCtsMatchOptionsExpression(params) {
+function shouldUseFullValueFallbackForIncludes(params) {
+	const { value, isCaseSensitive, terms } = params;
+	if (terms.length <= 1) return false;
+	const tokenSource = isCaseSensitive ? value : value.toLowerCase();
+	if (/[^\p{L}\p{N}\s*?]/u.test(tokenSource)) return true;
+	const rawSpaceTerms = tokenSource.trim().split(/\s+/u).filter(Boolean);
+	if (rawSpaceTerms.length !== terms.length) return true;
+	for (const rawTerm of rawSpaceTerms) {
+		const wildcardStrippedTerm = getWildcardStrippedValue(rawTerm);
+		if (hasWildcardCharacters(rawTerm)) return true;
+		if (!CTS_INCLUDES_TOKEN_WORD_REGEX.test(wildcardStrippedTerm)) return true;
+		if (CTS_INCLUDES_STOP_WORDS.has(rawTerm.toLowerCase())) return true;
+	}
+	for (const [index, rawTerm] of rawSpaceTerms.entries()) if (rawTerm !== (terms[index] ?? "")) return true;
+	return false;
+}
+function buildWordQueryOptionsExpression(params) {
 	const { matchMode, isCaseSensitive, queryFamily, language, isWildcarded } = params;
 	const { isStemmed } = params;
 	const options = [
@@ -2228,14 +2245,25 @@ function buildCtsMatchOptionsExpression(params) {
 	else if (queryFamily === "text") {
 		options.push(isStemmed ? "stemmed" : "unstemmed", isWildcarded ? "wildcarded" : "unwildcarded");
 		if (isStemmed && language != null && language !== "") options.push(`lang=${language}`);
-	} else options.push("unstemmed", isWildcarded ? "wildcarded" : "unwildcarded");
+	}
 	return `(${options.map((option) => stringLiteral(option)).join(", ")})`;
 }
+function buildRichTextPhraseOptionsExpression(params) {
+	const { isCaseSensitive } = params;
+	return `(${[
+		isCaseSensitive ? "case-sensitive" : "case-insensitive",
+		"diacritic-sensitive",
+		"punctuation-insensitive",
+		"whitespace-insensitive",
+		"unstemmed",
+		"unwildcarded"
+	].map((option) => stringLiteral(option)).join(", ")})`;
+}
 function buildCtsWordQueryExpression(params) {
 	const { value, matchMode, isCaseSensitive, queryFamily, language } = params;
 	const isWildcarded = matchMode === "includes" && hasWildcardCharacters(value);
 	const isStemmed = matchMode === "includes" && queryFamily === "text" && !isWildcarded && shouldUseStemmedTextSearch(value);
-	return `cts:word-query(${stringLiteral(value)}, ${buildCtsMatchOptionsExpression({
+	return `cts:word-query(${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
 		matchMode,
 		isCaseSensitive,
 		queryFamily,
@@ -2244,11 +2272,31 @@ function buildCtsWordQueryExpression(params) {
 		isStemmed
 	})})`;
 }
+function buildRichTextPhraseQueryExpression(params) {
+	const { value, isCaseSensitive } = params;
+	return `cts:word-query(${stringLiteral(value)}, ${buildRichTextPhraseOptionsExpression({ isCaseSensitive })})`;
+}
+function buildRichTextExactQueryExpression(params) {
+	const { value, isCaseSensitive } = params;
+	const phraseQuery = buildRichTextPhraseQueryExpression({
+		value,
+		isCaseSensitive
+	});
+	const terms = tokenizeExactTextSearchValue({
+		value,
+		isCaseSensitive
+	});
+	if (terms.length <= 1) return phraseQuery;
+	return buildOrCtsQueryExpressionInternal([phraseQuery, buildAndCtsQueryExpressionInternal(terms.map((term) => buildRichTextPhraseQueryExpression({
+		value: term,
+		isCaseSensitive
+	})))]);
+}
 function buildCtsElementWordQueryExpression(params) {
 	const { elementName, value, matchMode, isCaseSensitive, queryFamily, language } = params;
 	const isWildcarded = matchMode === "includes" && hasWildcardCharacters(value);
 	const isStemmed = matchMode === "includes" && queryFamily === "text" && !isWildcarded && shouldUseStemmedTextSearch(value);
-	return `cts:element-word-query(xs:QName("${elementName}"), ${stringLiteral(value)}, ${buildCtsMatchOptionsExpression({
+	return `cts:element-word-query(xs:QName("${elementName}"), ${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
 		matchMode,
 		isCaseSensitive,
 		queryFamily,
@@ -2261,7 +2309,7 @@ function buildCtsElementAttributeWordQueryExpression(params) {
 	const { elementName, attributeName, value, matchMode, isCaseSensitive, queryFamily, language } = params;
 	const isWildcarded = matchMode === "includes" && hasWildcardCharacters(value);
 	const isStemmed = matchMode === "includes" && queryFamily === "text" && !isWildcarded && shouldUseStemmedTextSearch(value);
-	return `cts:element-attribute-word-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${stringLiteral(value)}, ${buildCtsMatchOptionsExpression({
+	return `cts:element-attribute-word-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
 		matchMode,
 		isCaseSensitive,
 		queryFamily,
@@ -2272,14 +2320,14 @@ function buildCtsElementAttributeWordQueryExpression(params) {
 }
 function buildCtsElementValueQueryExpression(params) {
 	const { elementName, value, isCaseSensitive } = params;
-	return `cts:element-value-query(xs:QName("${elementName}"), ${stringLiteral(value)}, ${buildCtsMatchOptionsExpression({
+	return `cts:element-value-query(xs:QName("${elementName}"), ${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
 		matchMode: "exact",
 		isCaseSensitive
 	})})`;
 }
 function buildCtsElementAttributeValueQueryExpression(params) {
 	const { elementName, attributeName, value, isCaseSensitive } = params;
-	return `cts:element-attribute-value-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${stringLiteral(value)}, ${buildCtsMatchOptionsExpression({
+	return `cts:element-attribute-value-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
 		matchMode: "exact",
 		isCaseSensitive
 	})})`;
@@ -2288,39 +2336,6 @@ function buildPlainElementAttributeValueQueryExpression(params) {
 	const { elementName, attributeName, value } = params;
 	return `cts:element-attribute-value-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${stringLiteral(value)})`;
 }
-function buildSearchableContentTextQueryExpression(params) {
-	const { value, matchMode, isCaseSensitive, language } = params;
-	if (matchMode === "exact") {
-		const phraseTerms = tokenizeExactPhraseSearchValue({
-			value,
-			isCaseSensitive
-		});
-		if (phraseTerms.length > 1) return buildAndCtsQueryExpressionInternal(phraseTerms.map((term) => buildCtsWordQueryExpression({
-			value: term,
-			matchMode,
-			isCaseSensitive
-		})));
-		return buildCtsWordQueryExpression({
-			value,
-			matchMode,
-			isCaseSensitive
-		});
-	}
-	return buildOrCtsQueryExpressionInternal([buildCtsElementWordQueryExpression({
-		elementName: "string",
-		value,
-		matchMode,
-		isCaseSensitive,
-		queryFamily: "text",
-		language
-	}), buildCtsWordQueryExpression({
-		value,
-		matchMode,
-		isCaseSensitive,
-		queryFamily: "text",
-		language
-	})]);
-}
 function buildNestedElementQuery(elementNames, queryExpression) {
 	let wrappedQueryExpression = queryExpression;
 	for (const elementName of elementNames.toReversed()) wrappedQueryExpression = `cts:element-query(xs:QName("${elementName}"), ${wrappedQueryExpression})`;
@@ -2371,14 +2386,28 @@ function buildValueNotIdRefQuery() {
 		value: "IDREF"
 	}));
 }
-function buildValueContentInnerQuery(params) {
-	const { language, value, matchMode, isCaseSensitive } = params;
-	return buildNestedElementQuery(["content"], buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), buildSearchableContentTextQueryExpression({
+function buildRichTextContentQueryExpression(params) {
+	const { value, matchMode, isCaseSensitive, language } = params;
+	return buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), matchMode === "exact" ? buildRichTextExactQueryExpression({
+		value,
+		isCaseSensitive,
+		language
+	}) : buildCtsWordQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
+		queryFamily: "text",
 		language
-	})]));
+	})]);
+}
+function buildValueContentInnerQuery(params) {
+	const { language, value, matchMode, isCaseSensitive } = params;
+	return buildNestedElementQuery(["content"], buildRichTextContentQueryExpression({
+		language,
+		value,
+		matchMode,
+		isCaseSensitive
+	}));
 }
 function buildValueDirectTextInnerQuery(params) {
 	const { value, matchMode, isCaseSensitive } = params;
@@ -2418,35 +2447,22 @@ function buildNotesQueryExpression(params) {
 		"notes",
 		"note",
 		"content"
-	], buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), buildOrCtsQueryExpressionInternal([matchMode === "exact" ? buildCtsElementAttributeValueQueryExpression({
-		elementName: "content",
-		attributeName: "title",
-		value,
-		isCaseSensitive
-	}) : buildCtsElementAttributeWordQueryExpression({
-		elementName: "content",
-		attributeName: "title",
+	], buildRichTextContentQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
-		queryFamily: "text",
 		language
-	}), buildSearchableContentTextQueryExpression({
-		value,
-		matchMode,
-		isCaseSensitive,
-		language
-	})])]));
+	}));
 }
 function buildContentTargetQueryExpression(params) {
 	const { target, value, matchMode, isCaseSensitive, language } = params;
 	const contentElementPath = CONTENT_TARGET_CONTENT_ELEMENT_PATHS[target];
-	return buildNestedElementQuery(contentElementPath, buildAndCtsQueryExpressionInternal([buildContentLanguageQuery(language), buildSearchableContentTextQueryExpression({
+	return buildNestedElementQuery(contentElementPath, buildRichTextContentQueryExpression({
 		value,
 		matchMode,
 		isCaseSensitive,
 		language
-	})]));
+	}));
 }
 function buildPropertyQueryExpression(params) {
 	const { propertyVariable, queryExpression } = params;
@@ -2454,6 +2470,31 @@ function buildPropertyQueryExpression(params) {
 	if (propertyVariable != null) propertyQueryExpressions.unshift(buildPropertyLabelQuery(propertyVariable));
 	return buildNestedElementQuery(["properties", "property"], buildAndCtsQueryExpressionInternal(propertyQueryExpressions));
 }
+function buildPropertyTextMatchQueryExpression(params) {
+	const { propertyVariable, valueFilters = [], contentQueryExpression, rawValueQueryExpression, bareValueQueryExpression } = params;
+	const letBindings = [];
+	const valueMatchReferences = [];
+	if (contentQueryExpression != null) {
+		letBindings.push(`let $contentQuery := ${contentQueryExpression}`);
+		valueMatchReferences.push("$contentQuery");
+	}
+	if (rawValueQueryExpression != null) {
+		letBindings.push(`let $rawValueQuery := ${rawValueQueryExpression}`);
+		valueMatchReferences.push("$rawValueQuery");
+	}
+	if (bareValueQueryExpression != null) {
+		letBindings.push(`let $bareValueQuery := ${bareValueQueryExpression}`);
+		valueMatchReferences.push("$bareValueQuery");
+	}
+	const valueQueryExpressions = [...valueFilters];
+	if (valueMatchReferences.length > 0) valueQueryExpressions.push(buildOrCtsQueryExpressionInternal(valueMatchReferences));
+	const propertyQueryExpressions = [];
+	if (propertyVariable != null) propertyQueryExpressions.push(buildPropertyLabelQuery(propertyVariable));
+	propertyQueryExpressions.push(buildNestedElementQuery(["value"], buildAndCtsQueryExpressionInternal(valueQueryExpressions)));
+	const propertyQueryExpression = buildNestedElementQuery(["properties", "property"], buildAndCtsQueryExpressionInternal(propertyQueryExpressions));
+	if (letBindings.length === 0) return propertyQueryExpression;
+	return `(${letBindings.join("\n  ")}\n  return ${propertyQueryExpression})`;
+}
 function buildPropertyPresenceQueryExpression(params) {
 	return buildPropertyQueryExpression({
 		propertyVariable: params.propertyVariable,
@@ -2462,14 +2503,15 @@ function buildPropertyPresenceQueryExpression(params) {
 }
 function buildPropertyStringQueryExpression(params) {
 	const { propertyVariable, value, matchMode, isCaseSensitive, language } = params;
-	return buildPropertyQueryExpression({
+	return buildPropertyTextMatchQueryExpression({
 		propertyVariable,
-		queryExpression: buildNestedElementQuery(["value"], buildAndCtsQueryExpressionInternal([buildValueNotInheritedQuery(), buildValueContentInnerQuery({
+		valueFilters: [buildValueNotInheritedQuery()],
+		contentQueryExpression: buildValueContentInnerQuery({
 			language,
 			value,
 			matchMode,
 			isCaseSensitive
-		})]))
+		})
 	});
 }
 function buildPropertyScalarQueryExpression(params) {
@@ -2489,34 +2531,25 @@ function buildPropertyScalarQueryExpression(params) {
 }
 function buildPropertyAllQueryExpression(params) {
 	const { query, value, matchMode } = params;
-	if (matchMode === "includes") return buildPropertyQueryExpression({
-		propertyVariable: query.propertyVariable,
-		queryExpression: buildNestedElementQuery(["value"], buildAndCtsQueryExpressionInternal([buildValueNotIdRefQuery(), buildOrCtsQueryExpressionInternal([
-			buildValueContentInnerQuery({
-				language: query.language,
-				value,
-				matchMode,
-				isCaseSensitive: query.isCaseSensitive
-			}),
-			buildValueRawValueInnerQuery({
-				value,
-				matchMode,
-				isCaseSensitive: query.isCaseSensitive
-			}),
-			buildValueDirectTextInnerQuery({
-				value,
-				matchMode,
-				isCaseSensitive: query.isCaseSensitive
-			})
-		])]))
-	});
-	return buildPropertyQueryExpression({
+	return buildPropertyTextMatchQueryExpression({
 		propertyVariable: query.propertyVariable,
-		queryExpression: buildNestedElementQuery(["value"], buildAndCtsQueryExpressionInternal([buildValueNotIdRefQuery(), buildCtsWordQueryExpression({
+		valueFilters: [buildValueNotIdRefQuery()],
+		contentQueryExpression: buildValueContentInnerQuery({
+			language: query.language,
 			value,
 			matchMode,
 			isCaseSensitive: query.isCaseSensitive
-		})]))
+		}),
+		rawValueQueryExpression: buildValueRawValueInnerQuery({
+			value,
+			matchMode,
+			isCaseSensitive: query.isCaseSensitive
+		}),
+		bareValueQueryExpression: buildValueDirectTextInnerQuery({
+			value,
+			matchMode,
+			isCaseSensitive: query.isCaseSensitive
+		})
 	});
 }
 function buildPropertyIdRefQueryExpression(params) {
@@ -2623,35 +2656,181 @@ function buildLeafValueQueryExpression(params) {
 		}
 	}
 }
-function buildLeafQueryExpression(query) {
+function indentBlock(value, spaces) {
+	const prefix = " ".repeat(spaces);
+	return value.split("\n").map((line) => line === "" ? line : `${prefix}${line}`).join("\n");
+}
+function createQueryCompilerContext() {
+	return {
+		nextHelperSerial: 1,
+		helperNamesByKey: /* @__PURE__ */ new Map(),
+		helperDeclarations: []
+	};
+}
+function registerConstantHelper(params) {
+	const { context, key, bodyExpression } = params;
+	const existingName = context.helperNamesByKey.get(key);
+	if (existingName != null) return {
+		name: existingName,
+		callExpression: `${existingName}()`
+	};
+	const helperName = `local:queryHelper${context.nextHelperSerial}`;
+	context.nextHelperSerial += 1;
+	context.helperNamesByKey.set(key, helperName);
+	context.helperDeclarations.push(`declare function ${helperName}() as cts:query {\n${indentBlock(bodyExpression, 2)}\n};`);
+	return {
+		name: helperName,
+		callExpression: `${helperName}()`
+	};
+}
+function replaceSampleValueLiteral(expression, sampleValue, valueReference) {
+	return expression.replaceAll(stringLiteral(sampleValue), valueReference);
+}
+function registerParameterizedHelper(params) {
+	const { context, key, bodyExpression } = params;
+	const existingName = context.helperNamesByKey.get(key);
+	if (existingName != null) return {
+		name: existingName,
+		call: (valueExpression) => `${existingName}(${valueExpression})`
+	};
+	const helperName = `local:queryHelper${context.nextHelperSerial}`;
+	context.nextHelperSerial += 1;
+	context.helperNamesByKey.set(key, helperName);
+	context.helperDeclarations.push(`declare function ${helperName}($value as xs:string) as cts:query {\n${indentBlock(bodyExpression, 2)}\n};`);
+	return {
+		name: helperName,
+		call: (valueExpression) => `${helperName}(${valueExpression})`
+	};
+}
+function getLeafHelperKey(params) {
+	const { query, matchMode, value } = params;
+	switch (query.target) {
+		case "string":
+		case "title":
+		case "description":
+		case "image":
+		case "periods":
+		case "bibliography":
+		case "notes": return [
+			"leaf",
+			matchMode,
+			query.target,
+			value,
+			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
+			query.language
+		].join("|");
+		case "property": return [
+			"leaf",
+			matchMode,
+			query.target,
+			query.dataType,
+			query.propertyVariable ?? "",
+			value,
+			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
+			query.language
+		].join("|");
+	}
+}
+function registerLeafHelper(params) {
+	const { context, query, matchMode, value } = params;
+	return registerConstantHelper({
+		context,
+		key: getLeafHelperKey({
+			query,
+			matchMode,
+			value
+		}),
+		bodyExpression: buildLeafValueQueryExpression({
+			query,
+			value,
+			matchMode
+		})
+	});
+}
+function getIncludesLeafHelperKey(params) {
+	const { query, value } = params;
+	const isWildcarded = hasWildcardCharacters(value);
+	const isStemmed = !isWildcarded && shouldUseStemmedTextSearch(value);
+	switch (query.target) {
+		case "string":
+		case "title":
+		case "description":
+		case "image":
+		case "periods":
+		case "bibliography":
+		case "notes": return [
+			"includes-helper",
+			query.target,
+			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
+			query.language,
+			isWildcarded ? "wildcarded" : "unwildcarded",
+			isStemmed ? "stemmed" : "unstemmed"
+		].join("|");
+		case "property": return [
+			"includes-helper",
+			query.target,
+			query.dataType,
+			query.propertyVariable ?? "",
+			query.isCaseSensitive ? "case-sensitive" : "case-insensitive",
+			query.language,
+			isWildcarded ? "wildcarded" : "unwildcarded",
+			isStemmed ? "stemmed" : "unstemmed"
+		].join("|");
+	}
+}
+function registerIncludesLeafHelper(params) {
+	const { context, query, sampleValue } = params;
+	return registerParameterizedHelper({
+		context,
+		key: getIncludesLeafHelperKey({
+			query,
+			value: sampleValue
+		}),
+		bodyExpression: replaceSampleValueLiteral(buildLeafValueQueryExpression({
+			query,
+			value: sampleValue,
+			matchMode: "includes"
+		}), sampleValue, "$value")
+	});
+}
+function buildLeafQueryExpression(context, query) {
 	if (query.target === "property" && query.dataType !== "date" && query.dataType !== "dateTime" && !("value" in query) && query.propertyVariable != null) return buildPropertyPresenceQueryExpression({ propertyVariable: query.propertyVariable });
 	if (query.target === "property" && (query.dataType === "date" || query.dataType === "dateTime") && query.value == null) return buildPropertyDateRangeQueryExpression(query);
 	const searchValue = getLeafSearchValue(query);
 	if (searchValue == null) throw new Error("Missing searchable value for query leaf");
-	if (query.matchMode === "exact") return buildLeafValueQueryExpression({
+	const exactHelper = registerLeafHelper({
+		context,
 		query,
-		value: searchValue,
-		matchMode: "exact"
+		matchMode: "exact",
+		value: searchValue
 	});
+	if (query.matchMode === "exact") return exactHelper.callExpression;
 	const terms = tokenizeIncludesSearchValue({
 		value: searchValue,
 		isCaseSensitive: query.isCaseSensitive
 	});
-	const fullValueQueryExpression = buildLeafValueQueryExpression({
-		query,
-		value: searchValue,
-		matchMode: "exact"
-	});
 	if (terms.length === 0) return "cts:false-query()";
-	const termQueryExpressions = [];
-	for (const term of terms) termQueryExpressions.push(buildLeafValueQueryExpression({
+	const includesHelper = registerIncludesLeafHelper({
+		context,
 		query,
-		value: term,
-		matchMode: "includes"
-	}));
-	const tokenizedQueryExpression = buildAndCtsQueryExpressionInternal(termQueryExpressions);
-	if (terms.length === 1) return tokenizedQueryExpression;
-	return buildOrCtsQueryExpressionInternal([fullValueQueryExpression, tokenizedQueryExpression]);
+		sampleValue: terms[0] ?? ""
+	});
+	const tokenizedHelperCalls = [];
+	for (const term of terms) {
+		const termHelper = term === (terms[0] ?? "") ? includesHelper : registerIncludesLeafHelper({
+			context,
+			query,
+			sampleValue: term
+		});
+		tokenizedHelperCalls.push(termHelper.call(stringLiteral(term)));
+	}
+	const tokenizedQueryExpression = buildAndCtsQueryExpressionInternal(tokenizedHelperCalls);
+	if (!shouldUseFullValueFallbackForIncludes({
+		value: searchValue,
+		isCaseSensitive: query.isCaseSensitive,
+		terms
+	})) return tokenizedQueryExpression;
+	return buildOrCtsQueryExpressionInternal([exactHelper.callExpression, tokenizedQueryExpression]);
 }
 function getGroupableIncludesValue(query) {
 	if (query.matchMode !== "includes" || query.isNegated === true) return null;
@@ -2691,21 +2870,7 @@ function getCompatibleIncludesGroupLeaves(query) {
 	for (const leafQuery of leafQueries) if (getGroupableIncludesValue(leafQuery) !== groupValue || leafQuery.isCaseSensitive !== firstQuery.isCaseSensitive || leafQuery.language !== firstQuery.language) return null;
 	return leafQueries;
 }
-function buildIncludesGroupMember(query) {
-	return {
-		buildTermQuery: (term) => buildLeafValueQueryExpression({
-			query,
-			value: term,
-			matchMode: "includes"
-		}),
-		buildFullValueQuery: (value) => buildLeafValueQueryExpression({
-			query,
-			value,
-			matchMode: "exact"
-		})
-	};
-}
-function buildIncludesGroupQueryExpression(queries) {
+function buildIncludesGroupQueryExpression(context, queries) {
 	const firstQuery = queries[0];
 	if (firstQuery == null) throw new Error("Cannot build an includes group without queries");
 	const groupValue = getGroupableIncludesValue(firstQuery);
@@ -2715,28 +2880,56 @@ function buildIncludesGroupQueryExpression(queries) {
 		isCaseSensitive: firstQuery.isCaseSensitive
 	});
 	if (terms.length === 0) return "cts:false-query()";
-	const members = queries.map((query) => buildIncludesGroupMember(query));
-	const perTermQueryExpressions = [];
-	const fullValueFieldQueryExpressions = [];
-	for (const member of members) fullValueFieldQueryExpressions.push(member.buildFullValueQuery(groupValue));
+	const tokenizedHelperCalls = [];
 	for (const term of terms) {
-		const fieldQueryExpressions = [];
-		for (const member of members) fieldQueryExpressions.push(member.buildTermQuery(term));
-		perTermQueryExpressions.push(buildOrCtsQueryExpressionInternal(fieldQueryExpressions));
+		const memberHelpers = queries.map((query) => registerIncludesLeafHelper({
+			context,
+			query,
+			sampleValue: term
+		}));
+		const termGroupHelper = registerParameterizedHelper({
+			context,
+			key: [
+				"group",
+				"includes",
+				...memberHelpers.map((helper) => helper.name)
+			].join("|"),
+			bodyExpression: buildOrCtsQueryExpressionInternal(memberHelpers.map((helper) => helper.call("$value")))
+		});
+		tokenizedHelperCalls.push(termGroupHelper.call(stringLiteral(term)));
 	}
-	const tokenizedGroupQueryExpression = buildAndCtsQueryExpressionInternal(perTermQueryExpressions);
-	if (terms.length === 1) return tokenizedGroupQueryExpression;
-	return buildOrCtsQueryExpressionInternal([buildOrCtsQueryExpressionInternal(fullValueFieldQueryExpressions), tokenizedGroupQueryExpression]);
-}
-function buildQueryNode(query) {
+	const tokenizedQueryExpression = buildAndCtsQueryExpressionInternal(tokenizedHelperCalls);
+	if (!shouldUseFullValueFallbackForIncludes({
+		value: groupValue,
+		isCaseSensitive: firstQuery.isCaseSensitive,
+		terms
+	})) return tokenizedQueryExpression;
+	const exactMemberHelpers = queries.map((query) => registerLeafHelper({
+		context,
+		query,
+		matchMode: "exact",
+		value: groupValue
+	}));
+	return buildOrCtsQueryExpressionInternal([registerConstantHelper({
+		context,
+		key: [
+			"group",
+			"exact",
+			groupValue,
+			...exactMemberHelpers.map((helper) => helper.name)
+		].join("|"),
+		bodyExpression: buildOrCtsQueryExpressionInternal(exactMemberHelpers.map((helper) => helper.callExpression))
+	}).callExpression, tokenizedQueryExpression]);
+}
+function buildQueryNode(context, query) {
 	if (isQueryLeaf(query)) {
-		const queryExpression = buildLeafQueryExpression(query);
+		const queryExpression = buildLeafQueryExpression(context, query);
 		return query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression;
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
-	if (optimizedIncludesGroupQueries != null) return buildIncludesGroupQueryExpression(optimizedIncludesGroupQueries);
+	if (optimizedIncludesGroupQueries != null) return buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries);
 	const childQueryExpressions = [];
-	for (const childQuery of getQueryGroupChildren(query)) childQueryExpressions.push(buildQueryNode(childQuery));
+	for (const childQuery of getQueryGroupChildren(query)) childQueryExpressions.push(buildQueryNode(context, childQuery));
 	return getQueryGroupOperator(query) === "and" ? buildAndCtsQueryExpressionInternal(childQueryExpressions) : buildOrCtsQueryExpressionInternal(childQueryExpressions);
 }
 function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, belongsToCollectionPropertyVariableUuid) {
@@ -2754,8 +2947,16 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 }
 function buildQueryPlan(params) {
 	const { queries } = params;
-	if (queries == null) return { queryExpression: null };
-	return { queryExpression: buildQueryNode(queries) };
+	if (queries == null) return {
+		prolog: "",
+		queryExpression: null
+	};
+	const context = createQueryCompilerContext();
+	const queryExpression = buildQueryNode(context, queries);
+	return {
+		prolog: context.helperDeclarations.join("\n\n"),
+		queryExpression
+	};
 }
 //#endregion
 //#region src/utils/fetchers/set/items.ts
@@ -2844,8 +3045,8 @@ function buildOrderedItemsClause(sort) {
 function buildXQuery$1(params) {
 	const { queries, sort, setScopeUuids, belongsToCollectionScopeUuids, page, pageSize } = params;
 	const startPosition = (page - 1) * pageSize + 1;
-	const endPosition = page * pageSize;
-	const baseItemsExpression = `doc()/ochre${`/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items/*`}`;
+	const setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
+	const baseItemsExpression = "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
 	const compiledQueryPlan = buildQueryPlan({ queries });
 	const itemsQueryExpressions = [];
 	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
@@ -2853,17 +3054,22 @@ function buildXQuery$1(params) {
 	if (belongsToCollectionQueryExpression != null) itemsQueryExpressions.push(belongsToCollectionQueryExpression);
 	const itemsQueryExpression = buildAndCtsQueryExpression(itemsQueryExpressions);
 	const orderedItemsClause = buildOrderedItemsClause(sort);
-	return `<ochre>{${`${itemsQueryExpression == null ? `let $items := ${baseItemsExpression}` : `let $items := ${baseItemsExpression}[cts:contains(., ${itemsQueryExpression})]`}
+	const xqueryDeclarations = ["xquery version \"1.0-ml\";", setScopeDeclaration];
+	if (compiledQueryPlan.prolog !== "") xqueryDeclarations.push(compiledQueryPlan.prolog);
+	const itemsClause = itemsQueryExpression == null ? `let $items := ${baseItemsExpression}` : `let $query := ${itemsQueryExpression}
+  let $items := cts:search(${baseItemsExpression}, $query)`;
+	return `${xqueryDeclarations.join("\n\n")}
 
+<ochre>{
+${itemsClause}
   let $totalCount := count($items)
   ${orderedItemsClause}
+  let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})
 
   return <items totalCount="{$totalCount}" page="${page}" pageSize="${pageSize}">{
-    for $item in $orderedItems[position() ge ${startPosition} and position() le ${endPosition}]
-      return element { node-name($item) } {
-        $item/@*, $item/node()
-      }
-  }</items>`}}</ochre>`;
+    $pagedItems
+  }</items>
+}</ochre>`;
 }
 /**
 * Fetches and parses Set items from the OCHRE API
@@ -3154,9 +3360,9 @@ const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 */
 function buildXQuery(params) {
 	const { setScopeUuids, belongsToCollectionScopeUuids, queries, propertyVariableUuids, attributes, isLimitedToLeafPropertyValues } = params;
-	let setScopeFilter = "/set/items/*";
-	if (setScopeUuids.length > 0) setScopeFilter = `/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items/*`;
-	const baseItemsExpression = `doc()/ochre${setScopeFilter}`;
+	const setScopeValues = setScopeUuids.map((uuid) => stringLiteral(uuid));
+	const setScopeDeclaration = setScopeValues.length > 0 ? `declare variable $setScopeUuids := (${setScopeValues.join(", ")});` : "";
+	const baseItemsExpression = setScopeValues.length > 0 ? "doc()/ochre/set[@uuid = $setScopeUuids]/items/*" : "doc()/ochre/set/items/*";
 	const compiledQueryPlan = buildQueryPlan({ queries: getItemFilterQueriesFromPropertyValueQueries(queries) });
 	const itemsQueryExpressions = [];
 	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
@@ -3166,6 +3372,9 @@ function buildXQuery(params) {
 	const valueFilter = isLimitedToLeafPropertyValues ? "[not(@i)]" : "";
 	const queryBlocks = [];
 	const returnedSequences = [];
+	const xqueryDeclarations = ["xquery version \"1.0-ml\";"];
+	if (setScopeDeclaration !== "") xqueryDeclarations.push(setScopeDeclaration);
+	if (compiledQueryPlan.prolog !== "") xqueryDeclarations.push(compiledQueryPlan.prolog);
 	if (propertyVariableUuids.length > 0) {
 		const propertyVariableFilters = propertyVariableUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
 		queryBlocks.push(`let $matching-props := $items//property[label[${propertyVariableFilters}]]
@@ -3198,11 +3407,16 @@ let $property-values :=
     return <attributeValue attributeType="periods" itemUuid="{$item/@uuid}" content="{$label}" />`);
 		returnedSequences.push("$period-values");
 	}
-	return `<ochre>{${`${itemsQueryExpression == null ? `let $items := ${baseItemsExpression}` : `let $items := ${baseItemsExpression}[cts:contains(., ${itemsQueryExpression})]`}
+	const itemsClause = itemsQueryExpression == null ? `let $items := ${baseItemsExpression}` : `let $query := ${itemsQueryExpression}
+  let $items := cts:search(${baseItemsExpression}, $query)`;
+	return `${xqueryDeclarations.join("\n\n")}
 
+<ochre>{
+${itemsClause}
 ${queryBlocks.join("\n\n")}
 
-return (${returnedSequences.join(", ")})`}}</ochre>`;
+return (${returnedSequences.join(", ")})
+}</ochre>`;
 }
 /**
 * Fetches and parses Set property values from the OCHRE API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "0.22.16",
+  "version": "0.22.19",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -52,7 +52,7 @@
     "@antfu/eslint-config": "^8.2.0",
     "@types/node": "^24.12.2",
     "bumpp": "^11.0.1",
-    "eslint": "^10.2.0",
+    "eslint": "^10.2.1",
     "prettier": "^3.8.3",
     "tsdown": "^0.21.9",
     "typescript": "^6.0.3",