or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-lodash-sortby

The modern build of lodash's sortBy function for creating sorted arrays by iteratee results.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lodash.sortby@3.1.x

To install, run

npx @tessl/cli install tessl/npm-lodash-sortby@3.1.0

index.mddocs/

lodash.sortby

The modern build of lodash's sortBy function exported as a standalone module. This package provides a stable sorting utility that creates arrays of elements sorted in ascending order by the results of running each element through an iteratee function. It supports various callback styles including property shortcuts, matches callbacks, and matchesProperty callbacks.

Package Information

  • Package Name: lodash.sortby
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install lodash.sortby
  • Dependencies: This module depends on several internal lodash modules for optimal performance and reusability

Core Imports

var sortBy = require('lodash.sortby');

In modern environments with ES module interop:

import sortBy from 'lodash.sortby';

Basic Usage

var sortBy = require('lodash.sortby');

// Sort by function iteratee
var users = [
  { 'user': 'fred',   'age': 48 },
  { 'user': 'barney', 'age': 36 },
  { 'user': 'fred',   'age': 40 },
  { 'user': 'barney', 'age': 34 }
];

// Sort by age
var result = sortBy(users, function(o) { return o.age; });
// => [{ 'user': 'barney', 'age': 34 }, { 'user': 'barney', 'age': 36 }, { 'user': 'fred', 'age': 40 }, { 'user': 'fred', 'age': 48 }]

// Sort by property shorthand
var result = sortBy(users, 'age');
// => [{ 'user': 'barney', 'age': 34 }, { 'user': 'barney', 'age': 36 }, { 'user': 'fred', 'age': 40 }, { 'user': 'fred', 'age': 48 }]

Capabilities

Array Sorting

Creates an array of elements sorted in ascending order by the results of running each element through an iteratee function. Performs stable sorting that preserves the original order of equal elements.

/**
 * Creates an array of elements, sorted in ascending order by the results of
 * running each element in a collection through `iteratee`. This method performs
 * a stable sort, that is, it preserves the original sort order of equal elements.
 * The `iteratee` is bound to `thisArg` and invoked with three arguments:
 * (value, index|key, collection).
 *
 * @param {Array|Object|string} collection The collection to iterate over.
 * @param {Function|Object|string} [iteratee=_.identity] The function invoked per iteration.
 * @param {*} [thisArg] The `this` binding of `iteratee`.
 * @returns {Array} Returns the new sorted array.
 */
function sortBy(collection, iteratee, thisArg);

Parameters:

  • collection (Array|Object|string): The collection to iterate over. If null or undefined, returns empty array.
  • iteratee (Function|Object|string) [optional]: The function invoked per iteration. Defaults to identity function. Supports multiple callback styles:
    • Function: Custom function receiving (value, index|key, collection) arguments
    • String: Property name for property shorthand (e.g., 'age')
    • Object: Matches object for _.matches style callback
  • thisArg (*) [optional]: The this binding context for the iteratee function

Returns:

  • Array: A new sorted array containing all elements from the collection sorted in ascending order by the iteratee results

Iteratee Callback Styles:

  1. Function Callback:

    sortBy([1, 2, 3], function(n) { return Math.sin(n); });

  2. Property Shorthand:

    sortBy(users, 'user');  // sorts by 'user' property

  3. Matches Object:

    sortBy(users, { 'active': true });  // sorts by matching { 'active': true }

  4. MatchesProperty:

    sortBy(users, 'active', true);  // sorts by 'active' property matching true

Key Features:

  • Stable Sort: Preserves original order of equal elements. Elements that compare as equal maintain their relative position from the original collection.
  • Null-Safe: Handles null/undefined collections gracefully, returning empty array
  • Type-Flexible: Works with arrays, objects, and strings as input collections
  • Performance-Optimized: Uses Schwartzian transform (decorate-sort-undecorate) pattern internally

Usage Examples:

// Sort numbers by mathematical function
sortBy([1, 2, 3], function(n) {
  return Math.sin(n);
});
// => [3, 1, 2]

// Sort with thisArg binding
sortBy([1, 2, 3], function(n) {
  return this.sin(n);
}, Math);
// => [3, 1, 2]

// Sort objects by property
var users = [
  { 'user': 'fred' },
  { 'user': 'pebbles' },
  { 'user': 'barney' }
];

// Using property shorthand
sortBy(users, 'user');
// => [{ 'user': 'barney' }, { 'user': 'fred' }, { 'user': 'pebbles' }]

// Demonstrating stable sort behavior with equal elements
var items = [
  { name: 'apple', score: 5, id: 1 },
  { name: 'banana', score: 3, id: 2 },
  { name: 'cherry', score: 5, id: 3 },
  { name: 'date', score: 3, id: 4 }
];

// Equal scores maintain original order (stable sort)
sortBy(items, 'score');
// => [{ name: 'banana', score: 3, id: 2 }, { name: 'date', score: 3, id: 4 },
//     { name: 'apple', score: 5, id: 1 }, { name: 'cherry', score: 5, id: 3 }]

// Using property shorthand with lodash pluck pattern
var users = [
  { 'user': 'fred' },
  { 'user': 'pebbles' },
  { 'user': 'barney' }
];

// Extract sorted property values (requires additional lodash.pluck or map)
var sortedUsers = sortBy(users, 'user');
// => [{ 'user': 'barney' }, { 'user': 'fred' }, { 'user': 'pebbles' }]

// Empty/null collections
sortBy(null);      // => []
sortBy(undefined); // => []
sortBy([]);        // => []