Add remark-api to dev-dependencies

.gitignore

@@ -6,4 +6,5 @@ node_modules/
 .DS_Store
 yarn.lock
 
+!/index.d.ts
 !/test-types.d.ts

index.d.ts

@@ -0,0 +1,22 @@
+import type {Nodes} from 'hast'
+import type {VFile} from 'vfile'
+
+export {raw} from './lib/index.js'
+
+/**
+ * Configuration.
+ */
+export interface Options {
+  /**
+   * Corresponding virtual file representing the input document (optional).
+   */
+  file?: VFile | null | undefined
+
+  /**
+   * List of custom hast node types to pass through (as in, keep) (optional).
+   *
+   * If the passed through nodes have children, those children are expected to
+   * be hast again and will be handled.
+   */
+  passThrough?: Array<string> | null | undefined
+}

index.js

@@ -1,5 +1,2 @@
-/**
- * @typedef {import('./lib/index.js').Options} Options
- */
-
+// Note: types exposed from `index.d.ts`.
 export {raw} from './lib/index.js'

lib/index.js

@@ -7,6 +7,8 @@
  * @typedef {import('hast').RootContent} RootContent
  * @typedef {import('hast').Text} Text
  *
+ * @typedef {import('hast-util-raw').Options} Options
+ *
  * @typedef {import('mdast-util-to-hast').Raw} Raw
  *
  * @typedef {import('parse5').DefaultTreeAdapterMap} DefaultTreeAdapterMap
@@ -18,21 +20,9 @@
  * @typedef {import('parse5').Token.TagToken} TagToken
  *
  * @typedef {import('unist').Point} Point
- *
- * @typedef {import('vfile').VFile} VFile
  */
 
 /**
- * @typedef Options
- *   Configuration.
- * @property {VFile | null | undefined} [file]
- *   Corresponding virtual file representing the input document (optional).
- * @property {Array<Nodes['type']> | null | undefined} [passThrough]
- *   List of custom hast node types to pass through (as in, keep) (optional).
- *
- *   If the passed through nodes have children, those children are expected to
- *   be hast again and will be handled.
- *
  * @typedef State
  *   Info passed around about the current state.
  * @property {(node: Nodes) => undefined} handle
@@ -43,10 +33,16 @@
  *   Current parser.
  * @property {boolean} stitches
  *   Whether there are stitches.
- *
- * @typedef {{type: 'comment', value: {stitch: Nodes}}} Stitch
+ */
+
+/**
+ * @typedef Stitch
  *   Custom comment-like value we pass through parse5, which contains a
  *   replacement node that we’ll swap back in afterwards.
+ * @property {'comment'} type
+ *   Node type.
+ * @property {{stitch: Nodes}} value
+ *   Replacement value.
  */
 
 import structuredClone from '@ungap/structured-clone'

package.json

@@ -56,6 +56,7 @@
     "hastscript": "^9.0.0",
     "mdast-util-from-markdown": "^2.0.0",
     "prettier": "^3.0.0",
+    "remark-api": "^1.0.0",
     "remark-cli": "^12.0.0",
     "remark-preset-wooorm": "^10.0.0",
     "type-coverage": "^2.0.0",
@@ -81,7 +82,8 @@
   },
   "remarkConfig": {
     "plugins": [
-      "remark-preset-wooorm"
+      "remark-preset-wooorm",
+      "remark-api"
     ]
   },
   "typeCoverage": {
@@ -97,7 +99,22 @@
           "**/*.ts"
         ],
         "rules": {
-          "@typescript-eslint/consistent-type-definitions": "off"
+          "@typescript-eslint/array-type": [
+            "error",
+            {
+              "default": "generic"
+            }
+          ],
+          "@typescript-eslint/ban-types": [
+            "error",
+            {
+              "extendDefaults": true
+            }
+          ],
+          "@typescript-eslint/consistent-type-definitions": [
+            "error",
+            "interface"
+          ]
         }
       }
     ],

readme.md

@@ -18,8 +18,8 @@ HTML) again, keeping positional info okay.
 * [Install](#install)
 * [Use](#use)
 * [API](#api)
-  * [`raw(tree[, options])`](#rawtree-options)
   * [`Options`](#options)
+  * [`raw(tree, options)`](#rawtree-options)
 * [Types](#types)
 * [Compatibility](#compatibility)
 * [Security](#security)
@@ -117,37 +117,36 @@ Yields:
 
 ## API
 
-This package exports the identifier [`raw`][api-raw].
-There is no default export.
+### `Options`
 
-### `raw(tree[, options])`
+Configuration.
 
-Pass a hast tree through an HTML parser, which will fix nesting, and turn raw
-nodes into actual nodes.
+###### Fields
 
-###### Parameters
+* `file?` (`VFile | null | undefined`)
+  — corresponding virtual file representing the input document (optional)
+* `passThrough?` (`Array<string> | null | undefined`)
 
-* `tree` ([`Node`][node])
-  — original hast tree to transform
-* `options` ([`Options`][api-options], optional)
-  — configuration
+  List of custom hast node types to pass through (as in, keep) (optional).
 
-###### Returns
+  If the passed through nodes have children, those children are expected to
+  be hast again and will be handled.
 
-Parsed again tree ([`Node`][node]).
+### `raw(tree, options)`
 
-### `Options`
+Pass a hast tree through an HTML parser, which will fix nesting, and turn
+raw nodes into actual nodes.
+
+###### Parameters
 
-Configuration (TypeScript type).
+* `tree` (`Root | RootContent`)
+  — original hast tree to transform
+* `options?` (`Options | null | undefined`)
+  — configuration (optional)
 
-###### Fields
+###### Returns
 
-* `passThrough` (`Array<string>`, optional)
-  — list of custom hast node types to pass through (keep).
-  If the passed through nodes have children, those children are expected to be
-  hast and will be handled by this utility
-* `file` ([`VFile`][vfile], optional)
-  — corresponding virtual file representing the input document
+Parsed again tree (`Root | RootContent`).
 
 ## Types
 
@@ -260,18 +259,12 @@ abide by its terms.
 
 [hast]: https://github.com/syntax-tree/hast
 
-[node]: https://github.com/syntax-tree/hast#nodes
-
 [mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast
 
 [hast-util-sanitize]: https://github.com/syntax-tree/hast-util-sanitize
 
-[vfile]: https://github.com/vfile/vfile
-
 [rehype-raw]: https://github.com/rehypejs/rehype-raw
 
 [parse5]: https://github.com/inikulin/parse5
 
-[api-raw]: #rawtree-options
-
 [api-options]: #options

tsconfig.json

@@ -12,5 +12,5 @@
     "target": "es2022"
   },
   "exclude": ["coverage/", "node_modules/"],
-  "include": ["**/**.js", "test-types.d.ts"]
+  "include": ["**/**.js", "index.d.ts", "test-types.d.ts"]
 }