Registry / devops / babel-plugin-idx

babel-plugin-idx

library3.0.3jsnpmunverified

babel-plugin-idx is a Babel plugin designed to transform usages of the `idx` utility function into explicit null-checking code. The `idx` utility, now deprecated and unmaintained, was created by Facebook to safely access deeply nested properties on objects and arrays where intermediate properties might be `null` or `undefined`, preventing `TypeError` exceptions. The plugin effectively replaces calls like `idx(props, _ => _.user.friends[0].friends)` with verbose but safe conditional expressions, optimizing performance by removing the need for a runtime `idx` function. The current stable version is 3.0.3, but the module is no longer receiving updates. Its primary differentiator was providing safe property access similar to the now-standard optional chaining (`?.`) operator, though with a key difference: `idx` returns `null` or `undefined` for intermediate `null`/`undefined` values, while optional chaining consistently resolves to `undefined`. This plugin is essential for `idx` to function correctly and efficiently, as the `idx` runtime function is purely illustrative.

devops

npm install babel-plugin-idx

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-IDX

babel-plugin-idx

devopsjavascriptv3.0.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

idx

✓ import idx from 'idx';

✗ const idx = require('idx');

The Babel plugin transforms and removes this import statement, replacing `idx` calls with direct null checks, making the `idx` runtime module unnecessary after transformation.

Demonstrates how to use the `idx` function for safe, deeply nested property access on potentially null or undefined objects, including examples of its behavior with different input scenarios, assuming `babel-plugin-idx` is configured. It also highlights the type-safety provided by TypeScript.

import idx from 'idx'; // Define a type for demonstration, often in a .d.ts or .ts file type User = { user: { name: string, friends?: Array<User>, // Make friends optional } | null | undefined, // Make user itself nullable/undefined }; const props: User = { user: { name: 'Alice', friends: [ { user: { name: 'Bob', friends: [{ user: { name: 'Charlie' } }] } }, { user: { name: 'David' } } ] } }; const propsWithNullUser: User = { user: null }; const propsWithUndefinedFriends: User = { user: { name: 'Eve', friends: undefined } }; // To run this code, ensure 'babel-plugin-idx' is configured in your Babel setup: // // babel.config.js // module.exports = { // plugins: [['babel-plugin-idx']], // }; // Accessing a deeply nested property const charlieName = idx(props, _ => _.user.friends[0].friends[0].user.name); console.log('Charlie\'s name:', charlieName); // Expected output: Charlie // Accessing a non-existent intermediate property const nonExistentFriendOfFriend = idx(props, _ => _.user.friends[1].friends[0].user.name); console.log('Non-existent friend of friend:', nonExistentFriendOfFriend); // Expected output: undefined // Accessing property on a null intermediate const nameFromNullUser = idx(propsWithNullUser, _ => _.user.name); console.log('Name from null user:', nameFromNullUser); // Expected output: null // Accessing property on an undefined intermediate const nameFromUndefinedFriends = idx(propsWithUndefinedFriends, _ => _.user.friends[0]?.user.name); console.log('Name from undefined friends:', nameFromUndefinedFriends); // Expected output: undefined

Debug

Known issues

deprecatedThis module is officially deprecated and no longer maintained. Developers are strongly advised to migrate to native JavaScript optional chaining (`?.`) syntax, which offers similar functionality and is standardized and widely supported.

fix

Refactor existing code to utilize ECMAScript optional chaining (e.g., `object?.property?.nestedProperty`). Ensure your Babel or TypeScript setup supports optional chaining (available natively in ES2020).

affects: >=3.0.0

breakingThere is a subtle behavioral difference between `idx` and optional chaining. `idx` returns `null` or `undefined` if an intermediate property is `null` or `undefined`, preserving the original value. Optional chaining, however, always resolves to `undefined` in such cases.

fix

When migrating from `idx` to optional chaining, carefully review code that relies on distinguishing between `null` and `undefined` for intermediate values. Adjust logic to explicitly handle `null` if necessary, as optional chaining will yield `undefined`.

affects: >=3.0.0

gotchaThe `idx` runtime function is illustrative and not meant for direct execution. The `babel-plugin-idx` is mandatory for correct behavior and performance, transforming `idx` calls into native null-checking. Without it, `idx` calls will execute the basic, unoptimized runtime function or fail if `idx` isn't imported correctly.

fix

Ensure `babel-plugin-idx` is installed (`npm install --save-dev babel-plugin-idx`) and correctly added to your Babel configuration (e.g., `plugins: [['babel-plugin-idx']]`).

affects: *

gotchaFlow users working with `idx@3+` may encounter type-checking issues unless specific options are enabled in their `.flowconfig`. The plugin documentation recommends adding `conditional_type=true` and `mapped_type=true`.

fix

If using Flow with `idx@3+`, update your `.flowconfig` to include:
```
[options]
conditional_type=true
mapped_type=true
```

affects: >=3.0.0

Errors

Common errors & fixes

ReferenceError: idx is not defined

The `babel-plugin-idx` is not installed or configured in your Babel setup, or Babel is not processing the file, preventing the `idx` import and function calls from being transformed into native JavaScript.

fix

Install the plugin: `npm install --save-dev babel-plugin-idx`. Then, add it to your Babel configuration (e.g., `babel.config.js` or `.babelrc`):
```javascript
{
  "plugins": ["babel-plugin-idx"]
}
```

TypeError: Cannot read properties of undefined (reading 'someProperty')

This error can occur if `idx` is used but the `babel-plugin-idx` is either not active, misconfigured, or not applied to the relevant source files. This leads to the runtime `idx` function executing without the necessary transformations, potentially failing where it expects transformed code.

fix

Verify that `babel-plugin-idx` is correctly installed and listed in your Babel configuration. Ensure that your build process is correctly applying Babel transformations to all relevant source files where `idx` is used.

Upgrade

Version history

3.0.3latest on npm

Audit

Dependencies

idxrequiredRuntime library providing the idx function, which this plugin transforms.

@babel/corerequiredCore Babel library required to run any Babel plugin.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/facebook/idx ↗

packagehttps://www.npmjs.com/package/babel-plugin-idx ↗