@datocms/cma-client 5.1.9 → 5.1.11

package/dist/types/utilities/nonRecursiveBlocks.d.ts

@@ -0,0 +1,179 @@
+/**
+ * DatoCMS Block Field Value Processing Utilities
+ *
+ * This utility provides a unified interface for working with blocks embedded within DatoCMS field values.
+ * DatoCMS supports three field types that can contain blocks:
+ * - Modular Content fields: arrays of blocks
+ * - Single Block fields: a single block
+ * - Structured Text fields: complex document structures with embedded blocks
+ *
+ * The challenge this solves: Each field type stores blocks differently and requires different
+ * traversal logic, making it complex to perform operations like transformations, filtering,
+ * or searching across blocks regardless of their containing field type.
+ *
+ * This utility abstracts away these differences, providing a consistent API to:
+ * - Visit/iterate through all blocks in any field type
+ * - Transform blocks while preserving field structure
+ * - Filter blocks based on conditions
+ * - Search for specific blocks
+ * - Perform functional operations (map, reduce, some, every)
+ *
+ * All functions come in both sync and async variants to support different use cases,
+ * particularly useful when block transformations require async operations like API calls.
+ */
+import { type TreePath } from 'datocms-structured-text-utils';
+import type { BlockItemInARequest } from '../fieldTypes';
+import type * as ApiTypes from '../generated/ApiTypes';
+/**
+ * Visit every block in a field value, calling the visitor function for each block found.
+ * Supports rich text, single block, and structured text field types.
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to visit
+ * @param visitor - Synchronous function called for each block. Receives the block item and its path
+ */
+export declare function nonRecursiveVisitBlocksInNonLocalizedFieldValue(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, visitor: (item: BlockItemInARequest, path: TreePath) => void): void;
+/**
+ * Visit every block in a field value, calling the visitor function for each block found.
+ * Supports rich text, single block, and structured text field types.
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to visit
+ * @param visitor - Asynchronous function called for each block. Receives the block item and its path
+ * @returns Promise that resolves when all blocks have been visited
+ */
+export declare function nonRecursiveVisitBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, visitor: (item: BlockItemInARequest, path: TreePath) => Promise<void>): Promise<void>;
+/**
+ * Transform blocks in a field value by applying a mapping function to each block.
+ * Creates a new field value structure with transformed blocks while preserving the original structure.
+ * Supports rich text, single block, and structured text field types.
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to transform
+ * @param mapper - Synchronous function that transforms each block. Receives block item and path, returns new block
+ * @returns The new field value with transformed blocks
+ */
+export declare function nonRecursiveMapBlocksInNonLocalizedFieldValue(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, mapper: (item: BlockItemInARequest, path: TreePath) => BlockItemInARequest): unknown;
+/**
+ * Transform blocks in a field value by applying a mapping function to each block.
+ * Creates a new field value structure with transformed blocks while preserving the original structure.
+ * Supports rich text, single block, and structured text field types.
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to transform
+ * @param mapper - Asynchronous function that transforms each block. Receives block item and path, returns new block
+ * @returns Promise that resolves to the new field value with transformed blocks
+ */
+export declare function nonRecursiveMapBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, mapper: (item: BlockItemInARequest, path: TreePath) => Promise<BlockItemInARequest>): Promise<unknown>;
+/**
+ * Find all blocks that match the predicate function.
+ * Searches through all blocks in the non-localized field value and returns all matches.
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to search
+ * @param predicate - Synchronous function that tests each block. Should return true for matching blocks
+ * @returns Array of objects, each containing a matching block and its path
+ */
+export declare function nonRecursiveFindAllBlocksInNonLocalizedFieldValue(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean): Array<{
+    item: BlockItemInARequest;
+    path: TreePath;
+}>;
+/**
+ * Find all blocks that match the predicate function.
+ * Searches through all blocks in the non-localized field value and returns all matches.
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to search
+ * @param predicate - Asynchronous function that tests each block. Should return true for matching blocks
+ * @returns Promise that resolves to an array of objects, each containing a matching block and its path
+ */
+export declare function nonRecursiveFindAllBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => Promise<boolean>): Promise<Array<{
+    item: BlockItemInARequest;
+    path: TreePath;
+}>>;
+/**
+ * Filter blocks in a field value, removing those that don't match the predicate.
+ * Creates a new field value containing only blocks that pass the predicate test.
+ * Preserves the original field value structure and hierarchy.
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to filter
+ * @param predicate - Synchronous function that tests each block. Blocks returning false are removed
+ * @returns The new field value with filtered blocks
+ */
+export declare function nonRecursiveFilterBlocksInNonLocalizedFieldValue(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean): unknown;
+/**
+ * Filter blocks in a field value, removing those that don't match the predicate.
+ * Creates a new field value containing only blocks that pass the predicate test.
+ * Preserves the original field value structure and hierarchy.
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to filter
+ * @param predicate - Asynchronous function that tests each block. Blocks returning false are removed
+ * @returns Promise that resolves to the new field value with filtered blocks
+ */
+export declare function nonRecursiveFilterBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => Promise<boolean>): Promise<unknown>;
+/**
+ * Reduce all blocks in a field value to a single value by applying a reducer function.
+ * Processes each block in the non-localized field value and accumulates the results into a single value.
+ *
+ * @template R - The type of the accumulated result
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to reduce
+ * @param reducer - Synchronous function that processes each block and updates the accumulator
+ * @param initialValue - The initial value for the accumulator
+ * @returns The final accumulated value
+ */
+export declare function nonRecursiveReduceBlocksInNonLocalizedFieldValue<R>(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, reducer: (accumulator: R, item: BlockItemInARequest, path: TreePath) => R, initialValue: R): R;
+/**
+ * Reduce all blocks in a field value to a single value by applying a reducer function.
+ * Processes each block in the non-localized field value and accumulates the results into a single value.
+ *
+ * @template R - The type of the accumulated result
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to reduce
+ * @param reducer - Asynchronous function that processes each block and updates the accumulator
+ * @param initialValue - The initial value for the accumulator
+ * @returns Promise that resolves to the final accumulated value
+ */
+export declare function nonRecursiveReduceBlocksInNonLocalizedFieldValueAsync<R>(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, reducer: (accumulator: R, item: BlockItemInARequest, path: TreePath) => Promise<R>, initialValue: R): Promise<R>;
+/**
+ * Check if any block in the non-localized field value matches the predicate function.
+ * Returns true as soon as the first matching block is found (short-circuit evaluation).
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to test
+ * @param predicate - Synchronous function that tests each block. Should return true for matching blocks
+ * @returns True if any block matches, false otherwise
+ */
+export declare function nonRecursiveSomeBlocksInNonLocalizedFieldValue(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean): boolean;
+/**
+ * Check if any block in the non-localized field value matches the predicate function.
+ * Returns true as soon as the first matching block is found (short-circuit evaluation).
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to test
+ * @param predicate - Asynchronous function that tests each block. Should return true for matching blocks
+ * @returns Promise that resolves to true if any block matches, false otherwise
+ */
+export declare function nonRecursiveSomeBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => Promise<boolean>): Promise<boolean>;
+/**
+ * Check if every block in the non-localized field value matches the predicate function.
+ * Returns false as soon as the first non-matching block is found (short-circuit evaluation).
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to test
+ * @param predicate - Synchronous function that tests each block. Should return true for valid blocks
+ * @returns True if all blocks match, false otherwise
+ */
+export declare function nonRecursiveEveryBlockInNonLocalizedFieldValue(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean): boolean;
+/**
+ * Check if every block in the non-localized field value matches the predicate function.
+ * Returns false as soon as the first non-matching block is found (short-circuit evaluation).
+ *
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to test
+ * @param predicate - Asynchronous function that tests each block. Should return true for valid blocks
+ * @returns Promise that resolves to true if all blocks match, false otherwise
+ */
+export declare function nonRecursiveEveryBlockInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => Promise<boolean>): Promise<boolean>;

package/dist/{esm/utilities/fieldValue.d.ts → types/utilities/normalizedFieldValues.d.ts}

@@ -18,6 +18,7 @@ export type LocalizedFieldValue<T = unknown, L extends string = string> = Partia
  * @returns true if the field is localized, false otherwise
  */
 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.
  *
@@ -26,7 +27,7 @@ export declare function isLocalized(field: RawApiTypes.Field | ApiTypes.Field):
  *
  * This uniform structure allows the same processing logic to work with both field types.
  */
-export type FieldValueEntry<T = unknown, L extends string = string> = {
+export type NormalizedFieldValueEntry<T = unknown, L extends string = string> = {
     locale: L | undefined;
     value: T;
 };
@@ -40,11 +41,11 @@ export type FieldValueEntry<T = unknown, L extends string = string> = {
  * @param value - The field value to convert (either a localized object or direct value)
  * @returns Array of entries where each entry contains a locale (string for localized, undefined for non-localized) and the corresponding value
  */
-export declare function fieldValueToEntries<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>): FieldValueEntry<T, L>[];
+export declare function toNormalizedFieldValueEntries<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>): NormalizedFieldValueEntry<T, L>[];
 /**
  * Converts an array of possibly localized entries back into the appropriate field value format.
  *
- * This function is the inverse of `fieldValueToEntries`. It takes a uniform
+ * 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.
  *
@@ -52,7 +53,7 @@ export declare function fieldValueToEntries<T = unknown, L extends string = stri
  * @param entries - Array of entries to convert back to field value format
  * @returns Either a localized object (for localized fields) or the direct value (for non-localized fields)
  */
-export declare function entriesToFieldValue<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, entries: FieldValueEntry<T, L>[]): T | LocalizedFieldValue<T, L>;
+export declare function fromNormalizedFieldValueEntries<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, entries: NormalizedFieldValueEntry<T, L>[]): T | LocalizedFieldValue<T, L>;
 /**
  * Maps field values using a provided mapping function.
  * For localized fields, applies the mapping function to each locale value.
@@ -64,7 +65,7 @@ export declare function entriesToFieldValue<T = unknown, L extends string = stri
  * @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 mapFieldValue<TInput = unknown, TOutput = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: TInput | LocalizedFieldValue<TInput, L>, mapFn: (locale: L | undefined, localeValue: TInput) => TOutput): TOutput | LocalizedFieldValue<TOutput, L>;
+export declare function mapNormalizedFieldValues<TInput = unknown, TOutput = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: TInput | LocalizedFieldValue<TInput, L>, 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.
@@ -76,7 +77,7 @@ export declare function mapFieldValue<TInput = unknown, TOutput = unknown, L ext
  * @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 mapFieldValueAsync<TInput = unknown, TOutput = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: TInput | LocalizedFieldValue<TInput, L>, mapFn: (locale: L | undefined, localeValue: TInput) => Promise<TOutput>): Promise<TOutput | LocalizedFieldValue<TOutput, L>>;
+export declare function mapNormalizedFieldValuesAsync<TInput = unknown, TOutput = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: TInput | LocalizedFieldValue<TInput, L>, 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.
@@ -87,7 +88,7 @@ export declare function mapFieldValueAsync<TInput = unknown, TOutput = unknown,
  * @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 filterFieldValue<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, filterFn: (locale: L | undefined, localeValue: T) => boolean): T | LocalizedFieldValue<T, L> | undefined;
+export declare function filterNormalizedFieldValues<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, 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.
@@ -98,7 +99,7 @@ export declare function filterFieldValue<T = unknown, L extends string = string>
  * @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 filterFieldValueAsync<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, filterFn: (locale: L | undefined, localeValue: T) => Promise<boolean>): Promise<T | LocalizedFieldValue<T, L> | undefined>;
+export declare function filterNormalizedFieldValuesAsync<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, 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.
@@ -109,7 +110,7 @@ export declare function filterFieldValueAsync<T = unknown, L extends string = st
  * @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 someFieldValue<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, testFn: (locale: L | undefined, localeValue: T) => boolean): boolean;
+export declare function someNormalizedFieldValues<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, 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.
@@ -120,7 +121,7 @@ export declare function someFieldValue<T = unknown, L extends string = string>(f
  * @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 someFieldValueAsync<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, testFn: (locale: L | undefined, localeValue: T) => Promise<boolean>): Promise<boolean>;
+export declare function someNormalizedFieldValuesAsync<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, 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.
@@ -131,7 +132,7 @@ export declare function someFieldValueAsync<T = unknown, L extends string = stri
  * @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 everyFieldValue<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, testFn: (locale: L | undefined, localeValue: T) => boolean): boolean;
+export declare function everyNormalizedFieldValue<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, 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.
@@ -142,7 +143,7 @@ export declare function everyFieldValue<T = unknown, L extends string = string>(
  * @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 everyFieldValueAsync<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, testFn: (locale: L | undefined, localeValue: T) => Promise<boolean>): Promise<boolean>;
+export declare function everyNormalizedFieldValueAsync<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, 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.
@@ -152,7 +153,7 @@ export declare function everyFieldValueAsync<T = unknown, L extends string = str
  * @param value - The field value (either localized object or direct value)
  * @param visitFn - The function to call for each locale value or the direct value
  */
-export declare function visitFieldValue<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, visitFn: (locale: L | undefined, localeValue: T) => void): void;
+export declare function visitNormalizedFieldValues<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, 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.
@@ -162,4 +163,4 @@ export declare function visitFieldValue<T = unknown, L extends string = string>(
  * @param value - The field value (either localized object or direct value)
  * @param visitFn - The function to call for each locale value or the direct value
  */
-export declare function visitFieldValueAsync<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, visitFn: (locale: L | undefined, localeValue: T) => Promise<void>): Promise<void>;
+export declare function visitNormalizedFieldValuesAsync<T = unknown, L extends string = string>(field: RawApiTypes.Field | ApiTypes.Field, value: T | LocalizedFieldValue<T, L>, visitFn: (locale: L | undefined, localeValue: T) => Promise<void>): Promise<void>;

package/dist/types/utilities/recursiveBlocks.d.ts

@@ -1,18 +1,101 @@
 import { type BlockItemInARequest } from '../fieldTypes';
 import type * as ApiTypes from '../generated/ApiTypes';
-import type * as RawApiTypes from '../generated/RawApiTypes';
 import type { SchemaRepository } from './schemaRepository';
 /**
- * Path through a field value (ie. ['content', 0, 'attributes', 'title'])
+ * Path through a non-localized field value (ie. ['content', 0, 'attributes', 'title'])
  */
 export type TreePath = readonly (string | number)[];
-export declare function visitBlocksInFieldValues(schemaRepository: SchemaRepository, field: RawApiTypes.Field | ApiTypes.Field, value: unknown, visitor: (item: BlockItemInARequest, path: TreePath) => void | Promise<void>, path?: TreePath): Promise<void>;
-export declare function findAllBlocksInFieldValues(schemaRepository: SchemaRepository, field: RawApiTypes.Field | ApiTypes.Field, value: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<Array<{
+/**
+ * Recursively visit every block in a non-localized field value and all nested blocks within those blocks.
+ * This function traverses not only the direct blocks in the non-localized field value but also recursively
+ * visits blocks contained within the attributes of each block, creating a complete traversal
+ * of the entire block hierarchy.
+ *
+ * @param schemaRepository - Repository for accessing DatoCMS schema information to resolve block structures
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to visit
+ * @param visitor - Asynchronous function called for each block found, including nested blocks
+ * @returns Promise that resolves when all blocks and nested blocks have been visited
+ */
+export declare function visitBlocksInNonLocalizedFieldValue(schemaRepository: SchemaRepository, fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, visitor: (item: BlockItemInARequest, path: TreePath) => void | Promise<void>, path?: TreePath): Promise<void>;
+/**
+ * Recursively find all blocks that match the predicate function in a non-localized field value.
+ * Searches through all direct blocks and recursively through nested blocks within
+ * the attributes of each block, returning all matches found throughout the hierarchy.
+ *
+ * @param schemaRepository - Repository for accessing DatoCMS schema information to resolve block structures
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to search
+ * @param predicate - Asynchronous function that tests each block, including nested ones
+ * @returns Promise that resolves to an array of objects, each containing a matching block and its full path
+ */
+export declare function findAllBlocksInNonLocalizedFieldValue(schemaRepository: SchemaRepository, fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<Array<{
     item: BlockItemInARequest;
     path: TreePath;
 }>>;
-export declare function filterBlocksInFieldValues(schemaRepository: SchemaRepository, field: RawApiTypes.Field | ApiTypes.Field, value: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<unknown>;
-export declare function reduceBlocksInFieldValues<R>(schemaRepository: SchemaRepository, field: RawApiTypes.Field | ApiTypes.Field, value: unknown, reducer: (accumulator: R, item: BlockItemInARequest, path: TreePath) => R | Promise<R>, initialValue: R, path?: TreePath): Promise<R>;
-export declare function someBlocksInFieldValues(schemaRepository: SchemaRepository, field: RawApiTypes.Field | ApiTypes.Field, value: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<boolean>;
-export declare function everyBlockInFieldValues(schemaRepository: SchemaRepository, field: RawApiTypes.Field | ApiTypes.Field, value: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<boolean>;
-export declare function mapBlocksInFieldValues(schemaRepository: SchemaRepository, field: RawApiTypes.Field | ApiTypes.Field, value: unknown, mapper: (item: BlockItemInARequest, path: TreePath) => BlockItemInARequest | Promise<BlockItemInARequest>, path?: TreePath): Promise<unknown>;
+/**
+ * Recursively filter blocks in a non-localized field value, removing those that don't match the predicate.
+ * Creates a new non-localized field value structure containing only blocks that pass the predicate test,
+ * including recursive filtering of nested blocks within block attributes. The filtering
+ * preserves the original non-localized field value structure and hierarchy.
+ *
+ * @param schemaRepository - Repository for accessing DatoCMS schema information to resolve block structures
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to filter
+ * @param predicate - Asynchronous function that tests each block, including nested ones
+ * @returns Promise that resolves to the new non-localized field value with recursively filtered blocks
+ */
+export declare function filterBlocksInNonLocalizedFieldValue(schemaRepository: SchemaRepository, fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<unknown>;
+/**
+ * Recursively reduce all blocks in a non-localized field value to a single value by applying a reducer function.
+ * Processes each direct block and recursively processes nested blocks within block attributes,
+ * accumulating results from the entire block hierarchy into a single value.
+ *
+ * @template R - The type of the accumulated result
+ * @param schemaRepository - Repository for accessing DatoCMS schema information to resolve block structures
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to reduce
+ * @param reducer - Asynchronous function that processes each block and updates the accumulator
+ * @param initialNonLocalizedFieldValue - The initial value for the accumulator
+ * @returns Promise that resolves to the final accumulated value from all blocks in the hierarchy
+ */
+export declare function reduceBlocksInNonLocalizedFieldValue<R>(schemaRepository: SchemaRepository, fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, reducer: (accumulator: R, item: BlockItemInARequest, path: TreePath) => R | Promise<R>, initialValue: R, path?: TreePath): Promise<R>;
+/**
+ * Recursively check if any block in the non-localized field value matches the predicate function.
+ * Tests both direct blocks and recursively tests nested blocks within block attributes.
+ * Returns true as soon as the first matching block is found anywhere in the hierarchy
+ * (short-circuit evaluation).
+ *
+ * @param schemaRepository - Repository for accessing DatoCMS schema information to resolve block structures
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to test
+ * @param predicate - Asynchronous function that tests each block, including nested ones
+ * @returns Promise that resolves to true if any block in the hierarchy matches, false otherwise
+ */
+export declare function someBlocksInNonLocalizedFieldValue(schemaRepository: SchemaRepository, fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<boolean>;
+/**
+ * Recursively check if every block in the non-localized field value matches the predicate function.
+ * Tests both direct blocks and recursively tests nested blocks within block attributes.
+ * Returns false as soon as the first non-matching block is found anywhere in the hierarchy
+ * (short-circuit evaluation).
+ *
+ * @param schemaRepository - Repository for accessing DatoCMS schema information to resolve block structures
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to test
+ * @param predicate - Asynchronous function that tests each block, including nested ones
+ * @returns Promise that resolves to true if all blocks in the hierarchy match, false otherwise
+ */
+export declare function everyBlockInNonLocalizedFieldValue(schemaRepository: SchemaRepository, fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<boolean>;
+/**
+ * Recursively transform blocks in a non-localized field value by applying a mapping function to each block.
+ * Creates a new non-localized field value structure with transformed blocks while preserving the original
+ * structure. Applies the mapping function to both direct blocks and recursively to nested
+ * blocks within block attributes throughout the entire hierarchy.
+ *
+ * @param schemaRepository - Repository for accessing DatoCMS schema information to resolve block structures
+ * @param fieldType - The type of DatoCMS field definition that determines how the value is processed
+ * @param nonLocalizedFieldValue - The non-localized field value containing blocks to transform
+ * @param mapper - Asynchronous function that transforms each block, including nested ones
+ * @returns Promise that resolves to the new non-localized field value with recursively transformed blocks
+ */
+export declare function mapBlocksInNonLocalizedFieldValue(schemaRepository: SchemaRepository, fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, mapper: (item: BlockItemInARequest, path: TreePath) => BlockItemInARequest | Promise<BlockItemInARequest>, path?: TreePath): Promise<unknown>;

package/dist/types/utilities/schemaRepository.d.ts

@@ -41,7 +41,7 @@ interface GenericClient {
  * - **Caching schema entities**: Automatically caches item types, fields, fieldsets,
  *   and plugins after the first API request, returning cached results on subsequent calls
  * - **Complex traversal operations**: Essential when using utilities like
- *   `mapBlocksInFieldValues()` that need to repeatedly lookup block models and fields
+ *   `mapBlocksInNonLocalizedFieldValue()` that need to repeatedly lookup block models and fields
  *   while traversing nested content structures
  * - **Bulk operations**: Ideal for scripts that process multiple records of different
  *   types and need efficient access to schema information
@@ -73,7 +73,7 @@ interface GenericClient {
  * const sameBlogPost = await schemaRepository.getItemTypeByApiKey('blog_post');
  *
  * // Pass the repository to utilities that need schema information
- * await mapBlocksInFieldValues(schemaRepository, record, (block) => {
+ * await mapBlocksInNonLocalizedFieldValue(schemaRepository, record, (block) => {
  *   // The utility will use the cached schema data internally
  * });
  * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datocms/cma-client",
-  "version": "5.1.9",
+  "version": "5.1.11",
   "description": "JS client for DatoCMS REST Content Management API",
   "keywords": [
     "datocms",
@@ -38,12 +38,12 @@
   },
   "dependencies": {
     "@datocms/rest-client-utils": "^5.1.6",
-    "datocms-structured-text-utils": "^5.1.2",
+    "datocms-structured-text-utils": "^5.1.4",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@datocms/dashboard-client": "^5.1.7",
+    "@datocms/dashboard-client": "^5.1.10",
     "@types/uuid": "^9.0.7"
   },
-  "gitHead": "d0c86d5cbb6df9b9260ebe379bcbcc44f6f43706"
+  "gitHead": "e809594f4faa92ee8cb1943de52278f9030b09d7"
 }

package/src/fieldTypes/boolean.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { BooleanEditorConfiguration } from './appearance/boolean';
 import type { BooleanRadioGroupEditorConfiguration } from './appearance/boolean_radio_group';
 
@@ -14,8 +17,7 @@ export function isLocalizedBooleanFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<BooleanFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isBooleanFieldValue)
   );
 }

package/src/fieldTypes/color.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { ColorPickerEditorConfiguration } from './appearance/color_picker';
 import type { RequiredValidator } from './validators/required';
 
@@ -25,8 +28,7 @@ export function isLocalizedColorFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<ColorFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isColorFieldValue)
   );
 }

package/src/fieldTypes/date.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { DatePickerEditorConfiguration } from './appearance/date_picker';
 import type { DateRangeValidator } from './validators/date_range';
 import type { RequiredValidator } from './validators/required';
@@ -14,9 +17,7 @@ export function isLocalizedDateFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<DateFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
-    Object.values(value).every(isDateFieldValue)
+    isLocalizedFieldValue(value) && Object.values(value).every(isDateFieldValue)
   );
 }
 

package/src/fieldTypes/date_time.ts

@@ -1,4 +1,7 @@
-import type { LocalizedFieldValue } from '../utilities/fieldValue';
+import {
+  type LocalizedFieldValue,
+  isLocalizedFieldValue,
+} from '../utilities/normalizedFieldValues';
 import type { DateTimePickerEditorConfiguration } from './appearance/date_time_picker';
 import type { DateTimeRangeValidator } from './validators/date_time_range';
 import type { RequiredValidator } from './validators/required';
@@ -19,8 +22,7 @@ export function isLocalizedDateTimeFieldValue(
   value: unknown,
 ): value is LocalizedFieldValue<DateTimeFieldValue> {
   return (
-    typeof value === 'object' &&
-    value !== null &&
+    isLocalizedFieldValue(value) &&
     Object.values(value).every(isDateTimeFieldValue)
   );
 }