forto-sorter/README.md

Fast and powerful array sorting. Sort by any property in any direction with easy to read syntax.

# forto-sorter

Fast easy to use and flexible sorting with TypeScript support.
For speed comparison of `forto-sorter` vs other popular sort libraries check [benchmark](#benchmark) section.
For list of all available features check [highlights](#highlights) section.

```javascript
  import { sort } from 'forto-sorter';

  // Sort flat arrays
  const ascSorted = sort([1,4,2]).asc(); // => [1, 2, 4]
  const descSorted = sort([1, 4, 2]).desc(); // => [4, 2, 1]

  // Sort users (array of objects) by firstName in descending order
  const sorted = sort(users).desc(u => u.firstName);

  // Sort users in ascending order by firstName and lastName
  const sorted = sort(users).asc([
    u => u.firstName,
    u => u.lastName
  ]);

  // Sort users ascending by firstName and descending by city
  const sorted = sort(users).by([
    { asc: u => u.firstName },
    { desc: u => u.address.city }
  ]);

  // Sort based on computed property
  const sorted = sort(repositories).desc(r => r.openIssues + r.closedIssues);

  // Sort using string for object key
  // Only available for root object properties
  const sorted = sort(users).asc('firstName');
```

Fore more examples check [unit tests](https://github.com/AkkiParekh007/Forto-sorter/blob/master/test/sort.spec.ts).

## Highlights

  * Sort flat arrays
  * Sort array of objects by one or more properties
  * Sort in multiple directions
  * [Natural sort](#natural-sorting--language-sensitive-sorting) support
  * Support for [custom sort](#custom-sorting) instances
  * Easy to read syntax
  * [Faster](#benchmark) than other popular sort alternatives
  * Undefined and null values are always sorted to bottom (with default comparer)
  * TypeScript support
  * Packed with features in small footprint with 0 dependencies (~ 850 bytes gzip)
  * Compatible with any JS environment as Node, Web, etc..

## In place sorting

By default `sort` does not mutate provided array it creates new "sorted" instance of array. `inPlaceSort` on other hand mutates provided array by sorting it without creating new array instance. Benefits of `inPlaceSort` is that it's slightly faster and more generous on memory as it's not creating new array instance every time sorting is done. Other than that there is no difference between using one or another.

```javascript
const { sort, inPlaceSort } = require('forto-sorter');

const array = [3, 1, 5];
const sorted = sort(array).asc();

// sorted => [1, 3, 5]
// array => [3, 1, 5]

inPlaceSort(array).asc();

// array => [1, 3, 5]
```

## Natural sorting / Language sensitive sorting

By default `forto-sorter` is not doing language sensitive sorting of strings.
e.g `'image-11.jpg'` will be sorted before `'image-2.jpg'` (in ascending sorting).
We can provide custom [Intl.Collator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator) comparer to forto-sorter for language sensitive sorting of strings.
Keep in mind that natural sort is slower then default sorting so recommendation is to use it
only when needed.

```javascript
  import { sort, createNewSortInstance } from 'forto-sorter';

  const testArr = ['image-2.jpg', 'image-11.jpg', 'image-3.jpg'];

  // By default forto-sorter is not doing natural sort
  sort(testArr).desc(); // => ['image-3.jpg', 'image-2.jpg', 'image-11.jpg']

  // We can use `by` sort to override default comparer
  // with the one that is doing language sensitive comparison
  sort(testArr).by({
    desc: true,
    comparer: new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' }).compare,
  }); // => ['image-11.jpg', 'image-3.jpg', 'image-2.jpg']

  // Or we can create new sort instance with language sensitive comparer.
  // Recommended if used in multiple places
  const naturalSort = createNewSortInstance({
    comparer: new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' }).compare,
  });

  naturalSort(testArr).asc(); // => ['image-2.jpg', 'image-3.jpg', 'image-11.jpg']
  naturalSort(testArr).desc(); // => ['image-11.jpg', 'image-3.jpg', 'image-2.jpg']
```

## Custom sorting

Fast sort can be tailored to fit any sorting need or use case by:
  * creating custom sorting instances
  * overriding default comparer in `by` sorter
  * custom handling in provided callback function
  * combination of any from above

For example we will sort `tags` by "custom" tag importance (e.g `vip` tag is of greater importance then `captain` tag).

```javascript
  import { sort, createNewSortInstance } from 'forto-sorter';

  const tags = ['influencer', 'unknown', 'vip', 'captain'];
  const tagsImportance = { // Domain specific tag importance
    vip: 3,
    influencer: 2,
    captain: 1,
  };

  // We can use power of computed prop to sort tags by domain specific importance
  const descTags = sort(tags).desc(tag => tagImportance[tag] || 0);
  // => ['vip', 'influencer', 'captain', 'unknown'];

  // Or we can create specialized tagSorter so we can reuse it in multiple places
  const tagSorter = createNewSortInstance({
    comparer: (a, b) => (tagImportance[a] || 0) - (tagImportance[b] || 0),
    inPlaceSorting: true, // default[false] => Check "In Place Sort" section for more info.
  });

  tagSorter(tags).asc(); // => ['unknown', 'captain', 'influencer', 'vip'];
  tagSorter(tags).desc(); // => ['vip', 'influencer', 'captain', 'unknown'];

  // Default sorter will sort tags by comparing string values not by their domain specific value
  const defaultSort = sort(tags).asc(); // => ['captain', 'influencer', 'unknown' 'vip']
```
## More examples

```javascript
  // Sorting values that are not sortable will return same value back
  sort(null).asc(); // => null
  sort(33).desc(); // => 33

  // By default forto-sorter sorts null and undefined values to the
  // bottom no matter if sorting is in asc or decs order.
  // If this is not intended behaviour you can check "Should create sort instance that sorts nil value to the top in desc order" test on how to override
  const addresses = [{ city: 'Split' }, { city: undefined }, { city: 'Zagreb'}];
  sort(addresses).asc(a => a.city); // => Split, Zagreb, undefined
  sort(addresses).desc(a => a.city); // => Zagreb, Split, undefined
```

## Benchmark

Five different benchmarks have been created to get better insight of how forto-sorter perform under different scenarios.
Each benchmark is run with different array sizes raging from small 100 items to large 100 000 items.

Every run of benchmark outputs different results but the results are constantly showing better scores compared to similar popular sorting libraries.

#### Benchmark scores

Benchmark has been run on:

  * 16 GB Ram
  * Intel® Core™ i5-4570 CPU @ 3.20GHz × 4
  * Ubuntu 16.04
  * Node 8.9.1

![benchmark results](https://github.com/AkkiParekh007/Forto-sorter/raw/main/benchmark.png)

#### Running benchmark

To run benchmark on your PC follow steps from below

1) git clone https://github.com/AkkiParekh007/Forto-sorter.git
2) cd forto-sorter/benchmark
3) npm install
4) npm start

In case you notice any irregularities in benchmark or you want to add sort library to benchmark score
please open issue [here](https://github.com/AkkiParekh007/Forto-sorter)