From 5d0cd5a1a7d80ae3da90f2331d25161b28f06910 Mon Sep 17 00:00:00 2001
From: markkaylor <mark.kaylor@strapi.io>
Date: Tue, 7 Jan 2025 19:17:11 +0100
Subject: [PATCH] chore(docs): document traverseEntity util (#22573)

---
 .../docs/01-core/utils/traverse-entity.md     | 145 ++++++++++++++++++
 1 file changed, 145 insertions(+)
 create mode 100644 docs/docs/docs/01-core/utils/traverse-entity.md

diff --git a/docs/docs/docs/01-core/utils/traverse-entity.md b/docs/docs/docs/01-core/utils/traverse-entity.md
new file mode 100644
index 0000000000..3bc0d9538a
--- /dev/null
+++ b/docs/docs/docs/01-core/utils/traverse-entity.md
@@ -0,0 +1,145 @@
+---
+title: traverseEntity
+tags:
+  - utils
+---
+
+# Traverse Entity Utility
+
+The `traverseEntity` function is designed to recursively traverse a data entity based on its schema definition. It provides hooks to execute custom logic at each level of the traversal through the `Visitor` function.
+
+## Overview
+
+### Purpose
+
+The utility is used for structured data manipulation. It supports various types of attributes, such as relations, components, dynamic zones, and media, allowing seamless traversal and transformation of deeply nested entities.
+
+## Function: `traverseEntity`
+
+### Signature
+
+```typescript
+async function traverseEntity(
+  visitor: [Visitor](#visitoroptions),
+  options: TraverseOptions,
+  entity: Data
+): Promise<Data>;
+```
+
+### Parameters
+
+- **`visitor`**:  
+  A function executed for each attribute of the entity. It provides context and utilities for modifying the entity.
+
+- **`options`**:  
+  Configuration for traversal, including:
+
+  - `schema` _(Model)_: The schema definition of the current entity.
+  - `path` _(Path, optional)_: Tracks the current traversal path.
+  - `parent` _(Parent, optional)_: Information about the parent attribute.
+  - `getModel` _(Function)_: A function to retrieve the schema of a model by its UID.
+
+- **`entity`**:  
+  The data entity to be traversed.
+
+### Returns
+
+A `Promise<Data>` that resolves with the transformed entity.
+
+## Related Types
+
+### Visitor
+
+```typescript
+type Visitor = (visitorOptions: VisitorOptions, visitorUtils: VisitorUtils) => void;
+```
+
+A function executed during traversal for each attribute.
+
+**Parameters**:
+
+- **`visitorOptions`** _(VisitorOptions)_: Provides details about the current state of traversal.
+- **`visitorUtils`** _(VisitorUtils)_: Utilities for modifying the entity (e.g., `set`, `remove`).
+
+### VisitorOptions
+
+```typescript
+interface VisitorOptions {
+  data: Record<string, unknown>;
+  schema: Model;
+  key: string;
+  value: Data[keyof Data];
+  attribute?: AnyAttribute;
+  path: Path;
+  getModel(uid: string): Model;
+  parent?: Parent;
+}
+```
+
+- **`data`**: The current entity or its sub-section being processed.
+- **`schema`**: The schema definition of the current entity.
+- **`key`**: The current attribute key.
+- **`value`**: The current attribute value.
+- **`attribute`** _(optional)_: The schema attribute definition for the current key.
+- **`path`**: Tracks the traversal path.
+- **`getModel`**: Function to retrieve a schema definition by UID.
+- **`parent`** _(optional)_: Information about the parent attribute.
+
+### VisitorUtils
+
+```typescript
+interface VisitorUtils {
+  remove(key: string): void;
+  set(key: string, value: Data): void;
+}
+```
+
+Utility functions to modify the entity:
+
+- **`remove(key)`**: Deletes an attribute from the entity.
+- **`set(key, value)`**: Sets or updates an attribute on the entity.
+
+### Path
+
+```typescript
+interface Path {
+  raw: string | null;
+  attribute: string | null;
+}
+```
+
+Tracks the traversal path:
+
+- **`raw`**: The traversal path on the entity
+- **`attribute`**: The same traversal path on the schema if the attibute exists
+
+### Parent
+
+```typescript
+interface Parent {
+  attribute?: Attribute;
+  key: string | null;
+  path: Path;
+  schema: Model;
+}
+```
+
+Tracks parent information for the current attribute.
+
+### TraverseOptions
+
+```typescript
+interface TraverseOptions {
+  schema: Model;
+  path?: Path;
+  parent?: Parent;
+  getModel(uid: string): Model;
+}
+```
+
+Configuration for the traversal:
+
+- **`schema`**: The schema definition of the current entity.
+- **`path`** _(optional)_: Tracks the current traversal path.
+- **`parent`** _(optional)_: Information about the parent attribute.
+- **`getModel`**: Function to retrieve a schema definition by UID.