Add types

Closes GH-18.

Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>
Reviewed-by: Jonathan Haines <jonno.haines@gmail.com>
Reviewed-by: Titus Wormer <tituswormer@gmail.com>

package.json

@@ -30,8 +30,10 @@
     "Tsuyusato Kitsune <make.just.on@gmail.com>",
     "Matsuko Friedland <info@matsuko.ca>"
   ],
+  "types": "types/index.d.ts",
   "files": [
-    "index.js"
+    "index.js",
+    "types/index.d.ts"
   ],
   "dependencies": {
     "extend": "^3.0.0",
@@ -41,6 +43,7 @@
     "unist-util-visit": "^2.0.0"
   },
   "devDependencies": {
+    "dtslint": "^3.0.0",
     "nyc": "^15.0.0",
     "prettier": "^2.0.0",
     "remark": "^12.0.0",
@@ -54,7 +57,8 @@
     "format": "remark . -qfo && prettier . --write && 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,
@@ -74,7 +78,8 @@
     "prettier": true,
     "esnext": false,
     "rules": {
-      "unicorn/prefer-includes": "off"
+      "unicorn/prefer-includes": "off",
+      "import/no-extraneous-dependencies": "off"
     }
   },
   "remarkConfig": {

types/index.d.ts

@@ -0,0 +1,65 @@
+// TypeScript Version: 3.4
+
+import {Plugin} from 'unified'
+import {Node} from 'unist'
+
+declare namespace remarkExternalLinks {
+  type ExternalLinks = Plugin<[RemarkExternalLinksOptions?]>
+
+  interface RemarkExternalLinksOptions {
+    /**
+     * How to display referenced documents (`string?`: `_self`, `_blank`, `_parent`,
+     * or `_top`, default: `_blank`).
+     * Pass `false` to not set `target`s on links.
+     *
+     * @defaultValue '_blank'
+     */
+    target?: '_self' | '_blank' | '_parent' | '_top' | false
+    /**
+     * [Link types][mdn-rel] to hint about the referenced documents (`Array.<string>`
+     * or `string`, default: `['nofollow', 'noopener', 'noreferrer']`).
+     * Pass `false` to not set `rel`s on links.
+     *
+     * > When using a `target`, add [`noopener` and `noreferrer`][mdn-a] to avoid
+     * > exploitation of the `window.opener` API.
+     *
+     * [mdn-rel]: https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types
+     *
+     * @defaultValue ['nofollow', 'noopener', 'noreferrer']
+     */
+    rel?: string[] | string
+    /**
+     * Protocols to check, such as `mailto` or `tel` (`Array.<string>`, default:
+     * `['http', 'https']`).
+     */
+    protocols?: string[]
+    /**
+     * [**hast**][hast] content to insert at the end of external links
+     * ([**Node**][node] or [**Children**][children]).
+     * Will be inserted in a `<span>` element.
+     *
+     * Useful for improving accessibility by [giving users advanced warning when
+     * opening a new window][g201].
+     *
+     * [hast]: https://github.com/syntax-tree/hast
+     * [node]: https://github.com/syntax-tree/hast#nodes
+     * [children]: https://github.com/syntax-tree/unist#child
+     * [g201]: https://www.w3.org/WAI/WCAG21/Techniques/general/G201
+     */
+    content?: Node | Node[]
+    /**
+     * [`Properties`][properties] to add to the `span` wrapping `content`, when
+     * given.
+     *
+     * Reference: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/73e5ee37847e0ad313459222642db3eed1e985b7/types/hast/index.d.ts#L72-L77
+     */
+    contentProperties?: Record<
+      string,
+      boolean | number | string | null | undefined | Array<string | number>
+    >
+  }
+}
+
+declare const remarkExternalLinks: remarkExternalLinks.ExternalLinks
+
+export = remarkExternalLinks

types/remark-external-links-tests.ts

@@ -0,0 +1,19 @@
+import unified = require('unified')
+import externalLinks = require('remark-external-links')
+
+unified().use(externalLinks)
+
+unified().use(externalLinks, {})
+
+unified().use(externalLinks, {target: false})
+unified().use(externalLinks, {target: '_self'})
+
+unified().use(externalLinks, {rel: 'nofollow'})
+unified().use(externalLinks, {rel: ['nofollow', 'noopener', 'noreferrer']})
+
+unified().use(externalLinks, {protocols: ['mailto']})
+
+unified().use(externalLinks, {content: {type: 'text'}})
+unified().use(externalLinks, {content: [{type: 'text'}]})
+
+unified().use(externalLinks, {contentProperties: {title: 'span'}})

types/tsconfig.json

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

types/tslint.json

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