Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/b-fuze/deno-dom
Browser DOM & HTML parser in Deno
https://github.com/b-fuze/deno-dom
browser-dom deno dom html-parser rust typescript wasm
Last synced: 26 days ago
JSON representation
Browser DOM & HTML parser in Deno
- Host: GitHub
- URL: https://github.com/b-fuze/deno-dom
- Owner: b-fuze
- License: mit
- Created: 2020-05-06T11:25:15.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-05-05T10:53:25.000Z (6 months ago)
- Last Synced: 2024-05-05T11:38:43.550Z (6 months ago)
- Topics: browser-dom, deno, dom, html-parser, rust, typescript, wasm
- Language: HTML
- Homepage: https://deno.land/x/deno_dom
- Size: 5.41 MB
- Stars: 384
- Watchers: 10
- Forks: 43
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Deno DOM
An implementation of the browser DOM—primarily for SSR—in Deno. Implemented with
Rust, WASM, and obviously, Deno/TypeScript.
## Example
```typescript
import { DOMParser, Element } from "jsr:@b-fuze/deno-dom";
// non-JSR wasm url import: https://deno.land/x/deno_dom/deno-dom-wasm.ts
// non-JSR native url import: https://deno.land/x/deno_dom/deno-dom-native.ts
const doc = new DOMParser().parseFromString(
`
Hello World!
Hello from Deno!
`,
"text/html",
);
const p = doc.querySelector("p")!;
console.log(p.textContent); // "Hello from Deno!"
console.log(p.childNodes[1].textContent); // "Deno!"
p.innerHTML = "DOM in Deno is pretty cool";
console.log(p.children[0].outerHTML); // "Deno"
```
Deno DOM has **two** backends, WASM and native using Deno native plugins. Both
APIs are **identical**, the difference being only in performance. The WASM
backend works with all Deno restrictions, but the native backend requires the
`--unstable-ffi --allow-ffi --allow-env --allow-read --allow-net=deno.land`
flags. A shorter version could be `--unstable-ffi -A`, but that allows all
permissions so you'd have to assess your risk and requirements. You can switch
between them by importing either `jsr:@b-fuze/deno-dom` for WASM or
`jsr:@b-fuze/deno-dom/native` for the native binary.
Deno DOM is still under development, but is fairly usable for basic HTML
manipulation needs.
### WebAssembly Startup Penalty
Deno suffers an initial startup penalty in Deno DOM WASM due to Top Level Await
(TLA) preparing the WASM parser. As an alternative to running the initiation on
startup, you can initialize Deno DOM's parser on-demand yourself when you need
it by importing from `jsr:@b-fuze/deno-dom/wasm-noinit`. Example:
```typescript
import { DOMParser, initParser } from "jsr:@b-fuze/deno-dom/wasm-noinit";
// ...and when you need Deno DOM make sure you initialize the parser...
await initParser();
// Then you can use Deno DOM as you would normally
const doc = new DOMParser().parseFromString(
`
Lorem ipsum dolor...
`,
"text/html",
);
```
## Documentation
Refer to MDN (Mozilla Developer Network) for documentation. If there are
inconsistencies (that aren't a result of legacy APIs) file an issue.
## Goals
- HTML parser in Deno
- Fast
- Mirror _most_ supported DOM APIs as closely as possible
- Provide specific APIs in addition to DOM APIs to make certain operations more
efficient, like controlling Shadow DOM
- Use cutting-edge JS features like private class members, optional chaining,
etc
## Non-Goals
- Headless browser implementation
- Ability to run JS embedded in documents (`` tags, `onload`, etc)
- Parse CSS or JS (they're just text, but this may be supported in the future
for CSSOM)
- Support older (or even not so old) JS engines. In other words, there will be
no support of transpilation to ES5, no support of polyfills, etc
- Support special functionality of obsolete HTML elements (`<marquee>`, etc)
## Running tests
To run tests (excluding WPT tests) use the following for WASM
```sh
deno test --allow-read --allow-net wasm.test.ts
```
Or the following for native (native requires more permissions)
```sh
deno test --unstable -A native.test.ts
```
To run WPT tests update the WPT submodule
```sh
git submodule update --progress --depth 1
```
Then append `-- --wpt` to the test command before running it, e.g. for WASM
```sh
deno test --allow-read --allow-net wasm.test.ts -- --wpt
```
WPT tests are still a WIP, passed tests likely haven't actually passed.
## Building Deno DOM Native
Deno DOM native is a faster backend for Deno DOM (check [benchmarks](./bench/)),
however, the WASM backend is sufficient for almost all use-cases.
**Note:** If you're running an x86\_64 system with either Windows, Linux, or
macOS, then you probably don't need to build the plugin. Deno DOM native
downloads a prebuilt binary in those cases.
To build Deno DOM's native backend,
[install Rust](https://www.rust-lang.org/learn/get-started) if you haven't
already, then run
```sh
cargo build --release
```
which produces a binary located at `target/release/libplugin.{so,dll,dylib}`
(extension depends on your system).
To use the new binary you need to set the **`DENO_DOM_PLUGIN`** env var to the
path of the binary produced in the previous step. **Don't forget** to run Deno
with `--allow-env`.
# Credits
- html5ever developers for the HTML parser
- nwsapi developers for the selector parser