@datocms/cma-client 5.1.11 → 5.1.13

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

@@ -22,17 +22,8 @@
  * 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 { BlockInRequest } 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.
@@ -42,7 +33,7 @@ export declare function nonRecursiveVisitBlocksInNonLocalizedFieldValue(fieldTyp
  * @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>;
+export declare function nonRecursiveVisitBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, visitor: (item: BlockInRequest, 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.
@@ -53,7 +44,7 @@ export declare function nonRecursiveVisitBlocksInNonLocalizedFieldValueAsync(fie
  * @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;
+export declare function nonRecursiveMapBlocksInNonLocalizedFieldValue(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, mapper: (item: BlockInRequest, path: TreePath) => BlockInRequest): 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.
@@ -64,20 +55,7 @@ export declare function nonRecursiveMapBlocksInNonLocalizedFieldValue(fieldType:
  * @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;
-}>;
+export declare function nonRecursiveMapBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, mapper: (item: BlockInRequest, path: TreePath) => Promise<BlockInRequest>): Promise<unknown>;
 /**
  * Find all blocks that match the predicate function.
  * Searches through all blocks in the non-localized field value and returns all matches.
@@ -87,21 +65,10 @@ export declare function nonRecursiveFindAllBlocksInNonLocalizedFieldValue(fieldT
  * @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;
+export declare function nonRecursiveFindAllBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockInRequest, path: TreePath) => Promise<boolean>): Promise<Array<{
+    item: BlockInRequest;
     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.
@@ -112,19 +79,7 @@ export declare function nonRecursiveFilterBlocksInNonLocalizedFieldValue(fieldTy
  * @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;
+export declare function nonRecursiveFilterBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockInRequest, 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.
@@ -136,17 +91,7 @@ export declare function nonRecursiveReduceBlocksInNonLocalizedFieldValue<R>(fiel
  * @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;
+export declare function nonRecursiveReduceBlocksInNonLocalizedFieldValueAsync<R>(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, reducer: (accumulator: R, item: BlockInRequest, 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).
@@ -156,17 +101,7 @@ export declare function nonRecursiveSomeBlocksInNonLocalizedFieldValue(fieldType
  * @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;
+export declare function nonRecursiveSomeBlocksInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockInRequest, 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).
@@ -176,4 +111,4 @@ export declare function nonRecursiveEveryBlockInNonLocalizedFieldValue(fieldType
  * @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>;
+export declare function nonRecursiveEveryBlockInNonLocalizedFieldValueAsync(fieldType: ApiTypes.Field['field_type'], nonLocalizedFieldValue: unknown, predicate: (item: BlockInRequest, path: TreePath) => Promise<boolean>): Promise<boolean>;

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

@@ -1,36 +1,47 @@
-import { type BlockItemInARequest } from '../fieldTypes';
+import { type BlockInRequest, type RichTextFieldValue, type RichTextFieldValueInNestedResponse, type RichTextFieldValueInRequest, type SingleBlockFieldValue, type SingleBlockFieldValueInNestedResponse, type SingleBlockFieldValueInRequest, type StructuredTextFieldValue, type StructuredTextFieldValueInNestedResponse, type StructuredTextFieldValueInRequest } from '../fieldTypes';
 import type * as ApiTypes from '../generated/ApiTypes';
+import type { ExtractNestedBlocksFromFieldValue } from './itemDefinition';
 import type { SchemaRepository } from './schemaRepository';
+type RecognizableFieldValue = RichTextFieldValueInNestedResponse | SingleBlockFieldValueInNestedResponse | StructuredTextFieldValueInNestedResponse | RichTextFieldValueInRequest | SingleBlockFieldValueInRequest | StructuredTextFieldValueInRequest | RichTextFieldValue | SingleBlockFieldValue | StructuredTextFieldValue;
 /**
  * Path through a non-localized field value (ie. ['content', 0, 'attributes', 'title'])
  */
 export type TreePath = readonly (string | number)[];
+/**
+ * Traversal direction for recursive operations
+ */
+export type TraversalDirection = 'top-down' | 'bottom-up';
 /**
  * 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 fieldType - The type field (determines how the value is processed)
+ * @param schemaRepository - Repository for accessing DatoCMS schema information (to resolve block structures)
  * @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>;
+export declare function visitBlocksInNonLocalizedFieldValue<T extends RecognizableFieldValue>(nonLocalizedFieldValue: T, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, visitor: (item: ExtractNestedBlocksFromFieldValue<T>, path: TreePath) => void | Promise<void>, path?: TreePath): Promise<void>;
+export declare function visitBlocksInNonLocalizedFieldValue(nonLocalizedFieldValue: unknown, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, visitor: (item: BlockInRequest, 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 fieldType - The type field (determines how the value is processed)
+ * @param schemaRepository - Repository for accessing DatoCMS schema information (to resolve block structures)
  * @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;
+export declare function findAllBlocksInNonLocalizedFieldValue<T extends RecognizableFieldValue>(nonLocalizedFieldValue: T, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, predicate: (item: ExtractNestedBlocksFromFieldValue<T>, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<Array<{
+    item: ExtractNestedBlocksFromFieldValue<T>;
+    path: TreePath;
+}>>;
+export declare function findAllBlocksInNonLocalizedFieldValue(nonLocalizedFieldValue: unknown, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<Array<{
+    item: BlockInRequest;
     path: TreePath;
 }>>;
 /**
@@ -39,63 +50,82 @@ export declare function findAllBlocksInNonLocalizedFieldValue(schemaRepository:
  * 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 fieldType - The type field (determines how the value is processed)
+ * @param schemaRepository - Repository for accessing DatoCMS schema information (to resolve block structures)
  * @param predicate - Asynchronous function that tests each block, including nested ones
+ * @param options - Optional configuration object
+ * @param options.traversalDirection - Direction of traversal: 'top-down' (default) applies predicate before processing children, 'bottom-up' processes children first
  * @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>;
+export declare function filterBlocksInNonLocalizedFieldValue<T extends RecognizableFieldValue>(nonLocalizedFieldValue: T, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, predicate: (item: ExtractNestedBlocksFromFieldValue<T>, path: TreePath) => boolean | Promise<boolean>, options?: {
+    traversalDirection?: TraversalDirection;
+}, path?: TreePath): Promise<T>;
+export declare function filterBlocksInNonLocalizedFieldValue(nonLocalizedFieldValue: unknown, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>, options?: {
+    traversalDirection?: TraversalDirection;
+}, 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 fieldType - The type field (determines how the value is processed)
+ * @param schemaRepository - Repository for accessing DatoCMS schema information (to resolve block structures)
  * @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>;
+export declare function reduceBlocksInNonLocalizedFieldValue<T, R>(nonLocalizedFieldValue: T, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, reducer: (accumulator: R, item: ExtractNestedBlocksFromFieldValue<T>, path: TreePath) => R | Promise<R>, initialValue: R, path?: TreePath): Promise<R>;
+export declare function reduceBlocksInNonLocalizedFieldValue<R>(nonLocalizedFieldValue: unknown, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, reducer: (accumulator: R, item: BlockInRequest, 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 fieldType - The type field (determines how the value is processed)
+ * @param schemaRepository - Repository for accessing DatoCMS schema information (to resolve block structures)
  * @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>;
+export declare function someBlocksInNonLocalizedFieldValue<T extends RecognizableFieldValue>(nonLocalizedFieldValue: T, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, predicate: (item: ExtractNestedBlocksFromFieldValue<T>, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<boolean>;
+export declare function someBlocksInNonLocalizedFieldValue(nonLocalizedFieldValue: unknown, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, predicate: (item: BlockInRequest, 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 fieldType - The type field (determines how the value is processed)
+ * @param schemaRepository - Repository for accessing DatoCMS schema information (to resolve block structures)
  * @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>;
+export declare function everyBlockInNonLocalizedFieldValue<T extends RecognizableFieldValue>(nonLocalizedFieldValue: T, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, predicate: (item: ExtractNestedBlocksFromFieldValue<T>, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<boolean>;
+export declare function everyBlockInNonLocalizedFieldValue(nonLocalizedFieldValue: unknown, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>, path?: TreePath): Promise<boolean>;
+type FieldValueInRequest<T> = T extends RichTextFieldValueInNestedResponse<infer D> ? RichTextFieldValueInRequest<D> : T extends SingleBlockFieldValueInNestedResponse<infer D> ? SingleBlockFieldValueInRequest<D> : T extends StructuredTextFieldValueInNestedResponse<infer DB, infer DI> ? StructuredTextFieldValueInRequest<DB, DI> : T extends StructuredTextFieldValueInNestedResponse<infer DB> ? StructuredTextFieldValueInRequest<DB> : T;
 /**
  * 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 fieldType - The type field (determines how the value is processed)
+ * @param schemaRepository - Repository for accessing DatoCMS schema information (to resolve block structures)
  * @param mapper - Asynchronous function that transforms each block, including nested ones
+ * @param options - Optional configuration object
+ * @param options.traversalDirection - Direction of traversal: 'top-down' (default) applies mapper before processing children, 'bottom-up' processes children first
  * @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>;
+export declare function mapBlocksInNonLocalizedFieldValue<T extends RecognizableFieldValue>(nonLocalizedFieldValue: T, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, mapper: (item: ExtractNestedBlocksFromFieldValue<T>, path: TreePath) => BlockInRequest | Promise<BlockInRequest>, options?: {
+    traversalDirection?: TraversalDirection;
+}, path?: TreePath): Promise<FieldValueInRequest<T>>;
+export declare function mapBlocksInNonLocalizedFieldValue(nonLocalizedFieldValue: unknown, fieldType: ApiTypes.Field['field_type'], schemaRepository: SchemaRepository, mapper: (item: BlockInRequest, path: TreePath) => BlockInRequest | Promise<BlockInRequest>, options?: {
+    traversalDirection?: TraversalDirection;
+}, path?: TreePath): Promise<unknown>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datocms/cma-client",
-  "version": "5.1.11",
+  "version": "5.1.13",
   "description": "JS client for DatoCMS REST Content Management API",
   "keywords": [
     "datocms",
@@ -37,13 +37,13 @@
     "url": "https://github.com/datocms/js-rest-api-clients/issues"
   },
   "dependencies": {
-    "@datocms/rest-client-utils": "^5.1.6",
+    "@datocms/rest-client-utils": "^5.1.13",
     "datocms-structured-text-utils": "^5.1.4",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@datocms/dashboard-client": "^5.1.10",
+    "@datocms/dashboard-client": "^5.1.13",
     "@types/uuid": "^9.0.7"
   },
-  "gitHead": "e809594f4faa92ee8cb1943de52278f9030b09d7"
+  "gitHead": "966b5835bf69f9e87b34f2075a8596c9208e07c0"
 }

package/src/fieldTypes/file.ts

@@ -66,7 +66,7 @@ export type FileFieldValue = {
 /**
  * File field value for API requests - metadata fields are optional
  */
-export type FileFieldValueAsRequest = {
+export type FileFieldValueInRequest = {
   upload_id: string;
   alt?: string | null;
   title?: string | null;
@@ -103,9 +103,9 @@ export function isFileFieldValue(value: unknown): value is FileFieldValue {
  * Type guard for File field values in API request format.
  * Allows metadata fields to be optional or omitted.
  */
-export function isFileFieldValueAsRequest(
+export function isFileFieldValueInRequest(
   value: unknown,
-): value is FileFieldValueAsRequest {
+): value is FileFieldValueInRequest {
   if (value === null) return true;
   return typeof value === 'object' && value !== null && 'upload_id' in value;
 }
@@ -118,12 +118,12 @@ export function isLocalizedFileFieldValue(
   );
 }
 
-export function isLocalizedFileFieldValueAsRequest(
+export function isLocalizedFileFieldValueInRequest(
   value: unknown,
-): value is LocalizedFieldValue<FileFieldValueAsRequest> {
+): value is LocalizedFieldValue<FileFieldValueInRequest> {
   return (
     isLocalizedFieldValue(value) &&
-    Object.values(value).every(isFileFieldValueAsRequest)
+    Object.values(value).every(isFileFieldValueInRequest)
   );
 }
 

package/src/fieldTypes/gallery.ts

@@ -5,9 +5,9 @@ import {
 import type { GalleryEditorConfiguration } from './appearance/gallery';
 import {
   type FileFieldValue,
-  type FileFieldValueAsRequest,
+  type FileFieldValueInRequest,
   isFileFieldValue,
-  isFileFieldValueAsRequest,
+  isFileFieldValueInRequest,
 } from './file';
 import type { ExtensionValidator } from './validators/extension';
 import type { FileSizeValidator } from './validators/file_size';
@@ -25,7 +25,7 @@ import type { SizeValidator } from './validators/size';
  * Individual gallery item types - extracted from File field types
  */
 export type GalleryItem = NonNullable<FileFieldValue>;
-export type GalleryItemAsRequest = NonNullable<FileFieldValueAsRequest>;
+export type GalleryItemInRequest = NonNullable<FileFieldValueInRequest>;
 
 /**
  * Gallery field value - response format with all metadata fields present
@@ -35,7 +35,7 @@ export type GalleryFieldValue = Array<GalleryItem>;
 /**
  * Gallery field value for API requests - metadata fields are optional
  */
-export type GalleryFieldValueAsRequest = Array<GalleryItemAsRequest>;
+export type GalleryFieldValueInRequest = Array<GalleryItemInRequest>;
 
 /**
  * Type guard for Gallery field values - validates each item using File field validation
@@ -49,10 +49,10 @@ export function isGalleryFieldValue(
 /**
  * Type guard for Gallery field values in API request format
  */
-export function isGalleryFieldValueAsRequest(
+export function isGalleryFieldValueInRequest(
   value: unknown,
-): value is GalleryFieldValueAsRequest {
-  return Array.isArray(value) && value.every(isFileFieldValueAsRequest);
+): value is GalleryFieldValueInRequest {
+  return Array.isArray(value) && value.every(isFileFieldValueInRequest);
 }
 
 export function isLocalizedGalleryFieldValue(
@@ -64,12 +64,12 @@ export function isLocalizedGalleryFieldValue(
   );
 }
 
-export function isLocalizedGalleryFieldValueAsRequest(
+export function isLocalizedGalleryFieldValueInRequest(
   value: unknown,
-): value is LocalizedFieldValue<GalleryFieldValueAsRequest> {
+): value is LocalizedFieldValue<GalleryFieldValueInRequest> {
   return (
     isLocalizedFieldValue(value) &&
-    Object.values(value).every(isGalleryFieldValueAsRequest)
+    Object.values(value).every(isGalleryFieldValueInRequest)
   );
 }
 

package/src/fieldTypes/rich_text.ts

@@ -1,12 +1,13 @@
-import type * as RawApiTypes from '../generated/RawApiTypes';
-import type { ItemDefinition } from '../utilities/itemDefinition';
+import { isValidId } from '../utilities/id';
+import type { ItemTypeDefinition } from '../utilities/itemDefinition';
 import {
   type LocalizedFieldValue,
   isLocalizedFieldValue,
 } from '../utilities/normalizedFieldValues';
 import type { RichTextEditorConfiguration } from './appearance/rich_text';
 import {
-  type BlockItemInARequest,
+  type BlockInNestedResponse,
+  type BlockInRequest,
   isItemId,
   isItemWithOptionalIdAndMeta,
   isItemWithOptionalMeta,
@@ -64,9 +65,9 @@ export type RichTextFieldValue = string[];
  * - RawApiTypes.Item: Full block object with ID (for updates)
  * - Omit<RawApiTypes.Item, 'id'>: Block object without ID (for creation)
  */
-export type RichTextFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
-> = BlockItemInARequest<D>[] | null;
+export type RichTextFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = BlockInRequest<D>[] | null;
 
 /**
  * =============================================================================
@@ -81,9 +82,9 @@ export type RichTextFieldValueAsRequest<
 /**
  * Modular Content field value with nested blocks - array of fully populated block objects
  */
-export type RichTextFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
-> = RawApiTypes.Item<D>[];
+export type RichTextFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+> = BlockInNestedResponse<D>[];
 
 /**
  * =============================================================================
@@ -99,7 +100,8 @@ export function isRichTextFieldValue(
   value: unknown,
 ): value is RichTextFieldValue {
   return (
-    Array.isArray(value) && value.every((block) => typeof block === 'string')
+    Array.isArray(value) &&
+    value.every((block) => typeof block === 'string' && isValidId(block))
   );
 }
 
@@ -116,9 +118,9 @@ export function isLocalizedRichTextFieldValue(
  * Type guard for Modular Content field values in API request format.
  * Allows blocks as string IDs, full objects with IDs, or objects without IDs.
  */
-export function isRichTextFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
->(value: unknown): value is RichTextFieldValueAsRequest<D> {
+export function isRichTextFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+>(value: unknown): value is RichTextFieldValueInRequest<D> {
   if (value === null) return true;
 
   if (!Array.isArray(value)) return false;
@@ -132,14 +134,14 @@ export function isRichTextFieldValueAsRequest<
   });
 }
 
-export function isLocalizedRichTextFieldValueAsRequest<
-  D extends ItemDefinition = ItemDefinition,
+export function isLocalizedRichTextFieldValueInRequest<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is LocalizedFieldValue<RichTextFieldValueAsRequest<D>> {
+): value is LocalizedFieldValue<RichTextFieldValueInRequest<D>> {
   return (
     isLocalizedFieldValue(value) &&
-    Object.values(value).every(isRichTextFieldValueAsRequest)
+    Object.values(value).every(isRichTextFieldValueInRequest)
   );
 }
 
@@ -147,9 +149,9 @@ export function isLocalizedRichTextFieldValueAsRequest<
  * Type guard for Modular Content field values with nested blocks (?nested=true format).
  * Ensures all blocks are full RawApiTypes.Item objects with complete data.
  */
-export function isRichTextFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
->(value: unknown): value is RichTextFieldValueWithNestedBlocks<D> {
+export function isRichTextFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
+>(value: unknown): value is RichTextFieldValueInNestedResponse<D> {
   if (!Array.isArray(value)) return false;
 
   return value.every((block) => {
@@ -158,14 +160,14 @@ export function isRichTextFieldValueWithNestedBlocks<
   });
 }
 
-export function isLocalizedRichTextFieldValueWithNestedBlocks<
-  D extends ItemDefinition = ItemDefinition,
+export function isLocalizedRichTextFieldValueInNestedResponse<
+  D extends ItemTypeDefinition = ItemTypeDefinition,
 >(
   value: unknown,
-): value is LocalizedFieldValue<RichTextFieldValueWithNestedBlocks<D>> {
+): value is LocalizedFieldValue<RichTextFieldValueInNestedResponse<D>> {
   return (
     isLocalizedFieldValue(value) &&
-    Object.values(value).every(isRichTextFieldValueWithNestedBlocks)
+    Object.values(value).every(isRichTextFieldValueInNestedResponse)
   );
 }