ochre-sdk 1.0.79 → 1.1.1

package/dist/getters.mjs

@@ -1,23 +1,31 @@
 import { deepEqual } from "fast-equals";
 //#region src/getters.ts
+/**
+* The variable label that asks a filter to match against every property
+*/
+const ALL_FIELDS_VARIABLE_LABEL = "all-fields";
 const DEFAULT_OPTIONS = {
 	includeNestedProperties: false,
 	limitToLeafPropertyValues: true
 };
+/**
+* Normalize an OCHRE property variable label for comparison
+*
+* OCHRE varies the casing and the word separator of a property label, so every
+* comparison against a label goes through here. This is the only rule in the
+* SDK for deciding whether a label names a given property.
+* @param value - The label to normalize
+* @returns The normalized label
+*/
+function normalizePropertyVariableLabel(value) {
+	return value.trim().toLocaleLowerCase("en-US").replaceAll(/[\s_]+/g, "-");
+}
 function withDefaultOptions(options) {
 	return {
 		includeNestedProperties: options.includeNestedProperties ?? false,
 		limitToLeafPropertyValues: options.limitToLeafPropertyValues ?? true
 	};
 }
-function findPropertyByVariableUuid(properties, variableUuid) {
-	for (const property of properties) if (property.variable.uuid === variableUuid) return property;
-	return null;
-}
-function findPropertyByVariableLabel(properties, variableLabel) {
-	for (const property of properties) if (getPropertyVariableLabel(property) === variableLabel) return property;
-	return null;
-}
 function getPropertyVariableLabel(property) {
 	return typeof property.variable.label === "string" ? property.variable.label : property.variable.label.getText();
 }
@@ -34,270 +42,191 @@ function hasEqualPropertyValueContents(property, valueContents) {
 	for (const [index, value] of property.values.entries()) if (!deepEqual(value.content, valueContents[index])) return false;
 	return true;
 }
-function searchPropertyResult(properties, options, findDirectResult, transformNestedResult) {
-	const directResult = findDirectResult(properties);
-	if (directResult !== null) return directResult;
-	if (!options.includeNestedProperties) return null;
-	for (const property of properties) {
-		if (!("properties" in property)) continue;
-		const nestedResult = searchPropertyResult(property.properties, options, findDirectResult, transformNestedResult);
-		if (nestedResult === null) continue;
-		const transformedResult = transformNestedResult != null ? transformNestedResult(nestedResult) : nestedResult;
-		if (transformedResult !== null) return transformedResult;
+/**
+* Compile a selector into a predicate over one property
+*
+* The label is normalized once here rather than once per candidate property.
+*/
+function createPropertyPredicate(selector) {
+	if ("uuid" in selector) {
+		const { uuid } = selector;
+		return (property) => property.variable.uuid === uuid;
 	}
-	return null;
-}
-function getPropertyValuesResult(values, shouldLimitToLeafPropertyValues, shouldCopyValuesWhenUnfiltered) {
-	if (shouldLimitToLeafPropertyValues) return getLeafPropertyValues(values);
-	if (shouldCopyValuesWhenUnfiltered) return clonePropertyValues(values);
-	return [...values];
-}
-function clonePropertyValues(values) {
-	return Array.from(values, (value) => ({ ...value }));
-}
-function getNormalizedProperty(property, shouldLimitToLeafPropertyValues, transformValues) {
-	if (!shouldLimitToLeafPropertyValues) return property;
-	const values = getLeafPropertyValues(property.values);
-	return {
-		...property,
-		values: transformValues != null ? transformValues(values) : values
-	};
-}
-function getFirstPropertyValueResult(values, shouldLimitToLeafPropertyValues) {
-	if (shouldLimitToLeafPropertyValues) return getLeafPropertyValues(values)[0] ?? null;
-	return values[0] ?? null;
-}
-function getFirstPropertyValueContentResult(values, shouldLimitToLeafPropertyValues) {
-	if (shouldLimitToLeafPropertyValues) return getLeafPropertyValues(values)[0]?.content ?? null;
-	return values[0]?.content ?? null;
-}
-function visitProperties(properties, shouldIncludeNestedProperties, visit) {
-	for (const property of properties) {
-		visit(property);
-		if (shouldIncludeNestedProperties && "properties" in property) visitProperties(property.properties, shouldIncludeNestedProperties, visit);
+	const normalizedLabel = normalizePropertyVariableLabel(selector.label);
+	const hasMatchingLabel = (property) => normalizePropertyVariableLabel(getPropertyVariableLabel(property)) === normalizedLabel;
+	if ("values" in selector) {
+		const { values } = selector;
+		return (property) => hasMatchingLabel(property) && deepEqual(property.values, values);
 	}
-}
-function getPropertyByVariableUuid(properties, variableUuid, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => findPropertyByVariableUuid(currentProperties, variableUuid));
+	if ("valueContents" in selector) {
+		const { valueContents } = selector;
+		return (property) => hasMatchingLabel(property) && hasEqualPropertyValueContents(property, valueContents);
+	}
+	if ("value" in selector) {
+		const { value } = selector;
+		return (property) => hasMatchingLabel(property) && hasPropertyValue(property, value);
+	}
+	if ("valueContent" in selector) {
+		const { valueContent } = selector;
+		return (property) => hasMatchingLabel(property) && hasPropertyValueContent(property, valueContent);
+	}
+	return hasMatchingLabel;
 }
 /**
-* Retrieves all values for a property with the given variable UUID.
+* Find the first property matching a predicate, descending when asked to
 *
-* @param properties - Array of properties to search through
-* @param variableUuid - The property variable UUID to search for
-* @param options - Search options, including whether to include nested properties
-* @returns Array of property values, or null if property not found
+* Every property at one level is tested before descending, so a match on the
+* item's own properties always wins over one on a nested property.
 */
-function getPropertyValuesByVariableUuid(properties, variableUuid, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		const property = findPropertyByVariableUuid(currentProperties, variableUuid);
-		if (property == null) return null;
-		return getPropertyValuesResult(property.values, limitToLeafPropertyValues, true);
-	}, (nestedResult) => getPropertyValuesResult(nestedResult, limitToLeafPropertyValues, true));
+function findProperty(properties, isMatch, shouldIncludeNestedProperties) {
+	for (const property of properties) if (isMatch(property)) return property;
+	if (!shouldIncludeNestedProperties) return null;
+	for (const property of properties) {
+		if (!("properties" in property)) continue;
+		const nestedProperty = findProperty(property.properties, isMatch, true);
+		if (nestedProperty !== null) return nestedProperty;
+	}
+	return null;
 }
 /**
-* Retrieves all value contents for a property with the given variable UUID.
+* Keep only the leaf values from an array of property values
 *
-* @param properties - Array of properties to search through
-* @param variableUuid - The property variable UUID to search for
-* @param options - Search options, including whether to include nested properties
-* @returns Array of property value contents, or null if property not found
+* 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 getPropertyValueContentsByVariableUuid(properties, variableUuid, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		const property = findPropertyByVariableUuid(currentProperties, variableUuid);
-		if (property == null) return null;
-		return Array.from(getPropertyValuesResult(property.values, limitToLeafPropertyValues, false), (value) => value.content);
-	});
+function getLeafPropertyValues(propertyValues) {
+	const leafPropertyValues = [];
+	for (const value of propertyValues) if (value.hierarchy.isLeaf) leafPropertyValues.push(value);
+	return leafPropertyValues;
 }
 /**
-* Gets the first value of a property with the given variable UUID.
-*
-* @param properties - Array of properties to search through
-* @param variableUuid - The property variable UUID to search for
-* @param options - Search options, including whether to include nested properties
-* @returns The first property value, or null if property not found
+* Project a property's values, copying so callers cannot mutate the source
 */
-function getPropertyValueByVariableUuid(properties, variableUuid, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		const values = getPropertyValuesByVariableUuid(currentProperties, variableUuid, {
-			includeNestedProperties: false,
-			limitToLeafPropertyValues
-		});
-		if (values === null || values.length === 0) return null;
-		return getFirstPropertyValueResult(values, limitToLeafPropertyValues);
-	}, (nestedResult) => getFirstPropertyValueResult([nestedResult], limitToLeafPropertyValues));
+function projectPropertyValues(values, shouldLimitToLeafPropertyValues) {
+	const projectedValues = shouldLimitToLeafPropertyValues ? getLeafPropertyValues(values) : values;
+	return Array.from(projectedValues, (value) => ({ ...value }));
+}
+function visitProperties(properties, shouldIncludeNestedProperties, visit) {
+	for (const property of properties) {
+		visit(property);
+		if (shouldIncludeNestedProperties && "properties" in property) visitProperties(property.properties, shouldIncludeNestedProperties, visit);
+	}
 }
 /**
-* Gets the first value content of a property with the given variable UUID.
+* Find the property a selector names
 *
-* @param properties - Array of properties to search through
-* @param variableUuid - The property variable UUID to search for
-* @param options - Search options, including whether to include nested properties
-* @returns The first property value content, or null if property not found
+* The property is returned exactly as it was found, so its `values` are
+* whatever the item carries and `limitToLeafPropertyValues` does not apply.
+* Use {@link getPropertyValues} when leaf filtering matters.
+* @param properties - The properties to search
+* @param selector - Which property to look for
+* @param options - Search options
+* @param options.includeNestedProperties - Whether to descend into nested properties
+* @returns The matching property, or null when there is none
 */
-function getPropertyValueContentByVariableUuid(properties, variableUuid, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		const values = getPropertyValuesByVariableUuid(currentProperties, variableUuid, {
-			includeNestedProperties: false,
-			limitToLeafPropertyValues
-		});
-		if (values === null || values.length === 0) return null;
-		return getFirstPropertyValueContentResult(values, limitToLeafPropertyValues);
-	});
-}
-function getPropertyByVariableLabel(properties, variableLabel, options = DEFAULT_OPTIONS) {
+function getProperty(properties, selector, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => findPropertyByVariableLabel(currentProperties, variableLabel));
-}
-function getPropertyByVariableLabelAndValues(properties, variableLabel, values, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		for (const property of currentProperties) if (getPropertyVariableLabel(property) === variableLabel && deepEqual(property.values, values)) return getNormalizedProperty(property, limitToLeafPropertyValues);
-		return null;
-	}, (nestedResult) => getNormalizedProperty(nestedResult, limitToLeafPropertyValues));
-}
-function getPropertyByVariableLabelAndValueContents(properties, variableLabel, valueContents, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		for (const property of currentProperties) if (getPropertyVariableLabel(property) === variableLabel && hasEqualPropertyValueContents(property, valueContents)) return getNormalizedProperty(property, limitToLeafPropertyValues, clonePropertyValues);
-		return null;
-	}, (nestedResult) => getNormalizedProperty(nestedResult, limitToLeafPropertyValues));
-}
-function getPropertyByVariableLabelAndValue(properties, variableLabel, value, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		for (const property of currentProperties) if (getPropertyVariableLabel(property) === variableLabel && hasPropertyValue(property, value)) return getNormalizedProperty(property, limitToLeafPropertyValues);
-		return null;
-	}, (nestedResult) => getNormalizedProperty(nestedResult, limitToLeafPropertyValues));
-}
-function getPropertyByVariableLabelAndValueContent(properties, variableLabel, valueContent, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		for (const property of currentProperties) if (getPropertyVariableLabel(property) === variableLabel && hasPropertyValueContent(property, valueContent)) return getNormalizedProperty(property, limitToLeafPropertyValues);
-		return null;
-	}, (nestedResult) => getNormalizedProperty(nestedResult, limitToLeafPropertyValues));
+	return findProperty(properties, createPropertyPredicate(selector), includeNestedProperties);
 }
 /**
-* Retrieves all values for a property with the given variable label.
-*
-* @param properties - Array of properties to search through
-* @param variableLabel - The property variable label to search for
-* @param options - Search options, including whether to include nested properties
-* @returns Array of property values, or null if property not found
+* Read every value of the property a selector names
+* @param properties - The properties to search
+* @param selector - Which property to look for
+* @param options - Search options
+* @param options.includeNestedProperties - Whether to descend into nested properties
+* @param options.limitToLeafPropertyValues - Whether to keep only leaf values
+* @returns The values, or null when no property matched
 */
-function getPropertyValuesByVariableLabel(properties, variableLabel, options = DEFAULT_OPTIONS) {
+function getPropertyValues(properties, selector, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		const property = findPropertyByVariableLabel(currentProperties, variableLabel);
-		if (property == null) return null;
-		return getPropertyValuesResult(property.values, limitToLeafPropertyValues, false);
-	}, (nestedResult) => getPropertyValuesResult(nestedResult, limitToLeafPropertyValues, false));
+	const property = findProperty(properties, createPropertyPredicate(selector), includeNestedProperties);
+	return property == null ? null : projectPropertyValues(property.values, limitToLeafPropertyValues);
 }
 /**
-* Gets the first value of a property with the given variable label.
-*
-* @param properties - Array of properties to search through
-* @param variableLabel - The property variable label to search for
-* @param options - Search options, including whether to include nested properties
-* @returns The first property value, or null if property not found
+* Read the first value of the property a selector names
+* @param properties - The properties to search
+* @param selector - Which property to look for
+* @param options - Search options
+* @param options.includeNestedProperties - Whether to descend into nested properties
+* @param options.limitToLeafPropertyValues - Whether to keep only leaf values
+* @returns The first value, or null when no property matched or it has none
 */
-function getPropertyValueByVariableLabel(properties, variableLabel, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		const values = getPropertyValuesByVariableLabel(currentProperties, variableLabel, {
-			includeNestedProperties: false,
-			limitToLeafPropertyValues
-		});
-		if (values === null || values.length === 0) return null;
-		return getFirstPropertyValueResult(values, limitToLeafPropertyValues);
-	}, (nestedResult) => getFirstPropertyValueResult([nestedResult], limitToLeafPropertyValues));
+function getPropertyValue(properties, selector, options = DEFAULT_OPTIONS) {
+	return getPropertyValues(properties, selector, options)?.[0] ?? null;
 }
 /**
-* Gets the first value content of a property with the given variable label.
+* Gets all unique properties from an array of properties.
 *
-* @param properties - Array of properties to search through
-* @param variableLabel - The property variable label to search for
-* @param options - Search options, including whether to include nested properties
-* @returns The first property value content, or null if property not found
+* Properties are returned exactly as they were found, deduplicated by variable
+* UUID, keeping the first occurrence.
+* @param properties - Array of properties to get unique properties from
+* @param options - Search options
+* @param options.includeNestedProperties - Whether to descend into nested properties
+* @returns Array of unique properties
 */
-function getPropertyValueContentByVariableLabel(properties, variableLabel, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
-		const values = getPropertyValuesByVariableLabel(currentProperties, variableLabel, {
-			includeNestedProperties: false,
-			limitToLeafPropertyValues
-		});
-		if (values === null || values.length === 0) return null;
-		return getFirstPropertyValueContentResult(values, limitToLeafPropertyValues);
-	});
-}
 function getUniqueProperties(properties, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
+	const { includeNestedProperties } = withDefaultOptions(options);
 	const uniqueProperties = [];
+	const seenVariableUuids = /* @__PURE__ */ new Set();
 	visitProperties(properties, includeNestedProperties, (property) => {
-		for (const uniqueProperty of uniqueProperties) if (uniqueProperty.variable.uuid === property.variable.uuid) return;
+		if (seenVariableUuids.has(property.variable.uuid)) return;
+		seenVariableUuids.add(property.variable.uuid);
 		uniqueProperties.push(property);
 	});
-	if (limitToLeafPropertyValues) return Array.from(uniqueProperties, (property) => getNormalizedProperty(property, limitToLeafPropertyValues));
 	return uniqueProperties;
 }
 /**
 * Gets all unique property variable labels from an array of properties.
-*
 * @param properties - Array of properties to get unique property variable labels from
-* @param options - Search options, including whether to include nested properties
+* @param options - Search options
+* @param options.includeNestedProperties - Whether to descend into nested properties
 * @returns Array of unique property variable labels
 */
 function getUniquePropertyVariableLabels(properties, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = withDefaultOptions(options);
 	const uniquePropertyVariableLabels = [];
+	const seenLabels = /* @__PURE__ */ new Set();
 	visitProperties(properties, includeNestedProperties, (property) => {
 		const variableLabel = getPropertyVariableLabel(property);
-		if (uniquePropertyVariableLabels.includes(variableLabel)) return;
+		if (seenLabels.has(variableLabel)) return;
+		seenLabels.add(variableLabel);
 		uniquePropertyVariableLabels.push(variableLabel);
 	});
 	return uniquePropertyVariableLabels;
 }
-/**
-* Get the leaf property values from an array of property values.
-*
-* @param propertyValues - The array of property values to get the leaf property values from
-* @returns The array of leaf property values
-*/
-function getLeafPropertyValues(propertyValues) {
-	const leafPropertyValues = [];
-	for (const value of propertyValues) if (value.hierarchy.isLeaf) leafPropertyValues.push(value);
-	return leafPropertyValues;
-}
 function isContentMatchingFilter(content, filterContent) {
 	if (typeof content === "string") return typeof filterContent === "string" && content.toLocaleLowerCase("en-US").includes(filterContent.toLocaleLowerCase("en-US"));
 	if (typeof content === "number") return typeof filterContent === "number" && content === filterContent;
 	return typeof filterContent === "boolean" && content === filterContent;
 }
 /**
-* Filters a property based on a variable label and value content criterion.
+* Whether a property matches a variable label and value content criterion.
 *
-* @param property - The property to filter
+* Matching is client-side and deliberately loose: string contents match on a
+* case-insensitive substring, numbers and booleans on equality. A
+* `variableLabel` of "all fields" matches against every property.
+* @param property - The property to test
 * @param filter - Filter criteria containing variable label and value to match
 * @param filter.variableLabel - The variable label to filter by
 * @param filter.value - The value to filter by
-* @param options - Search options, including whether to include nested properties
+* @param options - Search options
+* @param options.includeNestedProperties - Whether to descend into nested properties
+* @param options.limitToLeafPropertyValues - Whether to test only leaf values
 * @returns True if the property matches the filter criteria, false otherwise
 */
-function filterProperties(property, filter, options = DEFAULT_OPTIONS) {
+function isPropertyMatchingFilter(property, filter, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
-	if (filter.variableLabel.toLocaleLowerCase("en-US") === "all fields" || getPropertyVariableLabel(property).toLocaleLowerCase("en-US") === filter.variableLabel.toLocaleLowerCase("en-US")) {
-		const values = getPropertyValuesResult(property.values, limitToLeafPropertyValues, false);
+	const normalizedFilterLabel = normalizePropertyVariableLabel(filter.variableLabel);
+	if (normalizedFilterLabel === ALL_FIELDS_VARIABLE_LABEL || normalizePropertyVariableLabel(getPropertyVariableLabel(property)) === normalizedFilterLabel) {
+		const values = limitToLeafPropertyValues ? getLeafPropertyValues(property.values) : property.values;
 		for (const value of values) if (isContentMatchingFilter(value.content, filter.value.content)) return true;
 	}
 	if (includeNestedProperties && "properties" in property) {
-		for (const nestedProperty of property.properties) if (filterProperties(nestedProperty, filter, {
+		for (const nestedProperty of property.properties) if (isPropertyMatchingFilter(nestedProperty, filter, {
 			includeNestedProperties: true,
 			limitToLeafPropertyValues
 		})) return true;
@@ -305,4 +234,4 @@ function filterProperties(property, filter, options = DEFAULT_OPTIONS) {
 	return false;
 }
 //#endregion
-export { filterProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels };
+export { getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };

package/dist/helpers.d.mts

@@ -3,10 +3,6 @@ import { ContainedItemCategory, Item, ItemCategory, ItemPayloadKind, LanguageCod
 type FlattenedItem<U, T extends LanguageCodes> = Omit<U, "properties"> & {
   properties: Array<SetItemProperty<T>>;
 };
-/**
- * The default page size to use for fetching paginated items
- */
-export declare const DEFAULT_PAGE_SIZE = 48;
 /**
  * Flatten the properties of an item
  * @param item - The item whose properties to flatten

package/dist/helpers.mjs

@@ -1,10 +1,5 @@
-import { flattenProperties } from "./utilities.mjs";
 //#region src/helpers.ts
 /**
-* The default page size to use for fetching paginated items
-*/
-const DEFAULT_PAGE_SIZE = 48;
-/**
 * Flatten the properties of an item
 * @param item - The item whose properties to flatten
 * @returns The item with the properties flattened
@@ -29,5 +24,23 @@ function flattenItemProperties(item) {
 		properties: flattenProperties(allProperties)
 	};
 }
+/**
+* Flatten a properties array
+* @param properties - The properties to flatten
+* @returns The flattened properties
+* @internal
+*/
+function flattenProperties(properties) {
+	const result = [];
+	for (const property of properties) {
+		result.push({
+			variable: property.variable,
+			values: property.values,
+			comment: property.comment
+		});
+		if ("properties" in property) result.push(...flattenProperties(property.properties));
+	}
+	return result;
+}
 //#endregion
-export { DEFAULT_PAGE_SIZE, flattenItemProperties };
+export { flattenItemProperties };

package/dist/index.d.mts

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

package/dist/index.mjs

@@ -1,13 +1,15 @@
-import { filterProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels } from "./getters.mjs";
-import { DEFAULT_PAGE_SIZE, flattenItemProperties } from "./helpers.mjs";
+import { DEFAULT_PAGE_SIZE } from "./constants.mjs";
+import { getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.mjs";
+import { flattenItemProperties } from "./helpers.mjs";
 import { MultilingualString } from "./parsers/multilingual.mjs";
+import { defineLanguages } from "./parsers/languages.mjs";
 import { fetchGallery } from "./fetchers/gallery.mjs";
 import { fetchItemChildren } from "./fetchers/item-children.mjs";
 import { fetchItemLinks } from "./fetchers/item-links.mjs";
 import { fetchItemOcrData } from "./fetchers/item-ocr-data.mjs";
-import { defineLanguages, fetchItem, withLanguages } from "./fetchers/item.mjs";
+import { fetchItem } from "./fetchers/item.mjs";
 import { fetchSetItems } from "./fetchers/set/items.mjs";
 import { fetchSetPropertyValues } from "./fetchers/set/property-values.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, filterProperties, flattenItemProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels, withLanguages };
+export { DEFAULT_PAGE_SIZE, MultilingualString, defineLanguages, fetchGallery, fetchItem, fetchItemChildren, fetchItemLinks, fetchItemOcrData, fetchSetItems, fetchSetPropertyValues, fetchWebsite, fetchWebsiteMetadata, flattenItemProperties, getLeafPropertyValues, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel };

package/dist/ocr.d.mts

@@ -0,0 +1,37 @@
+//#region src/ocr.d.ts
+/**
+ * The name of the element wrapping an OCR layer inside an OCHRE document
+ * @internal
+ */
+export declare const OCR_LAYER_ELEMENT_NAME = "ocr";
+/**
+ * The attribute an OCR word element holds its word in
+ *
+ * The word is in the attribute rather than in the element's text content.
+ * @internal
+ */
+export declare const OCR_WORD_CONTENT_ATTRIBUTE = "CONTENT";
+/**
+ * An XQuery sequence of every QName an OCR word element can carry
+ *
+ * Use with the `cts:element-*` query constructors, which need concrete QNames
+ * and cannot match on a case-folded local name the way {@link buildOcrWordPath}
+ * does. This has to stay in agreement with that path: a word element the
+ * narrowing misses is a document the search silently drops.
+ * @internal
+ */
+export declare const OCR_WORD_QNAMES: string;
+/**
+ * Build an XQuery path selecting every OCR word element beneath a node
+ *
+ * Matches the layer and the word elements on a case-folded `local-name()`
+ * rather than a name test, because a name test silently matches nothing when
+ * OCHRE varies the casing or serves the elements in a namespace. Word elements
+ * are selected at any depth, because the hierarchy between the layer and its
+ * words is irregular and is not parsed.
+ * @param rootExpression - The XQuery expression to select from
+ * @returns The XQuery path
+ * @internal
+ */
+export declare function buildOcrWordPath(rootExpression: string): string;
+//#endregion