ochre-sdk 1.0.78 → 1.1.0

package/dist/query.mjs

@@ -1,4 +1,6 @@
-import { stringLiteral } from "./utilities.mjs";
+import { BELONGS_TO_COLLECTION_UUID } from "./constants.mjs";
+import { compileOchreQuery, stringLiteral } from "./xquery.mjs";
+import { OCR_WORD_CONTENT_ATTRIBUTE, OCR_WORD_QNAMES, buildOcrWordPath } from "./ocr.mjs";
 //#region src/query.ts
 const CTS_INCLUDES_STOP_WORDS = /* @__PURE__ */ new Set([
 	"and",
@@ -40,6 +42,19 @@ const CONTENT_TARGET_CONTENT_ELEMENT_PATHS = {
 		"content"
 	]
 };
+const HELPER_SEARCH_VALUE_REFERENCE = "$value";
+function searchValue(text) {
+	return {
+		text,
+		expression: stringLiteral(text)
+	};
+}
+function referencedSearchValue(text) {
+	return {
+		text,
+		expression: HELPER_SEARCH_VALUE_REFERENCE
+	};
+}
 function tokenizeIncludesSearchValue(parameters) {
 	const { value, isCaseSensitive } = parameters;
 	const rawTerms = (isCaseSensitive ? value : value.toLowerCase()).match(CTS_INCLUDES_TOKEN_REGEX) ?? [];
@@ -116,9 +131,9 @@ function buildRichTextPhraseOptionsExpression(parameters) {
 }
 function buildCtsWordQueryExpression(parameters) {
 	const { value, matchMode, isCaseSensitive, queryFamily, language } = parameters;
-	const isWildcarded = matchMode === "includes" && hasWildcardCharacters(value);
-	const isStemmed = matchMode === "includes" && queryFamily === "text" && !isWildcarded && shouldUseStemmedTextSearch(value);
-	return `cts:word-query(${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
+	const isWildcarded = matchMode === "includes" && hasWildcardCharacters(value.text);
+	const isStemmed = matchMode === "includes" && queryFamily === "text" && !isWildcarded && shouldUseStemmedTextSearch(value.text);
+	return `cts:word-query(${value.expression}, ${buildWordQueryOptionsExpression({
 		matchMode,
 		isCaseSensitive,
 		queryFamily,
@@ -129,7 +144,7 @@ function buildCtsWordQueryExpression(parameters) {
 }
 function buildRichTextPhraseQueryExpression(parameters) {
 	const { value, isCaseSensitive } = parameters;
-	return `cts:word-query(${stringLiteral(value)}, ${buildRichTextPhraseOptionsExpression({ isCaseSensitive })})`;
+	return `cts:word-query(${value.expression}, ${buildRichTextPhraseOptionsExpression({ isCaseSensitive })})`;
 }
 function buildRichTextExactQueryExpression(parameters) {
 	const { value, isCaseSensitive } = parameters;
@@ -138,20 +153,20 @@ function buildRichTextExactQueryExpression(parameters) {
 		isCaseSensitive
 	});
 	const terms = tokenizeExactTextSearchValue({
-		value,
+		value: value.text,
 		isCaseSensitive
 	});
 	if (terms.length <= 1) return phraseQuery;
 	return buildOrCtsQueryExpressionInternal([phraseQuery, buildAndCtsQueryExpressionInternal(terms.map((term) => buildRichTextPhraseQueryExpression({
-		value: term,
+		value: searchValue(term),
 		isCaseSensitive
 	})))]);
 }
 function buildCtsElementWordQueryExpression(parameters) {
 	const { elementName, value, matchMode, isCaseSensitive, queryFamily, language } = parameters;
-	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)}, ${buildWordQueryOptionsExpression({
+	const isWildcarded = matchMode === "includes" && hasWildcardCharacters(value.text);
+	const isStemmed = matchMode === "includes" && queryFamily === "text" && !isWildcarded && shouldUseStemmedTextSearch(value.text);
+	return `cts:element-word-query(xs:QName("${elementName}"), ${value.expression}, ${buildWordQueryOptionsExpression({
 		matchMode,
 		isCaseSensitive,
 		queryFamily,
@@ -162,9 +177,9 @@ function buildCtsElementWordQueryExpression(parameters) {
 }
 function buildCtsElementAttributeWordQueryExpression(parameters) {
 	const { elementName, attributeName, value, matchMode, isCaseSensitive, queryFamily, language } = parameters;
-	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)}, ${buildWordQueryOptionsExpression({
+	const isWildcarded = matchMode === "includes" && hasWildcardCharacters(value.text);
+	const isStemmed = matchMode === "includes" && queryFamily === "text" && !isWildcarded && shouldUseStemmedTextSearch(value.text);
+	return `cts:element-attribute-word-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${value.expression}, ${buildWordQueryOptionsExpression({
 		matchMode,
 		isCaseSensitive,
 		queryFamily,
@@ -175,21 +190,21 @@ function buildCtsElementAttributeWordQueryExpression(parameters) {
 }
 function buildCtsElementValueQueryExpression(parameters) {
 	const { elementName, value, isCaseSensitive } = parameters;
-	return `cts:element-value-query(xs:QName("${elementName}"), ${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
+	return `cts:element-value-query(xs:QName("${elementName}"), ${value.expression}, ${buildWordQueryOptionsExpression({
 		matchMode: "exact",
 		isCaseSensitive
 	})})`;
 }
 function buildCtsElementAttributeValueQueryExpression(parameters) {
 	const { elementName, attributeName, value, isCaseSensitive } = parameters;
-	return `cts:element-attribute-value-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
+	return `cts:element-attribute-value-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${value.expression}, ${buildWordQueryOptionsExpression({
 		matchMode: "exact",
 		isCaseSensitive
 	})})`;
 }
 function buildPlainElementAttributeValueQueryExpression(parameters) {
 	const { elementName, attributeName, value } = parameters;
-	return `cts:element-attribute-value-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${stringLiteral(value)})`;
+	return `cts:element-attribute-value-query(xs:QName("${elementName}"), xs:QName("${attributeName}"), ${value.expression})`;
 }
 function buildNestedElementQuery(elementNames, queryExpression) {
 	let wrappedQueryExpression = queryExpression;
@@ -217,21 +232,21 @@ function buildContentLanguageQuery(language) {
 	return buildPlainElementAttributeValueQueryExpression({
 		elementName: "content",
 		attributeName: "xml:lang",
-		value: language
+		value: searchValue(language)
 	});
 }
 function buildPropertyLabelQuery(propertyVariable) {
 	return buildPlainElementAttributeValueQueryExpression({
 		elementName: "label",
 		attributeName: "uuid",
-		value: propertyVariable
+		value: searchValue(propertyVariable)
 	});
 }
 function buildValueNotIdReferenceQuery() {
 	return buildNotCtsQueryExpression(buildPlainElementAttributeValueQueryExpression({
 		elementName: "value",
 		attributeName: "dataType",
-		value: "IDREF"
+		value: searchValue("IDREF")
 	}));
 }
 function buildRichTextContentQueryExpression(parameters) {
@@ -327,7 +342,7 @@ function buildPropertyQueryExpression(parameters) {
 	if (propertyRelation != null) propertyQueryExpressions.unshift(buildPlainElementAttributeValueQueryExpression({
 		elementName: "label",
 		attributeName: "relation",
-		value: propertyRelation
+		value: searchValue(propertyRelation)
 	}));
 	return buildNestedElementQuery(["properties", "property"], buildAndCtsQueryExpressionInternal(propertyQueryExpressions));
 }
@@ -354,7 +369,7 @@ function buildPropertyTextMatchQueryExpression(parameters) {
 	if (propertyRelation != null) propertyQueryExpressions.push(buildPlainElementAttributeValueQueryExpression({
 		elementName: "label",
 		attributeName: "relation",
-		value: propertyRelation
+		value: searchValue(propertyRelation)
 	}));
 	propertyQueryExpressions.push(buildNestedElementQuery(["value"], buildAndCtsQueryExpressionInternal(valueQueryExpressions)));
 	const propertyQueryExpression = buildNestedElementQuery(["properties", "property"], buildAndCtsQueryExpressionInternal(propertyQueryExpressions));
@@ -472,7 +487,6 @@ function buildItemStringQueryExpression(parameters) {
 		language
 	})]);
 }
-const OCR_STRING_QNAMES = `(xs:QName("String"), fn:QName("http://www.loc.gov/standards/alto/ns-v2#", "string"))`;
 function tokenizeOcrExactValue(value) {
 	const terms = [];
 	for (const term of value.split(/\s+/u)) if (term !== "") terms.push(term);
@@ -492,12 +506,12 @@ function buildOcrWordQueryExpression(parameters) {
 		"punctuation-insensitive",
 		"whitespace-insensitive"
 	];
-	if (hasWildcardCharacters(value)) options.push("wildcarded");
-	return `cts:element-attribute-word-query(${OCR_STRING_QNAMES}, xs:QName("CONTENT"), ${stringLiteral(value)}, (${options.map((option) => stringLiteral(option)).join(", ")}))`;
+	if (hasWildcardCharacters(value.text)) options.push("wildcarded");
+	return `cts:element-attribute-word-query(${OCR_WORD_QNAMES}, xs:QName(${stringLiteral(OCR_WORD_CONTENT_ATTRIBUTE)}), ${value.expression}, (${options.map((option) => stringLiteral(option)).join(", ")}))`;
 }
 function buildOcrValueQueryExpression(parameters) {
 	const { value, isCaseSensitive } = parameters;
-	return `cts:element-attribute-value-query(${OCR_STRING_QNAMES}, xs:QName("CONTENT"), ${stringLiteral(value)}, ${buildWordQueryOptionsExpression({
+	return `cts:element-attribute-value-query(${OCR_WORD_QNAMES}, xs:QName(${stringLiteral(OCR_WORD_CONTENT_ATTRIBUTE)}), ${value.expression}, ${buildWordQueryOptionsExpression({
 		matchMode: "exact",
 		isCaseSensitive
 	})})`;
@@ -523,7 +537,7 @@ function buildOcrQueryExpression(query) {
 		const terms = tokenizeOcrExactValue(value);
 		if (terms.length === 0) return "cts:false-query()";
 		return buildNestedElementQuery(["ocr"], buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildOcrValueQueryExpression({
-			value: term,
+			value: searchValue(term),
 			isCaseSensitive
 		}))));
 	}
@@ -533,7 +547,7 @@ function buildOcrQueryExpression(query) {
 	});
 	if (terms.length === 0) return "cts:false-query()";
 	return buildNestedElementQuery(["ocr"], buildAndCtsQueryExpressionInternal(Array.from(terms, (term) => buildOcrWordQueryExpression({
-		value: term,
+		value: searchValue(term),
 		isCaseSensitive
 	}))));
 }
@@ -547,8 +561,8 @@ function registerOcrPhraseHelper(context) {
 	context.helperNamesByKey.set(helperName, helperName);
 	context.helperDeclarations.push(`declare function ${helperName}($resource as node(), $terms as xs:string*, $isCaseSensitive as xs:boolean) as xs:boolean {
   let $contents :=
-    for $word in $resource//*[lower-case(local-name(.)) = "ocr"]//*[lower-case(local-name(.)) = "string"][@CONTENT]
-    return if ($isCaseSensitive) then string($word/@CONTENT) else lower-case(string($word/@CONTENT))
+    for $word in ${buildOcrWordPath("$resource")}
+    return if ($isCaseSensitive) then string($word/@${OCR_WORD_CONTENT_ATTRIBUTE}) else lower-case(string($word/@${OCR_WORD_CONTENT_ATTRIBUTE}))
   let $needles :=
     for $term in $terms
     return if ($isCaseSensitive) then $term else lower-case($term)
@@ -578,7 +592,7 @@ function registerOcrBinding(context, query) {
 	const queryExpression = buildOcrQueryExpression(query);
 	const phraseTerms = query.matchMode === "exact" ? tokenizeOcrExactValue(query.value) : [];
 	context.ocrBindingNamesByKey.set(key, name);
-	const searchExpression = `cts:search(/ochre/resource, ${queryExpression})`;
+	const searchExpression = `cts:search(/ochre/resource, ${buildAndCtsQueryExpressionInternal([queryExpression, `cts:document-query(${context.baseItemsExpression}/@uuid/string())`])})`;
 	const phraseHelperName = phraseTerms.length > 1 ? registerOcrPhraseHelper(context) : null;
 	context.ocrBindings.push({
 		name,
@@ -664,13 +678,14 @@ function indentBlock(value, spaces) {
 	const prefix = " ".repeat(spaces);
 	return value.split("\n").map((line) => line === "" ? line : `${prefix}${line}`).join("\n");
 }
-function createQueryCompilerContext() {
+function createQueryCompilerContext(baseItemsExpression) {
 	return {
 		nextHelperSerial: 1,
 		helperNamesByKey: /* @__PURE__ */ new Map(),
 		helperDeclarations: [],
 		ocrBindingNamesByKey: /* @__PURE__ */ new Map(),
-		ocrBindings: []
+		ocrBindings: [],
+		baseItemsExpression
 	};
 }
 function registerConstantHelper(parameters) {
@@ -689,9 +704,6 @@ function registerConstantHelper(parameters) {
 		callExpression: `${helperName}()`
 	};
 }
-function replaceSampleValueLiteral(expression, sampleValue, valueReference) {
-	return expression.replaceAll(stringLiteral(sampleValue), () => valueReference);
-}
 function registerParameterizedHelper(parameters) {
 	const { context, key, bodyExpression } = parameters;
 	const existingName = context.helperNamesByKey.get(key);
@@ -749,7 +761,7 @@ function registerLeafHelper(parameters) {
 		}),
 		bodyExpression: buildLeafValueQueryExpression({
 			query,
-			value,
+			value: searchValue(value),
 			matchMode
 		})
 	});
@@ -794,11 +806,11 @@ function registerIncludesLeafHelper(parameters) {
 			query,
 			value: sampleValue
 		}),
-		bodyExpression: replaceSampleValueLiteral(buildLeafValueQueryExpression({
+		bodyExpression: buildLeafValueQueryExpression({
 			query,
-			value: sampleValue,
+			value: referencedSearchValue(sampleValue),
 			matchMode: "includes"
-		}), sampleValue, "$value")
+		})
 	});
 }
 function buildLeafQueryExpression(context, query) {
@@ -940,6 +952,23 @@ function buildCtsItemsPlan(queryExpression) {
 	};
 }
 /**
+* Plan a negated leaf as an item path predicate
+*
+* A Set holds every one of its items in one fragment, and CTS resolves
+* `cts:not-query` from the fragment indexes without filtering the match down to
+* the node it came from. Negating inside the search query would therefore drop
+* every item of a Set as soon as one of them matched, and keep every item of a
+* Set that held no match at all. `cts:contains` evaluates the leaf against one
+* item projection instead, which is the scope the negation is asking about.
+*/
+function buildNegatedItemsPlan(queryExpression) {
+	return {
+		kind: "search",
+		itemPredicates: [`[not(cts:contains(., ${queryExpression}))]`],
+		queryExpressions: []
+	};
+}
+/**
 * Splice the children of same-kind child plans into their parent, so that a
 * nested group of the same operator does not cost an extra search
 */
@@ -1021,7 +1050,7 @@ function buildItemsPlan(context, query) {
 			};
 		}
 		const queryExpression = buildLeafQueryExpression(context, query);
-		return buildCtsItemsPlan(query.isNegated === true ? buildNotCtsQueryExpression(queryExpression) : queryExpression);
+		return query.isNegated === true ? buildNegatedItemsPlan(queryExpression) : buildCtsItemsPlan(queryExpression);
 	}
 	const optimizedIncludesGroupQueries = getCompatibleIncludesGroupLeaves(query);
 	if (optimizedIncludesGroupQueries != null) return buildCtsItemsPlan(buildIncludesGroupQueryExpression(context, optimizedIncludesGroupQueries));
@@ -1055,7 +1084,7 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 		queryExpression: buildNestedElementQuery(["value"], buildOrCtsQueryExpressionInternal(Array.from(belongsToCollectionScopeUuids, (uuid) => buildPlainElementAttributeValueQueryExpression({
 			elementName: "value",
 			attributeName: "uuid",
-			value: uuid
+			value: searchValue(uuid)
 		}))))
 	});
 }
@@ -1066,9 +1095,12 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 * Most queries compile to a single `cts:search` over the Set item projections.
 * An `ocr` leaf cannot: the projections drop the `<ocr>` layer, so it resolves
 * to a search over the Resource documents whose matching UUIDs are joined back
-* in as an item path predicate. Path predicates only ever AND, so an `ocr` leaf
-* that sits under an `or` becomes its own arm of a node union instead, and one
-* that sits under an `and` alongside a union becomes an intersection.
+* in as an item path predicate. A negated leaf cannot either, because CTS
+* answers a negation for the whole fragment rather than for the item that
+* matched, so it is filtered per item instead. Path predicates only ever AND,
+* so such a leaf that sits under an `or` becomes its own arm of a node union
+* instead, and one that sits under an `and` alongside a union becomes an
+* intersection.
 *
 * The searchable path has to stay inline in `cts:search`: binding it to a
 * variable first makes every query XDMP-UNSEARCHABLE.
@@ -1078,9 +1110,34 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 * @param parameters.scopeQueryExpression - An optional CTS query ANDed into every compiled search
 * @returns The prolog declaring the query helpers, and the `let` clauses binding `$items`
 */
+const ITEMS_VARIABLE = "$items";
+const SET_SCOPE_VARIABLE = "$setScopeUuids";
+/**
+* The XQuery path a Set item search runs over
+*
+* The path has to stay inline in `cts:search`: binding it to a variable first
+* materializes the sequence and makes every query `XDMP-UNSEARCHABLE`, even a
+* plain word query. It references {@link SET_SCOPE_VARIABLE}, which
+* {@link compileSetItemsQuery} declares.
+*/
+const SET_ITEMS_EXPRESSION = `doc()/ochre/set[@uuid = ${SET_SCOPE_VARIABLE}]/items/*`;
+/**
+* Compile a query tree into the clauses that bind the matching Set items
+*
+* The returned `itemsClause` binds {@link ITEMS_VARIABLE} and has to be placed
+* inside an XQuery body, with `prolog` declared ahead of it.
+* {@link compileSetItemsQuery} does both and is what fetchers should use;
+* this is exposed for tests that assert on the compiled CTS.
+* @param parameters - The plan parameters
+* @param parameters.queries - The query tree to compile, or null to match every item
+* @param parameters.baseItemsExpression - The inline searchable path to filter
+* @param parameters.scopeQueryExpression - An extra query AND-ed into every search
+* @returns The prolog, the clauses binding the items, and the bound CTS queries
+* @internal
+*/
 function buildQueryPlan(parameters) {
 	const { queries, baseItemsExpression, scopeQueryExpression } = parameters;
-	const context = createQueryCompilerContext();
+	const context = createQueryCompilerContext(baseItemsExpression);
 	const plan = queries == null ? {
 		kind: "search",
 		itemPredicates: [],
@@ -1097,21 +1154,118 @@ function buildQueryPlan(parameters) {
 		});
 	}
 	const queryNamesByPlan = /* @__PURE__ */ new Map();
+	const queryBindings = [];
 	const letClauses = Array.from(context.ocrBindings, (binding) => `let ${binding.name} := ${binding.expression}`);
 	for (const [index, boundSearchPlan] of boundSearchPlans.entries()) {
 		const queryName = boundSearchPlans.length === 1 ? "$query" : `$query${index + 1}`;
 		queryNamesByPlan.set(boundSearchPlan.plan, queryName);
+		queryBindings.push({
+			name: queryName,
+			expression: boundSearchPlan.queryExpression
+		});
 		letClauses.push(`let ${queryName} := ${boundSearchPlan.queryExpression}`);
 	}
-	letClauses.push(`let $items := ${buildItemsPlanExpression({
+	letClauses.push(`let ${ITEMS_VARIABLE} := ${buildItemsPlanExpression({
 		plan,
 		baseItemsExpression,
 		queryNamesByPlan
 	})}`);
 	return {
 		prolog: context.helperDeclarations.join("\n\n"),
-		itemsClause: letClauses.join("\n  ")
+		itemsClause: letClauses.join("\n  "),
+		itemsVariable: ITEMS_VARIABLE,
+		queryBindings
 	};
 }
+/**
+* Compile a Set item query into a complete XQuery document
+*
+* Owns everything a caller would otherwise have to know and restate: the
+* version declaration, the Set scope variable, the supplemental-stripping
+* prolog, the inline searchable path, where the compiled helper prolog goes and
+* that it is only declared when non-empty, the `<ochre>` wrapper, and the name
+* of the variable holding the matching items. The body receives that name.
+* @param parameters - The query parameters
+* @param parameters.setScopeUuids - The Set scope UUIDs to search within
+* @param parameters.belongsToCollectionScopeUuids - Collection scope UUIDs to narrow to
+* @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
+* @returns A complete XQuery document
+* @internal
+*/
+function compileSetItemsQuery(parameters) {
+	const { setScopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body } = parameters;
+	const plan = buildQueryPlan({
+		queries,
+		baseItemsExpression: SET_ITEMS_EXPRESSION,
+		scopeQueryExpression: buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID)
+	});
+	return compileOchreQuery({
+		declarations: [
+			...declarations,
+			`declare variable ${SET_SCOPE_VARIABLE} := (${Array.from(setScopeUuids, (uuid) => stringLiteral(uuid)).join(", ")});`,
+			...plan.prolog === "" ? [] : [plan.prolog]
+		],
+		body: (context) => `<ochre>{
+${plan.itemsClause}
+${body({
+			...context,
+			items: plan.itemsVariable
+		})}
+}</ochre>`
+	});
+}
+/**
+* Reduce a property-value facet query tree to the leaves that filter items
+*
+* A facet request carries property leaves that name a variable without naming
+* a value, which select what to aggregate rather than which items to keep.
+* Those are dropped, and groups left with a single child collapse into it.
+* @param queries - The query tree to reduce
+* @returns The reduced tree, or null when nothing filters items
+* @internal
+*/
+function getItemFilterQueries(queries) {
+	if (queries == null) return null;
+	if (isQueryLeaf(queries)) {
+		if (queries.target !== "property" || queries.dataType === "date" || queries.dataType === "dateTime") return queries;
+		return "value" in queries && queries.value != null ? queries : null;
+	}
+	const filteredChildren = [];
+	for (const childQuery of getQueryGroupChildren(queries)) {
+		const filteredChildQuery = getItemFilterQueries(childQuery);
+		if (filteredChildQuery != null) filteredChildren.push(filteredChildQuery);
+	}
+	if (filteredChildren.length <= 1) return filteredChildren[0] ?? null;
+	return getQueryGroupOperator(queries) === "and" ? { and: filteredChildren } : { or: filteredChildren };
+}
+/**
+* Collect the property variables a query tree asks to be aggregated
+* @param queries - The query tree to walk
+* @returns One selector per distinct property variable and relation pair
+* @internal
+*/
+function getPropertyFacetSelectors(queries) {
+	if (queries == null) return [];
+	const selectors = /* @__PURE__ */ new Map();
+	const pendingQueries = [queries];
+	while (pendingQueries.length > 0) {
+		const query = pendingQueries.shift();
+		if (query == null) continue;
+		if (isQueryLeaf(query)) {
+			if (query.target === "property" && query.propertyVariable != null) {
+				const relation = query.propertyRelation ?? null;
+				selectors.set(`${query.propertyVariable}|${relation}`, {
+					uuid: query.propertyVariable,
+					relation
+				});
+			}
+			continue;
+		}
+		pendingQueries.push(...getQueryGroupChildren(query));
+	}
+	return selectors.values().toArray();
+}
 //#endregion
-export { buildBelongsToCollectionQueryExpression, buildQueryPlan };
+export { buildBelongsToCollectionQueryExpression, buildQueryPlan, compileSetItemsQuery, getItemFilterQueries, getPropertyFacetSelectors };

package/dist/reflection.d.mts

@@ -0,0 +1,64 @@
+//#region src/reflection.d.ts
+/**
+ * Reading values whose shape is not known at compile time
+ *
+ * The SDK used to do this with five copies of a
+ * `value is Record<string, unknown>` predicate over
+ * `typeof value === "object" && value != null`. That predicate lies three ways:
+ * it is true for arrays, `Date`, `Map` and every other object; it claims a
+ * string index signature the value does not have, so every read produces
+ * `unknown` and callers add a second cast to get anything out of it; and being
+ * an `&&` of unrelated checks, its `false` branch does not mean "not a record",
+ * which is what a type predicate promises.
+ *
+ * These take `unknown` and hand back `unknown`. They assert nothing they have
+ * not checked, so the one unavoidable cast at the boundary lives here instead
+ * of being repeated at every call site. Where the shape *is* known, validate it
+ * with a valibot schema and `v.is` rather than reaching for these.
+ */
+/**
+ * Whether a value is a non-null object
+ *
+ * Narrows to `object`, which is honest: arrays, `Date` and class instances are
+ * objects too. Callers that need to tell them apart still have to ask.
+ * @param value - The value to test
+ * @returns True when the value is a non-null object
+ * @internal
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Read one property from a value of unknown shape
+ *
+ * Uses `Reflect.get`, so there is no cast: a missing property, a non-object and
+ * a property holding `undefined` are all `undefined`, and the caller has to
+ * narrow whatever comes back.
+ * @param value - The value to read from
+ * @param key - The property to read
+ * @returns The property value, or undefined when there is none
+ * @internal
+ */
+export declare function readProperty(value: unknown, key: PropertyKey): unknown;
+/**
+ * Read the own enumerable string-keyed entries of a value of unknown shape
+ * @param value - The value to read from
+ * @returns The entries, or an empty array when the value is not an object
+ * @internal
+ */
+export declare function readEntries(value: unknown): Array<[string, unknown]>;
+/**
+ * Read a property that should hold an array, from a value of unknown shape
+ * @param value - The value to read from
+ * @param key - The property to read
+ * @returns The array, or an empty array when the property is absent or not one
+ * @internal
+ */
+export declare function readArrayProperty(value: unknown, key: PropertyKey): ReadonlyArray<unknown>;
+/**
+ * Read a property that should hold a string, from a value of unknown shape
+ * @param value - The value to read from
+ * @param key - The property to read
+ * @returns The string, or null when the property is absent or not one
+ * @internal
+ */
+export declare function readStringProperty(value: unknown, key: PropertyKey): string | null;
+//#endregion

package/dist/reflection.mjs

@@ -0,0 +1,79 @@
+//#region src/reflection.ts
+/**
+* Reading values whose shape is not known at compile time
+*
+* The SDK used to do this with five copies of a
+* `value is Record<string, unknown>` predicate over
+* `typeof value === "object" && value != null`. That predicate lies three ways:
+* it is true for arrays, `Date`, `Map` and every other object; it claims a
+* string index signature the value does not have, so every read produces
+* `unknown` and callers add a second cast to get anything out of it; and being
+* an `&&` of unrelated checks, its `false` branch does not mean "not a record",
+* which is what a type predicate promises.
+*
+* These take `unknown` and hand back `unknown`. They assert nothing they have
+* not checked, so the one unavoidable cast at the boundary lives here instead
+* of being repeated at every call site. Where the shape *is* known, validate it
+* with a valibot schema and `v.is` rather than reaching for these.
+*/
+/**
+* Whether a value is a non-null object
+*
+* Narrows to `object`, which is honest: arrays, `Date` and class instances are
+* objects too. Callers that need to tell them apart still have to ask.
+* @param value - The value to test
+* @returns True when the value is a non-null object
+* @internal
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Read one property from a value of unknown shape
+*
+* Uses `Reflect.get`, so there is no cast: a missing property, a non-object and
+* a property holding `undefined` are all `undefined`, and the caller has to
+* narrow whatever comes back.
+* @param value - The value to read from
+* @param key - The property to read
+* @returns The property value, or undefined when there is none
+* @internal
+*/
+function readProperty(value, key) {
+	if (!isObject(value)) return;
+	return Reflect.get(value, key);
+}
+/**
+* Read the own enumerable string-keyed entries of a value of unknown shape
+* @param value - The value to read from
+* @returns The entries, or an empty array when the value is not an object
+* @internal
+*/
+function readEntries(value) {
+	if (!isObject(value)) return [];
+	return Object.entries(value);
+}
+/**
+* Read a property that should hold an array, from a value of unknown shape
+* @param value - The value to read from
+* @param key - The property to read
+* @returns The array, or an empty array when the property is absent or not one
+* @internal
+*/
+function readArrayProperty(value, key) {
+	const property = readProperty(value, key);
+	return Array.isArray(property) ? property : [];
+}
+/**
+* Read a property that should hold a string, from a value of unknown shape
+* @param value - The value to read from
+* @param key - The property to read
+* @returns The string, or null when the property is absent or not one
+* @internal
+*/
+function readStringProperty(value, key) {
+	const property = readProperty(value, key);
+	return typeof property === "string" ? property : null;
+}
+//#endregion
+export { isObject, readArrayProperty, readEntries, readProperty, readStringProperty };

package/dist/schemas.d.mts

@@ -1,6 +1,13 @@
 import { Query } from "./types/index.mjs";
 import * as v from "valibot";
 //#region src/schemas.d.ts
+/**
+ * Validates a pseudo-UUID string
+ * @param value - The string to validate
+ * @returns True if the string is a valid pseudo-UUID, false otherwise
+ * @internal
+ */
+export declare function isPseudoUuid(value: string): boolean;
 /**
  * Schema for validating UUIDs
  * @internal

package/dist/schemas.mjs

@@ -1,7 +1,16 @@
-import { isPseudoUuid } from "./utilities.mjs";
-import "./helpers.mjs";
+import "./constants.mjs";
 import * as v from "valibot";
 //#region src/schemas.ts
+const PSEUDO_UUID_REGEX = /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i;
+/**
+* Validates a pseudo-UUID string
+* @param value - The string to validate
+* @returns True if the string is a valid pseudo-UUID, false otherwise
+* @internal
+*/
+function isPseudoUuid(value) {
+	return PSEUDO_UUID_REGEX.test(value);
+}
 const positiveNumber = (message) => v.pipe(v.number(), v.minValue(1, message));
 const defaultString = (value) => v.optional(v.string(), value);
 const defaultBoolean = (value) => v.optional(v.boolean(), value);
@@ -243,4 +252,4 @@ const setItemsParametersSchema = v.object({
 	pageSize: v.optional(positiveNumber("Page size must be positive"), 48)
 });
 //#endregion
-export { componentSchema, gallerySchema, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, isPseudoUuid, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };