Start here.
', { layout: 'readable', links: 'label', images: 'alt', }); // Guide // // Start here. ``` `toText` returns a JavaScript string. It does not return safe HTML. ## Safe output Prefer a text sink: ```ts element.textContent = toText(untrustedHtml); ``` If the only available sink is an HTML text node, escape the text explicitly: ```ts import { escapeHtmlText, toText } from 'purifai'; element.innerHTML = escapeHtmlText(toText(untrustedHtml)); ``` `escapeHtmlText` is only for an HTML text context. It does not make a value safe for an attribute, URL, JavaScript, CSS, or template source. A displayed URL is also still text; moving it into `href` requires a separate URL-policy decision. ## Why Purifai Most HTML-to-text tools optimize for either minimal tag removal or broad formatting control. Purifai targets a narrower intersection: | Requirement | Purifai behavior | | --- | --- | | Reader-friendly output | Preserves headings, paragraphs, lists, quotes, code, simple tables, links, and image alternatives | | Non-reader content | Drops bodies such as `script`, `style`, `template`, `iframe`, `svg`, and `math` | | Hostile-input bounds | Enforces input, output, depth, and aggregate retained-token limits during scanning | | Streaming | Uses a native Web `TransformStream` with chunk-invariant output | | Portability | Uses no DOM, document tree, Node built-in, or runtime dependency | | Predictability | Fixed policy, validated options, explicit overflow behavior, and frozen reports | That fixed scope is the reason to choose Purifai. It deliberately does not preserve markup, reconstruct CSS layout, expose custom formatters, or classify a user's intent. ## Streaming `createTextTransform` converts incrementally using the same state machine as `toText`. Joining its output produces exactly the same text for every possible input chunking. ```ts import { createTextTransform } from 'purifai'; const response = await fetch('https://example.test/article'); if (response.body === null) throw new Error('Response has no body'); const transform = createTextTransform({ links: 'label-and-url' }); const readable = response.body .pipeThrough(new TextDecoderStream()) .pipeThrough(transform); for await (const chunk of readable) { consumeText(chunk); } const report = await transform.result; ``` Stream conversion always throws when a limit is breached. Some output may already have been enqueued when `readable` and `transform.result` reject, so discard partial output unless your application explicitly accepts it. ## Bounded conversion `toText` throws a `PurifaiLimitError` when any configured limit is exceeded. Use `convert` only when a bounded prefix is an acceptable result: ```ts import { convert } from 'purifai'; const result = convert(largeHtml, { limits: { input: 1_000_000, output: 20_000, depth: 64, token: 65_536 }, overflow: 'truncate', }); result.text; result.truncatedBy; // 'input', 'output', 'depth', 'token', or null result.scanComplete; // false after truncation result.consumedInputCodeUnits; result.outputCodeUnits; result.droppedContainers; // e.g. { script: 2, style: 1 } ``` Truncation is explicit and deterministic, and never emits half of a UTF-16 surrogate pair. `toText` and `createTextTransform` never truncate silently. ## Options Unknown keys and invalid values throw `TypeError`; Purifai does not guess around configuration mistakes. | Option | Type | Default | Meaning | | --- | --- | --- | --- | | `layout` | `'readable' \| 'compact'` | `'readable'` | Structural boundaries, or normalized single-space text | | `links` | `'label' \| 'label-and-url' \| 'drop'` | `'label'` | Keep the label, append an accepted display URL, or drop the link body | | `images` | `'alt' \| 'drop'` | `'alt'` | Emit decoded non-empty `alt` text, or omit images | | `baseUrl` | `string \| URL` | none | Resolve relative display URLs against a credential-free HTTP(S) base | | `limits.input` | non-negative safe integer | `1_000_000` | Maximum input UTF-16 code units consumed | | `limits.output` | non-negative safe integer | `250_000` | Maximum output UTF-16 code units emitted | | `limits.depth` | non-negative safe integer | `64` | Maximum live structural nesting | | `limits.token` | non-negative safe integer | `65_536` | Maximum aggregate retained token and attribute code units | | `overflow` | `'throw' \| 'truncate'` | `'throw'` | `convert` only; other APIs always throw | All four limits are enforced before unbounded caller-controlled state can accumulate. Values measure JavaScript UTF-16 code units, not encoded bytes. ### Display URL policy `label-and-url` emits destinations as display text, never as active links. It accepts absolute `http:`, `https:`, and `mailto:` URLs. Relative URLs require a validated HTTP(S) `baseUrl`. Credentials, controls, ambiguous schemes, protocol-relative inputs, leading backslashes, unsupported schemes, and invalid URLs are omitted while their visible label remains. ## Extraction policy Purifai removes source and non-reader bodies including `script`, `style`, `template`, `iframe`, `noscript`, `noembed`, `noframes`, `svg`, and `math`. It preserves selected fallback and form text, decodes the complete pinned WHATWG character-reference set, preserves literal `xmp`, and treats `plaintext` as text through end of input. This is a bounded extraction grammar, not browser tree construction. It does not recreate CSS layout, browser `innerText`, complex `rowspan`/`colspan` tables, SVG/MathML semantics, selector rules, custom formatters, or browser-equivalent malformed-markup recovery. ## Benchmarks The checked category benchmark pins `striptags@3.2.0` and `html-to-text@10.0.0`. It measures reviewed readability and body-removal fixtures, isolated warm median and p95 latency, and fresh-process peak RSS. On the recorded Apple M1 / Node 24 run, Purifai passed all 11 category gates: - 8/8 readability fixtures and all 5 non-reader-body fixtures; - lower hostile-input p95 than `html-to-text` on four hostile corpora; and - lower streaming peak RSS than `html-to-text` on all five memory corpora. `striptags` remains faster on some flat-strip cases. That is not Purifai's claim. Results are machine-, runtime-, and corpus-specific. See the [complete methodology, raw results, and tables](docs/benchmarks/v3.md). Reproduce measurements with `pnpm run bench`; check the recorded release gates with `pnpm run bench:check`. ## Size, portability, and release proof The complete minified ESM runtime—including all 2,231 pinned WHATWG entity names—is 23,689 bytes with deterministic `gzip -9`. The release gate also checks packed exports, zero runtime dependencies, cold import time, and retained import heap. The same packed artifact is tested in: | Runtime | Release coverage | | --- | --- | | Node.js | 22, 24, and 26; ESM and CommonJS | | Bun | ESM and CommonJS | | Deno | ESM | | Cloudflare Workers | Real `workerd`, without Node compatibility | | Browsers | Chromium, Firefox, and WebKit | Release qualification also includes 10,000 seeded malformed-input cases, adversarial scaling checks, safe-sink tests with a positive control, package smoke tests, and npm OIDC provenance bound to the tagged GitHub source commit. ## API reference ### `toText(html, options?) → string` Converts one HTML string into readable text. Throws `TypeError` for invalid input or options and `PurifaiLimitError` for a breached limit. ### `convert(html, options?) → ConversionResult` Returns text plus a frozen report containing completion, truncation, consumed input, output length, and dropped-container counts. It is the only API that can return a deliberately truncated prefix. ### `createTextTransform(options?) → TextTransform` Returns a native `TransformStream