feat(node): expose seek, tell, bounded read, readRanges and close on BlobFile (#4348)

Closes #4300.

The TypeScript `BlobFile` only had `size()`, `read()` and `readRange()`,
while the Rust `BlobFile` behind it also has `seek`, `tell`,
`read_up_to`, `read_ranges` and `close`. This exposes those on the Node
binding:

- `read(maxBytes?)` reads at most `maxBytes` from the cursor (Rust
`read_up_to`). Without the argument it reads to the end, as before.
- `readRanges([{ start, end }, ...])` reads several half-open ranges and
returns one buffer per range, in order. Like `readRange`, it does not
move the cursor.
- `seek(position)` and `tell()` move and report the cursor.
- `close()` releases the handle, and `isClosed()` reports it. Every
read, `seek` and `tell` after `close()` fails with "blob file is already
closed". A second `close()` does nothing. The binding keeps its own
`closed` flag, the same way the Python `BlobFile` does.

Offsets and lengths are `bigint`, like `readRange` and `size()`.
`BlobRange` is exported as a type.

The new tests in `table.test.ts` cover chunked reads with
`read(maxBytes)`, `seek` and `tell`, a negative seek position,
`readRanges` order and cursor, a `readRanges` end past the blob size,
and reads after `close()`. The Node docs under `docs/src/js` are
regenerated with `pnpm run docs`.

I left the `ReadableStream`/async iterator idea from the issue out of
this PR. The AbortSignal work in #4288 touches the same methods, so it
can follow on top of this.

nodejs/src/blob.rs

@@ -3,6 +3,7 @@
 
 use std::ops::Range;
 use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
 
 use arrow_array::{Array, LargeBinaryArray};
 use lancedb::blob::BlobFile as LanceBlobFile;
@@ -11,15 +12,31 @@ use napi_derive::napi;
 
 use crate::error::convert_error;
 
+#[napi(object)]
+pub struct BlobRange {
+    pub start: BigInt,
+    pub end: BigInt,
+}
+
 #[napi]
 pub struct BlobFile {
     inner: Arc<LanceBlobFile>,
+    closed: AtomicBool,
 }
 
 impl BlobFile {
     pub(crate) fn new(inner: LanceBlobFile) -> Self {
         Self {
             inner: Arc::new(inner),
+            closed: AtomicBool::new(false),
+        }
+    }
+
+    fn ensure_open(&self) -> napi::Result<()> {
+        if self.closed.load(Ordering::Acquire) {
+            Err(napi::Error::from_reason("blob file is already closed"))
+        } else {
+            Ok(())
         }
     }
 }
@@ -32,13 +49,23 @@ impl BlobFile {
     }
 
     #[napi]
-    pub async fn read(&self) -> napi::Result<Buffer> {
-        let bytes = self.inner.read().await.map_err(|err| convert_error(&err))?;
+    pub async fn read(&self, max_bytes: Option<BigInt>) -> napi::Result<Buffer> {
+        self.ensure_open()?;
+        let bytes = match max_bytes {
+            None => self.inner.read().await,
+            Some(max_bytes) => {
+                let max_bytes = usize::try_from(parse_u64(max_bytes, "maxBytes")?)
+                    .map_err(|_| napi::Error::from_reason("maxBytes is too large"))?;
+                self.inner.read_up_to(max_bytes).await
+            }
+        }
+        .map_err(|err| convert_error(&err))?;
         Ok(Buffer::from(bytes.as_ref()))
     }
 
     #[napi]
     pub async fn read_range(&self, start: BigInt, end: BigInt) -> napi::Result<Buffer> {
+        self.ensure_open()?;
         let range = bigint_range(start, end)?;
         let bytes = self
             .inner
@@ -47,6 +74,54 @@ impl BlobFile {
             .map_err(|err| convert_error(&err))?;
         Ok(Buffer::from(bytes.as_ref()))
     }
+
+    #[napi]
+    pub async fn read_ranges(&self, ranges: Vec<BlobRange>) -> napi::Result<Vec<Buffer>> {
+        self.ensure_open()?;
+        let ranges = ranges
+            .into_iter()
+            .map(|range| bigint_range(range.start, range.end))
+            .collect::<napi::Result<Vec<_>>>()?;
+        let buffers = self
+            .inner
+            .read_ranges(&ranges)
+            .await
+            .map_err(|err| convert_error(&err))?;
+        Ok(buffers
+            .iter()
+            .map(|bytes| Buffer::from(bytes.as_ref()))
+            .collect())
+    }
+
+    #[napi]
+    pub async fn seek(&self, position: BigInt) -> napi::Result<()> {
+        self.ensure_open()?;
+        let position = parse_u64(position, "position")?;
+        self.inner
+            .seek(position)
+            .await
+            .map_err(|err| convert_error(&err))
+    }
+
+    #[napi]
+    pub async fn tell(&self) -> napi::Result<BigInt> {
+        self.ensure_open()?;
+        let position = self.inner.tell().await.map_err(|err| convert_error(&err))?;
+        Ok(BigInt::from(position))
+    }
+
+    #[napi]
+    pub async fn close(&self) -> napi::Result<()> {
+        if self.closed.swap(true, Ordering::AcqRel) {
+            return Ok(());
+        }
+        self.inner.close().await.map_err(|err| convert_error(&err))
+    }
+
+    #[napi]
+    pub fn is_closed(&self) -> bool {
+        self.closed.load(Ordering::Acquire)
+    }
 }
 
 fn bigint_range(start: BigInt, end: BigInt) -> napi::Result<Range<u64>> {