# node-array-flatten

> A modern, efficient, and lightweight utility for flattening nested arrays in Node.js and JavaScript. Leverages native Array.prototype.flat() for optimal performance.

Latest version **1.1.0** (published 2025-06-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-array-flatten
pnpm add node-array-flatten
yarn add node-array-flatten
bun add node-array-flatten
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2025-06-16 |
| First published | 2020-07-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=12.0.0 |
| Dependencies | 0 |
| Unpacked size | 7.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Vishal Sharma |
| Maintainers | vish052 |
| Keywords | array, flatten, flat, nested, utility, javascript, node, array-flatten, array-flat, array-utility, list, deep-flatten, es2019, es-next, performance, functional, immutable, collection, transform |

## Links

- npm: https://www.npmjs.com/package/node-array-flatten
- Repository: https://github.com/vish052/node-array-flatten
- Homepage: https://github.com/vish052/node-array-flatten#readme
- Issues: https://github.com/vish052/node-array-flatten/issues
- npm.io page: https://npm.io/package/node-array-flatten

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2025-06-16
- 1.0.3 — 2020-07-06

## README

# node-array-flatten

A modern, efficient, and lightweight utility for flattening nested arrays in Node.js and JavaScript environments. This package leverages the native `Array.prototype.flat()` method for optimal performance and simplicity, providing a robust solution for transforming multi-dimensional arrays into single-dimensional ones.

## Features

* **Optimal Performance:** Utilizes the highly optimized native `Array.prototype.flat()` for fast array flattening.
* **Depth Control:** Supports flattening to a specified depth or completely flattening all nested arrays.
* **Simple API:** Easy to use with a clear and intuitive function signature.
* **Robust Input Validation:** Ensures the input is always an array, throwing an error for invalid types.

## Installation

```bash
npm install node-array-flatten
```

## Usage Example

The `flatten` function takes an array as its first argument and an optional `depth` as its second argument.

### Basic Usage (Deep Flatten)
By default, if no `depth` is specified, the function performs a deep flatten, concatenating all sub-array elements into a single-dimensional array, regardless of nesting level.

```bash
// For CommonJS (Node.js older versions or default Node.js modules)
const flatten = require('node-array-flatten');

// For ES Modules (modern Node.js with type: "module" in package.json)
// import flatten from 'node-array-flatten';

const nestedArray = [1, [2, 3], 4, [5, [6, 7], null, undefined, 0, false]];
const flattenedArray = flatten(nestedArray);

console.log('Deep Flatten Example:');
console.log(flattenedArray);
// Expected Output: [1, 2, 3, 4, 5, 6, 7, null, undefined, 0, false]
```

### Flattening to a Specific Depth
You can control how many levels deep the array is flattened by providing a `depth` argument.

```bash
const deeplyNested = [1, [2, [3, 4]], 5, [6, [7, [8, 9]]]];

// Flatten one level deep
const oneLevelFlattened = flatten(deeplyNested, 1);
console.log('\nFlatten 1 Level Deep:');
console.log(oneLevelFlattened);
// Expected Output: [1, 2, [3, 4], 5, 6, [7, [8, 9]]]

// Flatten two levels deep
const twoLevelsFlattened = flatten(deeplyNested, 2);
console.log('\nFlatten 2 Levels Deep:');
console.log(twoLevelsFlattened);
// Expected Output: [1, 2, 3, 4, 5, 6, 7, [8, 9]]

// Explicitly flatten all levels (same as default if no depth is given)
const infinityFlattened = flatten(deeplyNested, Infinity);
console.log('\nFlatten All Levels (Infinity):');
console.log(infinityFlattened);
// Expected Output: [1, 2, 3, 4, 5, 6, 7, 8, 9]
```
### Handling Invalid Input
The function strictly requires an array as input. Passing a non-array value will result in an error.

```bash
try {
    flatten('This is not an array!');
} catch (error) {
    console.error('\nError Example:');
    console.error(error.message);
}
// Expected Output: Error: Input must be an array!

try {
    flatten(123);
} catch (error) {
    console.error(error.message);
}
// Expected Output: Error: Input must be an array!
```

Here's the Markdown text for your API, Compatibility, Contributing, and License sections, formatted clearly for your `README.md` file:

---

## API

### `flatten(arr, [depth])`

* `arr` (**Array**, **required**): The array to be flattened.
* `depth` (**number**, optional, default: `Infinity`): The number of levels to flatten.
    * Set to `1` to flatten only the first level of nested arrays.
    * Set to `Infinity` (or omit) to flatten all nested arrays recursively into a single-dimensional array.

**Returns:** A new **Array** with the sub-array elements concatenated into it.

**Throws:** An **Error** if `arr` is not an array.

---

## Compatibility

This package relies on `Array.prototype.flat()`, which is natively available in Node.js versions `>=12.0.0`. If you need to support older Node.js environments, consider polyfilling `Array.prototype.flat()` or using a different flattening utility.

---

## Contributing

We welcome contributions to `node-array-flatten`! If you have suggestions for improvements, bug reports, or want to contribute code, please feel free to:

1.  **Open an issue:** Describe the bug or feature request in detail.
2.  **Submit a pull request:**
    * Fork the repository.
    * Create a new branch for your feature or bug fix.
    * Write clear, concise code that adheres to the project's style.
    * Add or update tests to cover your changes.
    * Ensure all tests pass.
    * Submit your pull request, referencing any relevant issues.

---

## License

This project is licensed under the **MIT License**.

See the `LICENSE` file for more details.

---
_Source: https://npm.io/package/node-array-flatten · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._