├── .editorconfig ├── .gitattributes ├── .github ├── security.md └── workflows │ └── main.yml ├── .gitignore ├── .npmrc ├── index.d.ts ├── index.js ├── index.test-d.ts ├── license ├── package.json ├── readme.md └── test.js /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = tab 5 | end_of_line = lf 6 | charset = utf-8 7 | trim_trailing_whitespace = true 8 | insert_final_newline = true 9 | 10 | [*.yml] 11 | indent_style = space 12 | indent_size = 2 13 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto eol=lf 2 | -------------------------------------------------------------------------------- /.github/security.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure. 4 | -------------------------------------------------------------------------------- /.github/workflows/main.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | on: 3 | - push 4 | - pull_request 5 | jobs: 6 | test: 7 | name: Node.js ${{ matrix.node-version }} 8 | runs-on: ubuntu-latest 9 | strategy: 10 | fail-fast: false 11 | matrix: 12 | node-version: 13 | - 20 14 | - 18 15 | steps: 16 | - uses: actions/checkout@v4 17 | - uses: actions/setup-node@v4 18 | with: 19 | node-version: ${{ matrix.node-version }} 20 | - run: npm install 21 | - run: npm test 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | yarn.lock 3 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | package-lock=false 2 | -------------------------------------------------------------------------------- /index.d.ts: -------------------------------------------------------------------------------- 1 | export type Property = string | ((element: T) => unknown) | Array unknown)>; 2 | 3 | export type Options = { 4 | /** 5 | One or more locales to use when sorting strings. 6 | 7 | Should be a locale string or array of locale strings that contain one or more language or locale tags. 8 | 9 | If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. 10 | 11 | If you omit this parameter, the default locale of the JavaScript runtime is used. 12 | 13 | This parameter must conform to BCP 47 standards. See {@link Intl.Collator} for more details. 14 | */ 15 | readonly locales?: string | readonly string[]; 16 | 17 | /** 18 | Comparison options. 19 | 20 | See {@link Intl.Collator} for more details. 21 | */ 22 | readonly localeOptions?: Intl.CollatorOptions; 23 | }; 24 | 25 | /** 26 | Sort an array on an object property. 27 | 28 | @param array - The array to sort. 29 | @param property - The string can be a [dot path](https://github.com/sindresorhus/dot-prop) to a nested object property. Prefix it with `-` to sort it in descending order. 30 | @returns A new sorted version of the given array. 31 | 32 | @example 33 | ``` 34 | import sortOn from 'sort-on'; 35 | 36 | // Sort by an object property 37 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], 'x'); 38 | //=> [{x: 'a'}, {x: 'b'}, {x: 'c'}] 39 | 40 | // Sort descending by an object property 41 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], '-x'); 42 | //=> [{x: 'c'}, {x: 'b'}, {x: 'a'}] 43 | 44 | // Sort by a nested object property 45 | sortOn([{x: {y: 'b'}}, {x: {y: 'a'}}], 'x.y'); 46 | //=> [{x: {y: 'a'}}, {x: {y: 'b'}}] 47 | 48 | // Sort descending by a nested object property 49 | sortOn([{x: {y: 'b'}}, {x: {y: 'a'}}], '-x.y'); 50 | //=> [{x: {y: 'b'}, {x: {y: 'a'}}}] 51 | 52 | // Sort by the `x` property, then `y` 53 | sortOn([{x: 'c', y: 'c'}, {x: 'b', y: 'a'}, {x: 'b', y: 'b'}], ['x', 'y']); 54 | //=> [{x: 'b', y: 'a'}, {x: 'b', y: 'b'}, {x: 'c', y: 'c'}] 55 | 56 | // Sort by the returned value 57 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], el => el.x); 58 | //=> [{x: 'a'}, {x: 'b'}, {x: 'c'}] 59 | ``` 60 | */ 61 | export default function sortOn(array: readonly T[], property: Property, options?: Options): T[]; 62 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | import {getProperty} from 'dot-prop'; 2 | 3 | export default function sortOn(array, property, {locales, localeOptions} = {}) { 4 | if (!Array.isArray(array)) { 5 | throw new TypeError(`Expected type \`Array\`, got \`${typeof array}\``); 6 | } 7 | 8 | return [...array].sort((a, b) => { 9 | let returnValue = 0; 10 | 11 | [property].flat().some(element => { 12 | let isDescending; 13 | let x; 14 | let y; 15 | 16 | if (typeof element === 'function') { 17 | x = element(a); 18 | y = element(b); 19 | } else if (typeof element === 'string') { 20 | isDescending = element.charAt(0) === '-'; 21 | element = isDescending ? element.slice(1) : element; 22 | x = getProperty(a, element); 23 | y = getProperty(b, element); 24 | } else { 25 | x = a; 26 | y = b; 27 | } 28 | 29 | if (x === y) { 30 | returnValue = 0; 31 | return false; 32 | } 33 | 34 | if (y !== 0 && !y) { 35 | returnValue = isDescending ? 1 : -1; 36 | return true; 37 | } 38 | 39 | if (x !== 0 && !x) { 40 | returnValue = isDescending ? -1 : 1; 41 | return true; 42 | } 43 | 44 | if (typeof x === 'string' && typeof y === 'string') { 45 | returnValue = isDescending ? y.localeCompare(x, locales, localeOptions) : x.localeCompare(y, locales, localeOptions); 46 | return returnValue !== 0; 47 | } 48 | 49 | if (isDescending) { 50 | returnValue = x < y ? 1 : -1; 51 | } else { 52 | returnValue = x < y ? -1 : 1; 53 | } 54 | 55 | return true; 56 | }); 57 | 58 | return returnValue; 59 | }); 60 | } 61 | -------------------------------------------------------------------------------- /index.test-d.ts: -------------------------------------------------------------------------------- 1 | import {expectType} from 'tsd'; 2 | import sortOn, {type Property} from './index.js'; 3 | 4 | expectType(sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], 'x')[0].x); 5 | expectType(sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], 'x')[0].x); 6 | 7 | expectType(sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], ['x'])[0].x); 8 | expectType(sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], element => element.x)[0].x); 9 | expectType(sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], [element => element.x])[0].x); 10 | expectType(sortOn([{x: 'b', y: 1}, {x: 'a', y: 2}, {x: 'c', y: 1}], [element => element.x, 'y'])[0].x); 11 | 12 | const property: Property = string => string; 13 | expectType(sortOn(['a', 'bb', 'ccc'], property)[0]); 14 | 15 | sortOn(['a', 'bb', 'ccc'] as const, 'length'); 16 | 17 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], 'x', {locales: 'en'}); 18 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], 'x', {localeOptions: {numeric: true}}); 19 | 20 | declare const localeOptions: Intl.CollatorOptions; 21 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], 'x', {localeOptions}); 22 | -------------------------------------------------------------------------------- /license: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Sindre Sorhus (https://sindresorhus.com) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 | 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 10 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "sort-on", 3 | "version": "6.1.0", 4 | "description": "Sort an array on an object property", 5 | "license": "MIT", 6 | "repository": "sindresorhus/sort-on", 7 | "funding": "https://github.com/sponsors/sindresorhus", 8 | "author": { 9 | "name": "Sindre Sorhus", 10 | "email": "sindresorhus@gmail.com", 11 | "url": "https://sindresorhus.com" 12 | }, 13 | "type": "module", 14 | "exports": { 15 | "types": "./index.d.ts", 16 | "default": "./index.js" 17 | }, 18 | "sideEffects": false, 19 | "engines": { 20 | "node": ">=18" 21 | }, 22 | "scripts": { 23 | "test": "xo && ava && tsd" 24 | }, 25 | "files": [ 26 | "index.js", 27 | "index.d.ts" 28 | ], 29 | "keywords": [ 30 | "sort", 31 | "sorting", 32 | "array", 33 | "by", 34 | "object", 35 | "property", 36 | "dot", 37 | "path", 38 | "get" 39 | ], 40 | "dependencies": { 41 | "dot-prop": "^9.0.0" 42 | }, 43 | "devDependencies": { 44 | "ava": "^6.1.3", 45 | "tsd": "^0.31.1", 46 | "xo": "^0.59.3" 47 | } 48 | } 49 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # sort-on 2 | 3 | > Sort an array on an object property 4 | 5 | ## Install 6 | 7 | ```sh 8 | npm install sort-on 9 | ``` 10 | 11 | ## Usage 12 | 13 | ```js 14 | import sortOn from 'sort-on'; 15 | 16 | // Sort by an object property 17 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], 'x'); 18 | //=> [{x: 'a'}, {x: 'b'}, {x: 'c'}] 19 | 20 | // Sort descending by an object property 21 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], '-x'); 22 | //=> [{x: 'c'}, {x: 'b'}, {x: 'a'}] 23 | 24 | // Sort by a nested object property 25 | sortOn([{x: {y: 'b'}}, {x: {y: 'a'}}], 'x.y'); 26 | //=> [{x: {y: 'a'}}, {x: {y: 'b'}}] 27 | 28 | // Sort descending by a nested object property 29 | sortOn([{x: {y: 'b'}}, {x: {y: 'a'}}], '-x.y'); 30 | //=> [{x: {y: 'b'}, {x: {y: 'a'}}}] 31 | 32 | // Sort by the `x` property, then `y` 33 | sortOn([{x: 'c', y: 'c'}, {x: 'b', y: 'a'}, {x: 'b', y: 'b'}], ['x', 'y']); 34 | //=> [{x: 'b', y: 'a'}, {x: 'b', y: 'b'}, {x: 'c', y: 'c'}] 35 | 36 | // Sort by the returned value 37 | sortOn([{x: 'b'}, {x: 'a'}, {x: 'c'}], element => element.x); 38 | //=> [{x: 'a'}, {x: 'b'}, {x: 'c'}] 39 | ``` 40 | 41 | ## API 42 | 43 | ### sortOn(array, property, options) 44 | 45 | Returns a new sorted version of the given array. 46 | 47 | #### array 48 | 49 | Type: `unknown[]` 50 | 51 | The array to sort. 52 | 53 | #### property 54 | 55 | Type: `string | string[] | Function` 56 | 57 | The string can be a [dot path](https://github.com/sindresorhus/dot-prop) to a nested object property. 58 | 59 | Prefix it with `-` to sort it in descending order. 60 | 61 | #### options 62 | 63 | Type: `object` 64 | 65 | ##### locales 66 | 67 | Type: `string | string[]`\ 68 | Default: The default locale of the JavaScript runtime. 69 | 70 | One or more locales to use when sorting strings. 71 | 72 | Should be a locale string or array of locale strings that contain one or more language or locale tags. 73 | 74 | If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. 75 | 76 | This parameter must conform to BCP 47 standards. See [`Intl.Collator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator) for more details. 77 | 78 | ##### localeOptions 79 | 80 | Type: [`Intl.CollatorOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator#options) 81 | 82 | Comparison options. 83 | -------------------------------------------------------------------------------- /test.js: -------------------------------------------------------------------------------- 1 | import test from 'ava'; 2 | import sortOn from './index.js'; 3 | 4 | test('main', t => { 5 | t.is(sortOn([ 6 | {foo: 'b'}, 7 | {foo: 'a'}, 8 | {foo: 'c'}, 9 | ], 'foo')[0].foo, 'a'); 10 | 11 | t.is(sortOn([ 12 | {foo: 2}, 13 | {foo: 1}, 14 | {foo: 3}, 15 | ], 'foo')[0].foo, 1); 16 | 17 | t.is(sortOn([ 18 | {foo: 'b', bar: 'b'}, 19 | {foo: 'a', bar: 'b'}, 20 | {foo: 'a', bar: 'a'}, 21 | {foo: 'c', bar: 'c'}, 22 | ], ['foo', 'bar'])[0].bar, 'a'); 23 | 24 | t.is(sortOn([ 25 | {foo: {bar: 'b'}}, 26 | {foo: {bar: 'a'}}, 27 | {foo: {bar: 'c'}}, 28 | ], 'foo.bar')[0].foo.bar, 'a'); 29 | 30 | t.is(sortOn([ 31 | {foo: 'b'}, 32 | {foo: 'a'}, 33 | {foo: 'c'}, 34 | ], property => property.foo)[0].foo, 'a'); 35 | 36 | t.is(sortOn([ 37 | {foo: 'b', bar: 'b'}, 38 | {foo: 'a', bar: 'b'}, 39 | {foo: 'a', bar: 'a'}, 40 | {foo: 'c', bar: 'c'}, 41 | ], [ 42 | property => property.foo, 43 | property => property.bar, 44 | ])[0].bar, 'a'); 45 | 46 | t.is(sortOn([ 47 | {foo: 'b', bar: 'a'}, 48 | {foo: 'a', bar: 'b'}, 49 | {foo: 'a', bar: 'c'}, 50 | {foo: 'c', bar: 'c'}, 51 | ], [ 52 | property => property.foo, 53 | property => property.bar, 54 | ])[0].bar, 'b'); 55 | 56 | t.is(sortOn([ 57 | {foo: 2, bar: 2}, 58 | {foo: 1, bar: 2}, 59 | {foo: 1, bar: 1}, 60 | {foo: 3, bar: 3}, 61 | ], [ 62 | property => property.foo, 63 | property => property.bar, 64 | ])[0].bar, 1); 65 | 66 | t.is(sortOn([ 67 | {foo: 2, bar: 1}, 68 | {foo: 1, bar: 2}, 69 | {foo: 1, bar: 3}, 70 | {foo: 3, bar: 3}, 71 | ], [ 72 | property => property.foo, 73 | property => property.bar, 74 | ])[0].bar, 2); 75 | 76 | t.is(sortOn([ 77 | {foo: 2, bar: 1}, 78 | {foo: 1, bar: 2}, 79 | {foo: 1, bar: 3}, 80 | {foo: 3, bar: 3}, 81 | ], [ 82 | property => property.foo, 83 | 'bar', 84 | ])[0].bar, 2); 85 | 86 | const sorted = sortOn([ 87 | {bar: 'b'}, 88 | {foo: 'b'}, 89 | {foo: 'a'}, 90 | ], 'foo'); 91 | 92 | // {bar: 'b'} is not sorted so it might be the first or the second element 93 | t.is(sorted[0].foo || sorted[1].foo, 'a'); 94 | 95 | t.is(sortOn([ 96 | {foo: 'b', bar: 'a'}, 97 | {foo: 'a', bar: 'c'}, 98 | {foo: 'a', bar: 'b'}, 99 | {foo: 'c', bar: 'c'}, 100 | ], ['foo', 'bar'])[0].bar, 'b'); 101 | 102 | t.is(sortOn([ 103 | {foo: 'b'}, 104 | {foo: 'a'}, 105 | {foo: 'c'}, 106 | ], '-foo')[0].foo, 'c'); 107 | 108 | t.is(sortOn([ 109 | {foo: 'b', bar: 'b'}, 110 | {foo: 'a', bar: 'b'}, 111 | {foo: 'a', bar: 'a'}, 112 | {foo: 'c', bar: 'c'}, 113 | ], ['foo', '-bar'])[0].bar, 'b'); 114 | 115 | t.is(sortOn([ 116 | {foo: {bar: 'b'}}, 117 | {foo: {bar: 'a'}}, 118 | {foo: {bar: 'c'}}, 119 | ], '-foo.bar')[0].foo.bar, 'c'); 120 | 121 | t.is(sortOn([ 122 | {foo: {bar: 2}}, 123 | {foo: {bar: 1}}, 124 | {foo: {bar: 3}}, 125 | ], '-foo.bar')[0].foo.bar, 3); 126 | 127 | t.is(sortOn([ 128 | {foo: 'a'}, 129 | {foo: null}, 130 | {foo: 'b'}, 131 | ], 'foo')[2].foo, null); 132 | 133 | t.is(sortOn([ 134 | {foo: 'a'}, 135 | {foo: null}, 136 | {foo: 'b'}, 137 | ], '-foo')[0].foo, null); 138 | 139 | t.is(sortOn([ 140 | {foo: 'a'}, 141 | {foo: ''}, 142 | {foo: 'b'}, 143 | ], 'foo')[2].foo, ''); 144 | 145 | t.is(sortOn([ 146 | {foo: 'a'}, 147 | {foo: ''}, 148 | {foo: 'b'}, 149 | ], '-foo')[0].foo, ''); 150 | 151 | t.is(sortOn([ 152 | {foo: 1}, 153 | {foo: 0}, 154 | {foo: 2}, 155 | ], 'foo')[0].foo, 0); 156 | 157 | t.deepEqual(sortOn([ 158 | {foo: 'g'}, 159 | {foo: 'ä'}, 160 | {foo: 'x'}, 161 | {foo: 'a'}, 162 | ], 'foo', {locales: 'sv-SE'}), [ 163 | {foo: 'a'}, 164 | {foo: 'g'}, 165 | {foo: 'x'}, 166 | {foo: 'ä'}, 167 | ]); 168 | 169 | t.deepEqual(sortOn([ 170 | {foo: 'a1'}, 171 | {foo: 'a10'}, 172 | {foo: 'a11'}, 173 | {foo: 'a2'}, 174 | {foo: 'a25'}, 175 | {foo: 'a3'}, 176 | ], 'foo', {localeOptions: {numeric: true}}), [ 177 | {foo: 'a1'}, 178 | {foo: 'a2'}, 179 | {foo: 'a3'}, 180 | {foo: 'a10'}, 181 | {foo: 'a11'}, 182 | {foo: 'a25'}, 183 | ]); 184 | }); 185 | --------------------------------------------------------------------------------