Title ${index}
Lorem ipsum dolor sit amet, consectetur adipiscing Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Hello world
Paragraph ${index}
`, ).join(""); const manySiblings = buildDom(`${manySiblingsMarkup}
`);
// Deeply nested tree (depth=200)
function nestMarkup(depth: number): string {
if (depth === 0) return "leaf";
return `${nestMarkup(depth - 1)}
`;
}
const deeplyNested = buildDom(nestMarkup(200));
// Attribute-heavy element — 30 attributes each on 50 elements
const attributeHeavyMarkup = Array.from({ length: 50 }, (_, index) => {
const attributes = Array.from(
{ length: 30 },
(_, index_) => `data-attr-${index_}="value ${index_} & more"`,
).join(" ");
return `item ${index}
`;
}).join("");
const attributeHeavy = buildDom(attributeHeavyMarkup);
// SVG content (foreign mode)
const svgMarkup = ``;
const svgDom = buildDom(svgMarkup);
// Text-heavy content — lots of text nodes with entities
const textHeavyMarkup = Array.from(
{ length: 200 },
(_, index) =>
`Text with special chars: & < > " and unicode: \u00E9\u00E8\u00EA item ${index}
`, ).join(""); const textHeavy = buildDom(textHeavyMarkup); // Mixed realistic page const realisticPage = buildDom(`content ${index}
`,
).join("");
const commentsDom = buildDom(commentsMarkup);
// Empty/self-closing tags
const selfClosingMarkup = Array.from(
{ length: 200 },
() =>
'
',
).join("");
const selfClosingDom = buildDom(selfClosingMarkup);
const defaultOptions: DomSerializerOptions = {};
const xmlOptions: DomSerializerOptions = { xmlMode: true };
const foreignOptions: DomSerializerOptions = { xmlMode: "foreign" };
const utf8Options: DomSerializerOptions = { encodeEntities: "utf8" };
const selfClosingOptions: DomSerializerOptions = { selfClosingTags: true };
describe("Simple HTML", () => {
bench("render simple tag", () => {
render(simpleHtml, defaultOptions);
});
});
describe("Many siblings (500 elements)", () => {
bench("render many siblings", () => {
render(manySiblings, defaultOptions);
});
});
describe("Deeply nested (200 levels)", () => {
bench("render deeply nested", () => {
render(deeplyNested, defaultOptions);
});
});
describe("Attribute-heavy (50 elems × 30 attrs)", () => {
bench("render attribute-heavy", () => {
render(attributeHeavy, defaultOptions);
});
});
describe("SVG foreign mode", () => {
bench("render SVG (default)", () => {
render(svgDom, defaultOptions);
});
bench("render SVG (foreign)", () => {
render(svgDom, foreignOptions);
});
});
describe("Text-heavy with entities (200 paragraphs)", () => {
bench("render text-heavy (default)", () => {
render(textHeavy, defaultOptions);
});
bench("render text-heavy (utf8)", () => {
render(textHeavy, utf8Options);
});
});
describe("Realistic page", () => {
bench("render realistic page (default)", () => {
render(realisticPage, defaultOptions);
});
bench("render realistic page (utf8)", () => {
render(realisticPage, utf8Options);
});
bench("render realistic page (self-closing)", () => {
render(realisticPage, selfClosingOptions);
});
});
describe("XML mode (100 elements)", () => {
bench("render XML", () => {
render(xmlDom, xmlOptions);
});
});
describe("Comments (100 comments + elements)", () => {
bench("render comments", () => {
render(commentsDom, defaultOptions);
});
});
describe("Self-closing tags (1200 void elements)", () => {
bench("render self-closing tags", () => {
render(selfClosingDom, defaultOptions);
});
bench("render self-closing (with slash)", () => {
render(selfClosingDom, selfClosingOptions);
});
});
cheeriojs-dom-serializer-a6dc81c/src/index.spec.ts 0000664 0000000 0000000 00000023633 15175357524 0022330 0 ustar 00root root 0000000 0000000 import { type CheerioOptions, load } from "cheerio";
import { describe, expect, it } from "vitest";
import render from "./index.js";
interface LoadingOptions extends CheerioOptions {
_useHtmlParser2?: boolean;
decodeEntities?: boolean;
encodeEntities?: "utf8";
selfClosingTags?: boolean;
emptyAttrs?: boolean;
}
function html(
preset: LoadingOptions,
markup: string,
options: LoadingOptions = {},
) {
const options_ = { ...preset, ...options };
const $ = load(markup, options_, true);
return render($._root, options_);
}
function xml(markup: string, options: LoadingOptions = {}) {
const options_ = { ...options, xmlMode: true };
const $ = load(markup, options_, true);
return render($._root, options_);
}
describe("render DOM parsed with htmlparser2", () => {
// Only test applicable to the default setup
describe("(html)", () => {
const htmlFunction = html.bind(null, { _useHtmlParser2: true });
/*
* It doesn't really make sense for {decodeEntities: false}
* since currently it will convert into
anyway. */ it("should handle double quotes within single quoted attributes properly", () => { const markup = "
"; expect(htmlFunction(markup)).toStrictEqual( '
', ); }); it("should escape entities to utf8 if requested", () => { const markup = '& " < >'; expect( html({ _useHtmlParser2: true, encodeEntities: "utf8" }, markup), ).toStrictEqual('& " < >'); }); it("should stringify non-string attribute values before escaping", () => { const $ = load( "", { _useHtmlParser2: true } as CheerioOptions, true, ); const div = $("div")[0]; (div.attribs as Record
";
expect(xml(markup)).toStrictEqual('');
});
it('should append ="" to boolean attributes with no value', () => {
const markup = "";
expect(xml(markup)).toStrictEqual('');
});
it("should preserve XML prefixes on attributes", () => {
const markup =
'';
expect(xml(markup)).toStrictEqual(markup);
});
it("should preserve mixed-case XML elements and attributes", () => {
const markup = '';
expect(xml(markup)).toStrictEqual(markup);
});
it("should encode entities in otherwise special tags", () => {
expect(xml('')).toStrictEqual(
"",
);
});
it("should not encode entities if disabled", () => {
const markup = '';
expect(xml(markup, { decodeEntities: false })).toStrictEqual(markup);
});
it("should stringify non-string SVG attribute values before escaping", () => {
const $ = load("", { xmlMode: true }, true);
const rect = $("rect")[0];
(rect.attribs as Record).width = 42;
(rect.attribs as Record).height = 24;
expect(render($._root, { xmlMode: true })).toStrictEqual(
'',
);
});
});
});
describe("(xml, {selfClosingTags: false})", () => {
it("should render childless nodes with an explicit closing tag", () => {
const markup = "
tags correctly", () => { const markup = "
"; expect( html( { _useHtmlParser2: true, decodeEntities: false, selfClosingTags: true, }, markup, ), ).toStrictEqual(markup); }); }); describe("(html, {selfClosingTags: false})", () => { it("should render childless SVG nodes with an explicit closing tag", () => { const markup = ''; expect( html( { _useHtmlParser2: true, decodeEntities: false, selfClosingTags: false, }, markup, ), ).toStrictEqual(markup); }); }); function testBody(html: (input: string, options?: LoadingOptions) => string) { it("should render
tags without a slash", () => { const markup = "
"; expect(html(markup)).toStrictEqual("
"); }); it("should retain encoded HTML content within attributes", () => { const markup = '
'; expect(html(markup)).toStrictEqual( '
', ); }); it('should shorten the "checked" attribute when it contains the value "checked"', () => { const markup = ""; expect(html(markup)).toStrictEqual(""); }); it("should render empty attributes if asked for", () => { const markup = ""; expect(html(markup, { emptyAttrs: true })).toStrictEqual( '', ); }); it('should not shorten the "name" attribute when it contains the value "name"', () => { const markup = ''; expect(html(markup)).toStrictEqual(''); }); it('should not append ="" to attributes with no value', () => { const markup = "
text
tags correctly", () => { const markup = "
"; expect( html( { _useHtmlParser2: true, decodeEntities: false, selfClosingTags: true, }, markup, ), ).toStrictEqual(markup); }); }); describe("(html, {selfClosingTags: false})", () => { it("should render childless SVG nodes with an explicit closing tag", () => { const markup = ''; expect( html( { _useHtmlParser2: true, decodeEntities: false, selfClosingTags: false, }, markup, ), ).toStrictEqual(markup); }); }); function testBody(html: (input: string, options?: LoadingOptions) => string) { it("should render
tags without a slash", () => { const markup = "
"; expect(html(markup)).toStrictEqual("
"); }); it("should retain encoded HTML content within attributes", () => { const markup = '
'; expect(html(markup)).toStrictEqual( '
', ); }); it('should shorten the "checked" attribute when it contains the value "checked"', () => { const markup = ""; expect(html(markup)).toStrictEqual(""); }); it("should render empty attributes if asked for", () => { const markup = ""; expect(html(markup, { emptyAttrs: true })).toStrictEqual( '', ); }); it('should not shorten the "name" attribute when it contains the value "name"', () => { const markup = ''; expect(html(markup)).toStrictEqual(''); }); it('should not append ="" to attributes with no value', () => { const markup = "
";
expect(html(markup)).toStrictEqual("");
});
it("should render comments correctly", () => {
const markup = "";
expect(html(markup)).toStrictEqual("");
});
it("should render whitespace by default", () => {
const markup =
'hi blah';
expect(html(markup)).toStrictEqual(markup);
});
it("should preserve multiple hyphens in data attributes", () => {
const markup = '';
expect(html(markup)).toStrictEqual('');
});
it("should not encode characters in script tag", () => {
const markup = '';
expect(html(markup)).toStrictEqual(markup);
});
it("should not encode tags in script tag", () => {
const markup = '';
expect(html(markup)).toStrictEqual(markup);
});
it("should not encode json data", () => {
const markup =
'';
expect(html(markup)).toStrictEqual(markup);
});
it("should render childless SVG nodes with a closing slash in HTML mode", () => {
const markup =
'';
expect(html(markup)).toStrictEqual(markup);
});
it("should render childless MathML nodes with a closing slash in HTML mode", () => {
const markup = "";
expect(html(markup)).toStrictEqual(markup);
});
it("should allow SVG elements to have children", () => {
const markup =
'';
expect(html(markup)).toStrictEqual(markup);
});
it("should not include extra whitespace in SVG self-closed elements", () => {
const markup = '';
expect(html(markup)).toStrictEqual(markup);
});
it("should fix-up bad nesting in SVG in HTML mode", () => {
const markup = '';
expect(html(markup)).toStrictEqual(
'',
);
});
it("should preserve XML prefixed attributes on inline SVG nodes in HTML mode", () => {
const markup =
'';
expect(html(markup)).toStrictEqual(markup);
});
it("should handle mixed-case SVG content in HTML mode", () => {
const markup = '';
expect(html(markup)).toStrictEqual(markup);
});
it("should render HTML content in SVG foreignObject in HTML mode", () => {
const markup =
'';
expect(html(markup)).toStrictEqual(markup);
});
it("should render iframe nodes with a closing tag in HTML mode", () => {
const markup = '';
expect(html(markup)).toStrictEqual(markup);
});
it("should encode double quotes in attribute", () => {
const markup = `
`;
expect(html(markup)).toStrictEqual(
'',
);
});
}
cheeriojs-dom-serializer-a6dc81c/src/index.ts 0000664 0000000 0000000 00000023557 15175357524 0021404 0 ustar 00root root 0000000 0000000 import * as ElementType from "domelementtype";
import type {
AnyNode,
CDATA,
Comment,
Element,
ProcessingInstruction,
Text,
} from "domhandler";
import { encodeXML, escapeAttribute, escapeText } from "entities";
import { attributeNames, elementNames } from "./foreign-names.js";
/**
* Options for DOM serialization.
*/
export interface DomSerializerOptions {
/**
* Print an empty attribute's value.
* @default xmlMode
* @example With ,
options: DomSerializerOptions = {},
): string {
const nodes = "length" in node ? node : [node];
/*
* `xmlMode` is threaded as a separate argument through the internal
* functions so that foreign-mode transitions (svg/mathml ↔ html) can
* adjust it without copying the options object on every element.
*/
const xmlMode = options.xmlMode ?? false;
let output = "";
// eslint-disable-next-line unicorn/no-for-loop
for (let index = 0; index < nodes.length; index++) {
output += renderNode(nodes[index], options, xmlMode);
}
return output;
}
export default render;
// ── Internal rendering ───────────────────────────────────────────────
/**
* Render an array of child nodes (skips the single-node wrapping in `render`).
* @param children The child nodes to render.
* @param options The serialization options.
* @param xmlMode The XML mode to use.
*/
function renderChildren(
children: ArrayLike,
options: DomSerializerOptions,
xmlMode: boolean | "foreign",
): string {
let output = "";
// eslint-disable-next-line unicorn/no-for-loop
for (let index = 0; index < children.length; index++) {
output += renderNode(children[index], options, xmlMode);
}
return output;
}
function renderNode(
node: AnyNode,
options: DomSerializerOptions,
xmlMode: boolean | "foreign",
): string {
switch (node.type) {
case ElementType.Root: {
return renderChildren(node.children, options, xmlMode);
}
case ElementType.Directive: {
return `<${(node as ProcessingInstruction).data}>`;
}
case ElementType.Comment: {
return ``;
}
case ElementType.CDATA: {
return ``;
}
case ElementType.Script:
case ElementType.Style:
case ElementType.Tag: {
return renderTag(node as Element, options, xmlMode);
}
case ElementType.Text: {
const element = node as Text;
const data = element.data || "";
/*
* Skip encoding when entities weren't decoded on input, or when
* inside a raw-text element (script, style, etc.) in HTML mode.
*/
if (
(options.encodeEntities ?? options.decodeEntities) !== false &&
!(
!xmlMode &&
element.parent &&
unencodedElements.has((element.parent as Element).name)
)
) {
// `xmlMode: "foreign"` is truthy
return xmlMode || options.encodeEntities !== "utf8"
? encodeXML(data)
: escapeText(data);
}
return data;
}
}
}
function renderTag(
element: Element,
options: DomSerializerOptions,
xmlMode: boolean | "foreign",
) {
if (xmlMode === "foreign") {
// Correct lowercase element names back to their canonical mixed-case form
element.name = elementNames.get(element.name) ?? element.name;
// Integration points exit foreign mode: their children are HTML
if (
element.parent &&
foreignModeIntegrationPoints.has((element.parent as Element).name)
) {
xmlMode = false;
}
}
if (!xmlMode && foreignElements.has(element.name)) {
xmlMode = "foreign";
}
const { name, children } = element;
// Cache the void-element check — used for both self-closing and closing-tag logic
const isVoid = !xmlMode && voidElements.has(name);
let tag = `<${name}${formatAttributes(element.attribs, options, xmlMode)}`;
if (
children.length === 0 &&
(xmlMode
? options.selfClosingTags !== false
: options.selfClosingTags && isVoid)
) {
// XML: `
`, HTML: `
` tag += xmlMode ? "/>" : " />"; } else { tag += ">"; if (children.length > 0) { tag += renderChildren(children, options, xmlMode); } if (!isVoid) { tag += ``; } } return tag; } // ── Attribute formatting ───────────────────────────────────────────── function replaceQuotes(value: string): string { return value.replaceAll('"', """); } /** * Serialize an element's attribute map to a string. * * Returns a string with a leading space before each attribute, or an * empty string if there are no attributes. This convention lets the * caller unconditionally concatenate the result onto the tag name. * @param attributes * @param options * @param xmlMode */ function formatAttributes( attributes: Record | undefined,
options: DomSerializerOptions,
xmlMode: boolean | "foreign",
) {
if (!attributes) return "";
/*
* Pick the right encoder:
* - Encoding disabled → only escape double-quotes (for valid attributes)
* - XML / non-utf8 → full numeric entity encoding (encodeXML)
* - HTML + utf8 → minimal escaping (escapeAttribute)
*/
const encode =
(options.encodeEntities ?? options.decodeEntities) === false
? replaceQuotes
: xmlMode || options.encodeEntities !== "utf8"
? encodeXML
: escapeAttribute;
const isForeign = xmlMode === "foreign";
const showEmpty = !!(options.emptyAttrs ?? xmlMode);
let result = "";
for (const key in attributes) {
if (!Object.hasOwn(attributes, key)) continue;
const value = attributes[key];
const k = isForeign ? (attributeNames.get(key) ?? key) : key;
result +=
!showEmpty && (value == null || value === "")
? ` ${k}`
: ` ${k}="${encode(value == null ? "" : String(value))}"`;
}
return result;
}
cheeriojs-dom-serializer-a6dc81c/tsconfig.eslint.json 0000664 0000000 0000000 00000000215 15175357524 0023124 0 ustar 00root root 0000000 0000000 {
"extends": "./tsconfig.json",
"compilerOptions": {
"rootDir": ".",
"noEmit": true
},
"include": ["src"],
"exclude": []
}
cheeriojs-dom-serializer-a6dc81c/tsconfig.json 0000664 0000000 0000000 00000001303 15175357524 0021626 0 ustar 00root root 0000000 0000000 {
"compilerOptions": {
/* Basic Options */
"target": "es2022",
"module": "nodenext",
"moduleResolution": "nodenext",
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"rootDir": "./src",
"outDir": "./dist",
/* Strict Type-Checking Options */
"strict": true,
/* Additional Checks */
"noUnusedLocals": true,
"noUnusedParameters": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
/* Module Resolution Options */
"resolveJsonModule": true
},
"include": ["src"],
"exclude": [
"**/*.spec.ts",
"**/*.bench.ts",
"**/__fixtures__/*",
"**/__tests__/*",
"**/__snapshots__/*"
]
}
emptyAttrs: false: <input checked>
* @example With emptyAttrs: true: <input checked="">
*/
emptyAttrs?: boolean;
/**
* Print self-closing tags for tags without contents. If `xmlMode` is set,
* this will apply to all tags. Otherwise, only tags that are defined as
* self-closing in the HTML specification will be printed as such.
* @default xmlMode
* @example With selfClosingTags: false: <foo></foo><br></br>
* @example With xmlMode: true and selfClosingTags: true: <foo/><br/>
* @example With xmlMode: false and selfClosingTags: true: <foo></foo><br />
*/
selfClosingTags?: boolean;
/**
* Treat the input as an XML document; enables the `emptyAttrs` and
* `selfClosingTags` options.
*
* If the value is `"foreign"`, it will try to correct mixed-case attribute
* names.
* @default false
*/
xmlMode?: boolean | "foreign";
/**
* Encode characters reserved in HTML or XML in text and attribute values.
*
* If `xmlMode` is set or the value is not `'utf8'`, characters outside the
* ASCII range will also be encoded as numeric entities.
*
* **Security:** Setting this to `false` disables encoding of `<`, `>`, `&`,
* and (in attribute values) `'` — only `"` in attribute values is escaped.
* This is safe for the round-trip case (DOM was parsed with
* `decodeEntities: false`, so any markup characters in text or attribute
* values exist only as entity references), and unsafe otherwise. If text
* or attribute values in the DOM contain raw `<`, `>`, or `&`, those
* characters will appear literally in the output.
* @default `decodeEntities`
*/
encodeEntities?: boolean | "utf8";
/**
* Default for `encodeEntities`. Named to match the parser option of the
* same name so a single options object can be threaded through parse and
* serialize for a faithful round-trip — for example, cheerio parses with
* `decodeEntities: false` to preserve entity references and passes the
* same option here so they are not re-encoded.
*
* Despite the name, on the serializer this option controls *encoding*.
* Setting it to `false` carries the same caveat as `encodeEntities: false`
* — see that option.
* @default true
*/
decodeEntities?: boolean;
}
// ── Constants ────────────────────────────────────────────────────────
/** Elements whose text content is never entity-encoded. */
const unencodedElements = new Set(
"style script xmp iframe noembed noframes plaintext noscript".split(" "),
);
/** HTML void elements — they cannot have children. */
const voidElements = new Set(
"area base basefont br col command embed frame hr img input isindex keygen link meta param source track wbr".split(
" ",
),
);
/** Elements that switch the parser into foreign (XML-like) mode. */
const foreignElements = new Set(["svg", "math"]);
/**
* Foreign-mode integration points: children of these elements are parsed
* as HTML again, not as foreign content.
*/
const foreignModeIntegrationPoints = new Set(
"mi mo mn ms mtext annotation-xml foreignObject desc title".split(" "),
);
// ── Public API ───────────────────────────────────────────────────────
/**
* Renders a DOM node or an array of DOM nodes to a string.
*
* Can be thought of as the equivalent of the `outerHTML` of the passed
* node(s).
* @param node Node to be rendered.
* @param options Changes serialization behavior
*/
export function render(
node: AnyNode | ArrayLike`, HTML: `
` tag += xmlMode ? "/>" : " />"; } else { tag += ">"; if (children.length > 0) { tag += renderChildren(children, options, xmlMode); } if (!isVoid) { tag += ``; } } return tag; } // ── Attribute formatting ───────────────────────────────────────────── function replaceQuotes(value: string): string { return value.replaceAll('"', """); } /** * Serialize an element's attribute map to a string. * * Returns a string with a leading space before each attribute, or an * empty string if there are no attributes. This convention lets the * caller unconditionally concatenate the result onto the tag name. * @param attributes * @param options * @param xmlMode */ function formatAttributes( attributes: Record