feat(ts-definitions): Improve TypeScript definitions, add tests for types

Author: BendingBender

.npmrc

@@ -0,0 +1 @@
+package-lock=false

index.d.ts

@@ -1,4 +1,20 @@
-declare module 'fast-json-stable-stringify' {
-  function stringify(obj: any): string;
-  export = stringify;
+export = stringify;
+
+declare function stringify(
+  obj: any,
+  options?: stringify.Options | stringify.Comparator
+): string;
+
+declare namespace stringify {
+  interface Options {
+    cmp?: Comparator;
+    cycles?: boolean;
+  }
+
+  type Comparator = (a: CompareDescriptor, b: CompareDescriptor) => number;
+
+  interface CompareDescriptor {
+    key: string;
+    value: any;
+  }
 }

package.json

@@ -14,12 +14,14 @@
     "json-stable-stringify": "latest",
     "nyc": "^14.1.0",
     "pre-commit": "^1.2.2",
-    "tape": "^4.11.0"
+    "tape": "^4.11.0",
+    "tsd": "^0.15.1"
   },
   "scripts": {
     "eslint": "eslint index.js test",
     "test-spec": "tape test/*.js",
-    "test": "npm run eslint && nyc npm run test-spec"
+    "test-types": "tsd",
+    "test": "npm run eslint && nyc npm run test-spec && npm run test-types"
   },
   "repository": {
     "type": "git",
@@ -49,6 +51,15 @@
       "text-summary"
     ]
   },
+  "tsd": {
+    "directory": "test",
+    "compilerOptions": {
+      "lib": [
+        "es2015"
+      ],
+      "skipLibCheck": true
+    }
+  },
   "engines": {
     "node": ">=8"
   }

test/index.test-d.ts

@@ -0,0 +1,28 @@
+import { expectType } from "tsd";
+import stringify = require("../index");
+
+// test type exports
+type CompareDescriptor = stringify.CompareDescriptor;
+type Comparator = stringify.Comparator;
+type Options = stringify.Options;
+
+const obj = { c: 8, b: [{ z: 6, y: 5, x: 4 }, 7], a: 3 };
+
+expectType<string>(stringify(obj));
+expectType<string>(
+  stringify(obj, (a, b) => {
+    expectType<CompareDescriptor>(a);
+    expectType<CompareDescriptor>(b);
+    return a.key < b.key ? 1 : -1;
+  })
+);
+expectType<string>(
+  stringify(obj, {
+    cmp(a, b) {
+      expectType<CompareDescriptor>(a);
+      expectType<CompareDescriptor>(b);
+      return a.key < b.key ? 1 : -1;
+    },
+  })
+);
+expectType<string>(stringify(obj, { cycles: true }));