feat: update htmlAsRichText API

- remove `sync` helpers
- rename `converter` option to `serializer`
- add `direction`, `include` options
- remove `silent` option
- allow deep selectors in the `serializer` map
- refactor helpers return type
- refactor `rehypeRichText` plugin
- refactor tests

package.json

@@ -90,9 +90,9 @@
 		"remark-rehype": "^11.1.0",
 		"unified": "^11.0.5",
 		"unist-util-remove": "^4.0.0",
+		"unist-util-visit": "^5.0.0",
 		"unist-util-visit-parents": "^6.0.1",
-		"vfile": "^6.0.1",
-		"vfile-reporter": "^8.1.1"
+		"vfile": "^6.0.1"
 	},
 	"devDependencies": {
 		"@prismicio/mock": "^0.3.1",

src/richtext/htmlAsRichText.ts

@@ -3,10 +3,7 @@ import { unified } from "unified";
 
 import { AsRichTextConfig, AsRichTextReturnType } from "./types";
 
-import { rehypeRichText } from "./unified/rehypeRichText";
-
-const htmlProcessor = (config?: AsRichTextConfig) =>
-	unified().use(rehypeParse).use(rehypeRichText, config);
+import { rehypeRichText } from "./utils/rehypeRichText";
 
 /**
  * Converts an HTML string to a rich text field.
@@ -17,25 +14,14 @@ const htmlProcessor = (config?: AsRichTextConfig) =>
  *
  * @returns Rich text field equivalent of the provided HTML string.
  */
-export const htmlAsRichText = (
+export const htmlAsRichText = async (
 	html: string,
 	config?: AsRichTextConfig,
 ): Promise<AsRichTextReturnType> => {
-	return htmlProcessor(config).process(html);
-};
+	const { result, messages } = await unified()
+		.use(rehypeParse, { emitParseErrors: true })
+		.use(rehypeRichText, config)
+		.process(html);
 
-/**
- * Converts an HTML string to a rich text field synchronously.
- *
- * @param html - An HTML string
- * @param config - Configuration that determines the output of
- *   `htmlAsRichTextSync()`
- *
- * @returns Rich text field equivalent of the provided HTML string.
- */
-export const htmlAsRichTextSync = (
-	html: string,
-	config?: AsRichTextConfig,
-): AsRichTextReturnType => {
-	return htmlProcessor(config).processSync(html);
+	return { result, warnings: messages };
 };

src/richtext/index.ts

@@ -7,11 +7,8 @@ export { composeSerializers } from "./composeSerializers";
 
 export { RichTextNodeType as Element } from "../types/value/richText";
 
-export { htmlAsRichText, htmlAsRichTextSync } from "./htmlAsRichText";
-export {
-	markdownAsRichText,
-	markdownAsRichTextSync,
-} from "./markdownAsRichText";
+export { htmlAsRichText } from "./htmlAsRichText";
+export { markdownAsRichText } from "./markdownAsRichText";
 
 export type {
 	AsRichTextConfig,

src/richtext/markdownAsRichText.ts

@@ -4,14 +4,11 @@ import { unified } from "unified";
 
 import { AsRichTextConfig, AsRichTextReturnType } from "./types";
 
-import { rehypeRichText } from "./unified/rehypeRichText";
+import { rehypeRichText } from "./utils/rehypeRichText";
 
 // Used for TSDocs only.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import type { htmlAsRichText, htmlAsRichTextSync } from "./htmlAsRichText";
-
-const markdownProcessor = (config?: AsRichTextConfig) =>
-	unified().use(remarkParse).use(remarkRehype).use(rehypeRichText, config);
+import type { htmlAsRichText } from "./htmlAsRichText";
 
 /**
  * Converts a markdown string to a rich text field.
@@ -26,29 +23,15 @@ const markdownProcessor = (config?: AsRichTextConfig) =>
  *
  * @returns Rich text field equivalent of the provided markdown string.
  */
-export const markdownAsRichText = (
+export const markdownAsRichText = async (
 	markdown: string,
 	config?: AsRichTextConfig,
 ): Promise<AsRichTextReturnType> => {
-	return markdownProcessor(config).process(markdown);
-};
+	const { result, messages } = await unified()
+		.use(remarkParse)
+		.use(remarkRehype)
+		.use(rehypeRichText, config)
+		.process(markdown);
 
-/**
- * Converts an markdown string to a rich text field synchronously.
- *
- * @remarks
- * To convert markdown to a rich text field, this function first converts it to
- * HTML. It's essentially a sugar above {@link htmlAsRichTextSync}.
- *
- * @param markdown - An markdown string
- * @param config - Configuration that determines the output of
- *   `markdownAsRichTextSync()`
- *
- * @returns Rich text field equivalent of the provided markdown string.
- */
-export const markdownAsRichTextSync = (
-	markdown: string,
-	config?: AsRichTextConfig,
-): AsRichTextReturnType => {
-	return markdownProcessor(config).processSync(markdown);
+	return { result, warnings: messages };
 };

src/richtext/types.ts

@@ -25,7 +25,7 @@ import {
 	RichTextNodeType,
 } from "../types/value/richText";
 
-import { RehypeRichTextConfig } from "./unified/rehypeRichText";
+import { RehypeRichTextConfig } from "./utils/rehypeRichText";
 
 // Serializers
 
@@ -165,4 +165,7 @@ export type AsRichTextConfig = RehypeRichTextConfig;
 /**
  * The return type of `*AsRichText` functions.
  */
-export type AsRichTextReturnType = VFile & { result: RichTextField };
+export type AsRichTextReturnType = {
+	result: RichTextField;
+	warnings: VFile["messages"];
+};