# sort-by-property

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

Latest version **1.3.0** (published 2023-04-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install sort-by-property
pnpm add sort-by-property
yarn add sort-by-property
bun add sort-by-property
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.0 |
| Published | 2023-04-18 |
| First published | 2022-11-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 28.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Jordy van den Aardweg |
| Maintainers | jvandenaardweg |
| Keywords | typescript, sorting, array, sort, sortby, javascript, order, orderby, typed, typesafe |

## Links

- npm: https://www.npmjs.com/package/sort-by-property
- Repository: https://github.com/jvandenaardweg/sort-by-property
- Homepage: https://github.com/jvandenaardweg/sort-by-property#readme
- Issues: https://github.com/jvandenaardweg/sort-by-property/issues
- npm.io page: https://npm.io/package/sort-by-property

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.3.0 (latest) — 2023-04-18
- 1.2.4 — 2023-01-02
- 1.2.3 — 2022-12-16
- 1.2.2 — 2022-11-28
- 1.2.1 — 2022-11-16
- 1.2.0 — 2022-11-16
- 1.1.0 — 2022-11-16
- 1.0.5 — 2022-11-15
- 1.0.4 — 2022-11-14
- 1.0.3 — 2022-11-14
- 1.0.2 — 2022-11-14
- 1.0.1 — 2022-11-14
- 1.0.0 — 2022-11-14
- 0.6.0 — 2022-11-11
- 0.5.1 — 2022-11-11
- … 11 more at https://npm.io/package/sort-by-property/versions

## README

# sort-by-property [![npm version](https://badge.fury.io/js/sort-by-property.svg)](https://badge.fury.io/js/sort-by-property) [![mit license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jvandenaardweg/sort-by-property/blob/main/LICENSE)

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

```typescript
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
- 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](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-1.html) for the autocompletion.

## Installation

Install with your favorite package manager:

```bash
npm install sort-by-property
```

or

```bash
yarn add sort-by-property
```

## Usage

```typescript
// 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

```typescript
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`:

```typescript
[
  { 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:

![type-error-example](https://github.com/jvandenaardweg/typed-sort-by/blob/main/src/examples/type-error-example.png?raw=true)

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

![autocomplete](https://github.com/jvandenaardweg/typed-sort-by/blob/main/src/examples/autocomplete.png?raw=true)

## 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`.

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

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

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

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

<sub>\* on an array with 10 million items: ~450ms vs ~1350ms. See the /src/examples directory.</sub>

---
_Source: https://npm.io/package/sort-by-property · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._