@datocms/cma-client 5.1.12 → 5.1.14

package/README.md

@@ -1,28 +1,221 @@
-[![Node.js CI](https://github.com/datocms/js-rest-api-clients/actions/workflows/node.js.yml/badge.svg)](https://github.com/datocms/js-rest-api-clients/actions/workflows/node.js.yml)
+# DatoCMS Content Management API Utilities
 
-# DatoCMS Content Management JS API Client (Common)
+Take a look at the full [API documentation](https://www.datocms.com/docs/content-management-api) for examples!
 
-API client for [DatoCMS](https://www.datocms.com). Take a look at the full [API documentation](https://www.datocms.com/docs/content-management-api) for examples.
+## Field Types
 
-<br /><br />
-<a href="https://www.datocms.com/">
-<img src="https://www.datocms.com/images/full_logo.svg" height="60">
-</a>
-<br /><br />
+This library provides comprehensive TypeScript type definitions and utilities for all DatoCMS field types. Each field type includes type guards, validation functions, localization support, and editor appearance configurations.
 
-## Utility Functions
+### What's available
 
-This library provides a comprehensive set of utility functions to work with DatoCMS records, blocks, and field values. These utilities make it easier to manipulate, traverse, and inspect your content programmatically.
+Every field type follows a consistent pattern providing:
 
-### 1. Record Inspection Utilities
+- **Field value types**: TypeScript definitions for the field's data structure
+- **Type guards**: Functions to validate field values at runtime
+- **Localization support**: Utilities for handling localized field variants
+- **Validation types**: Supported validators for the field type
+- **Appearance configuration**: Editor types and their configuration options
 
-The `inspectItem()` function provides a visual, tree-structured representation of DatoCMS records in the console, making it easier to debug and understand complex content structures.
+**Example: `lat_lon` Field Type**
+
+<details>
+<summary>View example</summary>
+
+```typescript
+import { isLatLonFieldValue, isLocalizedLatLonFieldValue } from '@datocms/cma-client';
+import type { LatLonFieldValue, LatLonFieldValidators, LatLonFieldAppearance } from '@datocms/cma-client';
+
+// Field value type - object with latitude/longitude or null
+const value: LatLonFieldValue = { latitude: 45.4642, longitude: 9.1900 };
+
+// Type guard functions for validation
+if (isLatLonFieldValue(someValue)) {
+  // someValue is guaranteed to be { latitude: number; longitude: number } | null
+}
+
+if (isLocalizedLatLonFieldValue(localizedValue)) {
+  // localizedValue is a localized lat/lon field
+}
+
+// Validator and appearance types available for type-safe configuration
+type Validators = LatLonFieldValidators;
+type Appearance = LatLonFieldAppearance;
+```
+</details>
+
+### Context-Dependent field types
+
+Some field types have different value formats depending on the API context (request vs response) or query parameters:
+
+#### Request vs Response variations
+
+**File and Gallery fields** have different type requirements for API requests versus responses:
+
+<details>
+<summary>View example</summary>
+
+```typescript
+import {
+  FileFieldValue,
+  FileFieldValueInRequest,
+  GalleryFieldValue,
+  GalleryFieldValueInRequest,
+  // Type guards for runtime validation
+  isFileFieldValue,
+  isFileFieldValueInRequest,
+  isGalleryFieldValue,
+  isGalleryFieldValueInRequest
+} from '@datocms/cma-client';
+
+// API Response format - all metadata fields present with defaults
+const fileResponse: FileFieldValue = {
+  upload_id: "12345",
+  alt: null,           // Always present (default: null)
+  title: null,         // Always present (default: null)
+  custom_data: {},     // Always present (default: {})
+  focal_point: null    // Always present (default: null)
+};
+
+// API Request format - metadata fields are optional
+const fileRequest: FileFieldValueInRequest = {
+  upload_id: "12345"
+  // alt, title, custom_data, focal_point are optional
+};
+
+// Runtime validation for different contexts
+if (isFileFieldValueInRequest(someFileValue)) {
+  // someFileValue has optional metadata fields
+}
+
+if (isGalleryFieldValue(someGalleryValue)) {
+  // someGalleryValue is array of files with all metadata present
+}
+```
+</details>
+
+#### "Nested Mode" Response variations
+
+**Block-containing fields** (`structured_text`, `single_block`, `rich_text`) support different block representations for regular responses, for ["Nested Mode" responses](https://www.datocms.com/docs/content-management-api/resources/item#api-response-modes-regular-vs-nested), and for requests:
+
+<details>
+<summary>View example</summary>
+
+```typescript
+import {
+  StructuredTextFieldValue,
+  StructuredTextFieldValueInRequest,
+  StructuredTextFieldValueInNestedResponse,
+  // Type guards for all variations (also available for single_block and rich_text)
+  isStructuredTextFieldValue,
+  isStructuredTextFieldValueInRequest,
+  isStructuredTextFieldValueInNestedResponse
+} from '@datocms/cma-client';
+
+// Regular response - blocks as string IDs
+const standard: StructuredTextFieldValue = {
+  document: {
+    type: "root",
+    children: [
+      {
+        type: "block",
+        // String ID reference
+        item: "IdMLV2GJTXyQ0Bfns7R4IQ"
+      }
+    ]
+  }
+};
+
+// Nested Mode response (?nested=true) - blocks as full objects
+const nested: StructuredTextFieldValueInNestedResponse = {
+  document: {
+    type: "root",
+    children: [
+      {
+        type: "block",
+        // Always full block object
+        item: {
+          id: "IdMLV2GJTXyQ0Bfns7R4IQ",
+          type: "item",
+          attributes: { /* ... */ },
+          relationships: { /* ... */ }
+        }
+      }
+    ]
+  }
+};
+
+// Request format - flexible block representation
+const request: StructuredTextFieldValueInRequest = {
+  document: {
+    type: "root",
+    children: [
+      {
+        type: "block",
+        // Can be string ID, to keep block unchanged...
+        item: "FicV5CxCSQ6yOrgfwRoiKA"
+      },
+      {
+        type: "block",
+        // ...or full block object (to create new blocks or update existing ones)
+        item: {
+          type: "item",
+          attributes: { /* ... */ },
+          relationships: { /* ... */ }
+        }
+      }
+    ]
+  }
+};
+
+// Runtime validation for different contexts
+if (isStructuredTextFieldValueInNestedResponse(someStructuredText)) {
+  // someStructuredText has blocks as full objects
+}
+
+if (isStructuredTextFieldValueInRequest(requestData)) {
+  // requestData allows flexible block representations
+}
+```
+</details>
+
+These variants ensure type safety across different API contexts while maintaining the same conceptual data structure. All localized variants also have corresponding type guards (e.g., `isLocalizedStructuredTextFieldValueInRequest`, `isLocalizedStructuredTextFieldValueInNestedResponse`, etc.).
+
+**TypeScript Generics Support:** For maximum type safety, all field value types and type guards for block-containing fields accept [`ItemTypeDefinition` generics](https://www.datocms.com/docs/content-management-api/resources/item#type-safe-development-with-typescript) to provide precise typing for your specific schema:
 
 <details>
-<summary><strong>inspectItem()</strong> - Display records with visual appeal</summary>
+<summary>View example</summary>
+
+```typescript
+import type { MyArticle, MyArticleSection } from './schema';
+
+// Fully typed structured text with specific block types
+const content: StructuredTextFieldValueInRequest<MyArticleSection> = {
+  document: {
+    type: "root",
+    children: [/* ... */]
+  }
+};
+
+// Type guard with generic for precise validation
+if (isStructuredTextFieldValueInNestedResponse<MyArticleSection>(value)) {
+  // value is now typed with your specific block schema
+}
+```
+</details>
+
+## Block Processing Utilities
+
+### Inspecting Records and Blocks
+
+The `inspectItem()` function provides a visual, tree-structured representation of DatoCMS records in the console, making it easier to debug and understand complex content structures.
+
+#### inspectItem()
 
 Formats a DatoCMS item (record or block) as a visual tree structure, showing all fields with proper formatting for each field type. Particularly useful for debugging nested structures like modular content and structured text.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signature:**
 ```typescript
 function inspectItem(
@@ -59,19 +252,61 @@ console.log(inspectItem(record));
 ```
 </details>
 
-### 2. Block Processing Utilities
+### Creating and Duplicating Blocks
+
+#### buildBlockRecord()
+
+Converts a block data object into the proper format for API requests.
+
+<details>
+<summary>View details</summary>
+
+**TypeScript Signature:**
+```typescript
+function buildBlockRecord<D extends ItemTypeDefinition>(
+  body: ItemUpdateSchema<ToItemDefinitionInRequest<D>>
+): NewBlockInRequest<ToItemDefinitionInRequest<D>>
+```
 
-These utilities provide a unified interface for working with blocks embedded within DatoCMS field values. DatoCMS supports three field types that can contain blocks: Modular Content (arrays of blocks), Single Block fields, and Structured Text (with embedded blocks). These functions abstract away the differences between field types, providing consistent APIs for common operations.
+**Parameters:**
+- `body`: Block data in update schema format
 
-#### Recursive Block Operations
+**Returns:** Formatted block record ready for API requests
+</details>
 
-These functions traverse blocks recursively, processing nested blocks within blocks. They require a `SchemaRepository` instance to look up field definitions for nested blocks.
+#### duplicateBlockRecord()
+
+Creates a deep copy of a block record, including all nested blocks, removing IDs to create new instances.
 
 <details>
-<summary><strong>visitBlocksInNonLocalizedFieldValue()</strong> - Recursively visit all blocks</summary>
+<summary>View details</summary>
+
+**TypeScript Signature:**
+```typescript
+async function duplicateBlockRecord<D extends ItemTypeDefinition>(
+  existingBlock: ItemWithOptionalIdAndMeta<ToItemDefinitionInNestedResponse<D>>,
+  schemaRepository: SchemaRepository
+): Promise<NewBlockInRequest<ToItemDefinitionInRequest<D>>>
+```
+
+**Parameters:**
+- `existingBlock`: The block to duplicate
+- `schemaRepository`: Repository for schema lookups
+
+**Returns:** New block record without IDs, ready to be created
+</details>
+
+### Recursive Block Operations
+
+DatoCMS supports three field types that can contain blocks: Modular Content (arrays of blocks), Single Block fields, and Structured Text (rich-text with embedded blocks). These functions abstract away the differences between field types and can traverse blocks recursively, processing nested blocks within blocks. They require a `SchemaRepository` instance to look up field definitions for nested blocks.
+
+#### visitBlocksInNonLocalizedFieldValue()
 
 Visit every block in a non-localized field value recursively, including blocks nested within other blocks.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signature:**
 ```typescript
 async function visitBlocksInNonLocalizedFieldValue(
@@ -79,24 +314,23 @@ async function visitBlocksInNonLocalizedFieldValue(
   fieldType: string,
   schemaRepository: SchemaRepository,
   visitor: (item: BlockInRequest, path: TreePath) => void | Promise<void>,
-  path?: TreePath
 ): Promise<void>
 ```
 
 **Parameters:**
 - `nonLocalizedFieldValue`: The non-localized field value
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `schemaRepository`: Repository for caching schema lookups
 - `visitor`: Function called for each block (including nested)
-- `path`: Optional base path for tracking location
-```
 </details>
 
-<details>
-<summary><strong>mapBlocksInNonLocalizedFieldValue()</strong> - Recursively transform all blocks</summary>
+#### mapBlocksInNonLocalizedFieldValue()
 
 Transform all blocks in a non-localized field value recursively, including nested blocks.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signature:**
 ```typescript
 async function mapBlocksInNonLocalizedFieldValue(
@@ -104,24 +338,25 @@ async function mapBlocksInNonLocalizedFieldValue(
   fieldType: string,
   schemaRepository: SchemaRepository,
   mapper: (item: BlockInRequest, path: TreePath) => BlockInRequest | Promise<BlockInRequest>,
-  path?: TreePath
 ): Promise<unknown>
 ```
 
 **Parameters:**
 - `nonLocalizedFieldValue`: The non-localized field value
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `schemaRepository`: Repository for caching schema lookups
 - `mapper`: Function that transforms each block
 
 **Returns:** New field value
 </details>
 
-<details>
-<summary><strong>filterBlocksInNonLocalizedFieldValue()</strong> - Recursively filter blocks</summary>
+#### filterBlocksInNonLocalizedFieldValue()
 
 Filter blocks recursively, removing blocks at any nesting level that don't match the predicate.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signature:**
 ```typescript
 async function filterBlocksInNonLocalizedFieldValue(
@@ -129,13 +364,12 @@ async function filterBlocksInNonLocalizedFieldValue(
   fieldType: string,
   schemaRepository: SchemaRepository,
   predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>,
-  path?: TreePath
 ): Promise<unknown>
 ```
 
 **Parameters:**
 - `nonLocalizedFieldValue`: The non-localized field value to filter
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `schemaRepository`: Repository for caching schema lookups
 - `predicate`: Function that tests each block
 
@@ -153,11 +387,13 @@ const noVideos = await filterBlocksInNonLocalizedFieldValue(
 ```
 </details>
 
-<details>
-<summary><strong>findAllBlocksInNonLocalizedFieldValue()</strong> - Recursively search for blocks</summary>
+#### findAllBlocksInNonLocalizedFieldValue()
 
 Find all blocks that match the predicate, searching recursively through nested blocks.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signature:**
 ```typescript
 async function findAllBlocksInNonLocalizedFieldValue(
@@ -165,24 +401,25 @@ async function findAllBlocksInNonLocalizedFieldValue(
   fieldType: string,
   schemaRepository: SchemaRepository,
   predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>,
-  path?: TreePath
 ): Promise<Array<{ item: BlockInRequest; path: TreePath }>>
 ```
 
 **Parameters:**
 - `nonLocalizedFieldValue`: The non-localized field value to search
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `schemaRepository`: Repository for caching schema lookups
 - `predicate`: Function that tests each block
 
 **Returns:** Array of all matching blocks with their paths
 </details>
 
-<details>
-<summary><strong>reduceBlocksInNonLocalizedFieldValue()</strong> - Recursively reduce blocks</summary>
+#### reduceBlocksInNonLocalizedFieldValue()
 
 Reduce all blocks recursively to a single value.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signature:**
 ```typescript
 async function reduceBlocksInNonLocalizedFieldValue<R>(
@@ -191,26 +428,26 @@ async function reduceBlocksInNonLocalizedFieldValue<R>(
   schemaRepository: SchemaRepository,
   reducer: (accumulator: R, item: BlockInRequest, path: TreePath) => R | Promise<R>,
   initialValue: R,
-  path?: TreePath
 ): Promise<R>
 ```
 
 **Parameters:**
 - `nonLocalizedFieldValue`: The non-localized field value to reduce
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `schemaRepository`: Repository for caching schema lookups
 - `reducer`: Function that processes each block
 - `initialValue`: Initial accumulator value
 
 **Returns:** The final accumulated value
-```
 </details>
 
-<details>
-<summary><strong>someBlocksInNonLocalizedFieldValue()</strong> - Recursively test for any match</summary>
+#### someBlocksInNonLocalizedFieldValue()
 
 Check if any block (including nested) matches the predicate.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signature:**
 ```typescript
 async function someBlocksInNonLocalizedFieldValue(
@@ -218,25 +455,25 @@ async function someBlocksInNonLocalizedFieldValue(
   fieldType: string,
   schemaRepository: SchemaRepository,
   predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>,
-  path?: TreePath
 ): Promise<boolean>
 ```
 
 **Parameters:**
 - `nonLocalizedFieldValue`: The non-localized field value to test
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `schemaRepository`: Repository for caching schema lookups
 - `predicate`: Function that tests each block
 
 **Returns:** True if any block matches
-```
 </details>
 
-<details>
-<summary><strong>everyBlockInNonLocalizedFieldValue()</strong> - Recursively test if all match</summary>
+#### everyBlockInNonLocalizedFieldValue()
 
 Check if every block (including nested) matches the predicate.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signature:**
 ```typescript
 async function everyBlockInNonLocalizedFieldValue(
@@ -244,83 +481,28 @@ async function everyBlockInNonLocalizedFieldValue(
   fieldType: string,
   schemaRepository: SchemaRepository,
   predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>,
-  path?: TreePath
 ): Promise<boolean>
 ```
 
 **Parameters:**
 - `nonLocalizedFieldValue`: The non-localized field value to test
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `schemaRepository`: Repository for caching schema lookups
 - `predicate`: Function that tests each block
 
 **Returns:** True if all blocks match
 </details>
 
-#### Block Record Management
-
-<details>
-<summary><strong>buildBlockRecord()</strong> - Create block records from data</summary>
-
-Converts a block data object into the proper format for API requests.
-
-**TypeScript Signature:**
-```typescript
-function buildBlockRecord<D extends ItemTypeDefinition>(
-  body: ItemUpdateSchema<ToItemDefinitionInRequest<D>>
-): NewBlockInRequest<ToItemDefinitionInRequest<D>>
-```
-
-**Parameters:**
-- `body`: Block data in update schema format
-
-**Returns:** Formatted block record ready for API requests
-</details>
-
-<details>
-<summary><strong>duplicateBlockRecord()</strong> - Deep clone blocks with nested content</summary>
-
-Creates a deep copy of a block record, including all nested blocks, removing IDs to create new instances.
-
-**TypeScript Signature:**
-```typescript
-async function duplicateBlockRecord<D extends ItemTypeDefinition>(
-  existingBlock: ItemWithOptionalIdAndMeta<ToItemDefinitionInNestedResponse<D>>,
-  schemaRepository: SchemaRepository
-): Promise<NewBlockInRequest<ToItemDefinitionInRequest<D>>>
-```
-
-**Parameters:**
-- `existingBlock`: The block to duplicate
-- `schemaRepository`: Repository for schema lookups
-
-**Returns:** New block record without IDs, ready to be created
-</details>
-
-### 3. Localization-Aware Field Utilities
+## Unified Field Processing (Localized & Non-Localized)
 
 These utilities provide a unified interface for working with DatoCMS field values that may or may not be localized. They eliminate the need for conditional logic when processing fields that could be either localized or non-localized.
 
-<details>
-<summary><strong>isLocalized()</strong> - Check if a field is localized</summary>
-
-Determines whether a DatoCMS field is configured for localization.
+#### mapNormalizedFieldValues() / mapNormalizedFieldValuesAsync()
 
-**TypeScript Signature:**
-```typescript
-function isLocalized(field: Field): boolean
-```
-
-**Parameters:**
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
-
-**Returns:** True if the field is localized, false otherwise
-</details>
+Apply a transformation function to field values, handling both localized and non-localized fields uniformly.
 
 <details>
-<summary><strong>mapNormalizedFieldValues() / mapNormalizedFieldValuesAsync()</strong> - Transform field values</summary>
-
-Apply a transformation function to field values, handling both localized and non-localized fields uniformly.
+<summary>View details</summary>
 
 **TypeScript Signatures:**
 ```typescript
@@ -338,18 +520,20 @@ async function mapNormalizedFieldValuesAsync<TInput, TOutput>(
 ```
 
 **Parameters:**
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value (localized or non-localized)
 - `mapFn`: Function to transform each value (receives locale for localized fields, undefined for non-localized)
 
 **Returns:** Transformed value maintaining the same structure
 </details>
 
-<details>
-<summary><strong>filterNormalizedFieldValues() / filterNormalizedFieldValuesAsync()</strong> - Filter field values</summary>
+#### filterNormalizedFieldValues() / filterNormalizedFieldValuesAsync()
 
 Filter field values based on a predicate, handling both localized and non-localized fields.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signatures:**
 ```typescript
 function filterNormalizedFieldValues<T>(
@@ -366,18 +550,20 @@ async function filterNormalizedFieldValuesAsync<T>(
 ```
 
 **Parameters:**
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to filter
 - `filterFn`: Predicate function for filtering
 
 **Returns:** Filtered value or undefined if all filtered out
 </details>
 
-<details>
-<summary><strong>visitNormalizedFieldValues() / visitNormalizedFieldValuesAsync()</strong> - Iterate over field values</summary>
+#### visitNormalizedFieldValues() / visitNormalizedFieldValuesAsync()
 
 Visit each value in a field, handling both localized and non-localized fields.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signatures:**
 ```typescript
 function visitNormalizedFieldValues<T>(
@@ -394,16 +580,18 @@ async function visitNormalizedFieldValuesAsync<T>(
 ```
 
 **Parameters:**
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to visit
 - `visitFn`: Function called for each value
 </details>
 
-<details>
-<summary><strong>someNormalizedFieldValues() / someNormalizedFieldValuesAsync()</strong> - Test if any value matches</summary>
+#### someNormalizedFieldValues() / someNormalizedFieldValuesAsync()
 
 Check if at least one field value passes the test.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signatures:**
 ```typescript
 function someNormalizedFieldValues<T>(
@@ -420,18 +608,20 @@ async function someNormalizedFieldValuesAsync<T>(
 ```
 
 **Parameters:**
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to test
 - `testFn`: Predicate function
 
 **Returns:** True if any value passes the test
 </details>
 
-<details>
-<summary><strong>everyNormalizedFieldValue() / everyNormalizedFieldValueAsync()</strong> - Test if all values match</summary>
+#### everyNormalizedFieldValue() / everyNormalizedFieldValueAsync()
 
 Check if all field values pass the test.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signatures:**
 ```typescript
 function everyNormalizedFieldValue<T>(
@@ -448,18 +638,20 @@ async function everyNormalizedFieldValueAsync<T>(
 ```
 
 **Parameters:**
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to test
 - `testFn`: Predicate function
 
 **Returns:** True if all values pass the test
 </details>
 
-<details>
-<summary><strong>toNormalizedFieldValueEntries() / fromNormalizedFieldValueEntries()</strong> - Convert between formats</summary>
+#### toNormalizedFieldValueEntries() / fromNormalizedFieldValueEntries()
 
 Convert field values to/from a normalized entry format for uniform processing.
 
+<details>
+<summary>View details</summary>
+
 **TypeScript Signatures:**
 ```typescript
 function toNormalizedFieldValueEntries<T>(
@@ -479,7 +671,7 @@ type NormalizedFieldValueEntry<T> = {
 ```
 
 **Parameters:**
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`/`entries non-localized`: Value to convert from/to
 
 **Returns:** Normalized entries array or reconstructed field value
@@ -500,22 +692,60 @@ const result = fromNormalizedFieldValueEntries(field, processed);
 ```
 </details>
 
-### 4. Schema Repository
+## SchemaRepository
+
+The `SchemaRepository` class provides a lightweight, in-memory cache for DatoCMS schema entities (item types, fields, fieldsets, and plugins). It helps avoid redundant API calls when working across multiple functions or utilities that require schema lookups.
+
+**Why use it?**
 
-The `SchemaRepository` class provides an in-memory caching system for DatoCMS schema entities, significantly improving performance when working with complex content structures.
+- **Cache once, reuse everywhere**: The first API call stores results in memory; all subsequent lookups are instant.
+- **Efficient schema access**: Retrieve entities by ID, API key, or package name without re-fetching.
+- **Optimized for block processing**: Essential for utilities like `mapBlocksInNonLocalizedFieldValue`.
+- **Fewer API calls**: Dramatically speeds up bulk operations and complex traversals.
+
+**Usage Example:**
 
 <details>
-<summary><strong>SchemaRepository</strong> - Cache schema entities for performance</summary>
+<summary>View example</summary>
 
-Repository for DatoCMS schema entities including item types, fields, fieldsets, and plugins. Provides caching and efficient lookup functionality for schema-related operations.
+```typescript
+const schemaRepository = new SchemaRepository(client);
 
-**Key Features:**
-- Automatic caching of schema entities after first fetch
-- Efficient lookups by ID, API key, or package name
-- Essential for recursive block operations
-- Dramatically reduces API calls during complex traversals
+// First call: fetches from API and caches result
+const blogPost = await schemaRepository.getItemTypeByApiKey('blog_post');
+const fields = await schemaRepository.getItemTypeFields(blogPost);
+
+// Next calls: resolved instantly from cache (no API calls)
+const sameBlogPost = await schemaRepository.getItemTypeByApiKey('blog_post');
+const sameFields = await schemaRepository.getItemTypeFields(blogPost);
+
+// Works seamlessly with block-processing utilities
+await mapBlocksInNonLocalizedFieldValue(
+  fieldValue,
+  fieldType,
+  schemaRepository,  // share cached lookups
+  async (block) => {
+    // transform block here
+  }
+);
+```
+</details>
+
+**When to Use**
+
+* Traversing relationships that repeatedly query schema
+* Bulk record processing scripts
+* Block-processing utilities that need frequent lookups
+* Any script where reducing API calls matters
+
+**When Not to Use**
+
+* Scripts that modify schema (models, fields, etc.)
+* Long-running applications (cache never expires)
+* Situations where the schema might change during execution
+
+<details><summary><strong>Class signature</strong></summary>
 
-**TypeScript Class:**
 ```typescript
 class SchemaRepository {
   constructor(client: GenericClient)
@@ -542,41 +772,6 @@ class SchemaRepository {
   // ... and more raw variants
 }
 ```
-
-**When to Use:**
-- Complex traversal operations that repeatedly lookup schema
-- Bulk operations processing multiple records
-- Scripts that need efficient access to schema information
-- Working with recursive block utilities
-
-**When NOT to Use:**
-- Scripts that modify schema (models, fields, etc.)
-- Long-running applications (no cache expiration)
-- When schema might change during execution
-
-**Usage Example:**
-```typescript
-const schemaRepository = new SchemaRepository(client);
-
-// First call fetches from API and caches
-const blogPost = await schemaRepository.getItemTypeByApiKey('blog_post');
-const fields = await schemaRepository.getItemTypeFields(blogPost);
-
-// Subsequent calls use cached data (no API calls)
-const sameBlogPost = await schemaRepository.getItemTypeByApiKey('blog_post');
-const sameFields = await schemaRepository.getItemTypeFields(blogPost);
-
-// Use with recursive utilities for optimal performance
-await mapBlocksInNonLocalizedFieldValue(
-  schemaRepository,  // Pass repository for efficient lookups
-  field,
-  fieldValue,
-  async (block) => { /* transform */ }
-);
-```
-
-**Performance Impact:**
-Without SchemaRepository, a script processing structured text with nested blocks might make the same API calls dozens of times. SchemaRepository ensures each unique schema request is made only once, dramatically improving performance for complex operations.
 </details>
 
 ## Contributing