Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/75lb/sort-array
Isomorphic, load-anywhere function to sort an array by scalar, deep or computed values in any standard or custom order
https://github.com/75lb/sort-array
array esmodules function isomorphic javascript javascript-library load-anywhere module sort-array
Last synced: 1 day ago
JSON representation
Isomorphic, load-anywhere function to sort an array by scalar, deep or computed values in any standard or custom order
- Host: GitHub
- URL: https://github.com/75lb/sort-array
- Owner: 75lb
- License: mit
- Created: 2015-07-10T21:02:44.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-08-29T23:01:10.000Z (4 months ago)
- Last Synced: 2024-10-12T08:10:52.370Z (3 months ago)
- Topics: array, esmodules, function, isomorphic, javascript, javascript-library, load-anywhere, module, sort-array
- Language: JavaScript
- Homepage:
- Size: 502 KB
- Stars: 43
- Watchers: 3
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.hbs
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.org/package/sort-array)
[](https://www.npmjs.org/package/sort-array)
[](https://github.com/75lb/sort-array/network/dependents?dependent_type=REPOSITORY)
[](https://github.com/75lb/sort-array/network/dependents?dependent_type=PACKAGE)
[](https://github.com/75lb/sort-array/actions/workflows/node.js.yml)
[](https://github.com/feross/standard)
# sort-array
Isomorphic, load-anywhere function to sort an array by scalar, deep or computed values in any standard or custom order.
```js
const sortArray = require('sort-array')
```
## Synopsis
Some trivial examples to demonstrate typical usage.
### Sorting an array of primitives
#### Ascending order
Sort an array of strings in ascending order (the default).
```js
> const partsOfTheDay = ['twilight', 'afternoon', 'morning', 'evening']
> sortArray(partsOfTheDay)
[ 'afternoon', 'evening', 'morning', 'twilight' ]
```
#### Descending order
Sort an array of strings in descending order.
```js
> sortArray(partsOfTheDay, { order: 'desc' })
[ 'twilight', 'morning', 'evening', 'afternoon' ]
```
#### Custom sort order
The default value for `options.order` is `'asc'`. You can also specify `'desc'` or the name of a property from the `customOrders` object. For example, sort parts of the day by the order in which they occur.
```js
> sortArray(partsOfTheDay, {
order: 'time',
customOrders: {
time: ['morning', 'afternoon', 'evening', 'twilight']
}
})
[ 'morning', 'afternoon', 'evening', 'twilight' ]
```
### Sorting an array of objects
#### Sort by object property
Pass one or more property names to `options.by` to sort an array of objects by those properties.
```js
> const repositories = [
{ name: '75lb/sort-array', openIssues: 0, closedIssues: 4 },
{ name: 'lwsjs/local-web-server', openIssues: 4, closedIssues: 80 },
{ name: 'jsdoc2md/jsdoc-api', openIssues: 3, closedIssues: 47 }
]
> sortArray(repositories, {
by: 'openIssues',
order: 'desc'
})
[
{ name: 'lwsjs/local-web-server', openIssues: 4, closedIssues: 80 },
{ name: 'jsdoc2md/jsdoc-api', openIssues: 3, closedIssues: 47 },
{ name: '75lb/sort-array', openIssues: 0, closedIssues: 4 }
]
```
#### Sort by computed field
Sort by a computed field, i.e. a computed value that doesn't exist in the input dataset. Define your computed fields in the `options.computed` object, each value being a function which takes an array member as input and returns the primitive value to be sorted by. In this example we sort by `total` (the name of the computed field supplied in `options.computed`).
```js
> const repositories = [
{ name: '75lb/sort-array', openIssues: 0, closedIssues: 4 },
{ name: 'lwsjs/local-web-server', openIssues: 4, closedIssues: 80 },
{ name: 'jsdoc2md/jsdoc-api', openIssues: 3, closedIssues: 47 }
]
> sortArray(repositories, {
by: 'total',
order: 'desc',
computed: {
total: repository => repository.openIssues + repository.closedIssues
}
})
[
{ name: 'lwsjs/local-web-server', openIssues: 4, closedIssues: 80 },
{ name: 'jsdoc2md/jsdoc-api', openIssues: 3, closedIssues: 47 },
{ name: '75lb/sort-array', openIssues: 0, closedIssues: 4 }
]
```
#### Sort by deep object values
You can use computed fields to sort by values deep in an object structure.
```js
> const data = [
{ inner: { number: 2 } },
{ inner: { number: 3 } },
{ inner: { number: 1 } }
]
> sortArray(data, {
by: 'number',
computed: {
number: row => row.inner.number
}
})
[
{ inner: { number: 1 } },
{ inner: { number: 2 } },
{ inner: { number: 3 } }
]
```
#### Sort by multiple fields
Sort by multiple columns using multiple custom orders.
```js
> const attributes = [
{ skill: 'accuracy', confidence: 'medium' },
{ skill: 'power', confidence: 'high' },
{ skill: 'speed', confidence: 'low' },
{ skill: 'power', confidence: 'low' },
{ skill: 'speed', confidence: 'high' },
{ skill: 'accuracy', confidence: 'low' },
{ skill: 'speed', confidence: 'medium' },
{ skill: 'accuracy', confidence: 'high' },
{ skill: 'power', confidence: 'medium' }
]
> sortArray(attributes, {
by: ['skill', 'confidence'],
order: ['skill', 'confidence'],
customOrders: {
skill: ['accuracy', 'speed', 'power'],
confidence: ['low', 'medium', 'high'],
}
})
[
{ skill: 'accuracy', confidence: 'low' },
{ skill: 'accuracy', confidence: 'medium' },
{ skill: 'accuracy', confidence: 'high' },
{ skill: 'speed', confidence: 'low' },
{ skill: 'speed', confidence: 'medium' },
{ skill: 'speed', confidence: 'high' },
{ skill: 'power', confidence: 'low' },
{ skill: 'power', confidence: 'medium' },
{ skill: 'power', confidence: 'high' }
]
```
Please visit [the sort-array wiki](https://github.com/75lb/sort-array/wiki) for more examples.
## API Reference
{{>main}}
## Load anywhere
This library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation.
Node.js:
```js
const sortArray = require('sort-array')
```
Within Node.js with ECMAScript Module support enabled:
```js
import sortArray from 'sort-array'
```
Within an modern browser ECMAScript Module:
```js
import sortArray from './node_modules/sort-array/dist/index.mjs'
```
Old browser (adds `window.sortArray`):
```html
```
* * *
© 2015-24 Lloyd Brookes \<[email protected]\>.
Tested by [test-runner](https://github.com/test-runner-js/test-runner). Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown).