ochre-sdk 0.20.15 → 0.20.17

package/dist/index.d.mts

@@ -643,6 +643,13 @@ type PropertyValueQueryItem = {
   content: string | number | boolean | null;
   label: string | null;
 };
+/**
+ * Represents a grouped Set attribute value query item
+ */
+type SetAttributeValueQueryItem = {
+  count: number;
+  content: string;
+};
 /**
  * Represents sorting direction for Set items
  */
@@ -1262,28 +1269,41 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
  * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
  * @param params.propertyVariableUuids - The property variable UUIDs to query by
  * @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+ * @param params.attributes - Whether to return values for bibliographies and periods
+ * @param params.attributes.bibliographies - Whether to return values for bibliographies
+ * @param params.attributes.periods - Whether to return values for periods
  * @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
  * @param options.version - The version of the OCHRE API to use
- * @returns The parsed Set property values by property variables or null if the fetch/parse fails
+ * @returns Parsed Set property values and requested attribute values.
+ * Returns empty arrays/objects when no matches are found, and null outputs on fetch/parse errors.
  */
 declare function fetchSetPropertyValuesByPropertyVariables(params: {
   setScopeUuids: Array<string>;
   belongsToCollectionScopeUuids: Array<string>;
   propertyVariableUuids: Array<string>;
   queries?: Array<Query>;
+  attributes?: {
+    bibliographies: boolean;
+    periods: boolean;
+  };
   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;
+  propertyValues: Array<PropertyValueQueryItem>;
+  propertyValuesByPropertyVariableUuid: Record<string, Array<PropertyValueQueryItem>>;
+  attributeValues: {
+    bibliographies: Array<SetAttributeValueQueryItem> | null;
+    periods: Array<SetAttributeValueQueryItem> | null;
+  };
   error: null;
 } | {
   propertyValues: null;
   propertyValuesByPropertyVariableUuid: null;
+  attributeValues: null;
   error: string;
 }>;
 //#endregion
@@ -1446,4 +1466,4 @@ declare const DEFAULT_PAGE_SIZE = 48;
  */
 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, DEFAULT_PAGE_SIZE, 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, PropertyVariable, Query, Resource, Scope, Section, Set, SetItemsSort, SetItemsSortDirection, SpatialUnit, Style, Text, Tree, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebSegment, WebSegmentItem, WebTitle, Webpage, Website, WebsiteType, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };
+export { ApiVersion, Bibliography, Concept, Context, ContextItem, ContextNode, Coordinate, DEFAULT_API_VERSION, DEFAULT_PAGE_SIZE, 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, PropertyVariable, Query, Resource, Scope, Section, Set, SetAttributeValueQueryItem, SetItemsSort, SetItemsSortDirection, SpatialUnit, Style, Text, Tree, WebBlock, WebBlockLayout, WebElement, WebElementComponent, WebImage, WebSegment, WebSegmentItem, WebTitle, Webpage, Website, WebsiteType, fetchGallery, fetchItem, fetchSetItems, fetchSetPropertyValuesByPropertyVariables, fetchWebsite, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByLabel, getPropertyByLabelAndValue, getPropertyByLabelAndValues, getPropertyByUuid, getPropertyValueByLabel, getPropertyValueByUuid, getPropertyValuesByLabel, getPropertyValuesByUuid, getUniqueProperties, getUniquePropertyLabels };

package/dist/index.mjs

@@ -875,6 +875,13 @@ const setPropertyValuesByPropertyVariablesParamsSchema = z.object({
 	belongsToCollectionScopeUuids: z.array(uuidSchema).default([]),
 	propertyVariableUuids: z.array(uuidSchema).min(1, "At least one property variable UUID is required"),
 	queries: setQueriesSchema,
+	attributes: z.object({
+		bibliographies: z.boolean().default(false),
+		periods: z.boolean().default(false)
+	}).default({
+		bibliographies: false,
+		periods: false
+	}),
 	isLimitedToLeafPropertyValues: z.boolean().default(false)
 }).superRefine((value, ctx) => {
 	validateSetQueriesOperators(value.queries, ctx);
@@ -2501,6 +2508,30 @@ function aggregatePropertyValues(values) {
 		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) => {
+		if (a.count !== b.count) return b.count - a.count;
+		return a.content.localeCompare(b.content);
+	});
+}
 /**
 * Schema for a single property value query item in the OCHRE API response
 */
@@ -2548,10 +2579,22 @@ const propertyValueQueryItemSchema = z.object({
 	}
 	return returnValue;
 });
+const attributeValueQueryItemSchema = z.object({
+	attributeType: z.enum(["bibliographies", "periods"]),
+	itemUuid: z.string().optional(),
+	content: z.string().optional()
+}).transform((val) => ({
+	attributeType: val.attributeType,
+	itemUuid: val.itemUuid != null && val.itemUuid !== "" ? val.itemUuid : null,
+	content: val.content != null && val.content !== "" ? val.content : null
+}));
 /**
 * Schema for the property values by property variables OCHRE API response
 */
-const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({ propertyValue: z.union([propertyValueQueryItemSchema, z.array(propertyValueQueryItemSchema)]) }) }), z.array(z.unknown()).length(0)]) });
+const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
+	propertyValue: z.union([propertyValueQueryItemSchema, z.array(propertyValueQueryItemSchema)]).optional(),
+	attributeValue: z.union([attributeValueQueryItemSchema, z.array(attributeValueQueryItemSchema)]).optional()
+}) }), z.array(z.unknown()).length(0)]) });
 /**
 * Build an XQuery string to fetch property values by property variables from the OCHRE API
 * @param params - The parameters for the fetch
@@ -2559,6 +2602,9 @@ const responseSchema = z.object({ result: z.union([z.object({ ochre: z.object({
 * @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.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+* @param params.attributes - Whether to return values for bibliographies and periods
+* @param params.attributes.bibliographies - Whether to return values for bibliographies
+* @param params.attributes.periods - Whether to return values for periods
 * @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
@@ -2566,7 +2612,7 @@ 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, queries, isLimitedToLeafPropertyValues } = params;
+	const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, queries, attributes, 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 ");
@@ -2574,23 +2620,46 @@ function buildXQuery(params, options) {
 	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})]]`);
+		filterPredicates.push(`.//properties[property[label/@uuid="${BELONGS_TO_COLLECTION_UUID}" and value[${belongsToCollectionScopeValues}]]]`);
 	}
 	if (queryFilters.length > 0) filterPredicates.push(`(${queryFilters})`);
 	const itemFilters = filterPredicates.length > 0 ? `[${filterPredicates.join(" and ")}]` : "";
-	return `<ochre>{${`let $items := ${version === 2 ? "doc()" : "input()"}/ochre
-      ${setScopeFilter}
-      ${itemFilters}
-
-  let $matching-props := $items//property[label/(${propertyVariableFilters})]
+	const queryBlocks = [`let $matching-props := $items//property[label[${propertyVariableFilters}]]
 
+let $property-values :=
   for $p in $matching-props
   for $v in $p/value${isLimitedToLeafPropertyValues ? "[not(@i)]" : ""}
     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"]/string, "") else $v/text()
-    }</propertyValue>`}}</ochre>`;
+    }</propertyValue>`];
+	const returnedSequences = ["$property-values"];
+	if (attributes.bibliographies) {
+		queryBlocks.push(`let $bibliography-values :=
+  for $item in $items
+  for $bibliography in $item/bibliographies/bibliography
+    let $label := string-join($bibliography/identification/label/content[@xml:lang="eng"]/string, "")
+    where string-length($label) gt 0
+    return <attributeValue attributeType="bibliographies" itemUuid="{$item/@uuid}" content="{$label}" />`);
+		returnedSequences.push("$bibliography-values");
+	}
+	if (attributes.periods) {
+		queryBlocks.push(`let $period-values :=
+  for $item in $items
+  for $period in $item/periods/period
+    let $label := string-join($period/identification/label/content[@xml:lang="eng"]/string, "")
+    where string-length($label) gt 0
+    return <attributeValue attributeType="periods" itemUuid="{$item/@uuid}" content="{$label}" />`);
+		returnedSequences.push("$period-values");
+	}
+	return `<ochre>{${`let $items := ${version === 2 ? "doc()" : "input()"}/ochre
+      ${setScopeFilter}
+      ${itemFilters}
+
+${queryBlocks.join("\n\n")}
+
+return (${returnedSequences.join(", ")})`}}</ochre>`;
 }
 /**
 * Fetches and parses Set property values by property variables from the OCHRE API
@@ -2600,29 +2669,38 @@ function buildXQuery(params, options) {
 * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
 * @param params.propertyVariableUuids - The property variable UUIDs to query by
 * @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+* @param params.attributes - Whether to return values for bibliographies and periods
+* @param params.attributes.bibliographies - Whether to return values for bibliographies
+* @param params.attributes.periods - Whether to return values for periods
 * @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
 * @param options.version - The version of the OCHRE API to use
-* @returns The parsed Set property values by property variables or null if the fetch/parse fails
+* @returns Parsed Set property values and requested attribute values.
+* Returns empty arrays/objects when no matches are found, and null outputs on fetch/parse errors.
 */
 async function fetchSetPropertyValuesByPropertyVariables(params, options) {
 	try {
 		const version = options?.version ?? DEFAULT_API_VERSION;
-		const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, queries, isLimitedToLeafPropertyValues } = setPropertyValuesByPropertyVariablesParamsSchema.parse(params);
+		const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, queries, attributes, isLimitedToLeafPropertyValues } = setPropertyValuesByPropertyVariablesParamsSchema.parse(params);
 		const xquery = buildXQuery({
 			setScopeUuids,
 			belongsToCollectionScopeUuids,
 			propertyVariableUuids,
 			queries,
+			attributes,
 			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="*"`);
 		if (!response.ok) throw new Error(`OCHRE API responded with status: ${response.status}`);
 		const data = await response.json();
 		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 parsedPropertyValues = [];
+		const parsedAttributeValues = [];
+		if (!Array.isArray(parsedResultRaw.result)) {
+			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 = [];
 		for (const propertyValue of parsedPropertyValues) {
@@ -2641,9 +2719,18 @@ async function fetchSetPropertyValuesByPropertyVariables(params, options) {
 			const aggregatedValues = aggregatePropertyValues(values);
 			if (aggregatedValues.length > 0) propertyValuesByPropertyVariableUuid[propertyVariableUuid] = aggregatedValues;
 		}
+		const attributeValuesByTypeRaw = {
+			bibliographies: [],
+			periods: []
+		};
+		for (const attributeValue of parsedAttributeValues) attributeValuesByTypeRaw[attributeValue.attributeType].push(attributeValue);
 		return {
 			propertyValues: aggregatePropertyValues(flattenedPropertyValues),
 			propertyValuesByPropertyVariableUuid,
+			attributeValues: {
+				bibliographies: attributes.bibliographies ? aggregateAttributeValues(attributeValuesByTypeRaw.bibliographies) : null,
+				periods: attributes.periods ? aggregateAttributeValues(attributeValuesByTypeRaw.periods) : null
+			},
 			error: null
 		};
 	} catch (error) {
@@ -2651,6 +2738,7 @@ async function fetchSetPropertyValuesByPropertyVariables(params, options) {
 		return {
 			propertyValues: null,
 			propertyValuesByPropertyVariableUuid: null,
+			attributeValues: 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.15",
+  "version": "0.20.17",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",