ochre-sdk 1.1.0 → 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.
 
@@ -84,6 +87,34 @@ title.getExactText("tur");
 title.getAvailableLanguages();
 ```
 
+Reads come in three widths. `getText` and `getRichText` resolve one entry through the language fallback, `getExactText` and `getExactRichText` skip the fallback, and `getEntries`, `getTexts` and `getExactTexts` return every entry when OCHRE carried more than one for a language.
+
+Two questions look alike and are not the same. `isEmpty()` asks whether any language carries an entry at all. `hasContent()` asks whether any entry in any language holds text that is not whitespace, which is what a caller deciding whether to render something wants, because OCHRE does serve fields holding a single blank entry.
+
+```ts
+title.isEmpty();
+title.hasContent();
+title.hasLanguage("tur");
+title.hasAliases();
+
+title.getAvailableLanguages(); // languages that carry content
+title.getSupportedLanguages(); // languages the string was built to hold
+```
+
+Writes return a new string and never mutate the original.
+
+```ts
+title.with("tur", "Başlık");
+title.with("tur", "another entry", { shouldAppend: true });
+title.without("tur");
+title.withAliases(["ABC"]);
+
+title.mapText((text) => text.trim());
+title.filterEntries((entry) => entry.isPrimary);
+```
+
+`mapText` runs against plain text and rebuilds each entry's rich text from the result, so a transform cannot corrupt the markup OCHRE wrote. A transform that needs to keep or rewrite markup returns `{ text, richText }` instead of a string.
+
 For reusable language tuples, use `defineLanguages` to keep runtime validation
 and literal TypeScript inference together.
 
@@ -121,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.
@@ -177,8 +225,9 @@ types, query types, property getters, and small data helpers:
 - `Item`, `SetItem`, `ItemLink`, `Website`, `WebElementOf`,
   `WebElementComponentOf`, `WebBlockByLayout`, `Query`, and related types.
 - `getProperty`, `getPropertyValues`, `getPropertyValue`,
-  `getUniqueProperties`, `getUniquePropertyVariableLabels`, and
-  `isPropertyMatchingFilter` for reading properties off a parsed item.
+  `getUniqueProperties`, `getUniquePropertyVariableLabels`,
+  `isPropertyMatchingFilter`, and `getLeafPropertyValues` for reading
+  properties off a parsed item.
 - `flattenItemProperties` and `DEFAULT_PAGE_SIZE` for common collection UI
   workflows.
 

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/getters.d.mts

@@ -53,6 +53,17 @@ export type PropertySelector<T extends LanguageCodes = LanguageCodes> = {
  * @returns The normalized label
  */
 export declare function normalizePropertyVariableLabel(value: string): string;
+/**
+ * Keep only the leaf values from an array of property values
+ *
+ * OCHRE property values form a hierarchy, and a value with children is usually
+ * a grouping rather than something to show. This asks that of a values array
+ * the caller already holds; the same filter is available on the lookups
+ * through `limitToLeafPropertyValues`.
+ * @param propertyValues - The values to filter
+ * @returns The values that have no children
+ */
+export declare function getLeafPropertyValues<T extends LanguageCodes = LanguageCodes>(propertyValues: ReadonlyArray<PropertyValueContent<T>>): Array<PropertyValueContent<T>>;
 /**
  * Find the property a selector names
  *

package/dist/getters.mjs

@@ -88,6 +88,16 @@ function findProperty(properties, isMatch, shouldIncludeNestedProperties) {
 	}
 	return null;
 }
+/**
+* Keep only the leaf values from an array of property values
+*
+* OCHRE property values form a hierarchy, and a value with children is usually
+* a grouping rather than something to show. This asks that of a values array
+* the caller already holds; the same filter is available on the lookups
+* through `limitToLeafPropertyValues`.
+* @param propertyValues - The values to filter
+* @returns The values that have no children
+*/
 function getLeafPropertyValues(propertyValues) {
 	const leafPropertyValues = [];
 	for (const value of propertyValues) if (value.hierarchy.isLeaf) leafPropertyValues.push(value);
@@ -224,4 +234,4 @@ function isPropertyMatchingFilter(property, filter, options = DEFAULT_OPTIONS) {
 	return false;
 }
 //#endregion
-export { getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };
+export { getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };