ochre-sdk 0.20.5 → 0.20.7

package/dist/index.d.mts

@@ -1231,6 +1231,12 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
 }>;
 //#endregion
 //#region src/utils/fetchers/set/property-values-by-property-variables.d.ts
+type SetPropertyValuesByPropertyVariablesTitleQueryInput = {
+  value: string;
+  matchMode: "includes" | "exact";
+  isCaseSensitive: boolean;
+  language?: string;
+};
 /**
  * Fetches and parses Set property values by property variables from the OCHRE API
  *
@@ -1238,6 +1244,7 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
  * @param params.setScopeUuids - An array of set scope UUIDs to filter by
  * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
  * @param params.propertyVariableUuids - The property variable UUIDs to query by
+ * @param params.titleQuery - Title query to filter returned items by item title
  * @param params.isLimitedToLeafPropertyValues - Whether to limit the property values to leaf property values
  * @param options - Options for the fetch
  * @param options.fetch - The fetch function to use
@@ -1248,15 +1255,18 @@ declare function fetchSetPropertyValuesByPropertyVariables(params: {
   setScopeUuids: Array<string>;
   belongsToCollectionScopeUuids: Array<string>;
   propertyVariableUuids: Array<string>;
+  titleQuery?: SetPropertyValuesByPropertyVariablesTitleQueryInput;
   isLimitedToLeafPropertyValues?: boolean;
 }, options?: {
   fetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
   version?: ApiVersion;
 }): Promise<{
   propertyValues: Array<PropertyValueQueryItem> | null;
+  propertyValuesByPropertyVariableUuid: Record<string, Array<PropertyValueQueryItem>> | null;
   error: null;
 } | {
   propertyValues: null;
+  propertyValuesByPropertyVariableUuid: null;
   error: string;
 }>;
 //#endregion

package/dist/index.mjs

@@ -767,6 +767,12 @@ const setPropertyValuesByPropertyVariablesParamsSchema = z.object({
 	setScopeUuids: z.array(uuidSchema).min(1, "At least one set scope UUID is required"),
 	belongsToCollectionScopeUuids: z.array(uuidSchema).default([]),
 	propertyVariableUuids: z.array(uuidSchema).min(1, "At least one property variable UUID is required"),
+	titleQuery: z.object({
+		value: z.string(),
+		matchMode: z.enum(["includes", "exact"]),
+		isCaseSensitive: z.boolean(),
+		language: z.string().default("eng")
+	}).strict().optional(),
 	isLimitedToLeafPropertyValues: z.boolean().default(false)
 });
 const setItemsParamsSchema = z.object({
@@ -2109,7 +2115,7 @@ async function fetchItem(uuid, category, itemCategories, options) {
 * @param params.isCaseSensitive - Whether to match case-sensitively
 * @returns The string match predicate
 */
-function buildStringMatchPredicate(params) {
+function buildStringMatchPredicate$1(params) {
 	const { path, value, matchMode, isCaseSensitive } = params;
 	const comparedPath = isCaseSensitive ? path : `lower-case(${path})`;
 	const comparedValueLiteral = stringLiteral(isCaseSensitive ? value : value.toLowerCase());
@@ -2138,7 +2144,7 @@ function buildPropertyValuePredicate(query) {
 		to: query.to
 	})}]`;
 	if (query.dataType === "time" || query.dataType === "integer" || query.dataType === "decimal" || query.dataType === "boolean") return `.//properties//property[value[@rawValue=${stringLiteral(query.value)}]]`;
-	return `.//properties//property[${buildStringMatchPredicate({
+	return `.//properties//property[${buildStringMatchPredicate$1({
 		path: `string-join(value/content[@xml:lang="${query.language}"]/string, "")`,
 		value: query.value,
 		matchMode: query.matchMode,
@@ -2152,31 +2158,31 @@ function buildPropertyValuePredicate(query) {
 */
 function buildQueryPredicate(query) {
 	switch (query.target) {
-		case "title": return buildStringMatchPredicate({
+		case "title": return buildStringMatchPredicate$1({
 			path: `string-join(identification/label/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive
 		});
-		case "description": return buildStringMatchPredicate({
+		case "description": return buildStringMatchPredicate$1({
 			path: `string-join(description/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive
 		});
-		case "periods": return buildStringMatchPredicate({
+		case "periods": return buildStringMatchPredicate$1({
 			path: `string-join(periods/period/identification/label/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive
 		});
-		case "bibliography": return buildStringMatchPredicate({
+		case "bibliography": return buildStringMatchPredicate$1({
 			path: `string-join(bibliographies/bibliography/identification/label/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
 			isCaseSensitive: query.isCaseSensitive
 		});
-		case "image": return buildStringMatchPredicate({
+		case "image": return buildStringMatchPredicate$1({
 			path: `string-join(image/identification/label/content[@xml:lang="${query.language}"]/string, "")`,
 			value: query.value,
 			matchMode: query.matchMode,
@@ -2343,11 +2349,88 @@ async function fetchSetItems(params, itemCategories, options) {
 
 //#endregion
 //#region src/utils/fetchers/set/property-values-by-property-variables.ts
+function parsePropertyValueLabel(content) {
+	if (content == null || content === "") return null;
+	if (typeof content === "object") return parseStringContent({ content });
+	return parseFakeString(content);
+}
+function parsePropertyValueBooleanContent(rawValue) {
+	if (rawValue == null || rawValue === "") return null;
+	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) => {
+		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;
+	});
+}
+/**
+* Build a string match predicate for an XQuery string
+* @param params - The parameters for the predicate
+* @param params.path - The path to the string
+* @param params.value - The value to match
+* @param params.matchMode - The match mode (includes or exact)
+* @param params.isCaseSensitive - Whether to match case-sensitively
+* @returns The string match predicate
+*/
+function buildStringMatchPredicate(params) {
+	const { path, value, matchMode, isCaseSensitive } = params;
+	const comparedPath = isCaseSensitive ? path : `lower-case(${path})`;
+	const comparedValueLiteral = stringLiteral(isCaseSensitive ? value : value.toLowerCase());
+	if (matchMode === "includes") return `contains(${comparedPath}, ${comparedValueLiteral})`;
+	return `${comparedPath} = ${comparedValueLiteral}`;
+}
+/**
+* Build a title predicate for an XQuery string
+* @param titleQuery - The title query
+* @returns The title predicate
+*/
+function buildTitlePredicate(titleQuery) {
+	return buildStringMatchPredicate({
+		path: `string-join(identification/label/content[@xml:lang="${titleQuery.language}"]/string, "")`,
+		value: titleQuery.value,
+		matchMode: titleQuery.matchMode,
+		isCaseSensitive: titleQuery.isCaseSensitive
+	});
+}
 /**
 * Schema for a single property value query item in the OCHRE API response
 */
 const propertyValueQueryItemSchema = z.object({
 	uuid: z.string(),
+	variableUuid: z.string().optional(),
 	itemUuid: z.string().optional(),
 	dataType: z.string(),
 	rawValue: fakeStringSchema.optional(),
@@ -2358,6 +2441,7 @@ const propertyValueQueryItemSchema = z.object({
 	]).optional()
 }).transform((val) => {
 	const returnValue = {
+		variableUuid: val.variableUuid != null && val.variableUuid !== "" ? val.variableUuid : null,
 		itemUuid: val.itemUuid != null && val.itemUuid !== "" ? val.itemUuid : null,
 		dataType: val.dataType,
 		content: null,
@@ -2366,21 +2450,24 @@ const propertyValueQueryItemSchema = z.object({
 	switch (val.dataType) {
 		case "IDREF":
 			returnValue.content = val.uuid !== "" ? val.uuid : null;
-			returnValue.label = val.content != null && val.content !== "" ? typeof val.content === "object" ? parseStringContent({ content: val.content }) : parseFakeString(val.content) : null;
+			returnValue.label = parsePropertyValueLabel(val.content);
 			break;
 		case "integer":
 		case "decimal":
 		case "time":
-			returnValue.content = val.rawValue != null && val.rawValue !== "" ? Number(val.rawValue) : null;
-			returnValue.label = val.content != null && val.content !== "" ? val.content.toString() : null;
+			if (val.rawValue != null && val.rawValue !== "") {
+				const numericContent = Number(val.rawValue);
+				returnValue.content = Number.isNaN(numericContent) ? null : numericContent;
+			}
+			returnValue.label = parsePropertyValueLabel(val.content);
 			break;
 		case "boolean":
-			returnValue.content = val.rawValue != null && val.rawValue !== "" ? Boolean(val.rawValue) : null;
-			returnValue.label = val.content != null && val.content !== "" ? val.content.toString() : null;
+			returnValue.content = parsePropertyValueBooleanContent(val.rawValue);
+			returnValue.label = parsePropertyValueLabel(val.content);
 			break;
 		default:
 			returnValue.content = val.rawValue != null && val.rawValue !== "" ? val.rawValue.toString() : null;
-			returnValue.label = val.content != null && val.content !== "" ? val.content.toString() : null;
+			returnValue.label = parsePropertyValueLabel(val.content);
 			break;
 	}
 	return returnValue;
@@ -2395,6 +2482,7 @@ const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 * @param params.setScopeUuids - An array of set scope UUIDs to filter by
 * @param params.belongsToCollectionScopeUuids - An array of collection scope UUIDs to filter by
 * @param params.propertyVariableUuids - An array of property variable UUIDs to fetch
+* @param params.titleQuery - Title query to filter returned items by item title
 * @param params.isLimitedToLeafPropertyValues - Whether to limit the property values to leaf property values
 * @param options - Options for the fetch
 * @param options.version - The version of the OCHRE API to use
@@ -2402,20 +2490,28 @@ const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 */
 function buildXQuery(params, options) {
 	const version = options?.version ?? DEFAULT_API_VERSION;
-	const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, isLimitedToLeafPropertyValues } = params;
-	let setScopeFilter = "";
-	if (setScopeUuids.length > 0) setScopeFilter = `/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items`;
-	let collectionScopeFilter = "";
-	if (belongsToCollectionScopeUuids.length > 0) collectionScopeFilter = `//properties[property[label/@uuid="${BELONGS_TO_COLLECTION_UUID}" and value/(${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]]`;
+	const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, titleQuery, isLimitedToLeafPropertyValues } = params;
+	let setScopeFilter = "/set/items/*";
+	if (setScopeUuids.length > 0) setScopeFilter = `/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items/*`;
 	const propertyVariableFilters = propertyVariableUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
-	return `<ochre>{${`let $matching-props := ${version === 2 ? "doc()" : "input()"}/ochre
+	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 (titleQuery != null) filterPredicates.push(buildTitlePredicate(titleQuery));
+	const itemFilters = filterPredicates.length > 0 ? `[${filterPredicates.join(" and ")}]` : "";
+	return `<ochre>{${`let $items := ${version === 2 ? "doc()" : "input()"}/ochre
       ${setScopeFilter}
-      ${collectionScopeFilter}
-      //property[label/(${propertyVariableFilters})]
+      ${itemFilters}
 
-  for $v in $matching-props/value${isLimitedToLeafPropertyValues ? "[not(@i)]" : ""}
+  let $matching-props := $items//property[label/(${propertyVariableFilters})]
+
+  for $p in $matching-props
+  for $v in $p/value${isLimitedToLeafPropertyValues ? "[not(@i)]" : ""}
     let $item-uuid := $v/ancestor::*[parent::items]/@uuid
-    return <propertyValue uuid="{$v/@uuid}" rawValue="{$v/@rawValue}" dataType="{$v/@dataType}" itemUuid="{$item-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"]/string, "") else $v/text()
     }</propertyValue>`}}</ochre>`;
 }
@@ -2426,6 +2522,7 @@ function buildXQuery(params, options) {
 * @param params.setScopeUuids - An array of set scope UUIDs to filter by
 * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
 * @param params.propertyVariableUuids - The property variable UUIDs to query by
+* @param params.titleQuery - Title query to filter returned items by item title
 * @param params.isLimitedToLeafPropertyValues - Whether to limit the property values to leaf property values
 * @param options - Options for the fetch
 * @param options.fetch - The fetch function to use
@@ -2435,11 +2532,12 @@ function buildXQuery(params, options) {
 async function fetchSetPropertyValuesByPropertyVariables(params, options) {
 	try {
 		const version = options?.version ?? DEFAULT_API_VERSION;
-		const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, isLimitedToLeafPropertyValues } = setPropertyValuesByPropertyVariablesParamsSchema.parse(params);
+		const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, titleQuery, isLimitedToLeafPropertyValues } = setPropertyValuesByPropertyVariablesParamsSchema.parse(params);
 		const xquery = buildXQuery({
 			setScopeUuids,
 			belongsToCollectionScopeUuids,
 			propertyVariableUuids,
+			titleQuery,
 			isLimitedToLeafPropertyValues
 		}, { version });
 		const response = await (options?.fetch ?? fetch)(version === 2 ? `https://ochre.lib.uchicago.edu/ochre/v2/ochre.php?xquery=${encodeURIComponent(xquery)}&format=json&lang="*"` : `https://ochre.lib.uchicago.edu/ochre?xquery=${encodeURIComponent(xquery)}&format=json&lang="*"`);
@@ -2448,36 +2546,34 @@ async function fetchSetPropertyValuesByPropertyVariables(params, options) {
 		const parsedResultRaw = responseSchema.parse(data);
 		if (Array.isArray(parsedResultRaw.result)) throw new TypeError("No property values found");
 		const parsedPropertyValues = Array.isArray(parsedResultRaw.result.ochre.propertyValue) ? parsedResultRaw.result.ochre.propertyValue : [parsedResultRaw.result.ochre.propertyValue];
-		const groupedPropertyValuesMap = /* @__PURE__ */ new Map();
+		const propertyValuesByPropertyVariableUuidRaw = {};
+		const flattenedPropertyValues = [];
 		for (const propertyValue of parsedPropertyValues) {
-			const existing = groupedPropertyValuesMap.get(propertyValue.content);
-			if (existing == null) groupedPropertyValuesMap.set(propertyValue.content, {
+			const aggregatePropertyValueItem = {
+				itemUuid: propertyValue.itemUuid,
 				dataType: propertyValue.dataType,
 				content: propertyValue.content,
-				label: propertyValue.label,
-				itemUuids: new Set([propertyValue.itemUuid])
-			});
-			else existing.itemUuids.add(propertyValue.itemUuid);
+				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 groupedPropertyValues = [];
-		for (const group of groupedPropertyValuesMap.values()) groupedPropertyValues.push({
-			count: group.itemUuids.size,
-			dataType: group.dataType,
-			content: group.content,
-			label: group.label
-		});
 		return {
-			propertyValues: groupedPropertyValues.filter((propertyValue) => propertyValue.content !== null).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;
-			}),
+			propertyValues: aggregatePropertyValues(flattenedPropertyValues),
+			propertyValuesByPropertyVariableUuid,
 			error: null
 		};
 	} catch (error) {
 		console.error(error);
 		return {
 			propertyValues: null,
+			propertyValuesByPropertyVariableUuid: null,
 			error: error instanceof Error ? error.message : "Failed to fetch property values by property variables"
 		};
 	}

package/package.json

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