# @flatten/array

> Fastest array flatten.

Latest version **1.1.8** (published 2019-04-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install @flatten/array
pnpm add @flatten/array
yarn add @flatten/array
bun add @flatten/array
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.8 |
| Published | 2019-04-29 |
| First published | 2017-04-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=4 |
| Dependencies | 0 |
| Unpacked size | 11.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Eli Doran |
| Maintainers | elidoran |
| Keywords | flatten, flatten array, array flatten, array, fast, fastest, best |

## Links

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

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 1.1.8 (latest) — 2019-04-29
- 1.1.7 — 2018-07-15
- 1.1.6 — 2018-07-15
- 1.1.5 — 2018-07-15
- 1.1.4 — 2018-02-05
- 1.1.3 — 2017-06-01
- 1.1.2 — 2017-06-01
- 1.1.1 — 2017-04-30
- 1.1.0 — 2017-04-30
- 1.0.1 — 2017-04-23
- 1.0.0 — 2017-04-23
- 0.0.0 — 2017-04-23

## README

# @flatten/array
[![Build Status](https://travis-ci.org/elidoran/flatten-array.svg?branch=master)](https://travis-ci.org/elidoran/flatten-array)
[![npm version](https://badge.fury.io/js/%40flatten%2Farray.svg)](http://badge.fury.io/js/%40flatten%2Farray)
[![Coverage Status](https://coveralls.io/repos/github/elidoran/flatten-array/badge.svg?branch=master)](https://coveralls.io/github/elidoran/flatten-array?branch=master)

Fastest array flatten.

Fastest implementation compared to several published packages and many unpublished variations.

The outermost array (the one provided to `flatten()`) is mutated. If you want to preserve the outermost array as well (inner arrays are always preserved) then wrap it in an array when supplying it: `flatten([array])`. Then the new array is the one which will be changed. And, the flatten operation will still be far faster than the other implementations.

For this repo, run `npm run perf` to compare the performance of this implementation to:

1. [arr-flatten](https://www.npmjs.com/package/arr-flatten)
2. [array-flatten](https://www.npmjs.com/package/array-flatten)
3. [compute-flatten](https://www.npmjs.com/package/compute-flatten)
4. [flatten-array](https://www.npmjs.com/package/flatten-array)
5. [flatten](https://www.npmjs.com/package/flatten)
6. [just-flatten-it](https://www.npmjs.com/package/just-flatten-it)
7. [reduce-flatten](https://www.npmjs.com/package/reduce-flatten).
8. [array_flatten](https://www.npmjs.com/package/array_flatten).
9. [npm-array-flatten](https://www.npmjs.com/package/npm-array-flatten).

See screenshot of [performance results](#screenshot) below.

Note, on a Mac I use the `renice` command to give the performance testing process high priority before answering the "run?" prompt.


## Install

```sh
npm install --save @flatten/array
```


## Usage

```javascript
var flatten = require('@flatten/array')

console.log(flatten([1, [2, 3], [4, [5, [6, 7]]]]))
// [ 1, 2, 3, 4, 5, 6, 7 ]

// NOTE: it's an in-place change to the array supplied.
var array = [ 1, [2, 3], 4, [5, [6, [7], 8], 9], 10 ]
flatten(array)
// array = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
// no need to assign array to it.
// but, you can, if you want to because it returns it
// to allow inline use.

// want to preserve your array? wrap it:
var dontChangeThisArray = getSomeArray()
// wrap it in an array when passing it.
// this is still much faster than other implementations.
flatten( [ dontChangeThisArray ] )
```


## Don't Change My Array!

No problem. Wrap your array and you're all set.

And, it's still faster than the other implementations.

```javascript
array = getSomeArray()
flatten( [ array ] )
// NOTE: extra spaces added for emphasis
```


## Performance

### **tl;dr** This is the fastest flatten implementation.

An in-place flatten on the top-most array is significantly faster than producing a new array with the flattened results. Run this project's performance test to see it compared to the implementations listed above.

Also, use [my fork](https://github.com/elidoran/array-flatten/tree/add-more/benchmark/code/flatten) of the `array-flatten` project to compare this implementation, called `inplace2.js` there, against many other implementations.

Normally it's an anti-pattern to alter a provided array unless it is the specific intent (such as a sort utility). In this case, it is the specific intent, the fastest implementation, and the common use pattern.

The third reason, "common use pattern", means it's common to create a new array which contains many other things which may, or may not, be arrays. Then, that top-most array is provided to `@flatten/array`. So, it's a brand new array created to contain the results and is therefore a perfect candidate to mutate to hold the final results.

For example:

```javascript
buildSomething([ // top-most array is a great target
  // all these may or may not provide arrays
  require('some-plugin'),
  require('./local-addons'),
  [], // they can return empty arrays, too
  [ 'something', 'defined', 'here' ]
  makeSomeMore()
])
```


### Screenshot

Performance results screenshot shows this implementation is significantly faster than the others:

![Show performance comparison with various inputs for this implementation, array-flatten, and flatten-array.](https://raw.githubusercontent.com/elidoran/flatten-array/master/docs/performance.png)


## [MIT License](LICENSE)

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