ochre-sdk 1.0.13 → 1.0.14

package/dist/getters.d.mts

@@ -0,0 +1,193 @@
+import { LanguageCodes, Property, PropertyLike, PropertyValueContent, SetItemProperty, SetItemSimplifiedProperty, SimplifiedProperty } from "./types/index.mjs";
+
+//#region src/getters.d.ts
+/**
+ * Options for property search operations.
+ */
+type PropertyOptions = {
+  /** Whether to recursively search through nested properties. */includeNestedProperties?: boolean; /** Whether to limit property values to leaf values. */
+  limitToLeafPropertyValues?: boolean;
+};
+type PropertyContent<T extends LanguageCodes> = PropertyValueContent<T>["content"];
+type SearchableProperty<T extends LanguageCodes> = PropertyLike<T>;
+/**
+ * Finds a property by its variable UUID in an array of properties.
+ *
+ * @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 matching Property object, or null if not found
+ */
+declare function getPropertyByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableUuid: string, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableUuid: string, options?: PropertyOptions): SetItemProperty<T> | null;
+declare function getPropertyByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableUuid: string, options?: PropertyOptions): SimplifiedProperty<T> | null;
+declare function getPropertyByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, variableUuid: string, options?: PropertyOptions): SetItemSimplifiedProperty<T> | null;
+/**
+ * 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
+ */
+declare function getPropertyValuesByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableUuid: string, options?: PropertyOptions): Array<PropertyValueContent<T>> | null;
+/**
+ * Retrieves all value contents 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 value contents, or null if property not found
+ */
+declare function getPropertyValueContentsByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableUuid: string, options?: PropertyOptions): Array<PropertyContent<T>> | null;
+/**
+ * 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
+ */
+declare function getPropertyValueByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableUuid: string, options?: PropertyOptions): PropertyValueContent<T> | null;
+/**
+ * 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
+ */
+declare function getPropertyValueContentByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableUuid: string, options?: PropertyOptions): PropertyContent<T> | null;
+/**
+ * Finds a property by its variable label in 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 matching Property object, or null if not found
+ */
+declare function getPropertyByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, options?: PropertyOptions): SetItemProperty<T> | null;
+declare function getPropertyByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, options?: PropertyOptions): SimplifiedProperty<T> | null;
+declare function getPropertyByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, variableLabel: string, options?: PropertyOptions): SetItemSimplifiedProperty<T> | null;
+/**
+ * Finds a property by its variable label and all values.
+ *
+ * @param properties - Array of properties to search through
+ * @param variableLabel - The property variable label to search for
+ * @param values - The property values to search for
+ * @param options - Search options, including whether to include nested properties
+ * @returns The matching Property object, or null if not found or all values do not match
+ */
+declare function getPropertyByVariableLabelAndValues<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByVariableLabelAndValues<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): SetItemProperty<T> | null;
+declare function getPropertyByVariableLabelAndValues<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): SimplifiedProperty<T> | null;
+declare function getPropertyByVariableLabelAndValues<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, variableLabel: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): SetItemSimplifiedProperty<T> | null;
+/**
+ * Finds a property by its variable label and all value contents.
+ *
+ * @param properties - Array of properties to search through
+ * @param variableLabel - The property variable label to search for
+ * @param valueContents - The value contents to search for
+ * @param options - Search options, including whether to include nested properties
+ * @returns The matching Property object, or null if not found or all value contents do not match
+ */
+declare function getPropertyByVariableLabelAndValueContents<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByVariableLabelAndValueContents<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): SetItemProperty<T> | null;
+declare function getPropertyByVariableLabelAndValueContents<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): SimplifiedProperty<T> | null;
+declare function getPropertyByVariableLabelAndValueContents<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, variableLabel: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): SetItemSimplifiedProperty<T> | null;
+/**
+ * Finds a property by its variable label and one value.
+ *
+ * @param properties - Array of properties to search through
+ * @param variableLabel - The property variable label to search for
+ * @param value - The property value to search for
+ * @param options - Search options, including whether to include nested properties
+ * @returns The matching Property object, or null if not found or value does not match
+ */
+declare function getPropertyByVariableLabelAndValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, value: PropertyValueContent<T>, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByVariableLabelAndValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, value: PropertyValueContent<T>, options?: PropertyOptions): SetItemProperty<T> | null;
+declare function getPropertyByVariableLabelAndValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, value: PropertyValueContent<T>, options?: PropertyOptions): SimplifiedProperty<T> | null;
+declare function getPropertyByVariableLabelAndValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, variableLabel: string, value: PropertyValueContent<T>, options?: PropertyOptions): SetItemSimplifiedProperty<T> | null;
+/**
+ * Finds a property by its variable label and one value content.
+ *
+ * @param properties - Array of properties to search through
+ * @param variableLabel - The property variable label to search for
+ * @param valueContent - The value content to search for
+ * @param options - Search options, including whether to include nested properties
+ * @returns The matching Property object, or null if not found or value content does not match
+ */
+declare function getPropertyByVariableLabelAndValueContent<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, valueContent: PropertyContent<T>, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByVariableLabelAndValueContent<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, valueContent: PropertyContent<T>, options?: PropertyOptions): SetItemProperty<T> | null;
+declare function getPropertyByVariableLabelAndValueContent<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, valueContent: PropertyContent<T>, options?: PropertyOptions): SimplifiedProperty<T> | null;
+declare function getPropertyByVariableLabelAndValueContent<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, variableLabel: string, valueContent: PropertyContent<T>, options?: PropertyOptions): SetItemSimplifiedProperty<T> | null;
+/**
+ * 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
+ */
+declare function getPropertyValuesByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableLabel: string, options?: PropertyOptions): Array<PropertyValueContent<T>> | null;
+/**
+ * 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
+ */
+declare function getPropertyValueByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableLabel: string, options?: PropertyOptions): PropertyValueContent<T> | null;
+/**
+ * Gets the first value content 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 content, or null if property not found
+ */
+declare function getPropertyValueContentByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableLabel: string, options?: PropertyOptions): PropertyContent<T> | null;
+/**
+ * Gets all unique properties from an array of properties.
+ *
+ * @param properties - Array of properties to get unique properties from
+ * @param options - Search options, including whether to include nested properties
+ * @returns Array of unique properties
+ */
+declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, options?: PropertyOptions): Array<Property<T>>;
+declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, options?: PropertyOptions): Array<SetItemProperty<T>>;
+declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, options?: PropertyOptions): Array<SimplifiedProperty<T>>;
+declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, options?: PropertyOptions): Array<SetItemSimplifiedProperty<T>>;
+/**
+ * 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
+ * @returns Array of unique property variable labels
+ */
+declare function getUniquePropertyVariableLabels<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, options?: PropertyOptions): Array<string>;
+/**
+ * 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
+ */
+declare function getLeafPropertyValues<T extends LanguageCodes = LanguageCodes>(propertyValues: ReadonlyArray<PropertyValueContent<T>>): Array<PropertyValueContent<T>>;
+/**
+ * Filters a property based on a variable label and value content criterion.
+ *
+ * @param property - The property to filter
+ * @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
+ * @returns True if the property matches the filter criteria, false otherwise
+ */
+declare function filterProperties<T extends LanguageCodes = LanguageCodes>(property: SearchableProperty<T>, filter: {
+  variableLabel: string;
+  value: PropertyValueContent<T>;
+}, options?: PropertyOptions): boolean;
+//#endregion
+export { PropertyOptions, filterProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels };

package/dist/getters.mjs

@@ -0,0 +1,341 @@
+import { deepEqual } from "fast-equals";
+//#region src/getters.ts
+const DEFAULT_OPTIONS = {
+	includeNestedProperties: false,
+	limitToLeafPropertyValues: true
+};
+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();
+}
+function propertyHasValue(property, value) {
+	for (const candidateValue of property.values) if (deepEqual(candidateValue, value)) return true;
+	return false;
+}
+function propertyHasValueContent(property, valueContent) {
+	for (const value of property.values) if (deepEqual(value.content, valueContent)) return true;
+	return false;
+}
+function propertyValueContentsEqual(property, valueContents) {
+	if (property.values.length !== valueContents.length) return false;
+	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) for (const property of properties) {
+		if (!("properties" in property)) continue;
+		const nestedResult = searchPropertyResult(property.properties, options, findDirectResult, transformNestedResult);
+		if (nestedResult !== null) {
+			const transformedResult = transformNestedResult != null ? transformNestedResult(nestedResult) : nestedResult;
+			if (transformedResult !== null) return transformedResult;
+		}
+	}
+	return null;
+}
+function getPropertyValuesResult(values, limitToLeafPropertyValues, copyValuesWhenUnfiltered) {
+	if (limitToLeafPropertyValues) return getLeafPropertyValues(values);
+	if (copyValuesWhenUnfiltered) return clonePropertyValues(values);
+	return [...values];
+}
+function clonePropertyValues(values) {
+	const clonedValues = [];
+	for (const value of values) switch (value.dataType) {
+		case "IDREF":
+		case "coordinate":
+		case "date":
+		case "dateTime":
+		case "string":
+			clonedValues.push({
+				...value,
+				content: value.content
+			});
+			break;
+		case "decimal":
+		case "integer":
+		case "time":
+			clonedValues.push({
+				...value,
+				content: value.content
+			});
+			break;
+		case "boolean":
+			clonedValues.push({
+				...value,
+				content: value.content
+			});
+			break;
+	}
+	return clonedValues;
+}
+function getNormalizedProperty(property, limitToLeafPropertyValues, transformValues) {
+	if (!limitToLeafPropertyValues) return property;
+	const values = getLeafPropertyValues(property.values);
+	return {
+		...property,
+		values: transformValues != null ? transformValues(values) : values
+	};
+}
+function getFirstPropertyValueResult(values, limitToLeafPropertyValues) {
+	if (limitToLeafPropertyValues) return getLeafPropertyValues(values)[0] ?? null;
+	return values[0] ?? null;
+}
+function getFirstPropertyValueContentResult(values, limitToLeafPropertyValues) {
+	if (limitToLeafPropertyValues) return getLeafPropertyValues(values)[0]?.content ?? null;
+	return values[0]?.content ?? null;
+}
+function visitProperties(properties, includeNestedProperties, visit) {
+	for (const property of properties) {
+		visit(property);
+		if (includeNestedProperties && "properties" in property) visitProperties(property.properties, includeNestedProperties, 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.
+*
+* @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
+*/
+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;
+		const valueContents = [];
+		for (const value of getPropertyValuesResult(property.values, limitToLeafPropertyValues, false)) valueContents.push(value.content);
+		return valueContents;
+	});
+}
+/**
+* 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) {
+	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 && propertyValueContentsEqual(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 && propertyHasValue(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 && propertyHasValueContent(property, valueContent)) return getNormalizedProperty(property, limitToLeafPropertyValues);
+		return null;
+	}, (nestedResult) => getNormalizedProperty(nestedResult, limitToLeafPropertyValues));
+}
+/**
+* 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
+*/
+function getPropertyValuesByVariableLabel(properties, variableLabel, 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));
+}
+/**
+* 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
+*/
+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));
+}
+/**
+* Gets the first value content 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 content, or null if property not found
+*/
+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 uniqueProperties = [];
+	visitProperties(properties, includeNestedProperties, (property) => {
+		for (const uniqueProperty of uniqueProperties) if (uniqueProperty.variable.uuid === property.variable.uuid) return;
+		uniqueProperties.push(property);
+	});
+	if (limitToLeafPropertyValues) {
+		const normalizedProperties = [];
+		for (const property of uniqueProperties) normalizedProperties.push(getNormalizedProperty(property, limitToLeafPropertyValues));
+		return normalizedProperties;
+	}
+	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
+* @returns Array of unique property variable labels
+*/
+function getUniquePropertyVariableLabels(properties, options = DEFAULT_OPTIONS) {
+	const { includeNestedProperties } = withDefaultOptions(options);
+	const uniquePropertyVariableLabels = [];
+	visitProperties(properties, includeNestedProperties, (property) => {
+		const variableLabel = getPropertyVariableLabel(property);
+		if (uniquePropertyVariableLabels.includes(variableLabel)) return;
+		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 contentMatchesFilter(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.
+*
+* @param property - The property to filter
+* @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
+* @returns True if the property matches the filter criteria, false otherwise
+*/
+function filterProperties(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);
+		for (const value of values) if (contentMatchesFilter(value.content, filter.value.content)) return true;
+	}
+	if (includeNestedProperties && "properties" in property) {
+		for (const nestedProperty of property.properties) if (filterProperties(nestedProperty, filter, {
+			includeNestedProperties: true,
+			limitToLeafPropertyValues
+		})) return true;
+	}
+	return false;
+}
+//#endregion
+export { filterProperties, getLeafPropertyValues, getPropertyByVariableLabel, getPropertyByVariableLabelAndValue, getPropertyByVariableLabelAndValueContent, getPropertyByVariableLabelAndValueContents, getPropertyByVariableLabelAndValues, getPropertyByVariableUuid, getPropertyValueByVariableLabel, getPropertyValueByVariableUuid, getPropertyValueContentByVariableLabel, getPropertyValueContentByVariableUuid, getPropertyValueContentsByVariableUuid, getPropertyValuesByVariableLabel, getPropertyValuesByVariableUuid, getUniqueProperties, getUniquePropertyVariableLabels };

package/dist/helpers.d.mts

@@ -0,0 +1,18 @@
+import { ContainedItemCategory, Item, ItemCategory, ItemPayloadKind, LanguageCodes, SetItemProperty } from "./types/index.mjs";
+
+//#region src/helpers.d.ts
+type FlattenedItem<U, T extends LanguageCodes> = Omit<U, "properties"> & {
+  properties: Array<SetItemProperty<T>>;
+};
+/**
+ * The default page size to use for fetching paginated items
+ */
+declare 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
+ */
+declare function flattenItemProperties<U extends ItemCategory = ItemCategory, V extends ContainedItemCategory<U> = ContainedItemCategory<U>, T extends LanguageCodes = LanguageCodes, W extends ItemPayloadKind = "topLevel">(item: Item<U, V, T, W>): FlattenedItem<Item<U, V, T, W>, T>;
+//#endregion
+export { DEFAULT_PAGE_SIZE, flattenItemProperties };

package/dist/helpers.mjs

@@ -0,0 +1,33 @@
+import { flattenProperties } from "./utils.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
+*/
+function flattenItemProperties(item) {
+	const allProperties = [];
+	if ("properties" in item) allProperties.push(...item.properties);
+	if ("observations" in item) {
+		const { observations } = item;
+		for (const observation of observations) allProperties.push(...observation.properties);
+	}
+	if ("interpretations" in item) {
+		const { interpretations } = item;
+		for (const interpretation of interpretations) allProperties.push(...interpretation.properties);
+	}
+	if ("bibliographies" in item) {
+		const { bibliographies } = item;
+		for (const bibliography of bibliographies) allProperties.push(...bibliography.properties);
+	}
+	return {
+		...item,
+		properties: flattenProperties(allProperties)
+	};
+}
+//#endregion
+export { DEFAULT_PAGE_SIZE, flattenItemProperties };