@digitalculture/ochre-sdk 0.17.17 → 0.18.1

package/dist/index.d.mts

@@ -599,19 +599,13 @@ type Gallery = {
   maxLength: number;
 };
 /**
- * Represents a property query item with its item and value UUIDs
+ * Represents a property query item with its UUID, raw value, count, and content
  */
-type PropertyQueryItem = {
-  value: {
-    uuid: string | null;
-    category: string | null;
-    type: string | null;
-    dataType: string | null;
-    publicationDateTime: string | null;
-    content: string;
-    label: string | null;
-  };
-  resultUuids: Array<string>;
+type PropertyValueQueryItem = {
+  uuid: string | null;
+  count: number;
+  label: string | null;
+  content: string | number | boolean | null;
 };
 /**
  * Represents a metadata object given a UUID
@@ -1114,10 +1108,11 @@ declare function fetchItem<T extends DataCategory = DataCategory, U extends Data
  * Fetches and parses items by property values from the OCHRE API
  *
  * @param params - The parameters for the fetch
- * @param params.propertyVariableUuids - The property variable UUIDs to query by
- * @param params.propertyValues - The property values to query by
  * @param params.projectScopeUuid - The UUID of the project scope
  * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
+ * @param params.propertyVariableUuids - The property variable UUIDs to query by
+ * @param params.propertyValues - The property values to query by
+ * @param params.itemCategory - The category of the items to fetch
  * @param categoryParams - The category parameters for the fetch
  * @param categoryParams.category - The category of the items to fetch
  * @param categoryParams.itemCategories - The categories of the items to fetch
@@ -1127,13 +1122,14 @@ declare function fetchItem<T extends DataCategory = DataCategory, U extends Data
  * @returns The parsed items by property values or null if the fetch/parse fails
  */
 declare function fetchItemsByPropertyValues<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(params: {
+  projectScopeUuid: string;
+  belongsToCollectionScopeUuids: Array<string>;
   propertyVariableUuids: Array<string>;
   propertyValues: Array<{
     dataType: Exclude<PropertyValueContentType, "coordinate">;
     value: string;
   }>;
-  projectScopeUuid: string;
-  belongsToCollectionScopeUuids: Array<string>;
+  itemCategory?: "resource" | "spatialUnit" | "concept" | "text";
 }, categoryParams?: {
   category?: T;
   itemCategories?: U;
@@ -1155,7 +1151,9 @@ declare function fetchItemsByPropertyValues<T extends DataCategory = DataCategor
  * @param params - The parameters for the fetch
  * @param params.projectScopeUuid - The UUID of the project scope
  * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
- * @param params.propertyUuids - The property UUIDs to query by
+ * @param params.propertyVariables - The property variables to query by
+ * @param params.propertyVariables.dataType - The data type of the property variables
+ * @param params.propertyVariables.uuids - The UUIDs of the property variables
  * @param options - Options for the fetch
  * @param options.customFetch - A custom fetch function to use instead of the default fetch
  * @param options.version - The version of the OCHRE API to use
@@ -1164,12 +1162,15 @@ declare function fetchItemsByPropertyValues<T extends DataCategory = DataCategor
 declare function fetchPropertyValuesByPropertyVariables(params: {
   projectScopeUuid: string;
   belongsToCollectionScopeUuids: Array<string>;
-  propertyUuids: Array<string>;
+  propertyVariables: {
+    dataType: Exclude<PropertyValueContentType, "coordinate">;
+    uuids: Array<string>;
+  };
 }, options?: {
   customFetch?: (input: string | URL | globalThis.Request, init?: RequestInit) => Promise<Response>;
   version: ApiVersion;
 }): Promise<{
-  items: Array<PropertyQueryItem> | null;
+  items: Array<PropertyValueQueryItem> | null;
   error: null;
 } | {
   items: null;
@@ -1415,4 +1416,4 @@ declare function flattenItemProperties<T extends DataCategory = DataCategory, U
  */
 declare function getLeafPropertyValues<T extends PropertyValueContentType = PropertyValueContentType>(propertyValues: Array<PropertyValueContent<T>>): Array<PropertyValueContent<T>>;
 //#endregion
-export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyQueryItem, PropertyValue, PropertyValueContent, PropertyValueContentType, Resource, Scope, Section, Set, SpatialUnit, Style, Text, Tree, UuidMetadata, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebTitle, Webpage, Website, fetchByUuidMetadata, fetchGallery, fetchItem, fetchItemsByPropertyValues, fetchPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, Data, DataCategory, Event, FileFormat, Gallery, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, LevelContext, LevelContextItem, License, Link, Metadata, Note, Observation, Period, Person, Property, PropertyContexts, PropertyValue, PropertyValueContent, PropertyValueContentType, PropertyValueQueryItem, Resource, Scope, Section, Set, SpatialUnit, Style, Text, Tree, UuidMetadata, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebTitle, Webpage, Website, fetchByUuidMetadata, fetchGallery, fetchItem, fetchItemsByPropertyValues, fetchPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -95,6 +95,15 @@ const richTextStringSchema = z.object({
 	lang: z.string().optional()
 });
 /**
+* Schema for validating identification
+* @internal
+*/
+const identificationSchema = z.object({
+	label: z.object({ content: richTextStringSchema }),
+	abbreviation: z.object({ content: richTextStringSchema }).optional(),
+	code: z.string().optional()
+});
+/**
 * Schema for validating filters
 * @internal
 */
@@ -3562,43 +3571,54 @@ async function fetchItem(uuid, category, itemCategories, options) {
 * @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.propertyValues - An array of property values to fetch
+* @param params.itemCategory - The category of the items to fetch
 * @param options - Options for the fetch
 * @param options.version - The version of the OCHRE API to use
 * @returns An XQuery string
 */
 function buildXQuery$1(params, options) {
 	const version = options?.version ?? DEFAULT_API_VERSION;
-	const { propertyVariableUuids, propertyValues, projectScopeUuid, belongsToCollectionScopeUuids } = params;
+	const { propertyVariableUuids, propertyValues, projectScopeUuid, belongsToCollectionScopeUuids, itemCategory } = params;
 	let belongsToCollectionScopeFilter = "";
 	if (belongsToCollectionScopeUuids.length > 0) belongsToCollectionScopeFilter = `[properties/property[label/@uuid="${BELONG_TO_COLLECTION_UUID}"][value[${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")}]]]`;
 	const propertyVariables = propertyVariableUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
 	const propertyValuesFilters = propertyValues.map(({ dataType, value }) => {
-		if (dataType === "IDREF") return `value[@uuid="${value}"]`;
-		if (dataType === "date" || dataType === "dateTime" || dataType === "time" || dataType === "integer" || dataType === "decimal" || dataType === "boolean") return `value[@rawValue="${value}"]`;
+		if (dataType === "IDREF") return `value/@uuid="${value}"`;
+		if (dataType === "date" || dataType === "dateTime" || dataType === "time" || dataType === "integer" || dataType === "decimal" || dataType === "boolean") return `value/@rawValue="${value}"`;
 		return `value="${value}"`;
 	}).join(" or ");
-	return `<ochre>{${`let $matches := ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]/*${belongsToCollectionScopeFilter}/properties//property[label[${propertyVariables}]][${propertyValuesFilters}]
+	return `<ochre>{${`let $match-uuids := distinct-values(
+    ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]
+        /*${belongsToCollectionScopeFilter}
+          [properties//property/label[${propertyVariables}]
+                               [${propertyValuesFilters}]]
+        /@uuid
+  )
+
+  let $items := ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]
+      /${itemCategory ?? "*"}[@uuid = $match-uuids
+             or bibliographies/bibliography/@uuid = $match-uuids]
 
-let $items := $matches/ancestor::*[parent::ochre]
-let $unique-uuids := distinct-values($items/@uuid)
+  let $unique-uuids := distinct-values($items/@uuid)
 
-for $uuid in $unique-uuids
-let $item := $items[@uuid = $uuid][1]
-let $category := local-name($item)
+  for $uuid in $unique-uuids
+  let $item := $items[@uuid = $uuid][1]
+  let $category := local-name($item)
 
-return element { node-name($item) } {
-  $item/@*,
-  $item/node()[not(local-name(.) = $category)]
-}`}}</ochre>`;
+  return element { node-name($item) } {
+    $item/@*,
+    $item/node()[not(local-name(.) = $category)]
+  }`}}</ochre>`;
 }
 /**
 * Fetches and parses items by property values from the OCHRE API
 *
 * @param params - The parameters for the fetch
-* @param params.propertyVariableUuids - The property variable UUIDs to query by
-* @param params.propertyValues - The property values to query by
 * @param params.projectScopeUuid - The UUID of the project scope
 * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
+* @param params.propertyVariableUuids - The property variable UUIDs to query by
+* @param params.propertyValues - The property values to query by
+* @param params.itemCategory - The category of the items to fetch
 * @param categoryParams - The category parameters for the fetch
 * @param categoryParams.category - The category of the items to fetch
 * @param categoryParams.itemCategories - The categories of the items to fetch
@@ -3611,18 +3631,19 @@ async function fetchItemsByPropertyValues(params, categoryParams, options) {
 	try {
 		const customFetch = options?.customFetch;
 		const version = options?.version ?? DEFAULT_API_VERSION;
-		const { propertyVariableUuids, propertyValues, projectScopeUuid, belongsToCollectionScopeUuids } = params;
+		const { propertyVariableUuids, propertyValues, projectScopeUuid, belongsToCollectionScopeUuids, itemCategory } = params;
 		const { category, itemCategories } = categoryParams ?? {};
 		const xquery = buildXQuery$1({
 			projectScopeUuid,
 			belongsToCollectionScopeUuids,
 			propertyVariableUuids,
-			propertyValues
+			propertyValues,
+			itemCategory
 		}, { version });
 		const response = await (customFetch ?? 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="*"`);
 		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`);
 		const data = await response.json();
-		if (Object.keys(data.result.ochre).length === 0) throw new Error("No items found");
+		if (Array.isArray(data.result) || Object.keys(data.result.ochre).length === 0) throw new Error("No items found");
 		if (category != null && data.result.ochre[category] == null) throw new Error(`No items found for category: ${category}`);
 		if ((category === "set" || category === "tree") && itemCategories != null && "items" in data.result.ochre[category] && Array.isArray(data.result.ochre[category].items) && data.result.ochre[category].items.every((item) => item.category !== itemCategories)) throw new Error(`No items found for category: ${category} and item categories: ${itemCategories}`);
 		const items = [];
@@ -3682,60 +3703,119 @@ async function fetchItemsByPropertyValues(params, categoryParams, options) {
 //#endregion
 //#region src/utils/fetchers/property-values-by-property-variables.ts
 /**
-* Schema for a single property value by property variable item in the OCHRE API response
-*/
-const responseItemSchema = z.object({
-	property: uuidSchema,
-	category: z.object({
-		uuid: uuidSchema,
-		content: z.string()
-	}),
-	value: z.object({
-		uuid: uuidSchema.optional(),
-		category: z.string().optional(),
-		type: z.string().optional(),
-		dataType: z.string().optional(),
-		publicationDateTime: z.string().optional(),
-		content: z.union([
-			z.string(),
-			z.number(),
-			z.boolean(),
-			richTextStringSchema,
-			z.array(richTextStringSchema)
-		]).optional(),
-		rawValue: z.union([
-			z.string(),
-			z.number(),
-			z.boolean()
-		]).optional()
-	})
+* Schema for a single property value query item in the OCHRE API response
+*/
+const propertyValueQueryItemSchema = z.object({
+	uuid: uuidSchema.optional().transform((val) => val ?? null),
+	count: z.number(),
+	dataType: z.string(),
+	identification: identificationSchema.optional(),
+	label: z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	]).optional().transform((val) => val?.toString() ?? null),
+	content: z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	]).optional().transform((val) => val ?? null)
+}).transform((val) => {
+	let value = val;
+	switch (val.dataType) {
+		case "IDREF":
+		case "string":
+		case "date":
+		case "dateTime":
+			value = {
+				...val,
+				content: val.content?.toString() ?? null
+			};
+			break;
+		case "integer":
+		case "decimal":
+		case "time":
+			value = {
+				...val,
+				content: val.content !== null ? Number(val.content) : null
+			};
+			break;
+		case "boolean":
+			value = {
+				...val,
+				content: val.content !== null ? Boolean(val.content) : null
+			};
+			break;
+		default:
+			value = val;
+			break;
+	}
+	if ("identification" in value && value.identification != null) {
+		const { identification, ...rest } = value;
+		value = {
+			...rest,
+			content: parseStringContent({ content: identification.label.content })
+		};
+	}
+	return value;
 });
 /**
 * Schema for the property values by property variables OCHRE API response
 */
-const responseSchema = z.object({ result: z.object({ ochre: z.object({ item: z.union([responseItemSchema, z.array(responseItemSchema)]) }) }) });
+const responseSchema = z.object({ result: z.object({ ochre: z.object({ item: z.union([propertyValueQueryItemSchema, z.array(propertyValueQueryItemSchema)]) }) }) });
 /**
 * Build an XQuery string to fetch property values by property variables from the OCHRE API
 * @param params - The parameters for the fetch
 * @param params.projectScopeUuid - The UUID of the project scope
 * @param params.belongsToCollectionScopeUuids - An array of collection scope UUIDs to filter by
-* @param params.propertyUuids - An array of property UUIDs to fetch
+* @param params.propertyVariables - An array of property variables to fetch
+* @param params.propertyVariables.dataType - The data type of the property variables
+* @param params.propertyVariables.uuids - The UUIDs of the property variables
 * @param options - Options for the fetch
 * @param options.version - The version of the OCHRE API to use
 * @returns An XQuery string
 */
 function buildXQuery(params, options) {
 	const version = options?.version ?? DEFAULT_API_VERSION;
-	const { projectScopeUuid, belongsToCollectionScopeUuids, propertyUuids } = params;
+	const { projectScopeUuid, belongsToCollectionScopeUuids, propertyVariables } = params;
 	let collectionScopeFilter = "";
 	if (belongsToCollectionScopeUuids.length > 0) collectionScopeFilter = `[properties/property[label/@uuid="${BELONG_TO_COLLECTION_UUID}"][value[${belongsToCollectionScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")}]]]`;
-	const propertyFilters = propertyUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
-	return `<ochre>{${`for $q in ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]/*${collectionScopeFilter}/properties//property[label[${propertyFilters}]]
-return <item>
-<property>{xs:string($q/label/@uuid)}</property>
-<value> {$q/*[2]/@*} {$q/*[2]/text()} {$q/*[2]/content} </value>
-<category> {$q/ancestor::node()[local-name(.)="properties"]/../@uuid}  {local-name($q/ancestor::node()[local-name(.)="properties"]/../self::node())} </category>
-</item>`}}</ochre>`;
+	const propertyVariableFilters = propertyVariables.uuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
+	const isIDREF = propertyVariables.dataType === "IDREF";
+	return `<ochre>{${`let $matching-props := ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]
+      /*${collectionScopeFilter}
+      /properties//property[label[${propertyVariableFilters}]]
+
+  let $pairs :=
+    for $prop in $matching-props
+      return <p
+        v="{$prop/${isIDREF ? "value/@uuid" : propertyVariables.dataType === "date" || propertyVariables.dataType === "dateTime" || propertyVariables.dataType === "time" || propertyVariables.dataType === "integer" || propertyVariables.dataType === "decimal" || propertyVariables.dataType === "boolean" ? "value/@rawValue" : "value"}}"
+        r="{$prop/value/@rawValue}"
+        d="{$prop/value/@dataType}"
+        i="{$prop/ancestor::*[parent::ochre]/@uuid}">
+          ${isIDREF ? "{$prop/ancestor::*[parent::ochre]/identification}" : "{$prop/value/content/string()} {$prop/value/text()}"}
+        </p>
+
+  let $distinct-vals := distinct-values($pairs/@v)
+
+  for $val in $distinct-vals
+    let $matching := $pairs[@v = $val][1]
+    let $count := count(distinct-values($pairs[@v = $val]/@i))
+    let $rawValue := string($matching/@r)
+    let $dataType := string($matching/@d)
+    ${isIDREF ? `let $identification := $matching[1]/identification
+    let $sortLabel := string($identification/label/content/string/text())
+    order by $count descending, $sortLabel ascending
+
+  return
+    <item count="{$count}" uuid="{$val}" dataType="IDREF">{$identification}</item>` : `let $content := $matching/text()
+    order by $count descending, $content ascending
+
+  return
+    if ($rawValue != "") then
+      <item count="{$count}" label="{$content}" dataType="{$dataType}">{$rawValue}</item>
+    else
+      <item count="{$count}" dataType="{$dataType}">{$content}</item>`}`}}</ochre>`;
 }
 /**
 * Fetches and parses property values by property variables from the OCHRE API
@@ -3743,7 +3823,9 @@ return <item>
 * @param params - The parameters for the fetch
 * @param params.projectScopeUuid - The UUID of the project scope
 * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
-* @param params.propertyUuids - The property UUIDs to query by
+* @param params.propertyVariables - The property variables to query by
+* @param params.propertyVariables.dataType - The data type of the property variables
+* @param params.propertyVariables.uuids - The UUIDs of the property variables
 * @param options - Options for the fetch
 * @param options.customFetch - A custom fetch function to use instead of the default fetch
 * @param options.version - The version of the OCHRE API to use
@@ -3753,42 +3835,18 @@ async function fetchPropertyValuesByPropertyVariables(params, options) {
 	try {
 		const customFetch = options?.customFetch;
 		const version = options?.version ?? DEFAULT_API_VERSION;
-		const { belongsToCollectionScopeUuids, propertyUuids, projectScopeUuid } = params;
+		const { belongsToCollectionScopeUuids, propertyVariables, projectScopeUuid } = params;
 		const xquery = buildXQuery({
 			projectScopeUuid,
 			belongsToCollectionScopeUuids,
-			propertyUuids
+			propertyVariables
 		}, { version });
 		const response = await (customFetch ?? 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="*"`);
 		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`);
 		const data = await response.json();
 		const parsedResultRaw = responseSchema.parse(data);
-		const parsedItems = Array.isArray(parsedResultRaw.result.ochre.item) ? parsedResultRaw.result.ochre.item : [parsedResultRaw.result.ochre.item];
-		const items = {};
-		for (const item of parsedItems) {
-			const categoryUuid = item.category.uuid;
-			const valueUuid = item.value.uuid;
-			const valueContent = item.value.rawValue?.toString() ?? (typeof item.value.content === "string" || typeof item.value.content === "number" || typeof item.value.content === "boolean" ? parseFakeString(item.value.content) : item.value.content != null ? parseStringContent({ content: item.value.content }) : "");
-			if (valueContent in items) items[valueContent].resultUuids.push(categoryUuid);
-			else items[valueContent] = {
-				value: {
-					uuid: valueUuid ?? null,
-					category: item.value.category ?? null,
-					type: item.value.type ?? null,
-					dataType: item.value.dataType ?? null,
-					publicationDateTime: item.value.publicationDateTime ?? null,
-					content: valueContent,
-					label: item.value.rawValue != null && item.value.content != null ? typeof item.value.content === "string" || typeof item.value.content === "number" || typeof item.value.content === "boolean" ? item.value.content.toString() : Array.isArray(item.value.content) ? item.value.content.find((content) => content.lang === "eng")?.string.toString() ?? "" : item.value.content.string.toString() : null
-				},
-				resultUuids: [categoryUuid]
-			};
-		}
 		return {
-			items: Object.values(items).toSorted((a, b) => {
-				const aValue = a.value.label ?? a.value.content;
-				const bValue = b.value.label ?? b.value.content;
-				return aValue.localeCompare(bValue, "en-US");
-			}).filter((item) => item.value.content !== ""),
+			items: (Array.isArray(parsedResultRaw.result.ochre.item) ? parsedResultRaw.result.ochre.item : [parsedResultRaw.result.ochre.item]).filter((item) => String(item.content).trim() !== ""),
 			error: null
 		};
 	} catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digitalculture/ochre-sdk",
-  "version": "0.17.17",
+  "version": "0.18.1",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -57,10 +57,10 @@
   "scripts": {
     "dev": "tsdown src/index.ts --watch",
     "build": "tsdown",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --check .",
-    "format:fix": "prettier --write --list-different .",
+    "lint": "eslint --cache .",
+    "lint:fix": "eslint --cache . --fix",
+    "format": "prettier --cache --check .",
+    "format:fix": "prettier --cache --write --list-different .",
     "check-types": "tsc --noEmit",
     "test": "vitest run",
     "release": "bumpp"