Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lukeed/sort-isostring
A tiny (110B) and fast utility to sort ISO 8601 Date strings
https://github.com/lukeed/sort-isostring
Last synced: about 2 months ago
JSON representation
A tiny (110B) and fast utility to sort ISO 8601 Date strings
- Host: GitHub
- URL: https://github.com/lukeed/sort-isostring
- Owner: lukeed
- License: mit
- Archived: true
- Created: 2020-03-07T06:51:44.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-06-21T18:34:26.000Z (about 4 years ago)
- Last Synced: 2024-07-11T14:38:10.665Z (2 months ago)
- Language: JavaScript
- Size: 5.86 KB
- Stars: 98
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
- awesome-list - sort-isostring
README
> **ARCHIVED**
Unless you're working with _very_ old browsers or Node.js runtimes, you do not need this library!
A regular `arr.sort()` will work identically, and is now much faster.
If sorting by recency (latest first), please [beware of the gotchas](https://github.com/lukeed/sort-isostring/issues/1#issuecomment-647164151).
# sort-isostring [](https://github.com/lukeed/sort-isostring/actions) [](https://codecov.io/gh/lukeed/sort-isostring)
> A tiny (110B) and [fast](#benchmarks) utility to sort [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) Date strings
Converting strings to `Date` instances is expensive.
Unless you _truly_ need a `Date` instance (or have one anyway), you're better off relying on string comparison logic.
Gone are wasteful days of parsing Dates just to determine a sort order.
While ISO 8601 stirngs are preferred (see [`Date.prototype.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)), all you _really_ need is a `YYYY-MM-DD` prefix for safe LTR character comparisons.
**Note:** Formats like `MM/DD/YYYY` and `DD-MM-YYYY` will yield incorrect results.
This module is delivered as:
* **CommonJS**: [`dist/index.js`](https://unpkg.com/sort-isostring/dist/index.js)
* **ES Module**: [`dist/index.mjs`](https://unpkg.com/sort-isostring/dist/index.mjs)
* **UMD**: [`dist/index.min.js`](https://unpkg.com/sort-isostring/dist/index.min.js)
## Install
```
$ npm install --save sort-isostring
```
## Usage
```js
import sorter from 'sort-isostring';
const articles = [
{ updated: '2019-12-01' },
{ updated: '2020-03-07T05:51:07.746Z' },
{ updated: '2018-01-07T05:50:41.107Z' },
{ updated: '2020-02-21' },
];
// Sort: Oldest first
articles.sort((x, y) => sorter(x.updated, y.updated));
console.log(articles.map(x => x.updated));
//=> [ '2018-01-07T05:50:41.107Z', '2019-12-01',
//=> '2020-02-21', '2020-03-07T05:51:07.746Z' ]
// Sort: Newest first (aka, recency)
articles.sort((x, y) => sorter(y.updated, x.updated));
console.log(articles.map(x => x.updated));
//=> [ '2020-03-07T05:51:07.746Z', '2020-02-21',
//=> '2019-12-01', '2018-01-07T05:50:41.107Z' ]
```
## API
### sort(foo, bar)
Returns: `Number`
As with any comparison function, when comparing `foo` and `bar`:
* A `0` is returned if the values are equal
* A `-1` is returned if `foo` is less than `bar`
* A `1` is returned if `foo` is greater than `bar`
#### foo
Type: `String`
A Date string in ISO 8601 (or similar) format.
See [`Date.prototype.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString).
> **Important:** The string format must be identical to `bar`'s format.
#### bar
Type: `String`
A Date string in ISO 8601 (or similar) format.
See [`Date.prototype.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString).
> **Important:** The string format must be identical to `foo`'s format.
## Benchmarks
> Running on Node.js v10.13.0
```
Date[] -> Number x 322,876 ops/sec ±0.30% (96 runs sampled)
string[].map(Date) -> Number x 194,208 ops/sec ±0.77% (95 runs sampled)
string[] -> sort-isostring x 1,443,499 ops/sec ±1.22% (94 runs sampled)
```
## Related
- [tinydate](https://github.com/lukeed/tinydate) - An extremely quick, tiny (349B), and reusable date formatter.
## License
MIT © [Luke Edwards](https://lukeed.com)