lodash.keyby

The lodash method keyBy exported as a standalone module. Creates an object composed of keys generated from the results of running each element of a collection through an iteratee function. The corresponding value of each key is the last element responsible for generating the key.

Package Information

• Package Name: lodash.keyby
• Package Type: npm
• Language: JavaScript
• Installation: npm install lodash.keyby

Core Imports

var keyBy = require('lodash.keyby');

For ES modules (if supported by bundler):

import keyBy from 'lodash.keyby';

Basic Usage

var keyBy = require('lodash.keyby');

var array = [
  { 'dir': 'left', 'code': 97 },
  { 'dir': 'right', 'code': 100 }
];

// Using function iteratee
keyBy(array, function(o) {
  return String.fromCharCode(o.code);
});
// => { 'a': { 'dir': 'left', 'code': 97 }, 'd': { 'dir': 'right', 'code': 100 } }

// Using property string iteratee
keyBy(array, 'dir');
// => { 'left': { 'dir': 'left', 'code': 97 }, 'right': { 'dir': 'right', 'code': 100 } }

Capabilities

Object Key Generation

Creates an object where keys are generated from running each element through an iteratee function and values are the elements themselves. When multiple elements generate the same key, the last element wins.

/**
 * Creates an object composed of keys generated from the results of running
 * each element of `collection` through `iteratee`. The corresponding value
 * of each key is the last element responsible for generating the key.
 * 
 * @param {Array|Object} collection The collection to iterate over.
 * @param {Function|Object|string} [iteratee=_.identity] The iteratee to transform keys.
 * @returns {Object} Returns the composed aggregate object.
 */
function keyBy(collection, iteratee);

Parameters:

• collection (Array|Object): The collection to iterate over. Can be an array of items or an object with enumerable properties.
• iteratee (Function|Object|string, optional): The iteratee to transform keys. Defaults to identity function if not provided.

Returns:

• Object: The composed aggregate object where keys are generated by the iteratee and values are the original elements.

Iteratee Types:

1. Function: Custom key generation function that receives the value and returns the key.
2. String: Property path to use as the key (supports nested properties with dot notation).
3. Number: Array index for arrays of arrays.
4. Object: Partial object for property matching (uses lodash's matches functionality).
5. Undefined/null: Uses identity function (element itself becomes the key).

Usage Examples:

Function Iteratee:

var users = [
  { 'name': 'barney', 'age': 36 },
  { 'name': 'fred', 'age': 40 }
];

keyBy(users, function(user) {
  return user.name.charAt(0);
});
// => { 'b': { 'name': 'barney', 'age': 36 }, 'f': { 'name': 'fred', 'age': 40 } }

String Property Iteratee:

keyBy(users, 'name');
// => { 'barney': { 'name': 'barney', 'age': 36 }, 'fred': { 'name': 'fred', 'age': 40 } }

Numeric Index Iteratee (Arrays of Arrays):

var pairs = [[1, 'a'], [2, 'b'], [1, 'c']];
keyBy(pairs, 0);
// => { '1': [1, 'c'], '2': [2, 'b'] }

keyBy(pairs, 1);
// => { 'a': [1, 'a'], 'b': [2, 'b'], 'c': [1, 'c'] }

Object Collections:

var scores = { 'math': 95, 'english': 88, 'science': 92 };
keyBy(scores, function(score) {
  return score >= 90 ? 'excellent' : 'good';
});
// => { 'excellent': 92, 'good': 88 }

Handling Object.prototype Properties:

// Safely handles built-in properties
keyBy([6.1, 4.2, 6.3], function(n) {
  return Math.floor(n) > 4 ? 'hasOwnProperty' : 'constructor';
});
// => { 'hasOwnProperty': 6.3, 'constructor': 4.2 }

Key Collision Behavior:

var data = [
  { id: 1, category: 'A' },
  { id: 2, category: 'B' },
  { id: 3, category: 'A' }  // This will overwrite first element
];

keyBy(data, 'category');
// => { 'A': { id: 3, category: 'A' }, 'B': { id: 2, category: 'B' } }

Edge Cases:

• Empty Collections: Returns empty object {}
• Null/Undefined Values: Safely handled, uses string conversion for keys
• Key Collisions: Last element with duplicate key wins
• Non-enumerable Properties: Only enumerable properties are processed for object collections
• Built-in Property Names: Safely handles property names like 'constructor', 'hasOwnProperty', 'proto'

Compatibility:

• Node.js: All versions
• Browsers: All modern browsers (uses ES5 features)
• TypeScript: Type definitions available via @types/lodash.keyby
• Bundle Size: Lightweight standalone module optimized for tree-shaking