Add types

Closes GH-3.

Reviewed-by: Titus Wormer <tituswormer@gmail.com>
Reviewed-by: Junyoung Choi <fluke8259@gmail.com>

Author: ChristianMurphy

package.json

@@ -20,15 +20,20 @@
   "author": "Eugene Sharygin <eush77@gmail.com>",
   "contributors": [
     "Eugene Sharygin <eush77@gmail.com>",
-    "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)"
+    "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)",
+    "Christian Murphy <christian.murphy.42@gmail.com>"
   ],
   "files": [
-    "index.js"
+    "index.js",
+    "types/index.d.ts"
   ],
+  "types": "types/index.d.ts",
   "dependencies": {
     "object-assign": "^4.1.0"
   },
   "devDependencies": {
+    "@types/mdast": "^3.0.3",
+    "dtslint": "^0.9.9",
     "nyc": "^14.0.0",
     "prettier": "^1.14.2",
     "remark-cli": "^6.0.0",
@@ -40,7 +45,8 @@
     "format": "remark . -qfo && prettier --write \"**/*.js\" && xo --fix",
     "test-api": "node test",
     "test-coverage": "nyc --reporter lcov tape test.js",
-    "test": "npm run format && npm run test-coverage"
+    "test-types": "dtslint types",
+    "test": "npm run format && npm run test-coverage && npm run test-types"
   },
   "nyc": {
     "check-coverage": true,

types/index.d.ts

@@ -0,0 +1,78 @@
+// TypeScript Version: 3.5
+
+import {Node} from 'unist'
+
+// NOTE: namespace is needed to use `export = unistBuilder`
+declare namespace unistBuilder {}
+
+// NOTE: the order of the unistBuilder overloads is important.
+// Looking at the generics' "extends" left to right.
+// It should go from more specific types higher in the file, to more broad types lower in the file.
+
+/**
+ * Creates a node, with a given type
+ *
+ * @param type type of node
+ */
+declare function unistBuilder<T extends string>(type: T): {type: T}
+
+/**
+ * Creates a node, with type and value
+ *
+ * @param type type of node
+ * @param value  value property of node
+ */
+declare function unistBuilder<T extends string>(
+  type: T,
+  value: string
+): {type: T; value: string}
+
+/**
+ * Creates a node, with type, props, and value
+ *
+ * @param type type of node
+ * @param props additional properties for node
+ * @param value value property of node
+ */
+declare function unistBuilder<T extends string, P extends {}>(
+  type: T,
+  props: P,
+  value: string
+): {type: T; value: string} & P
+
+/**
+ * Creates a node, with type and children
+ *
+ * @param type type of node
+ * @param children child nodes of the current node
+ */
+declare function unistBuilder<T extends string, C extends Node[]>(
+  type: T,
+  children: C
+): {type: T; children: C}
+
+/**
+ * Creates a node, with type, props, and children
+ *
+ * @param type type of node
+ * @param props additional properties for node
+ * @param children child nodes of the current node
+ */
+declare function unistBuilder<T extends string, P extends {}, C extends Node[]>(
+  type: T,
+  props: P,
+  children: C
+): {type: T; children: C} & P
+
+/**
+ * Creates a node, with type and props
+ *
+ * @param type type of node
+ * @param props additional properties for node
+ */
+declare function unistBuilder<T extends string, P extends {}>(
+  type: T,
+  props: P
+): {type: T} & P
+
+export = unistBuilder

types/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "lib": ["es2015"],
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "unist-builder": ["index.d.ts"]
+    }
+  }
+}

types/tslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "whitespace": false,
+    "semicolon": false
+  }
+}

types/unist-builder-tests.ts

@@ -0,0 +1,16 @@
+import * as u from 'unist-builder'
+import {Text, List, ListItem, HTML} from 'mdast'
+
+u('example') // $ExpectType { type: "example"; }
+u('example', {property: true}) // $ExpectType { type: "example"; } & { property: boolean; }
+const node1 = u('text', 'text') // $ExpectType { type: "text"; value: string; }
+const text: Text = node1
+
+// $ExpectType { type: "list"; children: { type: "listItem"; children: ({ type: "html"; value: string; } & { checked: boolean; })[]; }[]; }
+const node2 = u('list', [
+  u('listItem', [u('html', {checked: true}, '<strong>text</strong>')])
+])
+
+const list: List = node2
+const listItem: ListItem = node2.children[0]
+const html: HTML = node2.children[0].children[0]