@datocms/cma-client 5.1.9 → 5.1.11

package/dist/esm/utilities/itemDefinition.d.ts

@@ -1,5 +1,5 @@
-import type { BooleanFieldValue, ColorFieldValue, DateFieldValue, DateTimeFieldValue, FileFieldValue, FloatFieldValue, GalleryFieldValue, IntegerFieldValue, JsonFieldValue, LatLonFieldValue, LinkFieldValue, LinksFieldValue, RichTextFieldValue, RichTextFieldValueAsRequest, RichTextFieldValueWithNestedBlocks, SeoFieldValue, SingleBlockFieldValue, SingleBlockFieldValueAsRequest, SingleBlockFieldValueWithNestedBlocks, SlugFieldValue, StringFieldValue, StructuredTextFieldValue, StructuredTextFieldValueAsRequest, StructuredTextFieldValueWithNestedBlocks, TextFieldValue, VideoFieldValue } from '../fieldTypes';
-import type { LocalizedFieldValue } from './fieldValue';
+import type { BooleanFieldValue, ColorFieldValue, DateFieldValue, DateTimeFieldValue, FileFieldValue, FileFieldValueAsRequest, FloatFieldValue, GalleryFieldValue, GalleryFieldValueAsRequest, IntegerFieldValue, JsonFieldValue, LatLonFieldValue, LinkFieldValue, LinksFieldValue, RichTextFieldValue, RichTextFieldValueAsRequest, RichTextFieldValueWithNestedBlocks, SeoFieldValue, SingleBlockFieldValue, SingleBlockFieldValueAsRequest, SingleBlockFieldValueWithNestedBlocks, SlugFieldValue, StringFieldValue, StructuredTextFieldValue, StructuredTextFieldValueAsRequest, StructuredTextFieldValueWithNestedBlocks, TextFieldValue, VideoFieldValue } from '../fieldTypes';
+import type { LocalizedFieldValue } from './normalizedFieldValues';
 /** Base field definition */
 type BaseFieldDefinition<Type extends string> = {
     type: Type;
@@ -32,7 +32,7 @@ export type ItemDefinition<ItemTypeId extends string = string, FieldValues exten
     itemTypeId: ItemTypeId;
     fields: FieldValues;
 };
-/** Standard field values */
+/** Standard field values (response format) */
 type FieldTypeToValue = {
     boolean: BooleanFieldValue;
     color: ColorFieldValue;
@@ -56,6 +56,30 @@ type FieldTypeToValue = {
     video: VideoFieldValue;
     unknown: unknown;
 };
+/** Request field values (request format with optional metadata) */
+type FieldTypeToValueAsRequest = {
+    boolean: BooleanFieldValue;
+    color: ColorFieldValue;
+    date: DateFieldValue;
+    date_time: DateTimeFieldValue;
+    file: FileFieldValueAsRequest;
+    float: FloatFieldValue;
+    gallery: GalleryFieldValueAsRequest;
+    integer: IntegerFieldValue;
+    json: JsonFieldValue;
+    lat_lon: LatLonFieldValue;
+    link: LinkFieldValue;
+    links: LinksFieldValue;
+    rich_text: RichTextFieldValueAsRequest;
+    seo: SeoFieldValue;
+    single_block: SingleBlockFieldValueAsRequest;
+    slug: SlugFieldValue;
+    string: StringFieldValue;
+    structured_text: StructuredTextFieldValueAsRequest;
+    text: TextFieldValue;
+    video: VideoFieldValue;
+    unknown: unknown;
+};
 /** Localized wrapper */
 type LocalizeIfNeeded<T extends FieldDefinition, Value, Locales extends string> = T extends {
     localized: true;
@@ -63,24 +87,24 @@ type LocalizeIfNeeded<T extends FieldDefinition, Value, Locales extends string>
 /** Standard mapping */
 type FieldDefinitionToFieldValue<T extends FieldDefinition, Locales extends string> = LocalizeIfNeeded<T, FieldTypeToValue[T['type']], Locales>;
 /** AsRequest mapping (block fields become generic over allowed blocks) */
-type FieldDefinitionToFieldValueAsRequest<T extends FieldDefinition, Locales extends string> = T extends RichTextFieldDefinition<infer B> ? LocalizeIfNeeded<T, RichTextFieldValueAsRequest<ItemTypeDefinitionToItemDefinitionAsRequest<B>>, Locales> : T extends SingleBlockFieldDefinition<infer B> ? LocalizeIfNeeded<T, SingleBlockFieldValueAsRequest<ItemTypeDefinitionToItemDefinitionAsRequest<B>>, Locales> : T extends StructuredTextFieldDefinition<infer B, infer I> ? LocalizeIfNeeded<T, StructuredTextFieldValueAsRequest<T extends {
+type FieldDefinitionToFieldValueAsRequest<T extends FieldDefinition, Locales extends string> = T extends RichTextFieldDefinition<infer B> ? LocalizeIfNeeded<T, RichTextFieldValueAsRequest<ToItemDefinitionAsRequest<B>>, Locales> : T extends SingleBlockFieldDefinition<infer B> ? LocalizeIfNeeded<T, SingleBlockFieldValueAsRequest<ToItemDefinitionAsRequest<B>>, Locales> : T extends StructuredTextFieldDefinition<infer B, infer I> ? LocalizeIfNeeded<T, StructuredTextFieldValueAsRequest<T extends {
     blocks: any;
-} ? ItemTypeDefinitionToItemDefinitionAsRequest<B> : never, T extends {
+} ? ToItemDefinitionAsRequest<B> : never, T extends {
     inline_blocks: any;
-} ? ItemTypeDefinitionToItemDefinitionAsRequest<I> : never>, Locales> : LocalizeIfNeeded<T, FieldTypeToValue[T['type']], Locales>;
-type FieldDefinitionToFieldValueWithNestedBlocks<T extends FieldDefinition, Locales extends string> = T extends RichTextFieldDefinition<infer B> ? LocalizeIfNeeded<T, RichTextFieldValueWithNestedBlocks<ItemTypeDefinitionToItemDefinitionWithNestedBlocks<B>>, Locales> : T extends SingleBlockFieldDefinition<infer B> ? LocalizeIfNeeded<T, SingleBlockFieldValueWithNestedBlocks<ItemTypeDefinitionToItemDefinitionWithNestedBlocks<B>>, Locales> : T extends StructuredTextFieldDefinition<infer B, infer I> ? LocalizeIfNeeded<T, StructuredTextFieldValueWithNestedBlocks<T extends {
+} ? ToItemDefinitionAsRequest<I> : never>, Locales> : LocalizeIfNeeded<T, FieldTypeToValueAsRequest[T['type']], Locales>;
+type FieldDefinitionToFieldValueWithNestedBlocks<T extends FieldDefinition, Locales extends string> = T extends RichTextFieldDefinition<infer B> ? LocalizeIfNeeded<T, RichTextFieldValueWithNestedBlocks<ToItemDefinitionWithNestedBlocks<B>>, Locales> : T extends SingleBlockFieldDefinition<infer B> ? LocalizeIfNeeded<T, SingleBlockFieldValueWithNestedBlocks<ToItemDefinitionWithNestedBlocks<B>>, Locales> : T extends StructuredTextFieldDefinition<infer B, infer I> ? LocalizeIfNeeded<T, StructuredTextFieldValueWithNestedBlocks<T extends {
     blocks: any;
-} ? ItemTypeDefinitionToItemDefinitionWithNestedBlocks<B> : never, T extends {
+} ? ToItemDefinitionWithNestedBlocks<B> : never, T extends {
     inline_blocks: any;
-} ? ItemTypeDefinitionToItemDefinitionWithNestedBlocks<I> : never>, Locales> : LocalizeIfNeeded<T, FieldTypeToValue[T['type']], Locales>;
+} ? ToItemDefinitionWithNestedBlocks<I> : never>, Locales> : LocalizeIfNeeded<T, FieldTypeToValue[T['type']], Locales>;
 /** Transformers */
-export type ItemTypeDefinitionToItemDefinition<T extends ItemTypeDefinition<any, any, any>> = T extends ItemTypeDefinition<infer Settings, infer ItemTypeId, infer Fields> ? keyof Fields extends never ? ItemDefinition<ItemTypeId> : ItemDefinition<ItemTypeId, {
+export type ToItemDefinition<T extends ItemTypeDefinition<any, any, any>> = T extends ItemTypeDefinition<infer Settings, infer ItemTypeId, infer Fields> ? keyof Fields extends never ? ItemDefinition<ItemTypeId> : ItemDefinition<ItemTypeId, {
     [K in keyof Fields]: Fields[K] extends FieldDefinition ? FieldDefinitionToFieldValue<Fields[K], Settings['locales']> : never;
 }> : never;
-export type ItemTypeDefinitionToItemDefinitionAsRequest<T extends ItemTypeDefinition<any, any, any>> = T extends ItemTypeDefinition<infer Settings, infer ItemTypeId, infer Fields> ? keyof Fields extends never ? ItemDefinition<ItemTypeId> : ItemDefinition<ItemTypeId, Partial<{
+export type ToItemDefinitionAsRequest<T extends ItemTypeDefinition<any, any, any>> = T extends ItemTypeDefinition<infer Settings, infer ItemTypeId, infer Fields> ? keyof Fields extends never ? ItemDefinition<ItemTypeId> : ItemDefinition<ItemTypeId, Partial<{
     [K in keyof Fields]: Fields[K] extends FieldDefinition ? FieldDefinitionToFieldValueAsRequest<Fields[K], Settings['locales']> : never;
 }>> : never;
-export type ItemTypeDefinitionToItemDefinitionWithNestedBlocks<T extends ItemTypeDefinition<any, any, any>> = T extends ItemTypeDefinition<infer Settings, infer ItemTypeId, infer Fields> ? keyof Fields extends never ? ItemDefinition<ItemTypeId> : ItemDefinition<ItemTypeId, {
+export type ToItemDefinitionWithNestedBlocks<T extends ItemTypeDefinition<any, any, any>> = T extends ItemTypeDefinition<infer Settings, infer ItemTypeId, infer Fields> ? keyof Fields extends never ? ItemDefinition<ItemTypeId> : ItemDefinition<ItemTypeId, {
     [K in keyof Fields]: Fields[K] extends FieldDefinition ? FieldDefinitionToFieldValueWithNestedBlocks<Fields[K], Settings['locales']> : never;
 }> : never;
 export type UnknownField = Record<string, unknown>;

package/dist/esm/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>;