Add JSDoc based types

Author: wooorm

.gitignore

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

index.js

@@ -1,21 +1,51 @@
+/**
+ * @typedef {import('xast').Root} Root
+ * @typedef {import('xast').Element} Element
+ *
+ * @typedef {string | Omit<Entry, 'lang'|'alternate'>} Alternate
+ *
+ * @typedef Entry Entries represent a single URL and describe them with metadata.
+ * @property {string} url Full URL (example: `'https://example.org/'`). See <https://www.sitemaps.org/protocol.html#locdef>
+ * @property {number|string|Date} [modified] Value indicating when the page last changed.
+ * @property {string} [lang] BCP 47 tag indicating the language of the page (example: `'en-GB'`). See <https://github.com/wooorm/bcp-47>
+ * @property {Object.<string, Alternate>} [alternate] Translations of the page, where each key is a BCP 47 tag and each value an entry. Alternate resources inherit fields from the entry they are described in.
+ */
+
+import {URL} from 'url'
 import bcp47 from 'bcp-47-normalize'
 import {u} from 'unist-builder'
 import {x} from 'xastscript'
 
 var own = {}.hasOwnProperty
 
+/**
+ * Build a sitemap.
+ *
+ * @param {Array<string|Entry>} [data] URLs to build a sitemap for.
+ * @returns {Root}
+ */
 export function sitemap(data) {
+  var index = -1
+  /** @type {Array.<Element>} */
   var nodes = []
+  /** @type {Object.<string, Entry>} */
   var urls = {}
+  /** @type {Object.<string, Array.<string>>} */
   var groupings = {}
-  var index = -1
-  var i18n
+  /** @type {Array.<string>} */
   var grouping
+  /** @type {Entry} */
   var entry
+  /** @type {Entry} */
   var alt
+  /** @type {string} */
   var key
+  /** @type {Element} */
   var node
+  /** @type {Date} */
   var modified
+  /** @type {boolean} */
+  var i18n
 
   if (data) {
     while (++index < data.length) {
@@ -85,14 +115,11 @@ export function sitemap(data) {
     if (own.call(urls, key)) {
       node = x('url', [x('loc', key)])
       entry = urls[key]
-      modified = entry.modified
 
       nodes.push(node)
 
-      if (modified != null) {
-        if (typeof modified !== 'object') {
-          modified = new Date(modified)
-        }
+      if (entry.modified != null) {
+        modified = toDate(entry.modified)
 
         if (Number.isNaN(modified.valueOf())) {
           throw new TypeError(
@@ -133,8 +160,13 @@ export function sitemap(data) {
   ])
 }
 
+/**
+ * @param {string|Entry} d
+ */
 function toEntry(d) {
+  /** @type {Entry} */
   var entry = {}
+  /** @type {string} */
   var url
 
   if (typeof d === 'string') {
@@ -149,3 +181,11 @@ function toEntry(d) {
   entry.url = new URL(url).href
   return entry
 }
+
+/**
+ * @param {Date|string|number} value
+ * @returns {Date}
+ */
+export function toDate(value) {
+  return typeof value === 'object' ? value : new Date(value)
+}

package.json

@@ -25,9 +25,9 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
-  "types": "types/",
+  "types": "index.d.ts",
   "files": [
-    "types/index.d.ts",
+    "index.d.ts",
     "index.js"
   ],
   "dependencies": {
@@ -37,21 +37,27 @@
     "xastscript": "^3.0.0"
   },
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "concat-stream": "^2.0.0",
     "prettier": "^2.0.0",
     "regenerate": "^1.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
+    "type-coverage": "^2.0.0",
+    "typescript": "^4.0.0",
     "xast-util-to-xml": "^3.0.0",
     "xo": "^0.39.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": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,
@@ -76,14 +82,16 @@
       "no-eq-null": "off",
       "no-var": "off",
       "prefer-arrow-callback": "off"
-    },
-    "ignores": [
-      "types"
-    ]
+    }
   },
   "remarkConfig": {
     "plugins": [
       "preset-wooorm"
     ]
+  },
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true
   }
 }

test.js

@@ -76,6 +76,7 @@ test('sitemap', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore runtime.
       sitemap([{}])
     },
     /Invalid URL: undefined/,

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