idx

library0.0.0jsnpmunverified

idx is a utility function designed for safely traversing deeply nested properties within JavaScript objects and arrays, where intermediate properties might be `null` or `undefined`. It provides a concise syntax for accessing values without throwing errors. The current stable version is 3.0.3. However, the `idx` package is officially deprecated and no longer maintained. Its primary use case has been superseded by the native JavaScript optional chaining operator (`?.`), introduced in ES2020. A key differentiator noted in its documentation is that `idx` returns the `null` or `undefined` intermediate value if encountered, whereas optional chaining resolves to `undefined`. This library also strictly requires a Babel plugin (`babel-plugin-idx`) for correct transformation and optimal performance, as the runtime function is illustrative and not meant for direct execution. The library does not follow a regular release cadence due to its deprecated status.

serialization

npm install idx

github ↗package ↗

INSTALL

IMPORT

SIG · IDX

idx

serializationjavascriptv0.0.0

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');

While a CJS `require` might technically work in some setups, `idx` is designed for transformation by a Babel plugin which expects ES module syntax for optimal behavior and removal of the import statement.

idx (type)

✓ import idx from 'idx'; // ... then use idx(props, _ => _.prop)

idx ships with TypeScript types. The type inference works directly with the `idx` import, allowing for safe access to potentially null/undefined properties. No separate type import is typically needed for the function itself.

idx (Babel config)

✓ plugins: [['babel-plugin-idx']]

✗ plugins: ['idx']

The Babel plugin is 'babel-plugin-idx', not 'idx'. It must be configured explicitly in your Babel configuration (e.g., .babelrc or babel.config.js).

This quickstart demonstrates the core functionality of `idx` for safely accessing deeply nested properties in objects and arrays, showcasing how it handles `null` or `undefined` intermediate values compared to native optional chaining. It defines sample types and then uses `idx` to extract values that might otherwise cause runtime errors.

import idx from 'idx'; type User = { id: string; name: string; friends?: Array<User | null | undefined>; }; type Props = { user?: User | null; }; const props: Props = { user: { id: '123', name: 'Alice', friends: [ { id: '456', name: 'Bob', friends: [{ id: '789', name: 'Charlie' }] }, null ] } }; // Safely get the name of the user const userName = idx(props, _ => _.user.name); console.log('User name:', userName); // Output: Alice // Safely get the name of the first friend's first friend const charlieName = idx(props, _ => _.user.friends[0].friends[0].name); console.log("Charlie's name:", charlieName); // Output: Charlie // Accessing a property that is null/undefined at an intermediate step const nonExistentFriendName = idx(props, _ => _.user.friends[1].name); console.log('Non-existent friend name:', nonExistentFriendName); // Output: null (idx returns the null/undefined value) // Compare with optional chaining behavior for an equivalent case const nonExistentFriendNameOptionalChaining = props.user?.friends?.[1]?.name; console.log('Non-existent friend name (optional chaining):', nonExistentFriendNameOptionalChaining); // Output: undefined const deeplyNested = idx(props, _ => _.user.friends[0].friends[0].name); console.log('Deeply nested:', deeplyNested); // Output: Charlie

Debug

Known issues

breaking`idx` is officially deprecated and no longer maintained. New projects should use native optional chaining (`?.`) instead. Existing projects are strongly advised to migrate to optional chaining.

fix

Refactor code to use JavaScript's native optional chaining operator (e.g., `props.user?.friends?.[0]?.friends?.[0]`) which provides similar safety and is natively supported without extra dependencies or build steps.

affects: >=1.0.0

gotcha`idx` relies on a Babel plugin (`babel-plugin-idx`) for correct and performant behavior. The runtime `idx` function is illustrative; without the plugin, `idx` will not function as expected or might lead to suboptimal performance/errors.

fix

Ensure `babel-plugin-idx` is installed (`npm install babel-plugin-idx`) and correctly configured in your Babel setup (e.g., `plugins: [['babel-plugin-idx']]` in `.babelrc`).

affects: >=1.0.0

gotchaThe `idx` utility returns the `null` or `undefined` value if an intermediate property is `null` or `undefined`. This differs from native optional chaining (`?.`) which consistently returns `undefined` in such cases.

fix

Be aware of this behavioral difference when migrating from `idx` to optional chaining or when mixing both in a codebase. Adjust logic where `null` vs `undefined` distinction is critical.

affects: >=1.0.0

breakingFor `idx@3+` users, if using Flow, specific configuration options (`conditional_type=true` and `mapped_type=true`) might be required in `.flowconfig` for correct static typing.

fix

Add `conditional_type=true` and `mapped_type=true` under the `[options]` section of your `.flowconfig` file.

affects: >=3.0.0

gotchaThe second argument to `idx` *must* be a function returning one or more nested member expressions. Any other expression within the callback (e.g., function calls, arithmetic operations) results in undefined behavior.

fix

Strictly adhere to the usage pattern `idx(obj, _ => _.prop1.prop2.prop3)`. If complex logic is needed, perform it outside the `idx` callback or after `idx` has returned a safe value.

affects: >=1.0.0

Errors

Common errors & fixes

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

The `babel-plugin-idx` plugin is either not installed, not configured, or incorrectly configured, leading to the runtime `idx` function being executed without transformation.

fix

Verify that `babel-plugin-idx` is installed (`npm install babel-plugin-idx`) and correctly added to your Babel configuration (e.g., `plugins: [['babel-plugin-idx']]`). Also ensure your files are being processed by Babel.

ReferenceError: idx is not defined

The `idx` import statement is missing or has been removed by a Babel plugin before the code is executed.

fix

Ensure `import idx from 'idx';` is present in your file. If using the Babel plugin, it will remove this import at compile time, but it must be present in source for the plugin to identify `idx` usages.

TS2345: Argument of type '(...)' is not assignable to parameter of type '(...)'

TypeScript type inference issues, possibly due to `idx` being deprecated or complex types that TypeScript struggles to narrow down without explicit assertions.

fix

Ensure `idx` types are correctly picked up. Consider adding explicit type assertions (`as Type | undefined`) if TypeScript is being overly strict, or, ideally, migrate to optional chaining for better native type inference.

Upgrade

Version history

0.0.0latest on npm

Audit

Dependencies

babel-plugin-idxrequiredRequired for idx to correctly transform code and provide its intended functionality. The runtime 'idx' function is illustrative and not meant to be executed directly without this plugin.

Agent activity

4 hits · last 30 days

node

Resources

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

packagehttps://www.npmjs.com/package/idx ↗