ochre-sdk 1.0.78 → 1.1.0

package/dist/getters.d.mts

@@ -1,4 +1,4 @@
-import { LanguageCodes, Property, PropertyLike, PropertyValueContent, SetItemProperty, SetItemSimplifiedProperty, SimplifiedProperty } from "./types/index.mjs";
+import { LanguageCodes, PropertyLike, PropertyValueContent } from "./types/index.mjs";
 //#region src/getters.d.ts
 /**
  * Options for property search operations.
@@ -9,188 +9,118 @@ export type PropertyOptions = {
     */
   includeNestedProperties?: boolean;
   /**
-    Whether to limit property values to leaf values.
+    Whether to limit property values to leaf values. Applies to the value
+    lookups; {@link getProperty} and {@link getUniqueProperties} always return a
+    property exactly as it was found.
     */
   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
- */
-export declare function getPropertyByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableUuid: string, options?: PropertyOptions): Property<T> | null;
-export declare function getPropertyByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableUuid: string, options?: PropertyOptions): SetItemProperty<T> | null;
-export declare function getPropertyByVariableUuid<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableUuid: string, options?: PropertyOptions): SimplifiedProperty<T> | null;
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export declare function getPropertyByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, options?: PropertyOptions): Property<T> | null;
-export declare function getPropertyByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, options?: PropertyOptions): SetItemProperty<T> | null;
-export declare function getPropertyByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, options?: PropertyOptions): SimplifiedProperty<T> | null;
-export 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
- */
-export declare function getPropertyByVariableLabelAndValues<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): Property<T> | null;
-export declare function getPropertyByVariableLabelAndValues<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): SetItemProperty<T> | null;
-export declare function getPropertyByVariableLabelAndValues<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, values: ReadonlyArray<PropertyValueContent<T>>, options?: PropertyOptions): SimplifiedProperty<T> | null;
-export 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
- */
-export declare function getPropertyByVariableLabelAndValueContents<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): Property<T> | null;
-export declare function getPropertyByVariableLabelAndValueContents<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): SetItemProperty<T> | null;
-export declare function getPropertyByVariableLabelAndValueContents<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, valueContents: ReadonlyArray<PropertyContent<T>>, options?: PropertyOptions): SimplifiedProperty<T> | null;
-export 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
- */
-export declare function getPropertyByVariableLabelAndValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, value: PropertyValueContent<T>, options?: PropertyOptions): Property<T> | null;
-export declare function getPropertyByVariableLabelAndValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, value: PropertyValueContent<T>, options?: PropertyOptions): SetItemProperty<T> | null;
-export declare function getPropertyByVariableLabelAndValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, value: PropertyValueContent<T>, options?: PropertyOptions): SimplifiedProperty<T> | null;
-export declare function getPropertyByVariableLabelAndValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, variableLabel: string, value: PropertyValueContent<T>, options?: PropertyOptions): SetItemSimplifiedProperty<T> | null;
+ * Which property to look for
+ *
+ * A property is named either by its variable UUID or by its variable label, and
+ * a label can be narrowed further by the values the property carries. The value
+ * forms differ in what they compare: `values` and `valueContents` require the
+ * property to carry exactly that sequence, while `value` and `valueContent`
+ * only require it to carry that one among others.
+ */
+export type PropertySelector<T extends LanguageCodes = LanguageCodes> = {
+  uuid: string;
+} | {
+  label: string;
+} | {
+  label: string;
+  values: ReadonlyArray<PropertyValueContent<T>>;
+} | {
+  label: string;
+  valueContents: ReadonlyArray<PropertyContent<T>>;
+} | {
+  label: string;
+  value: PropertyValueContent<T>;
+} | {
+  label: string;
+  valueContent: PropertyContent<T>;
+};
 /**
- * Finds a property by its variable label and one value content.
+ * Normalize an OCHRE property variable label for comparison
  *
- * @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
+ * 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
  */
-export declare function getPropertyByVariableLabelAndValueContent<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, variableLabel: string, valueContent: PropertyContent<T>, options?: PropertyOptions): Property<T> | null;
-export declare function getPropertyByVariableLabelAndValueContent<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, variableLabel: string, valueContent: PropertyContent<T>, options?: PropertyOptions): SetItemProperty<T> | null;
-export declare function getPropertyByVariableLabelAndValueContent<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, variableLabel: string, valueContent: PropertyContent<T>, options?: PropertyOptions): SimplifiedProperty<T> | null;
-export declare function getPropertyByVariableLabelAndValueContent<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, variableLabel: string, valueContent: PropertyContent<T>, options?: PropertyOptions): SetItemSimplifiedProperty<T> | null;
+export declare function normalizePropertyVariableLabel(value: string): string;
 /**
- * Retrieves all values for a property with the given variable label.
+ * Find the property a selector names
  *
- * @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
+ * 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
  */
-export declare function getPropertyValuesByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableLabel: string, options?: PropertyOptions): Array<PropertyValueContent<T>> | null;
+export declare function getProperty<T extends LanguageCodes = LanguageCodes, TProperty extends PropertyLike<T> = PropertyLike<T>>(properties: ReadonlyArray<TProperty>, selector: PropertySelector<T>, options?: PropertyOptions): TProperty | 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
+ * 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
  */
-export declare function getPropertyValueByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableLabel: string, options?: PropertyOptions): PropertyValueContent<T> | null;
+export declare function getPropertyValues<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, selector: PropertySelector<T>, options?: PropertyOptions): Array<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
+ * 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
  */
-export declare function getPropertyValueContentByVariableLabel<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, variableLabel: string, options?: PropertyOptions): PropertyContent<T> | null;
+export declare function getPropertyValue<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SearchableProperty<T>>, selector: PropertySelector<T>, options?: PropertyOptions): PropertyValueContent<T> | null;
 /**
  * Gets all unique properties from an array of properties.
  *
+ * 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, including whether to include nested properties
+ * @param options - Search options
+ * @param options.includeNestedProperties - Whether to descend into nested properties
  * @returns Array of unique properties
  */
-export declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<Property<T>>, options?: PropertyOptions): Array<Property<T>>;
-export declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemProperty<T>>, options?: PropertyOptions): Array<SetItemProperty<T>>;
-export declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SimplifiedProperty<T>>, options?: PropertyOptions): Array<SimplifiedProperty<T>>;
-export declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes>(properties: ReadonlyArray<SetItemSimplifiedProperty<T>>, options?: PropertyOptions): Array<SetItemSimplifiedProperty<T>>;
+export declare function getUniqueProperties<T extends LanguageCodes = LanguageCodes, TProperty extends PropertyLike<T> = PropertyLike<T>>(properties: ReadonlyArray<TProperty>, options?: PropertyOptions): Array<TProperty>;
 /**
  * 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
  */
 export 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
- */
-export 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.
+ * 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
  */
-export declare function filterProperties<T extends LanguageCodes = LanguageCodes>(property: SearchableProperty<T>, filter: {
+export declare function isPropertyMatchingFilter<T extends LanguageCodes = LanguageCodes>(property: SearchableProperty<T>, filter: {
   variableLabel: string;
   value: PropertyValueContent<T>;
 }, options?: PropertyOptions): boolean;