domq-wasm 0.0.0-stage → 0.4.0

package/LICENSE_MIT

@@ -0,0 +1,25 @@
+Copyright (c) 2018 iamsaquib8 <saquibulhassan6@gmail.com>
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# domq for JavaScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Messy HTML in. Clean tree, text, Markdown, or JSON out.** A forgiving HTML
+parser with CSS selectors for JavaScript: browsers, Node, Deno, Bun and edge
+workers. It is the Rust crate [`domq`](https://github.com/iamsaquib8/domq)
+compiled to one **~41 KB (gzipped)** WebAssembly module, with zero JS
+dependencies.
+
+**[Try it in the playground](https://iamsaquib8.github.io/domq/)**: paste
+any HTML and query it live.
+
+```js
+import { select, toMarkdown } from "domq-wasm";
+
+const html = `<ul id=links><li><a href="/a">One</a><li><a href="/b">Two</a></ul>`;
+
+select(html, "#links a[href]").map((a) => a.attrs.href); // ["/a", "/b"]
+toMarkdown(html); // "- [One](/a)\n- [Two](/b)"
+```
+
+- **Never throws on bad HTML.** Unclosed tags, mis-nesting and stray end tags
+  are repaired, and `errors()` tells you where.
+- **Real CSS selectors.** Combinators, attribute operators, `:nth-child()`,
+  `:not()`, `:is()`, `:has()`, plus jQuery-style `:contains("text")`.
+- **Content out.** Readable text (no scripts or styles), CommonMark/GFM Markdown
+  for LLM prompts and RAG, a JSON-ready tree, or repaired HTML.
+- **Small.** One `.wasm` (~41 KB gzipped) plus ~4 KB of generated glue JS.
+
+It is not a spec-compliant WHATWG parser (no implicit `<html>`/`<body>`, no
+adoption agency) and not a sanitizer. Use DOMPurify for untrusted HTML that you
+render.
+
+## Install
+
+```sh
+npm install domq-wasm
+```
+
+## Use it
+
+The package ships one ES module build. How it loads the `.wasm` depends on the
+runtime:
+
+| Runtime | Setup | Status |
+|---|---|---|
+| Node.js 22+ (supported LTS lines) | nothing: `import { select } from "domq-wasm"` | tested in CI on the current LTS |
+| Browsers, bundlers (Vite, webpack 5, …) | `await init()` once | tested (the playground uses this build) |
+| Bun | nothing (uses the Node entry point) | expected to work, not tested |
+| Deno | nothing with `npm:domq-wasm` (Node entry point) | expected to work, not tested |
+| Cloudflare Workers | `initSync({ module })` with the imported `.wasm` | expected to work, not tested |
+
+### Node.js
+
+Import and call. The Node entry point loads the module synchronously at import
+time, so there is no `init()` to await (calling it anyway is harmless).
+
+```js
+import { select, toText } from "domq-wasm";
+
+const res = await fetch("https://news.ycombinator.com");
+const html = await res.text();
+for (const link of select(html, ".titleline > a")) {
+  console.log(link.text, link.attrs.href);
+}
+```
+
+From CommonJS, `require("domq-wasm")` works on Node versions that can
+`require()` ES modules (20.19+ and 22.12+). On older versions, use
+`const { select } = await import("domq-wasm")`.
+
+### Browsers and bundlers
+
+Call the default export once before anything else. It fetches
+`domq_wasm_bg.wasm` from next to the JS file, which bundlers such as Vite
+and webpack 5 handle as an asset.
+
+```js
+import init, { select, toMarkdown } from "domq-wasm";
+
+await init();
+const md = toMarkdown(document.documentElement.outerHTML, "article");
+```
+
+Without a bundler, import it from a CDN:
+
+```html
+<script type="module">
+  import init, { toText } from "https://cdn.jsdelivr.net/npm/domq@0.3/domq_wasm.js";
+  await init();
+  console.log(toText("<p>Hello <b>world</b>"));
+</script>
+```
+
+### Deno and Bun
+
+```js
+import { select } from "npm:domq-wasm@0.4"; // Deno; in Bun: "domq-wasm"
+```
+
+Both resolve the package's Node entry point, which reads the `.wasm` with
+`node:fs`. Deno may ask for read permission (`--allow-read`).
+
+### Cloudflare Workers
+
+Wrangler imports `.wasm` files as compiled `WebAssembly.Module`s; hand it to
+`initSync`:
+
+```js
+import { initSync, toMarkdown } from "domq-wasm";
+import wasm from "domq-wasm/domq_wasm_bg.wasm";
+
+initSync({ module: wasm });
+
+export default {
+  async fetch(request) {
+    const page = await fetch("https://blog.rust-lang.org");
+    return new Response(toMarkdown(await page.text(), "main"));
+  },
+};
+```
+
+## API
+
+Every function takes the HTML as a string. Functions that take a `selector`
+throw a `SelectorError` if it is invalid; nothing else throws.
+
+| Function | Returns |
+|---|---|
+| `parse(html)` | `DomDocument`: the tree as plain objects |
+| `parseJson(html)` | `string`: the same tree as JSON text |
+| `select(html, selector)` | `Match[]`: every matching element, in document order |
+| `selectFirst(html, selector)` | `Match \| undefined`: the first match |
+| `toText(html, selector?)` | `string`: readable text of the document, or of every match separated by a blank line |
+| `toMarkdown(html, selector?)` | `string`: Markdown of the document, or of every match separated by a blank line |
+| `toHtml(html)` | `string`: the repaired HTML (every element closed and properly nested) |
+| `errors(html)` | `ParseError[]`: what the parser had to repair, and where |
+| `init(input?)`, `initSync({ module })` | load the `.wasm` (browsers and Workers only; see above) |
+
+### Parse once, query many times
+
+Each function above parses the HTML again. To run several queries on one
+document, parse it once:
+
+```js
+import { Document } from "domq-wasm";
+
+const doc = new Document(html); // or Document.parse(html)
+const title = doc.selectFirst("h1")?.text;
+const prices = doc.select("tr:has(td.in-stock) .price").map((m) => m.text);
+const body = doc.toMarkdown("article");
+doc.free(); // release its wasm memory now instead of waiting for the GC
+```
+
+`Document` has the same operations as methods: `select(selector)`,
+`selectFirst(selector)`, `toText(selector?)`, `toMarkdown(selector?)`,
+`toHtml()`, `tree()`, `errors()` and `free()`. `toJSON()` returns the same as
+`tree()`, so `JSON.stringify(doc)` gives the JSON tree. Where explicit resource
+management is available, `using doc = new Document(html)` frees it
+automatically.
+
+If you also use the DOM's `Document` type in the same file, rename the import:
+`import { Document as HtmlDocument } from "domq-wasm"`.
+
+### Types
+
+The package includes TypeScript declarations; none of the API is typed `any`.
+
+```ts
+interface Match {
+  tag: string;                   // lower-cased tag name
+  attrs: Record<string, string>; // attributes; boolean attributes are ""
+  text: string;                  // readable text, as toText() gives it
+  html: string;                  // outer HTML, re-serialized
+  nodeIndex: number;             // position in a depth-first walk of tree()
+}
+
+interface DomDocument {
+  type: "document";
+  errors: number;                // how many repairs (0 = clean input)
+  children: DomNode[];
+}
+
+type DomNode =
+  | { type: "element"; tag: string; attrs: Record<string, string>; children: DomNode[] }
+  | { type: "text"; value: string }
+  | { type: "comment"; value: string }
+  | { type: "doctype"; value: string };
+
+interface ParseError {
+  position: number;              // index into the html string
+  message: string;               // e.g. "element implicitly closed"
+}
+
+interface SelectorError extends Error {
+  name: "SelectorError";
+  position: number;              // index into the selector string
+}
+```
+
+### Invalid selectors
+
+```js
+try {
+  select(html, "a:hover");
+} catch (e) {
+  e.name;     // "SelectorError"
+  e.message;  // "unsupported pseudo-class ':hover' at byte 1"
+  e.position; // 1
+}
+```
+
+Unsupported selectors are errors rather than silently matching nothing:
+pseudo-elements, `:hover` and other interactive states, namespaces, and
+`:has()` inside `:has()`. The full grammar is in the
+[`Selector` docs](https://docs.rs/domq/latest/domq/struct.Selector.html).
+
+## Size
+
+| File | Raw | Gzipped |
+|---|---:|---:|
+| `domq_wasm_bg.wasm` | ~88 KB | ~41 KB |
+| `domq_wasm.js` (glue) | ~22 KB | ~4 KB |
+
+The module contains the parser, the selector engine, and the text, Markdown,
+JSON and HTML serializers. CI fails if the gzipped `.wasm` grows past 45 KiB.
+
+## Upgrading from 0.1 or 0.2
+
+0.3 is a new API. `parse()` now returns objects, so drop the `JSON.parse`, or
+call `parseJson()` for the string. `parseErrorCount(html)` is now
+`errors(html).length`. `query(html, selector)` is now `select(html, selector)`,
+which returns `Match` objects instead of a JSON string of subtrees.
+
+## Building from source
+
+```sh
+rustup target add wasm32-unknown-unknown
+cargo install wasm-pack
+
+cd wasm
+wasm-pack build --target web --release   # -> pkg/
+node npm/finish.mjs                      # add the Node entry point + "exports"
+wasm-pack test --node                    # Rust-side tests of the bindings
+sh npm/smoke-test.sh                     # pack pkg/ and run tests/node.mjs against it
+```
+
+For the playground: `wasm-pack build --target web --release --no-pack --out-dir ../playground/pkg`,
+then serve `playground/` over HTTP (for example `python3 -m http.server -d ../playground`).
+
+## License
+
+MIT

package/domq_wasm.d.ts

@@ -0,0 +1,221 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/** An element in the parsed tree. */
+export interface DomElement {
+    type: "element";
+    /** Lower-cased tag name, e.g. `"div"`. */
+    tag: string;
+    /** Attributes (names lower-cased, values entity-decoded; boolean attributes are `""`). */
+    attrs: Record<string, string>;
+    children: DomNode[];
+}
+
+/** Any node in the parsed tree. Text is already entity-decoded. */
+export type DomNode =
+| DomElement
+| { type: "text"; value: string }
+| { type: "comment"; value: string }
+| { type: "doctype"; value: string };
+
+/** The parsed document, as returned by `parse()` and `Document#tree()`. */
+export interface DomDocument {
+    type: "document";
+    /** How many problems the parser recovered from (0 = clean input). See `errors()`. */
+    errors: number;
+    /** Top-level nodes, in document order. */
+    children: DomNode[];
+}
+
+/** An element matched by a CSS selector. */
+export interface Match {
+    /** Lower-cased tag name. */
+    tag: string;
+    /** The element's attributes. */
+    attrs: Record<string, string>;
+    /** Readable text of the element (what `toText` gives: no scripts, collapsed whitespace). */
+    text: string;
+    /** The element's outer HTML (re-serialized, so it is well-formed). */
+    html: string;
+    /**
+     * The element's position in a depth-first walk of the whole tree (0-based,
+     * counting text, comment and doctype nodes too) — the order in which
+     * `tree()` lists nodes. Use it to find a match in the tree.
+     */
+    nodeIndex: number;
+}
+
+/** A problem the parser recovered from. Parsing itself never fails. */
+export interface ParseError {
+    /** Index into the input string (a normal JS string index) where it happened. */
+    position: number;
+    /** Short description, e.g. `"element implicitly closed"`. */
+    message: string;
+}
+
+/**
+ * Thrown (as an `Error` with `name === "SelectorError"`) when a CSS selector is
+ * invalid or unsupported, e.g. `"a:hover"` or `"div >"`.
+ */
+export interface SelectorError extends Error {
+    name: "SelectorError";
+    /** Index into the selector string where the problem is. */
+    position: number;
+}
+
+
+
+/**
+ * A parsed HTML document. Parse once, then query it as often as you like.
+ *
+ * Free it with `free()` (or a `using` declaration) when you are done, or let
+ * the garbage collector do it.
+ */
+export class Document {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * The problems the parser recovered from (empty for clean input).
+     */
+    errors(): ParseError[];
+    /**
+     * Parse `html` (a full page or a fragment). Never throws: broken markup is
+     * repaired and the repairs are listed by `errors()`.
+     */
+    constructor(html: string);
+    /**
+     * Same as `new Document(html)`.
+     */
+    static parse(html: string): Document;
+    /**
+     * The first element matching a CSS `selector`, or `undefined`. Throws a
+     * `SelectorError` if the selector is invalid.
+     */
+    selectFirst(selector: string): Match | undefined;
+    /**
+     * Every element matching a CSS `selector`, in document order. Throws a
+     * `SelectorError` if the selector is invalid.
+     */
+    select(selector: string): Match[];
+    /**
+     * The document re-serialized as HTML: every tag closed and nested
+     * properly, attributes quoted, text escaped.
+     */
+    toHtml(): string;
+    /**
+     * Same as `tree()`, so `JSON.stringify(doc)` gives the JSON tree.
+     */
+    toJSON(): DomDocument;
+    /**
+     * Markdown (CommonMark + GFM tables): headings, lists, links, images,
+     * code blocks, tables, quotes. With a `selector`, every match converted
+     * and separated by a blank line.
+     */
+    toMarkdown(selector?: string | null): string;
+    /**
+     * Readable plain text: no `<script>`/`<style>`/`<head>`, whitespace
+     * collapsed, a line per block, a blank line between paragraphs. With a
+     * `selector`, the text of every match, separated by a blank line.
+     */
+    toText(selector?: string | null): string;
+    /**
+     * The whole tree as plain JS objects.
+     */
+    tree(): DomDocument;
+}
+
+/**
+ * The problems the parser recovered from while parsing `html`.
+ */
+export function errors(html: string): ParseError[];
+
+/**
+ * Parse `html` into a tree of plain JS objects (see `DomDocument`).
+ */
+export function parse(html: string): DomDocument;
+
+/**
+ * Parse `html` and return the tree as a JSON string (the same shape as
+ * `parse()`), e.g. to send it over the network without re-encoding.
+ */
+export function parseJson(html: string): string;
+
+/**
+ * Every element of `html` matching a CSS `selector`. Throws a
+ * `SelectorError` if the selector is invalid.
+ */
+export function select(html: string, selector: string): Match[];
+
+/**
+ * The first element of `html` matching a CSS `selector`, or `undefined`.
+ * Throws a `SelectorError` if the selector is invalid.
+ */
+export function selectFirst(html: string, selector: string): Match | undefined;
+
+/**
+ * `html` parsed and re-serialized: the repaired, well-formed version.
+ */
+export function toHtml(html: string): string;
+
+/**
+ * `html` as Markdown — or, with a `selector`, every match converted and
+ * separated by a blank line.
+ */
+export function toMarkdown(html: string, selector?: string | null): string;
+
+/**
+ * `html` as readable plain text — or, with a `selector`, the text of every
+ * match separated by a blank line.
+ */
+export function toText(html: string, selector?: string | null): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_document_free: (a: number, b: number) => void;
+    readonly document_errors: (a: number) => number;
+    readonly document_new: (a: number, b: number) => number;
+    readonly document_parse: (a: number, b: number) => number;
+    readonly document_select: (a: number, b: number, c: number, d: number) => void;
+    readonly document_selectFirst: (a: number, b: number, c: number, d: number) => void;
+    readonly document_toHtml: (a: number, b: number) => void;
+    readonly document_toJSON: (a: number) => number;
+    readonly document_toMarkdown: (a: number, b: number, c: number, d: number) => void;
+    readonly document_toText: (a: number, b: number, c: number, d: number) => void;
+    readonly document_tree: (a: number) => number;
+    readonly errors: (a: number, b: number) => number;
+    readonly parse: (a: number, b: number) => number;
+    readonly parseJson: (a: number, b: number, c: number) => void;
+    readonly select: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly selectFirst: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly toHtml: (a: number, b: number, c: number) => void;
+    readonly toMarkdown: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly toText: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;

package/domq_wasm.js

@@ -0,0 +1,652 @@
+/* @ts-self-types="./domq_wasm.d.ts" */
+
+/**
+ * A parsed HTML document. Parse once, then query it as often as you like.
+ *
+ * Free it with `free()` (or a `using` declaration) when you are done, or let
+ * the garbage collector do it.
+ */
+export class Document {
+    static __wrap(ptr) {
+        const obj = Object.create(Document.prototype);
+        obj.__wbg_ptr = ptr;
+        DocumentFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        DocumentFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_document_free(ptr, 0);
+    }
+    /**
+     * The problems the parser recovered from (empty for clean input).
+     * @returns {ParseError[]}
+     */
+    errors() {
+        const ret = wasm.document_errors(this.__wbg_ptr);
+        return takeObject(ret);
+    }
+    /**
+     * Parse `html` (a full page or a fragment). Never throws: broken markup is
+     * repaired and the repairs are listed by `errors()`.
+     * @param {string} html
+     */
+    constructor(html) {
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.document_new(ptr0, len0);
+        this.__wbg_ptr = ret;
+        DocumentFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+    /**
+     * Same as `new Document(html)`.
+     * @param {string} html
+     * @returns {Document}
+     */
+    static parse(html) {
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.document_parse(ptr0, len0);
+        return Document.__wrap(ret);
+    }
+    /**
+     * The first element matching a CSS `selector`, or `undefined`. Throws a
+     * `SelectorError` if the selector is invalid.
+     * @param {string} selector
+     * @returns {Match | undefined}
+     */
+    selectFirst(selector) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(selector, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_selectFirst(retptr, this.__wbg_ptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Every element matching a CSS `selector`, in document order. Throws a
+     * `SelectorError` if the selector is invalid.
+     * @param {string} selector
+     * @returns {Match[]}
+     */
+    select(selector) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(selector, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.document_select(retptr, this.__wbg_ptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * The document re-serialized as HTML: every tag closed and nested
+     * properly, attributes quoted, text escaped.
+     * @returns {string}
+     */
+    toHtml() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.document_toHtml(retptr, this.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            deferred1_0 = r0;
+            deferred1_1 = r1;
+            return getStringFromWasm0(r0, r1);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export3(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Same as `tree()`, so `JSON.stringify(doc)` gives the JSON tree.
+     * @returns {DomDocument}
+     */
+    toJSON() {
+        const ret = wasm.document_toJSON(this.__wbg_ptr);
+        return takeObject(ret);
+    }
+    /**
+     * Markdown (CommonMark + GFM tables): headings, lists, links, images,
+     * code blocks, tables, quotes. With a `selector`, every match converted
+     * and separated by a blank line.
+     * @param {string | null} [selector]
+     * @returns {string}
+     */
+    toMarkdown(selector) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            var ptr0 = isLikeNone(selector) ? 0 : passStringToWasm0(selector, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len0 = WASM_VECTOR_LEN;
+            wasm.document_toMarkdown(retptr, this.__wbg_ptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr2 = r0;
+            var len2 = r1;
+            if (r3) {
+                ptr2 = 0; len2 = 0;
+                throw takeObject(r2);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export3(deferred3_0, deferred3_1, 1);
+        }
+    }
+    /**
+     * Readable plain text: no `<script>`/`<style>`/`<head>`, whitespace
+     * collapsed, a line per block, a blank line between paragraphs. With a
+     * `selector`, the text of every match, separated by a blank line.
+     * @param {string | null} [selector]
+     * @returns {string}
+     */
+    toText(selector) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            var ptr0 = isLikeNone(selector) ? 0 : passStringToWasm0(selector, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            var len0 = WASM_VECTOR_LEN;
+            wasm.document_toText(retptr, this.__wbg_ptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+            var ptr2 = r0;
+            var len2 = r1;
+            if (r3) {
+                ptr2 = 0; len2 = 0;
+                throw takeObject(r2);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+            wasm.__wbindgen_export3(deferred3_0, deferred3_1, 1);
+        }
+    }
+    /**
+     * The whole tree as plain JS objects.
+     * @returns {DomDocument}
+     */
+    tree() {
+        const ret = wasm.document_tree(this.__wbg_ptr);
+        return takeObject(ret);
+    }
+}
+if (Symbol.dispose) Document.prototype[Symbol.dispose] = Document.prototype.free;
+
+/**
+ * The problems the parser recovered from while parsing `html`.
+ * @param {string} html
+ * @returns {ParseError[]}
+ */
+export function errors(html) {
+    const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.errors(ptr0, len0);
+    return takeObject(ret);
+}
+
+/**
+ * Parse `html` into a tree of plain JS objects (see `DomDocument`).
+ * @param {string} html
+ * @returns {DomDocument}
+ */
+export function parse(html) {
+    const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.parse(ptr0, len0);
+    return takeObject(ret);
+}
+
+/**
+ * Parse `html` and return the tree as a JSON string (the same shape as
+ * `parse()`), e.g. to send it over the network without re-encoding.
+ * @param {string} html
+ * @returns {string}
+ */
+export function parseJson(html) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.parseJson(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred2_0 = r0;
+        deferred2_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * Every element of `html` matching a CSS `selector`. Throws a
+ * `SelectorError` if the selector is invalid.
+ * @param {string} html
+ * @param {string} selector
+ * @returns {Match[]}
+ */
+export function select(html, selector) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(selector, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.select(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
+/**
+ * The first element of `html` matching a CSS `selector`, or `undefined`.
+ * Throws a `SelectorError` if the selector is invalid.
+ * @param {string} html
+ * @param {string} selector
+ * @returns {Match | undefined}
+ */
+export function selectFirst(html, selector) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(selector, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.selectFirst(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return takeObject(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
+/**
+ * `html` parsed and re-serialized: the repaired, well-formed version.
+ * @param {string} html
+ * @returns {string}
+ */
+export function toHtml(html) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.toHtml(retptr, ptr0, len0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        deferred2_0 = r0;
+        deferred2_1 = r1;
+        return getStringFromWasm0(r0, r1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * `html` as Markdown — or, with a `selector`, every match converted and
+ * separated by a blank line.
+ * @param {string} html
+ * @param {string | null} [selector]
+ * @returns {string}
+ */
+export function toMarkdown(html, selector) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        var ptr1 = isLikeNone(selector) ? 0 : passStringToWasm0(selector, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        var len1 = WASM_VECTOR_LEN;
+        wasm.toMarkdown(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr3 = r0;
+        var len3 = r1;
+        if (r3) {
+            ptr3 = 0; len3 = 0;
+            throw takeObject(r2);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred4_0, deferred4_1, 1);
+    }
+}
+
+/**
+ * `html` as readable plain text — or, with a `selector`, the text of every
+ * match separated by a blank line.
+ * @param {string} html
+ * @param {string | null} [selector]
+ * @returns {string}
+ */
+export function toText(html, selector) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        var ptr1 = isLikeNone(selector) ? 0 : passStringToWasm0(selector, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        var len1 = WASM_VECTOR_LEN;
+        wasm.toText(retptr, ptr0, len0, ptr1, len1);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr3 = r0;
+        var len3 = r1;
+        if (r3) {
+            ptr3 = 0; len3 = 0;
+            throw takeObject(r2);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export3(deferred4_0, deferred4_1, 1);
+    }
+}
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbg___wbindgen_throw_41e9ee4f547fc59a: function(arg0, arg1) {
+            throw new Error(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_new_debb421d9db3ecaf: function(arg0, arg1) {
+            const ret = new Error(getStringFromWasm0(arg0, arg1));
+            return addHeapObject(ret);
+        },
+        __wbg_parse_727b9ce5f066bfca: function(arg0, arg1) {
+            const ret = JSON.parse(getStringFromWasm0(arg0, arg1));
+            return addHeapObject(ret);
+        },
+        __wbg_set_name_85a0a4c54f07ab5c: function(arg0, arg1, arg2) {
+            getObject(arg0).name = getStringFromWasm0(arg1, arg2);
+        },
+        __wbg_set_position_f011541ab3447656: function(arg0, arg1) {
+            getObject(arg0).position = arg1 >>> 0;
+        },
+    };
+    return {
+        __proto__: null,
+        "./domq_wasm_bg.js": import0,
+    };
+}
+
+const DocumentFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_document_free(ptr, 1));
+
+function addHeapObject(obj) {
+    if (heap_next === heap.length) heap.push(heap.length + 1);
+    const idx = heap_next;
+    heap_next = heap[idx];
+
+    heap[idx] = obj;
+    return idx;
+}
+
+function dropObject(idx) {
+    if (idx < 1028) return;
+    heap[idx] = heap_next;
+    heap_next = idx;
+}
+
+let cachedDataViewMemory0 = null;
+function getDataViewMemory0() {
+    if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {
+        cachedDataViewMemory0 = new DataView(wasm.memory.buffer);
+    }
+    return cachedDataViewMemory0;
+}
+
+function getStringFromWasm0(ptr, len) {
+    return decodeText(ptr >>> 0, len);
+}
+
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+
+function getObject(idx) { return heap[idx]; }
+
+let heap = new Array(1024).fill(undefined);
+heap.push(undefined, null, true, false);
+
+let heap_next = heap.length;
+
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+
+function takeObject(idx) {
+    const ret = getObject(idx);
+    dropObject(idx);
+    return ret;
+}
+
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+const MAX_SAFARI_DECODE_BYTES = 2146435072;
+let numBytesDecoded = 0;
+function decodeText(ptr, len) {
+    numBytesDecoded += len;
+    if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+        cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+        cachedTextDecoder.decode();
+        numBytesDecoded = len;
+    }
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+const cachedTextEncoder = new TextEncoder();
+
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+
+let WASM_VECTOR_LEN = 0;
+
+let wasmModule, wasmInstance, wasm;
+function __wbg_finalize_init(instance, module) {
+    wasmInstance = instance;
+    wasm = instance.exports;
+    wasmModule = module;
+    cachedDataViewMemory0 = null;
+    cachedUint8ArrayMemory0 = null;
+    return wasm;
+}
+
+async function __wbg_load(module, imports) {
+    if (typeof Response === 'function' && module instanceof Response) {
+        if (!module.ok) {
+            throw new Error(`failed to fetch Wasm: ${module.status} ${module.statusText} fetching '${module.url}'`);
+        }
+
+        if (typeof WebAssembly.instantiateStreaming === 'function') {
+            try {
+                return await WebAssembly.instantiateStreaming(module, imports);
+            } catch (e) {
+                const validResponse = expectedResponseType(module.type);
+
+                if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
+                    console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+
+                } else { throw e; }
+            }
+        }
+
+        const bytes = await module.arrayBuffer();
+        return await WebAssembly.instantiate(bytes, imports);
+    } else {
+        const instance = await WebAssembly.instantiate(module, imports);
+
+        if (instance instanceof WebAssembly.Instance) {
+            return { instance, module };
+        } else {
+            return instance;
+        }
+    }
+
+    function expectedResponseType(type) {
+        switch (type) {
+            case 'basic': case 'cors': case 'default': return true;
+        }
+        return false;
+    }
+}
+
+function initSync(module) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module !== undefined) {
+        if (Object.getPrototypeOf(module) === Object.prototype) {
+            ({module} = module)
+        } else {
+            console.warn('using deprecated parameters for `initSync()`; pass a single object instead')
+        }
+    }
+
+    const imports = __wbg_get_imports();
+    if (!(module instanceof WebAssembly.Module)) {
+        module = new WebAssembly.Module(module);
+    }
+    const instance = new WebAssembly.Instance(module, imports);
+    return __wbg_finalize_init(instance, module);
+}
+
+async function __wbg_init(module_or_path) {
+    if (wasm !== undefined) return wasm;
+
+
+    if (module_or_path !== undefined) {
+        if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+            ({module_or_path} = module_or_path)
+        } else {
+            console.warn('using deprecated parameters for the initialization function; pass a single object instead')
+        }
+    }
+
+    if (module_or_path === undefined) {
+        module_or_path = new URL('domq_wasm_bg.wasm', import.meta.url);
+    }
+    const imports = __wbg_get_imports();
+
+    if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) {
+        module_or_path = fetch(module_or_path);
+    }
+
+    const { instance, module } = await __wbg_load(await module_or_path, imports);
+
+    return __wbg_finalize_init(instance, module);
+}
+
+export { initSync, __wbg_init as default };

package/node.js

@@ -0,0 +1,13 @@
+// Node.js entry point of the `domq` npm package (selected through the
+// "node" export condition; Bun picks it too).
+//
+// It loads the .wasm from disk synchronously, so the API is ready as soon as
+// the import resolves: no `await init()` needed. Calling `init()` anyway (as
+// code shared with the browser does) is harmless: it returns immediately.
+import { readFileSync } from "node:fs";
+import init, { initSync } from "./domq_wasm.js";
+
+initSync({ module: readFileSync(new URL("./domq_wasm_bg.wasm", import.meta.url)) });
+
+export * from "./domq_wasm.js";
+export default init;

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "domq-wasm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "collaborators": [
+    "iamsaquib8 <saquibulhassan6@gmail.com>"
+  ],
+  "description": "Tiny, forgiving HTML parser for JavaScript (WebAssembly): CSS selectors, readable text, Markdown and JSON from messy HTML. Zero JS dependencies.",
+  "version": "0.4.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iamsaquib8/domq.git"
+  },
+  "files": [
+    "domq_wasm_bg.wasm",
+    "domq_wasm.js",
+    "domq_wasm.d.ts",
+    "LICENSE_MIT",
+    "node.js"
+  ],
+  "main": "domq_wasm.js",
+  "homepage": "https://iamsaquib8.github.io/domq/",
+  "types": "domq_wasm.d.ts",
+  "exports": {
+    ".": {
+      "types": "./domq_wasm.d.ts",
+      "node": "./node.js",
+      "default": "./domq_wasm.js"
+    },
+    "./domq_wasm.js": {
+      "types": "./domq_wasm.d.ts",
+      "default": "./domq_wasm.js"
+    },
+    "./domq_wasm_bg.wasm": "./domq_wasm_bg.wasm",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "./snippets/*",
+    "./node.js"
+  ],
+  "keywords": [
+    "html",
+    "parser",
+    "css-selector",
+    "markdown",
+    "wasm",
+    "scraper",
+    "html-to-markdown",
+    "html-to-text",
+    "dom",
+    "cloudflare-workers"
+  ]
+}