@stll/html 0.0.1-placeholder.0 → 0.1.1

package/README.md

@@ -0,0 +1,23 @@
+# @stll/html
+
+String HTML and XML loading for tree-based consumers. HTML uses parse5 with
+its htmlparser2 tree adapter; XML uses `cheerio/slim` directly. This keeps
+Cheerio's byte decoders and HTTP client out of the server bundle.
+
+Import `load` and the Cheerio types from `@stll/html`, and DOM node types and predicates from `@stll/html/nodes`.
+Document mode is the default. Pass `false` as the third argument for fragments.
+The loader preserves parse5 serialization and context-aware parsing of inserted
+HTML through the per-document Cheerio hooks. XML options retain slim's parser
+and serializer.
+
+Fixture equivalence goldens live beside the API's HTML fixtures test in
+`packages/html/src/loader-equivalence.test.ts`. They contain SHA-256 hashes
+of the original Cheerio 1.2.0 HTML, XML, text, and post-insertion HTML output,
+plus input hashes, across every enrolled input and parser mode.
+
+Apache-2.0.
+
+`@stll/html/email` owns the shared scripting-disabled parse and serialization mode
+for email previews. `@stll/html/bounded` limits allocations during initial HTML
+loading, leaving later document edits outside that budget. `htmlTreeAdapter` is
+available for adapter instrumentation. Parser dependencies are declared only here.

package/dist/bounded.d.ts

@@ -0,0 +1,7 @@
+import { n as CheerioAPI } from "./selection-DiMoYiIl.js";
+type AllocationBudget = {
+  maxDomAllocations: number;
+  reject: () => never;
+};
+export declare const loadWithAllocationBudget: (html: string, { maxDomAllocations, reject }: AllocationBudget) => import("cheerio/slim").CheerioAPI;
+export type { CheerioAPI };

package/dist/bounded.js

@@ -0,0 +1,58 @@
+import { load } from "./load.js";
+import { isText } from "domhandler";
+import { adapter } from "parse5-htmlparser2-tree-adapter";
+// src/bounded.ts
+const loadWithAllocationBudget = (html, { maxDomAllocations, reject }) => {
+	let allocations = 0;
+	let parsingPublisherMarkup = true;
+	const charge = (count) => {
+		if (!parsingPublisherMarkup) return;
+		allocations += count;
+		if (allocations > maxDomAllocations) reject();
+	};
+	const treeAdapter = {
+		...adapter,
+		createDocument: () => {
+			charge(1);
+			return adapter.createDocument();
+		},
+		createDocumentFragment: () => {
+			charge(1);
+			return adapter.createDocumentFragment();
+		},
+		createElement: (...args) => {
+			charge(1 + args[2].length);
+			return adapter.createElement(...args);
+		},
+		createCommentNode: (...args) => {
+			charge(1);
+			return adapter.createCommentNode(...args);
+		},
+		createTextNode: (...args) => {
+			charge(1);
+			return adapter.createTextNode(...args);
+		},
+		insertText: (parent, text) => {
+			const last = parent.children.at(-1);
+			if (last === void 0 || !isText(last)) charge(1);
+			return adapter.insertText(parent, text);
+		},
+		insertTextBefore: (parent, text, reference) => {
+			const previous = reference.prev;
+			if (previous === null || !isText(previous)) charge(1);
+			return adapter.insertTextBefore(parent, text, reference);
+		},
+		setDocumentType: (...args) => {
+			charge(1);
+			return adapter.setDocumentType(...args);
+		},
+		adoptAttributes: (...args) => {
+			charge(args[1].length);
+			return adapter.adoptAttributes(...args);
+		}
+	};
+	const document = load(html, { treeAdapter });
+	parsingPublisherMarkup = false;
+	return document;
+};
+export { loadWithAllocationBudget };

package/dist/email.d.ts

@@ -0,0 +1,8 @@
+import { AnyNode } from "./nodes.js";
+export declare const EMAIL_PREVIEW_DOM_OPTIONS: Readonly<{
+  scriptingEnabled: false;
+  treeAdapter: import("parse5").TreeAdapter<import("parse5-htmlparser2-tree-adapter").Htmlparser2TreeAdapterMap>;
+}>;
+export declare const loadEmailDocument: (html: string) => import("cheerio/slim").CheerioAPI;
+export declare const serializeEmailNode: (node: AnyNode) => string;
+export declare const serializeEmailPreviewMarkup: ($: ReturnType<typeof loadEmailDocument>) => string;

package/dist/email.js

@@ -0,0 +1,15 @@
+import { load } from "./load.js";
+import { serializeOuter } from "parse5";
+import { adapter } from "parse5-htmlparser2-tree-adapter";
+// src/email.ts
+const EMAIL_PREVIEW_DOM_OPTIONS = Object.freeze({
+	scriptingEnabled: false,
+	treeAdapter: adapter
+});
+const loadEmailDocument = (html) => load(html, EMAIL_PREVIEW_DOM_OPTIONS);
+const serializeEmailNode = (node) => serializeOuter(node, EMAIL_PREVIEW_DOM_OPTIONS);
+const serializeEmailPreviewMarkup = ($) => {
+	const html = $("html").get(0);
+	return html ? serializeEmailNode(html) : "";
+};
+export { EMAIL_PREVIEW_DOM_OPTIONS, loadEmailDocument, serializeEmailNode, serializeEmailPreviewMarkup };

package/dist/load.d.ts

@@ -0,0 +1,5 @@
+import { n as CheerioAPI, r as CheerioOptions, t as Cheerio } from "./selection-DiMoYiIl.js";
+export declare const htmlTreeAdapter: import("parse5").TreeAdapter<import("parse5-htmlparser2-tree-adapter").Htmlparser2TreeAdapterMap>;
+/** Parse strings without loading Cheerio's byte decoders or HTTP client. */
+export declare const load: (content: string, options?: CheerioOptions | null, document?: boolean) => CheerioAPI;
+export type { Cheerio, CheerioAPI, CheerioOptions };

package/dist/load.js

@@ -0,0 +1,53 @@
+import { panic } from "better-result";
+import { load as load$1 } from "cheerio/slim";
+import { isDocument } from "domhandler";
+import { parse, parseFragment, serializeOuter } from "parse5";
+import { adapter } from "parse5-htmlparser2-tree-adapter";
+// src/load.ts
+const htmlTreeAdapter = adapter;
+/** Parse strings without loading Cheerio's byte decoders or HTTP client. */
+const load = (content, options, document = true) => {
+	if (usesXmlParser(options)) return load$1(content, options, document);
+	const parseOptions = {
+		...options,
+		treeAdapter: options?.treeAdapter ?? adapter,
+		scriptingEnabled: options?.scriptingEnabled !== false
+	};
+	const root = document ? parse(content, parseOptions) : parseFragment(content, parseOptions);
+	const $ = load$1(root, options, document);
+	const methods = Object.getOwnPropertyDescriptors($.fn);
+	const slimParse = methods._parse.value ?? panic("Cheerio must own its parse hook");
+	const slimRender = methods._render.value ?? panic("Cheerio must own its render hook");
+	const slimMake = methods._make.value ?? panic("Cheerio must own its selection hook");
+	$.fn._parse = function(markup, opts, isDoc, context) {
+		if (typeof markup !== "string" || opts._useHtmlParser2) return slimParse.call(this, markup, opts, isDoc, context);
+		const parserOptions = {
+			...opts,
+			treeAdapter: opts.treeAdapter ?? adapter,
+			scriptingEnabled: opts.scriptingEnabled !== false
+		};
+		return isDoc ? parse(markup, parserOptions) : parseFragment(context, markup, parserOptions);
+	};
+	$.fn._render = function(dom) {
+		if (this.options._useHtmlParser2) return slimRender.call(this, dom);
+		return ("length" in dom ? Array.from(dom) : [dom]).flatMap((node) => isDocument(node) ? node.children : [node]).map((node) => serializeOuter(node, { treeAdapter: adapter })).join("");
+	};
+	$.fn._make = new Proxy(slimMake, { apply(target, receiver, [selector, context]) {
+		return target.call(receiver, isMarkup(selector) ? parseFragment(selector, parseOptions).children : selector, isMarkup(context) ? parseFragment(context, parseOptions) : context);
+	} });
+	return new Proxy($, { apply(target, _thisArg, [selector, context, scope, opts]) {
+		if (usesXmlParser(opts)) return target(selector, context, scope, opts);
+		const parserOptions = {
+			...parseOptions,
+			...opts
+		};
+		return target(isMarkup(selector) ? parseFragment(selector, parserOptions).children : selector, isMarkup(context) ? parseFragment(context, parserOptions) : context, typeof scope === "string" ? parseFragment(scope, parserOptions) : scope, opts);
+	} });
+};
+const isMarkup = (value) => {
+	if (typeof value !== "string") return false;
+	const start = value.indexOf("<");
+	return start !== -1 && /[a-z!]/iu.test(value.charAt(start + 1)) && value.includes(">", start + 2);
+};
+const usesXmlParser = (options) => options?.xml === true || typeof options?.xml === "object" || options?.xmlMode === true;
+export { htmlTreeAdapter, load };

package/dist/nodes.d.ts

@@ -0,0 +1,10 @@
+import { AnyNode, Element, Element as Element$1, ParentNode, Text, Text as Text$1, cloneNode as cloneNode$1, hasChildren as hasChildren$1, isCDATA as isCDATA$1, isComment as isComment$1, isTag as isTag$1, isText as isText$1 } from "domhandler";
+export declare const createElement: (...args: ConstructorParameters<typeof Element$1>) => Element$1;
+export declare const createText: (data: string) => Text$1;
+export declare const cloneNode: typeof cloneNode$1;
+export declare const hasChildren: typeof hasChildren$1;
+export declare const isCDATA: typeof isCDATA$1;
+export declare const isComment: typeof isComment$1;
+export declare const isTag: typeof isTag$1;
+export declare const isText: typeof isText$1;
+export type { AnyNode, Element, ParentNode, Text };

package/dist/nodes.js

@@ -0,0 +1,11 @@
+import { Element, Text, cloneNode as cloneNode$1, hasChildren as hasChildren$1, isCDATA as isCDATA$1, isComment as isComment$1, isTag as isTag$1, isText as isText$1 } from "domhandler";
+// src/nodes.ts
+const createElement = (...args) => new Element(...args);
+const createText = (data) => new Text(data);
+const cloneNode = cloneNode$1;
+const hasChildren = hasChildren$1;
+const isCDATA = isCDATA$1;
+const isComment = isComment$1;
+const isTag = isTag$1;
+const isText = isText$1;
+export { cloneNode, createElement, createText, hasChildren, isCDATA, isComment, isTag, isText };

package/dist/selection-DiMoYiIl.d.ts

@@ -0,0 +1,5 @@
+import { Cheerio, CheerioAPI, CheerioOptions } from "cheerio/slim";
+type CheerioOptions$1 = Omit<CheerioOptions, "xmlMode"> & {
+  xmlMode?: boolean;
+};
+export { CheerioAPI as n, CheerioOptions$1 as r, Cheerio as t };

package/package.json

@@ -1 +1,74 @@
-{"name":"@stll/html","version":"0.0.1-placeholder.0","description":"String-only HTML parsing with Cheerio traversal","license":"Apache-2.0","repository":{"type":"git","url":"https://github.com/stella/stella.git","directory":"packages/html"}}
+{
+  "name": "@stll/html",
+  "version": "0.1.1",
+  "description": "String-only HTML parsing with Cheerio traversal",
+  "keywords": [
+    "cheerio",
+    "html",
+    "parse5",
+    "parser",
+    "xml"
+  ],
+  "homepage": "https://github.com/stella/stella/tree/main/packages/html",
+  "bugs": {
+    "url": "https://github.com/stella/stella/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stella/stella.git",
+    "directory": "packages/html"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/load.d.ts",
+      "import": "./dist/load.js"
+    },
+    "./nodes": {
+      "types": "./dist/nodes.d.ts",
+      "import": "./dist/nodes.js"
+    },
+    "./bounded": {
+      "types": "./dist/bounded.d.ts",
+      "import": "./dist/bounded.js"
+    },
+    "./email": {
+      "types": "./dist/email.d.ts",
+      "import": "./dist/email.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "git clean -xdf dist .cache .turbo node_modules",
+    "build": "tsdown",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "test": "bun test src",
+    "typecheck": "bun check --no-pretty --all --project=tsconfig.json",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --type-aware --type-check packages/html",
+    "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/html",
+    "prepack": "bun run build"
+  },
+  "devDependencies": {
+    "@stll/sha256": "0.0.0",
+    "@stll/typescript-config": "0.0.0",
+    "bun-types": "1.4.4",
+    "tsdown": "0.23.4"
+  },
+  "dependencies": {
+    "better-result": "3.0.1",
+    "cheerio": "^1.2.0",
+    "domhandler": "^5.0.3",
+    "parse5": "7.3.0",
+    "parse5-htmlparser2-tree-adapter": "7.1.0"
+  },
+  "main": "./dist/load.js",
+  "types": "./dist/load.d.ts"
+}