@datocms/cma-client 5.1.10 → 5.1.12

package/src/utilities/nonRecursiveBlocks.ts

@@ -0,0 +1,406 @@
+/**
+ * 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,
+  collectNodesAsync,
+  filterNodesAsync,
+  mapNodes,
+  mapNodesAsync,
+} from 'datocms-structured-text-utils';
+import type {
+  BlockInRequest,
+  RichTextFieldValue,
+  RichTextFieldValueInNestedResponse,
+  RichTextFieldValueInRequest,
+  SingleBlockFieldValue,
+  SingleBlockFieldValueInNestedResponse,
+  SingleBlockFieldValueInRequest,
+  StructuredTextFieldValue,
+  StructuredTextFieldValueInNestedResponse,
+  StructuredTextFieldValueInRequest,
+} from '../fieldTypes';
+import type * as ApiTypes from '../generated/ApiTypes';
+
+type PossibleRichTextValue =
+  | RichTextFieldValue
+  | RichTextFieldValueInRequest
+  | RichTextFieldValueInNestedResponse;
+type PossibleSingleBlockValue =
+  | SingleBlockFieldValue
+  | SingleBlockFieldValueInRequest
+  | SingleBlockFieldValueInNestedResponse;
+type PossibleStructuredTextValue =
+  | StructuredTextFieldValue
+  | StructuredTextFieldValueInRequest
+  | StructuredTextFieldValueInNestedResponse;
+
+async function* iterateBlocksAsync(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+): AsyncGenerator<{ item: BlockInRequest; path: TreePath }> {
+  if (fieldType === 'rich_text') {
+    const richTextValue = nonLocalizedFieldValue as PossibleRichTextValue;
+    if (richTextValue) {
+      for (let index = 0; index < richTextValue.length; index++) {
+        const item = richTextValue[index]!;
+        yield { item, path: [index] };
+      }
+    }
+    return;
+  }
+
+  if (fieldType === 'single_block') {
+    const singleBlockValue = nonLocalizedFieldValue as PossibleSingleBlockValue;
+    if (singleBlockValue) {
+      yield { item: singleBlockValue, path: [] };
+    }
+    return;
+  }
+
+  if (fieldType === 'structured_text') {
+    const structuredTextValue =
+      nonLocalizedFieldValue as PossibleStructuredTextValue;
+    if (structuredTextValue) {
+      const foundNodes = await collectNodesAsync(
+        structuredTextValue.document,
+        async (node) => node.type === 'block' || node.type === 'inlineBlock',
+      );
+
+      for (const { node, path } of foundNodes) {
+        if (node.type === 'block' || node.type === 'inlineBlock') {
+          yield { item: node.item, path };
+        }
+      }
+    }
+    return;
+  }
+}
+
+/**
+ * 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 async function nonRecursiveVisitBlocksInNonLocalizedFieldValueAsync(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+  visitor: (item: BlockInRequest, path: TreePath) => Promise<void>,
+): Promise<void> {
+  for await (const { item, path } of iterateBlocksAsync(
+    fieldType,
+    nonLocalizedFieldValue,
+  )) {
+    await visitor(item, path);
+  }
+}
+
+/**
+ * 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 function nonRecursiveMapBlocksInNonLocalizedFieldValue(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+  mapper: (item: BlockInRequest, path: TreePath) => BlockInRequest,
+): unknown {
+  if (fieldType === 'rich_text') {
+    const richTextValue = nonLocalizedFieldValue as PossibleRichTextValue;
+    return richTextValue
+      ? richTextValue.map((item, index) => mapper(item, [index]))
+      : richTextValue;
+  }
+
+  if (fieldType === 'single_block') {
+    const singleBlockValue = nonLocalizedFieldValue as PossibleSingleBlockValue;
+    return singleBlockValue ? mapper(singleBlockValue, []) : null;
+  }
+
+  if (fieldType === 'structured_text') {
+    const structuredTextValue =
+      nonLocalizedFieldValue as PossibleStructuredTextValue;
+
+    if (!structuredTextValue) {
+      return null;
+    }
+
+    return {
+      schema: 'dast',
+      document: mapNodes(
+        structuredTextValue.document,
+        (node, _parent, path) => {
+          if (node.type === 'block' || node.type === 'inlineBlock') {
+            return { ...node, item: mapper(node.item, path) };
+          }
+
+          return node;
+        },
+      ),
+    };
+  }
+
+  return nonLocalizedFieldValue;
+}
+
+/**
+ * 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 async function nonRecursiveMapBlocksInNonLocalizedFieldValueAsync(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+  mapper: (item: BlockInRequest, path: TreePath) => Promise<BlockInRequest>,
+): Promise<unknown> {
+  if (fieldType === 'rich_text') {
+    const richTextValue = nonLocalizedFieldValue as PossibleRichTextValue;
+    return richTextValue
+      ? await Promise.all(
+          richTextValue.map((item, index) => mapper(item, [index])),
+        )
+      : richTextValue;
+  }
+
+  if (fieldType === 'single_block') {
+    const singleBlockValue = nonLocalizedFieldValue as PossibleSingleBlockValue;
+    return singleBlockValue ? await mapper(singleBlockValue, []) : null;
+  }
+
+  if (fieldType === 'structured_text') {
+    const structuredTextValue =
+      nonLocalizedFieldValue as PossibleStructuredTextValue;
+
+    if (!structuredTextValue) {
+      return null;
+    }
+
+    return {
+      schema: 'dast',
+      document: await mapNodesAsync(
+        structuredTextValue.document,
+        async (node, _parent, path) => {
+          if (node.type === 'block' || node.type === 'inlineBlock') {
+            return { ...node, item: await mapper(node.item, path) };
+          }
+
+          return node;
+        },
+      ),
+    };
+  }
+
+  return nonLocalizedFieldValue;
+}
+
+/**
+ * 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 async function nonRecursiveFindAllBlocksInNonLocalizedFieldValueAsync(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+  predicate: (item: BlockInRequest, path: TreePath) => Promise<boolean>,
+): Promise<Array<{ item: BlockInRequest; path: TreePath }>> {
+  const results: Array<{ item: BlockInRequest; path: TreePath }> = [];
+
+  for await (const { item, path } of iterateBlocksAsync(
+    fieldType,
+    nonLocalizedFieldValue,
+  )) {
+    if (await predicate(item, path)) {
+      results.push({ item, path });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * 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 async function nonRecursiveFilterBlocksInNonLocalizedFieldValueAsync(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+  predicate: (item: BlockInRequest, path: TreePath) => Promise<boolean>,
+): Promise<unknown> {
+  if (fieldType === 'rich_text') {
+    const filteredItems: BlockInRequest[] = [];
+
+    for await (const { item, path } of iterateBlocksAsync(
+      fieldType,
+      nonLocalizedFieldValue,
+    )) {
+      if (await predicate(item, path)) {
+        filteredItems.push(item);
+      }
+    }
+
+    return filteredItems;
+  }
+
+  if (fieldType === 'single_block') {
+    for await (const { item, path } of iterateBlocksAsync(
+      fieldType,
+      nonLocalizedFieldValue,
+    )) {
+      if (await predicate(item, path)) {
+        return item;
+      }
+    }
+    return null;
+  }
+
+  if (fieldType === 'structured_text') {
+    const structuredTextValue =
+      nonLocalizedFieldValue as PossibleStructuredTextValue;
+
+    if (!structuredTextValue) {
+      return null;
+    }
+
+    const filteredDocument = await filterNodesAsync(
+      structuredTextValue.document,
+      async (node, _parent, path) => {
+        if (node.type === 'block' || node.type === 'inlineBlock') {
+          return await predicate(node.item, path);
+        }
+        return true;
+      },
+    );
+
+    return filteredDocument
+      ? {
+          schema: 'dast',
+          document: filteredDocument,
+        }
+      : null;
+  }
+
+  return nonLocalizedFieldValue;
+}
+
+/**
+ * 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 async function nonRecursiveReduceBlocksInNonLocalizedFieldValueAsync<R>(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+  reducer: (accumulator: R, item: BlockInRequest, path: TreePath) => Promise<R>,
+  initialValue: R,
+): Promise<R> {
+  let accumulator = initialValue;
+
+  for await (const { item, path } of iterateBlocksAsync(
+    fieldType,
+    nonLocalizedFieldValue,
+  )) {
+    accumulator = await reducer(accumulator, item, path);
+  }
+
+  return accumulator;
+}
+
+/**
+ * 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 async function nonRecursiveSomeBlocksInNonLocalizedFieldValueAsync(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+  predicate: (item: BlockInRequest, path: TreePath) => Promise<boolean>,
+): Promise<boolean> {
+  for await (const { item, path } of iterateBlocksAsync(
+    fieldType,
+    nonLocalizedFieldValue,
+  )) {
+    if (await predicate(item, path)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 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 async function nonRecursiveEveryBlockInNonLocalizedFieldValueAsync(
+  fieldType: ApiTypes.Field['field_type'],
+  nonLocalizedFieldValue: unknown,
+  predicate: (item: BlockInRequest, path: TreePath) => Promise<boolean>,
+): Promise<boolean> {
+  return !(await nonRecursiveSomeBlocksInNonLocalizedFieldValueAsync(
+    fieldType,
+    nonLocalizedFieldValue,
+    async (item, path) => {
+      return !(await predicate(item, path));
+    },
+  ));
+}

package/src/utilities/{fieldValue.ts → normalizedFieldValues.ts}

@@ -47,6 +47,25 @@ export function isLocalized(
   return 'attributes' in field ? field.attributes.localized : field.localized;
 }
 
+export function isLocalizedFieldValue<T = unknown, L extends string = string>(
+  value: unknown,
+): value is LocalizedFieldValue<T, L> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return false;
+  }
+
+  const keys = Object.keys(value);
+
+  if (keys.length === 0) {
+    return false;
+  }
+
+  const localePattern =
+    /^[A-Za-z]{2,4}(-[A-Za-z]{4})?(-([A-Za-z]{2}|[0-9]{3}))?$/;
+
+  return keys.every((key) => localePattern.test(key));
+}
+
 /**
  * A normalized entry that represents a single value from either a localized or non-localized field.
  *
@@ -55,7 +74,10 @@ export function isLocalized(
  *
  * 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;
 };
@@ -70,10 +92,13 @@ 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 function fieldValueToEntries<T = unknown, L extends string = string>(
+export function toNormalizedFieldValueEntries<
+  T = unknown,
+  L extends string = string,
+>(
   field: RawApiTypes.Field | ApiTypes.Field,
   value: T | LocalizedFieldValue<T, L>,
-): FieldValueEntry<T, L>[] {
+): NormalizedFieldValueEntry<T, L>[] {
   if (isLocalized(field)) {
     const localizedValue = value as LocalizedFieldValue<T, L>;
 
@@ -89,7 +114,7 @@ export function fieldValueToEntries<T = unknown, L extends string = string>(
 /**
  * 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.
  *
@@ -97,9 +122,12 @@ export function fieldValueToEntries<T = unknown, L extends string = string>(
  * @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 function entriesToFieldValue<T = unknown, L extends string = string>(
+export function fromNormalizedFieldValueEntries<
+  T = unknown,
+  L extends string = string,
+>(
   field: RawApiTypes.Field | ApiTypes.Field,
-  entries: FieldValueEntry<T, L>[],
+  entries: NormalizedFieldValueEntry<T, L>[],
 ): T | LocalizedFieldValue<T, L> {
   if (isLocalized(field)) {
     return Object.fromEntries(
@@ -125,7 +153,7 @@ export function entriesToFieldValue<T = unknown, L extends string = string>(
  * @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 function mapFieldValue<
+export function mapNormalizedFieldValues<
   TInput = unknown,
   TOutput = unknown,
   L extends string = string,
@@ -134,12 +162,12 @@ export function mapFieldValue<
   value: TInput | LocalizedFieldValue<TInput, L>,
   mapFn: (locale: L | undefined, localeValue: TInput) => TOutput,
 ): TOutput | LocalizedFieldValue<TOutput, L> {
-  const entries = fieldValueToEntries<TInput, L>(field, value);
+  const entries = toNormalizedFieldValueEntries<TInput, L>(field, value);
   const mappedEntries = entries.map(({ locale, value }) => ({
     locale,
     value: mapFn(locale, value),
   }));
-  return entriesToFieldValue<TOutput, L>(field, mappedEntries);
+  return fromNormalizedFieldValueEntries<TOutput, L>(field, mappedEntries);
 }
 
 /**
@@ -153,7 +181,7 @@ export function mapFieldValue<
  * @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 async function mapFieldValueAsync<
+export async function mapNormalizedFieldValuesAsync<
   TInput = unknown,
   TOutput = unknown,
   L extends string = string,
@@ -162,14 +190,14 @@ export async function mapFieldValueAsync<
   value: TInput | LocalizedFieldValue<TInput, L>,
   mapFn: (locale: L | undefined, localeValue: TInput) => Promise<TOutput>,
 ): Promise<TOutput | LocalizedFieldValue<TOutput, L>> {
-  const entries = fieldValueToEntries<TInput, L>(field, value);
+  const entries = toNormalizedFieldValueEntries<TInput, L>(field, value);
   const mappedEntries = await Promise.all(
     entries.map(async ({ locale, value }) => ({
       locale,
       value: await mapFn(locale, value),
     })),
   );
-  return entriesToFieldValue<TOutput, L>(field, mappedEntries);
+  return fromNormalizedFieldValueEntries<TOutput, L>(field, mappedEntries);
 }
 
 /**
@@ -182,18 +210,21 @@ export async function mapFieldValueAsync<
  * @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 function filterFieldValue<T = unknown, L extends string = string>(
+export 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 {
-  const entries = fieldValueToEntries<T, L>(field, value);
+  const entries = toNormalizedFieldValueEntries<T, L>(field, value);
   const filteredEntries = entries.filter((entry) =>
     filterFn(entry.locale, entry.value),
   );
 
   if (isLocalized(field)) {
-    return entriesToFieldValue<T, L>(field, filteredEntries);
+    return fromNormalizedFieldValueEntries<T, L>(field, filteredEntries);
   }
 
   return filteredEntries.length > 0 ? filteredEntries[0]?.value : undefined;
@@ -209,7 +240,7 @@ export 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 async function filterFieldValueAsync<
+export async function filterNormalizedFieldValuesAsync<
   T = unknown,
   L extends string = string,
 >(
@@ -217,7 +248,7 @@ export async function filterFieldValueAsync<
   value: T | LocalizedFieldValue<T, L>,
   filterFn: (locale: L | undefined, localeValue: T) => Promise<boolean>,
 ): Promise<T | LocalizedFieldValue<T, L> | undefined> {
-  const entries = fieldValueToEntries<T, L>(field, value);
+  const entries = toNormalizedFieldValueEntries<T, L>(field, value);
   const results = await Promise.all(
     entries.map(async ({ locale, value }) => ({
       locale,
@@ -231,7 +262,7 @@ export async function filterFieldValueAsync<
     .map(({ locale, value }) => ({ locale, value }));
 
   if (isLocalized(field)) {
-    return entriesToFieldValue<T, L>(field, filteredEntries);
+    return fromNormalizedFieldValueEntries<T, L>(field, filteredEntries);
   }
 
   return filteredEntries.length > 0 ? filteredEntries[0]?.value : undefined;
@@ -247,12 +278,15 @@ export async function filterFieldValueAsync<
  * @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 function someFieldValue<T = unknown, L extends string = string>(
+export 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 {
-  const entries = fieldValueToEntries<T, L>(field, value);
+  const entries = toNormalizedFieldValueEntries<T, L>(field, value);
   return entries.some(({ locale, value }) => testFn(locale, value));
 }
 
@@ -266,7 +300,7 @@ export function someFieldValue<T = unknown, L extends string = string>(
  * @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 async function someFieldValueAsync<
+export async function someNormalizedFieldValuesAsync<
   T = unknown,
   L extends string = string,
 >(
@@ -274,7 +308,7 @@ export async function someFieldValueAsync<
   value: T | LocalizedFieldValue<T, L>,
   testFn: (locale: L | undefined, localeValue: T) => Promise<boolean>,
 ): Promise<boolean> {
-  const entries = fieldValueToEntries<T, L>(field, value);
+  const entries = toNormalizedFieldValueEntries<T, L>(field, value);
   const results = await Promise.all(
     entries.map(({ locale, value }) => testFn(locale, value)),
   );
@@ -291,12 +325,15 @@ export async function someFieldValueAsync<
  * @param testFn - The function to test each locale value or the direct value
  * @returns true if all values pass the test, false otherwise
  */
-export function everyFieldValue<T = unknown, L extends string = string>(
+export 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 {
-  return !someFieldValue(
+  return !someNormalizedFieldValues(
     field,
     value,
     (locale, localeValue) => !testFn(locale, localeValue),
@@ -313,7 +350,7 @@ export 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 async function everyFieldValueAsync<
+export async function everyNormalizedFieldValueAsync<
   T = unknown,
   L extends string = string,
 >(
@@ -321,7 +358,7 @@ export async function everyFieldValueAsync<
   value: T | LocalizedFieldValue<T, L>,
   testFn: (locale: L | undefined, localeValue: T) => Promise<boolean>,
 ): Promise<boolean> {
-  return !(await someFieldValueAsync(
+  return !(await someNormalizedFieldValuesAsync(
     field,
     value,
     async (locale, localeValue) => !(await testFn(locale, localeValue)),
@@ -337,12 +374,15 @@ export async function everyFieldValueAsync<
  * @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 function visitFieldValue<T = unknown, L extends string = string>(
+export 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 {
-  const entries = fieldValueToEntries<T, L>(field, value);
+  const entries = toNormalizedFieldValueEntries<T, L>(field, value);
   for (const { locale, value } of entries) {
     visitFn(locale, value);
   }
@@ -357,7 +397,7 @@ export 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 async function visitFieldValueAsync<
+export async function visitNormalizedFieldValuesAsync<
   T = unknown,
   L extends string = string,
 >(
@@ -365,6 +405,6 @@ export async function visitFieldValueAsync<
   value: T | LocalizedFieldValue<T, L>,
   visitFn: (locale: L | undefined, localeValue: T) => Promise<void>,
 ): Promise<void> {
-  const entries = fieldValueToEntries<T, L>(field, value);
+  const entries = toNormalizedFieldValueEntries<T, L>(field, value);
   await Promise.all(entries.map(({ locale, value }) => visitFn(locale, value)));
 }