[New] add types

Author: ljharb

.eslintrc

@@ -5,6 +5,7 @@
 
 	"rules": {
 		"consistent-return": 1,
+		"max-len": 0,
 		"max-lines-per-function": 0,
 		"max-params": 1,
 		"max-statements-per-line": [2, { "max": 2 }],

example/value_cmp.js

@@ -4,7 +4,8 @@ var stringify = require('../');
 
 var obj = { d: 6, c: 5, b: [{ z: 3, y: 2, x: 1 }, 9], a: 10 };
 
-var s = stringify(obj, function (a, b) {
+var s = stringify(obj, /** @type {import('..').Comparator} */ function (a, b) {
+	// @ts-expect-error implicit coercion here is fine
 	return a.value < b.value ? 1 : -1;
 });
 

index.d.ts

@@ -0,0 +1,24 @@
+declare namespace stableStringify {
+    type Key = string | number;
+
+    type NonArrayNode = Record<Key, unknown>;
+    type Node = unknown[] | NonArrayNode;
+
+    type Getter = { get(key: Key): unknown };
+
+    type Comparator = (a: { key: string, value: unknown }, b: { key: string, value: unknown }, getter: Getter) => number;
+
+    type StableStringifyOptions = {
+        cmp?: Comparator;
+        cycles?: boolean;
+        replacer?: (this: Node, key: Key, value: unknown) => unknown;
+        space?: string | number;
+    };
+}
+
+declare function stableStringify(
+    obj: object,
+    options?: (stableStringify.Comparator & stableStringify.StableStringifyOptions) | stableStringify.StableStringifyOptions,
+): string | undefined;
+
+export = stableStringify;

index.js

@@ -1,5 +1,6 @@
 'use strict';
 
+/** @type {typeof JSON.stringify} */
 var jsonStringify = (typeof JSON !== 'undefined' ? JSON : require('jsonify')).stringify;
 
 var isArray = require('isarray');
@@ -12,6 +13,7 @@ var $indexOf = callBound('Array.prototype.indexOf');
 var $splice = callBound('Array.prototype.splice');
 var $sort = callBound('Array.prototype.sort');
 
+/** @type {(n: number, char: string) => string} */
 var strRepeat = function repeat(n, char) {
 	var str = '';
 	for (var i = 0; i < n; i += 1) {
@@ -20,35 +22,47 @@ var strRepeat = function repeat(n, char) {
 	return str;
 };
 
-var defaultReplacer = function (parent, key, value) { return value; };
+/** @type {(parent: import('.').Node, key: import('.').Key, value: unknown) => unknown} */
+var defaultReplacer = function (_parent, _key, value) { return value; };
 
+/** @type {import('.')} */
 module.exports = function stableStringify(obj) {
+	/** @type {Parameters<import('.')>[1]} */
 	var opts = arguments.length > 1 ? arguments[1] : void undefined;
 	var space = (opts && opts.space) || '';
 	if (typeof space === 'number') { space = strRepeat(space, ' '); }
 	var cycles = !!opts && typeof opts.cycles === 'boolean' && opts.cycles;
+	/** @type {undefined | typeof defaultReplacer} */
 	var replacer = opts && opts.replacer ? callBind(opts.replacer) : defaultReplacer;
 
 	var cmpOpt = typeof opts === 'function' ? opts : opts && opts.cmp;
+	/** @type {undefined | (<T extends import('.').NonArrayNode>(node: T) => (a: Exclude<keyof T, symbol | number>, b: Exclude<keyof T, symbol | number>) => number)} */
 	var cmp = cmpOpt && function (node) {
-		var get = cmpOpt.length > 2 && function get(k) { return node[k]; };
+		// eslint-disable-next-line no-extra-parens
+		var get = /** @type {NonNullable<typeof cmpOpt>} */ (cmpOpt).length > 2
+			&& /** @type {import('.').Getter['get']} */ function get(k) { return node[k]; };
 		return function (a, b) {
-			return cmpOpt(
+			// eslint-disable-next-line no-extra-parens
+			return /** @type {NonNullable<typeof cmpOpt>} */ (cmpOpt)(
 				{ key: a, value: node[a] },
 				{ key: b, value: node[b] },
-				get ? { __proto__: null, get: get } : void undefined
+				// @ts-expect-error TS doesn't understand the optimization used here
+				get ? /** @type {import('.').Getter} */ { __proto__: null, get: get } : void undefined
 			);
 		};
 	};
 
+	/** @type {import('.').Node[]} */
 	var seen = [];
-	return (
+	return (/** @type {(parent: import('.').Node, key: string | number, node: unknown, level: number) => string | undefined} */
 		function stringify(parent, key, node, level) {
 			var indent = space ? '\n' + strRepeat(level, space) : '';
 			var colonSeparator = space ? ': ' : ':';
 
-			if (node && node.toJSON && typeof node.toJSON === 'function') {
-				node = node.toJSON();
+			// eslint-disable-next-line no-extra-parens
+			if (node && /** @type {{ toJSON?: unknown }} */ (node).toJSON && typeof /** @type {{ toJSON?: unknown }} */ (node).toJSON === 'function') {
+				// eslint-disable-next-line no-extra-parens
+				node = /** @type {{ toJSON: Function }} */ (node).toJSON();
 			}
 
 			node = replacer(parent, key, node);
@@ -72,14 +86,17 @@ module.exports = function stableStringify(obj) {
 				if (cycles) { return jsonStringify('__cycle__'); }
 				throw new TypeError('Converting circular structure to JSON');
 			} else {
-				seen[seen.length] = node;
+				seen[seen.length] = /** @type {import('.').NonArrayNode} */ (node);
 			}
 
-			var keys = $sort(objectKeys(node), cmp && cmp(node));
+			/** @type {import('.').Key[]} */
+			// eslint-disable-next-line no-extra-parens
+			var keys = $sort(objectKeys(node), cmp && cmp(/** @type {import('.').NonArrayNode} */ (node)));
 			var out = [];
 			for (var i = 0; i < keys.length; i++) {
 				var key = keys[i];
-				var value = stringify(node, key, node[key], level + 1);
+				// eslint-disable-next-line no-extra-parens
+				var value = stringify(/** @type {import('.').Node} */ (node), key, /** @type {import('.').NonArrayNode} */ (node)[key], level + 1);
 
 				if (!value) { continue; }
 
@@ -91,7 +108,6 @@ module.exports = function stableStringify(obj) {
 			}
 			$splice(seen, $indexOf(seen, node), 1);
 			return '{' + $join(out, ',') + indent + '}';
-
 		}({ '': obj }, '', obj, 0)
 	);
 };

package.json

@@ -8,6 +8,7 @@
 		"prepublishOnly": "safe-publish-latest",
 		"prepublish": "not-in-publish || npm run prepublishOnly",
 		"lint": "eslint --ext=js,mjs .",
+		"postlint": "tsc && attw -P",
 		"pretest": "npm run lint",
 		"tests-only": "tape 'test/**/*.js'",
 		"test": "npm run tests-only",
@@ -48,14 +49,21 @@
 		"object-keys": "^1.1.1"
 	},
 	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.17.1",
 		"@ljharb/eslint-config": "^21.1.1",
+		"@ljharb/tsconfig": "^0.2.2",
+		"@types/call-bind": "^1.0.5",
+		"@types/isarray": "^2.0.3",
+		"@types/object-keys": "^1.0.3",
+		"@types/tape": "^5.7.0",
 		"auto-changelog": "^2.5.0",
 		"encoding": "^0.1.13",
 		"eslint": "=8.8.0",
 		"in-publish": "^2.0.1",
 		"npmignore": "^0.3.1",
 		"safe-publish-latest": "^2.0.0",
-		"tape": "^5.9.0"
+		"tape": "^5.9.0",
+		"typescript": "next"
 	},
 	"engines": {
 		"node": ">= 0.4"
@@ -73,7 +81,8 @@
 	},
 	"publishConfig": {
 		"ignore": [
-			".github/workflows"
+			".github/workflows",
+			"types"
 		]
 	}
 }

test/cmp.js

@@ -15,14 +15,17 @@ test('custom comparison function', function (t) {
 test('custom comparison function with get', function (t) {
 	t.plan(2);
 
-	stringify({ a: 1, b: 2 }, function (a, b) { // eslint-disable-line no-unused-vars
+	stringify({ a: 1, b: 2 }, /** @type {import('..').Comparator} */ function (_a, _b) { // eslint-disable-line no-unused-vars
 		t.equal(arguments[2], undefined, 'comparator options not passed when not explicitly requested');
+		return NaN;
 	});
 
 	var obj = { c: 8, b: [{ z: 7, y: 6, x: 4, v: 2, '!v': 3 }, 7], a: 3 };
 	var s = stringify(obj, function (a, b, options) {
 		var get = options.get;
+		// @ts-expect-error implicit coercion here is fine
 		var v1 = (get('!' + a.key) || 0) + a.value;
+		// @ts-expect-error implicit coercion here is fine
 		var v2 = (get('!' + b.key) || 0) + b.value;
 		return v1 - v2;
 	});

test/nested.js

@@ -11,19 +11,23 @@ test('nested', function (t) {
 
 test('cyclic (default)', function (t) {
 	t.plan(1);
-	var one = { a: 1 };
+	var one = { a: 1, two: {} };
 	var two = { a: 2, one: one };
 	one.two = two;
 	try {
 		stringify(one);
 	} catch (ex) {
-		t.equal(ex.toString(), 'TypeError: Converting circular structure to JSON');
+		if (ex == null) { // eslint-disable-line eqeqeq
+			t.fail('nullish exception');
+		} else {
+			t.equal(ex.toString(), 'TypeError: Converting circular structure to JSON');
+		}
 	}
 });
 
 test('cyclic (specifically allowed)', function (t) {
 	t.plan(1);
-	var one = { a: 1 };
+	var one = { a: 1, two: {} };
 	var two = { a: 2, one: one };
 	one.two = two;
 	t.equal(stringify(one, { cycles: true }), '{"a":1,"two":{"a":2,"one":"__cycle__"}}');

test/replacer.js

@@ -16,7 +16,8 @@ test('replace numbers', function (t) {
 	t.plan(1);
 
 	var obj = { a: 1, b: 2, c: false };
-	var replacer = function (key, value) {
+	/** @type {import('..').StableStringifyOptions['replacer']} */
+	var replacer = function (_key, value) {
 		if (value === 1) { return 'one'; }
 		if (value === 2) { return 'two'; }
 		return value;
@@ -29,6 +30,7 @@ test('replace with object', function (t) {
 	t.plan(1);
 
 	var obj = { a: 1, b: 2, c: false };
+	/** @type {import('..').StableStringifyOptions['replacer']} */
 	var replacer = function (key, value) {
 		if (key === 'b') { return { d: 1 }; }
 		if (value === 1) { return 'one'; }
@@ -42,7 +44,8 @@ test('replace with undefined', function (t) {
 	t.plan(1);
 
 	var obj = { a: 1, b: 2, c: false };
-	var replacer = function (key, value) {
+	/** @type {import('..').StableStringifyOptions['replacer']} */
+	var replacer = function (_key, value) {
 		if (value === false) { return; }
 		return value;
 	};
@@ -54,6 +57,7 @@ test('replace with array', function (t) {
 	t.plan(1);
 
 	var obj = { a: 1, b: 2, c: false };
+	/** @type {import('..').StableStringifyOptions['replacer']} */
 	var replacer = function (key, value) {
 		if (key === 'b') { return ['one', 'two']; }
 		return value;
@@ -66,7 +70,8 @@ test('replace array item', function (t) {
 	t.plan(1);
 
 	var obj = { a: 1, b: 2, c: [1, 2] };
-	var replacer = function (key, value) {
+	/** @type {import('..').StableStringifyOptions['replacer']} */
+	var replacer = function (_key, value) {
 		if (value === 1) { return 'one'; }
 		if (value === 2) { return 'two'; }
 		return value;

test/space.js

@@ -74,6 +74,7 @@ test('space parameter (same as native)', function (t) {
 test('space parameter, on a cmp function', function (t) {
 	t.plan(3);
 	var obj = { one: 1, two: 2 };
+	/** @type {import('..').Comparator & import('../').StableStringifyOptions} */
 	var cmp = function (a, b) {
 		return a < b ? 1 : -1;
 	};

tsconfig.json

@@ -0,0 +1,10 @@
+{
+	"extends": "@ljharb/tsconfig",
+	"compilerOptions": {
+		"maxNodeModuleJsDepth": 0,
+		"target": "es2021",
+	},
+	"exclude": [
+		"coverage",
+	],
+}