react-optimized-sort

A simple component used for sorting collections and arrays only in an optimized way.

Storybook

Changelog

In what way is this component "optimized"?

Re-sorts only occur if the given items have changed order or any of the items have been changed/removed/added since the previous render or if any of the comparison props have changed sine the last render. A memoize once pattern is used to accomplish this (I.E. the previous result of sorting is cached and sorting only occurs again if the previously given props have changed, otherwise, the cached result is passed on to the render/children prop).

It is important to note that a hash of items and the comparator props is used to determine if a change has occurred. This is very useful because one does not need to ensure that the exact same objects are passed to OptimizedSort with every re-render; instead, everything can be specified inline and you will still get all of the optimization benefits of OptimizedSort. To illustrate this, see the "Usage" section below. In the example given, only the first render of MyComponent will trigger sorting within OptimizedSort, while all subsequent renders will not trigger re-sorting even though a new array is created for the comparators prop with ever render of MyComponent.

Install

$ npm i --save react-optimized-sort

Usage

import React from 'react';
import OptimizedSort from 'react-optimized-sort';
import { sort as timsort } from 'timsort';

export default function MyComponent(props) {
  return (
    {/* ... */}

      <OptimizedSort
        items={props.items}
        sorter={timsort}
        comparators={[
          { propPath: 'itemPropName1', type: 'string' },
          { propPath: 'itemPropName2', type: 'number' },
          { propPath: 'itemPropName3', type: 'date' },
          { propPath: 'itemPropName4', type: 'boolean' },
        
          {
            propPath: 'itemPropName5',
            options:  { myOptionProp: 42 },
        
            comparator(leftItem, rightItem, options) {
              // Perform comparison...
            }
          },
        
          function anotherComparator(leftItem, rightItem) {
            // Perform comparison...
          }
        ]}
        render={(sortedItems) => (
          // Render sorted items...
        )} />

      {/* ...or... */}

      <OptimizedSort items={props.items}
            sorter={timsort}
            comparators={[
              { propPath: 'itemPropName1', type: 'string' },
              { propPath: 'itemPropName2', type: 'number' },
              { propPath: 'itemPropName3', type: 'date' },
              { propPath: 'itemPropName4', type: 'boolean' },
            
              {
                propPath: 'itemPropName5',
                options:  { myOptionProp: 42 },
            
                comparator(leftItem, rightItem, options) {
                  // Perform comparison...
                }
              },
            
              function anotherComparator(leftItem, rightItem) {
                // Perform comparison...
              }
            ]}>
        {(sortedItems) => (
          // Render sorted items...
        )}
      </OptimizedSort>

    {/* ... */}
  );
}

Props

• items ?Array

  Array of items to be sorted and passed to render/children prop.

• render(sortedItems) or children(sortedItems) !Function - REQUIRED

  Render function (or function as child) called after items sorting is complete.

• ascending ?Boolean

  Default option to sort in ascending or descending order.

• nullsFirst ?Boolean

  Default option to sort with null values first or last.

• skip ?Boolean

  When true, skips sorting and the value of items prop will be passed to render, unsorted. This is useful in the case where sorting may only be conditionally needed.

• ignoreCache ?Boolean

  When true, a sort is forced even if none of the cached props have changed. This is useful when a custom comparator has been provided that depends on information outside of the given items prop.

• sorter(array, comparator) ?Function

  NOTE: If the sorter given does not return an Array, then it is assumed that the array that was given to the sorter was modified.

  Specifying a sorter function allows you to essential control the sorting algorithm used when a sort occurs within the component. By default, Array.prototype.sort is used if no sorter is specified or if sorter is null or undefined.

• comparator(leftItem, rightItem[, options]) ?Function

  NOTE: This prop takes precedence over the comparators prop and will cause the comparators prop to be ignored if this props is set to a non-null, non-undefined value.

  Comparator function to use when comparing the items found in the given items prop.

• comparators ?Array<(Function|Object)>

  IMPORTANT: When using this prop, it is assumed that all of the items given are objects and not primitive values like a string, boolean, date, or number.

  NOTE: This prop is ignored if the comparator prop is set to a non-null, non-undefined value.

  A list of comparators and/or comparator configurations to use when comparing the items found in the given items prop. The comparators/configurations are applied in the order that they are found in the comparators array given. If an item in the comparators list is a Function, then that function will just be called with "left" and "right" parameters passed to it (in that order as well). If an item in the comparators list is an Object, then it will be treated as a "configuration". For more information about said "configurations", refer to Comparator Config Properties below.

Comparator Configuration Properties

The comparator configuration objects can take one of two forms: either a comparator is given with some accompanying options, or a propPath and type are given and comparisons are taken care of for you by the OptimizedSort component. Below you will find two tables, each describes the properties available for one of the two configuration objects already described.

PropPath/Type Configuration Properties:

* = Required Property

| Property Name/Type | Type | Default Value | Description | |:--------------------------|:--------|:-----------------|:------------| | *propPath | String | | Path to item property to compare. | *type | String | | The type of the value found at propPath.Allowed Values:string, number, date, boolean | options | Object | | Comparison options. | options.isAscending | Boolean | props.ascending | When true, items will be sorted in ascending order. | options.nullsFirst | Boolean | props.nullsFirst | When true, null and undefined items will be placed before any defined item. | options.localeIds | String | | Only used when type is "string".See localeCompare docs for details. | options.usage | String | | Only used when type is "string".See localeCompare docs for details. | options.localeMatcher | String | | Only used when type is "string".See localeCompare docs for details. | options.numeric | Boolean | | Only used when type is "string".See localeCompare docs for details. | options.caseFirst | String | | Only used when type is "string".See localeCompare docs for details. | options.sensitivity | String | | Only used when type is "string".See localeCompare docs for details. | options.ignorePunctuation | Boolean | | Only used when type is "string".See localeCompare docs for details.

Comparator Configuration Properties:

* = Required Property

| Property Name/Type | Type | Default Value | Description | |:--------------------|:---------|:----------------|:------------| | *comparator | Function | | Comparator function to use for comparisons.Function Signature:comparator(leftParam, rightParam, options) | options | Object | | Comparison options.(NOTE: options will be passed to comparator as a 3rd function parameter) | options.isAscending | Boolean | props.ascending | When true, items will be sorted in ascending order.

License

ISC License (ISC)

Copyright (c) 2019, Brandon D. Sara (https://bsara.dev/)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.