{"id":13328,"library":"index-array-by","title":"Array Indexing Utility","description":"index-array-by is a lightweight utility function, currently at version 1.4.2, designed for efficiently indexing JavaScript arrays of objects based on various criteria. It enables developers to transform a flat list into a nested object or array structure. Key differentiators include its flexibility in defining index keys, supporting string property names, an array of property names for hierarchical indexing, or custom accessor functions for complex key generation. The library also provides robust handling for duplicate keys, allowing the user to specify whether each index key should map to a single item (potentially overwriting duplicates if not unique) or an array of all matching items (the default behavior). Furthermore, it supports custom transformation functions for reducing multiple items into a single value, and an optional parameter to flatten the output into an array of { keys, vals } objects. It is actively maintained, shipping with TypeScript types to enhance developer experience and provide strong type checking in modern JavaScript environments.","status":"active","version":"1.4.2","language":"javascript","source_language":"en","source_url":"https://github.com/vasturiano/index-array-by","tags":["javascript","index","array","helper","typescript"],"install":[{"cmd":"npm install index-array-by","lang":"bash","label":"npm"},{"cmd":"yarn add index-array-by","lang":"bash","label":"yarn"},{"cmd":"pnpm add index-array-by","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"indexBy is a default export. TypeScript types are included, providing type-safety for arguments and return values.","wrong":"import { indexBy } from 'index-array-by';","symbol":"indexBy","correct":"import indexBy from 'index-array-by';"},{"note":"For CommonJS environments, 'require' can be used directly. The package is compatible with both CJS and ESM.","symbol":"indexBy (CommonJS)","correct":"const indexBy = require('index-array-by');"}],"quickstart":{"code":"import indexBy from 'index-array-by';\n\nconst people = [\n    { name: 'Mary', surname: 'Jane', age: 28 },\n    { name: 'John', surname: 'Smith', age: 24 },\n    { name: 'John', surname: 'Doe', age: 32 }\n];\n\n// Index the 'people' array by 'surname', ensuring each key maps to a single item\nconst indexedBySurname = indexBy(people, 'surname', false);\n\nconsole.log(indexedBySurname);\n/*\n// Expected Output:\n{\n  Doe: { name: 'John', surname: 'Doe', age: 32 },\n  Jane: { name: 'Mary', surname: 'Jane', age: 28 },\n  Smith: { name: 'John', surname: 'Smith', age: 24 }\n}\n*/","lang":"typescript","description":"Demonstrates indexing an array of objects by a string property, resulting in an object where each key points to a single item, preventing array wrapping."},"warnings":[{"fix":"Call indexBy with `indexBy(list, keyAccessor, false)` to ensure single-item values.","message":"The third parameter, 'multiItem', defaults to 'true'. If you expect keys to map to single items, you must explicitly set 'multiItem' to 'false' to avoid values being wrapped in arrays even for unique keys.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your keyAccessor generates unique keys or set 'multiItem' to 'true' (default) to collect all items into an array, or provide a custom reducer function for 'multiItem' to handle conflicts.","message":"When 'multiItem' is set to 'false', if multiple items share the same key, only the last item processed for that key will be retained, effectively overwriting previous entries.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure custom key accessor functions explicitly return string or symbol values for predictable object indexing.","message":"Using function-based key accessors that return non-string/non-symbol values can lead to unexpected object key coercions (e.g., numbers becoming strings, objects becoming '[object Object]').","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use `import indexBy from 'index-array-by';` for ESM or ensure proper CommonJS require if not in an ESM environment (e.g., `const indexBy = require('index-array-by');`).","cause":"Attempting to import the default export as a named export or using CommonJS require incorrectly in an ESM context.","error":"TypeError: indexBy is not a function"},{"fix":"Set the third argument 'multiItem' to 'false': `indexBy(yourArray, 'yourKey', false)`.","cause":"The 'multiItem' parameter defaults to 'true', always returning an array of items for each key, even if only one item matches.","error":"Output object has array values like { key: [item] } even when expecting single items."},{"fix":"If all items sharing a key should be kept, set 'multiItem' to 'true'. If a single item is desired, ensure keys are unique or provide a custom reducer function to 'multiItem' to define how multiple items are consolidated.","cause":"When 'multiItem' is set to 'false' (or a single-item reducer is used) and multiple input items resolve to the same key, subsequent items overwrite earlier ones.","error":"Items are unexpectedly missing from the indexed object, or only the last item with a duplicate key is present."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}