@datocms/cma-client/dist/types/utilities/normalizedFieldValues.d.ts

JS client for DatoCMS REST Content Management API

import type * as ApiTypes from '../generated/ApiTypes';
import type * as RawApiTypes from '../generated/RawApiTypes';
/**
 * Represents a localized field value in DatoCMS.
 *
 * In DatoCMS, fields can be localized. In this scenario, their value contains values
 * for various locales structured as an object, such as
 * `{ "en": "Hello", "it": "Ciao" }`
 */
export type LocalizedFieldValue<T = unknown, L extends string = string> = Partial<Record<L, T>>;
/**
 * Determines whether a DatoCMS field is localized or not.
 *
 * This function handles both full Schema field objects and simplified Schema field objects
 * by checking the appropriate property based on the object structure.
 *
 * @returns true if the field is localized, false otherwise
 * @param field - The DatoCMS field definition (either full or simple schema)
 */
export declare function isLocalized(field: RawApiTypes.Field | ApiTypes.Field): boolean;
export declare function isLocalizedFieldValue<T = unknown, L extends string = string>(value: unknown): value is LocalizedFieldValue<T, L>;
/**
 * A normalized entry that represents a single value from either a localized or non-localized field.
 *
 * For localized fields, each locale produces one entry with `locale` set to the locale code (e.g., "en", "it").
 * For non-localized fields, there's one entry with `locale` set to `undefined`.
 *
 * This uniform structure allows the same processing logic to work with both field types.
 */
export type NormalizedFieldValueEntry<T = unknown, L extends string = string> = {
    locale: L | undefined;
    value: T;
};
/**
 * Converts a field value (localized or non-localized) into a uniform array of entries.
 *
 * This function normalizes the handling of field values by converting them into a consistent
 * array format, regardless of whether the field is localized or not.
 *
 * @param value - The field value to convert (either a localized object or direct value)
 * @param field - The DatoCMS field definition that determines localization behavior
 * @returns Array of entries where each entry contains a locale (string for localized, undefined for non-localized) and the corresponding value
 */
export declare function toNormalizedFieldValueEntries<T = unknown, L extends string = string>(value: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field): NormalizedFieldValueEntry<T, L>[];
/**
 * Converts an array of possibly localized entries back into the appropriate field value format.
 *
 * This function is the inverse of `toNormalizedFieldValueEntries`. It takes a uniform
 * array of entries and converts them back to either a localized object or a direct value,
 * depending on the field's localization setting.
 *
 * @param entries - Array of entries to convert back to field value format
 * @param field - The DatoCMS field definition that determines the output format
 * @returns Either a localized object (for localized fields) or the direct value (for non-localized fields)
 */
export declare function fromNormalizedFieldValueEntries<T = unknown, L extends string = string>(entries: NormalizedFieldValueEntry<T, L>[], field: RawApiTypes.Field | ApiTypes.Field): T | LocalizedFieldValue<T, L>;
/**
 * Maps field values using a provided mapping function.
 * For localized fields, applies the mapping function to each locale value.
 * For non-localized fields, applies the mapping function directly to the value.
 *
 * @template T - The type that the mapping function returns
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param mapFn - The function to apply to each locale value or the direct value
 * @returns The mapped value with the same structure as the input
 */
export declare function mapNormalizedFieldValues<TInput = unknown, TOutput = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: TInput | LocalizedFieldValue<TInput, L>, field: RawApiTypes.Field | ApiTypes.Field, mapFn: (locale: L | undefined, localeValue: TInput) => TOutput): TOutput | LocalizedFieldValue<TOutput, L>;
/**
 * Maps field values using a provided mapping function (async version).
 * For localized fields, applies the mapping function to each locale value.
 * For non-localized fields, applies the mapping function directly to the value.
 *
 * @template T - The type that the mapping function returns
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param mapFn - The function to apply to each locale value or the direct value
 * @returns The mapped value with the same structure as the input
 */
export declare function mapNormalizedFieldValuesAsync<TInput = unknown, TOutput = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: TInput | LocalizedFieldValue<TInput, L>, field: RawApiTypes.Field | ApiTypes.Field, mapFn: (locale: L | undefined, localeValue: TInput) => Promise<TOutput>): Promise<TOutput | LocalizedFieldValue<TOutput, L>>;
/**
 * Filters field values using a provided filter function.
 * For localized fields, filters each locale value.
 * For non-localized fields, returns the value if the filter passes, otherwise undefined.
 *
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param filterFn - The function to test each locale value or the direct value
 * @returns The filtered value with the same structure as the input
 */
export declare function filterNormalizedFieldValues<T = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field, filterFn: (locale: L | undefined, localeValue: T) => boolean): T | LocalizedFieldValue<T, L> | undefined;
/**
 * Filters field values using a provided filter function (async version).
 * For localized fields, filters each locale value.
 * For non-localized fields, returns the value if the filter passes, otherwise undefined.
 *
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param filterFn - The function to test each locale value or the direct value
 * @returns The filtered value with the same structure as the input
 */
export declare function filterNormalizedFieldValuesAsync<T = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field, filterFn: (locale: L | undefined, localeValue: T) => Promise<boolean>): Promise<T | LocalizedFieldValue<T, L> | undefined>;
/**
 * Tests whether at least one field value passes the test implemented by the provided function.
 * For localized fields, tests each locale value.
 * For non-localized fields, tests the direct value.
 *
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param testFn - The function to test each locale value or the direct value
 * @returns true if at least one value passes the test, false otherwise
 */
export declare function someNormalizedFieldValues<T = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field, testFn: (locale: L | undefined, localeValue: T) => boolean): boolean;
/**
 * Tests whether at least one field value passes the test implemented by the provided function (async version).
 * For localized fields, tests each locale value.
 * For non-localized fields, tests the direct value.
 *
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param testFn - The function to test each locale value or the direct value
 * @returns true if at least one value passes the test, false otherwise
 */
export declare function someNormalizedFieldValuesAsync<T = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field, testFn: (locale: L | undefined, localeValue: T) => Promise<boolean>): Promise<boolean>;
/**
 * Tests whether all field values pass the test implemented by the provided function.
 * For localized fields, tests each locale value.
 * For non-localized fields, tests the direct value.
 *
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param testFn - The function to test each locale value or the direct value
 * @returns true if all values pass the test, false otherwise
 */
export declare function everyNormalizedFieldValue<T = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field, testFn: (locale: L | undefined, localeValue: T) => boolean): boolean;
/**
 * Tests whether all field values pass the test implemented by the provided function (async version).
 * For localized fields, tests each locale value.
 * For non-localized fields, tests the direct value.
 *
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param testFn - The function to test each locale value or the direct value
 * @returns true if all values pass the test, false otherwise
 */
export declare function everyNormalizedFieldValueAsync<T = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field, testFn: (locale: L | undefined, localeValue: T) => Promise<boolean>): Promise<boolean>;
/**
 * Visits each field value with the provided function.
 * For localized fields, visits each locale value.
 * For non-localized fields, visits the direct value.
 *
 * @param value - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param visitFn - The function to call for each locale value or the direct value
 */
export declare function visitNormalizedFieldValues<T = unknown, L extends string = string>(value: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field, visitFn: (locale: L | undefined, localeValue: T) => void): void;
/**
 * Visits each field value with the provided function (async version).
 * For localized fields, visits each locale value.
 * For non-localized fields, visits the direct value.
 *
 * @param localizedOrNonLocalizedFieldValue - The field value (either localized object or direct value)
 * @param field - The DatoCMS field definition
 * @param visitFn - The function to call for each locale value or the direct value
 */
export declare function visitNormalizedFieldValuesAsync<T = unknown, L extends string = string>(localizedOrNonLocalizedFieldValue: T | LocalizedFieldValue<T, L>, field: RawApiTypes.Field | ApiTypes.Field, visitFn: (locale: L | undefined, localeValue: T) => Promise<void>): Promise<void>;