{"id":26977516,"url":"https://github.com/jherax/array-sort-by","last_synced_at":"2025-07-18T16:32:36.938Z","repository":{"id":53335479,"uuid":"71516367","full_name":"jherax/array-sort-by","owner":"jherax","description":"Powerful mechanism to sort arrays or array of objects by one or more properties. You can also specify a custom comparer function.","archived":false,"fork":false,"pushed_at":"2018-09-19T14:50:48.000Z","size":260,"stargazers_count":39,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T12:35:35.071Z","etag":null,"topics":["accent","amd","arrange","array","asc","commonjs","compare","desc","javascript","objects","ordering","requirejs","sort","sort-criteria","umd-modules"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jherax.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":"2016-10-21T00:51:10.000Z","updated_at":"2024-01-12T06:50:25.000Z","dependencies_parsed_at":"2022-08-23T01:20:53.192Z","dependency_job_id":null,"html_url":"https://github.com/jherax/array-sort-by","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/jherax/array-sort-by","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jherax%2Farray-sort-by","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jherax%2Farray-sort-by/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jherax%2Farray-sort-by/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jherax%2Farray-sort-by/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jherax","download_url":"https://codeload.github.com/jherax/array-sort-by/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jherax%2Farray-sort-by/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265793525,"owners_count":23829176,"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":["accent","amd","arrange","array","asc","commonjs","compare","desc","javascript","objects","ordering","requirejs","sort","sort-criteria","umd-modules"],"created_at":"2025-04-03T12:27:53.969Z","updated_at":"2025-07-18T16:32:36.894Z","avatar_url":"https://github.com/jherax.png","language":"JavaScript","readme":"# Array sortBy\n\n\u003c!-- markdownlint-disable MD033 MD034 MD014 --\u003e\n\nPowerful mechanism to sort arrays or array of objects by one or more properties.\nYou can also specify a custom comparer function.\n\nBy default it has support for some accented characters\n(see [`mapAccents`](#mapaccents)).\n\n## Content\n\n1. [Getting started](#getting-started)\n1. [Including the library](#including-the-library)\n1. [Examples](#examples)\n\n## Getting started\n\nTo include this library into your package manager with `npm` or `yarn`\n\n```shell\n# with npm\n$ npm install array-sort-by\n\n# with yarn\n$ yarn add array-sort-by\n```\n\nThe `sortBy` function has the following signature:\n\n```javascript\n/**\n * @param  {Array} array: the list of elements to sort\n * @param  {Function} parser: transforms each item and specifies the sorting mode\n * @return {Array}\n */\nsortBy(array: Array) : Array\nsortBy(array: Array, parser: Function) : Array\n```\n\nIf the parameter `parser` is not provided, then the array is sorted using\nthe default implementation of `Array.prototype.sort()`.\n\nOtherwise, the parameter `parser` is a function that transforms each element\nbeing iterated and sets the sorting rules: _ascending_ or _descending_.\nHere you can specify the way of sorting by multiple properties.\n\nThe `parser` callback has the following signature:\n\n```javascript\n/**\n * @param  {Any} item: the element being iterated over the list\n * @param  {Number} index: the index of the element in the list\n * @return {Any}\n */\nparser(item: Any, index: Number) : Any\nparser(item: Any) : Any\n```\n\nSee examples in the section [Examples](#examples)\n\n### mapAccents\n\nA new static method `mapAccents` has been added to the `sortBy` function.\nThis method allows to register a map of accented characters in order to\nsort the string accordingly.\n\nSignature:\n\n```javascript\n/**\n * @param {String} accents: a string with accented characters\n * @param {String} replacements: a string with the replacement for each accent\n */\nsortBy.mapAccents(accents: String, replacements: String) : void\n```\n\n\u003e **Problem solved**: when you try to order strings with non ASCII characters\nlike this: `['é', 'a', 'ú', 'c']`, you will obtain strange results after sorting\nthe array: `['c', 'e', 'á', 'ú']`. That happens because by default the method\n`Array.prototype.sort()` does not work correctly with accented characters.\n\nBut the static method `mapAccents` comes to the rescue, because it has an\ninternal mapping with some accented characters and their replacements:\n\n```javascript\n// accents\n\"ÂâÀàÁáÄäÃãÅåÊêÈèÉéËëÎîÌìÍíÏïÔôÒòÓóÖöÕõÛûÙùÚúÜüÑñÝýÿ\",\n\"AaAaAaAaAaAaEeEeEeEeIiIiIiIiOoOoOoOoOoUuUuUuUuNnYyy\"\n// replacements\n```\n\nYou also may extend the accented characters and register a new set of special\ncharacters with their respective replacements:\n\n```javascript\n// register special characters\nsortBy.mapAccents(\n  'ª@$',\n  'aas',\n);\n\nconst arr = ['$impson', 'Cªl@bazä', 'M@ría', 'Cal@bªzA'];\nsortBy(arr);\n/**\n * expected:\n * [\"Cªl@bazä\", \"Cal@bªzA\", \"M@ría\", \"$impson\"]\n *\n * translated as:\n * [\"CALABAZA\", \"CALABAZA\", \"MARIA\", \"SIMPSON\"]\n */\n\nsortBy(arr, item =\u003e `DESC:${item}`);\n/**\n * expected:\n * [\"$impson\", \"M@ría\", \"Cal@bªzA\", \"Cªl@bazä\"]\n *\n * translated as:\n * [\"SIMPSON\", \"MARIA\", \"CALABAZA\", \"CALABAZA\"]\n */\n```\n\nIn the example above, after calling `sortBy.mapAccents()` we extended\nthe internal mapping, by adding the new accents and their replacements\nat the beginning of the mapping, honoring the user mapping first:\n\n```javascript\n// accents: added \"ª@$\"\n\"ª@$ÂâÀàÁáÄäÃãÅåÊêÈèÉéËëÎîÌìÍíÏïÔôÒòÓóÖöÕõÛûÙùÚúÜüÑñÝýÿ\"\n\"aasAaAaAaAaAaAaEeEeEeEeIiIiIiIiOoOoOoOoOoUuUuUuUuNnYyy\"\n// replacements\n```\n\n[\u0026#9751; Back to Index](#content)\n\n## Including the library\n\n`array-sort-by` can be included directly from a CDN in your site:\n\n```html\n\u003c!-- from unpkg.com --\u003e\n\u003cscript src=\"https://unpkg.com/array-sort-by/dist/sort-by.min.js\"\u003e\u003c/script\u003e\n\u003c!-- from unpkg.com, including polyfills --\u003e\n\u003cscript src=\"https://unpkg.com/array-sort-by/dist/sort-by-full.min.js\"\u003e\u003c/script\u003e\n\n\u003c!-- from rawgit.com --\u003e\n\u003cscript src=\"https://cdn.rawgit.com/jherax/array-sort-by/1.2.1/dist/sort-by.min.js\"\u003e\u003c/script\u003e\n\u003c!-- from rawgit.com, including polyfills --\u003e\n\u003cscript src=\"https://cdn.rawgit.com/jherax/array-sort-by/1.2.1/dist/sort-by-full.min.js\"\u003e\u003c/script\u003e\n```\n\nIn the above case, the function [`sortBy`](#examples) is included as\nglobal object in the browser.\n\nAs `sortBy` is built as [UMD] _(Universal Module Definition)_, it can\nbe included from module loaders such as [CommonJS], [ES2015 Imports]\nor [AMD RequireJS].\n\n### CommonJS\n\n```javascript\nvar sortBy = require('array-sort-by');\n```\n\n### ES2015 Imports\n\n```javascript\nimport sortBy from 'array-sort-by';\n```\n\n### AMD\n\n```javascript\n// using RequireJS\nrequirejs.config({\n  paths: {\n    // remove the extension .js\n    'array-sort-by': '\u003cPATH\u003e/sort-by.min'\n  }\n});\nrequire(['array-sort-by'], function(sortBy) {\n  sortBy(someArray);\n});\n```\n\nSee an example with RequireJS here: http://jsfiddle.net/FdKTn/75/\n\n[\u0026#9751; Back to Index](#content)\n\n## Examples\n\n### Default sorting (ASC)\n\n```javascript\nlet arr = [10, 8, 5, 3, 0, 7, 4, 5, 1];\nsortBy(arr);\n\n/**\n * expected:\n * [0, 1, 3, 4, 5, 5, 7, 8, 10]\n */\n```\n\n### Sorting DESC: numbers\n\n```javascript\nlet arr = [5, 1, 8, 0, 3, 7, 10, 4, 3, 8];\nsortBy(arr, n =\u003e -n);\n\n/**\n * expected:\n * [10, 8, 8, 7, 5, 4, 3, 3, 1, 0]\n */\n```\n\n### Sorting DESC: date-strings as Date\n\n```javascript\nlet arr = ['1983/03/06', '1980/12/24', '1985/08/31', '1983/03/05'];\nsortBy(arr, (s) =\u003e -new Date(s));\n\n/**\n * expected:\n * [\"1985/08/31\", \"1983/03/06\", \"1983/03/05\", \"1980/12/24\"]\n */\n```\n\n### Sorting DESC: strings\n\nBecause we use the minus **(-)** symbol to specify a descending order,\nit would produce a `NaN` value if used with a `String` value.\nSo the flag **`\"desc:\"`** (not case sensitive) is prefixed\nto the string value in the `parser` callback.\n\n```javascript\nvar arr = ['único', 'cosas', 'Árbol', 'fútbol', 'algo'];\n\nsortBy(arr, item =\u003e 'desc:' + item);\n/**\n * expected:\n * [\"único\", \"fútbol\", \"cosas\", \"Árbol\", \"algo\"]\n */\n\n// sorting ASC: accented words\nsortBy(arr);\n/**\n * expected:\n * [\"algo\", \"Árbol\", \"cosas\", \"fútbol\", \"único\"]\n */\n```\n\n### Sorting ASC: accented words by @text\n\n```javascript\nvar arr = [\n  { id: 10, text: 'Woche' },\n  { id: 20, text: 'wöchentlich' },\n  { id: 30, text: 'wäre' }\n];\n\nsortBy(arr, item =\u003e item.text);\n\n/**\n * expected:\n * [\n *   { id: 30, text: \"wäre\" },\n *   { id: 10, text: \"Woche\" },\n *   { id: 20, text: \"wöchentlich\" }\n * ]\n */\n```\n\n### Sorting DESC by @id, after ASC by @dob (as Date)\n\n```javascript\nlet arr = [\n  { id: 8, dob: '1985/08/31' },\n  { id: 2, dob: '1980/12/24' },\n  { id: 5, dob: '1983/03/06' },\n  { id: 8, dob: '1983/03/06' }\n];\n\nsortBy(arr, (o) =\u003e [-o.id, new Date(o.dob)]);\n\n/**\n * expected:\n * [\n *   { id: 8, dob: \"1983/03/06\" },\n *   { id: 8, dob: \"1985/08/31\" },\n *   { id: 5, dob: \"1983/03/06\" },\n *   { id: 2, dob: \"1980/12/24\" }\n * ]\n */\n```\n\n### Sorting DESC by @name\n\n```javascript\nlet arr = [\n  { id: 4, name: 'Pedro' },\n  { id: 6, name: 'Lucía' },\n  { id: 7, name: 'paco' },\n  { id: 3, name: 'luis' }\n];\n\nsortBy(arr, item =\u003e `DESC:${item.name}`);\n\n/**\n * expected:\n * [\n *   { id: 4, name: \"Pedro\" },\n *   { id: 7, name: \"paco\" },\n *   { id: 3, name: \"luis\" },\n *   { id: 6, name: \"Lucía\" }\n * ]\n */\n```\n\n### Sorting ASC by @name, after DESC by @age, after ASC by @id\n\n```javascript\nlet arr = [\n  { id: 9, age: 26, name: 'pedro' },\n  { id: 6, age: 21, name: 'Pedro' },\n  { id: 7, age: 26, name: 'Maria' },\n  { id: 2, age: 26, name: 'maría' }\n];\n\nsortBy(arr, item =\u003e [item.name, -item.age, item.id]);\n\n/**\n * expected:\n * [\n *   { id: 2, age: 26, name: \"maría\" },\n *   { id: 7, age: 26, name: \"Maria\" },\n *   { id: 9, age: 26, name: \"pedro\" },\n *   { id: 6, age: 21, name: \"Pedro\" }\n * ]\n */\n```\n\n[\u0026#9751; Back to Index](#content)\n\n## Versioning\n\nThis projects adopts the [Semantic Versioning](http://semver.org/)\n(SemVer) guidelines:\n\n```text\n\u003cMAJOR\u003e.\u003cMINOR\u003e.\u003cPATCH\u003e\n```\n\nGiven a version number MAJOR.MINOR.PATCH, increment the:\n\n1. MAJOR version when you make incompatible API changes.\n1. MINOR version when you add functionality in a backwards-compatible manner.\n1. PATCH version when you make backwards-compatible bug fixes.\n\n## Issues\n\nTo report an issue and keep traceability of bug-fixes, please report to:\n\n- https://github.com/jherax/array-sort-by/issues\n\n## License\n\nThis project has been released under the [ISC](https://opensource.org/licenses/ISC) license.\nThis license applies ONLY to the source of this repository and does not extend to any other distribution,\nor any other 3rd party libraries used in a repository. See [LICENSE](LICENSE) file for more information.\n\n\u003c!-- LINKS --\u003e\n\n[UMD]: http://davidbcalhoun.com/2014/what-is-amd-commonjs-and-umd/\n[CommonJS]: https://blog.risingstack.com/node-js-at-scale-module-system-commonjs-require/\n[ES2015 Imports]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import\n[AMD RequireJS]: http://requirejs.org/docs/api.html#jsfiles\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjherax%2Farray-sort-by","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjherax%2Farray-sort-by","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjherax%2Farray-sort-by/lists"}