ochre-sdk 0.22.19 → 0.22.21

package/dist/index.d.mts

@@ -1293,6 +1293,11 @@ declare function fetchGallery(params: {
  * Fetches and parses an OCHRE item from the OCHRE API
  *
  * @param uuid - The UUID of the OCHRE item to fetch
+ * @param category - The category of the OCHRE item to fetch
+ * @param itemCategories - The categories of the OCHRE items to fetch
+ * @param options - The options for the fetch
+ * @param options.fetch - The fetch function to use
+ * @param options.version - The version of the OCHRE API to use
  * @returns Object containing the parsed OCHRE item, or an error message if the fetch/parse fails
  */
 declare function fetchItem<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(uuid: string, category?: T, itemCategories?: U, options?: {

package/dist/index.mjs

@@ -2065,6 +2065,11 @@ async function fetchByUuid(uuid, options) {
 * Fetches and parses an OCHRE item from the OCHRE API
 *
 * @param uuid - The UUID of the OCHRE item to fetch
+* @param category - The category of the OCHRE item to fetch
+* @param itemCategories - The categories of the OCHRE items to fetch
+* @param options - The options for the fetch
+* @param options.fetch - The fetch function to use
+* @param options.version - The version of the OCHRE API to use
 * @returns Object containing the parsed OCHRE item, or an error message if the fetch/parse fails
 */
 async function fetchItem(uuid, category, itemCategories, options) {
@@ -2511,6 +2516,16 @@ function buildPropertyStringQueryExpression(params) {
 			value,
 			matchMode,
 			isCaseSensitive
+		}),
+		rawValueQueryExpression: buildValueRawValueInnerQuery({
+			value,
+			matchMode,
+			isCaseSensitive
+		}),
+		bareValueQueryExpression: buildValueDirectTextInnerQuery({
+			value,
+			matchMode,
+			isCaseSensitive
 		})
 	});
 }
@@ -3030,6 +3045,47 @@ function buildOrderedItemsClause(sort) {
 	})}
       return $item`;
 }
+function isExactStringPropertyQuery(query) {
+	return "target" in query && query.target === "property" && query.dataType === "string" && query.value != null && query.matchMode === "exact" && query.isNegated !== true;
+}
+function getCtsQueriesWithoutExactStringPropertyQueries(queries) {
+	if (queries == null) return null;
+	if ("target" in queries) return isExactStringPropertyQuery(queries) ? null : queries;
+	if ("or" in queries) return queries;
+	const filteredChildren = [];
+	for (const childQuery of queries.and) {
+		const filteredChildQuery = getCtsQueriesWithoutExactStringPropertyQueries(childQuery);
+		if (filteredChildQuery != null) filteredChildren.push(filteredChildQuery);
+	}
+	if (filteredChildren.length === 0) return null;
+	return filteredChildren.length === 1 ? filteredChildren[0] ?? null : { and: filteredChildren };
+}
+function buildExactStringPropertyPredicate(query) {
+	const propertyPredicates = [];
+	const value = stringLiteral(query.value);
+	if (query.propertyVariable != null) propertyPredicates.push(`label/@uuid = ${stringLiteral(query.propertyVariable)}`);
+	propertyPredicates.push(`value[
+    not(@inherited = "true")
+    and (
+      content[@xml:lang = ${stringLiteral(query.language)}]/string = ${value}
+      or @rawValue = ${value}
+      or (not(content) and text() = ${value})
+    )
+  ]`);
+	return `.//properties/property[${propertyPredicates.join(" and ")}]`;
+}
+function buildExactStringPropertyXPathFilterExpression(queries) {
+	if (queries == null) return null;
+	if ("target" in queries) return isExactStringPropertyQuery(queries) ? buildExactStringPropertyPredicate(queries) : null;
+	if ("or" in queries) return null;
+	const childExpressions = [];
+	for (const childQuery of queries.and) {
+		const childExpression = buildExactStringPropertyXPathFilterExpression(childQuery);
+		if (childExpression != null) childExpressions.push(childExpression);
+	}
+	if (childExpressions.length === 0) return null;
+	return childExpressions.join(" and ");
+}
 /**
 * Build an XQuery string to fetch Set items from the OCHRE API
 * @param params - The parameters for the fetch
@@ -3047,7 +3103,9 @@ function buildXQuery$1(params) {
 	const startPosition = (page - 1) * pageSize + 1;
 	const setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
 	const baseItemsExpression = "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
-	const compiledQueryPlan = buildQueryPlan({ queries });
+	const ctsQueries = getCtsQueriesWithoutExactStringPropertyQueries(queries);
+	const exactStringPropertyXPathFilterExpression = buildExactStringPropertyXPathFilterExpression(queries);
+	const compiledQueryPlan = buildQueryPlan({ queries: ctsQueries });
 	const itemsQueryExpressions = [];
 	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
 	if (compiledQueryPlan.queryExpression != null) itemsQueryExpressions.push(compiledQueryPlan.queryExpression);
@@ -3056,8 +3114,11 @@ function buildXQuery$1(params) {
 	const orderedItemsClause = buildOrderedItemsClause(sort);
 	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)`;
+	const searchedItemsClause = itemsQueryExpression == null ? `let $searchedItems := ${baseItemsExpression}` : `let $query := ${itemsQueryExpression}
+  let $searchedItems := cts:search(${baseItemsExpression}, $query)`;
+	const itemsClause = exactStringPropertyXPathFilterExpression == null ? `${searchedItemsClause}
+  let $items := $searchedItems` : `${searchedItemsClause}
+  let $items := $searchedItems[${exactStringPropertyXPathFilterExpression}]`;
 	return `${xqueryDeclarations.join("\n\n")}
 
 <ochre>{
@@ -3190,67 +3251,27 @@ function parsePropertyValueBooleanContent(rawValue) {
 	if (typeof rawValue === "boolean") return rawValue;
 	return rawValue.toString().toLocaleLowerCase("en-US") === "true";
 }
-function getPropertyValueGroupKey(value) {
-	const contentKey = value.content == null ? "null" : `${typeof value.content}:${value.content.toLocaleString("en-US")}`;
-	return `${value.dataType}|${contentKey}`;
-}
-function aggregatePropertyValues(values) {
-	const groupedPropertyValuesMap = /* @__PURE__ */ new Map();
-	for (const value of values) {
-		const key = getPropertyValueGroupKey(value);
-		const existing = groupedPropertyValuesMap.get(key);
-		if (existing == null) {
-			groupedPropertyValuesMap.set(key, {
-				dataType: value.dataType,
-				content: value.content,
-				label: value.label,
-				itemUuids: new Set([value.itemUuid])
-			});
-			continue;
-		}
-		existing.itemUuids.add(value.itemUuid);
-		if (existing.label == null && value.label != null) existing.label = value.label;
-	}
-	const groupedPropertyValues = [];
-	for (const group of groupedPropertyValuesMap.values()) {
-		if (group.content == null) continue;
-		groupedPropertyValues.push({
-			count: group.itemUuids.size,
-			dataType: group.dataType,
-			content: group.content,
-			label: group.label
-		});
-	}
-	return groupedPropertyValues.toSorted((a, b) => {
+function sortPropertyValues(values) {
+	return values.toSorted((a, b) => {
 		if (a.count !== b.count) return b.count - a.count;
 		if (a.label !== b.label) return a.label?.localeCompare(b.label ?? "") ?? 0;
 		return a.content?.toString().localeCompare(b.content?.toString() ?? "") ?? 0;
 	});
 }
-function aggregateAttributeValues(values) {
-	const groupedAttributeValuesMap = /* @__PURE__ */ new Map();
-	for (const value of values) {
-		if (value.content == null || value.content === "") continue;
-		const existing = groupedAttributeValuesMap.get(value.content);
-		if (existing == null) {
-			groupedAttributeValuesMap.set(value.content, {
-				content: value.content,
-				itemUuids: new Set([value.itemUuid])
-			});
-			continue;
-		}
-		existing.itemUuids.add(value.itemUuid);
-	}
-	const groupedAttributeValues = [];
-	for (const group of groupedAttributeValuesMap.values()) groupedAttributeValues.push({
-		count: group.itemUuids.size,
-		content: group.content
-	});
-	return groupedAttributeValues.toSorted((a, b) => {
+function getPropertyValueKey(value) {
+	return `${value.dataType}|${typeof value.content}:${value.content.toLocaleString("en-US")}`;
+}
+function sortAttributeValues(values) {
+	return values.toSorted((a, b) => {
 		if (a.count !== b.count) return b.count - a.count;
 		return a.content.localeCompare(b.content);
 	});
 }
+const countSchema = z.union([z.number(), z.string()]).optional().transform((val) => {
+	if (val == null || val === "") return 1;
+	const count = Number(val);
+	return Number.isFinite(count) ? count : 1;
+});
 function getPropertyVariableUuidsFromQueries(queries) {
 	const propertyVariableUuids = /* @__PURE__ */ new Set();
 	if (queries == null) return [];
@@ -3287,8 +3308,10 @@ function getItemFilterQueriesFromPropertyValueQueries(queries) {
 */
 const propertyValueQueryItemSchema = z.object({
 	uuid: z.string(),
+	scope: z.enum(["global", "variable"]).default("global"),
 	variableUuid: z.string().optional(),
-	itemUuid: z.string().optional(),
+	count: countSchema,
+	globalCount: countSchema.nullish(),
 	dataType: z.string(),
 	rawValue: fakeStringSchema.optional(),
 	content: z.union([
@@ -3298,8 +3321,10 @@ const propertyValueQueryItemSchema = z.object({
 	]).optional()
 }).transform((val) => {
 	const returnValue = {
+		scope: val.scope,
 		variableUuid: val.variableUuid != null && val.variableUuid !== "" ? val.variableUuid : null,
-		itemUuid: val.itemUuid != null && val.itemUuid !== "" ? val.itemUuid : null,
+		count: val.count,
+		globalCount: val.globalCount ?? null,
 		dataType: val.dataType,
 		content: null,
 		label: null
@@ -3331,11 +3356,11 @@ const propertyValueQueryItemSchema = z.object({
 });
 const attributeValueQueryItemSchema = z.object({
 	attributeType: z.enum(["bibliographies", "periods"]),
-	itemUuid: z.string().optional(),
+	count: countSchema,
 	content: z.string().optional()
 }).transform((val) => ({
 	attributeType: val.attributeType,
-	itemUuid: val.itemUuid != null && val.itemUuid !== "" ? val.itemUuid : null,
+	count: val.count,
 	content: val.content != null && val.content !== "" ? val.content : null
 }));
 /**
@@ -3360,9 +3385,8 @@ const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 */
 function buildXQuery(params) {
 	const { setScopeUuids, belongsToCollectionScopeUuids, queries, propertyVariableUuids, attributes, isLimitedToLeafPropertyValues } = params;
-	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 setScopeDeclaration = `declare variable $setScopeUuids := (${setScopeUuids.map((uuid) => stringLiteral(uuid)).join(", ")});`;
+	const baseItemsExpression = "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
 	const compiledQueryPlan = buildQueryPlan({ queries: getItemFilterQueriesFromPropertyValueQueries(queries) });
 	const itemsQueryExpressions = [];
 	const belongsToCollectionQueryExpression = buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID);
@@ -3372,39 +3396,186 @@ function buildXQuery(params) {
 	const valueFilter = isLimitedToLeafPropertyValues ? "[not(@i)]" : "";
 	const queryBlocks = [];
 	const returnedSequences = [];
-	const xqueryDeclarations = ["xquery version \"1.0-ml\";"];
-	if (setScopeDeclaration !== "") xqueryDeclarations.push(setScopeDeclaration);
+	const xqueryDeclarations = [
+		"xquery version \"1.0-ml\";",
+		"declare namespace map = \"http://marklogic.com/xdmp/map\";",
+		setScopeDeclaration,
+		`declare function local:increment-count($counts, $key) {
+  let $current := map:get($counts, $key)
+  return map:put(
+    $counts,
+    $key,
+    if (empty($current)) then 1 else xs:integer($current) + 1
+  )
+};
+
+declare function local:value-display($v) {
+  if ($v/content)
+  then string-join($v/content[@xml:lang="eng"]//text(), "")
+  else string($v)
+};
+
+declare function local:value-content($data-type, $raw-value, $value-uuid, $display) {
+  if ($data-type = "IDREF") then $value-uuid
+  else if ($data-type = ("integer", "decimal", "time")) then
+    if ($raw-value castable as xs:double)
+    then string(xs:double($raw-value))
+    else ""
+  else if ($data-type = "boolean") then
+    if ($raw-value = "") then ""
+    else if (lower-case($raw-value) = "true") then "true"
+    else "false"
+  else if ($raw-value != "") then $raw-value
+  else if ($display != "" and $display != "<unassigned>") then $display
+  else ""
+};
+
+declare function local:value-kind($data-type) {
+  if ($data-type = ("integer", "decimal", "time")) then "number"
+  else if ($data-type = "boolean") then "boolean"
+  else "string"
+};
+
+declare function local:property-output-raw-value($data-type, $raw-value, $content) {
+  if ($data-type = ("integer", "decimal", "time", "boolean")) then $content
+  else $raw-value
+};
+
+declare function local:put-property-detail(
+  $details,
+  $key,
+  $scope,
+  $variable-uuid,
+  $value-uuid,
+  $raw-value,
+  $data-type,
+  $display
+) {
+  let $existing := map:get($details, $key)
+  return
+    if (
+      empty($existing)
+      or (string-length(string($existing)) = 0 and string-length($display) gt 0)
+    ) then
+      map:put(
+        $details,
+        $key,
+        <propertyValue scope="{$scope}" variableUuid="{$variable-uuid}" uuid="{$value-uuid}" rawValue="{$raw-value}" dataType="{$data-type}">{$display}</propertyValue>
+      )
+    else ()
+};
+
+declare function local:add-property-facet(
+  $counts,
+  $details,
+  $seen,
+  $key,
+  $scope,
+  $variable-uuid,
+  $value-uuid,
+  $raw-value,
+  $data-type,
+  $display
+) {
+  if (exists(map:get($seen, $key))) then ()
+  else (
+    map:put($seen, $key, true()),
+    local:increment-count($counts, $key),
+    local:put-property-detail($details, $key, $scope, $variable-uuid, $value-uuid, $raw-value, $data-type, $display)
+  )
+};
+
+declare function local:add-attribute-facet($counts, $seen, $key) {
+  if (exists(map:get($seen, $key))) then ()
+  else (
+    map:put($seen, $key, true()),
+    local:increment-count($counts, $key)
+  )
+};`
+	];
 	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}]]
+		const propertyVariableValues = propertyVariableUuids.map((uuid) => stringLiteral(uuid));
+		xqueryDeclarations.push(`declare variable $facetLabelUuids := (${propertyVariableValues.join(", ")});`);
+		queryBlocks.push(`let $global-property-counts := map:map()
+let $variable-property-counts := map:map()
+let $variable-property-details := map:map()
+let $variable-property-global-keys := map:map()
+let $_property-aggregation := xdmp:eager(
+  for $item in $items
+  let $global-seen := map:map()
+  let $variable-seen := map:map()
+  return
+    for $p in $item/properties/property[label/@uuid = $facetLabelUuids]
+    let $variable-uuid := string($p/label/@uuid)
+    for $v in $p/value${valueFilter}
+    let $value-uuid := string($v/@uuid)
+    let $raw-value := string($v/@rawValue)
+    let $data-type := string($v/@dataType)
+    let $display := local:value-display($v)
+    let $content := local:value-content($data-type, $raw-value, $value-uuid, $display)
+    let $value-kind := local:value-kind($data-type)
+    let $output-raw-value := local:property-output-raw-value($data-type, $raw-value, $content)
+    let $global-key := string-join(($data-type, $value-kind, $content), "||")
+    let $variable-key := string-join(($variable-uuid, $data-type, $value-kind, $content), "||")
+    where $content != ""
+    return (
+      local:add-attribute-facet($global-property-counts, $global-seen, $global-key),
+      local:add-property-facet($variable-property-counts, $variable-property-details, $variable-seen, $variable-key, "variable", $variable-uuid, $value-uuid, $output-raw-value, $data-type, $display),
+      map:put($variable-property-global-keys, $variable-key, $global-key)
+    )
+)
 
 let $property-values :=
-  for $p in $matching-props
-  for $v in $p/value${valueFilter}
-    let $item-uuid := $v/ancestor::*[parent::items]/@uuid
-    let $variable-uuid := $p/label/@uuid
-    return <propertyValue uuid="{$v/@uuid}" rawValue="{$v/@rawValue}" dataType="{$v/@dataType}" itemUuid="{$item-uuid}" variableUuid="{$variable-uuid}">{
-      if ($v/content) then string-join($v/content[@xml:lang="eng"]//text(), "") else $v/text()
-    }</propertyValue>`);
+  (
+    $_property-aggregation,
+    for $key in map:keys($variable-property-counts)
+    let $detail := map:get($variable-property-details, $key)
+    let $global-key := map:get($variable-property-global-keys, $key)
+    return <propertyValue scope="variable" variableUuid="{string($detail/@variableUuid)}" uuid="{string($detail/@uuid)}" rawValue="{string($detail/@rawValue)}" dataType="{string($detail/@dataType)}" count="{map:get($variable-property-counts, $key)}" globalCount="{map:get($global-property-counts, $global-key)}">{
+      string($detail)
+    }</propertyValue>
+  )`);
 		returnedSequences.push("$property-values");
 	}
 	if (attributes.bibliographies) {
-		queryBlocks.push(`let $bibliography-values :=
+		queryBlocks.push(`let $bibliography-counts := map:map()
+let $_bibliography-aggregation := xdmp:eager(
   for $item in $items
-  for $bibliography in $item/bibliographies/bibliography
+  let $seen := map:map()
+  return
+    for $bibliography in $item/bibliographies/bibliography
     let $label := string-join($bibliography/identification/label/content[@xml:lang="eng"]//text(), "")
     where string-length($label) gt 0
-    return <attributeValue attributeType="bibliographies" itemUuid="{$item/@uuid}" content="{$label}" />`);
+    return local:add-attribute-facet($bibliography-counts, $seen, $label)
+)
+
+let $bibliography-values :=
+  (
+    $_bibliography-aggregation,
+    for $label in map:keys($bibliography-counts)
+    return <attributeValue attributeType="bibliographies" count="{map:get($bibliography-counts, $label)}" content="{$label}" />
+  )`);
 		returnedSequences.push("$bibliography-values");
 	}
 	if (attributes.periods) {
-		queryBlocks.push(`let $period-values :=
+		queryBlocks.push(`let $period-counts := map:map()
+let $_period-aggregation := xdmp:eager(
   for $item in $items
-  for $period in $item/periods/period
+  let $seen := map:map()
+  return
+    for $period in $item/periods/period
     let $label := string-join($period/identification/label/content[@xml:lang="eng"]//text(), "")
     where string-length($label) gt 0
-    return <attributeValue attributeType="periods" itemUuid="{$item/@uuid}" content="{$label}" />`);
+    return local:add-attribute-facet($period-counts, $seen, $label)
+)
+
+let $period-values :=
+  (
+    $_period-aggregation,
+    for $label in map:keys($period-counts)
+    return <attributeValue attributeType="periods" count="{map:get($period-counts, $label)}" content="{$label}" />
+  )`);
 		returnedSequences.push("$period-values");
 	}
 	const itemsClause = itemsQueryExpression == null ? `let $items := ${baseItemsExpression}` : `let $query := ${itemsQueryExpression}
@@ -3470,35 +3641,50 @@ async function fetchSetPropertyValues(params, options) {
 			if (parsedResultRaw.result.ochre.propertyValue != null) parsedPropertyValues.push(...Array.isArray(parsedResultRaw.result.ochre.propertyValue) ? parsedResultRaw.result.ochre.propertyValue : [parsedResultRaw.result.ochre.propertyValue]);
 			if (parsedResultRaw.result.ochre.attributeValue != null) parsedAttributeValues.push(...Array.isArray(parsedResultRaw.result.ochre.attributeValue) ? parsedResultRaw.result.ochre.attributeValue : [parsedResultRaw.result.ochre.attributeValue]);
 		}
-		const propertyValuesByPropertyVariableUuidRaw = {};
-		const flattenedPropertyValues = [];
+		const propertyValuesByPropertyVariableUuid = {};
+		const flattenedPropertyValuesByKey = /* @__PURE__ */ new Map();
 		for (const propertyValue of parsedPropertyValues) {
-			const aggregatePropertyValueItem = {
-				itemUuid: propertyValue.itemUuid,
+			if (propertyValue.content == null) continue;
+			const propertyValueItem = {
+				count: propertyValue.count,
 				dataType: propertyValue.dataType,
 				content: propertyValue.content,
 				label: propertyValue.label
 			};
-			flattenedPropertyValues.push(aggregatePropertyValueItem);
-			if (propertyValue.variableUuid == null) continue;
-			(propertyValuesByPropertyVariableUuidRaw[propertyValue.variableUuid] ??= []).push(aggregatePropertyValueItem);
-		}
-		const propertyValuesByPropertyVariableUuid = {};
-		for (const [propertyVariableUuid, values] of Object.entries(propertyValuesByPropertyVariableUuidRaw)) {
-			const aggregatedValues = aggregatePropertyValues(values);
-			if (aggregatedValues.length > 0) propertyValuesByPropertyVariableUuid[propertyVariableUuid] = aggregatedValues;
+			const globalPropertyValueItem = {
+				count: propertyValue.globalCount ?? propertyValue.count,
+				dataType: propertyValue.dataType,
+				content: propertyValue.content,
+				label: propertyValue.label
+			};
+			const globalPropertyValueKey = getPropertyValueKey({
+				dataType: globalPropertyValueItem.dataType,
+				content: propertyValue.content
+			});
+			const existingGlobalPropertyValue = flattenedPropertyValuesByKey.get(globalPropertyValueKey);
+			if (existingGlobalPropertyValue == null) flattenedPropertyValuesByKey.set(globalPropertyValueKey, globalPropertyValueItem);
+			else if (existingGlobalPropertyValue.label == null && globalPropertyValueItem.label != null) existingGlobalPropertyValue.label = globalPropertyValueItem.label;
+			if (propertyValue.scope === "global") continue;
+			if (propertyValue.variableUuid != null) (propertyValuesByPropertyVariableUuid[propertyValue.variableUuid] ??= []).push(propertyValueItem);
 		}
-		const attributeValuesByTypeRaw = {
+		for (const [propertyVariableUuid, values] of Object.entries(propertyValuesByPropertyVariableUuid)) propertyValuesByPropertyVariableUuid[propertyVariableUuid] = sortPropertyValues(values);
+		const attributeValuesByType = {
 			bibliographies: [],
 			periods: []
 		};
-		for (const attributeValue of parsedAttributeValues) attributeValuesByTypeRaw[attributeValue.attributeType].push(attributeValue);
+		for (const attributeValue of parsedAttributeValues) {
+			if (attributeValue.content == null || attributeValue.content === "") continue;
+			attributeValuesByType[attributeValue.attributeType].push({
+				count: attributeValue.count,
+				content: attributeValue.content
+			});
+		}
 		return {
-			propertyValues: aggregatePropertyValues(flattenedPropertyValues),
+			propertyValues: sortPropertyValues([...flattenedPropertyValuesByKey.values()]),
 			propertyValuesByPropertyVariableUuid,
 			attributeValues: {
-				bibliographies: attributes.bibliographies ? aggregateAttributeValues(attributeValuesByTypeRaw.bibliographies) : null,
-				periods: attributes.periods ? aggregateAttributeValues(attributeValuesByTypeRaw.periods) : null
+				bibliographies: attributes.bibliographies ? sortAttributeValues(attributeValuesByType.bibliographies) : null,
+				periods: attributes.periods ? sortAttributeValues(attributeValuesByType.periods) : null
 			},
 			error: null
 		};
@@ -3869,6 +4055,15 @@ function filterProperties(property, filter, options = DEFAULT_OPTIONS) {
 //#region src/utils/parse/website.ts
 const SEGMENT_UNIQUE_SLUG_PREFIX_REGEX = /^\$[^-]*-/;
 const TRAILING_SLASH_REGEX = /\/$/;
+function formatRawResourceMetadata(resource) {
+	const metadata = [`label “${parseStringContent(resource.identification.label)}”`, `uuid “${resource.uuid}”`];
+	if (resource.slug != null) metadata.push(`slug “${resource.slug}”`);
+	if (resource.identification.abbreviation != null) metadata.push(`abbreviation “${parseFakeStringOrContent(resource.identification.abbreviation)}”`);
+	return metadata.join(", ");
+}
+function formatComponentError(message, componentName, elementResource) {
+	return `${message} for component “${componentName ?? "(unknown)"}” (${formatRawResourceMetadata(elementResource)})`;
+}
 /**
 * Extracts CSS style properties for a given presentation variant.
 *
@@ -3992,7 +4187,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 	switch (componentName) {
 		case "3d-viewer": {
 			const resourceLink = links.find((link) => link.category === "resource" && link.fileFormat === "model/obj");
-			if (resourceLink?.uuid == null) throw new Error(`Resource link not found for the following component: “${componentName}”`);
+			if (resourceLink?.uuid == null) throw new Error(formatComponentError("Resource link not found", componentName, elementResource));
 			let isInteractive = getPropertyValueContentByLabel(componentProperty.properties, "is-interactive");
 			isInteractive ??= true;
 			let isControlsDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "controls-displayed");
@@ -4010,7 +4205,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			const boundElementPropertyUuid = getPropertyByLabel(componentProperty.properties, "bound-element")?.values[0]?.uuid ?? null;
 			const linkToProperty = getPropertyByLabel(componentProperty.properties, "link-to");
 			const href = linkToProperty?.values[0]?.href != null ? transformPermanentIdentificationUrl(linkToProperty.values[0].href) : linkToProperty?.values[0]?.slug ?? null;
-			if (boundElementPropertyUuid == null && href == null) throw new Error(`Bound element or href not found for the following component: “${componentName}”`);
+			if (boundElementPropertyUuid == null && href == null) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource));
 			properties = {
 				component: "advanced-search",
 				boundElementUuid: boundElementPropertyUuid,
@@ -4020,7 +4215,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "annotated-document": {
 			const documentLink = links.find((link) => link.type === "internalDocument");
-			if (documentLink?.uuid == null) throw new Error(`Document link not found for the following component: “${componentName}”`);
+			if (documentLink?.uuid == null) throw new Error(formatComponentError("Document link not found", componentName, elementResource));
 			properties = {
 				component: "annotated-document",
 				linkUuid: documentLink.uuid
@@ -4029,7 +4224,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "annotated-image": {
 			const imageLinks = links.filter((link) => link.type === "image" || link.type === "IIIF");
-			if (imageLinks.length === 0 || imageLinks[0].uuid == null) throw new Error(`Image link not found for the following component: “${componentName}”`);
+			if (imageLinks.length === 0 || imageLinks[0].uuid == null) throw new Error(formatComponentError("Image link not found", componentName, elementResource));
 			let isFilterInputDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "filter-input-displayed");
 			isFilterInputDisplayed ??= true;
 			let isOptionsDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "options-displayed");
@@ -4050,7 +4245,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "audio-player": {
 			const audioLink = links.find((link) => link.type === "audio");
-			if (audioLink?.uuid == null) throw new Error(`Audio link not found for the following component: “${componentName}”`);
+			if (audioLink?.uuid == null) throw new Error(formatComponentError("Audio link not found", componentName, elementResource));
 			let isSpeedControlsDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "speed-controls-displayed");
 			isSpeedControlsDisplayed ??= true;
 			let isVolumeControlsDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "volume-controls-displayed");
@@ -4069,7 +4264,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		case "bibliography": {
 			const itemLinks = links.filter((link) => link.category !== "bibliography");
 			const bibliographyLink = links.find((link) => link.category === "bibliography");
-			if (itemLinks.length === 0 && bibliographyLink?.bibliographies == null) throw new Error(`No links found for the following component: “${componentName}”`);
+			if (itemLinks.length === 0 && bibliographyLink?.bibliographies == null) throw new Error(formatComponentError("No links found", componentName, elementResource));
 			let layout = getPropertyValueContentByLabel(componentProperty.properties, "layout");
 			layout ??= "long";
 			let isSourceDocumentDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "source-document-displayed");
@@ -4092,7 +4287,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			if (href === null) {
 				const linkToProperty = getPropertyByLabel(componentProperty.properties, "link-to");
 				href = linkToProperty?.values[0]?.href != null ? transformPermanentIdentificationUrl(linkToProperty.values[0].href) : linkToProperty?.values[0]?.slug ?? null;
-				if (href === null) throw new Error(`Properties “navigate-to” or “link-to” not found for the following component: “${componentName}”`);
+				if (href === null) throw new Error(formatComponentError("Properties “navigate-to” or “link-to” not found", componentName, elementResource));
 				else isExternal = true;
 			}
 			let startIcon = getPropertyValueContentByLabel(componentProperty.properties, "start-icon");
@@ -4123,7 +4318,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "collection": {
 			const setLinks = links.filter((link) => link.category === "set");
-			if (setLinks.every((link) => link.uuid === null)) throw new Error(`Set links not found for the following component: “${componentName}”`);
+			if (setLinks.every((link) => link.uuid === null)) throw new Error(formatComponentError("Set links not found", componentName, elementResource));
 			const displayedProperties = getPropertyByLabel(componentProperty.properties, "use-property");
 			let variant = getPropertyValueContentByLabel(componentProperty.properties, "variant");
 			variant ??= "slide";
@@ -4202,7 +4397,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "entries": {
 			const entriesLink = links.find((link) => link.category === "tree" || link.category === "set");
-			if (entriesLink?.uuid == null) throw new Error(`Entries link not found for the following component: “${componentName}”`);
+			if (entriesLink?.uuid == null) throw new Error(formatComponentError("Entries link not found", componentName, elementResource));
 			let variant = getPropertyValueContentByLabel(componentProperty.properties, "variant");
 			variant ??= "entry";
 			let isFilterInputDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "filter-input-displayed");
@@ -4217,7 +4412,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "iframe": {
 			const href = links.find((link) => link.type === "webpage")?.href;
-			if (!href) throw new Error(`URL not found for the following component: “${componentName}”`);
+			if (!href) throw new Error(formatComponentError("URL not found", componentName, elementResource));
 			const height = getPropertyValueContentByLabel(componentProperty.properties, "height");
 			const width = getPropertyValueContentByLabel(componentProperty.properties, "width");
 			properties = {
@@ -4230,7 +4425,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "iiif-viewer": {
 			const manifestLink = links.find((link) => link.type === "IIIF");
-			if (manifestLink?.uuid == null) throw new Error(`Manifest link not found for the following component: “${componentName}”`);
+			if (manifestLink?.uuid == null) throw new Error(formatComponentError("Manifest link not found", componentName, elementResource));
 			let variant = getPropertyValueContentByLabel(componentProperty.properties, "variant");
 			variant ??= "universal-viewer";
 			properties = {
@@ -4241,7 +4436,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			break;
 		}
 		case "image": {
-			if (links.length === 0) throw new Error(`No links found for the following component: “${componentName}”`);
+			if (links.length === 0) throw new Error(formatComponentError("No links found", componentName, elementResource));
 			let imageQuality = getPropertyValueContentByLabel(componentProperty.properties, "image-quality");
 			imageQuality ??= "high";
 			const images = [];
@@ -4329,7 +4524,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "image-gallery": {
 			const galleryLink = links.find((link) => link.category === "tree" || link.category === "set");
-			if (galleryLink?.uuid == null) throw new Error(`Image gallery link not found for the following component: “${componentName}”`);
+			if (galleryLink?.uuid == null) throw new Error(formatComponentError("Image gallery link not found", componentName, elementResource));
 			let isFilterInputDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "filter-input-displayed");
 			isFilterInputDisplayed ??= true;
 			properties = {
@@ -4341,7 +4536,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "map": {
 			const mapLink = links.find((link) => link.category === "set" || link.category === "tree");
-			if (mapLink?.uuid == null) throw new Error(`Map link not found for the following component: “${componentName}”`);
+			if (mapLink?.uuid == null) throw new Error(formatComponentError("Map link not found", componentName, elementResource));
 			let isInteractive = getPropertyValueContentByLabel(componentProperty.properties, "is-interactive");
 			isInteractive ??= true;
 			let isClustered = getPropertyValueContentByLabel(componentProperty.properties, "is-clustered");
@@ -4376,17 +4571,17 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "query": {
 			const setLinks = links.filter((link) => link.category === "set");
-			if (setLinks.every((link) => link.uuid === null)) throw new Error(`Set links not found for the following component: “${componentName}”`);
+			if (setLinks.every((link) => link.uuid === null)) throw new Error(formatComponentError("Set links not found", componentName, elementResource));
 			const items = [];
-			if (componentProperty.properties.length === 0) throw new Error(`Query properties not found for the following component: “${componentName}”`);
+			if (componentProperty.properties.length === 0) throw new Error(formatComponentError("Query properties not found", componentName, elementResource));
 			for (const queryItem of componentProperty.properties) {
 				const querySubProperties = queryItem.properties;
 				const label = getPropertyValueContentByLabel(querySubProperties, "query-prompt");
 				if (label === null) continue;
 				const queries = (getPropertyByLabel(querySubProperties, "use-property")?.values.filter((value) => value.uuid !== null) ?? []).map((propertyVariable) => {
-					if (propertyVariable.uuid === null) throw new Error(`Property variable UUID not found for the following component: “${componentName}”`);
+					if (propertyVariable.uuid === null) throw new Error(formatComponentError("Property variable UUID not found", componentName, elementResource));
 					const dataType = propertyVariable.dataType;
-					if (dataType === "coordinate") throw new Error(`Query prompts with data type "coordinate" are not supported for the following component: “${componentName}”`);
+					if (dataType === "coordinate") throw new Error(formatComponentError("Query prompts with data type \"coordinate\" are not supported", componentName, elementResource));
 					return {
 						target: "property",
 						propertyVariable: propertyVariable.uuid,
@@ -4407,7 +4602,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 					endIcon
 				});
 			}
-			if (items.length === 0) throw new Error(`No queries found for the following component: “${componentName}”`);
+			if (items.length === 0) throw new Error(formatComponentError("No queries found", componentName, elementResource));
 			const options = {
 				scopes: elementResource.options?.scopes != null ? ensureArray(elementResource.options.scopes.scope).map((scope) => ({
 					uuid: scope.uuid.content,
@@ -4453,7 +4648,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "table": {
 			const tableLink = links.find((link) => link.category === "set");
-			if (tableLink?.uuid == null) throw new Error(`Table link not found for the following component: “${componentName}”`);
+			if (tableLink?.uuid == null) throw new Error(formatComponentError("Table link not found", componentName, elementResource));
 			properties = {
 				component: "table",
 				linkUuid: tableLink.uuid
@@ -4467,7 +4662,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			const boundElementUuid = getPropertyByLabel(componentProperty.properties, "bound-element")?.values[0]?.uuid ?? null;
 			const linkToProperty = getPropertyByLabel(componentProperty.properties, "link-to");
 			const href = linkToProperty?.values[0]?.href != null ? transformPermanentIdentificationUrl(linkToProperty.values[0].href) : linkToProperty?.values[0]?.slug ?? null;
-			if (!boundElementUuid && !href) throw new Error(`Bound element or href not found for the following component: “${componentName}”`);
+			if (!boundElementUuid && !href) throw new Error(formatComponentError("Bound element or href not found", componentName, elementResource));
 			let placeholder = getPropertyValueContentByLabel(componentProperty.properties, "placeholder-text");
 			placeholder ??= null;
 			let baseFilterQueries = getPropertyValueContentByLabel(componentProperty.properties, "base-filter-queries");
@@ -4484,7 +4679,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "text": {
 			const content = elementResource.document && "content" in elementResource.document ? parseDocument(elementResource.document.content) : null;
-			if (!content) throw new Error(`Content not found for the following component: “${componentName}”`);
+			if (!content) throw new Error(formatComponentError("Content not found", componentName, elementResource));
 			let variantName = "block";
 			let variant;
 			const variantProperty = getPropertyByLabel(componentProperty.properties, "variant");
@@ -4511,7 +4706,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "timeline": {
 			const timelineLink = links.find((link) => link.category === "tree");
-			if (timelineLink?.uuid == null) throw new Error(`Timeline link not found for the following component: “${componentName}”`);
+			if (timelineLink?.uuid == null) throw new Error(formatComponentError("Timeline link not found", componentName, elementResource));
 			properties = {
 				component: "timeline",
 				linkUuid: timelineLink.uuid
@@ -4520,7 +4715,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		}
 		case "video": {
 			const videoLink = links.find((link) => link.type === "video");
-			if (videoLink?.uuid == null) throw new Error(`Video link not found for the following component: “${componentName}”`);
+			if (videoLink?.uuid == null) throw new Error(formatComponentError("Video link not found", componentName, elementResource));
 			let isChaptersDisplayed = getPropertyValueContentByLabel(componentProperty.properties, "chapters-displayed");
 			isChaptersDisplayed ??= true;
 			properties = {
@@ -4534,7 +4729,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			console.warn(`Invalid or non-implemented component name “${unparsedComponentName?.toString() ?? "(unknown)"}” for the following element: “${parseStringContent(elementResource.identification.label)}”`);
 			break;
 	}
-	if (properties === null) throw new Error(`Properties not found for the following component: “${componentName}”`);
+	if (properties === null) throw new Error(formatComponentError("Properties not found", componentName, elementResource));
 	return properties;
 }
 function parseWebTitle(properties, identification, overrides) {
@@ -4570,9 +4765,9 @@ function parseWebElement(elementResource) {
 	const identification = parseIdentification(elementResource.identification);
 	const elementProperties = elementResource.properties?.property ? parseProperties(Array.isArray(elementResource.properties.property) ? elementResource.properties.property : [elementResource.properties.property]) : [];
 	const presentationProperty = getPropertyByLabel(elementProperties, "presentation");
-	if (presentationProperty === null) throw new Error(`Presentation property not found for element “${identification.label}”`);
+	if (presentationProperty === null) throw new Error(`Presentation property not found for element (${formatRawResourceMetadata(elementResource)})`);
 	const componentProperty = getPropertyByLabel(presentationProperty.properties, "component");
-	if (componentProperty === null) throw new Error(`Component for element “${identification.label}” not found`);
+	if (componentProperty === null) throw new Error(`Component property not found for element (${formatRawResourceMetadata(elementResource)})`);
 	const properties = parseWebElementProperties(componentProperty, elementResource);
 	const cssStyles = parseResponsiveCssStyles(elementProperties);
 	const title = parseWebTitle(elementProperties, identification, {
@@ -4629,7 +4824,7 @@ function parseWebpage(webpageResource, slugPrefix) {
 	if (webpageProperties.length === 0 || getPropertyValueContentByLabel(webpageProperties, "presentation") !== "page") return null;
 	const identification = parseIdentification(webpageResource.identification);
 	const slug = webpageResource.slug?.replace(SEGMENT_UNIQUE_SLUG_PREFIX_REGEX, "") ?? null;
-	if (slug == null) throw new Error(`Slug not found for page “${identification.label}”`);
+	if (slug == null) throw new Error(`Slug not found for page (${formatRawResourceMetadata(webpageResource)})`);
 	const returnWebpage = {
 		uuid: webpageResource.uuid,
 		type: "page",
@@ -4724,7 +4919,7 @@ function parseWebSegment(segmentResource, slugPrefix) {
 	if (webpageProperties.length === 0 || getPropertyValueContentByLabel(webpageProperties, "presentation") !== "segment") return null;
 	const identification = parseIdentification(segmentResource.identification);
 	const slug = segmentResource.identification.abbreviation != null ? parseFakeStringOrContent(segmentResource.identification.abbreviation) : null;
-	if (slug == null) throw new Error(`Slug not found for segment “${identification.label}”`);
+	if (slug == null) throw new Error(`Slug not found for segment (${formatRawResourceMetadata(segmentResource)})`);
 	const returnSegment = {
 		uuid: segmentResource.uuid,
 		type: "segment",
@@ -4761,7 +4956,7 @@ function parseWebSegmentItem(segmentItemResource, slugPrefix) {
 	if (webpageProperties.length === 0 || getPropertyValueContentByLabel(webpageProperties, "presentation") !== "segment-item") return null;
 	const identification = parseIdentification(segmentItemResource.identification);
 	const slug = segmentItemResource.identification.abbreviation != null ? parseFakeStringOrContent(segmentItemResource.identification.abbreviation) : null;
-	if (slug == null) throw new Error(`Slug not found for segment item “${identification.label}”`);
+	if (slug == null) throw new Error(`Slug not found for segment item (${formatRawResourceMetadata(segmentItemResource)})`);
 	const returnSegmentItem = {
 		uuid: segmentItemResource.uuid,
 		type: "segment-item",
@@ -4987,9 +5182,9 @@ function parseWebBlock(blockResource) {
 		for (const resource of blockResources) {
 			const resourceProperties = resource.properties ? parseProperties(ensureArray(resource.properties.property)) : [];
 			const resourceType = getPropertyValueContentByLabel(resourceProperties, "presentation");
-			if (resourceType !== "element") throw new Error(`Accordion only accepts elements, but got “${resourceType}” for the following resource: “${parseStringContent(resource.identification.label)}”`);
+			if (resourceType !== "element") throw new Error(`Accordion only accepts elements, but got “${resourceType}” (${formatRawResourceMetadata(resource)})`);
 			const componentType = getPropertyValueContentByLabel(getPropertyByLabel(resourceProperties, "presentation")?.properties ?? [], "component");
-			if (componentType !== "text") throw new Error(`Accordion only accepts text components, but got “${componentType}” for the following resource: “${parseStringContent(resource.identification.label)}”`);
+			if (componentType !== "text") throw new Error(`Accordion only accepts text components, but got “${componentType}” (${formatRawResourceMetadata(resource)})`);
 			const element = parseWebElementForAccordion(resource);
 			accordionItems.push(element);
 		}
@@ -5088,7 +5283,7 @@ function parseWebsiteProperties(properties, websiteTree, sidebar) {
 			name: contactContent[0],
 			email: contactContent[1] ?? null
 		};
-		else throw new Error(`Contact property must be in the format “name;email”, but got “${contactProperty.values[0]?.content}”`);
+		else throw new Error(`Contact property must use “name;email”, got “${contactProperty.values[0]?.content}” (website uuid “${websiteTree.uuid}”)`);
 	}
 	returnProperties.loadingVariant = getPropertyValueContentByLabel(websiteProperties, "loading-variant") ?? "spinner";
 	returnProperties.theme.isThemeToggleDisplayed = getPropertyValueContentByLabel(websiteProperties, "supports-theme-toggle") ?? true;
@@ -5208,8 +5403,8 @@ function parseFilterContexts(filterContextLevels) {
 	return filterContextTreeLevels;
 }
 function parseWebsite(websiteTree, metadata, belongsTo, { version = 2 } = {}) {
-	if (!websiteTree.properties) throw new Error("Website properties not found");
-	if (typeof websiteTree.items === "string" || !("resource" in websiteTree.items)) throw new Error("Website pages not found");
+	if (!websiteTree.properties) throw new Error(`Website properties not found (website uuid “${websiteTree.uuid}”)`);
+	if (typeof websiteTree.items === "string" || !("resource" in websiteTree.items)) throw new Error(`Website pages not found (website uuid “${websiteTree.uuid}”)`);
 	const resources = ensureArray(websiteTree.items.resource);
 	const items = [...parseWebpages(resources), ...parseSegments(resources)];
 	const sidebar = parseSidebar(resources);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "0.22.19",
+  "version": "0.22.21",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -46,7 +46,7 @@
     "@date-fns/utc": "^2.1.1",
     "date-fns": "^4.1.0",
     "fast-equals": "^6.0.0",
-    "zod": "^4.3.6"
+    "zod": "^4.4.1"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^8.2.0",
@@ -54,9 +54,9 @@
     "bumpp": "^11.0.1",
     "eslint": "^10.2.1",
     "prettier": "^3.8.3",
-    "tsdown": "^0.21.9",
+    "tsdown": "^0.21.10",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.5"
   },
   "scripts": {
     "dev": "tsdown src/index.ts --watch",