Narcoleptic Pony Machine

    @antoniovdlc/sort
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.3 • Public • Published

    sort

    version issues downloads license

    Custom compare functions for sorting arrays.

    Installation

    This package is distributed via npm:

    npm install @antoniovdlc/sort
    

    Motivation

    Sorting arrays is a common operation in JavaScript, so this library provides some common custom compare functions to have a more declarative way of sorting arrays.

    Usage

    You can use this library either as an ES module or a CommonJS package:

    import { alphabetically, chronologically, numerically } from "@antoniovdlc/sort";

    - or -

    const { alphabetically, chronologically, numerically } = require("@antoniovdlc/sort");

    Examples

    All compare functions can be used out of the box for sorting as follows:

    import { numerically } from "@antoniovdlc/sort";
    
    const arr = [1, 2, 2, 23, 30, 4];
    arr.sort(numerically); // [1, 2, 2, 4, 23, 30]

    By default, sorting is doing in an ascending fashion. All compare functions also provide utility fields for descending sorting as well as an explicit ascending sort.

    import { numerically } from "@antoniovdlc/sort";
    
    const arr = [1, 2, 2, 23, 30, 4];
    arr.sort(numerically.asc); // [1, 2, 2, 4, 23, 30]
    import { numerically } from "@antoniovdlc/sort";
    
    const arr = [1, 2, 2, 23, 30, 4];
    arr.sort(numerically.desc); // [30, 23, 4, 2, 2, 1]

    Finally, all compare functions provide a .by("key") function which allows to sort arrays of objects by nested fields:

    const arr = [
      { name: "Bob", age: 23 },
      { name: "Alice", age: 32 },
      { name: "Tom", age: 60 },
      { name: "Candice", age: 45 },
    ];
    arr.sort(numerically.by("age"));
    /*
    [
      { name: "Bob", age: 23 },
      { name: "Alice", age: 32 },
      { name: "Candice", age: 45 },
      { name: "Tom", age: 60 },
    ]
    */

    The same .asc and .desc functions can be used for sorting arrays of objects:

    const arr = [
      { name: "Bob", age: 23 },
      { name: "Alice", age: 32 },
      { name: "Tom", age: 60 },
      { name: "Candice", age: 45 },
    ];
    arr.sort(numerically.by("age").desc);
    /*
    [
      { name: "Tom", age: 60 },
      { name: "Candice", age: 45 },
      { name: "Alice", age: 32 },
      { name: "Bob", age: 23 },
    ]
    */

    Compare functions

    Here is a list of provided compare functions:

    alphabetically

    Sorts an array in alphabetical (string) order. Case sensitive.

    alphabeticallyBase

    Sorts an array in alphabetical (string) order. Case insensitive.

    chronologically

    Sorts an array in chronological (date) order.

    numerically

    Sorts an array in numerical (number) order.

    Creating custom sorting functions

    You can create your own sorting functions by using the createCompareFunction() function:

    import { createCompareFunction } from "@antoniovdlc/sort";
    
    const alphabeticallyLocale = createCompareFunction(String, (a, b) => a.localeCompare(b));
    
    const arr = [
      { name: "Bob", age: 23 },
      { name: "Alice", age: 32 },
      { name: "Tom", age: 60 },
      { name: "Candice", age: 45 },
    ];
    arr.sort(alphabeticallyLocale.by("name").desc);

    Out of the box, your custom sorting functions have the same attributes and methods as the default sorting functions (such as .desc or .by())!

    Combining sorting functions

    You can also combine multiple sorting functions.

    Let's say that for example, you need to sort an array of users first by name, and then by age (descending). You can achieve that as follows:

    const arr = [
      { name: "Bob", age: 23 },
      { name: "Alice", age: 32 },
      { name: "Tom", age: 60 },
      { name: "Candice", age: 45 },
      { name: "Alice", age: 28 },
    ];
    arr.sort(combine([alphabetically.by("name"), numerically.by("age").desc]));
    /*
    [
      { name: "Alice", age: 32 },
      { name: "Alice", age: 28 },
      { name: "Bob", age: 23 },
      { name: "Candice", age: 45 },
      { name: "Tom", age: 60 },
    ]
    */

    License

    MIT

    Install

    npm i @antoniovdlc/sort

    DownloadsWeekly Downloads

    2

    Version

    1.2.3

    License

    MIT

    Unpacked Size

    11.4 kB

    Total Files

    8

    Last publish

    Collaborators

    • antoniovdlc