Have opinions about JavaScript? We want to hear them. Take the 2018 JavaScript Ecosystem Survey »

fluent-sort

1.2.5 • Public • Published

fluent-sort

A fluent sorting library for JavaScript

fluent-sort is a compact, dependency-free library (less than 1kb) that provides a fluent, pure API for sorting JavaScript arrays.

The API is a mostly pure, fluent API; all methods on Orderables will return new objects (with the exception of .sortInPlace()).

Example

const testCases = [
    {
      id: 0,
      name: "Strong Monster",
      strength: 10,
      agility: 5,
      intelligence: 8,
      monsterdexOrder: 5
    },
    {
      id: 1,
      name: "Fast Monster",
      strength: 5,
      agility: 10,
      intelligence: 5,
      monsterdexOrder: 1
    },
    {
      id: 2,
      name: "Mediocre Monster",
      strength: 7.5,
      agility: 7.5,
      intelligence: 8,
      monsterdexOrder: 6
    },
    {
      id: 3,
      name: "Unimpressive Monster",
      strength: 2,
      agility: 2,
      intelligence: 2,
      monsterdexOrder: 4
    },
    {
      id: 4,
      name: "Slow Monster",
      strength: 7.5,
      agility: 3,
      intelligence: 8,
      monsterdexOrder: 17
    },
    {
      id: 5,
      name: "Smart Monster",
      strength: 3,
      agility: 7.5,
      intelligence: 15,
      monsterdexOrder: 75
    }
  ];

const sortedTests = fluentSort(testCases) // Returns the OrderableInitiator
    .sortByField(x => x.intelligence) // Returns the Orderable
    .thenByFieldDescending(y => y.agility) // Returns a new Orderable with both rules applied
    .result(); // Evaluates and returns the result

console.log(sortedTests);

Classes

Orderable

A wrapper around an array and a set of rules defining how the array is to be ordered

OrderableInitiator

A wrapper around an array, prepared to be ordered.

Typedefs

comparatorCallbacknumber

A callback for comparing 2 objects and their associated sort order.

selectorCallbackany

A callback for selecting a field from an object.

Orderable

A wrapper around an array and a set of rules defining how the array is to be ordered

Kind: global class

new Orderable(arr, comparators)

Create an orderable.

Param Type Description
arr array The data that will be ordered
comparators array An array of callback functions that will compare the data to be sorted

orderable.thenBy(comparator) ⇒ Orderable

Generates a new Orderable with the next sorting rule added.

Kind: instance method of Orderable Returns: Orderable - The configured orderable structure.

Param Type Description
comparator comparatorCallback The callback that will be added to the array sorting rule

orderable.thenByDescending(comparator) ⇒ Orderable

Generates a new Orderable with the next sorting rule added to be sorted in descending order.

Kind: instance method of Orderable Returns: Orderable - The configured orderable structure.

Param Type Description
comparator comparatorCallback The callback that will be added to the array sorting rule

orderable.thenByField(selector) ⇒ Orderable

Generates a new Orderable with the next sorting rule added.

Kind: instance method of Orderable Returns: Orderable - The configured orderable structure.

Param Type Description
selector selectorCallback | string A selector to run on the left and right object to select a field to be sorted on, or a string to represent the field name to be sorted on.

orderable.thenByFieldDescending(selector) ⇒ Orderable

Generates a new Orderable with the next sorting rule added to be sorted in descending order.

Kind: instance method of Orderable Returns: Orderable - The configured orderable structure.

Param Type Description
selector selectorCallback | string A selector to run on the left and right object to select a field to be sorted on, or a string to represent the field name to be sorted on.

orderable.result() ⇒ array

Generates a copy of the array, sorted.

Kind: instance method of Orderable Returns: array - The sorted array

orderable.sortInPlace() ⇒ array

Sorts the original array, in place. This method is not pure.

Kind: instance method of Orderable Returns: array - The sorted array

OrderableInitiator

A wrapper around an array, prepared to be ordered.

Kind: global class

new OrderableInitiator(arr)

Create an orderable initiator.

Param Type Description
arr array The data that will be ordered

orderableInitiator.sortBy(comparator) ⇒ Orderable

Initiates the orderable with an initial sort order.

Kind: instance method of OrderableInitiator Returns: Orderable - The configured orderable structure.

Param Type Description
comparator comparatorCallback The callback that will be run first to sort the array

orderableInitiator.sortByDescending(comparator) ⇒ Orderable

Initiates the orderable with an initial sort order in descending order.

Kind: instance method of OrderableInitiator Returns: Orderable - The configured orderable structure.

Param Type Description
comparator comparatorCallback The callback that will be run first to sort the array

orderableInitiator.sortByField(selector) ⇒ Orderable

Initiates the orderable with a sort on the supplied field.

Kind: instance method of OrderableInitiator Returns: Orderable - The configured orderable structure.

Param Type Description
selector selectorCallback | string A selector to run on the left and right object to select a field to be sorted on, or a string to represent the field name to be sorted on.

orderableInitiator.sortByFieldDescending(selector) ⇒ Orderable

Initiates the orderable with a sort on the supplied field in descending order.

Kind: instance method of OrderableInitiator Returns: Orderable - The configured orderable structure.

Param Type Description
selector selectorCallback | string A selector to run on the left and right object to select a field to be sorted on, or a string to represent the field name to be sorted on.

comparatorCallback ⇒ number

A callback for comparing 2 objects and their associated sort order.

Kind: global typedef Returns: number - 1, 0, or -1 to denote whether left comes before, equal to, or after right

Param Type Description
left left the left object
right right the right object

selectorCallback ⇒ any

A callback for selecting a field from an object.

Kind: global typedef Returns: any - the field to be sorted on

Param Type Description
obj obj object - The object that the field will be selected from

Installation

From NPM

npm install fluent-sort

And in your file:

const fluentSort = require("fluent-sort");

In your browser

Add a script reference to the file /dist/fluent-sort.min.js to your page, and use it as above:

let sortedTests = fluentSort(testCases)
    .sortByField(x => x.intelligence)
    .thenByField(y => y.agility)
    .result();

install

npm i fluent-sort

Downloadsweekly downloads

1

version

1.2.5

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
Report a vulnerability