Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukeed/flattie
A tiny (203B) and fast utility to flatten an object with customizable glue
https://github.com/lukeed/flattie
Last synced: about 2 months ago
JSON representation
A tiny (203B) and fast utility to flatten an object with customizable glue
- Host: GitHub
- URL: https://github.com/lukeed/flattie
- Owner: lukeed
- License: mit
- Created: 2016-05-12T18:48:49.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-03-06T21:55:26.000Z (10 months ago)
- Last Synced: 2024-10-14T02:17:48.304Z (2 months ago)
- Language: JavaScript
- Homepage:
- Size: 44.9 KB
- Stars: 260
- Watchers: 4
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- Funding: .github/FUNDING.yml
- License: license
Awesome Lists containing this project
- awesome - lukeed/flattie - A tiny (203B) and fast utility to flatten an object with customizable glue (JavaScript)
README
# flattie [](https://github.com/lukeed/flattie/actions) [](https://codecov.io/gh/lukeed/flattie)
> A tiny (203B) and [fast](#benchmarks) utility to flatten an object with customizable glue
This module recursively squashes an Object/Array. The output is a flat object – AKA, it has a single level of depth.
By default, the `.` character is used to glue/join layers' keys together. This is customizable.
Finally, by default, any keys with nullish values (`null` and `undefined`) are **not** included in the return object.
## Install
```
$ npm install --save flattie
```
## Usage
```js
import { flattie } from 'flattie';
flattie({
a: 'hi',
b: {
a: null,
b: ['foo', '', null, 'bar'],
d: 'hello',
e: {
a: 'yo',
b: undefined,
c: 'sup',
d: 0,
f: [
{ foo: 123, bar: 123 },
{ foo: 465, bar: 456 },
]
}
},
c: 'world'
});
// {
// 'a': 'hi',
// 'b.b.0': 'foo',
// 'b.b.1': '',
// 'b.b.3': 'bar',
// 'b.d': 'hello',
// 'b.e.a': 'yo',
// 'b.e.c': 'sup',
// 'b.e.d': 0,
// 'b.e.f.0.foo': 123,
// 'b.e.f.0.bar': 123,
// 'b.e.f.1.foo': 465,
// 'b.e.f.1.bar': 456,
// 'c': 'world'
// }
```
> **Note:** `null` and `undefined` values are purged by default.
## API
### flattie(input, glue?, keepNullish?)
Returns: `Object`
Returns a new object with a single level of depth.
> **Important:** An object is always returned despite `input` type.
#### input
Type: `Object|Array`
The object to flatten.
#### glue
Type: `String`
Default: `.`
A string used to join parent key names to nested child key names.
```js
const foo = { bar: 123 };
flattie({ foo }); //=> { 'foo.bar': 123 }
flattie({ foo }, '???'); //=> { 'foo???bar': 123 }
```
#### keepNullish
Type: `Boolean`
Default: `false`
Whether or not `null` and `undefined` values should be kept.
```js
// Note: Applies to Objects too
const foo = ['hello', null, NaN, undefined, /*hole*/, 'world'];
flattie({ foo });
//=> {
//=> 'foo.0': 'hello',
//=> 'foo.2': NaN,
//=> 'foo.5': 'world'
//=> }
flattie({ foo }, '.', true);
//=> {
//=> 'foo.0': 'hello',
//=> 'foo.1': null,
//=> 'foo.2': NaN,
//=> 'foo.3': undefined,
//=> 'foo.4': undefined,
//=> 'foo.5': 'world'
//=> }
```
## Benchmarks
> Running on Node.js v10.13.0
```
Load Time:
flat 1.047ms
flatten-object 1.239ms
flat-obj 0.997ms
flattie 0.258ms
Validation:
✔ flat
✔ flatten-object
✔ flat-obj
✔ flattie
Benchmark:
flat x 186,487 ops/sec ±1.28% (86 runs sampled)
flatten-object x 199,476 ops/sec ±1.01% (93 runs sampled)
flat-obj x 393,574 ops/sec ±1.41% (95 runs sampled)
flattie x 909,734 ops/sec ±0.82% (93 runs sampled)
```
## Related
* [nestie](https://github.com/lukeed/nestie) – A tiny (242B) and fast utility to expand a flattened object
_This is `flattie`'s reverse / counterpart._
## License
MIT © [Luke Edwards](https://lukeed.com)