wasm-quickjs-dom 0.0.0-stage → 0.0.3

package/dist/limits.js

@@ -0,0 +1,114 @@
+const MAX_REDIRECTS = 10;
+/** True for localhost and private, loopback and link-local addresses (`host` as `URL.hostname` gives it). */
+export function isPrivateHost(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+    if (h === "localhost" || h.endsWith(".localhost") || h.endsWith(".local") || h.endsWith(".internal"))
+        return true;
+    const v4 = /^(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(h);
+    if (v4) {
+        const a = Number(v4[1]);
+        const b = Number(v4[2]);
+        return a === 0 || a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127) || a >= 224;
+    }
+    if (h.includes(":")) {
+        if (h === "::" || h === "::1" || /^f[cd]/.test(h) || /^fe[89ab]/.test(h))
+            return true;
+        const dotted = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(h);
+        if (dotted)
+            return isPrivateHost(dotted[1]);
+        // `new URL` writes an IPv4-mapped address in hex: ::ffff:7f00:1
+        const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(h);
+        if (hex) {
+            const n = (parseInt(hex[1], 16) << 16) | parseInt(hex[2], 16);
+            return isPrivateHost([n >>> 24, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join("."));
+        }
+    }
+    return false;
+}
+/** `fetch` and body reading that obey {@link FetchLimits}. With no limits they are plain `fetch` and `arrayBuffer`. */
+export function createGuard(limits = {}) {
+    const restricted = !!(limits.allowedProtocols || limits.allowedHosts || limits.blockedHosts || limits.blockPrivateHosts);
+    let requests = 0;
+    let total = 0;
+    const check = (url) => {
+        const deny = (why) => {
+            throw new Error(`Blocked by the fetch limits (${why}): ${url.href}`);
+        };
+        if (limits.allowedProtocols && !limits.allowedProtocols.includes(url.protocol))
+            deny(`protocol ${url.protocol}`);
+        const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+        if (limits.allowedHosts && !limits.allowedHosts.includes(host))
+            deny("host not allowed");
+        if (limits.blockedHosts && limits.blockedHosts.includes(host))
+            deny("host blocked");
+        if (limits.blockPrivateHosts && isPrivateHost(host))
+            deny("private host");
+    };
+    return {
+        /** Fetch `input`; with host or protocol limits every redirect is checked before it is followed. */
+        async fetch(input, init = {}) {
+            if (limits.maxResourceCount !== undefined && ++requests > limits.maxResourceCount) {
+                throw new Error(`Blocked by the fetch limits (more than ${limits.maxResourceCount} requests): ${String(input)}`);
+            }
+            let url = new URL(input);
+            let method = init.method;
+            for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+                check(url);
+                if (!restricted)
+                    return fetch(url, init);
+                const res = await fetch(url, { ...init, method, redirect: "manual" });
+                if (res.type === "opaqueredirect")
+                    throw new Error(`Blocked by the fetch limits (this runtime hides the redirect target, so it cannot be checked): ${url.href}`);
+                if (res.status >= 300 && res.status < 400 && res.headers.has("location")) {
+                    await res.body?.cancel();
+                    url = new URL(res.headers.get("location"), url);
+                    if (res.status === 303 || ((res.status === 301 || res.status === 302) && method === "POST"))
+                        method = "GET";
+                    continue;
+                }
+                return res;
+            }
+            throw new Error(`Blocked by the fetch limits (more than ${MAX_REDIRECTS} redirects): ${String(input)}`);
+        },
+        /** The body of `res`, refused when it is over the size limits. */
+        async bytes(res) {
+            const max = limits.maxResourceBytes;
+            const tooBig = () => new Error(`Blocked by the fetch limits (a response is over ${max} bytes): ${res.url}`);
+            if (max !== undefined && Number(res.headers.get("content-length")) > max) {
+                await res.body?.cancel();
+                throw tooBig();
+            }
+            let bytes;
+            if (max !== undefined && res.body) {
+                const reader = res.body.getReader();
+                const chunks = [];
+                let size = 0;
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.length;
+                    if (size > max) {
+                        await reader.cancel();
+                        throw tooBig();
+                    }
+                    chunks.push(value);
+                }
+                bytes = new Uint8Array(size);
+                let at = 0;
+                for (const c of chunks) {
+                    bytes.set(c, at);
+                    at += c.length;
+                }
+            }
+            else {
+                bytes = new Uint8Array(await res.arrayBuffer());
+            }
+            total += bytes.length;
+            if (limits.maxTotalResourceBytes !== undefined && total > limits.maxTotalResourceBytes) {
+                throw new Error(`Blocked by the fetch limits (responses together are over ${limits.maxTotalResourceBytes} bytes): ${res.url}`);
+            }
+            return bytes;
+        },
+    };
+}

package/dist/quickjs-edge-light.d.ts

@@ -0,0 +1 @@
+export default function defaultQuickJSWasm(): Promise<WebAssembly.Module | undefined>;

package/dist/quickjs-edge-light.js

@@ -0,0 +1,9 @@
+/**
+ * `#quickjs-wasm` on Vercel Edge and the Next.js Edge runtime (the `edge-light` condition of `imports` in package.json):
+ * their bundlers turn `import x from "….wasm?module"` into a pre-compiled `WebAssembly.Module`, since the runtime
+ * cannot compile WebAssembly from bytes it fetches.
+ */
+import quickjsWasm from "../dist/quickjs.wasm?module";
+export default function defaultQuickJSWasm() {
+    return Promise.resolve(quickjsWasm);
+}

package/dist/quickjs-node.d.ts

@@ -0,0 +1 @@
+export default function defaultQuickJSWasm(): Promise<WebAssembly.Module | undefined>;

package/dist/quickjs-node.js

@@ -0,0 +1,20 @@
+/**
+ * `#quickjs-wasm` on Node.js and Bun (the `node` condition of `imports` in package.json): the package's own
+ * `quickjs.wasm`, read from beside this file and compiled once. `undefined` when it cannot be read (the library
+ * then loads its own copy on every run).
+ */
+let compiled;
+export default function defaultQuickJSWasm() {
+    compiled ??= (async () => {
+        try {
+            const fs = "node:fs/promises", url = "node:url"; // not literals: a bundler must not try to resolve them
+            const file = (await import(/* @vite-ignore */ url)).fileURLToPath(new URL("./quickjs.wasm", import.meta.url));
+            const bytes = await (await import(/* @vite-ignore */ fs)).readFile(file);
+            return await WebAssembly.compile(bytes);
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    return compiled;
+}

package/dist/quickjs-wasm.d.ts

@@ -0,0 +1,2 @@
+declare const quickjsWasm: WebAssembly.Module;
+export default quickjsWasm;

package/dist/quickjs-web.d.ts

@@ -0,0 +1 @@
+export default function defaultQuickJSWasm(): Promise<WebAssembly.Module | undefined>;

package/dist/quickjs-web.js

@@ -0,0 +1,23 @@
+/**
+ * `#quickjs-wasm` for Deno, browsers, Vercel Edge and anything else (the default of `imports` in package.json):
+ * `quickjs.wasm` is fetched from beside this file and compiled once. `undefined` when that fails (the library then
+ * loads its own copy on every run).
+ */
+let compiled;
+export default function defaultQuickJSWasm() {
+    compiled ??= (async () => {
+        try {
+            const url = new URL("./quickjs.wasm", import.meta.url);
+            if (url.protocol === "file:") {
+                const read = globalThis.Deno?.readFile;
+                if (read)
+                    return await WebAssembly.compile((await read(url)));
+            }
+            return await WebAssembly.compile(await (await fetch(url)).arrayBuffer());
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    return compiled;
+}

package/dist/quickjs-workerd.d.ts

@@ -0,0 +1 @@
+export default function defaultQuickJSWasm(): Promise<WebAssembly.Module | undefined>;

package/dist/quickjs-workerd.js

@@ -0,0 +1,8 @@
+/**
+ * `#quickjs-wasm` on Cloudflare Workers (the `workerd` condition of `imports` in package.json): the wasm is imported
+ * as a pre-compiled `WebAssembly.Module`, because workerd cannot compile WebAssembly at run time.
+ */
+import quickjsWasm from "../dist/quickjs.wasm";
+export default function defaultQuickJSWasm() {
+    return Promise.resolve(quickjsWasm);
+}

package/dist/runtime.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The host side of csrc/qjsdom.c: one QuickJS runtime in one instance of `quickjs.wasm`.
+ *
+ * Plain WebAssembly (`new WebAssembly.Instance(module, imports)`), no Emscripten glue, so it works wherever a compiled
+ * module can be instantiated: Cloudflare Workers, Vercel Edge, Deno, Bun, Node.js, browsers. Every page gets an
+ * instance of its own; dropping the instance frees everything.
+ */
+/** What the page's shims call out to (`__host` in the guest). */
+export interface QuickJSHost {
+    log(level: string, message: string): void;
+    timer(id: number, ms: number): void;
+    /** A promise was rejected and nothing handled it. */
+    rejection(message: string): void;
+    /** The page called `__host.fetch(target, method)`; answer later with {@link QuickJSInstance.settle}. */
+    fetch(id: number, target: string, method: string): void;
+    /**
+     * Module requests. kind 0: the specifier of `name` as imported from `base`. kind 1: the source of module `name`
+     * (`base` is the name). `undefined` when there is none.
+     */
+    module(kind: 0 | 1, base: string, name: string): string | undefined;
+}
+/** What an evaluation produced: its type decides how `value` reads. */
+export type EvalResult = {
+    type: "undefined";
+} | {
+    type: "string";
+    value: string;
+} | {
+    type: "json";
+    value: string;
+} | {
+    type: "error";
+    value: string;
+};
+export declare class QuickJSInstance {
+    private readonly x;
+    private constructor();
+    /**
+     * Instantiate `wasm` and start a runtime in it. `memoryLimit` is what QuickJS may allocate, `stackLimit` what a script
+     * may recurse into (bytes).
+     *
+     * With `warm` (the same function every time for a module), the instance is started by it once; its memory is then
+     * kept, and every later instance is that memory copied into a fresh instance. `warm` must leave nothing of a page
+     * behind: no host callbacks pending, nothing that depends on when it ran.
+     */
+    static create(wasm: WebAssembly.Module, host: QuickJSHost, memoryLimit: number, stackLimit: number, warm?: (instance: QuickJSInstance) => void): QuickJSInstance;
+    /** Put a string in wasm memory, NUL-terminated; `use` gets its pointer and byte length. */
+    private withString;
+    private result;
+    /** Script running past this wall-clock time (ms since the epoch) is interrupted; 0 = no limit. */
+    setDeadline(ms: number): void;
+    /** Evaluate code (as a module when asked); a script error comes back as `{ type: "error" }`. */
+    eval(code: string, name: string, module?: boolean): EvalResult;
+    /** Run bytecode that {@link QuickJSInstance.compile} made with this very build of QuickJS. */
+    evalBytecode(bytes: Uint8Array): EvalResult;
+    /** Compile code to bytecode (build time). */
+    compile(code: string, name: string): Uint8Array;
+    /** Run the queued promise jobs. */
+    jobs(): number;
+    /** Resolve (or reject) the promise of fetch `id` with a string. */
+    settle(id: number, ok: boolean, text: string): void;
+}

package/dist/runtime.js

@@ -0,0 +1,174 @@
+/**
+ * The host side of csrc/qjsdom.c: one QuickJS runtime in one instance of `quickjs.wasm`.
+ *
+ * Plain WebAssembly (`new WebAssembly.Instance(module, imports)`), no Emscripten glue, so it works wherever a compiled
+ * module can be instantiated: Cloudflare Workers, Vercel Edge, Deno, Bun, Node.js, browsers. Every page gets an
+ * instance of its own; dropping the instance frees everything.
+ */
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+// What a started instance looks like in memory, per compiled module, so the next one is a copy instead of a start
+// (see QuickJSInstance.create): starting the guest program costs more than copying a few megabytes.
+const snapshots = new WeakMap();
+function takeSnapshot(memory) {
+    const words = new Uint32Array(memory.buffer);
+    let end = words.length;
+    while (end > 0 && words[end - 1] === 0)
+        end--; // the rest is still zero in a new instance
+    return new Uint8Array(memory.buffer.slice(0, end * 4));
+}
+const RESULT_TYPES = ["undefined", "string", "json", "error"];
+export class QuickJSInstance {
+    x;
+    constructor(x) {
+        this.x = x;
+    }
+    /**
+     * Instantiate `wasm` and start a runtime in it. `memoryLimit` is what QuickJS may allocate, `stackLimit` what a script
+     * may recurse into (bytes).
+     *
+     * With `warm` (the same function every time for a module), the instance is started by it once; its memory is then
+     * kept, and every later instance is that memory copied into a fresh instance. `warm` must leave nothing of a page
+     * behind: no host callbacks pending, nothing that depends on when it ran.
+     */
+    static create(wasm, host, memoryLimit, stackLimit, warm) {
+        let x;
+        const u8 = () => new Uint8Array(x.memory.buffer);
+        const text = (ptr, len) => decoder.decode(u8().subarray(ptr, ptr + len));
+        const imports = {
+            host: {
+                call(op, n1, n2, a, alen, b, blen) {
+                    if (op === 0)
+                        host.log(text(a, alen), text(b, blen));
+                    else if (op === 1)
+                        host.timer(n1, n2);
+                    else if (op === 2)
+                        host.fetch(n1, text(a, alen), text(b, blen));
+                    else if (op === 3)
+                        host.rejection(text(a, alen));
+                },
+                module(kind, a, alen, b, blen) {
+                    const out = host.module(kind, text(a, alen), text(b, blen));
+                    if (out === undefined)
+                        return -1;
+                    const bytes = encoder.encode(out);
+                    const ptr = x.qd_scratch(bytes.length);
+                    u8().set(bytes, ptr);
+                    return bytes.length;
+                },
+            },
+            wasi_snapshot_preview1: {
+                // the C library asks for a clock, an empty environment and a way to write that goes nowhere
+                clock_time_get(_id, _precision, out) {
+                    new DataView(x.memory.buffer).setBigUint64(out, BigInt(Date.now()) * 1000000n, true);
+                    return 0;
+                },
+                environ_sizes_get(count, size) {
+                    const view = new DataView(x.memory.buffer);
+                    view.setUint32(count, 0, true);
+                    view.setUint32(size, 0, true);
+                    return 0;
+                },
+                environ_get: () => 0,
+                fd_close: () => 0,
+                fd_write(_fd, iovs, iovsLen, written) {
+                    const view = new DataView(x.memory.buffer);
+                    let total = 0;
+                    for (let i = 0; i < iovsLen; i++)
+                        total += view.getUint32(iovs + i * 8 + 4, true);
+                    view.setUint32(written, total, true);
+                    return 0;
+                },
+                proc_exit(code) {
+                    throw new Error(`QuickJS exited (${code})`);
+                },
+            },
+            env: { emscripten_notify_memory_growth: () => { } },
+        };
+        // another Emscripten version may ask for more of the C library's system calls than these: say "not implemented"
+        for (const i of WebAssembly.Module.imports(wasm)) {
+            if (i.module === "wasi_snapshot_preview1" && !(i.name in imports.wasi_snapshot_preview1))
+                imports.wasi_snapshot_preview1[i.name] = () => 52;
+        }
+        const wanted = WebAssembly.Module.imports(wasm).filter((i) => !(i.name in (imports[i.module] ?? {})));
+        if (wanted.length)
+            throw new Error(`quickjs.wasm needs imports this runtime does not provide: ${wanted.map((i) => `${i.module}.${i.name}`).join(", ")}`);
+        x = new WebAssembly.Instance(wasm, imports).exports;
+        const key = `${memoryLimit}:${stackLimit}`;
+        const saved = warm ? snapshots.get(wasm) : undefined;
+        if (saved && saved.key === key) {
+            const pages = Math.ceil(saved.bytes.length / 65536);
+            const have = x.memory.buffer.byteLength / 65536;
+            if (pages > have)
+                x.memory.grow(pages - have);
+            new Uint8Array(x.memory.buffer).set(saved.bytes);
+            return new QuickJSInstance(x);
+        }
+        x._initialize?.();
+        if (x.qd_init(memoryLimit, stackLimit) !== 0)
+            throw new Error("The QuickJS runtime could not be created.");
+        const instance = new QuickJSInstance(x);
+        if (warm) {
+            warm(instance);
+            snapshots.set(wasm, { key, bytes: takeSnapshot(x.memory) });
+        }
+        return instance;
+    }
+    /** Put a string in wasm memory, NUL-terminated; `use` gets its pointer and byte length. */
+    withString(s, use) {
+        const bytes = encoder.encode(s);
+        const ptr = this.x.qd_alloc(bytes.length + 1);
+        const view = new Uint8Array(this.x.memory.buffer);
+        view.set(bytes, ptr);
+        view[ptr + bytes.length] = 0;
+        try {
+            return use(ptr, bytes.length);
+        }
+        finally {
+            this.x.qd_free(ptr);
+        }
+    }
+    result() {
+        const type = RESULT_TYPES[this.x.qd_result_type()] ?? "undefined";
+        if (type === "undefined")
+            return { type };
+        const ptr = this.x.qd_result_ptr();
+        return { type, value: decoder.decode(new Uint8Array(this.x.memory.buffer, ptr, this.x.qd_result_len())) };
+    }
+    /** Script running past this wall-clock time (ms since the epoch) is interrupted; 0 = no limit. */
+    setDeadline(ms) {
+        this.x.qd_set_deadline(ms);
+    }
+    /** Evaluate code (as a module when asked); a script error comes back as `{ type: "error" }`. */
+    eval(code, name, module = false) {
+        return this.withString(code, (c, len) => this.withString(name, (n) => (this.x.qd_eval(c, len, n, module ? 1 : 0), this.result())));
+    }
+    /** Run bytecode that {@link QuickJSInstance.compile} made with this very build of QuickJS. */
+    evalBytecode(bytes) {
+        const ptr = this.x.qd_alloc(bytes.length);
+        new Uint8Array(this.x.memory.buffer).set(bytes, ptr);
+        try {
+            const failed = this.x.qd_eval_bytecode(ptr, bytes.length);
+            return failed ? this.result() : { type: "undefined" };
+        }
+        finally {
+            this.x.qd_free(ptr);
+        }
+    }
+    /** Compile code to bytecode (build time). */
+    compile(code, name) {
+        return this.withString(code, (c, len) => this.withString(name, (n) => {
+            if (this.x.qd_compile(c, len, n))
+                throw new Error(`QuickJS could not compile ${name}: ${this.result().value}`);
+            return new Uint8Array(this.x.memory.buffer, this.x.qd_result_ptr(), this.x.qd_result_len()).slice();
+        }));
+    }
+    /** Run the queued promise jobs. */
+    jobs() {
+        return this.x.qd_jobs();
+    }
+    /** Resolve (or reject) the promise of fetch `id` with a string. */
+    settle(id, ok, text) {
+        this.withString(text, (ptr, len) => this.x.qd_settle(id, ok ? 1 : 0, ptr, len));
+    }
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "wasm-quickjs-dom",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.3",
+  "description": "A small JSDOM for runtimes without Node or eval: QuickJS-ng (WebAssembly) on a linkedom DOM, for Cloudflare Workers, Vercel Edge, Deno, Bun and browsers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "wasm-quickjs-dom": "./dist/bin.js"
+  },
+  "author": "SoraKumo <info@croud.jp>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SoraKumo001/wasm-html-to-image.git",
+    "directory": "packages/quickjs-dom"
+  },
+  "homepage": "https://sorakumo001.github.io/wasm-html-to-image/master/docs/",
+  "bugs": {
+    "url": "https://github.com/SoraKumo001/wasm-html-to-image/issues"
+  },
+  "keywords": [
+    "jsdom",
+    "dom",
+    "quickjs",
+    "linkedom",
+    "wasm",
+    "webassembly",
+    "cloudflare-workers",
+    "edge-runtime"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "imports": {
+    "#quickjs-wasm": {
+      "workerd": "./dist/quickjs-workerd.js",
+      "edge-light": "./dist/quickjs-edge-light.js",
+      "deno": "./dist/quickjs-web.js",
+      "node": "./dist/quickjs-node.js",
+      "bun": "./dist/quickjs-node.js",
+      "default": "./dist/quickjs-web.js"
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./quickjs.wasm": {
+      "types": "./dist/quickjs-wasm.d.ts",
+      "default": "./dist/quickjs.wasm"
+    }
+  },
+  "files": [
+    "dist",
+    "vendor/quickjs/LICENSE",
+    "THIRD-PARTY-NOTICES.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "linkedom": "0.18.13",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5",
+    "web-streams-polyfill": "4.3.0"
+  },
+  "scripts": {
+    "build": "node scripts/build-quickjs.mjs && tsc -b && node scripts/build-edge-js.mjs",
+    "test": "vitest run"
+  }
 }

package/vendor/quickjs/LICENSE

@@ -0,0 +1,24 @@
+The MIT License (MIT)
+ 
+Copyright (c) 2017-2026 Fabrice Bellard
+Copyright (c) 2017-2024 Charlie Gordon
+Copyright (c) 2023-2026 Ben Noordhuis
+Copyright (c) 2023-2026 Saúl Ibarra Corretgé
+
+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.