Add types

Closes GH-1.

Reviewed-by: Christian Murphy <[email protected]>
Reviewed-by: Junyoung Choi <[email protected]>
Reviewed-by: Titus Wormer <[email protected]>

Author: stefanprobst

package.json

@@ -25,17 +25,21 @@
   "type": "module",
   "main": "./index.mjs",
   "module": "./index.mjs",
+  "types": "types",
   "files": [
-    "index.mjs"
+    "index.mjs",
+    "types/index.d.ts"
   ],
   "dependencies": {
+    "@types/xast": "^1.0.0",
     "bcp-47-normalize": "^1.0.0",
     "unist-builder": "^2.0.0",
     "xastscript": "^2.0.0"
   },
   "devDependencies": {
     "c8": "^7.0.0",
     "concat-stream": "^2.0.0",
+    "dtslint": "^4.0.0",
     "prettier": "^2.0.0",
     "regenerate": "^1.0.0",
     "remark-cli": "^9.0.0",
@@ -48,7 +52,8 @@
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node test.mjs",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node --experimental-modules test.mjs",
-    "test": "npm run format && npm run test-coverage"
+    "test-types": "dtslint types",
+    "test": "npm run format && npm run test-coverage && npm run test-types"
   },
   "prettier": {
     "tabWidth": 2,
@@ -78,7 +83,10 @@
       "no-self-compare": "off",
       "unicorn/prefer-number-properties": "off",
       "unicorn/prefer-type-error": "off"
-    }
+    },
+    "ignores": [
+      "types"
+    ]
   },
   "remarkConfig": {
     "plugins": [

types/index.d.ts

@@ -0,0 +1,47 @@
+// Minimum TypeScript Version: 3.5
+
+import {Root} from 'xast'
+
+/**
+ * Entries represent a single URL and describe them with metadata.
+ */
+export interface Entry {
+  /**
+   * Full URL.
+   *
+   * @see  https://www.sitemaps.org/protocol.html#locdef
+   *
+   * @example 'https://example.org/'
+   */
+  url: string
+
+  /**
+   * Value indicating when the page last changed.
+   */
+  modified?: Date | string | number
+
+  /**
+   * BCP 47 tag indicating the language of the page.
+   *
+   * @see https://github.com/wooorm/bcp-47
+   *
+   * @example 'en-GB'
+   */
+  lang?: string
+
+  /**
+   * 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.
+   *
+   * @see https://github.com/wooorm/bcp-47
+   */
+  alternate?: Record<string, string | Omit<Entry, 'lang' | 'alternate'>>
+}
+
+/**
+ * Build a sitemap.
+ *
+ * @param data URLs to build a sitemap for.
+ */
+export function sitemap(data: Array<string | Entry>): Root

types/test.ts

@@ -0,0 +1,21 @@
+import {sitemap} from 'xast-util-sitemap'
+
+sitemap() // $ExpectError
+sitemap([
+  'https://example.com',
+  {url: 'https://example.com'},
+  {url: 'https://example.com', modified: new Date()},
+  {url: 'https://example.com', modified: Date.now()},
+  {url: 'https://example.com', modified: '01-02-2021'},
+  {url: 'https://example.com', lang: 'en-GB'},
+  {
+    url: 'https://example.com',
+    lang: 'en-GB',
+    alternate: {'de-AT': 'https://example.at'}
+  },
+  {
+    url: 'https://example.com',
+    lang: 'en-GB',
+    alternate: {'de-AT': {url: 'https://example.at', modified: Date.now()}}
+  }
+])

types/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "es2015",
+    "lib": ["es2015"],
+    "moduleResolution": "node",
+    "strict": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "xast-util-sitemap": ["."]
+    }
+  }
+}

types/tslint.json

@@ -0,0 +1,10 @@
+
+{
+  "extends": "dtslint/dtslint.json",
+  "rules": {
+    "no-redundant-jsdoc": false,
+    "no-redundant-jsdoc-2": true,
+    "semicolon": false,
+    "whitespace": false
+  }
+}