Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jvandenaardweg/sort-by-property
Type-safe array sorting method with support for deeply nested properties and Typescript autocompletion.
https://github.com/jvandenaardweg/sort-by-property
array array-manipulations array-methods array-sort array-sorting arrays browser javascript javascript-library javascript-tools json nodejs sort sortby sortbyvalue sorting typesafe typescript typescript-library typescript4
Last synced: 29 days ago
JSON representation
Type-safe array sorting method with support for deeply nested properties and Typescript autocompletion.
- Host: GitHub
- URL: https://github.com/jvandenaardweg/sort-by-property
- Owner: jvandenaardweg
- License: mit
- Created: 2022-11-08T10:45:28.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-12-01T08:30:58.000Z (12 months ago)
- Last Synced: 2024-10-03T12:42:58.924Z (about 2 months ago)
- Topics: array, array-manipulations, array-methods, array-sort, array-sorting, arrays, browser, javascript, javascript-library, javascript-tools, json, nodejs, sort, sortby, sortbyvalue, sorting, typesafe, typescript, typescript-library, typescript4
- Language: TypeScript
- Homepage:
- Size: 3.1 MB
- Stars: 4
- Watchers: 3
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# sort-by-property [](https://badge.fury.io/js/sort-by-property) [](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
- 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](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:
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`.
```typescript
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.