@paskdn-labs/html-parser-ts

v1.0.0

Published

3 months ago

A fast HTML parser for TypeScript with no dependencies. Creates a DOM tree from HTML strings.

0High
0Medium
0Low

paskdn

html parser dom typescript DOM parser HTML5

@paskdn-labs/html-parser-ts: A Zero-Dependency HTML Parser for TypeScript

@paskdn-labs/html-parser-ts is a fast HTML parser written in TypeScript. It has no dependencies. It turns HTML strings into a DOM tree for easy use.

Quick Usage Example

import { parseHtmlDocument } from '@paskdn-labs/html-parser-ts';

const htmlString = `
  <!DOCTYPE html>
  <html>
  <head>
    <title>My Page</title>
  </head>
  <body>
    <h1>Hello, World!</h1>
    <p>This is a paragraph.</p>
  </body>
  </html>
`;

const document = parseHtmlDocument(htmlString);

// Accessing elements
const h1Element = document.getElementsByTagName('h1')[0];
console.log(h1Element.textContent); // Output: Hello, World!

const pElement = document.getElementsByTagName('p')[0];
console.log(pElement.outerHTML); // Output: <p>This is a paragraph.</p>

Why @paskdn-labs/html-parser-ts?

Other HTML parsers are complex or need manual tag handling. This one is simple.

Zero-Dependency: No extra packages needed.
DOM Tree: Makes a full DOM from HTML.
Easy to Use: Simple code to parse and change HTML.
TypeScript: Works great with TypeScript.

Typescript Signature (Named Exported Library)

Details refer to core.ts on Github repo or @paskdn-labs/html-parser-ts/dist/core.d.ts on npm package.

Main Functions

function parseHtmlDocument (html: string, skipTrim?: boolean): Document;

type WalkResult = unknown | 'skip_child';
function walkNode         (node: Node, f: (node: Node, parent: Node, idx: number) => void, parent?: Node, idx?: number): WalkResult;
function walkNodeReversed (node: Node, f: (node: Node, parent: Node, idx: number) => void, parent?: Node): void;

function isTagName    (node: Node, tagName : string  ): boolean;
function isAnyTagName (node: Node, tagNames: string[]): boolean;

/** including the given node */
function getElementByTagName    (node: Node, tagName: string): HTMLElement | undefined;
/** including the given node */
function getElementsByTagName   (node: Node, tagName: string): HTMLElement[];
/** including the given node */
function hasElementByTagName    (node: Node, tagName: string): boolean;
/** including the given node */
function hasElementByAnyTagName (node: Node, tagNames: string[]): boolean;

Main Classes

abstract class Node {
    abstract outerHTML: string;
    abstract minifiedOuterHTML: string;
    abstract textContent: string | null;
    childNodes?: Node[];
    forEachChildNode(f: (node: Node, idx: number, childNodes: Node[]) => void): void;
    abstract clone(): this;
    static cloneChildNodes(node: Node): Node[] | undefined;
}
class Text extends Node {}
interface Attr {
    name: string;
    extraAfterName?: string;
    extraBeforeValue?: string;
    value?: string;
}
class Attributes extends Node {
    attrs: Array<Attr | string>;
    textContent: null;
    forEachAttr(f: (attr: Attr) => void): void;
    toObject(): Record<string, string>
    hasName(name: string): boolean;
    getValue(name: string): string | undefined;
}
class HTMLElement extends Node {
    tagName: string;
    parentElement?: HTMLElement;
    noBody?: boolean;
    attributes?: Attributes;
    notClosed: boolean;
    extraClosing?: boolean;
    textContent: string;
    innerHTML: string;
    /** @param tagName assume to be in lower case */
    isTagName(tagName: string): boolean;
    /** @param tagNames assume to be in lower case */
    isAnyTagName(tagNames: string[]): boolean;
    hasText(): boolean;
    /** not including this element */
    getElementsByTagName(tagName: string): HTMLElement[];
    /** not including this element */
    hasElementByTagName(tagName: string): boolean;
    /** not including this element */
    hasElementByAnyTagName(tagNames: string[]): boolean;
}
class Command extends HTMLElement {}
class Comment extends Command {
    tagName: string;
    content: string;
}
abstract class DSLElement extends HTMLElement {
    textContent: string;
    abstract minifiedTextContent: string;
}
class Style extends DSLElement {}
class Script extends DSLElement {}
class Document extends Node {
    childNodes: Node[];
}
// for easy reference
let NodeClasses = [
  Text,
  Attributes,
  HTMLElement,
  Command,
  Comment,
  DSLElement,
  Style,
  Script,
  Document,
];

Core Progress

Parse and encode html document / fragment:

[x] text
[x] normal element
[x] command
[x] short-closed elements
[x] comment
[ ] auto fix not properly closed elements*, e.g. li, td
[x] style
[x] script
- [x] regex
[x] svg
[x] extra string quote in attr*

Auto recover from extra string quote in attr*: e.g. <li class=" my-class"">

Auto fix not properly closed element

when unexpected closing tag is saw

  if the tag name is in the parent
    auto close until the matching parent
    auto create new opening tag to wrap following element

  if the tag name is not in the parent
    ignore the unexpected closing tag

Future work

To implement more query selector if needed.

License

This project is licensed under the MIT License.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme