feat(node): add Node.js/Bun TypeScript bindings (fleischwolf-node)

Add a napi-rs binding crate exposing the DocumentConverter to Node.js and
Bun via a single native N-API addon (Bun implements N-API, so the same
binary loads in both — no rebuild).

The TypeScript surface mirrors the Rust API:
- convertFile / convert (in-memory bytes) plus Promise-returning *Async
  variants that run the CPU-bound work off the event loop
- Markdown or docling-core JSON output; strict Markdown; placeholder /
  embedded / referenced image modes; allowedFormats; fetchImages
- a reusable DocumentConverter class
- streamFileMarkdown: an async generator over Markdown chunks in document
  order (the streaming win for PDF), wrapping the native callback API
- supportedFormats / formatFromName helpers

Packaging: @napi-rs/cli build, generated + hand-written TypeScript types,
a self-referencing exports map (works from ESM and CommonJS), a smoke test
that passes identically under Node and Bun, and runnable Node + Bun/TS
examples. Generated artifacts (.node, native.js/.d.ts, node_modules) are
gitignored; run `npm install && npm run build`.

The crate joins the workspace (covered by fmt/clippy/test) but is marked
publish=false — it ships to npm, not crates.io.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L7XwjsWSHWjrh39JxMLuB3

Author: claude

Cargo.toml

@@ -14,6 +14,8 @@ members = [
     "crates/fleischwolf",
     "crates/fleischwolf-cli",
     "crates/fleischwolf-pdf",
+    # Node.js / Bun N-API bindings (published to npm, not crates.io).
+    "crates/fleischwolf-node",
 ]
 
 [workspace.package]

README.md

@@ -152,6 +152,31 @@ buffered `export_to_markdown_with_images` path. Use
 The CLI streams Markdown by default (`--no-stream` opts back into buffering;
 `--to json` and `--images referenced` always buffer).
 
+## Node.js / Bun bindings
+
+Native TypeScript bindings live in
+[`crates/fleischwolf-node`](./crates/fleischwolf-node) (built with
+[napi-rs](https://napi.rs)). They ship a real `.node` addon that loads in both
+Node.js and Bun (Bun implements N-API — same binary, no rebuild), exposing the
+converter with the same knobs as the Rust API: Markdown / docling JSON output,
+`strict` mode, image modes, allowed-format restriction, `fetchImages`, sync +
+async (`Promise`) calls, and a `streamFileMarkdown` async generator.
+
+```bash
+cd crates/fleischwolf-node && npm install && npm run build
+```
+
+```ts
+import { convertFile, convertFileAsync, streamFileMarkdown } from 'fleischwolf'
+
+const { content } = convertFile('report.docx')          // Markdown
+const json = await convertFileAsync('paper.pdf', { to: 'json' })
+for await (const chunk of streamFileMarkdown('paper.pdf')) process.stdout.write(chunk)
+```
+
+See [`crates/fleischwolf-node/README.md`](./crates/fleischwolf-node/README.md)
+for the full API and runnable Node + Bun examples.
+
 ## Testing
 
 All commands run from the `fleischwolf/` workspace root.
@@ -286,7 +311,9 @@ fleischwolf — bigger means Rust wins by more.
 |---|---|---|
 | `fleischwolf-core` | `DoclingDocument` model + serializers | `docling-core` |
 | `fleischwolf` | `DocumentConverter`, source loading, backends | `docling` |
+| `fleischwolf-pdf` | PDF/image ML pipeline (pdfium + ONNX layout/table/OCR) | `docling` PDF pipeline |
 | `fleischwolf-cli` | command-line interface | `docling.cli` |
+| `fleischwolf-node` | Node.js / Bun N-API bindings (npm package) | — |
 
 ## License
 

crates/fleischwolf-node/.gitignore

@@ -0,0 +1,13 @@
+# npm
+node_modules/
+package-lock.json
+
+# Build artifacts generated by `napi build` (regenerate with `npm run build`):
+#  - the native addon (large; carries the linked ONNX runtime)
+#  - the platform loader + its types
+*.node
+native.js
+native.d.ts
+
+# Example scratch output
+examples/artifacts/

crates/fleischwolf-node/Cargo.toml

@@ -0,0 +1,37 @@
+# Node.js / Bun bindings for Fleischwolf, built with napi-rs.
+#
+# Produces a native N-API addon (`.node`) that loads in both Node.js and Bun
+# (Bun implements N-API). The TypeScript surface mirrors the Rust
+# `DocumentConverter`: convert a file or in-memory bytes to Markdown or docling
+# JSON, with the same knobs (strict Markdown, image modes, allowed formats,
+# external image fetching) plus incremental Markdown streaming.
+#
+# This crate is intentionally kept OUT of the default workspace members' publish
+# flow (it ships to npm, not crates.io). It is a `cdylib` — the only artifact is
+# the addon, there is no Rust library API here.
+[package]
+name = "fleischwolf-node"
+description = "Node.js / Bun bindings for Fleischwolf (a Rust port of docling)."
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+readme = "README.md"
+# ort (via fleischwolf-pdf) needs a newer compiler than the std-only crates.
+rust-version = "1.82"
+# Not a crates.io library — the deliverable is the npm package.
+publish = false
+
+[lib]
+# napi addons are C-ABI dynamic libraries loaded by the JS runtime.
+crate-type = ["cdylib"]
+
+[dependencies]
+fleischwolf = { path = "../fleischwolf", version = "0.6.1" }
+# Node-API bindings. `napi4` enables threadsafe functions, used for streaming.
+napi = { version = "2", default-features = false, features = ["napi4"] }
+napi-derive = "2"
+
+[build-dependencies]
+napi-build = "2"

crates/fleischwolf-node/README.md

@@ -0,0 +1,154 @@
+# fleischwolf (Node.js / Bun bindings)
+
+Native [Node.js](https://nodejs.org) / [Bun](https://bun.sh) bindings for
+[Fleischwolf](https://github.com/artiz/fleischwolf) — a Rust port of
+[docling](https://github.com/docling-project/docling). Convert Markdown, HTML,
+DOCX, PPTX, XLSX, EPUB, ODF, LaTeX, email, PDF, images and more into a unified
+`DoclingDocument`, and export it as **Markdown** or docling-core **JSON**.
+
+Built with [napi-rs](https://napi.rs), so it ships a real native addon (`.node`)
+that loads in both Node.js and Bun (Bun implements N-API) — the same binary, no
+rebuild between runtimes.
+
+## Install & build
+
+This package lives in the Fleischwolf Cargo workspace and builds the addon from
+the Rust source. You need a Rust toolchain (1.82+) and Node.js 14+ (or Bun).
+
+```bash
+cd crates/fleischwolf-node
+npm install          # installs @napi-rs/cli
+npm run build        # release build → index.<platform>.node + native.js/.d.ts
+# npm run build:debug  # faster, unoptimized
+```
+
+> The addon statically links the ONNX runtime used by the PDF/image pipeline, so
+> the built `.node` is large. Declarative formats (Markdown, HTML, DOCX, …) don't
+> touch it; only PDF/image conversion loads the ML models (downloaded on first
+> use, like the CLI).
+
+## Quick start
+
+```js
+import { convertFile, convert, DocumentConverter } from 'fleischwolf'
+
+// Convert a file — format detected from the extension.
+const { content } = convertFile('report.docx')
+console.log(content) // Markdown
+
+// Convert in-memory bytes (e.g. an upload) — pass the format explicitly.
+const md = convert({ name: 'notes', data: Buffer.from('# Hi\n'), format: 'md' })
+
+// docling-core JSON instead of Markdown.
+const json = convertFile('report.docx', { to: 'json' })
+
+// Reuse a converter across many documents.
+const converter = new DocumentConverter({ strict: true })
+const a = converter.convert({ name: 'a.md', data: Buffer.from('# A\n') })
+```
+
+CommonJS works too: `const { convertFile } = require('fleischwolf')`.
+
+### Async (off the event loop)
+
+Conversion is CPU-bound; the `*Async` variants run it on the libuv thread pool
+so the event loop stays free. Prefer these for PDF/image and for servers.
+
+```js
+import { convertFileAsync } from 'fleischwolf'
+
+const res = await convertFileAsync('paper.pdf', { to: 'json' })
+```
+
+### Streaming Markdown
+
+`streamFileMarkdown` yields Markdown chunks in document order as conversion
+progresses. For PDF (whose pages convert in parallel) output starts flowing
+before the whole document is done; concatenating the chunks reproduces the
+buffered `content` byte-for-byte.
+
+```js
+import { streamFileMarkdown } from 'fleischwolf'
+
+for await (const chunk of streamFileMarkdown('paper.pdf')) {
+  process.stdout.write(chunk)
+}
+```
+
+### Images
+
+Pick how pictures render in Markdown with `imageMode`:
+
+```js
+// Inline, self-contained: ![Image](data:image/png;base64,…)
+convertFile('slides.pptx', { imageMode: 'embedded' })
+
+// Referenced: links + the image bytes to write yourself.
+const res = convertFile('slides.pptx', { imageMode: 'referenced', artifactsDir: 'assets' })
+for (const img of res.images) {
+  await fs.writeFile(img.path, img.data) // e.g. assets/image_000000.png
+}
+```
+
+JSON output always embeds extracted images as data URIs.
+
+## API
+
+### Functions
+
+| Function | Returns | Notes |
+| --- | --- | --- |
+| `convertFile(path, options?)` | `ConvertResult` | Detects format from the extension. |
+| `convert(input, options?)` | `ConvertResult` | In-memory bytes (`{ name, data, format? }`). |
+| `convertFileAsync(path, options?)` | `Promise<ConvertResult>` | Off the event loop. |
+| `convertAsync(input, options?)` | `Promise<ConvertResult>` | Off the event loop. |
+| `streamFileMarkdown(path, options?)` | `AsyncGenerator<string>` | Markdown chunks in document order. |
+| `supportedFormats()` | `string[]` | Supported input format ids. |
+| `formatFromName(name)` | `string \| null` | Detect a format id from a filename/extension. |
+
+`DocumentConverter` is the reusable form: `new DocumentConverter(converterOptions)`
+then `convert` / `convertFile` / `convertFileAsync` / `convertAsync` /
+`convertFileStreaming`. Converter config (`strict`, `fetchImages`,
+`allowedFormats`) is set once on the constructor; output options (`to`,
+`imageMode`, `artifactsDir`) are per call.
+
+### Options
+
+- `to`: `"markdown"` (default) or `"json"`.
+- `imageMode`: `"placeholder"` (default), `"embedded"`, or `"referenced"`.
+- `artifactsDir`: directory name used in `referenced` links (default `"artifacts"`).
+- `strict`: cleaner, more conformant Markdown instead of docling's byte-for-byte
+  legacy output (Markdown only).
+- `fetchImages`: for HTML/EPUB, resolve and embed external `<img src>`. Off by
+  default; fetches http(s) URLs over the network — enable only for trusted input.
+- `allowedFormats`: restrict the converter to these format ids/extensions.
+
+### `ConvertResult`
+
+```ts
+interface ConvertResult {
+  content: string          // Markdown or JSON, per `to`
+  format: string           // detected input format id
+  status: string           // "success" | "partial_success" | "failure"
+  inputName: string
+  images: { path: string; data: Buffer }[] // for the `referenced` image mode
+}
+```
+
+Full TypeScript types are generated into `index.d.ts` / `native.d.ts`.
+
+## Examples
+
+- [`examples/node-basic.mjs`](examples/node-basic.mjs) — Node.js (ESM).
+- [`examples/bun-basic.ts`](examples/bun-basic.ts) — Bun + TypeScript, with async and streaming.
+
+```bash
+npm run build          # once
+node examples/node-basic.mjs
+bun run examples/bun-basic.ts
+node test/smoke.mjs    # or: bun test/smoke.mjs
+```
+
+## License
+
+MIT, same as the rest of Fleischwolf.

crates/fleischwolf-node/build.rs

@@ -0,0 +1,5 @@
+// napi-build wires up the N-API symbol resolution and, on Windows, the
+// delay-load shim so the addon links against the host `node.exe`/`bun`.
+fn main() {
+    napi_build::setup();
+}

crates/fleischwolf-node/examples/bun-basic.ts

@@ -0,0 +1,44 @@
+// Fleischwolf from Bun, in TypeScript. Run with:
+//
+//   bun run examples/bun-basic.ts
+//
+// Bun implements N-API, so the exact same native addon loads — no rebuild. This
+// example leans on the TypeScript types and shows async conversion and the
+// streaming async generator. It also runs unchanged under `tsx`/`ts-node` on Node.
+
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+import {
+  convertFileAsync,
+  streamFileMarkdown,
+  DocumentConverter,
+  type ConvertResult,
+} from 'fleischwolf'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const html = join(here, 'inputs', 'sample.html')
+
+// 1. Async conversion — the CPU-bound work runs off the event loop, so this
+//    scales to PDF/image without blocking. Fully typed: `res` is ConvertResult.
+const res: ConvertResult = await convertFileAsync(html, { to: 'markdown' })
+console.log(`converted "${res.inputName}" (${res.format}) → ${res.status}`)
+console.log(res.content)
+
+// 2. Streaming Markdown: chunks arrive in document order as conversion
+//    progresses. For PDF, pages stream out as each finishes — output starts
+//    before the whole document is done. Concatenating the chunks equals the
+//    buffered `content`.
+console.log('--- streamed ---')
+let streamed = ''
+for await (const chunk of streamFileMarkdown(html)) {
+  process.stdout.write(chunk)
+  streamed += chunk
+}
+console.log(`\n(streamed ${streamed.length} bytes)`)
+
+// 3. Embedded images: pictures become inline base64 data URIs, so the Markdown
+//    is self-contained. (This HTML has none; the option is a no-op here, but
+//    the same call handles DOCX/PPTX/PDF figures.)
+const embedded = new DocumentConverter().convertFile(html, { imageMode: 'embedded' })
+console.log('embedded-image Markdown length:', embedded.content.length)

crates/fleischwolf-node/examples/inputs/sample.html

@@ -0,0 +1,24 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Fleischwolf sample</title>
+  </head>
+  <body>
+    <h1>Quarterly report</h1>
+    <p>Revenue grew <strong>18%</strong> year over year.</p>
+    <h2>Highlights</h2>
+    <ul>
+      <li>Launched the new pipeline</li>
+      <li>Signed three enterprise customers</li>
+    </ul>
+    <table>
+      <thead>
+        <tr><th>Region</th><th>Growth</th></tr>
+      </thead>
+      <tbody>
+        <tr><td>EMEA</td><td>22%</td></tr>
+        <tr><td>APAC</td><td>15%</td></tr>
+      </tbody>
+    </table>
+  </body>
+</html>

crates/fleischwolf-node/examples/node-basic.mjs

@@ -0,0 +1,51 @@
+// Fleischwolf from Node.js (ESM). Run with:
+//
+//   node examples/node-basic.mjs
+//
+// Shows the four common paths: convert a file, convert in-memory bytes, emit
+// docling-core JSON, and reuse a converter. See bun-basic.ts for TypeScript and
+// streaming.
+
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+import {
+  convertFile,
+  convert,
+  DocumentConverter,
+  supportedFormats,
+} from 'fleischwolf'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// 1. Convert a file on disk — format detected from the extension.
+const html = join(here, 'inputs', 'sample.html')
+const doc = convertFile(html)
+console.log('--- Markdown from sample.html ---')
+console.log(doc.content)
+
+// 2. Convert in-memory bytes (e.g. an upload) — pass the format explicitly.
+const md = '# Notes\n\nInline math $E = mc^2$ and a [link](https://example.com).\n'
+const fromBytes = convert({ name: 'notes', data: Buffer.from(md), format: 'md' })
+console.log('--- Round-tripped Markdown ---')
+console.log(fromBytes.content)
+
+// 3. Emit docling-core's native JSON wire format instead of Markdown.
+const asJson = convertFile(html, { to: 'json' })
+const model = JSON.parse(asJson.content)
+console.log('--- docling JSON ---')
+console.log('schema:', model.schema_name, model.version)
+console.log('text nodes:', model.texts.length, '| tables:', model.tables.length)
+
+// 4. Reuse a converter across many documents (config parsed once). `strict`
+//    yields cleaner, more conformant Markdown.
+const converter = new DocumentConverter({ strict: true })
+for (const [name, body] of [
+  ['a.md', '# First\n'],
+  ['b.md', '# Second\n'],
+]) {
+  const r = converter.convert({ name, data: Buffer.from(body) })
+  console.log(`converted ${name}: ${r.content.trim()}`)
+}
+
+console.log('\nsupported formats:', supportedFormats().join(', '))