Add TypeScript definition, bump dependencies, target Node.js 16 (#36)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

Author: tommy-mitchell

.github/workflows/main.yml

@@ -10,12 +10,11 @@ jobs:
       fail-fast: false
       matrix:
         node-version:
+          - 18
           - 16
-          - 14
-          - 12
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm install

index.d.ts

@@ -0,0 +1,121 @@
+import type {JsonObject} from 'type-fest';
+
+/**
+Exposed for `instanceof` checking.
+*/
+export type JSONError = Error & { // eslint-disable-line @typescript-eslint/naming-convention
+	/**
+	The filename displayed in the error message, if any.
+	*/
+	fileName: string;
+
+	/**
+	The printable section of the JSON which produces the error.
+	*/
+	readonly codeFrame: string;
+};
+
+// Get 'reviver' parameter from JSON.parse()
+type ReviverFn = Parameters<typeof JSON['parse']>['1'];
+
+/**
+Parse JSON with more helpful errors.
+
+@param string - A valid JSON string.
+@param reviver - Prescribes how the value originally produced by parsing is transformed, before being returned. See [`JSON.parse` docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Using_the_reviver_parameter
+) for more.
+@param filename - The filename displayed in the error message.
+@returns A parsed JSON object.
+@throws A {@link JSONError} when there is a parsing error.
+
+@example
+```
+import parseJson, {JSONError} from 'parse-json';
+
+const json = '{\n\t"foo": true,\n}';
+
+parseJson(json);
+// JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}'
+//
+//   1 | {
+//   2 |   "foo": true,
+// > 3 | }
+//     | ^
+
+parseJson(json, 'foo.json');
+// JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}' in foo.json
+//
+//   1 | {
+//   2 |   "foo": true,
+// > 3 | }
+//     | ^
+
+// You can also add the filename at a later point
+try {
+	parseJson(json);
+} catch (error) {
+	if (error instanceof JSONError) {
+		error.fileName = 'foo.json';
+	}
+
+	throw error;
+}
+// JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}' in foo.json
+//
+//   1 | {
+//   2 |   "foo": true,
+// > 3 | }
+//     | ^
+```
+*/
+export default function parseJson(string: string, reviver?: ReviverFn, filename?: string): JsonObject;
+
+/**
+Parse JSON with more helpful errors.
+
+@param string - A valid JSON string.
+@param filename - The filename displayed in the error message.
+@returns A parsed JSON object.
+@throws A {@link JSONError} when there is a parsing error.
+
+@example
+```
+import parseJson, {JSONError} from 'parse-json';
+
+const json = '{\n\t"foo": true,\n}';
+
+parseJson(json);
+// JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}'
+//
+//   1 | {
+//   2 |   "foo": true,
+// > 3 | }
+//     | ^
+
+parseJson(json, 'foo.json');
+// JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}' in foo.json
+//
+//   1 | {
+//   2 |   "foo": true,
+// > 3 | }
+//     | ^
+
+// You can also add the filename at a later point
+try {
+	parseJson(json);
+} catch (error) {
+	if (error instanceof JSONError) {
+		error.fileName = 'foo.json';
+	}
+
+	throw error;
+}
+// JSONError: Unexpected token } in JSON at position 16 while parsing near '{      "foo": true,}' in foo.json
+//
+//   1 | {
+//   2 |   "foo": true,
+// > 3 | }
+//     | ^
+```
+*/
+export default function parseJson(string: string, filename?: string): JsonObject;

index.test-d.ts

@@ -0,0 +1,38 @@
+import {expectType, expectError} from 'tsd';
+import type {JsonObject} from 'type-fest';
+import parseJson, {type JSONError} from './index.js';
+
+expectError(parseJson());
+expectError(parseJson({foo: true}));
+expectType<JsonObject>(parseJson('{"foo": true}'));
+expectType<JsonObject>(parseJson('{"foo": true}', 'foo.json'));
+expectType<JsonObject>(parseJson('{"foo": true}', (key, value) => String(value)));
+expectType<JsonObject>(parseJson('{"foo": true}', (key, value) => String(value), 'foo.json'));
+
+expectType<string>((() => {
+	let x: string;
+	parseJson('{"foo": true}', (key, value) => x = key); // eslint-disable-line no-return-assign
+	return x!;
+})());
+
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return */
+expectType<any>((() => {
+	let x: any;
+	parseJson('{"foo": true}', (key, value) => x = value); // eslint-disable-line no-return-assign
+	return x;
+})());
+/* eslint-enable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return */
+
+const jsonError: JSONError = {
+	name: 'JSONError',
+	message: 'Unexpected token } in JSON at position 16 while parsing near \'{      "foo": true,}\'',
+	fileName: 'foo.json',
+	codeFrame: `
+		  1 | {
+		  2 |   "foo": true,
+		> 3 | }
+			| ^
+	`,
+};
+
+expectError(jsonError.codeFrame = '');

package.json

@@ -13,13 +13,14 @@
 	"type": "module",
 	"exports": "./index.js",
 	"engines": {
-		"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+		"node": ">=16"
 	},
 	"scripts": {
-		"test": "xo && nyc ava"
+		"test": "xo && nyc ava && tsd"
 	},
 	"files": [
 		"index.js",
+		"index.d.ts",
 		"vendor"
 	],
 	"keywords": [
@@ -34,14 +35,16 @@
 		"string"
 	],
 	"dependencies": {
-		"@babel/code-frame": "^7.16.0",
+		"@babel/code-frame": "^7.21.4",
 		"error-ex": "^1.3.2",
-		"json-parse-even-better-errors": "^2.3.1",
-		"lines-and-columns": "^2.0.2"
+		"json-parse-even-better-errors": "^3.0.0",
+		"lines-and-columns": "^2.0.3",
+		"type-fest": "^3.8.0"
 	},
 	"devDependencies": {
-		"ava": "^3.15.0",
+		"ava": "^5.2.0",
 		"nyc": "^15.1.0",
-		"xo": "^0.46.4"
+		"tsd": "^0.28.1",
+		"xo": "^0.54.0"
 	}
 }