Add JSDoc based types

Author: wooorm

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+*.d.ts
 *.log
 coverage/
 node_modules/

index.js

@@ -1,5 +1,18 @@
 var own = {}.hasOwnProperty
 
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {import('unist').Position} Position
+ * @typedef {import('unist').Point} Point
+ */
+
+/**
+ * Stringify one point, a position (start and end points), or a node’s
+ * positional information.
+ *
+ * @param {Node|Position|Point} [value]
+ * @returns {string}
+ */
 export function stringifyPosition(value) {
   // Nothing.
   if (!value || typeof value !== 'object') {
@@ -8,31 +21,46 @@ export function stringifyPosition(value) {
 
   // Node.
   if (own.call(value, 'position') || own.call(value, 'type')) {
+    // @ts-ignore looks like a node.
     return position(value.position)
   }
 
   // Position.
   if (own.call(value, 'start') || own.call(value, 'end')) {
+    // @ts-ignore looks like a position.
     return position(value)
   }
 
   // Point.
   if (own.call(value, 'line') || own.call(value, 'column')) {
+    // @ts-ignore looks like a point.
     return point(value)
   }
 
   // ?
   return ''
 }
 
+/**
+ * @param {Point} point
+ * @returns {string}
+ */
 function point(point) {
   return index(point && point.line) + ':' + index(point && point.column)
 }
 
+/**
+ * @param {Position} pos
+ * @returns {string}
+ */
 function position(pos) {
   return point(pos && pos.start) + '-' + point(pos && pos.end)
 }
 
+/**
+ * @param {number} value
+ * @returns {number}
+ */
 function index(value) {
   return value && typeof value === 'number' ? value : 1
 }

package.json

@@ -28,33 +28,33 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
-  "types": "types/index.d.ts",
+  "types": "index.d.ts",
   "files": [
-    "types/index.d.ts",
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
     "@types/unist": "^2.0.0"
   },
   "devDependencies": {
-    "browserify": "^17.0.0",
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
-    "dtslint": "^4.0.0",
-    "nyc": "^15.0.0",
     "prettier": "^2.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
-    "tinyify": "^3.0.0",
+    "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
     "xo": "^0.38.0"
   },
   "scripts": {
+    "prepack": "npm run build && npm run format",
+    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
-    "test-types": "dtslint types",
-    "test": "npm run format && npm run test-coverage && npm run test-types"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -75,5 +75,10 @@
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -13,16 +13,23 @@ test('stringifyPosition', function (t) {
     'should return empty `string` with `null`'
   )
   t.equal(
+    // @ts-ignore runtime.
     stringifyPosition('foo'),
     '',
     'should return empty `string` with `string`'
   )
   t.equal(
+    // @ts-ignore runtime.
     stringifyPosition(5),
     '',
     'should return empty `string` with `number`'
   )
-  t.equal(stringifyPosition({}), '', 'should return empty `string` with `{}`')
+  t.equal(
+    // @ts-ignore runtime.
+    stringifyPosition({}),
+    '',
+    'should return empty `string` with `{}`'
+  )
 
   t.equal(
     stringifyPosition({type: 'text'}),
@@ -31,6 +38,7 @@ test('stringifyPosition', function (t) {
   )
 
   t.equal(
+    // @ts-ignore runtime.
     stringifyPosition({type: 'text', position: 3}),
     '1:1-1:1',
     'should return a range for `node` with invalid `position` #1'
@@ -39,6 +47,7 @@ test('stringifyPosition', function (t) {
   t.equal(
     stringifyPosition({
       type: 'text',
+      // @ts-ignore runtime.
       position: {start: {}, end: {}}
     }),
     '1:1-1:1',
@@ -76,12 +85,14 @@ test('stringifyPosition', function (t) {
   )
 
   t.equal(
+    // @ts-ignore runtime.
     stringifyPosition({start: 3, end: 6}),
     '1:1-1:1',
     'should return a range for `position` with invalid `point`s #1'
   )
 
   t.equal(
+    // @ts-ignore runtime.
     stringifyPosition({start: {}, end: {}}),
     '1:1-1:1',
     'should return range for `position` with invalid `point`s #1'
@@ -112,18 +123,21 @@ test('stringifyPosition', function (t) {
   )
 
   t.equal(
+    // @ts-ignore runtime.
     stringifyPosition({line: 'foo', column: 'bar'}),
     '1:1',
     'should return a point for a `point` with invalid indices #1'
   )
 
   t.equal(
+    // @ts-ignore runtime.
     stringifyPosition({line: 4}),
     '4:1',
     'should return a point for a partially valid `point` #1'
   )
 
   t.equal(
+    // @ts-ignore runtime.
     stringifyPosition({column: 12}),
     '1:12',
     'should return a point for a partially valid `point` #1'

tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "include": ["*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  }
+}