refactor: rename HTMLSerializer to HTMLRichTextSerializer

src/helpers/asHTML.ts

@@ -22,15 +22,15 @@ import type { RichTextField } from "../types/value/richText";
 import { LinkResolverFunction } from "./asLink";
 
 /**
- * Serializes a node from a rich text or title field with a function to HTML
+ * Serializes a node from a rich text or title field with a function to HTML.
  *
  * Unlike a typical `@prismicio/richtext` function serializer, this serializer
  * converts the `children` argument to a single string rather than an array of
  * strings.
  *
  * @see Templating rich text and title fields from Prismic {@link https://prismic.io/docs/technologies/templating-rich-text-and-title-fields-javascript}
  */
-export type HTMLFunctionSerializer = (
+export type HTMLRichTextFunctionSerializer = (
 	type: Parameters<RichTextFunctionSerializer<string>>[0],
 	node: Parameters<RichTextFunctionSerializer<string>>[1],
 	text: Parameters<RichTextFunctionSerializer<string>>[2],
@@ -47,23 +47,25 @@ export type HTMLFunctionSerializer = (
  *
  * @see Templating rich text and title fields from Prismic {@link https://prismic.io/docs/technologies/templating-rich-text-and-title-fields-javascript}
  */
-export type HTMLMapSerializer = {
+export type HTMLRichTextMapSerializer = {
 	[P in keyof RichTextMapSerializer<string>]: (payload: {
-		type: Parameters<HTMLMapSerializerFunction<P>>[0]["type"];
-		node: Parameters<HTMLMapSerializerFunction<P>>[0]["node"];
-		text: Parameters<HTMLMapSerializerFunction<P>>[0]["text"];
-		children: Parameters<HTMLMapSerializerFunction<P>>[0]["children"][number];
-		key: Parameters<HTMLMapSerializerFunction<P>>[0]["key"];
+		type: Parameters<HTMLRichTextMapSerializerFunction<P>>[0]["type"];
+		node: Parameters<HTMLRichTextMapSerializerFunction<P>>[0]["node"];
+		text: Parameters<HTMLRichTextMapSerializerFunction<P>>[0]["text"];
+		children: Parameters<
+			HTMLRichTextMapSerializerFunction<P>
+		>[0]["children"][number];
+		key: Parameters<HTMLRichTextMapSerializerFunction<P>>[0]["key"];
 	}) => string | null | undefined;
 };
 
 /**
  * A {@link RichTextMapSerializerFunction} type specifically for
- * {@link HTMLMapSerializer}.
+ * {@link HTMLRichTextMapSerializer}.
  *
  * @typeParam BlockName - The serializer's Rich Text block type.
  */
-type HTMLMapSerializerFunction<
+type HTMLRichTextMapSerializerFunction<
 	BlockType extends keyof RichTextMapSerializer<string>,
 > = RichTextMapSerializerFunction<
 	string,
@@ -104,12 +106,12 @@ type ExtractTextTypeGeneric<T> = T extends RichTextMapSerializerFunction<
 	: never;
 
 /**
- * Creates a default HTML serializer with a given Link Resolver providing
+ * Creates a default HTML Rich Text Serializer with a given Link Resolver providing
  * sensible and safe defaults for every node type
  *
  * @internal
  */
-const createDefaultHTMLSerializer = (
+const createDefaultHTMLRichTextSerializer = (
 	linkResolver: LinkResolverFunction<string> | undefined | null,
 ): RichTextFunctionSerializer<string> => {
 	return (_type, node, text, children, _key) => {
@@ -167,7 +169,7 @@ const createDefaultHTMLSerializer = (
  * @returns A regular function serializer
  */
 const wrapMapSerializerWithStringChildren = (
-	mapSerializer: HTMLMapSerializer,
+	mapSerializer: HTMLRichTextMapSerializer,
 ): RichTextFunctionSerializer<string> => {
 	const modifiedMapSerializer = {} as RichTextMapSerializer<string>;
 
@@ -200,7 +202,7 @@ type AsHTMLReturnType<Field extends RichTextField | null | undefined> =
  * @param richTextField - A rich text or title field from Prismic
  * @param linkResolver - An optional link resolver function to resolve links,
  *   without it you're expected to use the `routes` options from the API
- * @param htmlSerializer - An optional serializer, unhandled cases will fallback
+ * @param htmlRichTextSerializer - An optional Rich Text Serializer, unhandled cases will fallback
  *   to the default serializer
  *
  * @returns HTML equivalent of the provided rich text or title field
@@ -209,20 +211,23 @@ type AsHTMLReturnType<Field extends RichTextField | null | undefined> =
 export const asHTML = <Field extends RichTextField | null | undefined>(
 	richTextField: Field,
 	linkResolver?: LinkResolverFunction<string> | null,
-	htmlSerializer?: HTMLFunctionSerializer | HTMLMapSerializer | null,
+	htmlRichTextSerializer?:
+		| HTMLRichTextFunctionSerializer
+		| HTMLRichTextMapSerializer
+		| null,
 ): AsHTMLReturnType<Field> => {
 	if (richTextField) {
 		let serializer: RichTextFunctionSerializer<string>;
-		if (htmlSerializer) {
+		if (htmlRichTextSerializer) {
 			serializer = composeSerializers(
-				typeof htmlSerializer === "object"
-					? wrapMapSerializerWithStringChildren(htmlSerializer)
+				typeof htmlRichTextSerializer === "object"
+					? wrapMapSerializerWithStringChildren(htmlRichTextSerializer)
 					: (type, node, text, children, key) =>
-							htmlSerializer(type, node, text, children.join(""), key),
-				createDefaultHTMLSerializer(linkResolver),
+							htmlRichTextSerializer(type, node, text, children.join(""), key),
+				createDefaultHTMLRichTextSerializer(linkResolver),
 			);
 		} else {
-			serializer = createDefaultHTMLSerializer(linkResolver);
+			serializer = createDefaultHTMLRichTextSerializer(linkResolver);
 		}
 
 		return serialize(richTextField, serializer).join(

src/index.ts

@@ -1,3 +1,9 @@
+// Use for deprecations.
+import type {
+	HTMLRichTextFunctionSerializer,
+	HTMLRichTextMapSerializer,
+} from "./helpers/asHTML";
+
 //=============================================================================
 // Client - Query content from Prismic.
 //=============================================================================
@@ -57,10 +63,21 @@ export { documentToLinkField } from "./helpers/documentToLinkField";
 export { Element } from "@prismicio/richtext";
 
 export type { LinkResolverFunction } from "./helpers/asLink";
+
+/**
+ * @deprecated Renamed to `HTMLRichTextMapSerializer`
+ */
+type HTMLMapSerializer = HTMLRichTextMapSerializer;
+/**
+ * @deprecated Renamed to `HTMLRichTextFunctionSerializer`
+ */
+type HTMLFunctionSerializer = HTMLRichTextFunctionSerializer;
 export type {
+	HTMLRichTextMapSerializer,
+	HTMLRichTextFunctionSerializer,
 	HTMLMapSerializer,
 	HTMLFunctionSerializer,
-} from "./helpers/asHTML";
+};
 
 //=============================================================================
 // Errors - Custom errors for Prismic APIs.

test/__fixtures__/htmlRichTextFunctionSerializer.ts

@@ -0,0 +1,14 @@
+import { Element } from "@prismicio/richtext";
+
+import * as prismic from "../../src";
+
+export const htmlRichTextFunctionSerializer: prismic.HTMLRichTextFunctionSerializer =
+	(_type, node, _text, children) => {
+		switch (node.type) {
+			case Element.heading1: {
+				return `<h2>${children}</h2>`;
+			}
+		}
+
+		return null;
+	};

test/__fixtures__/htmlMapSerializer.ts → test/__fixtures__/htmlRichTextMapSerializer.ts

@@ -1,6 +1,6 @@
 import * as prismic from "../../src";
 
-export const htmlMapSerializer: prismic.HTMLMapSerializer = {
+export const htmlRichTextMapSerializer: prismic.HTMLRichTextMapSerializer = {
 	heading1: ({ children }) => `<h2>${children}</h2>`,
 	// `undefined` serializers should be treated the same as not including it.
 	heading2: undefined,

test/helpers-asHTML.test.ts

@@ -1,7 +1,7 @@
 import { expect, it } from "vitest";
 
-import { htmlFunctionSerializer } from "./__fixtures__/htmlFunctionSerializer";
-import { htmlMapSerializer } from "./__fixtures__/htmlMapSerializer";
+import { htmlRichTextFunctionSerializer } from "./__fixtures__/htmlRichTextFunctionSerializer";
+import { htmlRichTextMapSerializer } from "./__fixtures__/htmlRichTextMapSerializer";
 import { linkResolver } from "./__fixtures__/linkResolver";
 import { richTextFixture } from "./__fixtures__/richText";
 
@@ -13,13 +13,13 @@ it("serializes with default serializer", () => {
 
 it("serializes with a custom function serializer", () => {
 	expect(
-		asHTML(richTextFixture.en, linkResolver, htmlFunctionSerializer),
+		asHTML(richTextFixture.en, linkResolver, htmlRichTextFunctionSerializer),
 	).toMatchSnapshot();
 });
 
 it("serializes with a custom map serializer", () => {
 	expect(
-		asHTML(richTextFixture.en, linkResolver, htmlMapSerializer),
+		asHTML(richTextFixture.en, linkResolver, htmlRichTextMapSerializer),
 	).toMatchSnapshot();
 });