Add JSDoc based types

.gitignore

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

index.js

@@ -1,15 +1,41 @@
+/**
+ * @typedef {import('unist').Node} Node
+ * @typedef {Node & {position: undefined}} NodeWithUndefinedPosition
+ * @typedef {Omit<Node, 'position'>} NodeWithoutPosition
+ */
+
 import {visit} from 'unist-util-visit'
 
-export function removePosition(node, force) {
- visit(node, remove)
+export const removePosition =
+ /**
+ * @type {(
+ * ((tree: Node, force?: false) => NodeWithUndefinedPosition) &
+ * ((tree: Node, force: true) => NodeWithoutPosition)
+ * )}
+ */
+ (
+ /**
+ * Utility to remove positions from a tree
+ *
+ * @param {Node} node the unist tree
+ * @param {boolean} [force=false] if `force` is given, uses `delete`, otherwise, sets positions to `undefined`.
+ * @returns {NodeWithUndefinedPosition}
+ */
+ function (node, force) {
+ visit(node, remove)
 
- return node
+ // @ts-ignore hush TS, we know what we’re doing.
+ return node
 
- function remove(node) {
- if (force) {
- delete node.position
- } else {
- node.position = undefined
+ /**
+ * @param {Node} node the unist tree
+ */
+ function remove(node) {
+ if (force) {
+ delete node.position
+ } else {
+ node.position = undefined
+ }
+ }
  }
- }
-}
+ )

index.test-d.ts

@@ -0,0 +1,21 @@
+import {expectType} from 'tsd'
+import {Node} from 'unist'
+import remark from 'remark'
+import {
+ removePosition,
+ NodeWithUndefinedPosition,
+ NodeWithoutPosition
+} from './index.js'
+
+const tree: Node = remark().parse(
+ 'Some _emphasis_, **importance**, and `code`.'
+)
+
+expectType<NodeWithUndefinedPosition>(removePosition(tree))
+expectType<NodeWithUndefinedPosition>(removePosition(tree, false))
+expectType<NodeWithoutPosition>(removePosition(tree, true))
+
+// Used as a plugin
+void remark()
+ .use(() => (tree: Node) => removePosition(tree))
+ .process('Some _emphasis_, **importance**, and `code`.')

package.json

@@ -28,29 +28,37 @@
  "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",
  "unist-util-visit": "^3.0.0"
  },
  "devDependencies": {
+ "@types/tape": "^4.0.0",
  "c8": "^7.0.0",
  "prettier": "^2.0.0",
  "remark": "^13.0.0",
  "remark-cli": "^9.0.0",
  "remark-preset-wooorm": "^8.0.0",
+ "rimraf": "^3.0.0",
  "tape": "^5.0.0",
+ "tsd": "^0.14.0",
+ "type-coverage": "^2.0.0",
+ "typescript": "^4.0.0",
  "unist-builder": "^3.0.0",
  "xo": "^0.38.0"
  },
  "scripts": {
+ "prepack": "npm run build && npm run format",
+ "build": "rimraf \"*.d.ts\" && tsc && tsd && 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": "npm run format && npm run test-coverage"
+ "test": "npm run build && npm run format && npm run test-coverage"
  },
  "prettier": {
  "tabWidth": 2,
@@ -65,14 +73,16 @@
  "rules": {
  "no-var": "off",
  "prefer-arrow-callback": "off"
- },
- "ignores": [
- "types/"
- ]
+ }
  },
  "remarkConfig": {
  "plugins": [
  "preset-wooorm"
  ]
+ },
+ "typeCoverage": {
+ "atLeast": 100,
+ "detail": true,
+ "strict": true
  }
 }

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