rusteerio 0.0.0-stage → 0.1.0

package/src/nodes.ts

@@ -0,0 +1,290 @@
+import type { NativeDocument, NativeNodeRecord } from './native.js';
+import type { AnyNode } from './types.js';
+import { nodePrototype } from './dom.js';
+import { sameNodeSpace } from './router.js';
+
+export interface NodeBinding { document: NativeDocument; id: number }
+interface ViewState { document: NativeDocument; id: number; lease?: object; children?: AnyNode[]; attributes?: Record<string, string>; maps?: Record<string, Record<string, string>> }
+interface NodeState { views: WeakMap<object, ViewState>; bindings: WeakMap<object, NodeBinding>; caches: WeakMap<object, Map<number, WeakRef<AnyNode>>>; finalizer: FinalizationRegistry<{ cache: Map<number, WeakRef<AnyNode>>; id: number }> }
+const nodeStateKey = Symbol.for('rusteerio.native-node-views.v2');
+const nodeGlobals = globalThis as typeof globalThis & { [key: symbol]: NodeState | undefined };
+const nodeState: NodeState = nodeGlobals[nodeStateKey] ??= { views: new WeakMap(), bindings: new WeakMap(), caches: new WeakMap(), finalizer: new FinalizationRegistry(({ cache, id }) => { if (!cache.get(id)?.deref()) cache.delete(id); }) };
+const { bindings, caches } = nodeState;
+const arrayIndex = /^(?:0|[1-9]\d*)$/;
+
+export function operation<T = any>(document: NativeDocument, command: string, args: unknown = {}): T {
+  const direct = (document as NativeDocument & { operate?(command: string, args: unknown): T }).operate;
+  if (direct) return direct.call(document, command, args);
+  const value = document.op(command, JSON.stringify(args));
+  return (value === undefined || value === '' ? undefined : JSON.parse(value)) as T;
+}
+
+export function nodeBinding(node: unknown): NodeBinding | undefined {
+  return node && typeof node === 'object' ? bindings.get(node) : undefined;
+}
+
+export function nodeId(node: unknown, document?: NativeDocument): number | undefined {
+  const binding = nodeBinding(node);
+  return binding && (!document || sameNodeSpace(document, binding.document)) ? binding.id : undefined;
+}
+
+/** Recreate parse5's null-prototype attribute maps and shared start-tag map. */
+export function hydrateLocation<T>(location: T): T {
+  if (!location || typeof location !== 'object') return location;
+  const value = location as Record<string, any>;
+  if (value.attrs && typeof value.attrs === 'object') Object.setPrototypeOf(value.attrs, null);
+  if (value.startTag?.attrs && typeof value.startTag.attrs === 'object') {
+    Object.setPrototypeOf(value.startTag.attrs, null);
+    if (value.attrs && JSON.stringify(value.attrs) === JSON.stringify(value.startTag.attrs)) value.startTag.attrs = value.attrs;
+  }
+  return location;
+}
+
+export function nodeRecord(document: NativeDocument, id: number): NativeNodeRecord {
+  return operation(document, 'node', { id });
+}
+
+function setField(document: NativeDocument, id: number, field: string, value: unknown): void {
+  operation(document, 'setNode', { id, field, value });
+}
+
+function attributes(document: NativeDocument, id: number, field = 'attribs', prototype: object | null = (document as NativeDocument & { options?: { _useHtmlParser2?: boolean } }).options?._useHtmlParser2 === false ? null : Object.prototype): Record<string, string> {
+  const read = () => (nodeRecord(document, id) as any)?.[field] ?? {};
+  const target = Object.create(prototype);
+  return new Proxy(target, {
+    get(_target, key) { return typeof key === 'symbol' ? Reflect.get(target, key) : Object.hasOwn(read(), key) ? read()[key] : Reflect.get(target, key); },
+    set(_target, key, value) { setField(document, id, field, { ...read(), [key]: String(value) }); return true; },
+    deleteProperty(_target, key) { const values = { ...read() }; delete values[key]; setField(document, id, field, values); return true; },
+    ownKeys() { return Reflect.ownKeys(read()); },
+    has(_target, key) { return Object.hasOwn(read(), key) || key in target; },
+    getOwnPropertyDescriptor(_target, key) { return Object.hasOwn(read(), key) ? { value: read()[key], writable: true, enumerable: true, configurable: true } : undefined; },
+    defineProperty(_target, key, descriptor) { const values = { ...read(), [key]: String(descriptor.value) }; setField(document, id, field, values); return true; },
+  });
+}
+
+function children(document: NativeDocument, id: number): AnyNode[] {
+  const read = (): number[] => nodeRecord(document, id)?.children ?? [];
+  const snapshot = () => read().map((child) => getNode(document, child));
+  const save = (nodes: unknown[]) => setField(document, id, 'children', importNodes(document, nodes));
+  const mutating = new Set(['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse', 'copyWithin', 'fill']);
+  const target: AnyNode[] = [];
+  return new Proxy(target, {
+    get(_target, key, receiver) {
+      if (key === 'length') return read().length;
+      if (typeof key === 'string' && arrayIndex.test(key)) { const child = read()[Number(key)]; return child === undefined ? undefined : getNode(document, child); }
+      if (typeof key === 'string' && mutating.has(key)) return (...args: unknown[]) => {
+        const values = snapshot();
+        const result = Reflect.apply((Array.prototype as any)[key], values, args);
+        save(values);
+        return result === values ? receiver : result;
+      };
+      return Reflect.get(target, key, receiver);
+    },
+    set(_target, key, value) {
+      const values = snapshot();
+      if (key === 'length') values.length = value;
+      else if (typeof key === 'string' && arrayIndex.test(key)) values[Number(key)] = value;
+      else return Reflect.set(target, key, value);
+      save(values); return true;
+    },
+    deleteProperty(_target, key) { if (typeof key === 'string' && arrayIndex.test(key)) { const values = snapshot(); values.splice(Number(key), 1); save(values); return true; } return Reflect.deleteProperty(target, key); },
+    has(_target, key) { return typeof key === 'string' && arrayIndex.test(key) ? Number(key) < read().length : Reflect.has(target, key); },
+    ownKeys() { return [...read().map((_child, i) => String(i)), 'length']; },
+    getOwnPropertyDescriptor(_target, key) {
+      if (key === 'length') return { ...Reflect.getOwnPropertyDescriptor(target, 'length')!, value: read().length };
+      if (typeof key === 'string' && arrayIndex.test(key) && Number(key) < read().length) return { value: getNode(document, read()[Number(key)]), writable: true, enumerable: true, configurable: true };
+      return Reflect.getOwnPropertyDescriptor(target, key);
+    },
+  });
+}
+
+const parentAliases: Record<string, string> = { parentNode: 'parent', previousSibling: 'prev', nextSibling: 'next' };
+const sourceFields = new Set(['type', 'name', 'data', 'namespace', 'prefix', 'startIndex', 'endIndex', 'sourceCodeLocation', 'x-name', 'x-publicId', 'x-systemId', 'x-mode']);
+const tagTypes = new Set(['tag', 'script', 'style']);
+const parentTypes = new Set(['root', 'tag', 'script', 'style', 'cdata']);
+const dataTypes = new Set(['text', 'comment', 'directive']);
+function viewKeys(record: NativeNodeRecord): string[] {
+  const keys = ['parent', 'prev', 'next', 'startIndex', 'endIndex'];
+  if (parentTypes.has(record.type)) keys.push('children');
+  if (record.data !== undefined) keys.push('data');
+  if (record.name !== undefined) keys.push('name');
+  if (tagTypes.has(record.type)) keys.push('attribs');
+  keys.push('type');
+  for (const field of sourceFields) if (!keys.includes(field) && field in record) keys.push(field);
+  if (tagTypes.has(record.type)) {
+    if ('attribsNamespace' in record) keys.push('x-attribsNamespace');
+    if ('attribsPrefix' in record) keys.push('x-attribsPrefix');
+  }
+  return keys;
+}
+function viewValue(state: ViewState, key: string, receiver: any): any {
+  const { document, id } = state;
+  const record = nodeRecord(document, id);
+  if (key === 'cloneNode') return cloneNode;
+  if (key === 'nodeType') return ({ root: 9, text: 3, comment: 8, cdata: 4 } as Record<string, number>)[record.type] ?? 1;
+  if (key === 'tagName' && tagTypes.has(record.type)) return record.name;
+  if (key === 'nodeValue' && dataTypes.has(record.type)) return record.data;
+  const pointer = parentAliases[key] ?? key;
+  if (['parent', 'prev', 'next'].includes(pointer)) return record[pointer] == null ? null : getNode(document, record[pointer]);
+  if (['children', 'childNodes', 'firstChild', 'lastChild'].includes(key) && parentTypes.has(record.type)) {
+    const list = state.children ??= children(document, id);
+    return key === 'firstChild' ? list[0] ?? null : key === 'lastChild' ? list[list.length - 1] ?? null : list;
+  }
+  if (key === 'attribs' && tagTypes.has(record.type)) return state.attributes ??= attributes(document, id);
+  if ((key === 'x-attribsNamespace' && 'attribsNamespace' in record || key === 'x-attribsPrefix' && 'attribsPrefix' in record) && tagTypes.has(record.type)) {
+    state.maps ??= {};
+    return state.maps[key] ??= attributes(document, id, key === 'x-attribsNamespace' ? 'attribsNamespace' : 'attribsPrefix');
+  }
+  if (key === 'attributes' && tagTypes.has(record.type)) {
+    const attrs = state.attributes ??= attributes(document, id);
+    return Object.keys(attrs).map((name) => ({ name, value: attrs[name], namespace: record.attribsNamespace?.[name], prefix: record.attribsPrefix?.[name] }));
+  }
+  if (key === 'sourceCodeLocation') return hydrateLocation(record[key]);
+  if (sourceFields.has(key)) return record[key] ?? (key === 'startIndex' || key === 'endIndex' ? null : undefined);
+  return undefined;
+}
+function writeView(state: ViewState, key: string, value: any): boolean {
+  const { document, id } = state;
+  const record = nodeRecord(document, id);
+  if (key === 'tagName' && tagTypes.has(record.type)) key = 'name';
+  else if (key === 'nodeValue' && dataTypes.has(record.type)) key = 'data';
+  else if (key === 'childNodes') key = 'children';
+  else key = parentAliases[key] ?? key;
+  if (sourceFields.has(key) || ['attribs', 'x-attribsNamespace', 'x-attribsPrefix'].includes(key)) { setField(document, id, key, value); return true; }
+  if (key === 'children' && parentTypes.has(record.type)) { setField(document, id, key, importNodes(document, value)); return true; }
+  if (['parent', 'prev', 'next'].includes(key)) { setField(document, id, key, value == null ? null : importNodes(document, [value])[0]); return true; }
+  return false;
+}
+const nodeHandler: ProxyHandler<object> = {
+  get(target, key, receiver) {
+    if (Reflect.getOwnPropertyDescriptor(target, key)) return Reflect.get(target, key, receiver);
+    if (typeof key === 'string') {
+      const state = nodeState.views.get(target)!;
+      if (key === 'cloneNode' || key === 'nodeType' || sourceFields.has(key) || ['tagName', 'nodeValue', 'parent', 'prev', 'next', 'parentNode', 'previousSibling', 'nextSibling', 'children', 'childNodes', 'firstChild', 'lastChild', 'attribs', 'attributes', 'x-attribsNamespace', 'x-attribsPrefix'].includes(key)) return viewValue(state, key, receiver);
+    }
+    return Reflect.get(target, key, receiver);
+  },
+  set(target, key, value, receiver) {
+    if (Reflect.getOwnPropertyDescriptor(target, key)) return Reflect.set(target, key, value, receiver);
+    if (typeof key === 'string' && writeView(nodeState.views.get(target)!, key, value)) return true;
+    return Reflect.set(target, key, value, receiver);
+  },
+  has(target, key) { return Reflect.has(target, key) || typeof key === 'string' && (viewKeys(nodeRecord(nodeState.views.get(target)!.document, nodeState.views.get(target)!.id)).includes(key) || ['cloneNode', 'nodeType', 'parentNode', 'previousSibling', 'nextSibling'].includes(key)); },
+  ownKeys(target) { const state = nodeState.views.get(target)!; return [...new Set([...viewKeys(nodeRecord(state.document, state.id)), ...Reflect.ownKeys(target)])]; },
+  getOwnPropertyDescriptor(target, key) {
+    const existing = Reflect.getOwnPropertyDescriptor(target, key);
+    if (existing) return existing;
+    const state = nodeState.views.get(target)!;
+    if (typeof key === 'string' && viewKeys(nodeRecord(state.document, state.id)).includes(key)) return { value: viewValue(state, key, undefined), configurable: true, enumerable: true, writable: true };
+    return undefined;
+  },
+};
+
+/** Stable DOM node identities; each property reads or updates the Rust arena. */
+export function getNode(document: NativeDocument, id: number, original?: any): AnyNode {
+  const cacheKey = document.nodeSpace ?? document;
+  let cache = caches.get(cacheKey);
+  if (!cache) caches.set(cacheKey, cache = new Map());
+  const existing = cache.get(id)?.deref();
+  if (existing) return existing;
+  document = (document as NativeDocument & { nodeDocument?(id: number): NativeDocument }).nodeDocument?.(id) ?? document;
+  const lease = (document as NativeDocument & { retainNodes?(ids: number[]): object }).retainNodes?.([id]);
+  const record = nodeRecord(document, id);
+  if (!record) return undefined as unknown as AnyNode;
+  if (original === undefined) {
+    const target = Object.create(nodePrototype(record.type));
+    const node = new Proxy(target, nodeHandler) as AnyNode;
+    nodeState.views.set(target, { document, id, lease });
+    cache.set(id, new WeakRef(node));
+    nodeState.finalizer.register(node, { cache, id });
+    bindings.set(node, { document, id });
+    return node;
+  }
+  const node: any = original;
+  cache.set(id, new WeakRef(node));
+  nodeState.finalizer.register(node, { cache, id });
+  bindings.set(node, { document, id });
+  const read = (): any => { void lease; return nodeRecord(document, id); };
+  const define = (key: string, get: () => unknown, set?: (value: any) => void, enumerable = true) => {
+    try { Object.defineProperty(node, key, { configurable: true, enumerable, get, ...(set ? { set } : {}) }); } catch { /* Foreign user properties may be non-configurable. */ }
+  };
+  for (const field of ['type', 'name', 'data', 'namespace', 'prefix', 'startIndex', 'endIndex', 'sourceCodeLocation', 'x-name', 'x-publicId', 'x-systemId', 'x-mode']) {
+    if (field in record || ['type', 'startIndex', 'endIndex'].includes(field)) define(field, () => (field === 'sourceCodeLocation' ? hydrateLocation(read()[field]) : read()[field]) ?? (field === 'startIndex' || field === 'endIndex' ? null : undefined), (value) => setField(document, id, field, value));
+  }
+  for (const field of ['parent', 'prev', 'next']) define(field, () => { const value = read()[field]; return value === null || value === undefined ? null : getNode(document, value); }, (value) => setField(document, id, field, value == null ? null : importNodes(document, [value])[0]));
+  for (const [alias, field] of [['parentNode', 'parent'], ['previousSibling', 'prev'], ['nextSibling', 'next']]) define(alias, () => node[field], (value) => { node[field] = value; }, false);
+  if ('children' in record && ['root', 'tag', 'script', 'style', 'cdata'].includes(record.type)) {
+    const list = children(document, id);
+    define('children', () => list, (value) => setField(document, id, 'children', importNodes(document, value)));
+    define('childNodes', () => list, (value) => { node.children = value; }, false);
+    define('firstChild', () => list[0] ?? null, undefined, false);
+    define('lastChild', () => list[list.length - 1] ?? null, undefined, false);
+  }
+  if (['tag', 'script', 'style'].includes(record.type)) {
+    const attrs = attributes(document, id, 'attribs', Object.getPrototypeOf(original.attribs ?? {}));
+    define('attribs', () => attrs, (value) => setField(document, id, 'attribs', value));
+    define('tagName', () => node.name, (value) => { node.name = value; }, false);
+    for (const field of ['x-attribsNamespace', 'x-attribsPrefix']) {
+      if (!((field === 'x-attribsNamespace' ? 'attribsNamespace' : 'attribsPrefix') in record) && !Object.hasOwn(original, field)) continue;
+      const values = attributes(document, id, field === 'x-attribsNamespace' ? 'attribsNamespace' : 'attribsPrefix');
+      define(field, () => values, (value) => setField(document, id, field, value));
+    }
+    define('attributes', () => Object.keys(attrs).map((name) => ({ name, value: attrs[name], namespace: read().attribsNamespace?.[name], prefix: read().attribsPrefix?.[name] })), undefined, false);
+  }
+  if (['text', 'comment', 'directive'].includes(record.type)) define('nodeValue', () => node.data, (value) => { node.data = value; }, false);
+  define('nodeType', () => ({ root: 9, text: 3, comment: 8, cdata: 4 } as Record<string, number>)[read().type] ?? 1, undefined, false);
+  Object.defineProperty(node, 'cloneNode', { configurable: true, enumerable: false, writable: true, value: cloneNode });
+  return node;
+}
+
+/** Clone through the receiver's current native owner, including borrowed calls. */
+export function cloneNode<T extends AnyNode>(this: T, recursive = false): T {
+  const binding = nodeBinding(this);
+  if (!binding) throw new TypeError('cloneNode requires a native DOM node receiver');
+  return getNode(binding.document, operation<number[]>(binding.document, 'clone', { ids: [binding.id], deep: recursive })[0]) as T;
+}
+
+/** Import external DOM nodes once and keep their object identities as handles. */
+export function importNodes(document: NativeDocument, input: unknown): number[] {
+  if (input == null || input === false) return [];
+  const values: any[] = Array.isArray(input) || (typeof input === 'object' && 'length' in input && !('type' in input)) ? Array.from(input as ArrayLike<any>) : [input];
+  const result: number[] = [];
+  for (const node of values) {
+    if (node == null) continue;
+    const existing = nodeId(node, document);
+    if (existing !== undefined) { document.retainNode?.(existing); result.push(existing); continue; }
+    if (typeof node !== 'object' || typeof node.type !== 'string') continue;
+    const records: any[] = [];
+    const originals = new Map<number, any>();
+    const visit = (value: any, parent?: number): number => {
+      const id = records.length;
+      const record: any = { id, type: value.type, children: [], ...(parent === undefined ? {} : { parent }) };
+      records.push(record); originals.set(id, value);
+      for (const field of ['name', 'data', 'namespace', 'prefix', 'startIndex', 'endIndex', 'sourceCodeLocation', 'x-name', 'x-publicId', 'x-systemId', 'x-mode']) if (value[field] !== undefined) record[field] = value[field];
+      if (value.attribs) record.attribs = { ...value.attribs };
+      if (value['x-attribsNamespace']) record.attribsNamespace = { ...value['x-attribsNamespace'] };
+      if (value['x-attribsPrefix']) record.attribsPrefix = { ...value['x-attribsPrefix'] };
+      record.children = (value.children ?? []).map((child: any) => visit(child, id));
+      return id;
+    };
+    const root = visit(node);
+    const imported = operation<number[]>(document, 'import', { nodes: records, roots: [root] });
+    if (!imported.length) continue;
+    const adopt = (oldId: number, newId: number): void => {
+      const source = originals.get(oldId);
+      const oldChildren = records[oldId].children;
+      const newChildren = nodeRecord(document, newId).children ?? [];
+      // A node already belonging to another Rust document must retain its
+      // original document handle. Imported clones receive their own handles.
+      getNode(document, newId, nodeBinding(source) ? undefined : source);
+      for (let i = 0; i < oldChildren.length; i++) if (newChildren[i] !== undefined) adopt(oldChildren[i], newChildren[i]);
+    };
+    adopt(root, imported[0]);
+    result.push(imported[0]);
+  }
+  return result;
+}
+
+export const isTag = (node: any): boolean => !!node && ['tag', 'script', 'style'].includes(node.type);
+export const isDocument = (node: any): boolean => node?.type === 'root';
+export const hasChildren = (node: any): boolean => !!node && 'children' in node;

package/src/parse.ts

@@ -0,0 +1,53 @@
+import { requireNative } from './native.js';
+import { getNode, importNodes, nodeBinding, operation } from './nodes.js';
+import { routeDocument } from './router.js';
+import { parseNativeDocument, cleanParserOptions } from './hooks.js';
+import type { AnyNode, Document, InternalOptions, ParentNode } from './types.js';
+
+type ParseContent = string | Buffer | Document | AnyNode | AnyNode[];
+type Parser = (content: string, options: InternalOptions, isDocument: boolean, context: ParentNode | null) => Document;
+
+/** Parse with the Rust HTML5 or HTML/XML engine, preserving fragment context. */
+function parseWithNative(content: string, options: InternalOptions, isDocument: boolean, context: ParentNode | null): Document {
+  if (!isDocument && context) {
+    const document = nodeBinding(context)?.document
+      ?? routeDocument(new (requireNative().NativeDocument)('', false, JSON.stringify(cleanParserOptions(options))), options);
+    const contextId = importNodes(document, [context])[0];
+    const children = operation<number[]>(document, 'create', { html: content, contextId, options });
+    const root = operation<number>(document, 'createNode', { type: 'root', options });
+    operation(document, 'setNode', { id: root, field: 'children', value: children, options });
+    return getNode(document, root) as Document;
+  }
+  const document = parseNativeDocument(content, options, isDocument);
+  return getNode(document, document.rootId()) as Document;
+}
+
+/** The HTML5 adapter uses Rust's HTML5 tree builder. */
+export function parseWithParse5(content: string, options: InternalOptions, isDocument: boolean, context: ParentNode | null): Document {
+  return parseWithNative(content, { ...options, _useHtmlParser2: false, xml: false, xmlMode: false }, isDocument, context);
+}
+
+/** The htmlparser2-compatible adapter uses the Rust HTML/XML tokenizer. */
+export function parseWithHtmlparser2(content: string, options: InternalOptions): Document {
+  return parseWithNative(content, { ...options, _useHtmlParser2: true }, false, null);
+}
+
+export { parseWithHtmlparser2 as parseDocument };
+
+/** Normalize parser inputs while keeping every DOM operation in the native arena. */
+export function getParse(parser: Parser) {
+  return function parse(content: ParseContent, options: InternalOptions, isDocument: boolean, context: ParentNode | null): Document {
+    if (Buffer.isBuffer(content)) content = content.toString();
+    if (typeof content === 'string') return parser(content, options, isDocument, context);
+    if (!Array.isArray(content) && content.type === 'root' && nodeBinding(content)) return content;
+    const document = routeDocument(new (requireNative().NativeDocument)('', false, JSON.stringify(cleanParserOptions(options))), options);
+    const ids = importNodes(document, content);
+    if (!Array.isArray(content) && content.type === 'root') return getNode(document, ids[0]) as Document;
+    operation(document, 'setNode', { id: document.rootId(), field: 'children', value: ids, options });
+    return getNode(document, document.rootId()) as Document;
+  };
+}
+
+export const parse = getParse((content, options, isDocument, context) => options._useHtmlParser2
+  ? parseWithHtmlparser2(content, options)
+  : parseWithParse5(content, options, isDocument, context));

package/src/parser-types.ts

@@ -0,0 +1,157 @@
+import type { AnyNode, ParentNode, ChildNode, Document, Element, Comment, Text, ProcessingInstruction, SourceCodeLocation, TagSourceCodeLocation } from './types.js';
+
+/** Parse5-compatible diagnostics, declared locally without a parser dependency. */
+declare enum ERR {
+    controlCharacterInInputStream = "control-character-in-input-stream",
+    noncharacterInInputStream = "noncharacter-in-input-stream",
+    surrogateInInputStream = "surrogate-in-input-stream",
+    nonVoidHtmlElementStartTagWithTrailingSolidus = "non-void-html-element-start-tag-with-trailing-solidus",
+    endTagWithAttributes = "end-tag-with-attributes",
+    endTagWithTrailingSolidus = "end-tag-with-trailing-solidus",
+    unexpectedSolidusInTag = "unexpected-solidus-in-tag",
+    unexpectedNullCharacter = "unexpected-null-character",
+    unexpectedQuestionMarkInsteadOfTagName = "unexpected-question-mark-instead-of-tag-name",
+    invalidFirstCharacterOfTagName = "invalid-first-character-of-tag-name",
+    unexpectedEqualsSignBeforeAttributeName = "unexpected-equals-sign-before-attribute-name",
+    missingEndTagName = "missing-end-tag-name",
+    unexpectedCharacterInAttributeName = "unexpected-character-in-attribute-name",
+    unknownNamedCharacterReference = "unknown-named-character-reference",
+    missingSemicolonAfterCharacterReference = "missing-semicolon-after-character-reference",
+    unexpectedCharacterAfterDoctypeSystemIdentifier = "unexpected-character-after-doctype-system-identifier",
+    unexpectedCharacterInUnquotedAttributeValue = "unexpected-character-in-unquoted-attribute-value",
+    eofBeforeTagName = "eof-before-tag-name",
+    eofInTag = "eof-in-tag",
+    missingAttributeValue = "missing-attribute-value",
+    missingWhitespaceBetweenAttributes = "missing-whitespace-between-attributes",
+    missingWhitespaceAfterDoctypePublicKeyword = "missing-whitespace-after-doctype-public-keyword",
+    missingWhitespaceBetweenDoctypePublicAndSystemIdentifiers = "missing-whitespace-between-doctype-public-and-system-identifiers",
+    missingWhitespaceAfterDoctypeSystemKeyword = "missing-whitespace-after-doctype-system-keyword",
+    missingQuoteBeforeDoctypePublicIdentifier = "missing-quote-before-doctype-public-identifier",
+    missingQuoteBeforeDoctypeSystemIdentifier = "missing-quote-before-doctype-system-identifier",
+    missingDoctypePublicIdentifier = "missing-doctype-public-identifier",
+    missingDoctypeSystemIdentifier = "missing-doctype-system-identifier",
+    abruptDoctypePublicIdentifier = "abrupt-doctype-public-identifier",
+    abruptDoctypeSystemIdentifier = "abrupt-doctype-system-identifier",
+    cdataInHtmlContent = "cdata-in-html-content",
+    incorrectlyOpenedComment = "incorrectly-opened-comment",
+    eofInScriptHtmlCommentLikeText = "eof-in-script-html-comment-like-text",
+    eofInDoctype = "eof-in-doctype",
+    nestedComment = "nested-comment",
+    abruptClosingOfEmptyComment = "abrupt-closing-of-empty-comment",
+    eofInComment = "eof-in-comment",
+    incorrectlyClosedComment = "incorrectly-closed-comment",
+    eofInCdata = "eof-in-cdata",
+    absenceOfDigitsInNumericCharacterReference = "absence-of-digits-in-numeric-character-reference",
+    nullCharacterReference = "null-character-reference",
+    surrogateCharacterReference = "surrogate-character-reference",
+    characterReferenceOutsideUnicodeRange = "character-reference-outside-unicode-range",
+    controlCharacterReference = "control-character-reference",
+    noncharacterCharacterReference = "noncharacter-character-reference",
+    missingWhitespaceBeforeDoctypeName = "missing-whitespace-before-doctype-name",
+    missingDoctypeName = "missing-doctype-name",
+    invalidCharacterSequenceAfterDoctypeName = "invalid-character-sequence-after-doctype-name",
+    duplicateAttribute = "duplicate-attribute",
+    nonConformingDoctype = "non-conforming-doctype",
+    missingDoctype = "missing-doctype",
+    misplacedDoctype = "misplaced-doctype",
+    endTagWithoutMatchingOpenElement = "end-tag-without-matching-open-element",
+    closingOfElementWithOpenChildElements = "closing-of-element-with-open-child-elements",
+    disallowedContentInNoscriptInHead = "disallowed-content-in-noscript-in-head",
+    openElementsLeftAfterEof = "open-elements-left-after-eof",
+    abandonedHeadElementChild = "abandoned-head-element-child",
+    misplacedStartTagForHeadElement = "misplaced-start-tag-for-head-element",
+    nestedNoscriptInHead = "nested-noscript-in-head",
+    eofInElementThatCanContainOnlyText = "eof-in-element-that-can-contain-only-text"
+}
+
+export type ParserErrorCode = ERR;
+export interface ParserError extends SourceCodeLocation { code: ParserErrorCode }
+export type ParserErrorHandler = (error: ParserError) => void;
+
+declare enum NS {
+  HTML = 'http://www.w3.org/1999/xhtml',
+  MATHML = 'http://www.w3.org/1998/Math/MathML',
+  SVG = 'http://www.w3.org/2000/svg',
+  XLINK = 'http://www.w3.org/1999/xlink',
+  XML = 'http://www.w3.org/XML/1998/namespace',
+  XMLNS = 'http://www.w3.org/2000/xmlns/',
+}
+declare enum DOCUMENT_MODE {
+  NO_QUIRKS = 'no-quirks', QUIRKS = 'quirks', LIMITED_QUIRKS = 'limited-quirks',
+}
+export type NamespaceURI = NS;
+export type DocumentMode = DOCUMENT_MODE;
+export interface TreeAdapterAttribute { name: string; value: string; namespace?: string; prefix?: string }
+
+/** The HTML5 adapter shape used by Cheerio's DOM representation. */
+export interface TreeAdapter {
+  adoptAttributes(recipient: Element, attrs: TreeAdapterAttribute[]): void;
+  appendChild(parentNode: ParentNode, newNode: ChildNode): void;
+  createCommentNode(data: string): Comment;
+  createTextNode(value: string): Text;
+  createDocument(): Document;
+  createDocumentFragment(): Document;
+  createElement(tagName: string, namespaceURI: NamespaceURI, attrs: TreeAdapterAttribute[]): Element;
+  detachNode(node: ChildNode): void;
+  getAttrList(element: Element): TreeAdapterAttribute[];
+  getChildNodes(node: ParentNode): ChildNode[];
+  getCommentNodeContent(node: Comment): string;
+  getDocumentMode(document: Document): DocumentMode;
+  getDocumentTypeNodeName(node: ProcessingInstruction): string;
+  getDocumentTypeNodePublicId(node: ProcessingInstruction): string;
+  getDocumentTypeNodeSystemId(node: ProcessingInstruction): string;
+  getFirstChild(node: ParentNode): ChildNode | null;
+  getNamespaceURI(element: Element): NamespaceURI;
+  getNodeSourceCodeLocation(node: AnyNode): TagSourceCodeLocation | undefined | null;
+  getParentNode(node: AnyNode): ParentNode | null;
+  getTagName(element: Element): string;
+  getTextNodeContent(node: Text): string;
+  getTemplateContent(element: Element): Document;
+  insertBefore(parent: ParentNode, child: ChildNode, reference: ChildNode): void;
+  insertText(parent: ParentNode, text: string): void;
+  insertTextBefore(parent: ParentNode, text: string, reference: ChildNode): void;
+  isCommentNode(node: AnyNode): node is Comment;
+  isDocumentTypeNode(node: AnyNode): node is ProcessingInstruction;
+  isElementNode(node: AnyNode): node is Element;
+  isTextNode(node: AnyNode): node is Text;
+  setDocumentMode(document: Document, mode: DocumentMode): void;
+  setDocumentType(document: Document, name: string, publicId: string, systemId: string): void;
+  setNodeSourceCodeLocation(node: AnyNode, location: TagSourceCodeLocation | null): void;
+  updateNodeSourceCodeLocation(node: AnyNode, location: Partial<TagSourceCodeLocation>): void;
+  setTemplateContent(element: Element, content: Document): void;
+  onItemPush?: (item: Element) => void;
+  onItemPop?: (item: Element, newTop: ParentNode) => void;
+}
+
+declare enum QuoteType { NoValue = 0, Unquoted = 1, Single = 2, Double = 3 }
+export interface TokenizerCallbacks {
+  onattribdata(start: number, endIndex: number): void;
+  onattribentity(codepoint: number): void;
+  onattribend(quote: QuoteType, endIndex: number): void;
+  onattribname(start: number, endIndex: number): void;
+  oncdata(start: number, endIndex: number, endOffset: number): void;
+  onclosetag(start: number, endIndex: number): void;
+  oncomment(start: number, endIndex: number, endOffset: number): void;
+  ondeclaration(start: number, endIndex: number): void;
+  onend(): void;
+  onopentagend(endIndex: number): void;
+  onopentagname(start: number, endIndex: number): void;
+  onprocessinginstruction(start: number, endIndex: number): void;
+  onselfclosingtag(endIndex: number): void;
+  ontext(start: number, endIndex: number): void;
+  ontextentity(codepoint: number, endIndex: number): void;
+}
+export interface Tokenizer {
+  running: boolean;
+  reset(): void;
+  write(chunk: string): void;
+  end(): void;
+  pause(): void;
+  resume(): void;
+}
+export interface TokenizerOptions { xmlMode?: boolean; decodeEntities?: boolean }
+export interface TokenizerConstructor {
+  new (options: TokenizerOptions, callbacks: TokenizerCallbacks): Tokenizer;
+  // The native facade accepts third-party tokenizer classes with private state.
+  new (options: TokenizerOptions, callbacks: TokenizerCallbacks): any;
+}