@datocms/cma-client 5.1.11 → 5.1.13

package/README.md

@@ -1,20 +1,195 @@
-[![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
+
+**Example: `lat_lon` Field Type**
+
+```typescript
+import { LatLonFieldValue, isLatLonFieldValue, isLocalizedLatLonFieldValue } from '@datocms/cma-client';
+import type { LatLonFieldValidators, LatLonFieldAppearance } from '@datocms/cma-client';
+
+// Field value type - can be boolean or null
+const value: LatLonFieldValue = true;
+
+// Type guard functions for validation
+if (isLatLonFieldValue(someValue)) {
+  // someValue is guaranteed to be boolean | null
+}
+
+if (isLocalizedLatLonFieldValue(localizedValue)) {
+  // localizedValue is a localized boolean field
+}
+
+// Validator and appearance types available for type-safe configuration
+type Validators = LatLonFieldValidators;
+type Appearance = LatLonFieldAppearance;
+```
+
+### 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:
+
+```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
+}
+```
+
+#### "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:
+
+```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
+}
+```
+
+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:
+
+```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
+}
+```
+
+## 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.
 
@@ -59,13 +234,49 @@ console.log(inspectItem(record));
 ```
 </details>
 
-### 2. Block Processing Utilities
+### Creating and Duplicating Blocks
 
-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.
+<details>
+<summary><strong>buildBlockRecord()</strong> - Create block records from data</summary>
 
-#### Recursive Block Operations
+Converts a block data object into the proper format for API requests.
 
-These functions traverse blocks recursively, processing nested blocks within blocks. They require a `SchemaRepository` instance to look up field definitions for nested blocks.
+**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>
+
+### 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.
 
 <details>
 <summary><strong>visitBlocksInNonLocalizedFieldValue()</strong> - Recursively visit all blocks</summary>
@@ -75,21 +286,18 @@ Visit every block in a non-localized field value recursively, including blocks n
 **TypeScript Signature:**
 ```typescript
 async function visitBlocksInNonLocalizedFieldValue(
-  schemaRepository: SchemaRepository,
-  fieldType: string,
   nonLocalizedFieldValue: unknown,
-  visitor: (item: BlockItemInARequest, path: TreePath) => void | Promise<void>,
-  path?: TreePath
+  fieldType: string,
+  schemaRepository: SchemaRepository,
+  visitor: (item: BlockInRequest, path: TreePath) => void | Promise<void>,
 ): Promise<void>
 ```
 
 **Parameters:**
-- `schemaRepository`: Repository for caching schema lookups
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value
+- `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>
@@ -100,20 +308,18 @@ Transform all blocks in a non-localized field value recursively, including neste
 **TypeScript Signature:**
 ```typescript
 async function mapBlocksInNonLocalizedFieldValue(
-  schemaRepository: SchemaRepository,
-  fieldType: string,
   nonLocalizedFieldValue: unknown,
-  mapper: (item: BlockItemInARequest, path: TreePath) => BlockItemInARequest | Promise<BlockItemInARequest>,
-  path?: TreePath
+  fieldType: string,
+  schemaRepository: SchemaRepository,
+  mapper: (item: BlockInRequest, path: TreePath) => BlockInRequest | Promise<BlockInRequest>,
 ): Promise<unknown>
 ```
 
 **Parameters:**
-- `schemaRepository`: Repository for caching schema lookups
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `schemaRepository`: Repository for caching schema lookups
 - `mapper`: Function that transforms each block
-- `path`: Optional base path
 
 **Returns:** New field value
 </details>
@@ -126,20 +332,18 @@ Filter blocks recursively, removing blocks at any nesting level that don't match
 **TypeScript Signature:**
 ```typescript
 async function filterBlocksInNonLocalizedFieldValue(
-  schemaRepository: SchemaRepository,
-  fieldType: string,
   nonLocalizedFieldValue: unknown,
-  predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>,
-  path?: TreePath
+  fieldType: string,
+  schemaRepository: SchemaRepository,
+  predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>,
 ): Promise<unknown>
 ```
 
 **Parameters:**
-- `schemaRepository`: Repository for caching schema lookups
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to filter
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `schemaRepository`: Repository for caching schema lookups
 - `predicate`: Function that tests each block
-- `path`: Optional base path
 
 **Returns:** New field value with filtered blocks
 
@@ -163,20 +367,18 @@ Find all blocks that match the predicate, searching recursively through nested b
 **TypeScript Signature:**
 ```typescript
 async function findAllBlocksInNonLocalizedFieldValue(
-  schemaRepository: SchemaRepository,
-  fieldType: string,
   nonLocalizedFieldValue: unknown,
-  predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>,
-  path?: TreePath
-): Promise<Array<{ item: BlockItemInARequest; path: TreePath }>>
+  fieldType: string,
+  schemaRepository: SchemaRepository,
+  predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>,
+): Promise<Array<{ item: BlockInRequest; path: TreePath }>>
 ```
 
 **Parameters:**
-- `schemaRepository`: Repository for caching schema lookups
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to search
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `schemaRepository`: Repository for caching schema lookups
 - `predicate`: Function that tests each block
-- `path`: Optional base path
 
 **Returns:** Array of all matching blocks with their paths
 </details>
@@ -189,25 +391,22 @@ Reduce all blocks recursively to a single value.
 **TypeScript Signature:**
 ```typescript
 async function reduceBlocksInNonLocalizedFieldValue<R>(
-  schemaRepository: SchemaRepository,
-  fieldType: string,
   nonLocalizedFieldValue: unknown,
-  reducer: (accumulator: R, item: BlockItemInARequest, path: TreePath) => R | Promise<R>,
+  fieldType: string,
+  schemaRepository: SchemaRepository,
+  reducer: (accumulator: R, item: BlockInRequest, path: TreePath) => R | Promise<R>,
   initialValue: R,
-  path?: TreePath
 ): Promise<R>
 ```
 
 **Parameters:**
-- `schemaRepository`: Repository for caching schema lookups
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to reduce
+- `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
-- `path`: Optional base path
 
 **Returns:** The final accumulated value
-```
 </details>
 
 <details>
@@ -218,23 +417,20 @@ Check if any block (including nested) matches the predicate.
 **TypeScript Signature:**
 ```typescript
 async function someBlocksInNonLocalizedFieldValue(
-  schemaRepository: SchemaRepository,
-  fieldType: string,
   nonLocalizedFieldValue: unknown,
-  predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>,
-  path?: TreePath
+  fieldType: string,
+  schemaRepository: SchemaRepository,
+  predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>,
 ): Promise<boolean>
 ```
 
 **Parameters:**
-- `schemaRepository`: Repository for caching schema lookups
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to test
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `schemaRepository`: Repository for caching schema lookups
 - `predicate`: Function that tests each block
-- `path`: Optional base path
 
 **Returns:** True if any block matches
-```
 </details>
 
 <details>
@@ -245,84 +441,26 @@ Check if every block (including nested) matches the predicate.
 **TypeScript Signature:**
 ```typescript
 async function everyBlockInNonLocalizedFieldValue(
-  schemaRepository: SchemaRepository,
-  fieldType: string,
   nonLocalizedFieldValue: unknown,
-  predicate: (item: BlockItemInARequest, path: TreePath) => boolean | Promise<boolean>,
-  path?: TreePath
+  fieldType: string,
+  schemaRepository: SchemaRepository,
+  predicate: (item: BlockInRequest, path: TreePath) => boolean | Promise<boolean>,
 ): Promise<boolean>
 ```
 
 **Parameters:**
-- `schemaRepository`: Repository for caching schema lookups
-- `fieldType`: The typeo of DatoCMS field (ie. `string`, `rich_text`, etc.)
 - `nonLocalizedFieldValue`: The non-localized field value to test
+- `fieldType`: The type of DatoCMS field (ie. `string`, `rich_text`, etc.)
+- `schemaRepository`: Repository for caching schema lookups
 - `predicate`: Function that tests each block
-- `path`: Optional base path
 
 **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<ToItemDefinitionAsRequest<D>>
-): NewBlockInARequest<ToItemDefinitionAsRequest<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<ToItemDefinitionWithNestedBlocks<D>>,
-  schemaRepository: SchemaRepository
-): Promise<NewBlockInARequest<ToItemDefinitionAsRequest<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.
-
-**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>
-
 <details>
 <summary><strong>mapNormalizedFieldValues() / mapNormalizedFieldValuesAsync()</strong> - Transform field values</summary>
 
@@ -344,7 +482,7 @@ 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)
 
@@ -372,7 +510,7 @@ 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
 
@@ -400,7 +538,7 @@ 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>
@@ -426,7 +564,7 @@ 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
 
@@ -454,7 +592,7 @@ 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
 
@@ -485,7 +623,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
@@ -503,25 +641,57 @@ const processed = entries.map(({ locale, value }) => ({
 
 // Convert back to field value format
 const result = fromNormalizedFieldValueEntries(field, processed);
-```
 </details>
 
-### 4. Schema Repository
+### 4. SchemaRepository
 
-The `SchemaRepository` class provides an in-memory caching system for DatoCMS schema entities, significantly improving performance when working with complex content structures.
+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.
 
-<details>
-<summary><strong>SchemaRepository</strong> - Cache schema entities for performance</summary>
+**Why use it?**
+
+- **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:**
+```typescript
+const schemaRepository = new SchemaRepository(client);
+
+// 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,
+  field,
+  schemaRepository,  // share cached lookups
+  async (block) => {
+    // transform block here
+  }
+);
+```
+
+**When to Use**
 
-Repository for DatoCMS schema entities including item types, fields, fieldsets, and plugins. Provides caching and efficient lookup functionality for schema-related operations.
+* Traversing relationships that repeatedly query schema
+* Bulk record processing scripts
+* Block-processing utilities that need frequent lookups
+* Any script where reducing API calls matters
 
-**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
+**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)
@@ -548,41 +718,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