npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

sort-array

v5.0.0

Published

Isomorphic, load-anywhere function to sort an array by scalar, deep or computed values in any standard or custom order

Downloads

738,643

Readme

view on npm npm module downloads Gihub repo dependents Gihub package dependents Node.js CI js-standard-style

sort-array

Isomorphic, load-anywhere function to sort an array by scalar, deep or computed values in any standard or custom order.

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

> const partsOfTheDay = ['twilight', 'afternoon', 'morning', 'evening']

> sortArray(partsOfTheDay)
[ 'afternoon', 'evening', 'morning', 'twilight' ]

Descending order

Sort an array of strings in descending order.

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

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

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

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

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

> 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 for more examples.

API Reference

sort-array

Isomorphic, load-anywhere function to sort an array by scalar, deep or computed values in any standard or custom order.

Example

const sortArray = require('sort-array')

sortArray(array, [options]) ⇒ Array

Kind: Exported function
Returns: Array - Returns the array that was passed in.

| Param | Type | Description | | --- | --- | --- | | array | Array | The input array to sort. It is sorted in place. | | [options] | object | Sort options. | | [options.by] | Array.<string> | One or more property names or computed fields to sort by. Specifying property names is only relevant when sorting an array of objects. | | [options.order] | Array.<string> | One or more sort orders. Specify 'asc', 'desc' or a property name from the options.customOrders object. | | [options.customOrders] | object | A dictionary object containing one or more custom orders. Each custom order value must be an array defining the order expected values must be sorted in. | | [options.computed] | object | A dictionary object containing one or more computed field functions. The function will be invoked once per item in the array. Each invocation will receive the array item as input and must return a primitive value by which the array can be sorted. | | [options.nullRank] | number | Configures whether null values will be sorted before or after defined values. Set to -1 for before, 1 for after. Defaults to 1. | | [options.undefinedRank] | number | Configures whether undefined values will be sorted before or after defined values. Set to -1 for before, 1 for after. Defaults to 1. |

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:

const sortArray = require('sort-array')

Within Node.js with ECMAScript Module support enabled:

import sortArray from 'sort-array'

Within an modern browser ECMAScript Module:

import sortArray from './node_modules/sort-array/dist/index.mjs'

Old browser (adds window.sortArray):

<script nomodule src="./node_modules/sort-array/dist/index.js"></script>

© 2015-24 Lloyd Brookes <[email protected]>.

Tested by test-runner. Documented by jsdoc-to-markdown.