From 1df20aed817e84ba8a99e1280a167bc729c170bb Mon Sep 17 00:00:00 2001 From: Brendan Clement Date: Mon, 18 May 2026 09:53:20 -0700 Subject: [PATCH] docs(nodejs): clarify Table.add progress dispatch semantics --- docs/src/js/interfaces/AddDataOptions.md | 6 +++--- nodejs/lancedb/table.ts | 6 +++--- nodejs/src/table.rs | 6 ++++-- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/src/js/interfaces/AddDataOptions.md b/docs/src/js/interfaces/AddDataOptions.md index 3c787b4fd..6976787f0 100644 --- a/docs/src/js/interfaces/AddDataOptions.md +++ b/docs/src/js/interfaces/AddDataOptions.md @@ -31,9 +31,9 @@ progress: (progress) => void; Optional callback invoked periodically with write progress. The callback is fired once per batch written and once more with -`done: true` when the write completes. Calls are non-blocking — if the -callback is slow, intermediate updates may be dropped to avoid stalling -the write. +`done: true` when the write completes. Calls are dispatched +asynchronously to the JS event loop and never block the write — a slow +callback will queue events rather than back-pressure the writer. Errors thrown from the callback are logged with `console.warn` and swallowed — they do not abort the write. diff --git a/nodejs/lancedb/table.ts b/nodejs/lancedb/table.ts index 3e27db52a..fe495392a 100644 --- a/nodejs/lancedb/table.ts +++ b/nodejs/lancedb/table.ts @@ -88,9 +88,9 @@ export interface AddDataOptions { * Optional callback invoked periodically with write progress. * * The callback is fired once per batch written and once more with - * `done: true` when the write completes. Calls are non-blocking — if the - * callback is slow, intermediate updates may be dropped to avoid stalling - * the write. + * `done: true` when the write completes. Calls are dispatched + * asynchronously to the JS event loop and never block the write — a slow + * callback will queue events rather than back-pressure the writer. * * Errors thrown from the callback are logged with `console.warn` and * swallowed — they do not abort the write. diff --git a/nodejs/src/table.rs b/nodejs/src/table.rs index 6f526e9fd..4c5424bc9 100644 --- a/nodejs/src/table.rs +++ b/nodejs/src/table.rs @@ -103,8 +103,10 @@ impl Table { if let Some(tsfn) = progress_callback { op = op.progress(move |p| { - // Non-blocking: drop progress events rather than back-pressuring - // the write if the JS callback can't keep up. + // NonBlocking: dispatch onto the JS event loop without + // blocking the writer thread. With napi-rs's default + // unbounded queue, events are not dropped — a slow JS + // callback will just queue them. tsfn.call( WriteProgressInfo::from(p), ThreadsafeFunctionCallMode::NonBlocking,