# index-array-by

> A utility function to index arrays by any criteria

Latest version **1.4.2** (published 2024-07-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install index-array-by
pnpm add index-array-by
yarn add index-array-by
bun add index-array-by
```

## Health

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

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.2 |
| Published | 2024-07-19 |
| First published | 2018-02-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=12 |
| Dependencies | 0 |
| Unpacked size | 28.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Vasco Asturiano |
| Maintainers | vasturiano |
| Keywords | index, array, helper |

## Links

- npm: https://www.npmjs.com/package/index-array-by
- Repository: https://github.com/vasturiano/index-array-by
- Issues: https://github.com/vasturiano/index-array-by/issues
- npm.io page: https://npm.io/package/index-array-by

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 1.4.2 (latest) — 2024-07-19
- 1.4.1 — 2023-02-08
- 1.4.0 — 2023-02-06
- 1.3.3 — 2022-08-18
- 1.3.2 — 2022-02-09
- 1.3.1 — 2021-05-05
- 1.3.0 — 2020-03-17
- 1.2.9 — 2020-03-15
- 1.2.7 — 2019-09-29
- 1.2.6 — 2019-06-26
- 1.2.5 — 2019-06-26
- 1.2.4 — 2019-06-12
- 1.2.3 — 2019-03-28
- 1.2.2 — 2018-12-14
- 1.2.1 — 2018-12-14
- … 3 more at https://npm.io/package/index-array-by/versions

## README

index-array-by
==============

[![NPM package][npm-img]][npm-url]
[![Build Size][build-size-img]][build-size-url]
[![NPM Downloads][npm-downloads-img]][npm-downloads-url]

A utility function to index arrays by any criteria.

`indexBy(list, keyAccessors, multiItem = true)`

## Quick start

```js
import indexBy from 'index-array-by';
```
or using a *script* tag
```html
<script src="//unpkg.com/index-array-by"></script>
```

## Usage example

Given an array
```js
const people = [
    { name: 'Mary', surname: 'Jane', age: 28 },
    { name: 'John', surname: 'Smith', age: 24 },
    { name: 'John', surname: 'Doe', age: 32 }
];
```

Use `indexBy` to index it by a given attribute (string type `keyAccessor`) or any other custom criteria (function type `keyAccessor`). You can also pass an array of `keyAccessors` to retrieve a nested object recursively indexed by the multiple keys.

Use the third parameter (`multiItem`) to indicate whether each key should point to a single item (unadvised if the keys are not unique) or an array of multiple items (default behavior). 

```js
indexBy(people, 'surname', false);

// Result: 
{
 Doe: { name: 'John', age: 32 },
 Jane: { name: 'Mary', age: 28 },
 Smith: { name: 'John', age: 24 }
}
```

```js
indexBy(people, 'name', true);

// Result: 
{
  Mary: [ { surname: 'Jane', age: 28 } ],
  John: [
    { surname: 'Smith', age: 24 },
    { surname: 'Doe', age: 32 }
  ]
}
```

```js
indexBy(people, ({ name, surname }) => `${surname}, ${name}`, false);

// Result: 
{
 'Jane, Mary': { name: 'Mary', surname: 'Jane', age: 28 },
 'Smith, John': { name: 'John', surname: 'Smith', age: 24 },
 'Doe, John': { name: 'John', surname: 'Doe', age: 32 }
}
```

```js
indexBy(people, ['name', 'surname'], false));

// Result: 
{
 Mary: { Jane: { age: 28 }},
 John: { Smith: { age: 24 }, Doe: { age: 32 }}
}
```

```js
indexBy(people, ({ age }) => `${Math.floor(age / 10) * 10}s`, true);

// Result: 
{
  '20s': [
    { name: 'Mary', surname: 'Jane', age: 28 },
    { name: 'John', surname: 'Smith', age: 24 },
  ],
  '30s': [{ name: 'John', surname: 'Doe', age: 32 }]
}
```


The `multiItem` parameter also accepts a transformation function with the method to reduce multiple items into a single one. In this case, it's keeping only the max age.

```js
indexBy(people, 'name', items => Math.max(...items.map(item => item.age)));

// Result:

{
  John: 32,
  Mary: 28
}
```


A fourth optional parameter (`flattenKeys`) (default: `false`) allows you to receive a flat array structure instead of the default nested format, with each item formatted as `{ keys: [<ordered unique keys for the item>], vals: <single or multiple item> }`.

```js
indexBy(people, ['name', 'surname'], true, true));

// Result: 
[
  { keys: ['Mary', 'Jane'], vals: [{ age: 28 }] },
  { keys: ['John', 'Smith'], vals: [{ age: 24 }] },
  { keys: ['John', 'Doe'], vals: [{ age: 32 }] }
]
```


[npm-img]: https://img.shields.io/npm/v/index-array-by
[npm-url]: https://npmjs.org/package/index-array-by
[build-size-img]: https://img.shields.io/bundlephobia/minzip/index-array-by
[build-size-url]: https://bundlephobia.com/result?p=index-array-by
[npm-downloads-img]: https://img.shields.io/npm/dt/index-array-by
[npm-downloads-url]: https://www.npmtrends.com/index-array-by

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