ochre-sdk 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/index.d.mts

@@ -1680,6 +1680,7 @@ type PropertyOptions = {
   limitToLeafPropertyValues?: boolean;
 };
 type PropertyContent<T extends ReadonlyArray<string>> = PropertyValueContent<T>["content"];
+type SearchableProperty<T extends ReadonlyArray<string>> = Property<T> | SingleHierarchyProperty<T>;
 /**
  * Finds a property by its label UUID in an array of properties.
  *
@@ -1689,6 +1690,7 @@ type PropertyContent<T extends ReadonlyArray<string>> = PropertyValueContent<T>[
  * @returns The matching Property object, or null if not found
  */
 declare function getPropertyByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelUuid: string, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SingleHierarchyProperty<T>>, labelUuid: string, options?: PropertyOptions): SingleHierarchyProperty<T> | null;
 /**
  * Retrieves all values for a property with the given label UUID.
  *
@@ -1697,7 +1699,7 @@ declare function getPropertyByLabelUuid<T extends ReadonlyArray<string> = Readon
  * @param options - Search options, including whether to include nested properties
  * @returns Array of property values, or null if property not found
  */
-declare function getPropertyValuesByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelUuid: string, options?: PropertyOptions): Array<PropertyValueContent<T>> | null;
+declare function getPropertyValuesByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SearchableProperty<T>>, labelUuid: string, options?: PropertyOptions): Array<PropertyValueContent<T>> | null;
 /**
  * Retrieves all value contents for a property with the given label UUID.
  *
@@ -1706,7 +1708,7 @@ declare function getPropertyValuesByLabelUuid<T extends ReadonlyArray<string> =
  * @param options - Search options, including whether to include nested properties
  * @returns Array of property value contents, or null if property not found
  */
-declare function getPropertyValueContentsByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelUuid: string, options?: PropertyOptions): Array<PropertyContent<T>> | null;
+declare function getPropertyValueContentsByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SearchableProperty<T>>, labelUuid: string, options?: PropertyOptions): Array<PropertyContent<T>> | null;
 /**
  * Gets the first value of a property with the given label UUID.
  *
@@ -1715,7 +1717,7 @@ declare function getPropertyValueContentsByLabelUuid<T extends ReadonlyArray<str
  * @param options - Search options, including whether to include nested properties
  * @returns The first property value, or null if property not found
  */
-declare function getPropertyValueByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelUuid: string, options?: PropertyOptions): PropertyValueContent<T> | null;
+declare function getPropertyValueByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SearchableProperty<T>>, labelUuid: string, options?: PropertyOptions): PropertyValueContent<T> | null;
 /**
  * Gets the first value content of a property with the given label UUID.
  *
@@ -1724,7 +1726,7 @@ declare function getPropertyValueByLabelUuid<T extends ReadonlyArray<string> = R
  * @param options - Search options, including whether to include nested properties
  * @returns The first property value content, or null if property not found
  */
-declare function getPropertyValueContentByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelUuid: string, options?: PropertyOptions): PropertyContent<T> | null;
+declare function getPropertyValueContentByLabelUuid<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SearchableProperty<T>>, labelUuid: string, options?: PropertyOptions): PropertyContent<T> | null;
 /**
  * Finds a property by its label name in an array of properties.
  *
@@ -1734,6 +1736,7 @@ declare function getPropertyValueContentByLabelUuid<T extends ReadonlyArray<stri
  * @returns The matching Property object, or null if not found
  */
 declare function getPropertyByLabelName<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelName: string, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByLabelName<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SingleHierarchyProperty<T>>, labelName: string, options?: PropertyOptions): SingleHierarchyProperty<T> | null;
 /**
  * Finds a property by its label name and all values.
  *
@@ -1744,6 +1747,7 @@ declare function getPropertyByLabelName<T extends ReadonlyArray<string> = Readon
  * @returns The matching Property object, or null if not found or all values do not match
  */
 declare function getPropertyByLabelNameAndValues<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelName: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByLabelNameAndValues<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SingleHierarchyProperty<T>>, labelName: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): SingleHierarchyProperty<T> | null;
 /**
  * Finds a property by its label name and all value contents.
  *
@@ -1754,6 +1758,7 @@ declare function getPropertyByLabelNameAndValues<T extends ReadonlyArray<string>
  * @returns The matching Property object, or null if not found or all value contents do not match
  */
 declare function getPropertyByLabelNameAndValueContents<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelName: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByLabelNameAndValueContents<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SingleHierarchyProperty<T>>, labelName: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): SingleHierarchyProperty<T> | null;
 /**
  * Finds a property by its label name and one value.
  *
@@ -1764,6 +1769,7 @@ declare function getPropertyByLabelNameAndValueContents<T extends ReadonlyArray<
  * @returns The matching Property object, or null if not found or value does not match
  */
 declare function getPropertyByLabelNameAndValue<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelName: string, value: PropertyValueContent<T>, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByLabelNameAndValue<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SingleHierarchyProperty<T>>, labelName: string, value: PropertyValueContent<T>, options?: PropertyOptions): SingleHierarchyProperty<T> | null;
 /**
  * Finds a property by its label name and one value content.
  *
@@ -1774,6 +1780,7 @@ declare function getPropertyByLabelNameAndValue<T extends ReadonlyArray<string>
  * @returns The matching Property object, or null if not found or value content does not match
  */
 declare function getPropertyByLabelNameAndValueContent<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelName: string, valueContent: PropertyContent<T>, options?: PropertyOptions): Property<T> | null;
+declare function getPropertyByLabelNameAndValueContent<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SingleHierarchyProperty<T>>, labelName: string, valueContent: PropertyContent<T>, options?: PropertyOptions): SingleHierarchyProperty<T> | null;
 /**
  * Retrieves all values for a property with the given label name.
  *
@@ -1782,7 +1789,7 @@ declare function getPropertyByLabelNameAndValueContent<T extends ReadonlyArray<s
  * @param options - Search options, including whether to include nested properties
  * @returns Array of property values, or null if property not found
  */
-declare function getPropertyValuesByLabelName<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelName: string, options?: PropertyOptions): Array<PropertyValueContent<T>> | null;
+declare function getPropertyValuesByLabelName<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SearchableProperty<T>>, labelName: string, options?: PropertyOptions): Array<PropertyValueContent<T>> | null;
 /**
  * Gets the first value of a property with the given label name.
  *
@@ -1791,7 +1798,7 @@ declare function getPropertyValuesByLabelName<T extends ReadonlyArray<string> =
  * @param options - Search options, including whether to include nested properties
  * @returns The first property value, or null if property not found
  */
-declare function getPropertyValueByLabelName<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelName: string, options?: PropertyOptions): PropertyValueContent<T> | null;
+declare function getPropertyValueByLabelName<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SearchableProperty<T>>, labelName: string, options?: PropertyOptions): PropertyValueContent<T> | null;
 /**
  * Gets the first value content of a property with the given label name.
  *
@@ -1800,7 +1807,7 @@ declare function getPropertyValueByLabelName<T extends ReadonlyArray<string> = R
  * @param options - Search options, including whether to include nested properties
  * @returns The first property value content, or null if property not found
  */
-declare function getPropertyValueContentByLabelName<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, labelName: string, options?: PropertyOptions): PropertyContent<T> | null;
+declare function getPropertyValueContentByLabelName<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SearchableProperty<T>>, labelName: string, options?: PropertyOptions): PropertyContent<T> | null;
 /**
  * Gets all unique properties from an array of properties.
  *
@@ -1809,6 +1816,7 @@ declare function getPropertyValueContentByLabelName<T extends ReadonlyArray<stri
  * @returns Array of unique properties
  */
 declare function getUniqueProperties<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, options?: PropertyOptions): Array<Property<T>>;
+declare function getUniqueProperties<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SingleHierarchyProperty<T>>, options?: PropertyOptions): Array<SingleHierarchyProperty<T>>;
 /**
  * Gets all unique property label names from an array of properties.
  *
@@ -1816,7 +1824,7 @@ declare function getUniqueProperties<T extends ReadonlyArray<string> = ReadonlyA
  * @param options - Search options, including whether to include nested properties
  * @returns Array of unique property label names
  */
-declare function getUniquePropertyLabelNames<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<Property<T>>, options?: PropertyOptions): Array<string>;
+declare function getUniquePropertyLabelNames<T extends ReadonlyArray<string> = ReadonlyArray<string>>(properties: ReadonlyArray<SearchableProperty<T>>, options?: PropertyOptions): Array<string>;
 /**
  * Get the leaf property values from an array of property values.
  *
@@ -1834,7 +1842,7 @@ declare function getLeafPropertyValues<T extends ReadonlyArray<string> = Readonl
  * @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 ReadonlyArray<string> = ReadonlyArray<string>>(property: Property<T>, filter: {
+declare function filterProperties<T extends ReadonlyArray<string> = ReadonlyArray<string>>(property: SearchableProperty<T>, filter: {
   labelName: string;
   value: PropertyValueContent<T>;
 }, options?: PropertyOptions): boolean;

package/dist/index.mjs

@@ -879,9 +879,13 @@ function parseWhitespace(contentString, whitespace, rendering) {
 * @internal
 */
 function parseXMLStringVariant(string, options) {
-	let returnString = (string.payload ?? "").replaceAll("<", options.rendering === "rich" ? String.raw`\<` : "<").replaceAll("{", String.raw`\{`).replaceAll("}", String.raw`\}`);
+	let returnString = parseXMLStringPayload(string, options);
 	if (string.whitespace != null) returnString = parseWhitespace(returnString, string.whitespace, options.rendering);
 	if (string.rend != null) returnString = parseRenderOptions(returnString, string.rend, options.rendering);
+	return returnString;
+}
+function parseXMLStringPayload(string, options) {
+	const returnString = (string.payload ?? "").replaceAll("<", options.rendering === "rich" ? String.raw`\<` : "<").replaceAll("{", String.raw`\{`).replaceAll("}", String.raw`\}`);
 	return options.parseEmail ? parseEmail(returnString) : returnString;
 }
 function parseXMLString(string, options) {
@@ -1035,14 +1039,13 @@ function hasRichTextEnvelope(item) {
 	return item.properties?.property[0] != null || getXMLRichTextLinks(item).length > 0;
 }
 function parseXMLStringItem(item, contentItem, options) {
-	if (item.payload != null) return parseXMLStringVariant(item, {
-		rendering: options.rendering,
-		parseEmail: options.parseEmail
-	});
-	if (item.string == null && item.whitespace != null) return parseWhitespace("", item.whitespace, options.rendering);
-	if (item.string == null) return "";
+	if (item.payload == null && item.string == null && item.whitespace != null) return parseWhitespace("", item.whitespace, options.rendering);
+	if (item.payload == null && item.string == null) return "";
 	if (hasRichTextEnvelope(item)) {
-		let linkString = parseNestedStringItems(item.string, contentItem, {
+		let linkString = item.payload != null ? parseXMLStringPayload(item, {
+			rendering: options.rendering,
+			parseEmail: false
+		}) : parseNestedStringItems(item.string ?? [], contentItem, {
 			...options,
 			parseEmail: false
 		});
@@ -1050,7 +1053,11 @@ function parseXMLStringItem(item, contentItem, options) {
 		if (options.rendering === "plain") return applyWhitespaceToResult(linkString, item.whitespace, options.rendering);
 		return renderRichTextItem(item, linkString, contentItem, options);
 	}
-	let result = parseNestedStringItems(item.string, contentItem, options);
+	if (item.payload != null) return parseXMLStringVariant(item, {
+		rendering: options.rendering,
+		parseEmail: options.parseEmail
+	});
+	let result = parseNestedStringItems(item.string ?? [], contentItem, options);
 	if (item.rend != null) result = parseRenderOptions(result, item.rend, options.rendering);
 	return applyWhitespaceToResult(result, item.whitespace, options.rendering);
 }
@@ -5194,6 +5201,7 @@ function searchPropertyResult(properties, options, findDirectResult, transformNe
 	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;
@@ -5256,17 +5264,9 @@ function getFirstPropertyValueContentResult(values, limitToLeafPropertyValues) {
 function visitProperties(properties, includeNestedProperties, visit) {
 	for (const property of properties) {
 		visit(property);
-		if (includeNestedProperties) visitProperties(property.properties, includeNestedProperties, visit);
+		if (includeNestedProperties && "properties" in property) visitProperties(property.properties, includeNestedProperties, visit);
 	}
 }
-/**
-* Finds a property by its label UUID in an array of properties.
-*
-* @param properties - Array of properties to search through
-* @param labelUuid - The property label UUID to search for
-* @param options - Search options, including whether to include nested properties
-* @returns The matching Property object, or null if not found
-*/
 function getPropertyByLabelUuid(properties, labelUuid, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = withDefaultOptions(options);
 	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => findPropertyByLabelUuid(currentProperties, labelUuid));
@@ -5343,27 +5343,10 @@ function getPropertyValueContentByLabelUuid(properties, labelUuid, options = DEF
 		return getFirstPropertyValueContentResult(values, limitToLeafPropertyValues);
 	});
 }
-/**
-* Finds a property by its label name in an array of properties.
-*
-* @param properties - Array of properties to search through
-* @param labelName - The property label name to search for
-* @param options - Search options, including whether to include nested properties
-* @returns The matching Property object, or null if not found
-*/
 function getPropertyByLabelName(properties, labelName, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties } = withDefaultOptions(options);
 	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => findPropertyByLabelName(currentProperties, labelName));
 }
-/**
-* Finds a property by its label name and all values.
-*
-* @param properties - Array of properties to search through
-* @param labelName - The property label name 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
-*/
 function getPropertyByLabelNameAndValues(properties, labelName, values, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
 	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
@@ -5371,15 +5354,6 @@ function getPropertyByLabelNameAndValues(properties, labelName, values, options
 		return null;
 	}, (nestedResult) => getNormalizedProperty(nestedResult, limitToLeafPropertyValues));
 }
-/**
-* Finds a property by its label name and all value contents.
-*
-* @param properties - Array of properties to search through
-* @param labelName - The property label name 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
-*/
 function getPropertyByLabelNameAndValueContents(properties, labelName, valueContents, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
 	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
@@ -5387,15 +5361,6 @@ function getPropertyByLabelNameAndValueContents(properties, labelName, valueCont
 		return null;
 	}, (nestedResult) => getNormalizedProperty(nestedResult, limitToLeafPropertyValues));
 }
-/**
-* Finds a property by its label name and one value.
-*
-* @param properties - Array of properties to search through
-* @param labelName - The property label name 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
-*/
 function getPropertyByLabelNameAndValue(properties, labelName, value, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
 	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
@@ -5403,15 +5368,6 @@ function getPropertyByLabelNameAndValue(properties, labelName, value, options =
 		return null;
 	}, (nestedResult) => getNormalizedProperty(nestedResult, limitToLeafPropertyValues));
 }
-/**
-* Finds a property by its label name and one value content.
-*
-* @param properties - Array of properties to search through
-* @param labelName - The property label name 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
-*/
 function getPropertyByLabelNameAndValueContent(properties, labelName, valueContent, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
 	return searchPropertyResult(properties, { includeNestedProperties }, (currentProperties) => {
@@ -5473,13 +5429,6 @@ function getPropertyValueContentByLabelName(properties, labelName, options = DEF
 		return getFirstPropertyValueContentResult(values, limitToLeafPropertyValues);
 	});
 }
-/**
-* 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
-*/
 function getUniqueProperties(properties, options = DEFAULT_OPTIONS) {
 	const { includeNestedProperties, limitToLeafPropertyValues } = withDefaultOptions(options);
 	const uniqueProperties = [];
@@ -5542,7 +5491,7 @@ function filterProperties(property, filter, options = DEFAULT_OPTIONS) {
 		const values = getPropertyValuesResult(property.values, limitToLeafPropertyValues, false);
 		for (const value of values) if (contentMatchesFilter(value.content, filter.value.content)) return true;
 	}
-	if (includeNestedProperties) {
+	if (includeNestedProperties && "properties" in property) {
 		for (const nestedProperty of property.properties) if (filterProperties(nestedProperty, filter, {
 			includeNestedProperties: true,
 			limitToLeafPropertyValues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ochre-sdk",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "type": "module",
   "license": "MIT",
   "description": "Node.js library for working with OCHRE (Online Cultural and Historical Research Environment) data",