sort-by-property

Type-safe array sorting method with support for deeply nested properties and Typescript autocompletion.

blogPosts.sort(sortByProperty('author.name', 'asc'));

Features

Type-safety and Typescript autocompletion on the properties you try to sort
Define nested property to sort on using a path string like: "author.name"
Supports sorting by string, number, boolean, Date, Symbol and BigInt values
Use a specific locale when sorting by string
Handles null and undefined values gracefully by moving the object to the end of the array
Small file size, only 0.6kb gzipped
High performance, up to 3 times faster than lodash orderBy and sortBy *

Try it out: https://codesandbox.io/s/sort-by-property-example-hin358

Requirements

Requires Typescript 4.1+ because of the internal use of template literals for the autocompletion.

Installation

Install with your favorite package manager:

npm install sort-by-property

yarn add sort-by-property

Usage

// For an array of objects
import { sortByProperty } from 'sort-by-property';

// For one-dimensional arrays
import { sortBy } from 'sort-by-property';

Example: Sorting an array of objects

import { sortByProperty } from 'sort-by-property';

interface BlogPost {
  id: number;
  title: string;
  author: {
    id: number;
    name: string;
  };
}

const blogPosts: BlogPost[] = [
  {
    id: 1,
    title: 'Never gonna run around and desert you',
    author: {
      id: 10,
      name: 'Joe',
    },
  },
  {
    id: 2,
    title: 'Never gonna let you down',
    author: {
      id: 20,
      name: 'Ben',
    },
  },
  {
    id: 3,
    title: 'Never gonna give you up',
    author: {
      id: 30,
      name: 'Alice',
    },
  },
];

// Sort the blog posts by author name
blogPosts.sort(sortByProperty('author.name', 'asc'));

// If you need to use a custom locale for sorting strings, you can do
blogPosts.sort(sortByProperty('author.name', 'asc', {locale: 'nb-no'}))

Will sort the array ascending by author.name:

[
  { id: 3, title: 'Never gonna give you up', author: { id: 30, name: 'Alice' } },
  { id: 2, title: 'Never gonna let you down', author: { id: 20, name: 'Ben' } },
  { id: 1, title: 'Never gonna run around and desert you', author: { id: 10, name: 'Joe' } },
];

Will show a type error when you try to sort on properties that do not exist:

Will show an autocomplete of the available properties to sort on:

Example: Sorting one-dimensional arrays

This package exports 2 methods. Use sortBy to sort one-dimensional arrays. This sorting method supports all the same types as sortByProperty.

import { sortBy } from 'sort-by-property';

const array = ['c', 'b', 'a'];

array.sort(sortBy('asc'));

// Result: ['a', 'b', 'c']

_{* on an array with 10 million items: ~450ms vs ~1350ms. See the /src/examples directory.}