ochre-sdk 1.1.1 → 1.1.2

package/README.md

@@ -66,6 +66,9 @@ present and `error` is `null`; on failure, the parsed value is `null` and
   style, collection, and item-page configuration.
 - `fetchSetItems(params, containedItemCategories, options)` fetches paginated
   Set search results with typed query and sort support.
+- `fetchTreeItems(params, containedItemCategories, options)` is the same for a
+  Tree, and is how to read a Tree too large to fetch whole. Items nested under
+  headings come back flat, in document order.
 - `fetchSetPropertyValues(params, options)` fetches Set property-value facets
   and optional bibliography/period attribute facets for the same query model.
 
@@ -149,6 +152,23 @@ const result = await fetchSetItems(
 Use `fetchSetPropertyValues` with the same query shape when you need facet data
 for a filtered result set.
 
+`fetchTreeItems` takes the same `Query` tree and the same sort options, because
+both fetchers compile the same query model against their container's searchable
+path. The difference is what the payload carries: OCHRE publishes Tree items as
+identification-only stubs unless the Tree is published with item properties, so
+a `property` query or a `propertyValue` sort only works on a Tree that carries
+them.
+
+```ts
+import { fetchTreeItems } from "ochre-sdk";
+
+const result = await fetchTreeItems(
+  { treeScopeUuids: ["<tree-uuid>"], sort: { target: "title" }, page: 1 },
+  ["concept"],
+  { languages: ["eng"] },
+);
+```
+
 ### OCR Text Queries
 
 The `ocr` target searches the OCR text layer of the Resource items in a Set. It takes no `language`, because OCR text carries none.

package/dist/fetchers/container-items.d.mts

@@ -0,0 +1,52 @@
+import { ItemCategory, Query, SetItem, SetItemsSort } from "../types/index.mjs";
+import { XMLSetItems } from "../xml/types.mjs";
+import { FetchRuntimeOptions } from "../parsers/helpers.mjs";
+//#region src/fetchers/container-items.d.ts
+/**
+ * Whether a container payload carries any item of a category
+ * @param items - The parsed `<items>` payload
+ * @param category - The category to look for
+ * @returns True when the payload carries at least one item of it
+ * @internal
+ */
+export declare function hasItemsCategory(items: XMLSetItems, category: ItemCategory): boolean;
+/**
+ * Fetch one page of the items a Set or a Tree holds
+ *
+ * The only thing that differs between the two containers is the searchable
+ * path {@link compileContainerItemsQuery} picks, so counting, sorting,
+ * paginating, validating and parsing are written once here and the public
+ * fetchers are thin wrappers that name their own scope parameter.
+ * @param parameters - The request parameters
+ * @param parameters.container - Whether the scope UUIDs name Sets or Trees
+ * @param parameters.scopeUuids - The container UUIDs to search within
+ * @param parameters.belongsToCollectionScopeUuids - Collection scope UUIDs to narrow to
+ * @param parameters.queries - The query tree to filter by, or null to match every item
+ * @param parameters.sort - The sort applied before pagination
+ * @param parameters.page - The page number, 1-indexed
+ * @param parameters.pageSize - The number of items per page
+ * @param parameters.containedItemCategories - Categories the payload must carry
+ * @param parameters.label - What is being fetched, used in failure messages
+ * @param parameters.options - Fetch and parser options
+ * @returns The page of items, deduplicated by UUID
+ * @throws When the request fails, validation fails, or a category is missing
+ * @internal
+ */
+export declare function fetchContainerItems(parameters: {
+  container: "set" | "tree";
+  scopeUuids: Array<string>;
+  belongsToCollectionScopeUuids: Array<string>;
+  queries: Query | null;
+  sort: SetItemsSort;
+  page: number;
+  pageSize: number;
+  containedItemCategories?: ReadonlyArray<ItemCategory>;
+  label: string;
+  options?: FetchRuntimeOptions;
+}): Promise<{
+  totalCount: number;
+  page: number;
+  pageSize: number;
+  items: Array<SetItem<ItemCategory, ReadonlyArray<string>>>;
+}>;
+//#endregion

package/dist/fetchers/container-items.mjs

@@ -0,0 +1,171 @@
+import { requestOchre } from "./request.mjs";
+import { parseRequestedLanguages, resolveContentLanguages } from "../parsers/languages.mjs";
+import { parseSetItems } from "../parsers/index.mjs";
+import { XMLSetItemsData } from "../xml/schemas.mjs";
+import { stringLiteral } from "../xquery.mjs";
+import { compileContainerItemsQuery } from "../query.mjs";
+//#region src/fetchers/container-items.ts
+function hasArray(items) {
+	return items != null && items.length > 0;
+}
+/**
+* Whether a container payload carries any item of a category
+* @param items - The parsed `<items>` payload
+* @param category - The category to look for
+* @returns True when the payload carries at least one item of it
+* @internal
+*/
+function hasItemsCategory(items, category) {
+	switch (category) {
+		case "tree": return hasArray(items.tree);
+		case "bibliography": return hasArray(items.bibliography);
+		case "concept": return hasArray(items.concept);
+		case "spatialUnit": return hasArray(items.spatialUnit);
+		case "period": return hasArray(items.period);
+		case "person": return hasArray(items.person);
+		case "propertyVariable": return hasArray(items.propertyVariable) || hasArray(items.variable);
+		case "propertyValue": return hasArray(items.propertyValue) || hasArray(items.value);
+		case "resource": return hasArray(items.resource);
+		case "text": return hasArray(items.text);
+		case "set": return hasArray(items.set);
+	}
+}
+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(parameters) {
+	const { sort, dataType } = parameters;
+	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(parameters) {
+	const { dataType, direction } = parameters;
+	return (dataType === "string" || dataType === "IDREF" ? buildStringOrderByClause : 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`;
+	if (sort.target === "date") return `let $orderedItems :=
+    for $item at $position in $items
+      let $sortKey := string(($item/@date, $item/interpretations/interpretation/@date)[1])
+      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`;
+}
+/**
+* Fetch one page of the items a Set or a Tree holds
+*
+* The only thing that differs between the two containers is the searchable
+* path {@link compileContainerItemsQuery} picks, so counting, sorting,
+* paginating, validating and parsing are written once here and the public
+* fetchers are thin wrappers that name their own scope parameter.
+* @param parameters - The request parameters
+* @param parameters.container - Whether the scope UUIDs name Sets or Trees
+* @param parameters.scopeUuids - The container UUIDs to search within
+* @param parameters.belongsToCollectionScopeUuids - Collection scope UUIDs to narrow to
+* @param parameters.queries - The query tree to filter by, or null to match every item
+* @param parameters.sort - The sort applied before pagination
+* @param parameters.page - The page number, 1-indexed
+* @param parameters.pageSize - The number of items per page
+* @param parameters.containedItemCategories - Categories the payload must carry
+* @param parameters.label - What is being fetched, used in failure messages
+* @param parameters.options - Fetch and parser options
+* @returns The page of items, deduplicated by UUID
+* @throws When the request fails, validation fails, or a category is missing
+* @internal
+*/
+async function fetchContainerItems(parameters) {
+	const { container, scopeUuids, belongsToCollectionScopeUuids, queries, sort, page, pageSize, containedItemCategories, label, options } = parameters;
+	const requestedLanguages = parseRequestedLanguages(options?.languages);
+	const startPosition = (page - 1) * pageSize + 1;
+	const output = await requestOchre({
+		xquery: compileContainerItemsQuery({
+			container,
+			scopeUuids,
+			belongsToCollectionScopeUuids,
+			queries,
+			body: ({ items, omitSupplemental }) => `  let $totalCount := count(${items})
+  ${buildOrderedItemsClause(sort)}
+  let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})
+
+  return <items totalCount="{$totalCount}" page="${page}" pageSize="${pageSize}">{
+    ${omitSupplemental("$pagedItems")}
+  }</items>`
+		}),
+		schema: XMLSetItemsData,
+		label,
+		options
+	});
+	if (containedItemCategories != null) {
+		const missingCategories = containedItemCategories.filter((category) => !hasItemsCategory(output.result.ochre.items, category));
+		if (missingCategories.length > 0) throw new Error(`No items found for item categories: ${missingCategories.join(", ")}`, { cause: missingCategories });
+	}
+	const parserOptions = { languages: resolveContentLanguages(output.result.ochre.items, requestedLanguages) };
+	const items = parseSetItems(output.result.ochre.items, {
+		containedItemCategories,
+		languages: parserOptions.languages
+	});
+	const itemsByUuid = /* @__PURE__ */ new Map();
+	for (const item of items) if (!itemsByUuid.has(item.uuid)) itemsByUuid.set(item.uuid, item);
+	return {
+		totalCount: output.result.ochre.items.totalCount,
+		page: output.result.ochre.items.page,
+		pageSize: output.result.ochre.items.pageSize,
+		items: itemsByUuid.values().toArray()
+	};
+}
+//#endregion
+export { fetchContainerItems, hasItemsCategory };

package/dist/fetchers/set/items.mjs

@@ -1,163 +1,24 @@
 import { getErrorOutput } from "../../errors.mjs";
-import { requestOchre } from "../request.mjs";
 import { setItemsParametersSchema } from "../../schemas.mjs";
-import { parseRequestedLanguages, resolveContentLanguages } from "../../parsers/languages.mjs";
-import { parseSetItems } from "../../parsers/index.mjs";
-import { XMLSetItemsData } from "../../xml/schemas.mjs";
-import { stringLiteral } from "../../xquery.mjs";
-import { compileSetItemsQuery } from "../../query.mjs";
+import { fetchContainerItems } from "../container-items.mjs";
 import * as v from "valibot";
 //#region src/fetchers/set/items.ts
-function hasArray(items) {
-	return items != null && items.length > 0;
-}
-function hasSetItemsCategory(items, category) {
-	switch (category) {
-		case "tree": return hasArray(items.tree);
-		case "bibliography": return hasArray(items.bibliography);
-		case "concept": return hasArray(items.concept);
-		case "spatialUnit": return hasArray(items.spatialUnit);
-		case "period": return hasArray(items.period);
-		case "person": return hasArray(items.person);
-		case "propertyVariable": return hasArray(items.propertyVariable) || hasArray(items.variable);
-		case "propertyValue": return hasArray(items.propertyValue) || hasArray(items.value);
-		case "resource": return hasArray(items.resource);
-		case "text": return hasArray(items.text);
-		case "set": return hasArray(items.set);
-	}
-}
-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(parameters) {
-	const { sort, dataType } = parameters;
-	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(parameters) {
-	const { dataType, direction } = parameters;
-	return (dataType === "string" || dataType === "IDREF" ? buildStringOrderByClause : 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 parameters - The parameters for the fetch
-* @param parameters.setScopeUuids - An array of Set scope UUIDs to filter by
-* @param parameters.belongsToCollectionScopeUuids - An array of collection scope UUIDs to filter by
-* @param parameters.queries - Recursive query tree used to filter matching items
-* @param parameters.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 parameters.page - The page number (1-indexed)
-* @param parameters.pageSize - The number of items per page
-* @returns An XQuery string
-*/
-function buildXQuery(parameters) {
-	const { queries, sort, setScopeUuids, belongsToCollectionScopeUuids, page, pageSize } = parameters;
-	const startPosition = (page - 1) * pageSize + 1;
-	return compileSetItemsQuery({
-		setScopeUuids,
-		belongsToCollectionScopeUuids,
-		queries,
-		body: ({ items, omitSupplemental }) => `  let $totalCount := count(${items})
-  ${buildOrderedItemsClause(sort)}
-  let $pagedItems := subsequence($orderedItems, ${startPosition}, ${pageSize})
-
-  return <items totalCount="{$totalCount}" page="${page}" pageSize="${pageSize}">{
-    ${omitSupplemental("$pagedItems")}
-  }</items>`
-	});
-}
 async function fetchSetItems(parameters, containedItemCategories, options) {
 	try {
 		const { setScopeUuids, belongsToCollectionScopeUuids, queries, sort, page, pageSize } = v.parse(setItemsParametersSchema, parameters);
-		const requestedLanguages = parseRequestedLanguages(options?.languages);
-		const output = await requestOchre({
-			xquery: buildXQuery({
-				setScopeUuids,
+		return {
+			...await fetchContainerItems({
+				container: "set",
+				scopeUuids: setScopeUuids,
 				belongsToCollectionScopeUuids,
 				queries,
 				sort,
 				page,
-				pageSize
+				pageSize,
+				containedItemCategories,
+				label: "OCHRE Set items",
+				options
 			}),
-			schema: XMLSetItemsData,
-			label: "OCHRE Set items",
-			options
-		});
-		if (containedItemCategories != null) {
-			const missingCategories = containedItemCategories.filter((category) => !hasSetItemsCategory(output.result.ochre.items, category));
-			if (missingCategories.length > 0) throw new Error(`No Set items found for item categories: ${missingCategories.join(", ")}`, { cause: missingCategories });
-		}
-		const languages = resolveContentLanguages(output.result.ochre.items, requestedLanguages);
-		const items = parseSetItems(output.result.ochre.items, {
-			containedItemCategories,
-			languages
-		});
-		const itemsByUuid = /* @__PURE__ */ new Map();
-		for (const item of items) if (!itemsByUuid.has(item.uuid)) itemsByUuid.set(item.uuid, item);
-		const uniqueItems = itemsByUuid.values().toArray();
-		return {
-			totalCount: output.result.ochre.items.totalCount,
-			page: output.result.ochre.items.page,
-			pageSize: output.result.ochre.items.pageSize,
-			items: uniqueItems,
 			error: null,
 			detailedError: null
 		};

package/dist/fetchers/set/property-values.mjs

@@ -5,7 +5,7 @@ import { MultilingualString } from "../../parsers/multilingual.mjs";
 import { setPropertyValuesParametersSchema } from "../../schemas.mjs";
 import { parseXMLContent } from "../../parsers/string.mjs";
 import { stringLiteral } from "../../xquery.mjs";
-import { compileSetItemsQuery, getItemFilterQueries, getPropertyFacetSelectors } from "../../query.mjs";
+import { compileContainerItemsQuery, getItemFilterQueries, getPropertyFacetSelectors } from "../../query.mjs";
 import * as v from "valibot";
 //#region src/fetchers/set/property-values.ts
 function getLabelContentLanguages(content) {
@@ -367,8 +367,9 @@ let $period-values :=
 		}
 		return queryBlocks;
 	}
-	return compileSetItemsQuery({
-		setScopeUuids,
+	return compileContainerItemsQuery({
+		container: "set",
+		scopeUuids: setScopeUuids,
 		belongsToCollectionScopeUuids,
 		queries: getItemFilterQueries(queries),
 		declarations: xqueryDeclarations,

package/dist/fetchers/tree/items.d.mts

@@ -0,0 +1,53 @@
+import { Query, SetItem, SetItemsSort, TreeItemCategory } from "../../types/index.mjs";
+import { FetchBaseOptions, FetchLanguages } from "../../parsers/helpers.mjs";
+//#region src/fetchers/tree/items.d.ts
+type FetchTreeItemsCategory<TContainedItemCategories extends ReadonlyArray<TreeItemCategory> | undefined> = TContainedItemCategories extends ReadonlyArray<infer U> ? Extract<U, TreeItemCategory> : TreeItemCategory;
+/**
+ * Fetches and parses Tree items from the OCHRE API
+ *
+ * The counterpart of {@link fetchSetItems} for a Tree, and the way to read a
+ * Tree too large to fetch whole: a Tree of tens of thousands of items is one
+ * OCHRE document, so counting, filtering and sorting run inside it rather than
+ * over one document per item.
+ *
+ * Items nested under headings are returned flat, in document order, because a
+ * heading groups items for display rather than identifying them. What the
+ * returned items carry is whatever the Tree payload carries: OCHRE publishes
+ * Tree items as identification-only stubs unless the Tree is published with
+ * item properties, so a `property` query or a `propertyValue` sort only works
+ * on a Tree that carries them.
+ *
+ * @param parameters - The parameters for the fetch
+ * @param parameters.treeScopeUuids - The Tree scope UUIDs to filter by
+ * @param parameters.queries - Recursive query tree used to filter matching items
+ * @param parameters.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 parameters.page - The page number (1-indexed)
+ * @param parameters.pageSize - The number of items per page
+ * @param containedItemCategories - The categories of the items to fetch
+ * @param options - Options for the fetch
+ * @param options.fetch - The fetch function to use
+ * @returns The parsed Tree items or null if the fetch/parse fails
+ */
+export declare function fetchTreeItems<const TContainedItemCategories extends ReadonlyArray<TreeItemCategory> | undefined = undefined, const TLanguages extends ReadonlyArray<string> | undefined = undefined>(parameters: {
+  treeScopeUuids: Array<string>;
+  queries?: Query | null;
+  sort?: SetItemsSort;
+  page: number;
+  pageSize?: number;
+}, containedItemCategories?: TContainedItemCategories, options?: FetchBaseOptions<TLanguages>): Promise<{
+  totalCount: number;
+  page: number;
+  pageSize: number;
+  items: Array<SetItem<FetchTreeItemsCategory<TContainedItemCategories>, FetchLanguages<TLanguages>>>;
+  error: null;
+  detailedError: null;
+} | {
+  totalCount: null;
+  page: null;
+  pageSize: null;
+  items: null;
+  error: string;
+  detailedError: string;
+}>;
+//#endregion

package/dist/fetchers/tree/items.mjs

@@ -0,0 +1,38 @@
+import { getErrorOutput } from "../../errors.mjs";
+import { treeItemsParametersSchema } from "../../schemas.mjs";
+import { fetchContainerItems } from "../container-items.mjs";
+import * as v from "valibot";
+//#region src/fetchers/tree/items.ts
+async function fetchTreeItems(parameters, containedItemCategories, options) {
+	try {
+		const { treeScopeUuids, belongsToCollectionScopeUuids, queries, sort, page, pageSize } = v.parse(treeItemsParametersSchema, parameters);
+		const { items, ...pagination } = await fetchContainerItems({
+			container: "tree",
+			scopeUuids: treeScopeUuids,
+			belongsToCollectionScopeUuids,
+			queries,
+			sort,
+			page,
+			pageSize,
+			containedItemCategories,
+			label: "OCHRE Tree items",
+			options
+		});
+		return {
+			...pagination,
+			items,
+			error: null,
+			detailedError: null
+		};
+	} catch (error) {
+		return {
+			totalCount: null,
+			page: null,
+			pageSize: null,
+			items: null,
+			...getErrorOutput(error, "Failed to fetch Tree items")
+		};
+	}
+}
+//#endregion
+export { fetchTreeItems };

package/dist/index.d.mts

@@ -9,9 +9,10 @@ import { fetchItemOcrData } from "./fetchers/item-ocr-data.mjs";
 import { fetchItem } from "./fetchers/item.mjs";
 import { fetchSetItems } from "./fetchers/set/items.mjs";
 import { fetchSetPropertyValues } from "./fetchers/set/property-values.mjs";
+import { fetchTreeItems } from "./fetchers/tree/items.mjs";
 import { fetchWebsiteMetadata } from "./fetchers/website-metadata.mjs";
 import { fetchWebsite } from "./fetchers/website.mjs";
 import { PropertyOptions, PropertySelector, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.mjs";
 import { flattenItemProperties } from "./helpers.mjs";
 import { defineLanguages } from "./parsers/languages.mjs";
-export { type AccordionWebBlock, type AnyBibliography, type AnyConcept, type AnyItem, type AnyPeriod, type AnyPerson, type AnyPropertyValue, type AnyPropertyVariable, type AnyResource, type AnySet, type AnySpatialUnit, type AnyText, type AnyTree, type BaseItem, type BaseItemLink, type BelongsTo, type Bibliography, type BibliographyEntryInfo, type BibliographyItemLink, type BibliographySourceDocument, type Concept, type ConceptItemLink, type ContainedItemCategory, type ContainedItemCategoryFromOption, type ContainedItemCategoryOption, type Context, type ContextItem, type ContextItemCategory, type ContextNode, type ContextTree, type ContextTreeFilterLevel, type ContextTreeFilterVariant, type ContextTreeLevel, type ContextTreeLevelItem, type Coordinates, type CoordinatesSource, DEFAULT_PAGE_SIZE, type DictionaryUnitItemLink, type EmbeddedBibliography, type EmbeddedConcept, type EmbeddedItem, type EmbeddedPeriod, type EmbeddedPerson, type EmbeddedPropertyValue, type EmbeddedPropertyVariable, type EmbeddedResource, type EmbeddedSet, type EmbeddedSpatialUnit, type EmbeddedText, type EmbeddedTree, type Event, type Gallery, type Heading, type HeadingItemCategory, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type Item, type ItemCategory, type ItemCategoryFromOption, type ItemCategoryOption, type ItemCategoryWithEmbeddedItems, type ItemContainerCategory, type ItemLink, type ItemLinkCategory, type ItemLinks, type ItemPayloadKind, type ItemProperty, type ItemWithoutEmbeddedItems, type LanguageCodes, type License, type Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, type Note, type Observation, type OcrString, type Period, type PeriodItemLink, type Person, type PersonItemLink, type Property, type PropertyLike, type PropertyOptions, type PropertyRelation, type PropertySelector, type PropertyValue, type PropertyValueContent, type PropertyValueDataType, type PropertyValueItemLink, type PropertyValueQueryItem, type PropertyVariable, type PropertyVariableItemLink, type ProtectedWebsite, type Query, type QueryGroup, type QueryLeaf, type QueryablePropertyValueDataType, type RecursiveItemCategory, type Resource, type ResourceItemLink, type ResponsiveStyles, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetCategory, type StylesheetItem, type Text, type TextItemLink, type TopLevelItem, type Tree, type TreeItemCategory, type TreeItemLink, type WebAccordionItem, type WebBlock, type WebBlockByLayout, type WebBlockItem, type WebBlockLayout, type WebElement, type WebElementComponent, type WebElementComponentName, type WebElementComponentOf, type WebElementOf, type WebIiifViewer, type WebImage, type WebLoadingVariant, type WebOptions, type WebSectionDisplay, type WebSectionVariant, type WebSidebar, type WebTitle, type Webpage, type Website, type WebsiteMetadata, type WebsitePrivacy, type WebsitePropertyQuery, type WebsitePropertyQueryNode, type WebsiteSegment, type WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItems, fetchSetPropertyValues, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };
+export { type AccordionWebBlock, type AnyBibliography, type AnyConcept, type AnyItem, type AnyPeriod, type AnyPerson, type AnyPropertyValue, type AnyPropertyVariable, type AnyResource, type AnySet, type AnySpatialUnit, type AnyText, type AnyTree, type BaseItem, type BaseItemLink, type BelongsTo, type Bibliography, type BibliographyEntryInfo, type BibliographyItemLink, type BibliographySourceDocument, type Concept, type ConceptItemLink, type ContainedItemCategory, type ContainedItemCategoryFromOption, type ContainedItemCategoryOption, type Context, type ContextItem, type ContextItemCategory, type ContextNode, type ContextTree, type ContextTreeFilterLevel, type ContextTreeFilterVariant, type ContextTreeLevel, type ContextTreeLevelItem, type Coordinates, type CoordinatesSource, DEFAULT_PAGE_SIZE, type DictionaryUnitItemLink, type EmbeddedBibliography, type EmbeddedConcept, type EmbeddedItem, type EmbeddedPeriod, type EmbeddedPerson, type EmbeddedPropertyValue, type EmbeddedPropertyVariable, type EmbeddedResource, type EmbeddedSet, type EmbeddedSpatialUnit, type EmbeddedText, type EmbeddedTree, type Event, type Gallery, type Heading, type HeadingItemCategory, type Identification, type Image, type ImageMap, type ImageMapArea, type Interpretation, type Item, type ItemCategory, type ItemCategoryFromOption, type ItemCategoryOption, type ItemCategoryWithEmbeddedItems, type ItemContainerCategory, type ItemLink, type ItemLinkCategory, type ItemLinks, type ItemPayloadKind, type ItemProperty, type ItemWithoutEmbeddedItems, type LanguageCodes, type License, type Metadata, type MultilingualOptions, MultilingualString, type MultilingualStringEntries, type MultilingualStringEntry, type MultilingualStringInput, type MultilingualStringJSON, type MultilingualStringObject, type MultilingualStringText, type Note, type Observation, type OcrString, type Period, type PeriodItemLink, type Person, type PersonItemLink, type Property, type PropertyLike, type PropertyOptions, type PropertyRelation, type PropertySelector, type PropertyValue, type PropertyValueContent, type PropertyValueDataType, type PropertyValueItemLink, type PropertyValueQueryItem, type PropertyVariable, type PropertyVariableItemLink, type ProtectedWebsite, type Query, type QueryGroup, type QueryLeaf, type QueryablePropertyValueDataType, type RecursiveItemCategory, type Resource, type ResourceItemLink, type ResponsiveStyles, type Scope, type Section, type Set, type SetAttributeValueQueryItem, type SetBibliography, type SetConcept, type SetItem, type SetItemCategory, type SetItemLink, type SetItemProperty, type SetItemSimplifiedProperty, type SetItemsSort, type SetItemsSortDirection, type SetPeriod, type SetResource, type SetSpatialUnit, type SetTree, type SimplifiedProperty, type SpatialUnit, type SpatialUnitItemLink, type Style, type StylesheetCategory, type StylesheetItem, type Text, type TextItemLink, type TopLevelItem, type Tree, type TreeItemCategory, type TreeItemLink, type WebAccordionItem, type WebBlock, type WebBlockByLayout, type WebBlockItem, type WebBlockLayout, type WebElement, type WebElementComponent, type WebElementComponentName, type WebElementComponentOf, type WebElementOf, type WebIiifViewer, type WebImage, type WebLoadingVariant, type WebOptions, type WebSectionDisplay, type WebSectionVariant, type WebSidebar, type WebTitle, type Webpage, type Website, type WebsiteMetadata, type WebsitePrivacy, type WebsitePropertyQuery, type WebsitePropertyQueryNode, type WebsiteSegment, type WebsiteType, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };

package/dist/index.mjs

@@ -10,6 +10,7 @@ import { fetchItemOcrData } from "./fetchers/item-ocr-data.mjs";
 import { fetchItem } from "./fetchers/item.mjs";
 import { fetchSetItems } from "./fetchers/set/items.mjs";
 import { fetchSetPropertyValues } from "./fetchers/set/property-values.mjs";
+import { fetchTreeItems } from "./fetchers/tree/items.mjs";
 import { fetchWebsiteMetadata } from "./fetchers/website-metadata.mjs";
 import { fetchWebsite } from "./fetchers/website.mjs";
-export { DEFAULT_PAGE_SIZE, MultilingualString, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItems, fetchSetPropertyValues, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };
+export { DEFAULT_PAGE_SIZE, MultilingualString, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItems, fetchSetPropertyValues, fetchTreeItems, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };

package/dist/query.d.mts

@@ -2,12 +2,38 @@ import { PropertyRelation, Query } from "./types/index.mjs";
 import { OchreQueryContext } from "./xquery.mjs";
 //#region src/query.d.ts
 export declare function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids: ReadonlyArray<string>, belongsToCollectionPropertyVariableUuid: string): string | null;
+/**
+ * The scope variable and searchable path of each item container
+ *
+ * A path has to stay inline in `cts:search`: binding it to a variable first
+ * materializes the sequence and makes every query `XDMP-UNSEARCHABLE`, even a
+ * plain word query. Each references its own scope variable, which
+ * {@link compileContainerItemsQuery} declares.
+ *
+ * A Tree nests its items under headings to any depth, so its path walks the
+ * descendant axis and then keeps only the nodes a heading or `items` holds
+ * directly, which is what distinguishes an item from the elements inside one.
+ * Excluding `heading` matters twice: a heading is not an item, and searching
+ * over headings would match every item under a heading whose own text matches.
+ * The union form `items/(* | heading/*)` is deliberately not used, because
+ * MarkLogic rejects a union as `XDMP-UNSEARCHABLE`.
+ */
+declare const ITEMS_CONTAINERS: {
+  readonly set: {
+    readonly scopeVariable: "$setScopeUuids";
+    readonly itemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*";
+  };
+  readonly tree: {
+    readonly scopeVariable: "$treeScopeUuids";
+    readonly itemsExpression: "doc()/ochre/tree[@uuid = $treeScopeUuids]/items/descendant::*[not(self::heading)][parent::items or parent::heading]";
+  };
+};
 /**
  * Compile a query tree into the clauses that bind the matching Set items
  *
  * The returned `itemsClause` binds {@link ITEMS_VARIABLE} and has to be placed
  * inside an XQuery body, with `prolog` declared ahead of it.
- * {@link compileSetItemsQuery} does both and is what fetchers should use;
+ * {@link compileContainerItemsQuery} does both and is what fetchers should use;
  * this is exposed for tests that assert on the compiled CTS.
  * @param parameters - The plan parameters
  * @param parameters.queries - The query tree to compile, or null to match every item
@@ -30,15 +56,21 @@ export declare function buildQueryPlan(parameters: {
   }>;
 };
 /**
- * Compile a Set item query into a complete XQuery document
+ * The OCHRE item containers a paginated item query can run over
+ */
+export type ItemsContainer = keyof typeof ITEMS_CONTAINERS;
+/**
+ * Compile an item query over a Set or a Tree into a complete XQuery document
  *
  * Owns everything a caller would otherwise have to know and restate: the
- * version declaration, the Set scope variable, the supplemental-stripping
- * prolog, the inline searchable path, where the compiled helper prolog goes and
- * that it is only declared when non-empty, the `<ochre>` wrapper, and the name
- * of the variable holding the matching items. The body receives that name.
+ * version declaration, the scope variable, the supplemental-stripping prolog,
+ * the inline searchable path for the container, where the compiled helper
+ * prolog goes and that it is only declared when non-empty, the `<ochre>`
+ * wrapper, and the name of the variable holding the matching items. The body
+ * receives that name, so it is identical for either container.
  * @param parameters - The query parameters
- * @param parameters.setScopeUuids - The Set scope UUIDs to search within
+ * @param parameters.container - Whether the scope UUIDs name Sets or Trees
+ * @param parameters.scopeUuids - The container UUIDs to search within
  * @param parameters.belongsToCollectionScopeUuids - Collection scope UUIDs to narrow to
  * @param parameters.queries - The query tree to compile, or null to match every item
  * @param parameters.declarations - Extra prolog declarations, placed before the compiled prolog
@@ -46,8 +78,9 @@ export declare function buildQueryPlan(parameters: {
  * @returns A complete XQuery document
  * @internal
  */
-export declare function compileSetItemsQuery(parameters: {
-  setScopeUuids: ReadonlyArray<string>;
+export declare function compileContainerItemsQuery(parameters: {
+  container: ItemsContainer;
+  scopeUuids: ReadonlyArray<string>;
   belongsToCollectionScopeUuids: ReadonlyArray<string>;
   queries: Query | null;
   declarations?: ReadonlyArray<string>;

package/dist/query.mjs

@@ -1111,22 +1111,38 @@ function buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids,
 * @returns The prolog declaring the query helpers, and the `let` clauses binding `$items`
 */
 const ITEMS_VARIABLE = "$items";
-const SET_SCOPE_VARIABLE = "$setScopeUuids";
 /**
-* The XQuery path a Set item search runs over
+* The scope variable and searchable path of each item container
 *
-* The path has to stay inline in `cts:search`: binding it to a variable first
+* A path has to stay inline in `cts:search`: binding it to a variable first
 * materializes the sequence and makes every query `XDMP-UNSEARCHABLE`, even a
-* plain word query. It references {@link SET_SCOPE_VARIABLE}, which
-* {@link compileSetItemsQuery} declares.
+* plain word query. Each references its own scope variable, which
+* {@link compileContainerItemsQuery} declares.
+*
+* A Tree nests its items under headings to any depth, so its path walks the
+* descendant axis and then keeps only the nodes a heading or `items` holds
+* directly, which is what distinguishes an item from the elements inside one.
+* Excluding `heading` matters twice: a heading is not an item, and searching
+* over headings would match every item under a heading whose own text matches.
+* The union form `items/(* | heading/*)` is deliberately not used, because
+* MarkLogic rejects a union as `XDMP-UNSEARCHABLE`.
 */
-const SET_ITEMS_EXPRESSION = `doc()/ochre/set[@uuid = ${SET_SCOPE_VARIABLE}]/items/*`;
+const ITEMS_CONTAINERS = {
+	set: {
+		scopeVariable: "$setScopeUuids",
+		itemsExpression: "doc()/ochre/set[@uuid = $setScopeUuids]/items/*"
+	},
+	tree: {
+		scopeVariable: "$treeScopeUuids",
+		itemsExpression: "doc()/ochre/tree[@uuid = $treeScopeUuids]/items/descendant::*[not(self::heading)][parent::items or parent::heading]"
+	}
+};
 /**
 * Compile a query tree into the clauses that bind the matching Set items
 *
 * The returned `itemsClause` binds {@link ITEMS_VARIABLE} and has to be placed
 * inside an XQuery body, with `prolog` declared ahead of it.
-* {@link compileSetItemsQuery} does both and is what fetchers should use;
+* {@link compileContainerItemsQuery} does both and is what fetchers should use;
 * this is exposed for tests that assert on the compiled CTS.
 * @param parameters - The plan parameters
 * @param parameters.queries - The query tree to compile, or null to match every item
@@ -1178,15 +1194,17 @@ function buildQueryPlan(parameters) {
 	};
 }
 /**
-* Compile a Set item query into a complete XQuery document
+* Compile an item query over a Set or a Tree into a complete XQuery document
 *
 * Owns everything a caller would otherwise have to know and restate: the
-* version declaration, the Set scope variable, the supplemental-stripping
-* prolog, the inline searchable path, where the compiled helper prolog goes and
-* that it is only declared when non-empty, the `<ochre>` wrapper, and the name
-* of the variable holding the matching items. The body receives that name.
+* version declaration, the scope variable, the supplemental-stripping prolog,
+* the inline searchable path for the container, where the compiled helper
+* prolog goes and that it is only declared when non-empty, the `<ochre>`
+* wrapper, and the name of the variable holding the matching items. The body
+* receives that name, so it is identical for either container.
 * @param parameters - The query parameters
-* @param parameters.setScopeUuids - The Set scope UUIDs to search within
+* @param parameters.container - Whether the scope UUIDs name Sets or Trees
+* @param parameters.scopeUuids - The container UUIDs to search within
 * @param parameters.belongsToCollectionScopeUuids - Collection scope UUIDs to narrow to
 * @param parameters.queries - The query tree to compile, or null to match every item
 * @param parameters.declarations - Extra prolog declarations, placed before the compiled prolog
@@ -1194,17 +1212,18 @@ function buildQueryPlan(parameters) {
 * @returns A complete XQuery document
 * @internal
 */
-function compileSetItemsQuery(parameters) {
-	const { setScopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body } = parameters;
+function compileContainerItemsQuery(parameters) {
+	const { container, scopeUuids, belongsToCollectionScopeUuids, queries, declarations = [], body } = parameters;
+	const { scopeVariable, itemsExpression } = ITEMS_CONTAINERS[container];
 	const plan = buildQueryPlan({
 		queries,
-		baseItemsExpression: SET_ITEMS_EXPRESSION,
+		baseItemsExpression: itemsExpression,
 		scopeQueryExpression: buildBelongsToCollectionQueryExpression(belongsToCollectionScopeUuids, BELONGS_TO_COLLECTION_UUID)
 	});
 	return compileOchreQuery({
 		declarations: [
 			...declarations,
-			`declare variable ${SET_SCOPE_VARIABLE} := (${Array.from(setScopeUuids, (uuid) => stringLiteral(uuid)).join(", ")});`,
+			`declare variable ${scopeVariable} := (${Array.from(scopeUuids, (uuid) => stringLiteral(uuid)).join(", ")});`,
 			...plan.prolog === "" ? [] : [plan.prolog]
 		],
 		body: (context) => `<ochre>{
@@ -1268,4 +1287,4 @@ function getPropertyFacetSelectors(queries) {
 	return selectors.values().toArray();
 }
 //#endregion
-export { buildBelongsToCollectionQueryExpression, buildQueryPlan, compileSetItemsQuery, getItemFilterQueries, getPropertyFacetSelectors };
+export { buildBelongsToCollectionQueryExpression, buildQueryPlan, compileContainerItemsQuery, getItemFilterQueries, getPropertyFacetSelectors };

package/dist/schemas.d.mts

@@ -65,12 +65,32 @@ export declare const itemOcrDataParametersSchema: v.ObjectSchema<{
   readonly matchMode: v.OptionalSchema<v.PicklistSchema<["includes", "exact"], undefined>, "includes">;
   readonly isCaseSensitive: v.GenericSchema<unknown, boolean>;
 }, undefined>;
-/**
- * Schema for validating Set items parameters
- * @internal
- */
 export declare const setItemsParametersSchema: v.ObjectSchema<{
+  readonly belongsToCollectionScopeUuids: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, readonly []>;
+  readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
+  readonly sort: v.OptionalSchema<v.VariantSchema<"target", [v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"none", undefined>;
+  }, undefined>, v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"title", undefined>;
+    readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
+    readonly language: v.GenericSchema<unknown, string>;
+  }, undefined>, v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"date", undefined>;
+    readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
+  }, undefined>, v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"propertyValue", undefined>;
+    readonly propertyVariableUuid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>;
+    readonly dataType: v.PicklistSchema<readonly ["string", "integer", "decimal", "boolean", "date", "dateTime", "time", "IDREF"], undefined>;
+    readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
+    readonly language: v.GenericSchema<unknown, string>;
+  }, undefined>], undefined>, {
+    readonly target: "none";
+  }>;
+  readonly page: v.OptionalSchema<v.GenericSchema<unknown, number>, 1>;
+  readonly pageSize: v.OptionalSchema<v.GenericSchema<unknown, number>, 48>;
   readonly setScopeUuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one set scope UUID is required">]>;
+}, undefined>;
+export declare const treeItemsParametersSchema: v.ObjectSchema<{
   readonly belongsToCollectionScopeUuids: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, readonly []>;
   readonly queries: v.OptionalSchema<v.NullableSchema<v.GenericSchema<unknown, Query>, undefined>, null>;
   readonly sort: v.OptionalSchema<v.VariantSchema<"target", [v.StrictObjectSchema<{
@@ -79,6 +99,9 @@ export declare const setItemsParametersSchema: v.ObjectSchema<{
     readonly target: v.LiteralSchema<"title", undefined>;
     readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
     readonly language: v.GenericSchema<unknown, string>;
+  }, undefined>, v.StrictObjectSchema<{
+    readonly target: v.LiteralSchema<"date", undefined>;
+    readonly direction: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "asc">;
   }, undefined>, v.StrictObjectSchema<{
     readonly target: v.LiteralSchema<"propertyValue", undefined>;
     readonly propertyVariableUuid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>;
@@ -90,5 +113,6 @@ export declare const setItemsParametersSchema: v.ObjectSchema<{
   }>;
   readonly page: v.OptionalSchema<v.GenericSchema<unknown, number>, 1>;
   readonly pageSize: v.OptionalSchema<v.GenericSchema<unknown, number>, 48>;
+  readonly treeScopeUuids: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Invalid pseudo-UUID">]>, undefined>, v.MinLengthAction<string[], 1, "At least one tree scope UUID is required">]>;
 }, undefined>;
 //#endregion

package/dist/schemas.mjs

@@ -195,6 +195,10 @@ const setItemsSortSchema = v.optional(v.variant("target", [
 		direction: sortDirectionSchema,
 		language: defaultString("eng")
 	}),
+	v.strictObject({
+		target: v.literal("date"),
+		direction: sortDirectionSchema
+	}),
 	v.strictObject({
 		target: v.literal("propertyValue"),
 		propertyVariableUuid: uuidSchema,
@@ -243,13 +247,20 @@ const itemOcrDataParametersSchema = v.object({
 * Schema for validating Set items parameters
 * @internal
 */
-const setItemsParametersSchema = v.object({
-	setScopeUuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one set scope UUID is required")),
+const containerItemsParametersEntries = {
 	belongsToCollectionScopeUuids: v.optional(v.array(uuidSchema), []),
 	queries: setQueriesSchema,
 	sort: setItemsSortSchema,
 	page: v.optional(positiveNumber("Page must be positive"), 1),
 	pageSize: v.optional(positiveNumber("Page size must be positive"), 48)
+};
+const setItemsParametersSchema = v.object({
+	setScopeUuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one set scope UUID is required")),
+	...containerItemsParametersEntries
+});
+const treeItemsParametersSchema = v.object({
+	treeScopeUuids: v.pipe(v.array(uuidSchema), v.minLength(1, "At least one tree scope UUID is required")),
+	...containerItemsParametersEntries
 });
 //#endregion
-export { componentSchema, gallerySchema, isPseudoUuid, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, uuidSchema };
+export { componentSchema, gallerySchema, isPseudoUuid, iso639_3Schema, itemOcrDataParametersSchema, renderOptionsSchema, setItemsParametersSchema, setPropertyValuesParametersSchema, treeItemsParametersSchema, uuidSchema };

package/dist/types/index.d.mts

@@ -779,6 +779,15 @@ export type SetItemsSort = {
   target: "title";
   direction?: SetItemsSortDirection;
   language?: string;
+} |
+/**
+ * Sort on the item's own date, falling back to its first interpretation's
+ * date. A Concept carries no date of its own and dates its interpretations
+ * instead, so the two together are the one date an item has.
+ */
+{
+  target: "date";
+  direction?: SetItemsSortDirection;
 } | {
   target: "propertyValue";
   propertyVariableUuid: string;

package/dist/xml/schemas.d.mts

@@ -1816,7 +1816,7 @@ export declare const XMLGalleryData: v.ObjectSchema<{
                     rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
                     whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
                   }, "XMLString: Shape error">], undefined>, undefined>, undefined>;
-                  readonly identification: v.OptionalSchema<v.ObjectSchema<{
+                  readonly identification: v.OptionalSchema<v.OptionalSchema<v.ObjectSchema<{
                     readonly label: v.UnionSchema<[v.ObjectSchema<{
                       readonly content: v.ArraySchema<v.ObjectSchema<{
                         readonly links: v.OptionalSchema<v.LazySchema<v.GenericSchema<unknown, XMLLink$1>>, undefined>;
@@ -1914,7 +1914,11 @@ export declare const XMLGalleryData: v.ObjectSchema<{
                       rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
                       whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
                     }, "XMLString: Shape error">, v.StringSchema<"XMLIdentification: website is string and optional">], undefined>, undefined>;
-                  }, "XMLIdentification: Shape error">, undefined>;
+                  }, "XMLIdentification: Shape error">, {
+                    readonly label: {
+                      readonly content: readonly [];
+                    };
+                  }>, undefined>;
                   readonly context: v.OptionalSchema<v.OptionalSchema<v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
                     readonly context: v.ArraySchema<v.UnionSchema<[v.ObjectWithRestSchema<{
                       readonly project: v.ObjectSchema<{
@@ -2213,7 +2217,7 @@ export declare const XMLGalleryData: v.ObjectSchema<{
                 rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
                 whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
               }, "XMLString: Shape error">], undefined>, undefined>;
-              readonly identification: v.ObjectSchema<{
+              readonly identification: v.OptionalSchema<v.ObjectSchema<{
                 readonly label: v.UnionSchema<[v.ObjectSchema<{
                   readonly content: v.ArraySchema<v.ObjectSchema<{
                     readonly links: v.OptionalSchema<v.LazySchema<v.GenericSchema<unknown, XMLLink$1>>, undefined>;
@@ -2311,7 +2315,11 @@ export declare const XMLGalleryData: v.ObjectSchema<{
                   rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
                   whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
                 }, "XMLString: Shape error">, v.StringSchema<"XMLIdentification: website is string and optional">], undefined>, undefined>;
-              }, "XMLIdentification: Shape error">;
+              }, "XMLIdentification: Shape error">, {
+                readonly label: {
+                  readonly content: readonly [];
+                };
+              }>;
               readonly context: v.OptionalSchema<v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
                 readonly context: v.ArraySchema<v.UnionSchema<[v.ObjectWithRestSchema<{
                   readonly project: v.ObjectSchema<{
@@ -2961,7 +2969,7 @@ export declare const XMLGalleryData: v.ObjectSchema<{
                 rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
                 whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
               }, "XMLString: Shape error">], undefined>, undefined>, undefined>;
-              readonly identification: v.OptionalSchema<v.ObjectSchema<{
+              readonly identification: v.OptionalSchema<v.OptionalSchema<v.ObjectSchema<{
                 readonly label: v.UnionSchema<[v.ObjectSchema<{
                   readonly content: v.ArraySchema<v.ObjectSchema<{
                     readonly links: v.OptionalSchema<v.LazySchema<v.GenericSchema<unknown, XMLLink$1>>, undefined>;
@@ -3059,7 +3067,11 @@ export declare const XMLGalleryData: v.ObjectSchema<{
                   rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
                   whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
                 }, "XMLString: Shape error">, v.StringSchema<"XMLIdentification: website is string and optional">], undefined>, undefined>;
-              }, "XMLIdentification: Shape error">, undefined>;
+              }, "XMLIdentification: Shape error">, {
+                readonly label: {
+                  readonly content: readonly [];
+                };
+              }>, undefined>;
               readonly context: v.OptionalSchema<v.OptionalSchema<v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
                 readonly context: v.ArraySchema<v.UnionSchema<[v.ObjectWithRestSchema<{
                   readonly project: v.ObjectSchema<{
@@ -3351,7 +3363,7 @@ export declare const XMLGalleryData: v.ObjectSchema<{
             rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
             whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
           }, "XMLString: Shape error">], undefined>, undefined>;
-          readonly identification: v.ObjectSchema<{
+          readonly identification: v.OptionalSchema<v.ObjectSchema<{
             readonly label: v.UnionSchema<[v.ObjectSchema<{
               readonly content: v.ArraySchema<v.ObjectSchema<{
                 readonly links: v.OptionalSchema<v.LazySchema<v.GenericSchema<unknown, XMLLink$1>>, undefined>;
@@ -3449,7 +3461,11 @@ export declare const XMLGalleryData: v.ObjectSchema<{
               rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
               whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
             }, "XMLString: Shape error">, v.StringSchema<"XMLIdentification: website is string and optional">], undefined>, undefined>;
-          }, "XMLIdentification: Shape error">;
+          }, "XMLIdentification: Shape error">, {
+            readonly label: {
+              readonly content: readonly [];
+            };
+          }>;
           readonly context: v.OptionalSchema<v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
             readonly context: v.ArraySchema<v.UnionSchema<[v.ObjectWithRestSchema<{
               readonly project: v.ObjectSchema<{
@@ -5668,7 +5684,7 @@ export declare const XMLWebsiteData: v.ObjectSchema<{
           rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
           whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
         }, "XMLString: Shape error">], undefined>, undefined>;
-        readonly identification: v.ObjectSchema<{
+        readonly identification: v.OptionalSchema<v.ObjectSchema<{
           readonly label: v.UnionSchema<[v.ObjectSchema<{
             readonly content: v.ArraySchema<v.ObjectSchema<{
               readonly links: v.OptionalSchema<v.LazySchema<v.GenericSchema<unknown, XMLLink$1>>, undefined>;
@@ -5766,7 +5782,11 @@ export declare const XMLWebsiteData: v.ObjectSchema<{
             rend: v.OptionalSchema<v.StringSchema<"XMLString: rend is string and optional">, undefined>;
             whitespace: v.OptionalSchema<v.StringSchema<"XMLString: whitespace is string and optional">, undefined>;
           }, "XMLString: Shape error">, v.StringSchema<"XMLIdentification: website is string and optional">], undefined>, undefined>;
-        }, "XMLIdentification: Shape error">;
+        }, "XMLIdentification: Shape error">, {
+          readonly label: {
+            readonly content: readonly [];
+          };
+        }>;
         readonly context: v.OptionalSchema<v.ArraySchema<v.UnionSchema<[v.ObjectSchema<{
           readonly context: v.ArraySchema<v.UnionSchema<[v.ObjectWithRestSchema<{
             readonly project: v.ObjectSchema<{

package/dist/xml/schemas.mjs

@@ -286,7 +286,7 @@ const XMLBaseItem = v.object({
 	availability: v.optional(v.object({ license: XMLLicense })),
 	copyright: v.optional(v.union([XMLContent, XMLString])),
 	watermark: v.optional(v.union([XMLContent, XMLString])),
-	identification: XMLIdentification,
+	identification: v.optional(XMLIdentification, { label: { content: [] } }),
 	context: v.optional(XMLContext),
 	creators: v.optional(v.object({ creator: v.array(v.lazy(() => XMLPerson)) }, "XMLBaseItem: creators is object with creator array of XMLPerson")),
 	description: v.optional(XMLContent),
@@ -402,7 +402,8 @@ const XMLHeading = v.intersect([v.object({
 	v.optional(v.object({ propertyValue: v.array(v.lazy(() => XMLPropertyValue)) })),
 	v.optional(v.object({ resource: v.array(v.union([v.lazy(() => XMLResource), v.object({ resource: v.array(v.lazy(() => XMLResource)) })])) })),
 	v.optional(v.object({ text: v.array(v.lazy(() => XMLText)) })),
-	v.optional(v.object({ set: v.array(v.lazy(() => XMLSet)) }))
+	v.optional(v.object({ set: v.array(v.lazy(() => XMLSet)) })),
+	v.object({})
 ])]);
 const XMLTree = v.object({
 	...XMLBaseItem.entries,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",
@@ -47,18 +47,18 @@
   "dependencies": {
     "fast-equals": "^6.0.3",
     "fast-xml-parser": "^5.11.1",
-    "valibot": "^1.4.2"
+    "valibot": "^1.5.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.5.1",
-    "@types/node": "^24.13.3",
+    "@types/node": "^24.13.4",
     "bumpp": "^12.3.0",
-    "eslint": "^10.9.1",
+    "eslint": "^10.10.0",
     "eslint-plugin-erasable-syntax-only": "^0.7.1",
     "eslint-plugin-slop": "^0.1.3",
     "eslint-plugin-sonarjs": "^4.2.0",
-    "knip": "^6.34.0",
-    "oxfmt": "^0.66.0",
+    "knip": "^6.35.1",
+    "oxfmt": "^0.67.0",
     "tsdown": "^0.23.0",
     "typescript": "^6.0.3",
     "vitest": "^5.0.0"