ochre-sdk 1.0.78 → 1.1.0

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,42 +42,63 @@ 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;
+/**
+* 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;
+	}
+	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);
+	}
+	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;
+}
+/**
+* Find the first property matching a predicate, descending when asked to
+*
+* 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 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 nestedResult = searchPropertyResult(property.properties, options, findDirectResult, transformNestedResult);
-		if (nestedResult === null) continue;
-		const transformedResult = transformNestedResult != null ? transformNestedResult(nestedResult) : nestedResult;
-		if (transformedResult !== null) return transformedResult;
+		const nestedProperty = findProperty(property.properties, isMatch, true);
+		if (nestedProperty !== null) return nestedProperty;
 	}
 	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 getLeafPropertyValues(propertyValues) {
+	const leafPropertyValues = [];
+	for (const value of propertyValues) if (value.hierarchy.isLeaf) leafPropertyValues.push(value);
+	return leafPropertyValues;
 }
-function getFirstPropertyValueContentResult(values, shouldLimitToLeafPropertyValues) {
-	if (shouldLimitToLeafPropertyValues) return getLeafPropertyValues(values)[0]?.content ?? null;
-	return values[0]?.content ?? null;
+/**
+* Project a property's values, copying so callers cannot mutate the source
+*/
+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) {
@@ -77,227 +106,117 @@ function visitProperties(properties, shouldIncludeNestedProperties, visit) {
 		if (shouldIncludeNestedProperties && "properties" in property) visitProperties(property.properties, shouldIncludeNestedProperties, visit);
 	}
 }
-function getPropertyByVariableUuid(properties, variableUuid, options = DEFAULT_OPTIONS) {
-	const { includeNestedProperties } = withDefaultOptions(options);
-	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => findPropertyByVariableUuid(currentProperties, variableUuid));
-}
-/**
-* Retrieves all values for 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 Array of property values, or null if property not found
-*/
-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));
-}
 /**
-* Retrieves all value contents for 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 Array of property value contents, 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 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);
-	});
-}
-/**
-* 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
-*/
-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));
-}
-/**
-* Gets the first value content 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 content, or null if property not found
-*/
-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 +224,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 { 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 { ContextTree, ContextTreeFilterLevel, ContextTreeFilterVariant, ContextTreeLevel, ContextTreeLevelItem, ProtectedWebsite, ResponsiveStyles, Scope, Style, 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 { BaseItem, BaseItemLink, BelongsTo, Bibliography, BibliographyEntryInfo, BibliographyItemLink, BibliographySourceDocument, Concept, ConceptItemLink, ContainedItemCategory, ContainedItemCategoryFromOption, ContainedItemCategoryOption, Context, ContextItem, ContextItemCategory, ContextNode, Coordinates, CoordinatesSource, DictionaryUnitItemLink, Event, Gallery, Heading, HeadingItemCategory, Identification, Image, ImageMap, ImageMapArea, Interpretation, Item, ItemCategory, ItemCategoryFromOption, ItemCategoryOption, ItemCategoryWithEmbeddedItems, ItemContainerCategory, ItemLink, ItemLinkCategory, ItemLinks, ItemPayloadKind, 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, Resource, ResourceItemLink, Section, Set, SetAttributeValueQueryItem, SetBibliography, SetConcept, SetItem, SetItemCategory, SetItemLink, SetItemProperty, SetItemSimplifiedProperty, SetItemsSort, SetItemsSortDirection, SetPeriod, SetResource, SetSpatialUnit, SetTree, SimplifiedProperty, SpatialUnit, SpatialUnitItemLink, Text, TextItemLink, 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, getProperty, getPropertyValue, getPropertyValues, getUniqueProperties, getUniquePropertyVariableLabels, isPropertyMatchingFilter, normalizePropertyVariableLabel } from "./getters.mjs";
+import { flattenItemProperties } from "./helpers.mjs";
+import { defineLanguages } from "./parsers/languages.mjs";
+export { 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 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 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 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 StylesheetItem, type Text, type TextItemLink, 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, 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 { 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, 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

package/dist/ocr.mjs

@@ -0,0 +1,52 @@
+import { stringLiteral } from "./xquery.mjs";
+//#region src/ocr.ts
+const ALTO_NAMESPACE = "http://www.loc.gov/standards/alto/ns-v2#";
+/**
+* The local names OCHRE serves OCR word elements under
+*
+* OCHRE varies the casing, and serves the elements both in the ALTO namespace
+* and in no namespace at all. Every selector over the layer has to accept all
+* of them: an `xs:QName("String")` narrowing matches 2 of the 18,446 documents
+* carrying an OCR layer, while the ALTO-namespaced `String` matches 14,650.
+*/
+const OCR_WORD_LOCAL_NAMES = ["String", "string"];
+const OCR_WORD_CASE_FOLDED_LOCAL_NAME = "string";
+/**
+* The name of the element wrapping an OCR layer inside an OCHRE document
+* @internal
+*/
+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
+*/
+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
+*/
+const OCR_WORD_QNAMES = `(${[...OCR_WORD_LOCAL_NAMES.map((localName) => `fn:QName(${stringLiteral(ALTO_NAMESPACE)}, ${stringLiteral(localName)})`), ...OCR_WORD_LOCAL_NAMES.map((localName) => `xs:QName(${stringLiteral(localName)})`)].join(", ")})`;
+/**
+* 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
+*/
+function buildOcrWordPath(rootExpression) {
+	return `${rootExpression}//*[lower-case(local-name(.)) = ${stringLiteral("ocr")}]//*[lower-case(local-name(.)) = ${stringLiteral(OCR_WORD_CASE_FOLDED_LOCAL_NAME)}][@${OCR_WORD_CONTENT_ATTRIBUTE}]`;
+}
+//#endregion
+export { OCR_LAYER_ELEMENT_NAME, OCR_WORD_CONTENT_ATTRIBUTE, OCR_WORD_QNAMES, buildOcrWordPath };