# idx

> Utility function for traversing properties on objects and arrays.

Latest version **3.0.3** (published 2024-01-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install idx
pnpm add idx
yarn add idx
bun add idx
```

## Health

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

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.3 |
| Published | 2024-01-10 |
| First published | 2011-12-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 11.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1687 |
| Maintainers | zertosh, yungsters, fb |

## Links

- npm: https://www.npmjs.com/package/idx
- Repository: https://github.com/facebook/idx
- npm.io page: https://npm.io/package/idx

## Recent versions

- 3.0.3 (latest) — 2024-01-10
- 3.0.1 — 2023-07-07
- 3.0.0 — 2023-07-06
- 2.5.6 — 2019-05-06
- 2.5.5 — 2019-03-13
- 2.5.4 — 2019-02-21
- 2.5.3 — 2019-02-10
- 2.5.2 — 2018-11-27
- 2.5.1 — 2018-11-24
- 2.5.0 — 2018-11-16
- 2.4.0 — 2018-06-12
- 2.3.0 — 2018-04-13
- 2.2.0 — 2017-10-27
- 2.1.0 — 2017-10-09
- 1.5.0 — 2017-04-10
- … 6 more at https://npm.io/package/idx/versions

## README

# idx

**This module is deprecated and no longer maintained. Use [optional chaining](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Optional_chaining) instead.**

`idx` is a utility function for traversing properties on objects and arrays,
where intermediate properties may be null or undefined.

One notable difference between `idx` and optional chaining is what happens when
an intermediate property is null or undefined. With `idx`, the null or undefined
value is returned, whereas optional chaining would resolve to undefined.

## Install

```shell
$ npm install idx babel-plugin-idx
```

or

```shell
$ yarn add idx babel-plugin-idx
```

[Configure Babel](https://babeljs.io/docs/en/configuration) to include the
`babel-plugin-idx` Babel plugin.

```javascript
{
  plugins: [['babel-plugin-idx']];
}
```

This is necessary for `idx` to behave correctly
with minimal performance impact.

## Usage

Consider the following type for `props`:

```javascript
type User = {
  user: ?{
    name: string,
    friends: ?Array<User>,
  },
};
```

Getting to the friends of my first friend would resemble:

```javascript
props.user &&
  props.user.friends &&
  props.user.friends[0] &&
  props.user.friends[0].friends;
```

Instead, `idx` allows us to safely write:

```javascript
idx(props, _ => _.user.friends[0].friends);
```

The second argument must be a function that returns one or more nested member
expressions. Any other expression has undefined behavior.

## Static Typing

[Flow](https://flow.org/) and [TypeScript](https://www.typescriptlang.org/)
understand the `idx` idiom:

```javascript
// @flow

import idx from 'idx';

function getName(props: User): ?string {
  return idx(props, _ => _.user.name);
}
```

**If you use `idx@3+`,** you may need to add the following to your `.flowconfig`:

```
[options]
conditional_type=true
mapped_type=true
```

## Babel Plugin

The `idx` runtime function exists for the purpose of illustrating the expected
behavior and is not meant to be executed. The `idx` function requires the use of
a Babel plugin that replaces it with an implementation that does not depend on
details related to browser error messages.

This Babel plugin searches for requires or imports to the `idx` module and
replaces all its usages, so this code:

```javascript
import idx from 'idx';

function getFriends() {
  return idx(props, _ => _.user.friends[0].friends);
}
```

gets transformed to something like:

```javascript
function getFriends() {
  return props.user == null
    ? props.user
    : props.user.friends == null
    ? props.user.friends
    : props.user.friends[0] == null
    ? props.user.friends[0]
    : props.user.friends[0].friends;
}
```

Note that the original `import` gets also removed.

It's possible to customize the name of the import/require, so code that is not
directly requiring the `idx` npm package can also get transformed:

```javascript
{
  plugins: [
    [
      'babel-plugin-idx',
      {
        importName: './idx',
      },
    ],
  ];
}
```

## License

`idx` is [MIT licensed](./LICENSE).

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