Add augmentation of types in file.data.meta

.gitignore

@@ -1,6 +1,7 @@
 .DS_Store
-*.d.ts
 *.log
 coverage/
 node_modules/
+index.d.ts
+test.d.ts
 yarn.lock

complex-types.d.ts

@@ -0,0 +1,15 @@
+// Need a random export to turn this into a module?
+export type Whatever = unknown
+
+declare module 'vfile' {
+  interface DataMap {
+    meta: {
+      /**
+       * Title of this document.
+       *
+       * Populated by `rehype-infer-title-meta` from the HTML.
+       */
+      title?: string
+    }
+  }
+}

index.js

@@ -1,4 +1,6 @@
 /**
+ * @typedef {import('./complex-types.js')} DoNotTouchThisAsItIncludesAugmentation
+ *
  * @typedef {import('hast').Root} Root
  *
  * @typedef Options
@@ -26,9 +28,7 @@ export default function rehypeInferTitleMeta(options = {}) {
     const matter = /** @type {Record<string, unknown>} */ (
       file.data.matter || {}
     )
-    const meta = /** @type {Record<string, unknown>} */ (
-      file.data.meta || (file.data.meta = {})
-    )
+    const meta = file.data.meta || (file.data.meta = {})
 
     if (node && !matter.title && !meta.title) {
       meta.title = toText(node)

package.json

@@ -29,6 +29,7 @@
   "main": "index.js",
   "types": "index.d.ts",
   "files": [
+    "complex-types.d.ts",
     "index.d.ts",
     "index.js"
   ],
@@ -53,7 +54,7 @@
     "xo": "^0.50.0"
   },
   "scripts": {
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "build": "rimraf \"{index,test}.d.ts\" && tsc && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
     "test-api": "node --conditions development test.js",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node --conditions development test.js",

readme.md

@@ -47,7 +47,7 @@ title.
 ## Install
 
 This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
-In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]:
+In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with [npm][]:
 
 ```sh
 npm install rehype-infer-title-meta
@@ -81,25 +81,21 @@ import rehypeMeta from 'rehype-meta'
 import rehypeFormat from 'rehype-format'
 import rehypeStringify from 'rehype-stringify'
 
-main()
-
-async function main() {
-  const file = await unified()
-    .use(remarkParse)
-    .use(remarkRehype)
-    .use(rehypeDocument)
-    .use(rehypeInferTitleMeta)
-    .use(rehypeMeta)
-    .use(rehypeFormat)
-    .use(rehypeStringify)
-    .process('# Hello, world!')
-
-  console.log(file.data)
-  console.log(String(file))
-}
+const file = await unified()
+  .use(remarkParse)
+  .use(remarkRehype)
+  .use(rehypeDocument)
+  .use(rehypeInferTitleMeta)
+  .use(rehypeMeta)
+  .use(rehypeFormat)
+  .use(rehypeStringify)
+  .process('# Hello, world!')
+
+console.log(file.data)
+console.log(String(file))
 ```
 
-Now running `node example.js` yields:
+…now running `node example.js` yields:
 
 ```js
 {meta: {title: 'Hello, world!'}}
@@ -142,13 +138,29 @@ element in the tree that matches is used.
 ## Types
 
 This package is fully typed with [TypeScript][].
-The extra type `Options` is exported.
+The additional type `Options` is exported.
+
+It also registers the `file.data.meta` field with `vfile`.
+If you’re working with the file, make sure to import this plugin somewhere in
+your types, as that registers the new field on the file.
+
+```js
+/**
+ * @typedef {import('rehype-infer-title-meta')}
+ */
+
+import {VFile} from 'vfile'
+
+const file = new VFile()
+
+console.log(file.data.meta.title) //=> TS now knows that this is a `string?`.
+```
 
 ## Compatibility
 
 Projects maintained by the unified collective are compatible with all maintained
 versions of Node.js.
-As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
+As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+.
 Our projects sometimes work with older versions, but this is not guaranteed.
 
 This plugin works with `rehype-parse` version 3+, `rehype-stringify` version 3+,