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

JS client for DatoCMS REST Content Management API

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 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<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 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<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;
}>>;
/**
 * 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 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<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 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<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 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<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 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<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 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<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 {};