@lancedb/lancedb 0.40.0-beta.12 → 0.40.0-beta.13

package/NODEJS_THIRD_PARTY_LICENSES.md

@@ -275,6 +275,7 @@
 [@types/node@20.16.10](https://github.com/DefinitelyTyped/DefinitelyTyped) - MIT
 [@types/node@20.17.9](https://github.com/DefinitelyTyped/DefinitelyTyped) - MIT
 [@types/node@22.7.4](https://github.com/DefinitelyTyped/DefinitelyTyped) - MIT
+[@types/node@25.9.8](https://github.com/DefinitelyTyped/DefinitelyTyped) - MIT
 [@types/semver@7.5.6](https://github.com/DefinitelyTyped/DefinitelyTyped) - MIT
 [@types/stack-utils@2.0.3](https://github.com/DefinitelyTyped/DefinitelyTyped) - MIT
 [@types/tmp@0.2.6](https://github.com/DefinitelyTyped/DefinitelyTyped) - MIT
@@ -306,6 +307,9 @@
 [apache-arrow@16.0.0](https://github.com/apache/arrow) - Apache-2.0
 [apache-arrow@17.0.0](https://github.com/apache/arrow) - Apache-2.0
 [apache-arrow@18.0.0](https://github.com/apache/arrow) - Apache-2.0
+[apache-arrow@19.0.1](https://github.com/apache/arrow) - Apache-2.0
+[apache-arrow@20.0.0](https://github.com/apache/arrow) - Apache-2.0
+[apache-arrow@21.2.0](https://github.com/apache/arrow-js) - Apache-2.0
 [argparse@1.0.10](https://github.com/nodeca/argparse) - MIT
 [argparse@2.0.1](https://github.com/nodeca/argparse) - Python-2.0
 [array-back@3.1.0](https://github.com/75lb/array-back) - MIT
@@ -348,6 +352,7 @@
 [color@4.2.3](https://github.com/Qix-/color) - MIT
 [combined-stream@1.0.8](https://github.com/felixge/node-combined-stream) - MIT
 [command-line-args@5.2.1](https://github.com/75lb/command-line-args) - MIT
+[command-line-args@6.0.2](https://github.com/75lb/command-line-args) - MIT
 [command-line-usage@7.0.1](https://github.com/75lb/command-line-usage) - MIT
 [concat-map@0.0.1](https://github.com/substack/node-concat-map) - MIT
 [convert-source-map@2.0.0](https://github.com/thlorenz/convert-source-map) - MIT
@@ -398,12 +403,14 @@
 [file-entry-cache@6.0.1](https://github.com/royriojas/file-entry-cache) - MIT
 [fill-range@7.1.1](https://github.com/jonschlinkert/fill-range) - MIT
 [find-replace@3.0.0](https://github.com/75lb/find-replace) - MIT
+[find-replace@5.0.2](https://github.com/75lb/find-replace) - MIT
 [find-up@4.1.0](https://github.com/sindresorhus/find-up) - MIT
 [find-up@5.0.0](https://github.com/sindresorhus/find-up) - MIT
 [flat-cache@3.2.0](https://github.com/jaredwray/flat-cache) - MIT
 [flatbuffers@1.12.0](https://github.com/google/flatbuffers) - Apache*
 [flatbuffers@23.5.26](https://github.com/google/flatbuffers) - Apache*
 [flatbuffers@24.3.25](https://github.com/google/flatbuffers) - Apache-2.0
+[flatbuffers@25.9.23](https://github.com/google/flatbuffers) - Apache-2.0
 [flatted@3.2.9](https://github.com/WebReflection/flatted) - ISC
 [follow-redirects@1.15.6](https://github.com/follow-redirects/follow-redirects) - MIT
 [foreground-child@3.3.0](https://github.com/tapjs/foreground-child) - ISC
@@ -644,6 +651,7 @@
 [uc.micro@2.1.0](https://github.com/markdown-it/uc.micro) - MIT
 [undici-types@5.26.5](https://github.com/nodejs/undici) - MIT
 [undici-types@6.19.8](https://github.com/nodejs/undici) - MIT
+[undici-types@7.24.6](https://github.com/nodejs/undici) - MIT
 [update-browserslist-db@1.0.13](https://github.com/browserslist/update-db) - MIT
 [uri-js@4.4.1](https://github.com/garycourt/uri-js) - BSD-2-Clause
 [uuid@9.0.1](https://github.com/uuidjs/uuid) - MIT

package/dist/arrow.d.ts

@@ -9,11 +9,22 @@ export type SchemaLike = Schema | {
     get names(): unknown[];
 };
 export type FieldLike = Field | {
-    type: string;
+    type: string | DataTypeLike;
     name: string;
     nullable: boolean;
     metadata?: Map<string, string>;
 };
+/**
+ * A `DataType` from any copy or version of apache-arrow.
+ *
+ * Arrow 21 brands its classes with `unique symbol` properties, so a type
+ * object from a second copy of the library no longer satisfies the `DataType`
+ * type of this one even though it is structurally identical. Inputs that only
+ * need to be sanitized accept this looser shape instead.
+ */
+export type DataTypeLike = DataType | {
+    readonly typeId: number;
+};
 /**
  * Create an Arrow field backed by LanceDB's JSON extension type.
  *
@@ -205,6 +216,12 @@ export declare class MakeArrowTableOptions {
  * ```
  */
 export declare function makeArrowTable(data: Array<Record<string, unknown>>, options?: Partial<MakeArrowTableOptions>, metadata?: Map<string, string>): ArrowTable;
+/**
+ * Reads `Blob` / `File` values in the blob columns of `schema` into bytes so
+ * the synchronous conversion in {@link makeArrowTable} can accept them.
+ * Returns `data` itself when there is nothing to read.
+ */
+export declare function resolveBlobInputs(data: Array<Record<string, unknown>>, schema?: SchemaLike): Promise<Array<Record<string, unknown>>>;
 /**
  * Create an empty Arrow table with the provided schema
  */

package/dist/arrow.js

@@ -42,6 +42,7 @@ exports.isUnion = isUnion;
 exports.isFixedSizeBinary = isFixedSizeBinary;
 exports.isFixedSizeList = isFixedSizeList;
 exports.makeArrowTable = makeArrowTable;
+exports.resolveBlobInputs = resolveBlobInputs;
 exports.makeEmptyTable = makeEmptyTable;
 exports.convertToTable = convertToTable;
 exports.newVectorType = newVectorType;
@@ -354,6 +355,22 @@ function makeArrowTable(data, options, metadata) {
         schema = (0, sanitize_1.sanitizeSchema)(opt.schema);
         schema = validateSchemaEmbeddings(schema, data, options?.embeddingFunction);
     }
+    if (schema !== undefined) {
+        // Validate blob values up front and give every one the full
+        // `{ data, uri }` shape, so inference sees the same struct whether a row
+        // passed bytes, a URI, or a partial struct.
+        data = mapBlobInputs(data, schema, (value, field, row) => {
+            if (value === undefined) {
+                return value;
+            }
+            try {
+                return (0, blob_1.coerceBlobValue)(value);
+            }
+            catch (e) {
+                throw new Error(`Invalid value for blob field ${field} at row ${row}: ${e.message}`);
+            }
+        });
+    }
     let schemaMetadata = schema?.metadata || new Map();
     if (metadata !== undefined) {
         schemaMetadata = new Map([...schemaMetadata, ...metadata]);
@@ -401,6 +418,87 @@ function containsBlobField(field) {
     }
     return (field.type.children ?? []).some((child) => containsBlobField(child));
 }
+/**
+ * Calls `visit` on every value that lands in a blob column of `schema`,
+ * including blobs nested in structs and lists, and replaces it with the
+ * result. Records and arrays are copied only where a value changed, so the
+ * caller's data is never mutated.
+ */
+function mapBlobInputs(data, schema, visit) {
+    if (!schema.fields.some(containsBlobField)) {
+        return data;
+    }
+    return data.map((record, row) => isObject(record)
+        ? mapBlobFields(record, schema.fields, "", row, visit)
+        : record);
+}
+function mapBlobFields(record, fields, prefix, row, visit) {
+    let out;
+    for (const field of fields) {
+        if (!containsBlobField(field) || !Object.hasOwn(record, field.name)) {
+            continue;
+        }
+        const value = record[field.name];
+        const mapped = mapBlobField(value, field, `${prefix}${field.name}`, row, visit);
+        if (mapped !== value) {
+            out ??= { ...record };
+            out[field.name] = mapped;
+        }
+    }
+    return out ?? record;
+}
+function mapBlobField(value, field, label, row, visit) {
+    if ((0, blob_1.isBlobField)(field)) {
+        return visit(value, label, row);
+    }
+    if (field.type instanceof apache_arrow_1.Struct && isObject(value)) {
+        return mapBlobFields(value, field.type.children, `${label}.`, row, visit);
+    }
+    if (isList(field.type) && Array.isArray(value)) {
+        const child = field.type.children[0];
+        let out;
+        for (const [index, element] of value.entries()) {
+            const mapped = mapBlobField(element, child, `${label}[${index}]`, row, visit);
+            if (mapped !== element) {
+                out ??= [...value];
+                out[index] = mapped;
+            }
+        }
+        return out ?? value;
+    }
+    return value;
+}
+/**
+ * Reads `Blob` / `File` values in the blob columns of `schema` into bytes so
+ * the synchronous conversion in {@link makeArrowTable} can accept them.
+ * Returns `data` itself when there is nothing to read.
+ */
+async function resolveBlobInputs(data, schema) {
+    if (schema === undefined || schema === null) {
+        return data;
+    }
+    const sanitized = (0, sanitize_1.sanitizeSchema)(schema);
+    // Keyed by the Blob itself, so rows sharing one Blob (bare or as
+    // `{ data }`) read it once and share the bytes.
+    const reads = new Map();
+    mapBlobInputs(data, sanitized, (value) => {
+        const source = (0, blob_1.blobToRead)(value);
+        if (source !== undefined && !reads.has(source)) {
+            reads.set(source, source.arrayBuffer().then((buffer) => new Uint8Array(buffer)));
+        }
+        return value;
+    });
+    if (reads.size === 0) {
+        return data;
+    }
+    const bytes = new Map(await Promise.all([...reads].map(async ([source, read]) => [source, await read])));
+    return mapBlobInputs(data, sanitized, (value) => {
+        const source = (0, blob_1.blobToRead)(value);
+        return source === undefined
+            ? value
+            : (0, blob_1.withBlobBytes)(value, bytes.get(source));
+    });
+}
 function isObject(value) {
     return (typeof value === "object" &&
         value !== null &&
@@ -795,6 +893,7 @@ async function convertToTable(data, embeddings, makeTableOptions) {
         makeTableOptions.schema.metadata?.has("embedding_functions")) {
         processedData = ensureNestedFieldsExist(data, makeTableOptions.schema);
     }
+    processedData = await resolveBlobInputs(processedData, makeTableOptions?.schema);
     const table = makeArrowTable(processedData, makeTableOptions);
     return await applyEmbeddings(table, embeddings, makeTableOptions?.schema);
 }
@@ -835,6 +934,69 @@ async function fromRecordsToStreamBuffer(data, embeddings, schema) {
     const writer = apache_arrow_1.RecordBatchStreamWriter.writeAll(table);
     return Buffer.from(await writer.toUint8Array());
 }
+// `Type.Utf8View` / `Type.BinaryView` as numbers: the enum members only exist
+// in Arrow 21+, and this module compiles against every supported release.
+const UTF8_VIEW_TYPE_ID = 24;
+const BINARY_VIEW_TYPE_ID = 23;
+/**
+ * Copy a Utf8View / BinaryView `Data` into a single `Data` of `type`.
+ */
+function materializeViewData(child, type) {
+    const builder = (0, apache_arrow_1.makeBuilder)({ type, nullValues: [null] });
+    for (const value of new apache_arrow_1.Vector([child])) {
+        builder.append(value);
+    }
+    return builder.finish().flush();
+}
+/**
+ * Rebuild any top-level Utf8View / BinaryView column as Utf8 / Binary.
+ *
+ * Lance stores the view types as their offset-based equivalents anyway, so
+ * nothing is lost. Doing it here also sidesteps an Arrow JS 21 bug: its IPC
+ * writer emits a truncated views buffer for a *sliced* view array, which the
+ * Rust reader rejects with "Need at least N bytes in buffers[0]".
+ *
+ * The record batches are rebuilt positionally rather than through a
+ * `Record<string, Vector>`: JavaScript enumerates integer-like keys first, so
+ * a field named e.g. `"1"` would otherwise be paired with the wrong column.
+ *
+ * Tables without view columns are returned as-is.
+ */
+function materializeViewColumns(table) {
+    const replacements = new Map();
+    table.schema.fields.forEach((field, i) => {
+        if (field.type.typeId === UTF8_VIEW_TYPE_ID) {
+            replacements.set(i, new apache_arrow_1.Utf8());
+        }
+        else if (field.type.typeId === BINARY_VIEW_TYPE_ID) {
+            replacements.set(i, new apache_arrow_1.Binary());
+        }
+    });
+    if (replacements.size === 0) {
+        return table;
+    }
+    const fields = table.schema.fields.map((field, i) => {
+        const type = replacements.get(i);
+        return type === undefined
+            ? field
+            : new apache_arrow_1.Field(field.name, type, field.nullable, field.metadata);
+    });
+    const schema = new apache_arrow_1.Schema(fields, table.schema.metadata);
+    const batches = table.batches.map((batch) => {
+        const children = batch.data.children.map((child, i) => {
+            const type = replacements.get(i);
+            return type === undefined ? child : materializeViewData(child, type);
+        });
+        const data = (0, apache_arrow_1.makeData)({
+            type: new apache_arrow_1.Struct(fields),
+            length: batch.numRows,
+            nullCount: 0,
+            children,
+        });
+        return new apache_arrow_1.RecordBatch(schema, data);
+    });
+    return new apache_arrow_1.Table(schema, batches);
+}
 /**
  * Serialize an Arrow Table into a buffer using the Arrow IPC File serialization
  *
@@ -847,7 +1009,7 @@ async function fromTableToBuffer(table, embeddings, schema) {
     if (schema !== undefined && schema !== null) {
         schema = (0, sanitize_1.sanitizeSchema)(schema);
     }
-    const tableWithEmbeddings = await applyEmbeddings(table, embeddings, schema);
+    const tableWithEmbeddings = materializeViewColumns(await applyEmbeddings(table, embeddings, schema));
     validateBlobSchema(tableWithEmbeddings.schema);
     const writer = apache_arrow_1.RecordBatchFileWriter.writeAll(tableWithEmbeddings);
     return Buffer.from(await writer.toUint8Array());
@@ -906,7 +1068,8 @@ async function fromRecordBatchToBuffer(batch) {
  * batch + EOS) suitable for incremental decode by `arrow_ipc::reader::StreamReader`.
  */
 async function fromRecordBatchToStreamBuffer(batch) {
-    const writer = apache_arrow_1.RecordBatchStreamWriter.writeAll([batch]);
+    const table = materializeViewColumns(new apache_arrow_1.Table([batch]));
+    const writer = apache_arrow_1.RecordBatchStreamWriter.writeAll(table);
     return Buffer.from(await writer.toUint8Array());
 }
 /**
@@ -918,7 +1081,7 @@ async function fromRecordBatchToStreamBuffer(batch) {
  * `schema` is required if the table is empty
  */
 async function fromTableToStreamBuffer(table, embeddings, schema) {
-    const tableWithEmbeddings = await applyEmbeddings(table, embeddings, schema);
+    const tableWithEmbeddings = materializeViewColumns(await applyEmbeddings(table, embeddings, schema));
     const writer = apache_arrow_1.RecordBatchStreamWriter.writeAll(tableWithEmbeddings);
     return Buffer.from(await writer.toUint8Array());
 }
@@ -1019,7 +1182,7 @@ function ensureNestedFieldsExist(data, schema) {
         const completeRow = {};
         for (const field of schema.fields) {
             if (field.name in row) {
-                if (field.type.constructor.name === "Struct" &&
+                if (isPlainStructField(field) &&
                     row[field.name] !== null &&
                     row[field.name] !== undefined) {
                     // Handle nested struct
@@ -1034,15 +1197,22 @@ function ensureNestedFieldsExist(data, schema) {
             else {
                 // Keep a missing struct valid while filling each of its children with
                 // null. This is distinct from an explicitly null struct value.
-                completeRow[field.name] =
-                    field.type.constructor.name === "Struct"
-                        ? ensureStructFieldsExist({}, field.type)
-                        : null;
+                completeRow[field.name] = isPlainStructField(field)
+                    ? ensureStructFieldsExist({}, field.type)
+                    : null;
             }
         }
         return completeRow;
     });
 }
+/**
+ * Blob fields are Arrow structs, but their values are bytes, URIs, or
+ * `{ data } | { uri }` inputs that the blob coercion in `makeArrowTable`
+ * handles, so they must not be filled in like ordinary structs.
+ */
+function isPlainStructField(field) {
+    return field.type.constructor.name === "Struct" && !(0, blob_1.isBlobField)(field);
+}
 /**
  * Recursively ensures that all fields in a struct type exist in the data,
  * filling missing fields with null values.
@@ -1051,7 +1221,7 @@ function ensureStructFieldsExist(data, structType) {
     const completeStruct = {};
     for (const childField of structType.children) {
         if (childField.name in data) {
-            if (childField.type.constructor.name === "Struct" &&
+            if (isPlainStructField(childField) &&
                 data[childField.name] !== null &&
                 data[childField.name] !== undefined) {
                 // Recursively handle nested struct
@@ -1065,10 +1235,9 @@ function ensureStructFieldsExist(data, structType) {
         else {
             // Keep a missing struct valid while filling each of its children with
             // null. This is distinct from an explicitly null struct value.
-            completeStruct[childField.name] =
-                childField.type.constructor.name === "Struct"
-                    ? ensureStructFieldsExist({}, childField.type)
-                    : null;
+            completeStruct[childField.name] = isPlainStructField(childField)
+                ? ensureStructFieldsExist({}, childField.type)
+                : null;
         }
     }
     return completeStruct;

package/dist/blob.d.ts

@@ -1,6 +1,42 @@
 import { Field } from "apache-arrow";
 import { BlobFile as NativeBlobFile } from "./native";
-export type BlobInput = {
+/**
+ * Bytes accepted for a blob value. `ArrayBuffer` is wrapped without copying.
+ * `Blob` and `File` are read with `arrayBuffer()`, which only the async write
+ * paths ({@link Connection.createTable}, {@link Table.add},
+ * {@link Table.mergeInsert}) can do.
+ */
+export type BlobData = Buffer | Uint8Array | ArrayBuffer | Blob;
+/** A URI accepted for a blob value. A `URL` is stored as its `href`. */
+export type BlobUri = string | URL;
+/**
+ * A value accepted for a `lance.blob.v2` column (see {@link blob}).
+ *
+ * Either inline bytes, a URI pointing at external bytes, or a struct that sets
+ * exactly one of `data` or `uri`. `null` and `undefined` write a null blob.
+ *
+ * @example
+ * ```ts
+ * import { pathToFileURL } from "node:url";
+ * import type { BlobInput } from "@lancedb/lancedb";
+ *
+ * const rows: { id: bigint; image: BlobInput }[] = [
+ *   { id: 1n, image: await (await fetch(url)).arrayBuffer() },
+ *   { id: 2n, image: pathToFileURL("/data/cat.png") },
+ *   { id: 3n, image: { data: new Blob(["hello"]) } },
+ * ];
+ * await table.add(rows);
+ * ```
+ */
+export type BlobInput = BlobData | BlobUri | {
+    data: BlobData;
+    uri?: null;
+} | {
+    data?: null;
+    uri: BlobUri;
+} | null | undefined;
+/** A blob value normalized to the columns of the blob struct. */
+export type BlobValue = {
     data: Buffer | Uint8Array | null;
     uri: string | null;
 };
@@ -123,4 +159,22 @@ export type BlobRange = {
     start: bigint;
     end: bigint;
 };
-export declare function coerceBlobValue(value: unknown): BlobInput | null;
+/**
+ * Rewrites the synchronous-only widenings of {@link BlobInput} (`ArrayBuffer`,
+ * `URL`) into `Uint8Array` and URI strings, keeping the value's shape. Other
+ * values are returned unchanged and validated later by {@link coerceBlobValue}.
+ *
+ * Throws on `Blob` / `File`, which must be read into bytes first.
+ */
+export declare function normalizeBlobInput(value: unknown): unknown;
+/**
+ * Returns the `Blob` / `File` a blob value needs read, either the value itself
+ * or its `data` field, or `undefined` when there is nothing to read.
+ */
+export declare function blobToRead(value: unknown): Blob | undefined;
+/**
+ * Replaces the `Blob` that {@link blobToRead} found in `value` with `bytes`,
+ * keeping the value's shape.
+ */
+export declare function withBlobBytes(value: unknown, bytes: Uint8Array): unknown;
+export declare function coerceBlobValue(input: unknown): BlobValue | null;

package/dist/blob.js

@@ -6,6 +6,9 @@ exports.BlobFile = void 0;
 exports.blob = blob;
 exports.isBlobField = isBlobField;
 exports.runWithSignal = runWithSignal;
+exports.normalizeBlobInput = normalizeBlobInput;
+exports.blobToRead = blobToRead;
+exports.withBlobBytes = withBlobBytes;
 exports.coerceBlobValue = coerceBlobValue;
 const apache_arrow_1 = require("apache-arrow");
 const native_1 = require("./native");
@@ -159,7 +162,72 @@ async function runWithSignal(signal, run) {
         signal.removeEventListener("abort", onAbort);
     }
 }
-function coerceBlobValue(value) {
+/**
+ * Rewrites the synchronous-only widenings of {@link BlobInput} (`ArrayBuffer`,
+ * `URL`) into `Uint8Array` and URI strings, keeping the value's shape. Other
+ * values are returned unchanged and validated later by {@link coerceBlobValue}.
+ *
+ * Throws on `Blob` / `File`, which must be read into bytes first.
+ */
+function normalizeBlobInput(value) {
+    if (blobToRead(value) !== undefined) {
+        throw new Error("Blob and File values must be read asynchronously. Pass them to " +
+            "createTable, add, or mergeInsert, or convert them with " +
+            "`new Uint8Array(await value.arrayBuffer())`");
+    }
+    if (value instanceof ArrayBuffer) {
+        return new Uint8Array(value);
+    }
+    if (value instanceof URL) {
+        return value.href;
+    }
+    if (isBlobStruct(value)) {
+        // Read `data` and `uri` explicitly: spreading a class instance would drop
+        // fields defined as getters on its prototype.
+        const out = {
+            ...value,
+            data: value.data,
+            uri: value.uri,
+        };
+        let changed = false;
+        if (value.data instanceof ArrayBuffer) {
+            out.data = new Uint8Array(value.data);
+            changed = true;
+        }
+        if (value.uri instanceof URL) {
+            out.uri = value.uri.href;
+            changed = true;
+        }
+        return changed ? out : value;
+    }
+    return value;
+}
+/**
+ * Returns the `Blob` / `File` a blob value needs read, either the value itself
+ * or its `data` field, or `undefined` when there is nothing to read.
+ */
+function blobToRead(value) {
+    if (isBlobLike(value)) {
+        return value;
+    }
+    if (isBlobStruct(value) && isBlobLike(value.data)) {
+        return value.data;
+    }
+    return undefined;
+}
+/**
+ * Replaces the `Blob` that {@link blobToRead} found in `value` with `bytes`,
+ * keeping the value's shape.
+ */
+function withBlobBytes(value, bytes) {
+    if (isBlobLike(value)) {
+        return bytes;
+    }
+    const record = value;
+    return { ...record, uri: record.uri, data: bytes };
+}
+function coerceBlobValue(input) {
+    const value = normalizeBlobInput(input);
     if (value == null) {
         return null;
     }
@@ -167,7 +235,7 @@ function coerceBlobValue(value) {
         return { data: value, uri: null };
     }
     if (ArrayBuffer.isView(value)) {
-        throw new Error("Blob data must be Buffer or Uint8Array");
+        throw new Error("Blob data must be Buffer, Uint8Array, ArrayBuffer, or Blob");
     }
     if (typeof value === "string") {
         if (value === "") {
@@ -175,21 +243,27 @@ function coerceBlobValue(value) {
         }
         return { data: null, uri: value };
     }
-    if (typeof value === "object") {
+    if (isBlobStruct(value)) {
         const record = value;
         if (!("data" in record) && !("uri" in record)) {
             throw new Error("Blob struct values must include a 'data' or 'uri' field");
         }
+        const unknownKeys = Object.keys(record).filter((key) => key !== "data" && key !== "uri");
+        if (unknownKeys.length > 0) {
+            throw new Error(`Blob struct values only support 'data' and 'uri', got ${unknownKeys
+                .map((key) => `'${key}'`)
+                .join(", ")}`);
+        }
         const uri = record.uri;
         if (uri === "") {
             throw new Error("Blob uri cannot be empty");
         }
         if (uri != null && typeof uri !== "string") {
-            throw new Error(`Blob uri must be a string or null, got ${typeof uri}`);
+            throw new Error(`Blob uri must be a string, URL, or null, got ${typeof uri}`);
         }
         const data = record.data;
         if (data != null && !isBlobBytes(data)) {
-            throw new Error("Blob data must be Buffer, Uint8Array, or null");
+            throw new Error("Blob data must be Buffer, Uint8Array, ArrayBuffer, Blob, or null");
         }
         const bytes = data ?? null;
         const uriValue = uri ?? null;
@@ -198,7 +272,33 @@ function coerceBlobValue(value) {
         }
         return { data: bytes, uri: uriValue };
     }
-    throw new Error("Blob column values must be Buffer, Uint8Array, a URI string, null, or { data?, uri? }");
+    throw new Error("Blob column values must be Buffer, Uint8Array, ArrayBuffer, Blob, a URI string or URL, null, or { data?, uri? }");
+}
+function isBlobLike(value) {
+    return typeof Blob !== "undefined" && value instanceof Blob;
+}
+/**
+ * Whether `value` is a `{ data?, uri? }` struct: any plain object, or any
+ * other object with a `data` or `uri` field (such as a class instance), apart
+ * from the binary, `Blob`, and `URL` values that are blob inputs themselves.
+ */
+function isBlobStruct(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        ArrayBuffer.isView(value) ||
+        value instanceof ArrayBuffer ||
+        (typeof SharedArrayBuffer !== "undefined" &&
+            value instanceof SharedArrayBuffer) ||
+        isBlobLike(value) ||
+        value instanceof URL) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return (prototype === Object.prototype ||
+        prototype === null ||
+        "data" in value ||
+        "uri" in value);
 }
 function isBlobBytes(value) {
     return Buffer.isBuffer(value) || value instanceof Uint8Array;

package/dist/catalog.d.ts

@@ -1,6 +1,6 @@
 import { Connection } from "./connection";
 import { HeaderProvider } from "./header";
-import { ListDatabasesResponse, Catalog as NativeCatalog, CatalogOptions as NativeCatalogOptions } from "./native.js";
+import { Catalog as NativeCatalog, CatalogOptions as NativeCatalogOptions, DatabaseNames as NativeDatabaseNames } from "./native.js";
 import { OAuthConfig } from "./oauth";
 /** Options shared by a catalog and the database connections it returns. */
 export interface CatalogOptions extends Omit<NativeCatalogOptions, "oauthConfig"> {
@@ -8,7 +8,27 @@ export interface CatalogOptions extends Omit<NativeCatalogOptions, "oauthConfig"
     /** Called for each request to supply authentication headers. */
     headerProvider?: HeaderProvider | (() => Record<string, string> | Promise<Record<string, string>>);
 }
-export type { ListDatabasesResponse } from "./native.js";
+/**
+ * A lazy async iterator of database names with pagination state.
+ * Returned by {@link Catalog.listDatabases}.
+ */
+export declare class DatabaseNames implements AsyncIterableIterator<string> {
+    private readonly inner;
+    /** @hidden */
+    constructor(inner: NativeDatabaseNames);
+    [Symbol.asyncIterator](): AsyncIterableIterator<string>;
+    /** Fetch the next name, requesting another page only when needed. */
+    next(): Promise<IteratorResult<string>>;
+    /** Number of names available without another REST request. */
+    numPageResults(): number;
+    /**
+     * Token for the next REST request. Initially this is the supplied starting token.
+     * Returns undefined after the final page is fetched, even if names remain cached.
+     * Drain the cache before saving a token to avoid skipping names when resuming.
+     * A failed request terminates iteration and retains its token for a new iterator.
+     */
+    pageToken(): string | undefined;
+}
 /** A remote catalog manages databases through the server's root namespace. */
 export declare class Catalog {
     private readonly inner;
@@ -26,11 +46,23 @@ export declare class Catalog {
     dropDatabase(name: string, options?: {
         ignoreMissing?: boolean;
     }): Promise<void>;
-    /** List one page of databases; pass pageToken from a response for the next page. */
+    /**
+     * Iterate lazily over all database names using `for await...of`.
+     * pageToken resumes from a saved token; omitted starts at the beginning.
+     * pageLimit limits each REST response, not the total; omitted uses the server default.
+     * Request errors are raised during iteration and terminate the iterator.
+     *
+     * @example
+     * ```ts
+     * for await (const name of catalog.listDatabases({ pageLimit: 20 })) {
+     *   console.log(name);
+     * }
+     * ```
+     */
     listDatabases(options?: {
-        limit?: number;
+        pageLimit?: number;
         pageToken?: string;
-    }): Promise<ListDatabasesResponse>;
+    }): DatabaseNames;
 }
 /**
  * Connect to an HTTP(S) catalog endpoint. Catalog requests omit database-selection
@@ -40,7 +72,9 @@ export declare class Catalog {
  * ```ts
  * const catalog = await connectCatalog("https://my-server.example", { apiKey: "secret" });
  * const db = await catalog.createDatabase("analytics", { existOk: true });
- * const page = await catalog.listDatabases({ limit: 20 });
+ * for await (const name of catalog.listDatabases({ pageLimit: 20 })) {
+ *   console.log(name);
+ * }
  * ```
  */
 export declare function connectCatalog(endpoint: string, options?: CatalogOptions): Promise<Catalog>;