{"id":13725429,"url":"https://github.com/lukeed/sort-isostring","last_synced_at":"2025-05-07T20:32:17.514Z","repository":{"id":57366287,"uuid":"245583504","full_name":"lukeed/sort-isostring","owner":"lukeed","description":"A tiny (110B) and fast utility to sort ISO 8601 Date strings","archived":true,"fork":false,"pushed_at":"2020-06-21T18:34:26.000Z","size":6,"stargazers_count":96,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-19T19:30:28.431Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukeed.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-07T06:51:44.000Z","updated_at":"2025-01-18T13:07:26.000Z","dependencies_parsed_at":"2022-08-23T19:01:07.602Z","dependency_job_id":null,"html_url":"https://github.com/lukeed/sort-isostring","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukeed%2Fsort-isostring","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukeed%2Fsort-isostring/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukeed%2Fsort-isostring/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukeed%2Fsort-isostring/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukeed","download_url":"https://codeload.github.com/lukeed/sort-isostring/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252953715,"owners_count":21830890,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:02:23.066Z","updated_at":"2025-05-07T20:32:17.129Z","avatar_url":"https://github.com/lukeed.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003e **ARCHIVED**\u003cbr\u003eUnless you're working with _very_ old browsers or Node.js runtimes, you do not need this library!\u003cbr\u003eA regular `arr.sort()` will work identically, and is now much faster.\u003cbr\u003eIf sorting by recency (latest first), please [beware of the gotchas](https://github.com/lukeed/sort-isostring/issues/1#issuecomment-647164151).\n\n# sort-isostring [![build status](https://badgen.net/github/status/lukeed/sort-isostring)](https://github.com/lukeed/sort-isostring/actions) [![codecov](https://badgen.now.sh/codecov/c/github/lukeed/sort-isostring)](https://codecov.io/gh/lukeed/sort-isostring)\n\n\u003e A tiny (110B) and [fast](#benchmarks) utility to sort [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) Date strings\n\nConverting strings to `Date` instances is expensive.\u003cbr\u003eUnless you _truly_ need a `Date` instance (or have one anyway), you're better off relying on string comparison logic.\u003cbr\u003eGone are wasteful days of parsing Dates just to determine a sort order.\n\nWhile 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.\n\n**Note:** Formats like `MM/DD/YYYY` and `DD-MM-YYYY` will yield incorrect results.\n\nThis module is delivered as:\n\n* **CommonJS**: [`dist/index.js`](https://unpkg.com/sort-isostring/dist/index.js)\n* **ES Module**: [`dist/index.mjs`](https://unpkg.com/sort-isostring/dist/index.mjs)\n* **UMD**: [`dist/index.min.js`](https://unpkg.com/sort-isostring/dist/index.min.js)\n\n## Install\n\n```\n$ npm install --save sort-isostring\n```\n\n\n## Usage\n\n```js\nimport sorter from 'sort-isostring';\n\nconst articles = [\n  { updated: '2019-12-01' },\n  { updated: '2020-03-07T05:51:07.746Z' },\n  { updated: '2018-01-07T05:50:41.107Z' },\n  { updated: '2020-02-21' },\n];\n\n// Sort: Oldest first\narticles.sort((x, y) =\u003e sorter(x.updated, y.updated));\nconsole.log(articles.map(x =\u003e x.updated));\n//=\u003e [ '2018-01-07T05:50:41.107Z', '2019-12-01',\n//=\u003e   '2020-02-21', '2020-03-07T05:51:07.746Z' ]\n\n\n// Sort: Newest first (aka, recency)\narticles.sort((x, y) =\u003e sorter(y.updated, x.updated));\nconsole.log(articles.map(x =\u003e x.updated));\n//=\u003e [ '2020-03-07T05:51:07.746Z', '2020-02-21',\n//=\u003e   '2019-12-01', '2018-01-07T05:50:41.107Z' ]\n```\n\n\n## API\n\n### sort(foo, bar)\nReturns: `Number`\n\nAs with any comparison function, when comparing `foo` and `bar`:\n\n* A `0` is returned if the values are equal\n* A `-1` is returned if `foo` is less than `bar`\n* A `1` is returned if `foo` is greater than `bar`\n\n\n#### foo\nType: `String`\n\nA Date string in ISO 8601 (or similar) format.\u003cbr\u003eSee [`Date.prototype.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString).\n\n\u003e **Important:** The string format must be identical to `bar`'s format.\n\n#### bar\nType: `String`\n\nA Date string in ISO 8601 (or similar) format.\u003cbr\u003eSee [`Date.prototype.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString).\n\n\u003e **Important:** The string format must be identical to `foo`'s format.\n\n\n## Benchmarks\n\n\u003e Running on Node.js v10.13.0\n\n```\nDate[] -\u003e Number                 x    322,876 ops/sec ±0.30% (96 runs sampled)\nstring[].map(Date) -\u003e Number     x    194,208 ops/sec ±0.77% (95 runs sampled)\nstring[] -\u003e sort-isostring       x  1,443,499 ops/sec ±1.22% (94 runs sampled)\n```\n\n## Related\n\n- [tinydate](https://github.com/lukeed/tinydate) - An extremely quick, tiny (349B), and reusable date formatter.\n\n\n## License\n\nMIT © [Luke Edwards](https://lukeed.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukeed%2Fsort-isostring","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukeed%2Fsort-isostring","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukeed%2Fsort-isostring/lists"}