ochre-sdk 0.20.12 → 0.20.13

package/dist/index.d.mts

@@ -643,6 +643,26 @@ type PropertyValueQueryItem = {
   content: string | number | boolean | null;
   label: string | null;
 };
+/**
+ * Represents sorting direction for Set items
+ */
+type SetItemsSortDirection = "asc" | "desc";
+/**
+ * Represents sorting options for Set items
+ */
+type SetItemsSort = {
+  target: "none";
+} | {
+  target: "title";
+  direction?: SetItemsSortDirection;
+  language?: string;
+} | {
+  target: "propertyValue";
+  propertyVariableUuid: string;
+  dataType: Exclude<PropertyValueContentType, "coordinate">;
+  direction?: SetItemsSortDirection;
+  language?: string;
+};
 /**
  * Represents a query for Set items
  */
@@ -1198,6 +1218,8 @@ declare function fetchItem<T extends DataCategory = DataCategory, U extends Data
  * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
  * @param params.propertyVariableUuids - The property variable UUIDs to filter by
  * @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+ * @param params.sort - Optional sorting configuration applied before pagination.
+ * For propertyValue sorting, dataType is required and the sort key uses the first valid leaf value (value[not(@i)]).
  * @param params.page - The page number (1-indexed)
  * @param params.pageSize - The number of items per page
  * @param itemCategories - The categories of the items to fetch
@@ -1211,6 +1233,7 @@ declare function fetchSetItems<U extends Array<DataCategory> = Array<DataCategor
   belongsToCollectionScopeUuids: Array<string>;
   propertyVariableUuids: Array<string>;
   queries: Array<Query>;
+  sort?: SetItemsSort;
   page: number;
   pageSize?: number;
 }, itemCategories?: U, options?: {
@@ -1423,4 +1446,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, 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, 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

@@ -831,6 +831,30 @@ const setQuerySchema = z.union([
 	}).strict()
 ]);
 const setQueriesSchema = z.array(setQuerySchema).default([]);
+const setItemsSortSchema = z.discriminatedUnion("target", [
+	z.object({ target: z.literal("none") }).strict(),
+	z.object({
+		target: z.literal("title"),
+		direction: z.enum(["asc", "desc"]).default("asc"),
+		language: z.string().default("eng")
+	}).strict(),
+	z.object({
+		target: z.literal("propertyValue"),
+		propertyVariableUuid: uuidSchema,
+		dataType: z.enum([
+			"string",
+			"integer",
+			"decimal",
+			"boolean",
+			"date",
+			"dateTime",
+			"time",
+			"IDREF"
+		]),
+		direction: z.enum(["asc", "desc"]).default("asc"),
+		language: z.string().default("eng")
+	}).strict()
+]).default({ target: "none" });
 function validateSetQueriesOperators(queries, ctx) {
 	for (const [index, query] of queries.entries()) if (index > 0 && query.operator == null) ctx.addIssue({
 		code: "custom",
@@ -860,6 +884,7 @@ const setItemsParamsSchema = z.object({
 	belongsToCollectionScopeUuids: z.array(uuidSchema).default([]),
 	propertyVariableUuids: z.array(uuidSchema).default([]),
 	queries: setQueriesSchema,
+	sort: setItemsSortSchema,
 	page: z.number().min(1, "Page must be positive").default(1),
 	pageSize: z.number().min(1, "Page size must be positive").default(DEFAULT_PAGE_SIZE)
 }).superRefine((value, ctx) => {
@@ -2199,12 +2224,82 @@ function buildQueryFilters(queries) {
 	return queries.map((query, index) => {
 		const clause = buildBooleanQueryClause(query);
 		if (index === 0) return clause;
-		return `${query.operator === "OR" ? "or" : "and"} ${clause}`;
+		return `${query.operator === "AND" ? "and" : "or"} ${clause}`;
 	}).join(" ");
 }
 
 //#endregion
 //#region src/utils/fetchers/set/items.ts
+function mapSortDirectionToXQuery(direction) {
+	return direction === "desc" ? "descending" : "ascending";
+}
+function buildStringOrderByClause(direction) {
+	return `($sortKey = "") ascending, lower-case($sortKey) ${direction}, $position ascending`;
+}
+function buildTypedOrderByClause(direction) {
+	return `empty($sortKey) ascending, $sortKey ${direction}, $position ascending`;
+}
+function buildPropertyValueValuePath(sort) {
+	return `$item//properties//property[label/@uuid=${stringLiteral(sort.propertyVariableUuid)}]/value[not(@i)]`;
+}
+function buildPropertyValueStringSortKeyExpression(sort) {
+	const languageLiteral = stringLiteral(sort.language ?? "eng");
+	return `string((for $v in ${buildPropertyValueValuePath(sort)}
+        let $candidate := string-join($v/content[@xml:lang=${languageLiteral}]/string, "")
+        where string-length($candidate) gt 0
+        return $candidate)[1])`;
+}
+function buildPropertyValueTypedSortKeyExpression(params) {
+	const { sort, dataType } = params;
+	const propertyValuePath = buildPropertyValueValuePath(sort);
+	switch (dataType) {
+		case "integer": return `(for $v in ${propertyValuePath}
+        let $candidate := normalize-space(string($v/@rawValue))
+        where $candidate castable as xs:integer
+        return xs:integer($candidate))[1]`;
+		case "decimal":
+		case "time": return `(for $v in ${propertyValuePath}
+        let $candidate := normalize-space(string($v/@rawValue))
+        where $candidate castable as xs:decimal
+        return xs:decimal($candidate))[1]`;
+		case "boolean": return `(for $v in ${propertyValuePath}
+        let $candidate := lower-case(normalize-space(string($v/@rawValue)))
+        where $candidate = ("true", "false", "1", "0")
+        return if ($candidate = ("true", "1")) then 1 else 0)[1]`;
+		case "date": return `(for $v in ${propertyValuePath}
+        let $candidate := normalize-space(string($v/@rawValue))
+        where $candidate castable as xs:date
+        return xs:date($candidate))[1]`;
+		case "dateTime": return `(for $v in ${propertyValuePath}
+        let $candidate := normalize-space(string($v/@rawValue))
+        where $candidate castable as xs:dateTime
+        return xs:dateTime($candidate))[1]`;
+	}
+}
+function buildPropertyValueOrderByClause(params) {
+	const { dataType, direction } = params;
+	return dataType === "string" || dataType === "IDREF" ? buildStringOrderByClause(direction) : buildTypedOrderByClause(direction);
+}
+function buildOrderedItemsClause(sort) {
+	if (sort.target === "none") return "let $orderedItems := $items";
+	const direction = mapSortDirectionToXQuery(sort.direction);
+	if (sort.target === "title") return `let $orderedItems :=
+    for $item at $position in $items
+      let $sortKey := ${`string-join($item/identification/label/content[@xml:lang=${stringLiteral(sort.language ?? "eng")}]/string, "")`}
+      stable order by ${buildStringOrderByClause(direction)}
+      return $item`;
+	return `let $orderedItems :=
+    for $item at $position in $items
+      let $sortKey := ${sort.dataType === "string" || sort.dataType === "IDREF" ? buildPropertyValueStringSortKeyExpression(sort) : buildPropertyValueTypedSortKeyExpression({
+		sort,
+		dataType: sort.dataType
+	})}
+      stable order by ${buildPropertyValueOrderByClause({
+		dataType: sort.dataType,
+		direction
+	})}
+      return $item`;
+}
 /**
 * Build an XQuery string to fetch Set items from the OCHRE API
 * @param params - The parameters for the fetch
@@ -2212,6 +2307,8 @@ function buildQueryFilters(queries) {
 * @param params.belongsToCollectionScopeUuids - An array of collection scope UUIDs to filter by
 * @param params.propertyVariableUuids - An array of property variable UUIDs to filter by
 * @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+* @param params.sort - Optional sorting configuration applied before pagination.
+* For propertyValue sorting, dataType is required and the sort key uses the first valid leaf value (value[not(@i)]).
 * @param params.page - The page number (1-indexed)
 * @param params.pageSize - The number of items per page
 * @param options - Options for the fetch
@@ -2220,7 +2317,7 @@ function buildQueryFilters(queries) {
 */
 function buildXQuery$1(params, options) {
 	const version = options?.version ?? DEFAULT_API_VERSION;
-	const { propertyVariableUuids, queries, setScopeUuids, belongsToCollectionScopeUuids, page, pageSize } = params;
+	const { propertyVariableUuids, queries, sort, setScopeUuids, belongsToCollectionScopeUuids, page, pageSize } = params;
 	const startPosition = (page - 1) * pageSize + 1;
 	const endPosition = page * pageSize;
 	const setScopeFilter = `/set[(${setScopeUuids.map((uuid) => `@uuid="${uuid}"`).join(" or ")})]/items/*`;
@@ -2236,14 +2333,16 @@ function buildXQuery$1(params, options) {
 	}
 	if (queryFilters.length > 0) filterPredicates.push(`(${queryFilters})`);
 	const itemFilters = filterPredicates.length > 0 ? `[${filterPredicates.join(" and ")}]` : "";
+	const orderedItemsClause = buildOrderedItemsClause(sort);
 	return `<ochre>{${`let $items := ${version === 2 ? "doc()" : "input()"}/ochre
         ${setScopeFilter}
         ${itemFilters}
 
   let $totalCount := count($items)
+  ${orderedItemsClause}
 
   return <items totalCount="{$totalCount}" page="${page}" pageSize="${pageSize}">{
-    for $item in $items[position() ge ${startPosition} and position() le ${endPosition}]
+    for $item in $orderedItems[position() ge ${startPosition} and position() le ${endPosition}]
       return element { node-name($item) } {
         $item/@*, $item/node()
       }
@@ -2257,6 +2356,8 @@ function buildXQuery$1(params, options) {
 * @param params.belongsToCollectionScopeUuids - The collection scope UUIDs to filter by
 * @param params.propertyVariableUuids - The property variable UUIDs to filter by
 * @param params.queries - Ordered queries to combine with AND/OR and optional NOT via negation
+* @param params.sort - Optional sorting configuration applied before pagination.
+* For propertyValue sorting, dataType is required and the sort key uses the first valid leaf value (value[not(@i)]).
 * @param params.page - The page number (1-indexed)
 * @param params.pageSize - The number of items per page
 * @param itemCategories - The categories of the items to fetch
@@ -2268,12 +2369,13 @@ function buildXQuery$1(params, options) {
 async function fetchSetItems(params, itemCategories, options) {
 	try {
 		const version = options?.version ?? DEFAULT_API_VERSION;
-		const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, queries, page, pageSize } = setItemsParamsSchema.parse(params);
+		const { setScopeUuids, belongsToCollectionScopeUuids, propertyVariableUuids, queries, sort, page, pageSize } = setItemsParamsSchema.parse(params);
 		const xquery = buildXQuery$1({
 			setScopeUuids,
 			belongsToCollectionScopeUuids,
 			propertyVariableUuids,
 			queries,
+			sort,
 			page,
 			pageSize
 		}, { version });

package/package.json

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