added options.nullRank and undefinedRank

Author: 75lb

README.md

@@ -139,15 +139,15 @@ Please visit [the sort-array wiki](https://github.com/75lb/sort-array/wiki) for
 ### sort-array
 Isomorphic, load-anywhere function to sort an array by scalar, deep or computed values in any standard or custom order.
 
-**Example**
+**Example**  
 ```js
 const sortArray = require('sort-array')
 ```
 <a name="exp_module_sort-array--sortArray"></a>
 
 #### sortArray(array, [options]) ⇒ <code>Array</code> ⏏
-**Kind**: Exported function
-**Returns**: <code>Array</code> - Returns the array that was passed in.
+**Kind**: Exported function  
+**Returns**: <code>Array</code> - Returns the array that was passed in.  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -157,6 +157,8 @@ const sortArray = require('sort-array')
 | [options.order] | <code>Array.&lt;string&gt;</code> | One or more sort orders. Specify `asc`, `desc` or a property name from the `options.customOrders` object. |
 | [options.customOrders] | <code>object</code> | 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] | <code>object</code> | 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] | <code>number</code> | 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] | <code>number</code> | 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

dist/index.js

@@ -356,7 +356,12 @@
    */
   function sortArray (arr, options = {}) {
     options = Object.assign(
-      { computed: {}, customOrders: {} },
+      {
+        computed: {},
+        customOrders: {},
+        nullRank: 1,
+        undefinedRank: 1
+      },
       options
     );
     arr.sort(getCompareFunc(options));
@@ -403,13 +408,13 @@
             ? 1
             : 0;
       } else if (t.isNull(x) && t.isDefinedValue(y)) {
-        result = 1;
+        result = options.nullRank;
       } else if (t.isUndefined(x) && t.isDefinedValue(y)) {
-        result = 1;
+        result = options.undefinedRank;
       } else if (t.isNull(y) && t.isDefinedValue(x)) {
-        result = -1;
+        result = -options.nullRank;
       } else if (t.isUndefined(y) && t.isDefinedValue(x)) {
-        result = -1;
+        result = -options.undefinedRank;
       } else {
         result = x < y ? -1 : x > y ? 1 : 0;
         if (currOrder === 'desc') {

dist/index.mjs

@@ -350,7 +350,12 @@ var t = {
  */
 function sortArray (arr, options = {}) {
   options = Object.assign(
-    { computed: {}, customOrders: {} },
+    {
+      computed: {},
+      customOrders: {},
+      nullRank: 1,
+      undefinedRank: 1
+    },
     options
   );
   arr.sort(getCompareFunc(options));
@@ -397,13 +402,13 @@ function getCompareFunc (options = {}) {
           ? 1
           : 0;
     } else if (t.isNull(x) && t.isDefinedValue(y)) {
-      result = 1;
+      result = options.nullRank;
     } else if (t.isUndefined(x) && t.isDefinedValue(y)) {
-      result = 1;
+      result = options.undefinedRank;
     } else if (t.isNull(y) && t.isDefinedValue(x)) {
-      result = -1;
+      result = -options.nullRank;
     } else if (t.isUndefined(y) && t.isDefinedValue(x)) {
-      result = -1;
+      result = -options.undefinedRank;
     } else {
       result = x < y ? -1 : x > y ? 1 : 0;
       if (currOrder === 'desc') {

index.mjs

@@ -17,12 +17,19 @@ import t from 'typical/index.mjs'
  * @param {string[]} [options.order] - One or more sort orders. Specify `asc`, `desc` or a property name from the `options.customOrders` object.
  * @param {object} [options.customOrders] - 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.
  * @param {object} [options.computed] - 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.
+ * @param {number} [options.nullRank] - Configures whether `null` values will be sorted before or after defined values. Set to `-1` for before, `1` for after. Defaults to `1`.
+ * @param {number} [options.undefinedRank] - Configures whether `undefined` values will be sorted before or after defined values. Set to `-1` for before, `1` for after. Defaults to `1`.
  * @returns {Array} Returns the array that was passed in.
  * @alias module:sort-array
  */
 function sortArray (arr, options = {}) {
   options = Object.assign(
-    { computed: {}, customOrders: {} },
+    {
+      computed: {},
+      customOrders: {},
+      nullRank: 1,
+      undefinedRank: 1
+    },
     options
   )
   arr.sort(getCompareFunc(options))
@@ -69,13 +76,13 @@ function getCompareFunc (options = {}) {
           ? 1
           : 0
     } else if (t.isNull(x) && t.isDefinedValue(y)) {
-      result = 1
+      result = options.nullRank
     } else if (t.isUndefined(x) && t.isDefinedValue(y)) {
-      result = 1
+      result = options.undefinedRank
     } else if (t.isNull(y) && t.isDefinedValue(x)) {
-      result = -1
+      result = -options.nullRank
     } else if (t.isUndefined(y) && t.isDefinedValue(x)) {
-      result = -1
+      result = -options.undefinedRank
     } else {
       result = x < y ? -1 : x > y ? 1 : 0
       if (currOrder === 'desc') {

test/sort-falsy.mjs

@@ -169,6 +169,126 @@ async function getTom () {
     a.deepStrictEqual(result, expected)
   })
 
+  tom.test('nullRank: -1', function () {
+    const fixture = [
+      { a: 4, b: null, c: 3 },
+      { a: 4, b: 2, c: null },
+      { a: 2, b: 2, c: 3 },
+      { a: 2, b: 2, c: 2 },
+      { a: null, b: 3, c: 4 },
+      { a: null, b: null, c: 4 },
+      { a: null, b: 2, c: 4 },
+      { a: 3, b: 3, c: 3 },
+      { a: 4, b: 3, c: null }
+    ]
+    const expected = [
+      { a: null, b: null, c: 4 },
+      { a: null, b: 2, c: 4 },
+      { a: null, b: 3, c: 4 },
+      { a: 2, b: 2, c: 2 },
+      { a: 2, b: 2, c: 3 },
+      { a: 3, b: 3, c: 3 },
+      { a: 4, b: null, c: 3 },
+      { a: 4, b: 2, c: null },
+      { a: 4, b: 3, c: null },
+    ]
+
+    const by = ['a', 'b', 'c']
+    const order = ['asc', 'asc', 'asc']
+    const result = sortArray(fixture, { by, order, nullRank: -1 })
+    a.deepStrictEqual(result, expected)
+  })
+
+  tom.test('nullRank: 1', function () {
+    const fixture = [
+      { a: 4, b: null, c: 3 },
+      { a: 4, b: 2, c: null },
+      { a: 2, b: 2, c: 3 },
+      { a: 2, b: 2, c: 2 },
+      { a: null, b: 3, c: 4 },
+      { a: null, b: null, c: 4 },
+      { a: null, b: 2, c: 4 },
+      { a: 3, b: 3, c: 3 },
+      { a: 4, b: 3, c: null }
+    ]
+    const expected = [
+      { a: 2, b: 2, c: 2 },
+      { a: 2, b: 2, c: 3 },
+      { a: 3, b: 3, c: 3 },
+      { a: 4, b: 2, c: null },
+      { a: 4, b: 3, c: null },
+      { a: 4, b: null, c: 3 },
+      { a: null, b: 2, c: 4 },
+      { a: null, b: 3, c: 4 },
+      { a: null, b: null, c: 4 },
+    ]
+
+    const by = ['a', 'b', 'c']
+    const order = ['asc', 'asc', 'asc']
+    const result = sortArray(fixture, { by, order, nullRank: 1 })
+    a.deepStrictEqual(result, expected)
+  })
+
+  tom.test('undefinedRank: -1', function () {
+    const fixture = [
+      { a: 4, b: undefined, c: 3 },
+      { a: 4, b: 2, c: undefined },
+      { a: 2, b: 2, c: 3 },
+      { a: 2, b: 2, c: 2 },
+      { a: undefined, b: 3, c: 4 },
+      { a: undefined, b: undefined, c: 4 },
+      { a: undefined, b: 2, c: 4 },
+      { a: 3, b: 3, c: 3 },
+      { a: 4, b: 3, c: undefined }
+    ]
+    const expected = [
+      { a: undefined, b: undefined, c: 4 },
+      { a: undefined, b: 2, c: 4 },
+      { a: undefined, b: 3, c: 4 },
+      { a: 2, b: 2, c: 2 },
+      { a: 2, b: 2, c: 3 },
+      { a: 3, b: 3, c: 3 },
+      { a: 4, b: undefined, c: 3 },
+      { a: 4, b: 2, c: undefined },
+      { a: 4, b: 3, c: undefined },
+    ]
+
+    const by = ['a', 'b', 'c']
+    const order = ['asc', 'asc', 'asc']
+    const result = sortArray(fixture, { by, order, undefinedRank: -1 })
+    a.deepStrictEqual(result, expected)
+  })
+
+  tom.test('undefinedRank: 1', function () {
+    const fixture = [
+      { a: 4, b: undefined, c: 3 },
+      { a: 4, b: 2, c: undefined },
+      { a: 2, b: 2, c: 3 },
+      { a: 2, b: 2, c: 2 },
+      { a: undefined, b: 3, c: 4 },
+      { a: undefined, b: undefined, c: 4 },
+      { a: undefined, b: 2, c: 4 },
+      { a: 3, b: 3, c: 3 },
+      { a: 4, b: 3, c: undefined }
+    ]
+    const expected = [
+      { a: 2, b: 2, c: 2 },
+      { a: 2, b: 2, c: 3 },
+      { a: 3, b: 3, c: 3 },
+      { a: 4, b: 2, c: undefined },
+      { a: 4, b: 3, c: undefined },
+      { a: 4, b: undefined, c: 3 },
+      { a: undefined, b: 2, c: 4 },
+      { a: undefined, b: 3, c: 4 },
+      { a: undefined, b: undefined, c: 4 },
+    ]
+
+    const by = ['a', 'b', 'c']
+    const order = ['asc', 'asc', 'asc']
+    const result = sortArray(fixture, { by, order, undefinedRank: 1 })
+    a.deepStrictEqual(result, expected)
+  })
+
   return tom
 }