idx: Optional Property Traversal Utility

Common errors

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

  cause 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

  cause 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 '(...)'

  cause 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.

Warnings

• 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.
• 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`).
• gotcha The `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.
• breaking For `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.
• gotcha The 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.

Install

• npm install idx npm
• yarn add idx yarn
• pnpm add idx pnpm

Imports

• idx
  wrong:

  const idx = require('idx');

  correct:

  import idx from '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)
  wrong:

  plugins: ['idx']

  correct:

  plugins: [['babel-plugin-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).

Quickstart

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