docling.rs 0.32.0 → 0.33.0

package/README.md

@@ -159,12 +159,22 @@ import { Pipeline } from 'docling.rs'
 
 const pipeline = new Pipeline({ strict: true })
 for (const path of pdfPaths) {
-  const { content } = pipeline.convertFile(path, { to: 'markdown' }) // warm models
+  const { content } = await pipeline.convertFileAsync(path, { to: 'json' }) // warm models, off the event loop
+}
+
+// Or stream a PDF's Markdown as pages finish converting:
+for await (const chunk of pipeline.streamFileMarkdown('paper.pdf')) {
+  process.stdout.write(chunk)
 }
 ```
 
-`Pipeline` handles `pdf` and `image` inputs (the ML pipeline) and is synchronous
-— reuse one instance behind a job queue.
+`Pipeline` handles `pdf` and `image` inputs (the ML pipeline). The sync
+`convertFile` / `convert` block the event loop; the `*Async` variants run on the
+libuv thread pool, and `streamFileMarkdown` yields Markdown chunks in document
+order as pages finish. Conversions on one instance run one at a time (the
+models are mutable sessions) — overlapping `*Async` calls queue in submission
+order, so batch throughput comes from keeping the models warm, not from
+parallel calls.
 
 ### Images
 
@@ -199,7 +209,8 @@ JSON output always embeds extracted images as data URIs.
 | `checkDependencies(options?)` | `DependencyStatus` | Report which PDF/image deps are present. |
 
 `Pipeline` is the reusable warm PDF/image converter: `new Pipeline(converterOptions)`
-then `convertFile` / `convert`.
+then `convertFile` / `convert` / `convertFileAsync` / `convertAsync` /
+`convertFileStreaming` / `streamFileMarkdown`.
 
 `DocumentConverter` is the reusable form: `new DocumentConverter(converterOptions)`
 then `convert` / `convertFile` / `convertFileAsync` / `convertAsync` /

package/index.d.ts

@@ -37,15 +37,40 @@ export declare class DocumentConverter {
   convertFileStreaming(path: string, callback: StreamCallback, options?: OutputOptions | null): void
 }
 
+/** Output options for {@link Pipeline.streamFileMarkdown} (streamable modes only). */
+export interface PipelineStreamOptions {
+  imageMode?: 'placeholder' | 'embedded'
+  artifactsDir?: string
+}
+
 /**
  * A reusable PDF/image pipeline that keeps the ONNX models loaded across calls.
  * Use instead of the per-call functions when converting many PDFs/images — the
  * one-shot path reloads every model each call. Handles `pdf` and `image` inputs.
+ *
+ * The `*Async` variants run the conversion off the event loop; overlapping
+ * calls on one instance queue (the models are mutable sessions), so batch
+ * throughput comes from keeping the models warm, not from parallel calls.
  */
 export declare class Pipeline {
   constructor(options?: ConverterOptions | null)
   convertFile(path: string, options?: OutputOptions | null): ConvertResult
   convert(input: ConvertInput, options?: OutputOptions | null): ConvertResult
+  /** Async (Promise) file conversion on the warm pipeline, off the event loop. */
+  convertFileAsync(path: string, options?: OutputOptions | null): Promise<ConvertResult>
+  /** Async (Promise) bytes conversion on the warm pipeline, off the event loop. */
+  convertAsync(input: ConvertInput, options?: OutputOptions | null): Promise<ConvertResult>
+  /** Callback-form streaming (prefer {@link Pipeline.streamFileMarkdown}). */
+  convertFileStreaming(path: string, callback: StreamCallback, options?: OutputOptions | null): void
+  /**
+   * Stream a PDF's Markdown in chunks through the warm pipeline, in document
+   * order, as pages finish converting (an image arrives as a single chunk).
+   * Concatenating the chunks reproduces the buffered Markdown byte-for-byte.
+   */
+  streamFileMarkdown(
+    filePath: string,
+    options?: PipelineStreamOptions,
+  ): AsyncGenerator<string, void, unknown>
 }
 
 // --- dependency provisioning (PDF/image ML pipeline) -----------------------

package/index.js

@@ -5,7 +5,8 @@
 //   1. dependency guards — converting a PDF/image/METS input throws a clear
 //      error unless the ML models + pdfium are on disk (see
 //      scripts/download_dependencies.sh);
-//   2. a `streamFileMarkdown` async generator over Markdown chunks.
+//   2. `streamFileMarkdown` async generators over Markdown chunks (module-level
+//      and on the warm `Pipeline`).
 //
 // Works in Node.js and Bun (Bun implements N-API).
 
@@ -23,6 +24,48 @@ function mlFormatOf(name, format) {
   return native.formatFromName(name || '') || ''
 }
 
+// Bridge a native (err, chunk) streaming callback into an async generator.
+// `start` receives the callback and kicks off the native conversion. Chunks
+// are delivered on the event loop (via a threadsafe function); a null chunk
+// ends the stream, a non-null err ends it with a throw.
+async function* chunkStream(start) {
+  const queue = []
+  let done = false
+  let failure = null
+  let notify = null
+  const wake = () => {
+    if (notify) {
+      const n = notify
+      notify = null
+      n()
+    }
+  }
+
+  start((err, chunk) => {
+    if (err) {
+      failure = err
+      done = true
+    } else if (chunk === null || chunk === undefined) {
+      done = true
+    } else {
+      queue.push(chunk)
+    }
+    wake()
+  })
+
+  while (true) {
+    if (queue.length > 0) {
+      yield queue.shift()
+      continue
+    }
+    if (failure) throw failure
+    if (done) return
+    await new Promise((resolve) => {
+      notify = resolve
+    })
+  }
+}
+
 // --- guarded one-shot functions --------------------------------------------
 
 function convertFile(path, options) {
@@ -94,6 +137,41 @@ class Pipeline {
     assertMlReady(mlFormatOf(input && input.name, input && input.format))
     return this._inner.convert(input, options)
   }
+
+  // async so a guard failure surfaces as a rejected promise, not a sync throw.
+  async convertFileAsync(path, options) {
+    assertMlReady(mlFormatOf(path))
+    return this._inner.convertFileAsync(path, options)
+  }
+
+  async convertAsync(input, options) {
+    assertMlReady(mlFormatOf(input && input.name, input && input.format))
+    return this._inner.convertAsync(input, options)
+  }
+
+  convertFileStreaming(path, callback, options) {
+    assertMlReady(mlFormatOf(path))
+    return this._inner.convertFileStreaming(path, callback, options)
+  }
+
+  /**
+   * Stream a PDF's Markdown in chunks through the warm pipeline, in document
+   * order, as pages finish converting (an image arrives as a single chunk).
+   * Same contract as the module-level `streamFileMarkdown`, but reusing this
+   * instance's loaded models — no per-call model reload.
+   *
+   * @param {string} filePath
+   * @param {object} [options] output options (`imageMode`: `placeholder` or
+   *   `embedded`; `referenced` is rejected)
+   * @returns {AsyncGenerator<string, void, unknown>}
+   */
+  async *streamFileMarkdown(filePath, options = {}) {
+    assertMlReady(mlFormatOf(filePath))
+    const { imageMode, artifactsDir } = options
+    yield* chunkStream((callback) =>
+      this._inner.convertFileStreaming(filePath, callback, { imageMode, artifactsDir }),
+    )
+  }
 }
 
 // --- streaming --------------------------------------------------------------
@@ -113,49 +191,9 @@ async function* streamFileMarkdown(filePath, options = {}) {
   assertMlReady(mlFormatOf(filePath))
   const { strict, fetchImages, allowedFormats, imageMode, artifactsDir } = options
   const converter = new native.DocumentConverter({ strict, fetchImages, allowedFormats })
-
-  // Bridge the native (err, chunk) callback into an async generator. Chunks are
-  // delivered on the event loop (via a threadsafe function); a null chunk ends
-  // the stream, a non-null err ends it with a throw.
-  const queue = []
-  let done = false
-  let failure = null
-  let notify = null
-  const wake = () => {
-    if (notify) {
-      const n = notify
-      notify = null
-      n()
-    }
-  }
-
-  converter.convertFileStreaming(
-    filePath,
-    (err, chunk) => {
-      if (err) {
-        failure = err
-        done = true
-      } else if (chunk === null || chunk === undefined) {
-        done = true
-      } else {
-        queue.push(chunk)
-      }
-      wake()
-    },
-    { imageMode, artifactsDir },
+  yield* chunkStream((callback) =>
+    converter.convertFileStreaming(filePath, callback, { imageMode, artifactsDir }),
   )
-
-  while (true) {
-    if (queue.length > 0) {
-      yield queue.shift()
-      continue
-    }
-    if (failure) throw failure
-    if (done) return
-    await new Promise((resolve) => {
-      notify = resolve
-    })
-  }
 }
 
 // --- exports (explicit, so ESM named imports work in Node and Bun) ----------

package/native.d.ts

@@ -154,4 +154,25 @@ export declare class Pipeline {
   convertFile(path: string, options?: OutputOptions | undefined | null): ConvertResult
   /** Convert PDF or image bytes, reusing the warm models. */
   convert(input: ConvertInput, options?: OutputOptions | undefined | null): ConvertResult
+  /**
+   * Async (Promise-returning) file conversion on the warm pipeline. The
+   * CPU-bound work runs on the libuv thread pool, keeping the event loop
+   * free; calls on the same instance run one at a time (the models are
+   * mutable sessions), so overlapping Promises queue in submission order.
+   */
+  convertFileAsync(path: string, options?: OutputOptions | undefined | null): Promise<ConvertResult>
+  /** Async (Promise-returning) bytes conversion on the warm pipeline. */
+  convertAsync(input: ConvertInput, options?: OutputOptions | undefined | null): Promise<ConvertResult>
+  /**
+   * Stream a PDF's Markdown in chunks through the warm pipeline, in document
+   * order, as pages finish converting (an image converts in one step and
+   * arrives as a single chunk).
+   *
+   * `callback` is invoked as `(err, chunk)`: once per Markdown chunk with
+   * `chunk` a string, once with `chunk === null` at the end, or once with a
+   * non-null `err` on failure. Only `placeholder` / `embedded` image modes
+   * stream; `referenced` is rejected. Prefer the `streamFileMarkdown`
+   * async-generator wrapper in JS over calling this directly.
+   */
+  convertFileStreaming(path: string, callback: (err: Error | null, arg: string | undefined | null) => any, options?: OutputOptions | undefined | null): void
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docling.rs",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Node.js / Bun bindings for docling.rs — a Rust port of docling. Convert Markdown, HTML, DOCX, PPTX, XLSX, PDF, images and more into a unified DoclingDocument (Markdown or docling-core JSON).",
   "keywords": [
     "docling",
@@ -64,8 +64,8 @@
     "@napi-rs/cli": "^2.18.4"
   },
   "optionalDependencies": {
-    "docling.rs-linux-x64-gnu": "0.32.0",
-    "docling.rs-linux-arm64-gnu": "0.32.0",
-    "docling.rs-win32-x64-msvc": "0.32.0"
+    "docling.rs-linux-x64-gnu": "0.33.0",
+    "docling.rs-linux-arm64-gnu": "0.33.0",
+    "docling.rs-win32-x64-msvc": "0.33.0"
   }
 }