arrange

The arrange utility enables advanced multi-field sorting for arrays of objects. It allows you to specify multiple properties to sort by, each with its own independent sort direction (ascending or descending).

Implementation

View Source Code

import { compareBy } from '../function/compareBy';

/**
 * Arranges (sorts) an array of objects based on multiple selectors.
 *
 * @example
 * ```ts
 * const data = [
 *   { name: 'Alice', age: 30 },
 *   { name: 'Bob', age: 25 },
 *   { name: 'Charlie', age: 35 },
 *   { name: 'Alice', age: 25 },
 *   { name: 'Bob', age: 30 },
 *   { name: 'Charlie', age: 30 },
 * ].arrange(data, { name: 'asc', age: 'desc' }); // [ { name: 'Alice', age: 30 }, { name: 'Alice', age: 25 }, { name: 'Bob', age: 30 }, { name: 'Bob', age: 25 }, { name: 'Charlie', age: 35 }, { name: 'Charlie', age: 30 } ]
 * ```
 *
 * @param array - The array to sort.
 * @param selectors - An object where keys are the properties to sort by and values are 'asc' or 'desc'.
 * @returns A new sorted array.
 */
export const arrange = <T>(array: T[], selectors: Partial<Record<keyof T, 'asc' | 'desc'>>) => {
  return [...array].sort(compareBy(selectors));
};

Features

• Isomorphic: Works in both Browser and Node.js.
• Multi-Level Sorting: Primary sort, secondary sort, etc., in a single call.
• Declarative API: Define sort rules using a simple configuration object.
• Immutable: Returns a new sorted array, leaving the original untouched.

API

function arrange<T>(array: T[], selectors: Partial<Record<keyof T, 'asc' | 'desc'>>): T[];

Parameters

• array: The array of objects to sort.
• selectors: An object where keys are the property names and values are the sort directions ('asc' or 'desc'). The order of properties in the object determines the sort priority.

Returns

• A new sorted array.

Examples

Basic Multi-Field Sorting

import { arrange } from '@vielzeug/toolkit';

const users = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 30 },
];

// Sort by name (asc) then age (desc)
const sorted = arrange(users, { name: 'asc', age: 'desc' });
/*
[
  { name: 'Alice', age: 30 },
  { name: 'Alice', age: 25 },
  { name: 'Bob', age: 30 },
  { name: 'Bob', age: 25 }
]
*/

Complex Object Sorting

import { arrange } from '@vielzeug/toolkit';

const products = [
  { category: 'Fruit', price: 2.0 },
  { category: 'Meat', price: 5.0 },
  { category: 'Fruit', price: 1.5 },
  { category: 'Meat', price: 10.0 },
];

// Sort by category (desc) then price (asc)
arrange(products, { category: 'desc', price: 'asc' });
/*
[
  { category: 'Meat', price: 5.0 },
  { category: 'Meat', price: 10.0 },
  { category: 'Fruit', price: 1.5 },
  { category: 'Fruit', price: 2.0 }
]
*/

Implementation Notes

• Throws TypeError if the first argument is not an array.
• Stable sort: Elements that compare as equal will maintain their relative order.
• Internally leverages compareBy to generate a composite comparator.

See Also

• sort: Simple sorting by a single selector.
• compareBy: Generate a comparator for use with native sort.
• aggregate: Transform arrays into lookup maps.