@digitalculture/ochre-sdk 0.17.7 → 0.17.8

package/dist/index.d.mts

@@ -899,6 +899,7 @@ type WebElementComponent = {
   component: "network-graph";
 } | {
   component: "query";
+  itemCategory: "resource" | "spatialUnit" | "concept" | "text";
   queries: Array<{
     label: string;
     propertyUuids: Array<string>;
@@ -1096,28 +1097,31 @@ declare function fetchItem<T extends DataCategory = DataCategory, U extends Data
   itemCategories: never;
 }>;
 //#endregion
-//#region src/utils/fetchers/items-by-property-value.d.ts
+//#region src/utils/fetchers/items-by-property-values.d.ts
 /**
- * Fetches and parses items by property value from the OCHRE API
+ * Fetches and parses items by property values from the OCHRE API
  *
  * @param params - The parameters for the fetch
- * @param params.scopeUuids - The scope UUIDs to filter by
  * @param params.propertyVariableUuids - The property variable UUIDs to query by
- * @param params.propertyValueUuids - The property value 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 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
  * @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
- * @returns The parsed items by property value or null if the fetch/parse fails
+ * @returns The parsed items by property values or null if the fetch/parse fails
  */
-declare function fetchItemsByPropertyValue<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(params: {
-  scopeUuids: Array<string>;
+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: {
   propertyVariableUuids: Array<string>;
-  propertyValueUuids: Array<string>;
+  propertyValues: Array<{
+    dataType: Exclude<PropertyValueContentType, "coordinate">;
+    value: string;
+  }>;
   projectScopeUuid: string;
+  belongsToCollectionScopeUuids: Array<string>;
 }, categoryParams?: {
   category?: T;
   itemCategories?: U;
@@ -1132,9 +1136,9 @@ declare function fetchItemsByPropertyValue<T extends DataCategory = DataCategory
   error: string;
 }>;
 //#endregion
-//#region src/utils/fetchers/property-query.d.ts
+//#region src/utils/fetchers/property-values-by-property-variables.d.ts
 /**
- * Fetches and parses a property query from the OCHRE API
+ * Fetches and parses property values by property variables from the OCHRE API
  *
  * @param params - The parameters for the fetch
  * @param params.scopeUuids - The scope UUIDs to filter by
@@ -1143,23 +1147,9 @@ declare function fetchItemsByPropertyValue<T extends DataCategory = DataCategory
  * @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
- * @returns The parsed property query or null if the fetch/parse fails
- *
- * @example
- * ```ts
- * const propertyQuery = await fetchPropertyQuery(["0c0aae37-7246-495b-9547-e25dbf5b99a3"], ["9c4da06b-f15e-40af-a747-0933eaf3587e"]);
- * if (propertyQuery === null) {
- *   console.error("Failed to fetch property query");
- *   return;
- * }
- * console.log(`Fetched property query: ${propertyQuery.item}`);
- * ```
- *
- * @remarks
- * The returned property query includes:
- * - Property items
+ * @returns The parsed property values by property variables or null if the fetch/parse fails
  */
-declare function fetchPropertyQuery(params: {
+declare function fetchPropertyValuesByPropertyVariables(params: {
   scopeUuids: Array<string>;
   propertyUuids: Array<string>;
   projectScopeUuid: string;
@@ -1407,4 +1397,4 @@ declare const DEFAULT_API_VERSION = 2;
  */
 declare function flattenItemProperties<T extends DataCategory = DataCategory, U extends DataCategory | Array<DataCategory> = (T extends "tree" ? Exclude<DataCategory, "tree"> : T extends "set" ? Array<DataCategory> : never)>(item: Item<T, U>): Item<T, U>;
 //#endregion
-export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, 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, fetchItemsByPropertyValue, fetchPropertyQuery, fetchWebsite, filterProperties, flattenItemProperties, 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, 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, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -2519,6 +2519,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 		case "network-graph": break;
 		case "query": {
 			const queries = [];
+			const itemCategory = getPropertyValueByLabel(componentProperty.properties, "item-category");
 			const queryProperties = componentProperty.properties;
 			if (queryProperties.length === 0) throw new Error(`Query properties not found for the following component: “${componentName}”`);
 			for (const query of queryProperties) {
@@ -2543,6 +2544,7 @@ function parseWebElementProperties(componentProperty, elementResource) {
 			paginationVariant ??= "default";
 			let layout = getPropertyValueByLabel(componentProperty.properties, "layout");
 			layout ??= "image-start";
+			properties.itemCategory = itemCategory;
 			properties.queries = queries;
 			properties.displayedProperties = displayedProperties?.values.map((value) => ({
 				uuid: value.uuid,
@@ -3476,24 +3478,36 @@ async function fetchItem(uuid, category, itemCategories, options) {
 }
 
 //#endregion
-//#region src/utils/fetchers/items-by-property-value.ts
+//#region src/utils/fetchers/items-by-property-values.ts
 /**
-* Build an XQuery string to fetch items by property value from the OCHRE API
-* @param scopeUuids - An array of scope UUIDs to filter by
-* @param propertyVariableUuids - An array of property variable UUIDs to fetch
-* @param propertyValueUuids - An array of property value UUIDs to fetch
-* @param projectScopeUuid - The UUID of the project scope
+* Build an XQuery string to fetch items by property values 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.propertyVariableUuids - An array of property variable UUIDs to fetch
+* @param params.propertyValues - An array of property values 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(scopeUuids, propertyVariableUuids, propertyValueUuids, projectScopeUuid, options) {
+function buildXQuery$1(params, options) {
 	const version = options?.version ?? DEFAULT_API_VERSION;
-	let collectionScopeFilter = "";
-	if (scopeUuids.length > 0) collectionScopeFilter = `[properties/property[label/@uuid="${BELONG_TO_COLLECTION_UUID}"][value[${scopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")}]]]`;
+	const { propertyVariableUuids, propertyValues, projectScopeUuid, belongsToCollectionScopeUuids } = 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 propertyValues = propertyValueUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ");
-	return `<ochre>{${`for $q in ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]/*${collectionScopeFilter}/properties//property[label[${propertyVariables}]][value[${propertyValues}]]
+	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}"]`;
+		return `value="${value}"`;
+	}).join(" or ");
+	return `<ochre>{${`let $matches := ${version === 2 ? "doc()" : "input()"}/ochre[@uuidBelongsTo="${projectScopeUuid}"]/*${belongsToCollectionScopeFilter}/properties//property[label[${propertyVariables}]][${propertyValuesFilters}]
+
+let $items := $matches/ancestor::*[parent::ochre]
+let $unique-uuids := distinct-values($items/@uuid)
 
-let $item := $q/ancestor::*[parent::ochre]
+for $uuid in $unique-uuids
+let $item := $items[@uuid = $uuid][1]
 let $category := local-name($item)
 
 return element { node-name($item) } {
@@ -3502,28 +3516,33 @@ return element { node-name($item) } {
 }`}}</ochre>`;
 }
 /**
-* Fetches and parses items by property value from the OCHRE API
+* Fetches and parses items by property values from the OCHRE API
 *
 * @param params - The parameters for the fetch
-* @param params.scopeUuids - The scope UUIDs to filter by
 * @param params.propertyVariableUuids - The property variable UUIDs to query by
-* @param params.propertyValueUuids - The property value 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 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
 * @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
-* @returns The parsed items by property value or null if the fetch/parse fails
+* @returns The parsed items by property values or null if the fetch/parse fails
 */
-async function fetchItemsByPropertyValue(params, categoryParams, options) {
+async function fetchItemsByPropertyValues(params, categoryParams, options) {
 	try {
 		const customFetch = options?.customFetch;
 		const version = options?.version ?? DEFAULT_API_VERSION;
-		const { scopeUuids, propertyVariableUuids, propertyValueUuids, projectScopeUuid } = params;
+		const { propertyVariableUuids, propertyValues, projectScopeUuid, belongsToCollectionScopeUuids } = params;
 		const { category, itemCategories } = categoryParams ?? {};
-		const xquery = buildXQuery$1(scopeUuids, propertyVariableUuids, propertyValueUuids, projectScopeUuid, { version });
+		const xquery = buildXQuery$1({
+			projectScopeUuid,
+			belongsToCollectionScopeUuids,
+			propertyVariableUuids,
+			propertyValues
+		}, { 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();
@@ -3579,15 +3598,15 @@ async function fetchItemsByPropertyValue(params, categoryParams, options) {
 		console.error(error);
 		return {
 			items: null,
-			error: error instanceof Error ? error.message : "Failed to fetch items by property value"
+			error: error instanceof Error ? error.message : "Failed to fetch items by property values"
 		};
 	}
 }
 
 //#endregion
-//#region src/utils/fetchers/property-query.ts
+//#region src/utils/fetchers/property-values-by-property-variables.ts
 /**
-* Schema for a single item in the OCHRE API response
+* Schema for a single property value by property variable item in the OCHRE API response
 */
 const responseItemSchema = z.object({
 	property: uuidSchema,
@@ -3606,11 +3625,11 @@ const responseItemSchema = z.object({
 	})
 });
 /**
-* Schema for the OCHRE API response
+* 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)]) }) }) });
 /**
-* Build an XQuery string to fetch property query items from the OCHRE API
+* Build an XQuery string to fetch property values by property variables from the OCHRE API
 * @param scopeUuids - An array of scope UUIDs to filter by
 * @param propertyUuids - An array of property UUIDs to fetch
 * @param projectScopeUuid - The UUID of the project scope
@@ -3624,12 +3643,12 @@ function buildXQuery(scopeUuids, propertyUuids, projectScopeUuid, options) {
 	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]/content[1]/string/text()} </value>
+<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>`;
 }
 /**
-* Fetches and parses a property query from the OCHRE API
+* Fetches and parses property values by property variables from the OCHRE API
 *
 * @param params - The parameters for the fetch
 * @param params.scopeUuids - The scope UUIDs to filter by
@@ -3638,23 +3657,9 @@ return <item>
 * @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
-* @returns The parsed property query or null if the fetch/parse fails
-*
-* @example
-* ```ts
-* const propertyQuery = await fetchPropertyQuery(["0c0aae37-7246-495b-9547-e25dbf5b99a3"], ["9c4da06b-f15e-40af-a747-0933eaf3587e"]);
-* if (propertyQuery === null) {
-*   console.error("Failed to fetch property query");
-*   return;
-* }
-* console.log(`Fetched property query: ${propertyQuery.item}`);
-* ```
-*
-* @remarks
-* The returned property query includes:
-* - Property items
+* @returns The parsed property values by property variables or null if the fetch/parse fails
 */
-async function fetchPropertyQuery(params, options) {
+async function fetchPropertyValuesByPropertyVariables(params, options) {
 	try {
 		const customFetch = options?.customFetch;
 		const version = options?.version ?? DEFAULT_API_VERSION;
@@ -3696,7 +3701,7 @@ async function fetchPropertyQuery(params, options) {
 		console.error(error);
 		return {
 			items: null,
-			error: error instanceof Error ? error.message : "Failed to fetch property query"
+			error: error instanceof Error ? error.message : "Failed to fetch property values by property variables"
 		};
 	}
 }
@@ -3842,4 +3847,4 @@ async function fetchWebsite(abbreviation, options) {
 }
 
 //#endregion
-export { DEFAULT_API_VERSION, fetchByUuidMetadata, fetchGallery, fetchItem, fetchItemsByPropertyValue, fetchPropertyQuery, fetchWebsite, filterProperties, flattenItemProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { DEFAULT_API_VERSION, fetchByUuidMetadata, fetchGallery, fetchItem, fetchItemsByPropertyValues, fetchPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getPropertyByLabel, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/package.json

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