@datocms/cma-client 5.1.0 → 5.1.2

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

@@ -1,5 +1,5 @@
-import type * as SchemaTypes from '../generated/SchemaTypes';
-import type * as SimpleSchemaTypes from '../generated/SimpleSchemaTypes';
+import type * as ApiTypes from '../generated/ApiTypes';
+import type * as RawApiTypes from '../generated/RawApiTypes';
 
 /*
  * Localized Field Value Operations Utilities
@@ -18,72 +18,100 @@ import type * as SimpleSchemaTypes from '../generated/SimpleSchemaTypes';
  * - Reduces code duplication and potential bugs from inconsistent handling
  * - Supports both synchronous and asynchronous operations
  * - Maintains the original data structure (localized fields remain localized, non-localized remain direct)
- *
- * Example usage:
- * ```typescript
- * // Instead of manually checking localization:
- * if (isLocalized(field)) {
- *   const result = {};
- *   for (const [locale, value] of Object.entries(fieldValue)) {
- *     result[locale] = processValue(value);
- *   }
- *   return result;
- * } else {
- *   return processValue(fieldValue);
- * }
- *
- * // Use the utility:
- * return mapLocalizedFieldValues(field, fieldValue, (locale, value) => processValue(value));
- * ```
  */
 
 /**
- * In DatoCMS, fields can be localized. In this scenario, their value contains values 
+ * Represents a localized field value in DatoCMS.
+ *
+ * In DatoCMS, fields can be localized. In this scenario, their value contains values
  * for various locales structured as an object, such as
- `{ "en": "Hello", "it": "Ciao" }`)
+ * `{ "en": "Hello", "it": "Ciao" }`
  */
 export type LocalizedFieldValue = Record<string, unknown>;
 
+/**
+ * Determines whether a DatoCMS field is localized or not.
+ *
+ * This function handles both full Schema field objects and simplified Schema field objects
+ * by checking the appropriate property based on the object structure.
+ *
+ * @param field - The DatoCMS field definition (either full or simple schema)
+ * @returns true if the field is localized, false otherwise
+ */
 export function isLocalized(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+  field: RawApiTypes.Field | ApiTypes.Field,
 ): boolean {
   return 'attributes' in field ? field.attributes.localized : field.localized;
 }
 
 /**
- * Maps localized field values using a provided mapping function.
- * For localized fields, applies the mapping function to each locale value.
- * For non-localized fields, applies the mapping function directly to the only non-localizeed value.
+ * A normalized entry that represents a single value from either a localized or non-localized field.
  *
- * @template T - The type that the mapping function returns
- * @param field - The DatoCMS field definition
- * @param value - The field value (either localized object or direct value)
- * @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
+ * For localized fields, each locale produces one entry with `locale` set to the locale code (e.g., "en", "it").
+ * For non-localized fields, there's one entry with `locale` set to `undefined`.
+ *
+ * This uniform structure allows the same processing logic to work with both field types.
  */
-export function mapLocalizedFieldValues<T>(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export type FieldValueEntry = {
+  locale: string | undefined;
+  value: unknown;
+};
+
+export type PossiblyLocalizedEntry = FieldValueEntry;
+
+/**
+ * Converts a field value (localized or non-localized) into a uniform array of entries.
+ *
+ * This function normalizes the handling of field values by converting them into a consistent
+ * array format, regardless of whether the field is localized or not.
+ *
+ * @param field - The DatoCMS field definition that determines localization behavior
+ * @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(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
-  mapFn: (locale: string | undefined, localeValue: unknown) => T,
 ) {
   if (isLocalized(field)) {
     const localizedValue = value as LocalizedFieldValue;
 
+    return Object.entries(localizedValue).map<FieldValueEntry>(
+      ([locale, value]) => ({ locale, value }),
+    );
+  }
+
+  return [{ locale: undefined, value }];
+}
+
+/**
+ * Converts an array of possibly localized entries back into the appropriate field value format.
+ *
+ * This function is the inverse of `fieldValueToPossiblyLocalizedEntries`. 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.
+ *
+ * @param field - The DatoCMS field definition that determines the output format
+ * @param possiblyLocalizedEntries - 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(
+  field: RawApiTypes.Field | ApiTypes.Field,
+  possiblyLocalizedEntries: FieldValueEntry[],
+) {
+  if (isLocalized(field)) {
     return Object.fromEntries(
-      Object.entries(localizedValue).map(([locale, value]) => [
-        locale,
-        mapFn(locale, value),
-      ]),
+      possiblyLocalizedEntries.map(({ locale, value }) => [locale, value]),
     );
   }
 
-  return mapFn(undefined, value);
+  return possiblyLocalizedEntries[0]?.value;
 }
 
 /**
- * Maps localized field values using a provided mapping function (async version).
+ * Maps field values using a provided mapping function.
  * For localized fields, applies the mapping function to each locale value.
- * For non-localized fields, applies the mapping function directly to the only non-localizeed value.
+ * For non-localized fields, applies the mapping function directly to the value.
  *
  * @template T - The type that the mapping function returns
  * @param field - The DatoCMS field definition
@@ -91,28 +119,47 @@ export function mapLocalizedFieldValues<T>(
  * @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 mapLocalizedFieldValuesAsync<T>(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export function mapFieldValue<T>(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
-  mapFn: (locale: string | undefined, localeValue: unknown) => Promise<T>,
+  mapFn: (locale: string | undefined, localeValue: unknown) => T,
 ) {
-  if (isLocalized(field)) {
-    const localizedValue = value as LocalizedFieldValue;
-
-    return Object.fromEntries(
-      await Promise.all(
-        Object.entries(localizedValue).map<Promise<[string, unknown]>>(
-          async ([locale, value]) => [locale, await mapFn(locale, value)],
-        ),
-      ),
-    );
-  }
+  const entries = fieldValueToEntries(field, value);
+  const mappedEntries = entries.map(({ locale, value }) => ({
+    locale,
+    value: mapFn(locale, value),
+  }));
+  return entriesToFieldValue(field, mappedEntries);
+}
 
-  return await mapFn(undefined, value);
+/**
+ * Maps field values using a provided mapping function (async version).
+ * For localized fields, applies the mapping function to each locale value.
+ * For non-localized fields, applies the mapping function directly to the value.
+ *
+ * @template T - The type that the mapping function returns
+ * @param field - The DatoCMS field definition
+ * @param value - The field value (either localized object or direct value)
+ * @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<T>(
+  field: RawApiTypes.Field | ApiTypes.Field,
+  value: unknown,
+  mapFn: (locale: string | undefined, localeValue: unknown) => Promise<T>,
+) {
+  const entries = fieldValueToEntries(field, value);
+  const mappedEntries = await Promise.all(
+    entries.map(async ({ locale, value }) => ({
+      locale,
+      value: await mapFn(locale, value),
+    })),
+  );
+  return entriesToFieldValue(field, mappedEntries);
 }
 
 /**
- * Filters localized field values using a provided filter function.
+ * Filters field values using a provided filter function.
  * For localized fields, filters each locale value.
  * For non-localized fields, returns the value if the filter passes, otherwise undefined.
  *
@@ -121,26 +168,25 @@ export async function mapLocalizedFieldValuesAsync<T>(
  * @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 filterLocalizedFieldValues(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export function filterFieldValue(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
   filterFn: (locale: string | undefined, localeValue: unknown) => boolean,
 ) {
-  if (isLocalized(field)) {
-    const localizedValue = value as LocalizedFieldValue;
+  const entries = fieldValueToEntries(field, value);
+  const filteredEntries = entries.filter(({ locale, value }) =>
+    filterFn(locale, value),
+  );
 
-    return Object.fromEntries(
-      Object.entries(localizedValue).filter(([locale, value]) =>
-        filterFn(locale, value),
-      ),
-    );
+  if (isLocalized(field)) {
+    return entriesToFieldValue(field, filteredEntries);
   }
 
-  return filterFn(undefined, value) ? value : undefined;
+  return filteredEntries.length > 0 ? filteredEntries[0]?.value : undefined;
 }
 
 /**
- * Filters localized field values using a provided filter function (async version).
+ * Filters field values using a provided filter function (async version).
  * For localized fields, filters each locale value.
  * For non-localized fields, returns the value if the filter passes, otherwise undefined.
  *
@@ -149,39 +195,36 @@ export function filterLocalizedFieldValues(
  * @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 filterLocalizedFieldValuesAsync(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export async function filterFieldValueAsync(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
   filterFn: (
     locale: string | undefined,
     localeValue: unknown,
   ) => Promise<boolean>,
 ) {
-  if (isLocalized(field)) {
-    const localizedValue = value as LocalizedFieldValue;
+  const entries = fieldValueToEntries(field, value);
+  const results = await Promise.all(
+    entries.map(async ({ locale, value }) => ({
+      locale,
+      value,
+      passed: await filterFn(locale, value),
+    })),
+  );
 
-    const results = await Promise.all(
-      Object.entries(localizedValue).map<Promise<[string, unknown, boolean]>>(
-        async ([locale, value]) => [
-          locale,
-          value,
-          await filterFn(locale, value),
-        ],
-      ),
-    );
+  const filteredEntries = results
+    .filter(({ passed }) => passed)
+    .map(({ locale, value }) => ({ locale, value }));
 
-    return Object.fromEntries(
-      results
-        .filter(([, , passed]) => passed)
-        .map(([locale, value]) => [locale, value]),
-    );
+  if (isLocalized(field)) {
+    return entriesToFieldValue(field, filteredEntries);
   }
 
-  return (await filterFn(undefined, value)) ? value : undefined;
+  return filteredEntries.length > 0 ? filteredEntries[0]?.value : undefined;
 }
 
 /**
- * Tests whether at least one localized field value passes the test implemented by the provided function.
+ * Tests whether at least one field value passes the test implemented by the provided function.
  * For localized fields, tests each locale value.
  * For non-localized fields, tests the direct value.
  *
@@ -190,24 +233,17 @@ export async function filterLocalizedFieldValuesAsync(
  * @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 someLocalizedFieldValues(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export function someFieldValue(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
   testFn: (locale: string | undefined, localeValue: unknown) => boolean,
 ): boolean {
-  if (isLocalized(field)) {
-    const localizedValue = value as LocalizedFieldValue;
-
-    return Object.entries(localizedValue).some(([locale, value]) =>
-      testFn(locale, value),
-    );
-  }
-
-  return testFn(undefined, value);
+  const entries = fieldValueToEntries(field, value);
+  return entries.some(({ locale, value }) => testFn(locale, value));
 }
 
 /**
- * Tests whether at least one localized field value passes the test implemented by the provided function (async version).
+ * Tests whether at least one field value passes the test implemented by the provided function (async version).
  * For localized fields, tests each locale value.
  * For non-localized fields, tests the direct value.
  *
@@ -216,31 +252,23 @@ export function someLocalizedFieldValues(
  * @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 someLocalizedFieldValuesAsync(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export async function someFieldValueAsync(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
   testFn: (
     locale: string | undefined,
     localeValue: unknown,
   ) => Promise<boolean>,
 ): Promise<boolean> {
-  if (isLocalized(field)) {
-    const localizedValue = value as LocalizedFieldValue;
-
-    const results = await Promise.all(
-      Object.entries(localizedValue).map(
-        async ([locale, value]) => await testFn(locale, value),
-      ),
-    );
-
-    return results.some((result) => result);
-  }
-
-  return await testFn(undefined, value);
+  const entries = fieldValueToEntries(field, value);
+  const results = await Promise.all(
+    entries.map(({ locale, value }) => testFn(locale, value)),
+  );
+  return results.some((result) => result);
 }
 
 /**
- * Tests whether all localized field values pass the test implemented by the provided function.
+ * Tests whether all field values pass the test implemented by the provided function.
  * For localized fields, tests each locale value.
  * For non-localized fields, tests the direct value.
  *
@@ -249,12 +277,12 @@ export async function someLocalizedFieldValuesAsync(
  * @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 everyLocalizedFieldValues(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export function everyFieldValue(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
   testFn: (locale: string | undefined, localeValue: unknown) => boolean,
 ): boolean {
-  return !someLocalizedFieldValues(
+  return !someFieldValue(
     field,
     value,
     (locale, localeValue) => !testFn(locale, localeValue),
@@ -262,7 +290,7 @@ export function everyLocalizedFieldValues(
 }
 
 /**
- * Tests whether all localized field values pass the test implemented by the provided function (async version).
+ * Tests whether all field values pass the test implemented by the provided function (async version).
  * For localized fields, tests each locale value.
  * For non-localized fields, tests the direct value.
  *
@@ -271,15 +299,15 @@ export function everyLocalizedFieldValues(
  * @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 everyLocalizedFieldValuesAsync(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export async function everyFieldValueAsync(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
   testFn: (
     locale: string | undefined,
     localeValue: unknown,
   ) => Promise<boolean>,
 ): Promise<boolean> {
-  return !(await someLocalizedFieldValuesAsync(
+  return !(await someFieldValueAsync(
     field,
     value,
     async (locale, localeValue) => !(await testFn(locale, localeValue)),
@@ -287,7 +315,7 @@ export async function everyLocalizedFieldValuesAsync(
 }
 
 /**
- * Visits each localized field value with the provided function.
+ * Visits each field value with the provided function.
  * For localized fields, visits each locale value.
  * For non-localized fields, visits the direct value.
  *
@@ -295,24 +323,19 @@ export async function everyLocalizedFieldValuesAsync(
  * @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 visitLocalizedFieldValues(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export function visitFieldValue(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
   visitFn: (locale: string | undefined, localeValue: unknown) => void,
 ): void {
-  if (isLocalized(field)) {
-    const localizedValue = value as LocalizedFieldValue;
-
-    for (const [locale, value] of Object.entries(localizedValue)) {
-      visitFn(locale, value);
-    }
-  } else {
-    visitFn(undefined, value);
+  const entries = fieldValueToEntries(field, value);
+  for (const { locale, value } of entries) {
+    visitFn(locale, value);
   }
 }
 
 /**
- * Visits each localized field value with the provided function (async version).
+ * Visits each field value with the provided function (async version).
  * For localized fields, visits each locale value.
  * For non-localized fields, visits the direct value.
  *
@@ -320,20 +343,11 @@ export function visitLocalizedFieldValues(
  * @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 visitLocalizedFieldValuesAsync(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+export async function visitFieldValueAsync(
+  field: RawApiTypes.Field | ApiTypes.Field,
   value: unknown,
   visitFn: (locale: string | undefined, localeValue: unknown) => Promise<void>,
 ): Promise<void> {
-  if (isLocalized(field)) {
-    const localizedValue = value as LocalizedFieldValue;
-
-    await Promise.all(
-      Object.entries(localizedValue).map(
-        async ([locale, value]) => await visitFn(locale, value),
-      ),
-    );
-  } else {
-    await visitFn(undefined, value);
-  }
+  const entries = fieldValueToEntries(field, value);
+  await Promise.all(entries.map(({ locale, value }) => visitFn(locale, value)));
 }

package/src/utilities/fieldsContainingReferences.ts

@@ -1,8 +1,8 @@
-import type * as SchemaTypes from '../generated/SchemaTypes';
-import type * as SimpleSchemaTypes from '../generated/SimpleSchemaTypes';
+import type * as ApiTypes from '../generated/ApiTypes';
+import type * as RawApiTypes from '../generated/RawApiTypes';
 
 export function modelIdsReferencedInField(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+  field: RawApiTypes.Field | ApiTypes.Field,
 ) {
   const attributes = 'attributes' in field ? field.attributes : field;
 
@@ -23,7 +23,7 @@ export function modelIdsReferencedInField(
 }
 
 export function blockModelIdsReferencedInField(
-  field: SchemaTypes.Field | SimpleSchemaTypes.Field,
+  field: RawApiTypes.Field | ApiTypes.Field,
 ) {
   const attributes = 'attributes' in field ? field.attributes : field;