sort-isostring

sort-isostring

A tiny (110B) and fast utility to sort 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()), 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
• ES Module: dist/index.mjs
• UMD: dist/index.min.js

Install

$ npm install --save sort-isostring

Usage

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().

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().

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 - An extremely quick, tiny (349B), and reusable date formatter.

License

MIT © Luke Edwards