feat: add TypeScript definitions

Author: bjohansebas

.github/workflows/ci.yml

@@ -205,6 +205,9 @@ jobs:
           npm test
         fi
 
+    - name: Run type tests
+      run: npm run test-types
+
     - name: Lint code
       if: steps.list_env.outputs.eslint != ''
       run: npm run lint

index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * When ranges are returned, the array has a "type" property which is the type of
+ * range that is required (most commonly, "bytes"). Each array element is an object
+ * with a "start" and "end" property for the portion of the range.
+ *
+ * @returns `-1` when unsatisfiable and `-2` when syntactically invalid, ranges otherwise.
+ */
+declare function RangeParser(
+    size: number,
+    str: string,
+    options?: RangeParser.Options,
+): RangeParser.Result | RangeParser.Ranges;
+
+declare namespace RangeParser {
+    interface Ranges extends Array<Range> {
+        type: string;
+    }
+    interface Range {
+        start: number;
+        end: number;
+    }
+    interface Options {
+        /**
+         * The "combine" option can be set to `true` and overlapping & adjacent ranges
+         * will be combined into a single range.
+         */
+        combine?: boolean | undefined;
+    }
+    type ResultUnsatisfiable = -1;
+    type ResultInvalid = -2;
+    type Result = ResultUnsatisfiable | ResultInvalid;
+}
+
+export = RangeParser;

package.json

@@ -20,6 +20,7 @@
     "url": "https://opencollective.com/express"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
     "deep-equal": "1.0.1",
     "eslint": "6.0.1",
     "eslint-config-standard": "13.0.1",
@@ -28,21 +29,27 @@
     "eslint-plugin-node": "9.1.0",
     "eslint-plugin-promise": "4.2.1",
     "eslint-plugin-standard": "4.0.0",
+    "expect-type": "~1.2.0",
     "mocha": "6.1.4",
-    "nyc": "14.1.1"
+    "nyc": "14.1.1",
+    "typescript": "~5.9.2"
   },
   "files": [
-    "HISTORY.md",
+    "index.d.ts",
     "LICENSE",
     "index.js"
   ],
+  "type": "commonjs",
+  "main": "./index.js",
+  "typings": "./index.d.ts",
   "engines": {
     "node": ">= 0.6"
   },
   "scripts": {
     "lint": "eslint --plugin markdown --ext js,md .",
     "test": "mocha --reporter spec",
     "test-ci": "nyc --reporter=lcovonly --reporter=text npm test",
-    "test-cov": "nyc --reporter=html --reporter=text npm test"
+    "test-cov": "nyc --reporter=html --reporter=text npm test",
+    "test-types": "tsc && attw --pack"
   }
 }

test/types.ts

@@ -0,0 +1,9 @@
+import * as RangeParser from "../index.js";
+import { expectTypeOf } from "expect-type"
+
+expectTypeOf(RangeParser).toBeFunction();
+expectTypeOf(RangeParser).toEqualTypeOf<(
+    size: number,
+    str: string,
+    options?: RangeParser.Options,
+) => RangeParser.Result | RangeParser.Ranges>();

tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": [ "es2015" ],
+    "module": "commonjs",
+    "noEmit": true,
+    "strict": true
+  },
+  "include": [
+    "./test/**/*.ts",
+    "./**/*.d.ts"
+  ]
+}