Add jsonSortOrder option

An option has been added to specify a custom sort order using a JSON
file.

README.md

@@ -76,6 +76,39 @@ Sort JSON objects recursively, including all nested objects. This also sorts obj
 | ------- | ----------------------- | --------------------------- |
 | `false` | `--json-recursive-sort` | `jsonRecursiveSort: <bool>` |
 
+### JSON Sort Order
+
+Use a custom sort order. This order is specified using a JSON file that maps exact strings or regular expressions to sorting algorithms.
+
+| Default | CLI                        | Configuration           |
+| ------- | -------------------------- | ----------------------- |
+| `""`    | `--json-sort-order <path>` | `jsonSortOrder: <path>` |
+
+Here is an example JSON sort order file:
+
+```json
+{
+  "placeThisFirst": null,
+  "/^[^\\d+]/": "lexical",
+  "/^\\d+/": "numeric"
+}
+```
+
+This file sorts the key "placeThisFirst" ahead of all others. After that, the set of all keys that _don't_ start with a number are sorted lexically. Lastly, the set of keys that start with a number are sorted numerically.
+
+Each key represents a literal key value or a _category_ of keys, represented by a regular expression. Regular expressions are identified by leading and trailing forward slashes, along with some number of paths optionally following the trailing slash (supported flags are `i`, `m`, `s`, and `u`).
+
+Each category is ordered in relation to other categories. Each value represents the sorting algorithm to use _within_ that category. If the value is `null`, the default sorting algorithm `lexical` is used. Here are the supported sorting algorithms:
+
+| Sorting Algorithm | Description                                                                                                 |
+| ----------------- | ----------------------------------------------------------------------------------------------------------- |
+| `lexical`         | Sort lexically (i.e. lexicographically). This is the default.                                               |
+| `numeric`         | For keys that are prefixed with a number, sort by that number in ascending order. Otherwise sort lexically. |
+| `reverseLexical`  | Reverse-order lexical sort.                                                                                 |
+| `reverseNumeric`  | Reverse-order numeric sort.                                                                                 |
+
+Keys that do not match any defined category are treated as being in an implied last category, with `lexical` sorting.
+
 ## Contributing
 
 ### Setup

fixtures/complex-sort.json

@@ -0,0 +1,8 @@
+{
+  "first": null,
+  "/^0\\d+/": "reverseNumeric",
+  "/^\\d+/": "numeric",
+  "/^a/": "reverseLexical",
+  "/^b/": null,
+  "last": null
+}

fixtures/invalid-array.json

@@ -0,0 +1 @@
+[]

fixtures/invalid-category-sort.json

@@ -0,0 +1,3 @@
+{
+  "first": "imaginarySort"
+}

fixtures/invalid-json.json

@@ -0,0 +1 @@
+{

fixtures/numeric-sort.json

@@ -0,0 +1,3 @@
+{
+  "/.+/u": "numeric"
+}

fixtures/simple-sort.json

@@ -0,0 +1,3 @@
+{
+  "first": null
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "prettier-plugin-sort-json",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Prettier plugin to sort JSON files alphanumerically by key",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
     "lint": "yarn lint:eslint && yarn lint:misc --check",
     "lint:eslint": "eslint . --cache --ext js,ts",
     "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write",
-    "lint:misc": "prettier '**/*.json' '**/*.md' '!CHANGELOG.md' '**/*.yml' '!.yarnrc.yml' --ignore-path .gitignore",
+    "lint:misc": "prettier '**/*.json' '**/*.md' '!CHANGELOG.md' '**/*.yml' '!.yarnrc.yml' '!fixtures/invalid-json.json' --ignore-path .gitignore",
     "prepack": "yarn build",
     "test": "jest",
     "test:watch": "jest --watch"

src/__snapshots__/index.test.ts.snap

@@ -1,5 +1,113 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`Sort JSON complex custom sort should sort an unsorted JSON object 1`] = `
+"{
+  \\"3\\": null,
+  \\"20\\": null,
+  \\"100\\": null,
+  \\"first\\": \\"first\\",
+  \\"050\\": null,
+  \\"021\\": null,
+  \\"001\\": null,
+  \\"a2\\": null,
+  \\"a1\\": null,
+  \\"b1\\": null,
+  \\"b2\\": null,
+  \\"exampleNestedObject\\": {
+    \\"3\\": null,
+    \\"20\\": null,
+    \\"100\\": null,
+    \\"z\\": null,
+    \\"exampleArray\\": [\\"z\\", \\"b\\", \\"a\\"],
+    \\"001\\": null,
+    \\"examplePrimitive\\": 1,
+    \\"021\\": null,
+    \\"a\\": null,
+    \\"050\\": null
+  },
+  \\"z\\": null
+}
+"
+`;
+
+exports[`Sort JSON complex custom sort should validate a sorted JSON object 1`] = `
+"{
+  \\"0\\": null,
+  \\"3\\": null,
+  \\"20\\": null,
+  \\"100\\": null,
+  \\"first\\": \\"first\\",
+  \\"050\\": null,
+  \\"021\\": null,
+  \\"001\\": null,
+  \\"a2\\": null,
+  \\"a1\\": null,
+  \\"b1\\": null,
+  \\"b2\\": null,
+  \\"b3\\": null,
+  \\"exampleNestedObject\\": {
+    \\"3\\": null,
+    \\"20\\": null,
+    \\"100\\": null,
+    \\"050\\": null,
+    \\"021\\": null,
+    \\"001\\": null,
+    \\"z\\": null,
+    \\"exampleArray\\": [\\"z\\", \\"b\\", \\"a\\"],
+    \\"examplePrimitive\\": 1,
+    \\"a\\": null
+  },
+  \\"z\\": null
+}
+"
+`;
+
+exports[`Sort JSON numeric custom sort should sort an unsorted JSON object 1`] = `
+"{
+  \\"0\\": null,
+  \\"3\\": null,
+  \\"20\\": null,
+  \\"100\\": null,
+  \\"a\\": null,
+  \\"b\\": null,
+  \\"exampleNestedObject\\": {
+    \\"3\\": null,
+    \\"20\\": null,
+    \\"100\\": null,
+    \\"z\\": null,
+    \\"exampleArray\\": [\\"z\\", \\"b\\", \\"a\\"],
+    \\"examplePrimitive\\": 1,
+    \\"a\\": null
+  },
+  \\"first\\": \\"first\\",
+  \\"z\\": null
+}
+"
+`;
+
+exports[`Sort JSON numeric custom sort should validate a sorted JSON object 1`] = `
+"{
+  \\"0\\": null,
+  \\"3\\": null,
+  \\"20\\": null,
+  \\"100\\": null,
+  \\"a\\": null,
+  \\"b\\": null,
+  \\"exampleNestedObject\\": {
+    \\"3\\": null,
+    \\"20\\": null,
+    \\"100\\": null,
+    \\"z\\": null,
+    \\"exampleArray\\": [\\"z\\", \\"b\\", \\"a\\"],
+    \\"examplePrimitive\\": 1,
+    \\"a\\": null
+  },
+  \\"first\\": \\"first\\",
+  \\"z\\": null
+}
+"
+`;
+
 exports[`Sort JSON should sort JSON objects recursively within a nested array 1`] = `
 "{
   \\"0\\": null,
@@ -277,3 +385,37 @@ exports[`Sort JSON should validate a sorted JSON object within an array recursiv
 ]
 "
 `;
+
+exports[`Sort JSON simple custom sort should sort an unsorted JSON object 1`] = `
+"{
+  \\"0\\": null,
+  \\"first\\": \\"first\\",
+  \\"a\\": null,
+  \\"b\\": null,
+  \\"exampleNestedObject\\": {
+    \\"z\\": null,
+    \\"exampleArray\\": [\\"z\\", \\"b\\", \\"a\\"],
+    \\"examplePrimitive\\": 1,
+    \\"a\\": null
+  },
+  \\"z\\": null
+}
+"
+`;
+
+exports[`Sort JSON simple custom sort should validate a sorted JSON object 1`] = `
+"{
+  \\"0\\": null,
+  \\"first\\": \\"first\\",
+  \\"a\\": null,
+  \\"b\\": null,
+  \\"exampleNestedObject\\": {
+    \\"z\\": null,
+    \\"exampleArray\\": [\\"z\\", \\"b\\", \\"a\\"],
+    \\"examplePrimitive\\": 1,
+    \\"a\\": null
+  },
+  \\"z\\": null
+}
+"
+`;