import { Meta } from '@storybook/addon-docs/blocks'

<Meta title='@dxtmisha/ru/functional-basic/Functions/forEach - Перебор объекта или массива'/>

# `forEach`

Функция выполняет указанную функцию один раз для каждого элемента в объекте. И возвращает массив с результатами выполнения функции.

**Параметры:**
- `data: D` — объект для перебора.
- `callback: (item: T, key: K, dataMain: typeof data) => R` — функция, которая будет вызвана для каждого элемента.
- `saveUndefined?: boolean` — если `true`, функция вернет массив, включая `undefined` значения (по умолчанию фильтруются).

**Возвращает:**
`R[]` — массив с результатами выполнения функции.

## Как это работает

Функция является универсальным инструментом для перебора различных структур данных и сбора результатов в массив.

**Особенности:**
- **Поддержка типов** — работает с `Array`, `Map`, `Set` и обычными объектами (`Object`).
- **Сбор результатов** — в отличие от стандартного `forEach`, эта функция собирает значения, возвращаемые из `callback`, в новый массив.
- **Фильтрация undefined** — по умолчанию все значения `undefined` (например, если callback ничего не вернул для элемента) отфильтровываются из итогового массива.
- **Параметр saveUndefined** — если передать `true` третьим аргументом, массив сохранит все результаты, включая `undefined`.

## Пример

```typescript
import { forEach } from '@dxtmisha/functional-basic'

const data = [1, 2, 3]

// По умолчанию undefined фильтруются
forEach(data, (item) => item % 2 === 0 ? item : undefined) // [2]

// С сохранением undefined
forEach(data, (item) => item % 2 === 0 ? item : undefined, true) // [undefined, 2, undefined]
```
