Add export of Raw node, register it

Author: wooorm

.gitignore

@@ -4,3 +4,4 @@
 coverage/
 node_modules/
 yarn.lock
+!/index.d.ts

index.d.ts

@@ -0,0 +1,35 @@
+import type {Data, Literal} from 'xast'
+
+export type {Options, Quote} from './lib/index.js'
+export {toXml} from './lib/index.js'
+
+/**
+ * Raw.
+ */
+export interface Raw extends Literal {
+  /**
+   * Node type of raw.
+   */
+  type: 'raw'
+
+  /**
+   * Data associated with the xast raw.
+   */
+  data?: RawData | undefined
+}
+
+/**
+ * Info associated with xast raw nodes by the ecosystem.
+ */
+export interface RawData extends Data {}
+
+// Add nodes to tree.
+declare module 'xast' {
+  interface ElementContentMap {
+    raw: Raw
+  }
+
+  interface RootContentMap {
+    raw: Raw
+  }
+}

index.js

@@ -1,6 +1,2 @@
-/**
- * @typedef {import('./lib/index.js').Options} Options
- * @typedef {import('./lib/index.js').Quote} Quote
- */
-
+// Note: Types exported from `index.d.ts`.
 export {toXml} from './lib/index.js'

lib/index.js

@@ -31,10 +31,6 @@
  * @typedef {'"' | "'"} Quote
  *   XML quotes for attribute values.
  *
- * @typedef {Literal & {type: 'raw'}} Raw
- *   To do: improved `Raw` type?
- *
- *
  * @typedef State
  *   Info passed around about the current state.
  * @property {Options} options

lib/raw.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('./index.js').Raw} Raw
+ * @typedef {import('../index.js').Raw} Raw
  * @typedef {import('./index.js').State} State
  */
 

lib/text.js

@@ -1,6 +1,6 @@
 /**
  * @typedef {import('xast').Text} Text
- * @typedef {import('./index.js').Raw} Raw
+ * @typedef {import('../index.js').Raw} Raw
  */
 
 import {escape} from './util-escape.js'

package.json

@@ -75,6 +75,16 @@
     "strict": true
   },
   "xo": {
+    "overrides": [
+      {
+        "files": [
+          "**/*.ts"
+        ],
+        "rules": {
+          "@typescript-eslint/consistent-type-definitions": "off"
+        }
+      }
+    ],
     "prettier": true,
     "rules": {
       "unicorn/prefer-string-replace-all": "off"

readme.md

@@ -20,6 +20,7 @@
     *   [`toXml(tree[, options])`](#toxmltree-options)
     *   [`Options`](#options)
     *   [`Quote`](#quote-1)
+    *   [`Raw`](#raw)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Security](#security)
@@ -181,11 +182,47 @@ XML quotes for attribute values (TypeScript type).
 type Quote = '"' | "'"
 ```
 
+### `Raw`
+
+Raw (TypeScript type).
+
+###### Type
+
+```ts
+import type {Data, Literal} from 'xast'
+
+interface Raw extends Literal {
+  type: 'raw'
+  data?: RawData | undefined
+}
+
+export interface RawData extends Data {}
+```
+
 ## Types
 
 This package is fully typed with [TypeScript][].
-It exports the additional types [`Options`][api-options] and
-[`Quote`][api-quote].
+It exports the additional types [`Options`][api-options], [`Quote`][api-quote],
+and [`Raw`][api-raw].
+
+It also registers the node type with `@types/xast`.
+If you’re working with the syntax tree, make sure to import this utility
+somewhere in your types, as that registers the new node types in the tree.
+
+```js
+/**
+ * @typedef {import('xast-util-to-xml')}
+ */
+
+import {visit} from 'unist-util-visit'
+
+/** @type {import('xast').Root} */
+const tree = getXastNodeSomeHow()
+
+visit(tree, function (node) {
+  // `node` can now be a raw node.
+})
+```
 
 ## Compatibility
 
@@ -287,3 +324,5 @@ abide by its terms.
 [api-options]: #options
 
 [api-quote]: #quote-1
+
+[api-raw]: #raw

test/raw.js

@@ -6,7 +6,6 @@ import {toXml} from '../index.js'
 test('`raw`', async function (t) {
   await t.test('should encode `raw`s', async function () {
     assert.deepEqual(
-      // @ts-expect-error: check how the runtime handles `raw` nodes.
       toXml(u('raw', '<script>alert("XSS!")</script>')),
       '&#x3C;script>alert("XSS!")&#x3C;/script>'
     )
@@ -16,7 +15,6 @@ test('`raw`', async function (t) {
     'should not encode `raw`s in `allowDangerousXml` mode',
     async function () {
       assert.deepEqual(
-        // @ts-expect-error: check how the runtime handles `raw` nodes.
         toXml(u('raw', '<script>alert("XSS!")</script>'), {
           allowDangerousXml: true
         }),

tsconfig.json

@@ -11,5 +11,5 @@
     "target": "es2020"
   },
   "exclude": ["coverage/", "node_modules/"],
-  "include": ["**/*.js"]
+  "include": ["**/*.js", "index.d.ts"]
 }