feat: add TypeScript definitions

.github/workflows/ci.yml

@@ -47,7 +47,7 @@ jobs:
         - name: Node.js 0.8
           node-version: "0.8"
           npm-i: mocha@2.5.3
-          npm-rm: nyc
+          npm-rm: nyc typescript @arethetypeswrong/cli expect-type
 
         - name: Node.js 0.10
           node-version: "0.10"
@@ -76,6 +76,8 @@ jobs:
         - name: Node.js 5.x
           node-version: "5.12"
           npm-i: mocha@5.2.0 nyc@11.9.0
+          # fixes https://github.com/npm/cli/issues/681
+          npm-version: "npm@3.10.10"
 
         - name: Node.js 6.x
           node-version: "6.17"
@@ -156,6 +158,10 @@ jobs:
         fi
         dirname "$(nvm which ${{ matrix.node-version }})" >> "$GITHUB_PATH"
 
+    - name: Npm version fixes
+      if: ${{matrix.npm-version != ''}}
+      run: npm install -g ${{ matrix.npm-version }}
+
     - name: Configure npm
       run: |
         if [[ "$(npm config get package-lock)" == "true" ]]; then
@@ -228,3 +234,19 @@ jobs:
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
         parallel-finished: true
+
+  test_typescript:
+    runs-on: 'ubuntu-latest'
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v6
+
+      - name: Install
+        run: |
+          npm install --ignore-scripts
+
+      - name: Run typescript tests
+        run: npm run test-types

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"
+  ]
+}