npm - @fast-scrape/wasm - Versions diffs - 0.1.0 - Mend

@fast-scrape/wasm 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,153 @@
+# @scrape-rs/wasm
+[![npm](https://img.shields.io/npm/v/@scrape-rs/wasm)](https://www.npmjs.com/package/@scrape-rs/wasm)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@scrape-rs/wasm)](https://bundlephobia.com/package/@scrape-rs/wasm)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
+[![codecov](https://codecov.io/gh/bug-ops/scrape-rs/graph/badge.svg?token=6MQTONGT95&flag=wasm)](https://codecov.io/gh/bug-ops/scrape-rs)
+[![License](https://img.shields.io/npm/l/@scrape-rs/wasm)](../../LICENSE-MIT)
+WebAssembly bindings for scrape-rs, a high-performance HTML parsing library. Run native-speed parsing in the browser.
+## Installation
+```bash
+# npm
+npm install @scrape-rs/wasm
+# yarn
+yarn add @scrape-rs/wasm
+# pnpm
+pnpm add @scrape-rs/wasm
+# bun
+bun add @scrape-rs/wasm
+```
+## Quick start
+```typescript
+import init, { Soup } from '@scrape-rs/wasm';
+// Initialize WASM module (required once)
+await init();
+const html = "<html><body><div class='content'>Hello, World!</div></body></html>";
+const soup = new Soup(html);
+const div = soup.find("div");
+console.log(div.text);
+// Hello, World!
+```
+> [!IMPORTANT]
+> Call `init()` once before using any other functions. It loads and compiles the WASM module.
+## Usage
+### Find elements
+```typescript
+import init, { Soup } from '@scrape-rs/wasm';
+await init();
+const soup = new Soup(html);
+// Find first element by tag
+const div = soup.find("div");
+// Find all elements
+const divs = soup.findAll("div");
+// CSS selectors
+for (const el of soup.select("div.content > p")) {
+    console.log(el.text);
+}
+```
+### With bundlers
+**Vite:**
+```typescript
+import init, { Soup } from '@scrape-rs/wasm';
+// Vite handles WASM automatically
+await init();
+```
+**Webpack 5:**
+```javascript
+// webpack.config.js
+module.exports = {
+    experiments: {
+        asyncWebAssembly: true,
+    },
+};
+```
+### CDN usage
+```html
+<script type="module">
+import init, { Soup } from 'https://esm.sh/@scrape-rs/wasm';
+await init();
+const soup = new Soup('<div>Hello</div>');
+console.log(soup.find('div').text);
+</script>
+```
+## Bundle size
+| Build | Size |
+|-------|------|
+| Minified + gzip | ~150 KB |
+| Minified | ~400 KB |
+> [!TIP]
+> The WASM module includes SIMD optimizations. Modern browsers (Chrome 91+, Firefox 89+, Safari 16.4+) run SIMD automatically.
+## TypeScript
+Full TypeScript support with exported types:
+```typescript
+import init, { Soup, Tag } from '@scrape-rs/wasm';
+await init();
+function extractLinks(soup: Soup): string[] {
+    return soup.select("a[href]").map(a => a.getAttribute("href") ?? "");
+}
+```
+## Browser support
+| Browser | Version | SIMD |
+|---------|---------|------|
+| Chrome | 80+ | 91+ |
+| Firefox | 75+ | 89+ |
+| Safari | 13+ | 16.4+ |
+| Edge | 80+ | 91+ |
+## Limitations
+- No parallel processing (WASM threads have limited browser support)
+- Must call `init()` before using the API
+- Slightly higher memory usage than native bindings
+## Related packages
+Part of the [scrape-rs](https://github.com/bug-ops/scrape-rs) project:
+- `scrape-core` — Rust core library
+- `scrape-rs` (PyPI) — Python bindings
+- `scrape-rs` (npm) — Node.js bindings
+## License
+Licensed under either of [Apache License, Version 2.0](../../LICENSE-APACHE) or [MIT License](../../LICENSE-MIT) at your option.

package/package.json ADDED Viewed

@@ -0,0 +1,24 @@
+{
+  "name": "@fast-scrape/wasm",
+  "type": "module",
+  "collaborators": [
+    "scrape-rs contributors"
+  ],
+  "description": "WebAssembly bindings for scrape-rs HTML parsing library",
+  "version": "0.1.0",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bug-ops/scrape-rs"
+  },
+  "files": [
+    "scrape_wasm_bg.wasm",
+    "scrape_wasm.js",
+    "scrape_wasm.d.ts"
+  ],
+  "main": "scrape_wasm.js",
+  "types": "scrape_wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ]
+}

package/scrape_wasm.d.ts ADDED Viewed

@@ -0,0 +1,367 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * A parsed HTML document.
+ *
+ * `Soup` is the main entry point for parsing and querying HTML documents.
+ * It provides methods for finding elements by CSS selector.
+ *
+ * @example
+ * ```javascript
+ * import init, { Soup } from '@scrape-rs/wasm';
+ *
+ * await init();
+ *
+ * const soup = new Soup("<div class='item'>Hello</div>");
+ * const div = soup.find("div.item");
+ * console.log(div.text); // "Hello"
+ * ```
+ */
+export class Soup {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Finds the first element matching a CSS selector.
+     *
+     * @param selector - CSS selector string
+     * @returns The first matching Tag, or undefined if not found
+     * @throws Error if the selector syntax is invalid
+     */
+    find(selector: string): Tag | undefined;
+    /**
+     * Finds all elements matching a CSS selector.
+     *
+     * @param selector - CSS selector string
+     * @returns Array of matching Tag instances
+     * @throws Error if the selector syntax is invalid
+     */
+    findAll(selector: string): Tag[];
+    /**
+     * Parses an HTML string into a Soup document.
+     *
+     * @param html - The HTML string to parse
+     * @param config - Optional configuration options
+     */
+    constructor(html: string, config?: SoupConfig | null);
+    /**
+     * Finds all elements matching a CSS selector (alias for findAll).
+     *
+     * @param selector - CSS selector string
+     * @returns Array of matching Tag instances
+     */
+    select(selector: string): Tag[];
+    /**
+     * Get the HTML representation of the document.
+     *
+     * @returns The document as an HTML string
+     */
+    toHtml(): string;
+    /**
+     * Get the number of nodes in the document.
+     */
+    readonly length: number;
+    /**
+     * Get the root element of the document.
+     *
+     * @returns The root Tag (usually <html>), or undefined for empty documents
+     */
+    readonly root: Tag | undefined;
+    /**
+     * Get the text content of the entire document.
+     *
+     * @returns All text content with HTML tags stripped
+     */
+    readonly text: string;
+    /**
+     * Get the document title.
+     *
+     * @returns The title text, or undefined if no <title> element exists
+     */
+    readonly title: string | undefined;
+}
+/**
+ * Configuration options for HTML parsing.
+ *
+ * All options have sensible defaults. Use setters to customize behavior.
+ *
+ * @example
+ * ```javascript
+ * const config = new SoupConfig();
+ * config.maxDepth = 256;
+ * config.strictMode = true;
+ * const soup = new Soup("<div>Hello</div>", config);
+ * ```
+ */
+export class SoupConfig {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Creates a new configuration with default values.
+     *
+     * Default values:
+     * - maxDepth: 512
+     * - strictMode: false
+     * - preserveWhitespace: false
+     * - includeComments: false
+     */
+    constructor();
+    /**
+     * Include comment nodes in DOM.
+     */
+    includeComments: boolean;
+    /**
+     * Maximum nesting depth for DOM tree.
+     */
+    maxDepth: number;
+    /**
+     * Preserve whitespace-only text nodes.
+     */
+    preserveWhitespace: boolean;
+    /**
+     * Enable strict parsing mode (fail on malformed HTML).
+     */
+    strictMode: boolean;
+}
+/**
+ * An HTML element in the DOM tree.
+ *
+ * Provides access to element content, attributes, and tree navigation.
+ *
+ * @example
+ * ```javascript
+ * const soup = new Soup('<div class="test">Hello</div>');
+ * const div = soup.find("div");
+ * console.log(div.name);          // "div"
+ * console.log(div.text);          // "Hello"
+ * console.log(div.attr("class")); // "test"
+ * ```
+ */
+export class Tag {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Get an attribute value by name (alias for get).
+     *
+     * @param name - The attribute name
+     * @returns The attribute value, or undefined if not present
+     */
+    attr(name: string): string | undefined;
+    /**
+     * Find the first descendant matching a CSS selector.
+     *
+     * @param selector - CSS selector string
+     * @returns The first matching Tag, or undefined if not found
+     * @throws Error if the selector syntax is invalid
+     */
+    find(selector: string): Tag | undefined;
+    /**
+     * Find all descendants matching a CSS selector.
+     *
+     * @param selector - CSS selector string
+     * @returns Array of matching Tag instances
+     * @throws Error if the selector syntax is invalid
+     */
+    findAll(selector: string): Tag[];
+    /**
+     * Get an attribute value by name.
+     *
+     * @param name - The attribute name
+     * @returns The attribute value, or undefined if not present
+     */
+    get(name: string): string | undefined;
+    /**
+     * Check if the element has an attribute.
+     *
+     * @param name - The attribute name
+     * @returns True if the attribute exists
+     */
+    hasAttr(name: string): boolean;
+    /**
+     * Check if the element has a specific class.
+     *
+     * @param className - The class name to check
+     * @returns True if the element has the class
+     */
+    hasClass(class_name: string): boolean;
+    /**
+     * Find all descendants matching a CSS selector (alias for findAll).
+     *
+     * @param selector - CSS selector string
+     * @returns Array of matching Tag instances
+     */
+    select(selector: string): Tag[];
+    /**
+     * Get all attributes as an object.
+     */
+    readonly attrs: object;
+    /**
+     * Get all direct child elements.
+     */
+    readonly children: Tag[];
+    /**
+     * Get all classes as an array.
+     */
+    readonly classes: string[];
+    /**
+     * Get all descendant elements.
+     */
+    readonly descendants: Tag[];
+    /**
+     * Get the inner HTML content (excluding this element's tags).
+     */
+    readonly innerHTML: string;
+    /**
+     * Get the number of direct child elements.
+     */
+    readonly length: number;
+    /**
+     * Get the tag name (e.g., "div", "span").
+     */
+    readonly name: string | undefined;
+    /**
+     * Get the next sibling element.
+     */
+    readonly nextSibling: Tag | undefined;
+    /**
+     * Get the outer HTML (including this element's tags).
+     */
+    readonly outerHTML: string;
+    /**
+     * Get the parent element.
+     */
+    readonly parent: Tag | undefined;
+    /**
+     * Get the previous sibling element.
+     */
+    readonly prevSibling: Tag | undefined;
+    /**
+     * Get the text content of this element and all descendants.
+     */
+    readonly text: string;
+}
+/**
+ * Check if WASM SIMD is supported in the current environment.
+ *
+ * Returns true if the module was compiled with SIMD support and
+ * is running on a platform that supports SIMD128 instructions.
+ *
+ * SIMD support requires:
+ * - Chrome 91+ / Firefox 89+ / Safari 16.4+
+ * - Module built with RUSTFLAGS='-C target-feature=+simd128'
+ */
+export function hasSimdSupport(): boolean;
+/**
+ * Initialize the WASM module.
+ *
+ * Sets up panic hook for better error messages in browser console.
+ * This is called automatically when the module is loaded.
+ */
+export function init(): void;
+/**
+ * Parse multiple HTML documents.
+ *
+ * Note: WASM does not support threads, so this processes documents sequentially.
+ * For parallel processing in browsers, use Web Workers with separate WASM instances.
+ *
+ * @param documents - Array of HTML strings to parse
+ * @returns Array of Soup documents
+ *
+ * @example
+ * ```javascript
+ * const soups = parseBatch(['<div>A</div>', '<div>B</div>']);
+ * console.log(soups.length); // 2
+ * ```
+ */
+export function parseBatch(documents: string[]): Soup[];
+/**
+ * Get the library version.
+ *
+ * @returns Version string (e.g., "0.1.0")
+ */
+export function version(): string;
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_tag_free: (a: number, b: number) => void;
+    readonly tag_attr: (a: number, b: number, c: number, d: number) => void;
+    readonly tag_attrs: (a: number) => number;
+    readonly tag_children: (a: number, b: number) => void;
+    readonly tag_classes: (a: number, b: number) => void;
+    readonly tag_descendants: (a: number, b: number) => void;
+    readonly tag_find: (a: number, b: number, c: number, d: number) => void;
+    readonly tag_findAll: (a: number, b: number, c: number, d: number) => void;
+    readonly tag_get: (a: number, b: number, c: number, d: number) => void;
+    readonly tag_hasAttr: (a: number, b: number, c: number) => number;
+    readonly tag_hasClass: (a: number, b: number, c: number) => number;
+    readonly tag_innerHTML: (a: number, b: number) => void;
+    readonly tag_length: (a: number) => number;
+    readonly tag_name: (a: number, b: number) => void;
+    readonly tag_nextSibling: (a: number) => number;
+    readonly tag_outerHTML: (a: number, b: number) => void;
+    readonly tag_parent: (a: number) => number;
+    readonly tag_prevSibling: (a: number) => number;
+    readonly tag_select: (a: number, b: number, c: number, d: number) => void;
+    readonly tag_text: (a: number, b: number) => void;
+    readonly __wbg_soupconfig_free: (a: number, b: number) => void;
+    readonly soupconfig_includeComments: (a: number) => number;
+    readonly soupconfig_maxDepth: (a: number) => number;
+    readonly soupconfig_new: () => number;
+    readonly soupconfig_preserveWhitespace: (a: number) => number;
+    readonly soupconfig_set_includeComments: (a: number, b: number) => void;
+    readonly soupconfig_set_maxDepth: (a: number, b: number) => void;
+    readonly soupconfig_set_preserveWhitespace: (a: number, b: number) => void;
+    readonly soupconfig_set_strictMode: (a: number, b: number) => void;
+    readonly soupconfig_strictMode: (a: number) => number;
+    readonly __wbg_soup_free: (a: number, b: number) => void;
+    readonly soup_find: (a: number, b: number, c: number, d: number) => void;
+    readonly soup_findAll: (a: number, b: number, c: number, d: number) => void;
+    readonly soup_length: (a: number) => number;
+    readonly soup_new: (a: number, b: number, c: number) => number;
+    readonly soup_root: (a: number) => number;
+    readonly soup_select: (a: number, b: number, c: number, d: number) => void;
+    readonly soup_text: (a: number, b: number) => void;
+    readonly soup_title: (a: number, b: number) => void;
+    readonly soup_toHtml: (a: number, b: number) => void;
+    readonly hasSimdSupport: () => number;
+    readonly parseBatch: (a: number, b: number, c: number) => void;
+    readonly version: (a: number) => void;
+    readonly init: () => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export4: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_start: () => 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>;