Collection Functions

A collection of utility functions for working with collections (arrays and objects).

keyBy

Creates an object composed of keys generated from the results of running each element of collection through the iteratee function. The corresponding value of each key is the last element responsible for generating the key.

Usage

// With an array of objects
const array = [
  { id: 'a1', name: 'John' },
  { id: 'b2', name: 'Jane' },
  { id: 'c3', name: 'Jack' }
];

// Using a function that returns the key
const keyedById = keyBy(array, item => item.id);
console.log(keyedById);
// {
//   a1: { id: 'a1', name: 'John' },
//   b2: { id: 'b2', name: 'Jane' },
//   c3: { id: 'c3', name: 'Jack' }
// }

// Using a property name string
const keyedByName = keyBy(array, 'name');
console.log(keyedByName);
// {
//   John: { id: 'a1', name: 'John' },
//   Jane: { id: 'b2', name: 'Jane' },
//   Jack: { id: 'c3', name: 'Jack' }
// }

Code

/**
 * Creates an object composed of keys generated from the results of running
 * each element of collection through the iteratee function.
 *
 * @param collection - The collection to iterate over
 * @param iteratee - The function or property name to transform keys
 * @returns The composed aggregate object
 */
function keyBy<T>(
  collection: T[],
  iteratee: ((item: T) => string | number) | string
): Record<string | number, T> {
  return collection.reduce((result, value) => {
    const key = typeof iteratee === 'function'
      ? iteratee(value)
      : (value as any)[iteratee];

    result[key] = value;
    return result;
  }, {} as Record<string | number, T>);
}

orderBy

Creates a new array of elements sorted by multiple iteratees and respective sort orders.

Usage

// With an array of objects
const users = [
  { user: 'fred', age: 48 },
  { user: 'barney', age: 34 },
  { user: 'fred', age: 40 },
  { user: 'barney', age: 36 }
];

// Sort by user in ascending order, then by age in descending order
const result = orderBy(users, ['user', 'age'], ['asc', 'desc']);
console.log(result);
// [
//   { user: 'barney', age: 36 },
//   { user: 'barney', age: 34 },
//   { user: 'fred', age: 48 },
//   { user: 'fred', age: 40 }
// ]

// Sort by age in ascending order (default)
const ageAsc = orderBy(users, ['age']);
console.log(ageAsc);
// [
//   { user: 'barney', age: 34 },
//   { user: 'barney', age: 36 },
//   { user: 'fred', age: 40 },
//   { user: 'fred', age: 48 }
// ]

// Using functions as iteratees
const funcResult = orderBy(users,
  [user => user.user, user => user.age],
  ['asc', 'desc']
);
console.log(funcResult);
// Same result as first example

Code

/**
 * Creates an array of elements, sorted in ascending or descending order by the results
 * of running each element through each iteratee. This method implements a stable sort.
 *
 * @param collection - The collection to iterate over
 * @param iteratees - The iteratees to sort by, either property names or functions
 * @param orders - The sort orders of iteratees, either 'asc' or 'desc'
 * @returns The new sorted array
 */
function orderBy<T>(
  collection: T[],
  iteratees: Array<((item: T) => any) | string> = [],
  orders: Array<'asc' | 'desc'> = []
): T[] {
  // Create a copy to avoid mutating the original array
  const result = [...collection];

  return result.sort((a, b) => {
    for (let i = 0; i < iteratees.length; i++) {
      const iteratee = iteratees[i];
      const order = orders[i] === 'desc' ? -1 : 1;

      // Get values for comparison
      const valueA = typeof iteratee === 'function'
        ? iteratee(a)
        : (a as any)[iteratee];
      const valueB = typeof iteratee === 'function'
        ? iteratee(b)
        : (b as any)[iteratee];

      if (valueA < valueB) return -1 * order;
      if (valueA > valueB) return 1 * order;
    }
    return 0;
  });
}