ochre-sdk 0.20.24 → 0.20.26

package/dist/index.d.mts

@@ -675,7 +675,7 @@ type SetItemsSort = {
  */
 type Query = {
   target: "property";
-  propertyVariables: Array<string>;
+  propertyVariables?: Array<string>;
   dataType: Exclude<Exclude<PropertyValueContentType, "coordinate">, "date" | "dateTime">;
   propertyValues?: Array<string>;
   from?: never;
@@ -1268,9 +1268,9 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
   error: string;
 }>;
 //#endregion
-//#region src/utils/fetchers/set/property-values-by-property-variables.d.ts
+//#region src/utils/fetchers/set/property-values.d.ts
 /**
- * Fetches and parses Set property values by property variables from the OCHRE API
+ * Fetches and parses Set property values from the OCHRE API
  *
  * @param params - The parameters for the fetch
  * @param params.setScopeUuids - An array of set scope UUIDs to filter by
@@ -1285,7 +1285,7 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
  * @returns Parsed Set property values and requested attribute values.
  * Returns empty arrays/objects when no matches are found, and null outputs on fetch/parse errors.
  */
-declare function fetchSetPropertyValuesByPropertyVariables(params: {
+declare function fetchSetPropertyValues(params: {
   setScopeUuids: Array<string>;
   queries?: Array<Query>;
   attributes?: {
@@ -1470,4 +1470,4 @@ declare const DEFAULT_PAGE_SIZE = 48;
  */
 declare function flattenItemProperties<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(item: Item<T, U>): Item<T, U>;
 //#endregion
-export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, PropertyVariable, Query, Resource, Scope, Section, Set, SetAttributeValueQueryItem, SetItemsSort, SetItemsSortDirection, SpatialUnit, Style, Text, Tree, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebSegment, WebSegmentItem, WebTitle, Webpage, Website, WebsiteType, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, PropertyVariable, Query, Resource, Scope, Section, Set, SetAttributeValueQueryItem, SetItemsSort, SetItemsSortDirection, SpatialUnit, Style, Text, Tree, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebSegment, WebSegmentItem, WebTitle, Webpage, Website, WebsiteType, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -759,7 +759,7 @@ const boundsSchema = z.string().transform((str, ctx) => {
 const setQuerySchema = z.union([
 	z.object({
 		target: z.literal("property"),
-		propertyVariables: z.array(uuidSchema).min(1, "At least one property variable UUID is required"),
+		propertyVariables: z.array(uuidSchema).default([]),
 		dataType: z.enum([
 			"string",
 			"integer",
@@ -774,7 +774,12 @@ const setQuerySchema = z.union([
 		language: z.string().default("eng"),
 		operator: z.enum(["AND", "OR"]).optional(),
 		isNegated: z.boolean().optional().default(false)
-	}).strict(),
+	}).strict().superRefine((value, ctx) => {
+		if (value.propertyVariables.length === 0 && value.propertyValues == null) ctx.addIssue({
+			code: "custom",
+			message: "Property queries must include at least one propertyVariable or propertyValue"
+		});
+	}),
 	z.object({
 		target: z.literal("property"),
 		propertyVariables: z.array(uuidSchema).min(1, "At least one property variable UUID is required"),
@@ -861,10 +866,10 @@ function validateSetQueriesOperators(queries, ctx) {
 	});
 }
 /**
-* Schema for validating the parameters for the Set property values by property variables fetching function
+* Schema for validating the parameters for the Set property values fetching function
 * @internal
 */
-const setPropertyValuesByPropertyVariablesParamsSchema = z.object({
+const setPropertyValuesParamsSchema = z.object({
 	setScopeUuids: z.array(uuidSchema).min(1, "At least one set scope UUID is required"),
 	belongsToCollectionScopeUuids: z.array(uuidSchema).default([]),
 	queries: setQueriesSchema,
@@ -878,10 +883,10 @@ const setPropertyValuesByPropertyVariablesParamsSchema = z.object({
 	isLimitedToLeafPropertyValues: z.boolean().default(false)
 }).superRefine((value, ctx) => {
 	validateSetQueriesOperators(value.queries, ctx);
-	if (!value.queries.some((query) => query.target === "property")) ctx.addIssue({
+	if (!value.queries.some((query) => query.target === "property" && query.propertyVariables.length > 0)) ctx.addIssue({
 		code: "custom",
 		path: ["queries"],
-		message: "At least one property query is required"
+		message: "At least one property query with propertyVariables is required"
 	});
 });
 const setItemsParamsSchema = z.object({
@@ -2145,10 +2150,35 @@ const CTS_INCLUDES_STOP_WORDS = [
 	"to"
 ];
 const CTS_INCLUDES_STOP_WORDS_VAR = "$ctsIncludesStopWords";
+const CTS_INCLUDES_TOKEN_SPLIT_REGEX = /\W+/u;
+function tokenizeIncludesSearchValue(params) {
+	const { value, isCaseSensitive } = params;
+	const rawTerms = (isCaseSensitive ? value : value.toLowerCase()).split(CTS_INCLUDES_TOKEN_SPLIT_REGEX);
+	const terms = [];
+	for (const term of rawTerms) {
+		const normalizedTerm = term.toLowerCase();
+		if (normalizedTerm !== "" && !CTS_INCLUDES_STOP_WORDS.includes(normalizedTerm)) terms.push(term);
+	}
+	return terms;
+}
 function buildFlattenedContentValuesExpression(contentNodesExpression) {
 	return `for $content in ${contentNodesExpression}
     return string-join($content//text(), "")`;
 }
+function buildSearchableContentNodesExpression(contentNodesExpression) {
+	return `for $content in ${contentNodesExpression}
+    return (
+      $content//string[not(ancestor::string)],
+      $content[not(.//string)]
+    )`;
+}
+function buildCombinedSearchableContentNodesExpression(contentNodesExpressions) {
+	const searchableExpressions = [];
+	for (const contentNodesExpression of contentNodesExpressions) searchableExpressions.push(buildSearchableContentNodesExpression(contentNodesExpression));
+	if (searchableExpressions.length === 0) return "()";
+	if (searchableExpressions.length === 1) return searchableExpressions[0] ?? "()";
+	return `(${searchableExpressions.join(", ")})`;
+}
 /**
 * Build a string match predicate for an XQuery string.
 */
@@ -2174,8 +2204,7 @@ function buildCombinedRawStringMatchPredicate(params) {
 		matchMode,
 		isCaseSensitive
 	}));
-	if (predicates.length === 1) return predicates[0] ?? "false()";
-	return `(${predicates.join(" or ")})`;
+	return buildOrPredicate(predicates);
 }
 /**
 * Build CTS word-query options for API v2 includes search.
@@ -2216,44 +2245,52 @@ function buildTokenizedSearchDeclarations(params) {
 		termsVar
 	};
 }
-/**
-* Build a CTS-backed field includes predicate for an XQuery string.
-*/
-function buildCtsFieldIncludesPredicate(params) {
-	const { contentNodesExpression, valueExpression, value, isCaseSensitive, queryKey } = params;
+function buildCtsIncludesPredicate(params) {
+	const { searchableNodesExpression, fallbackValueExpression, value, isCaseSensitive, queryKey, buildCandidateTermQuery } = params;
 	const tokenizedSearchDeclarations = buildTokenizedSearchDeclarations({
 		value,
 		isCaseSensitive,
 		queryKey
 	});
-	const ctsQueryVar = `$query${queryKey}CtsQuery`;
-	const contentNodeVar = `$query${queryKey}ContentNode`;
+	const termQueriesVar = `$query${queryKey}TermQueries`;
+	const candidateQueryVar = `$query${queryKey}CandidateQuery`;
 	const fallbackPredicate = buildRawStringMatchPredicate({
-		valueExpression,
+		valueExpression: fallbackValueExpression,
 		value,
 		matchMode: "includes",
 		isCaseSensitive
 	});
+	if (tokenizeIncludesSearchValue({
+		value,
+		isCaseSensitive
+	}).length === 0) return {
+		declarations: [],
+		predicate: fallbackPredicate,
+		candidateQueryVar: null
+	};
 	return {
-		declarations: [...tokenizedSearchDeclarations.declarations, `let ${ctsQueryVar} :=
+		declarations: [
+			...tokenizedSearchDeclarations.declarations,
+			`let ${termQueriesVar} :=
+  for $term in ${tokenizedSearchDeclarations.termsVar}
+    return ${buildCandidateTermQuery("$term")}`,
+			`let ${candidateQueryVar} :=
   if (count(${tokenizedSearchDeclarations.termsVar}) = 1)
-  then ${buildCtsWordQueryExpression({
-			termExpression: `${tokenizedSearchDeclarations.termsVar}[1]`,
-			isCaseSensitive
-		})}
+  then ${termQueriesVar}[1]
   else if (count(${tokenizedSearchDeclarations.termsVar}) gt 1)
-  then cts:and-query((
-    for $term in ${tokenizedSearchDeclarations.termsVar}
-      return ${buildCtsWordQueryExpression({
+  then cts:and-query(${termQueriesVar})
+  else ()`
+		],
+		predicate: `(every $term in ${tokenizedSearchDeclarations.termsVar}
+  satisfies some $searchNode in (${searchableNodesExpression})
+    satisfies cts:contains(
+      $searchNode,
+      ${buildCtsWordQueryExpression({
 			termExpression: "$term",
 			isCaseSensitive
 		})}
-  ))
-  else ()`],
-		predicate: `(if (exists(${ctsQueryVar}))
-  then some ${contentNodeVar} in (${contentNodesExpression})
-    satisfies cts:contains(${contentNodeVar}, ${ctsQueryVar})
-  else ${fallbackPredicate})`
+    ))`,
+		candidateQueryVar
 	};
 }
 /**
@@ -2262,6 +2299,9 @@ function buildCtsFieldIncludesPredicate(params) {
 function buildItemStringSearchPaths(language) {
 	return [buildFlattenedContentValuesExpression(`identification/label/content[@xml:lang="${language}"]`), buildFlattenedContentValuesExpression(`properties//property/value[not(@inherited="true")]/content[@xml:lang="${language}"]`)];
 }
+function buildItemStringSearchableNodesExpression(language) {
+	return buildCombinedSearchableContentNodesExpression([`identification/label/content[@xml:lang="${language}"]`, `properties//property/value[not(@inherited="true")]/content[@xml:lang="${language}"]`]);
+}
 /**
 * Build the identification branch for an item-level CTS string search.
 */
@@ -2304,7 +2344,7 @@ function buildItemStringPropertyValueBranch(params) {
 /**
 * Build an item-level CTS string search predicate.
 */
-function buildItemStringSearchPredicate(params) {
+function buildItemStringSearchClause(params) {
 	const { query, version, queryKey } = params;
 	const fallbackPredicate = buildCombinedRawStringMatchPredicate({
 		valueExpressions: buildItemStringSearchPaths(query.language),
@@ -2314,55 +2354,292 @@ function buildItemStringSearchPredicate(params) {
 	});
 	if (query.matchMode !== "includes" || version !== 2) return {
 		declarations: [],
-		predicate: fallbackPredicate
+		predicate: fallbackPredicate,
+		candidateQueryVar: null
 	};
-	const tokenizedSearchDeclarations = buildTokenizedSearchDeclarations({
+	return buildCtsIncludesPredicate({
+		searchableNodesExpression: buildItemStringSearchableNodesExpression(query.language),
+		fallbackValueExpression: `(${buildItemStringSearchPaths(query.language).join(", ")})`,
 		value: query.value,
 		isCaseSensitive: query.isCaseSensitive,
+		queryKey,
+		buildCandidateTermQuery: (termExpression) => `cts:or-query((
+        ${buildItemStringIdentificationBranch({
+			termExpression,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language
+		})},
+        ${buildItemStringPropertyValueBranch({
+			termExpression,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language
+		})}
+      ))`
+	});
+}
+function buildOrPredicate(predicates) {
+	if (predicates.length === 0) return "false()";
+	if (predicates.length === 1) return predicates[0] ?? "false()";
+	return `(${predicates.join(" or ")})`;
+}
+function buildAndPredicate(predicates) {
+	if (predicates.length === 0) return "true()";
+	if (predicates.length === 1) return predicates[0] ?? "true()";
+	return `(${predicates.join(" and ")})`;
+}
+/**
+* Build a date/dateTime range predicate for an XQuery string.
+*/
+function buildDateRangePredicate(params) {
+	const { from, to } = params;
+	const conditions = [];
+	if (from != null) conditions.push(`(value/@rawValue ge ${stringLiteral(from)})`);
+	if (to != null) conditions.push(`(value/@rawValue le ${stringLiteral(to)})`);
+	return buildAndPredicate(conditions);
+}
+/**
+* Build a property label predicate for an XQuery string.
+*/
+function buildPropertyLabelPredicate(propertyVariables) {
+	const labelPredicates = [];
+	for (const propertyVariable of propertyVariables) labelPredicates.push(`@uuid=${stringLiteral(propertyVariable)}`);
+	return `label[${buildOrPredicate(labelPredicates)}]`;
+}
+function buildOrCtsQueryExpression(queries) {
+	if (queries.length === 1) return queries[0] ?? "cts:false-query()";
+	return `cts:or-query((${queries.join(", ")}))`;
+}
+function buildContentTargetCandidateBranch(params) {
+	const { containerElementName, termExpression, isCaseSensitive, language } = params;
+	return `cts:element-query(xs:QName("${containerElementName}"),
+        cts:and-query((
+          cts:element-attribute-value-query(xs:QName("content"), xs:QName("xml:lang"), ${stringLiteral(language)}),
+          ${buildCtsWordQueryExpression({
+		termExpression,
+		isCaseSensitive
+	})}
+        ))
+      )`;
+}
+function buildPropertyStringCandidateBranch(params) {
+	const { termExpression, isCaseSensitive, language } = params;
+	return `cts:element-query(xs:QName("properties"),
+        cts:element-query(xs:QName("property"),
+          cts:element-query(xs:QName("value"),
+            cts:and-query((
+              cts:not-query(cts:element-attribute-value-query(xs:QName("value"), xs:QName("inherited"), "true")),
+              cts:element-query(xs:QName("content"),
+                cts:and-query((
+                  cts:element-attribute-value-query(xs:QName("content"), xs:QName("xml:lang"), ${stringLiteral(language)}),
+                  ${buildCtsWordQueryExpression({
+		termExpression,
+		isCaseSensitive
+	})}
+                ))
+              )
+            ))
+          )
+        )
+      )`;
+}
+function getGroupableIncludesValue(query) {
+	switch (query.target) {
+		case "string":
+		case "title":
+		case "description":
+		case "image":
+		case "periods":
+		case "bibliography": return query.value;
+		case "property":
+			if (query.dataType !== "string" || query.propertyValues?.length !== 1) return null;
+			return query.propertyValues[0] ?? null;
+	}
+}
+function isCompatibleIncludesGroupQuery(params) {
+	const { query, value, isCaseSensitive, language, version } = params;
+	if (version !== 2 || query.matchMode !== "includes" || query.isNegated === true) return false;
+	const queryValue = getGroupableIncludesValue(query);
+	return queryValue != null && queryValue === value && query.isCaseSensitive === isCaseSensitive && query.language === language;
+}
+function buildContentTargetIncludesGroupMember(params) {
+	const { contentNodesExpression, value, isCaseSensitive, language, containerElementName } = params;
+	return {
+		rawPredicate: buildRawStringMatchPredicate({
+			valueExpression: buildFlattenedContentValuesExpression(contentNodesExpression),
+			value,
+			matchMode: "includes",
+			isCaseSensitive
+		}),
+		buildCandidateTermQuery: (termExpression) => buildContentTargetCandidateBranch({
+			containerElementName,
+			termExpression,
+			isCaseSensitive,
+			language
+		})
+	};
+}
+function buildItemStringIncludesGroupMember(query) {
+	return {
+		rawPredicate: buildCombinedRawStringMatchPredicate({
+			valueExpressions: buildItemStringSearchPaths(query.language),
+			value: query.value,
+			matchMode: "includes",
+			isCaseSensitive: query.isCaseSensitive
+		}),
+		buildCandidateTermQuery: (termExpression) => `cts:or-query((
+        ${buildItemStringIdentificationBranch({
+			termExpression,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language
+		})},
+        ${buildItemStringPropertyValueBranch({
+			termExpression,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language
+		})}
+      ))`
+	};
+}
+function buildPropertyStringIncludesGroupMember(query) {
+	const propertyVariables = query.propertyVariables ?? [];
+	const predicateParts = [];
+	const valueExpression = buildFlattenedContentValuesExpression(`value[not(@inherited="true")]/content[@xml:lang="${query.language}"]`);
+	const propertyValue = query.propertyValues[0] ?? "";
+	if (propertyVariables.length > 0) predicateParts.push(buildPropertyLabelPredicate(propertyVariables));
+	return {
+		rawPredicate: `.//properties//property[${buildAndPredicate([...predicateParts, buildRawStringMatchPredicate({
+			valueExpression,
+			value: propertyValue,
+			matchMode: "includes",
+			isCaseSensitive: query.isCaseSensitive
+		})])}]`,
+		buildCandidateTermQuery: (termExpression) => buildPropertyStringCandidateBranch({
+			termExpression,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language
+		})
+	};
+}
+function buildIncludesGroupMember(query) {
+	switch (query.target) {
+		case "string": return buildItemStringIncludesGroupMember(query);
+		case "title": return buildContentTargetIncludesGroupMember({
+			contentNodesExpression: `identification/label/content[@xml:lang="${query.language}"]`,
+			value: query.value,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language,
+			containerElementName: "identification"
+		});
+		case "description": return buildContentTargetIncludesGroupMember({
+			contentNodesExpression: `description/content[@xml:lang="${query.language}"]`,
+			value: query.value,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language,
+			containerElementName: "description"
+		});
+		case "periods": return buildContentTargetIncludesGroupMember({
+			contentNodesExpression: `periods/period/identification/label/content[@xml:lang="${query.language}"]`,
+			value: query.value,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language,
+			containerElementName: "period"
+		});
+		case "bibliography": return buildContentTargetIncludesGroupMember({
+			contentNodesExpression: `bibliographies/bibliography/identification/label/content[@xml:lang="${query.language}"]`,
+			value: query.value,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language,
+			containerElementName: "bibliography"
+		});
+		case "image": return buildContentTargetIncludesGroupMember({
+			contentNodesExpression: `image/identification/label/content[@xml:lang="${query.language}"]`,
+			value: query.value,
+			isCaseSensitive: query.isCaseSensitive,
+			language: query.language,
+			containerElementName: "image"
+		});
+		case "property": return buildPropertyStringIncludesGroupMember(query);
+	}
+}
+function findCompatibleIncludesGroup(params) {
+	const { queries, startIndex, version } = params;
+	const startQuery = queries[startIndex];
+	if (startQuery == null) return null;
+	const groupValue = getGroupableIncludesValue(startQuery);
+	if (groupValue == null || !isCompatibleIncludesGroupQuery({
+		query: startQuery,
+		value: groupValue,
+		isCaseSensitive: startQuery.isCaseSensitive,
+		language: startQuery.language,
+		version
+	}) || startIndex > 0 && queries[startIndex]?.operator === "AND") return null;
+	const groupedQueries = [startQuery];
+	for (let index = startIndex + 1; index < queries.length; index += 1) {
+		const query = queries[index];
+		if (query?.operator !== "OR" || !isCompatibleIncludesGroupQuery({
+			query,
+			value: groupValue,
+			isCaseSensitive: startQuery.isCaseSensitive,
+			language: startQuery.language,
+			version
+		})) break;
+		groupedQueries.push(query);
+	}
+	return groupedQueries.length > 1 ? groupedQueries : null;
+}
+function buildIncludesGroupClause(params) {
+	const { queries, queryKey } = params;
+	const firstQuery = queries[0];
+	if (firstQuery == null) throw new Error("Cannot build an includes group without queries");
+	const groupValue = getGroupableIncludesValue(firstQuery);
+	if (groupValue == null) throw new Error("Cannot build an includes group without a search value");
+	const members = queries.map((query) => buildIncludesGroupMember(query));
+	const tokenizedSearchDeclarations = buildTokenizedSearchDeclarations({
+		value: groupValue,
+		isCaseSensitive: firstQuery.isCaseSensitive,
 		queryKey
 	});
+	const tokenizedTerms = tokenizeIncludesSearchValue({
+		value: groupValue,
+		isCaseSensitive: firstQuery.isCaseSensitive
+	});
 	const termQueriesVar = `$query${queryKey}TermQueries`;
-	const ctsQueryVar = `$query${queryKey}CtsQuery`;
+	const candidateQueryVar = `$query${queryKey}CandidateQuery`;
+	if (tokenizedTerms.length === 0) return {
+		declarations: [],
+		predicate: buildOrPredicate(members.map((member) => member.rawPredicate)),
+		candidateQueryVar: null
+	};
 	return {
 		declarations: [
 			...tokenizedSearchDeclarations.declarations,
 			`let ${termQueriesVar} :=
   for $term in ${tokenizedSearchDeclarations.termsVar}
-    return
-      cts:or-query((
-        ${buildItemStringIdentificationBranch({
-				termExpression: "$term",
-				isCaseSensitive: query.isCaseSensitive,
-				language: query.language
-			})},
-        ${buildItemStringPropertyValueBranch({
-				termExpression: "$term",
-				isCaseSensitive: query.isCaseSensitive,
-				language: query.language
-			})}
-      ))`,
-			`let ${ctsQueryVar} :=
+    return ${buildOrCtsQueryExpression(members.map((member) => member.buildCandidateTermQuery("$term")))}`,
+			`let ${candidateQueryVar} :=
   if (count(${tokenizedSearchDeclarations.termsVar}) = 1)
   then ${termQueriesVar}[1]
   else if (count(${tokenizedSearchDeclarations.termsVar}) gt 1)
   then cts:and-query(${termQueriesVar})
   else ()`
 		],
-		predicate: `(if (exists(${ctsQueryVar})) then cts:contains(., ${ctsQueryVar}) else ${fallbackPredicate})`
+		predicate: `cts:contains(., ${candidateQueryVar})`,
+		candidateQueryVar
 	};
 }
 /**
 * Build a string match predicate for an XQuery string.
 */
-function buildStringMatchPredicate(params) {
-	const { contentNodesExpression, value, matchMode, isCaseSensitive, version, queryKey } = params;
+function buildStringMatchClause(params) {
+	const { contentNodesExpression, value, matchMode, isCaseSensitive, version, queryKey, buildCandidateTermQuery } = params;
 	const valueExpression = buildFlattenedContentValuesExpression(contentNodesExpression);
-	if (matchMode === "includes" && version === 2) return buildCtsFieldIncludesPredicate({
-		contentNodesExpression,
-		valueExpression,
+	if (matchMode === "includes" && version === 2 && buildCandidateTermQuery != null) return buildCtsIncludesPredicate({
+		searchableNodesExpression: buildSearchableContentNodesExpression(contentNodesExpression),
+		fallbackValueExpression: valueExpression,
 		value,
 		isCaseSensitive,
-		queryKey
+		queryKey,
+		buildCandidateTermQuery
 	});
 	return {
 		declarations: [],
@@ -2371,70 +2648,67 @@ function buildStringMatchPredicate(params) {
 			value,
 			matchMode,
 			isCaseSensitive
-		})
+		}),
+		candidateQueryVar: null
 	};
 }
-function buildOrPredicate(predicates) {
-	if (predicates.length === 1) return predicates[0] ?? "false()";
-	return `(${predicates.join(" or ")})`;
-}
-function buildAndPredicate(predicates) {
-	if (predicates.length === 1) return predicates[0] ?? "false()";
-	return `(${predicates.join(" and ")})`;
-}
-/**
-* Build a date/dateTime range predicate for an XQuery string.
-*/
-function buildDateRangePredicate(params) {
-	const { from, to } = params;
-	const conditions = [];
-	if (from != null) conditions.push(`(value/@rawValue ge ${stringLiteral(from)})`);
-	if (to != null) conditions.push(`(value/@rawValue le ${stringLiteral(to)})`);
-	return conditions.join(" and ");
-}
-/**
-* Build a property label predicate for an XQuery string.
-*/
-function buildPropertyLabelPredicate(propertyVariables) {
-	const labelPredicates = [];
-	for (const propertyVariable of propertyVariables) labelPredicates.push(`@uuid=${stringLiteral(propertyVariable)}`);
-	return `label[${buildOrPredicate(labelPredicates)}]`;
-}
 function buildPropertyValueAttributePredicate(params) {
 	const { propertyValues, attributeName } = params;
 	const valuePredicates = [];
 	for (const propertyValue of propertyValues) valuePredicates.push(`value[@${attributeName}=${stringLiteral(propertyValue)}]`);
 	return buildOrPredicate(valuePredicates);
 }
-function buildPropertyStringValuePredicate(params) {
+function buildPropertyStringValueClause(params) {
 	const { query, version, queryKey } = params;
 	const propertyContentNodesExpression = query.matchMode === "includes" && version === 2 ? `value[not(@inherited="true")]/content[@xml:lang="${query.language}"]` : `value/content[@xml:lang="${query.language}"]`;
 	const declarations = [];
 	const valuePredicates = [];
+	const candidateQueryVars = [];
 	for (const [propertyValueIndex, propertyValue] of query.propertyValues.entries()) {
-		const compiledStringPredicate = buildStringMatchPredicate({
+		const compiledStringClause = buildStringMatchClause({
 			contentNodesExpression: propertyContentNodesExpression,
 			value: propertyValue,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive,
 			version,
-			queryKey: `${queryKey}_${propertyValueIndex + 1}`
+			queryKey: `${queryKey}_${propertyValueIndex + 1}`,
+			buildCandidateTermQuery: (termExpression) => buildPropertyStringCandidateBranch({
+				termExpression,
+				isCaseSensitive: query.isCaseSensitive,
+				language: query.language
+			})
 		});
-		declarations.push(...compiledStringPredicate.declarations);
-		valuePredicates.push(compiledStringPredicate.predicate);
+		declarations.push(...compiledStringClause.declarations);
+		valuePredicates.push(compiledStringClause.predicate);
+		if (compiledStringClause.candidateQueryVar != null) candidateQueryVars.push(compiledStringClause.candidateQueryVar);
+	}
+	let candidateQueryVar = null;
+	if (candidateQueryVars.length > 0) {
+		const candidateQueriesExpression = `(${candidateQueryVars.join(", ")})`;
+		candidateQueryVar = `$query${queryKey}CandidateQuery`;
+		declarations.push(`let ${candidateQueryVar} :=
+  if (count(${candidateQueriesExpression}) = 1)
+  then ${candidateQueriesExpression}[1]
+  else if (count(${candidateQueriesExpression}) gt 1)
+  then cts:or-query(${candidateQueriesExpression})
+  else ()`);
 	}
 	return {
 		declarations,
-		predicate: buildOrPredicate(valuePredicates)
+		predicate: buildOrPredicate(valuePredicates),
+		candidateQueryVar
 	};
 }
 /**
 * Build a property predicate for an XQuery string.
 */
-function buildPropertyPredicate(params) {
+function buildPropertyClause(params) {
 	const { query, version, queryKey } = params;
-	const predicateParts = [buildPropertyLabelPredicate(query.propertyVariables)];
+	const predicateParts = [];
 	const declarations = [];
+	const propertyVariables = query.propertyVariables ?? [];
+	let candidateQueryVar = null;
+	if (propertyVariables.length > 0) predicateParts.push(buildPropertyLabelPredicate(propertyVariables));
 	if (query.dataType === "date" || query.dataType === "dateTime") predicateParts.push(buildDateRangePredicate({
 		from: query.from,
 		to: query.to
@@ -2456,73 +2730,105 @@ function buildPropertyPredicate(params) {
 			}));
 			break;
 		case "string": {
-			const compiledStringPredicate = buildPropertyStringValuePredicate({
+			const compiledStringClause = buildPropertyStringValueClause({
 				query,
 				version,
 				queryKey
 			});
-			declarations.push(...compiledStringPredicate.declarations);
-			predicateParts.push(compiledStringPredicate.predicate);
+			declarations.push(...compiledStringClause.declarations);
+			predicateParts.push(compiledStringClause.predicate);
+			candidateQueryVar = compiledStringClause.candidateQueryVar;
 			break;
 		}
 	}
 	return {
 		declarations,
-		predicate: `.//properties//property[${buildAndPredicate(predicateParts)}]`
+		predicate: `.//properties//property[${buildAndPredicate(predicateParts)}]`,
+		candidateQueryVar
 	};
 }
 /**
 * Build a query predicate for an XQuery string.
 */
-function buildQueryPredicate(params) {
+function buildQueryClause(params) {
 	const { query, version, queryKey } = params;
 	switch (query.target) {
-		case "string": return buildItemStringSearchPredicate({
+		case "string": return buildItemStringSearchClause({
 			query,
 			version,
 			queryKey
 		});
-		case "title": return buildStringMatchPredicate({
+		case "title": return buildStringMatchClause({
 			contentNodesExpression: `identification/label/content[@xml:lang="${query.language}"]`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive,
 			version,
-			queryKey
+			queryKey,
+			buildCandidateTermQuery: (termExpression) => buildContentTargetCandidateBranch({
+				containerElementName: "identification",
+				termExpression,
+				isCaseSensitive: query.isCaseSensitive,
+				language: query.language
+			})
 		});
-		case "description": return buildStringMatchPredicate({
+		case "description": return buildStringMatchClause({
 			contentNodesExpression: `description/content[@xml:lang="${query.language}"]`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive,
 			version,
-			queryKey
+			queryKey,
+			buildCandidateTermQuery: (termExpression) => buildContentTargetCandidateBranch({
+				containerElementName: "description",
+				termExpression,
+				isCaseSensitive: query.isCaseSensitive,
+				language: query.language
+			})
 		});
-		case "periods": return buildStringMatchPredicate({
+		case "periods": return buildStringMatchClause({
 			contentNodesExpression: `periods/period/identification/label/content[@xml:lang="${query.language}"]`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive,
 			version,
-			queryKey
+			queryKey,
+			buildCandidateTermQuery: (termExpression) => buildContentTargetCandidateBranch({
+				containerElementName: "period",
+				termExpression,
+				isCaseSensitive: query.isCaseSensitive,
+				language: query.language
+			})
 		});
-		case "bibliography": return buildStringMatchPredicate({
+		case "bibliography": return buildStringMatchClause({
 			contentNodesExpression: `bibliographies/bibliography/identification/label/content[@xml:lang="${query.language}"]`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive,
 			version,
-			queryKey
+			queryKey,
+			buildCandidateTermQuery: (termExpression) => buildContentTargetCandidateBranch({
+				containerElementName: "bibliography",
+				termExpression,
+				isCaseSensitive: query.isCaseSensitive,
+				language: query.language
+			})
 		});
-		case "image": return buildStringMatchPredicate({
+		case "image": return buildStringMatchClause({
 			contentNodesExpression: `image/identification/label/content[@xml:lang="${query.language}"]`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive,
 			version,
-			queryKey
+			queryKey,
+			buildCandidateTermQuery: (termExpression) => buildContentTargetCandidateBranch({
+				containerElementName: "image",
+				termExpression,
+				isCaseSensitive: query.isCaseSensitive,
+				language: query.language
+			})
 		});
-		case "property": return buildPropertyPredicate({
+		case "property": return buildPropertyClause({
 			query,
 			version,
 			queryKey
@@ -2534,27 +2840,36 @@ function buildQueryPredicate(params) {
 */
 function buildBooleanQueryClause(params) {
 	const { query, version, queryKey } = params;
-	const compiledQueryPredicate = buildQueryPredicate({
+	const compiledQueryClause = buildQueryClause({
 		query,
 		version,
 		queryKey
 	});
-	const baseClause = `(${compiledQueryPredicate.predicate})`;
+	const baseClause = `(${compiledQueryClause.predicate})`;
 	return {
-		declarations: compiledQueryPredicate.declarations,
-		predicate: query.isNegated ? `not(${baseClause})` : baseClause
+		declarations: compiledQueryClause.declarations,
+		predicate: query.isNegated ? `not(${baseClause})` : baseClause,
+		candidateQueryVar: query.isNegated ? null : compiledQueryClause.candidateQueryVar
 	};
 }
-/**
-* Build query filters for an XQuery string.
-*/
-function buildQueryFilters(params) {
-	const { queries, version } = params;
+function buildQueryPlan(params) {
+	const { queries, version, baseItemsExpression } = params;
 	const declarations = [];
 	const predicateParts = [];
+	const candidateQueryVars = [];
 	let hasCtsIncludesClauses = false;
-	for (const [index, query] of queries.entries()) {
-		const compiledClause = buildBooleanQueryClause({
+	for (let index = 0; index < queries.length;) {
+		const groupedQueries = findCompatibleIncludesGroup({
+			queries,
+			startIndex: index,
+			version
+		});
+		const query = queries[index];
+		if (query == null) break;
+		const compiledClause = groupedQueries != null ? buildIncludesGroupClause({
+			queries: groupedQueries,
+			queryKey: `${index + 1}`
+		}) : buildBooleanQueryClause({
 			query,
 			version,
 			queryKey: `${index + 1}`
@@ -2563,15 +2878,33 @@ function buildQueryFilters(params) {
 			hasCtsIncludesClauses = true;
 			declarations.push(...compiledClause.declarations);
 		}
+		if (compiledClause.candidateQueryVar != null) candidateQueryVars.push(compiledClause.candidateQueryVar);
 		if (index === 0) {
 			predicateParts.push(compiledClause.predicate);
+			index += groupedQueries?.length ?? 1;
 			continue;
 		}
 		predicateParts.push(`${query.operator === "AND" ? "and" : "or"} ${compiledClause.predicate}`);
+		index += groupedQueries?.length ?? 1;
 	}
 	if (hasCtsIncludesClauses) declarations.unshift(`let ${CTS_INCLUDES_STOP_WORDS_VAR} := (${CTS_INCLUDES_STOP_WORDS.map((stopWord) => stringLiteral(stopWord)).join(", ")})`);
+	let itemsExpression = `(${baseItemsExpression})`;
+	if (candidateQueryVars.length > 0) {
+		const candidateQueriesExpression = `(${candidateQueryVars.join(", ")})`;
+		const candidateItemsQueryVar = "$candidateItemsQuery";
+		declarations.push(`let ${candidateItemsQueryVar} :=
+  if (count(${candidateQueriesExpression}) = 1)
+  then ${candidateQueriesExpression}[1]
+  else if (count(${candidateQueriesExpression}) gt 1)
+  then cts:or-query(${candidateQueriesExpression})
+  else ()`);
+		itemsExpression = `(if (exists(${candidateItemsQueryVar}))
+  then cts:search(${baseItemsExpression}, ${candidateItemsQueryVar})
+  else ${baseItemsExpression})`;
+	}
 	return {
 		declarations,
+		itemsExpression,
 		predicate: predicateParts.join(" ")
 	};
 }
@@ -2667,22 +3000,21 @@ function buildXQuery$1(params, options) {
 	const startPosition = (page - 1) * pageSize + 1;
 	const endPosition = page * pageSize;
 	const setScopeFilter = `/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items/*`;
-	const compiledQueryFilters = buildQueryFilters({
+	const compiledQueryPlan = buildQueryPlan({
 		queries,
-		version
+		version,
+		baseItemsExpression: `${version === 2 ? "doc()" : "input()"}/ochre${setScopeFilter}`
 	});
-	const queryFilterDeclarations = compiledQueryFilters.declarations.length > 0 ? `${compiledQueryFilters.declarations.join("\n")}\n\n` : "";
+	const queryFilterDeclarations = compiledQueryPlan.declarations.length > 0 ? `${compiledQueryPlan.declarations.join("\n")}\n\n` : "";
 	const filterPredicates = [];
 	if (belongsToCollectionScopeUuids.length > 0) {
 		const belongsToCollectionScopeValues = belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
 		filterPredicates.push(`.//properties[property[label/@uuid="${BELONGS_TO_COLLECTION_UUID}" and value/(${belongsToCollectionScopeValues})]]`);
 	}
-	if (compiledQueryFilters.predicate.length > 0) filterPredicates.push(`(${compiledQueryFilters.predicate})`);
+	if (compiledQueryPlan.predicate.length > 0) filterPredicates.push(`(${compiledQueryPlan.predicate})`);
 	const itemFilters = filterPredicates.length > 0 ? `[${filterPredicates.join(" and ")}]` : "";
 	const orderedItemsClause = buildOrderedItemsClause(sort);
-	return `<ochre>{${`${queryFilterDeclarations}let $items := ${version === 2 ? "doc()" : "input()"}/ochre
-        ${setScopeFilter}
-        ${itemFilters}
+	return `<ochre>{${`${queryFilterDeclarations}let $items := ${compiledQueryPlan.itemsExpression}${itemFilters}
 
   let $totalCount := count($items)
   ${orderedItemsClause}
@@ -2807,7 +3139,7 @@ async function fetchSetItems(params, itemCategories, options) {
 	}
 }
 //#endregion
-//#region src/utils/fetchers/set/property-values-by-property-variables.ts
+//#region src/utils/fetchers/set/property-values.ts
 function parsePropertyValueLabel(content) {
 	if (content == null || content === "") return null;
 	if (typeof content === "object") return parseStringContent({ content });
@@ -2883,7 +3215,7 @@ function getPropertyVariableUuidsFromQueries(queries) {
 	const propertyVariableUuids = /* @__PURE__ */ new Set();
 	for (const query of queries) {
 		if (query.target !== "property") continue;
-		for (const propertyVariableUuid of query.propertyVariables) propertyVariableUuids.add(propertyVariableUuid);
+		for (const propertyVariableUuid of query.propertyVariables ?? []) propertyVariableUuids.add(propertyVariableUuid);
 	}
 	return [...propertyVariableUuids];
 }
@@ -2944,14 +3276,14 @@ const attributeValueQueryItemSchema = z.object({
 	content: val.content != null && val.content !== "" ? val.content : null
 }));
 /**
-* Schema for the property values by property variables OCHRE API response
+* Schema for the property values OCHRE API response
 */
 const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 	propertyValue: z.union([propertyValueQueryItemSchema, z.array(propertyValueQueryItemSchema)]).optional(),
 	attributeValue: z.union([attributeValueQueryItemSchema, z.array(attributeValueQueryItemSchema)]).optional()
 }) }), z.array(z.unknown()).length(0)]) });
 /**
-* Build an XQuery string to fetch property values by property variables from the OCHRE API
+* Build an XQuery string to fetch property values from the OCHRE API
 * @param params - The parameters for the fetch
 * @param params.setScopeUuids - An array of set scope UUIDs to filter by
 * @param params.belongsToCollectionScopeUuids - An array of collection scope UUIDs to filter by
@@ -2970,17 +3302,18 @@ function buildXQuery(params, options) {
 	let setScopeFilter = "/set/items/*";
 	if (setScopeUuids.length > 0) setScopeFilter = `/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items/*`;
 	const propertyVariableFilters = getPropertyVariableUuidsFromQueries(queries).map((uuid) => `@uuid="${uuid}"`).join(" or ");
-	const compiledQueryFilters = buildQueryFilters({
+	const compiledQueryPlan = buildQueryPlan({
 		queries,
-		version
+		version,
+		baseItemsExpression: `${version === 2 ? "doc()" : "input()"}/ochre${setScopeFilter}`
 	});
-	const queryFilterDeclarations = compiledQueryFilters.declarations.length > 0 ? `${compiledQueryFilters.declarations.join("\n")}\n\n` : "";
+	const queryFilterDeclarations = compiledQueryPlan.declarations.length > 0 ? `${compiledQueryPlan.declarations.join("\n")}\n\n` : "";
 	const filterPredicates = [];
 	if (belongsToCollectionScopeUuids.length > 0) {
 		const belongsToCollectionScopeValues = belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
 		filterPredicates.push(`.//properties[property[label/@uuid="${BELONGS_TO_COLLECTION_UUID}" and value[${belongsToCollectionScopeValues}]]]`);
 	}
-	if (compiledQueryFilters.predicate.length > 0) filterPredicates.push(`(${compiledQueryFilters.predicate})`);
+	if (compiledQueryPlan.predicate.length > 0) filterPredicates.push(`(${compiledQueryPlan.predicate})`);
 	const itemFilters = filterPredicates.length > 0 ? `[${filterPredicates.join(" and ")}]` : "";
 	const queryBlocks = [`let $matching-props := $items//property[label[${propertyVariableFilters}]]
 
@@ -3011,16 +3344,14 @@ let $property-values :=
     return <attributeValue attributeType="periods" itemUuid="{$item/@uuid}" content="{$label}" />`);
 		returnedSequences.push("$period-values");
 	}
-	return `<ochre>{${`${queryFilterDeclarations}let $items := ${version === 2 ? "doc()" : "input()"}/ochre
-      ${setScopeFilter}
-      ${itemFilters}
+	return `<ochre>{${`${queryFilterDeclarations}let $items := ${compiledQueryPlan.itemsExpression}${itemFilters}
 
 ${queryBlocks.join("\n\n")}
 
 return (${returnedSequences.join(", ")})`}}</ochre>`;
 }
 /**
-* Fetches and parses Set property values by property variables from the OCHRE API
+* Fetches and parses Set property values from the OCHRE API
 *
 * @param params - The parameters for the fetch
 * @param params.setScopeUuids - An array of set scope UUIDs to filter by
@@ -3035,10 +3366,10 @@ return (${returnedSequences.join(", ")})`}}</ochre>`;
 * @returns Parsed Set property values and requested attribute values.
 * Returns empty arrays/objects when no matches are found, and null outputs on fetch/parse errors.
 */
-async function fetchSetPropertyValuesByPropertyVariables(params, options) {
+async function fetchSetPropertyValues(params, options) {
 	try {
 		const version = options?.version ?? 2;
-		const { setScopeUuids, belongsToCollectionScopeUuids, queries, attributes, isLimitedToLeafPropertyValues } = setPropertyValuesByPropertyVariablesParamsSchema.parse(params);
+		const { setScopeUuids, belongsToCollectionScopeUuids, queries, attributes, isLimitedToLeafPropertyValues } = setPropertyValuesParamsSchema.parse(params);
 		const xquery = buildXQuery({
 			setScopeUuids,
 			belongsToCollectionScopeUuids,
@@ -3100,7 +3431,7 @@ async function fetchSetPropertyValuesByPropertyVariables(params, options) {
 			propertyValues: null,
 			propertyValuesByPropertyVariableUuid: null,
 			attributeValues: null,
-			error: error instanceof Error ? error.message : "Failed to fetch property values by property variables"
+			error: error instanceof Error ? error.message : "Failed to fetch property values"
 		};
 	}
 }
@@ -4700,4 +5031,4 @@ async function fetchWebsite(abbreviation, options) {
 	}
 }
 //#endregion
-export { DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValues, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/package.json

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