Added byDefault function

package.json

@@ -31,6 +31,7 @@
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-react": "^7.33.2",
+    "fast-check": "^3.13.1",
     "husky": "^8.0.3",
     "mocha": "^10.2.0",
     "nyc": "^15.1.0",

src/interfaces/interfaces.ts

@@ -1,15 +1,37 @@
 import {datable} from "../types/types";
 
 export interface SortOption {
+    /** 
+     * Sort in descending order if true.
+     *
+     * Using a descending sorter is generally not the same as reversing an array
+     * after sorting it, doing so breaks the stability of the sort function, and
+     * because `Array.sort` always puts `undefined` last, regardless of the
+     * comparator function in use.
+     */
     desc?: boolean;
+
+    /**
+     * If true, treat `null` or `undefined` like 0, "", etc.  Not all sorters
+     * honor this option.
+     *
+     * This option doesn't always work correctly with `Array.sort`, which always
+     * puts `undefined` last.
+     */
     nullable?: boolean;
 }
 
 export interface SortByStringOption extends SortOption {
+    /**
+     * If true, puts the strings to lowercase before comparising them.
+     */
     lowercase?: boolean;
 }
 
 export interface SortByDateOption extends SortOption {
+    /**
+     * A custom date parser.
+     */
     customParser?: (item: datable) => Date;
 }
 

src/sortables/byAny.ts

@@ -5,6 +5,14 @@ import byString from "../sortables/byString";
 import { SortOption } from "../interfaces/interfaces";
 import { isDate, isNumber, isString } from "../utils/typeCheck";
 
+/**
+ * the sortable that works on **`number`, `string`, and `Date` values**,
+ * provided the types are not mixed
+ * @param options the options to sort the values
+ *
+ * {@link https://sort-es.netlify.app/by-default byDefault docs}
+ * @version 1.8.0
+ */
 const byAny = <T extends string | number | Date>(
   options: SortOption = { desc: false }
 ): sortable<T> => {

src/sortables/byDefault.ts

@@ -0,0 +1,40 @@
+import { SortOption } from "src/interfaces/interfaces";
+import { sortable, sortableWithOption } from "../types/types";
+
+/**
+ * the sortable which sorts the same as `Array.sort` with no comparator
+ * @param options used to specify whether the sort is descending; the `nullable` setting is ignored
+ *
+ * {@link https://sort-es.netlify.app/by-default byDefault docs}
+ * @version 1.8.0
+ */
+const byDefault: sortableWithOption<unknown, Omit<SortOption, "nullable">> = ({
+  desc = false,
+} = {}): sortable<unknown> => {
+  const sign = desc ? -1 : 1;
+  return (x: unknown, y: unknown): number => {
+    if (x === undefined) {
+      if (y === undefined) {
+        return 0;
+      } else {
+        return 1;
+      }
+    }
+    if (y === undefined) {
+      return -1;
+    }
+    const xString = String(x);
+    const yString = String(y);
+    const xSmaller = xString < yString;
+    if (xSmaller) {
+      return -sign;
+    }
+    const ySmaller = yString < xString;
+    if (ySmaller) {
+      return sign;
+    }
+    return 0;
+  };
+};
+
+export default byDefault;

test/byDefault.spec.ts

@@ -0,0 +1,78 @@
+import "mocha";
+import { expect } from "chai";
+import byDefault from "../src/sortables/byDefault";
+import fc from "fast-check";
+
+const somePrimitive: fc.Arbitrary<unknown> = fc.oneof(
+  fc.float(),
+  fc.string(),
+  fc.boolean(),
+  fc.bigIntN(64),
+  fc.constantFrom(null, undefined)
+);
+
+const someSortable: fc.Arbitrary<unknown> = fc.oneof(
+  somePrimitive,
+  somePrimitive.map((p) => ({
+    toString: undefined,
+    valueOf(): unknown {
+      return p;
+    },
+  })),
+  somePrimitive.map((p) => ({
+    valueOf: undefined,
+    toString(): unknown {
+      return p;
+    },
+  }))
+);
+
+describe("byDefault", () => {
+  it(`Treats undefined as equal to itself`, () => {
+    fc.assert(
+      fc.property(fc.boolean(), (desc) => {
+        expect(byDefault({ desc })(undefined, undefined)).equals(0);
+      })
+    );
+  });
+
+  it(`Treats undefined as greater than anything else`, () => {
+    fc.assert(
+      fc.property(
+        fc.boolean(),
+        someSortable.filter((x) => x !== undefined),
+        (desc, x) => {
+          const cmp = byDefault({ desc });
+          expect(cmp(x, undefined)).is.below(0);
+          expect(cmp(undefined, x)).is.above(0);
+        }
+      )
+    );
+  });
+
+  it("Works the same as the default sort order", () => {
+    fc.assert(
+      fc.property(someSortable, someSortable, (x, y) => {
+        const a1 = [x, y].sort(byDefault());
+        const a2 = [x, y].sort();
+        expect(a1).deep.equals(a2);
+      })
+    );
+  });
+
+  it("Works in descending mode", () => {
+    fc.assert(
+      fc.property(someSortable, someSortable, (x, y) => {
+        const a1 = [x, y];
+        a1.sort(byDefault({ desc: true }));
+        if (x === undefined) {
+          expect(a1).deep.equals([y, undefined]);
+        } else if (y === undefined) {
+          expect(a1).deep.equals([x, undefined]);
+        } else {
+          expect(a1).deep.equals([x, y].reverse().sort().reverse());
+        }
+      })
+    );
+  });
+});

yarn.lock

@@ -1859,6 +1859,13 @@ execa@^7.1.1:
     signal-exit "^3.0.7"
     strip-final-newline "^3.0.0"
 
+fast-check@^3.13.1:
+  version "3.13.1"
+  resolved "https://domoreexp.pkgs.visualstudio.com/_packaging/npm-mirror/npm/registry/fast-check/-/fast-check-3.13.1.tgz#32c7a78621098bd30d71e40c0e269a728a3188e2"
+  integrity sha1-MsenhiEJi9MNceQMDiaacooxiOI=
+  dependencies:
+    pure-rand "^6.0.0"
+
 fast-deep-equal@^3.1.1, fast-deep-equal@^3.1.3:
   version "3.1.3"
   resolved "https://registry.yarnpkg.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz#3a7d56b559d6cbc3eb512325244e619a65c6c525"
@@ -3436,6 +3443,11 @@ punycode@^2.1.0:
   resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.3.0.tgz#f67fa67c94da8f4d0cfff981aee4118064199b8f"
   integrity sha512-rRV+zQD8tVFys26lAGR9WUuS4iUAngJScM+ZRSKtvl5tKeZ2t5bvdNFdNHBW9FWR4guGHlgmsZ1G7BSm2wTbuA==
 
+pure-rand@^6.0.0:
+  version "6.0.4"
+  resolved "https://domoreexp.pkgs.visualstudio.com/_packaging/npm-mirror/npm/registry/pure-rand/-/pure-rand-6.0.4.tgz#50b737f6a925468679bff00ad20eade53f37d5c7"
+  integrity sha1-ULc39qklRoZ5v/AK0g6t5T831cc=
+
 queue-microtask@^1.2.2:
   version "1.2.3"
   resolved "https://registry.yarnpkg.com/queue-microtask/-/queue-microtask-1.2.3.tgz#4929228bbc724dfac43e0efb058caf7b6cfb6243"