feat: support opening a branch directly via open_table

nodejs/__test__/table.test.ts

@@ -118,6 +118,21 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
       expect(Object.keys(after)).not.toContain("exp");
     });
 
+    it("should open a branch via open_table", async () => {
+      const db = await connect(tmpDir.name);
+      await table.add([{ id: 1 }]);
+      const branch = await (await table.branches()).create("exp");
+      await branch.add([{ id: 2 }]);
+
+      // open_table(..., { branch }) returns a handle scoped to the branch
+      const opened = await db.openTable("some_table", undefined, {
+        branch: "exp",
+      });
+      expect(await opened.countRows()).toBe(2);
+      // opening without branch still tracks main
+      expect(await (await db.openTable("some_table")).countRows()).toBe(1);
+    });
+
     it("should show table stats", async () => {
       await table.add([{ id: 1 }, { id: 2 }]);
       await table.add([{ id: 1 }]);

nodejs/lancedb/connection.ts

@@ -84,6 +84,12 @@ export interface CreateTableOptions {
 }
 
 export interface OpenTableOptions {
+  /**
+   * Open the table scoped to this branch instead of the default branch.
+   *
+   * Reads and writes on the returned table operate in the branch's context.
+   */
+  branch?: string;
   /**
    * Configuration for object storage.
    *
@@ -483,7 +489,11 @@ export class LocalConnection extends Connection {
       options?.indexCacheSize,
     );
 
-    return new LocalTable(innerTable);
+    const table = new LocalTable(innerTable);
+    if (options?.branch != null) {
+      return (await table.branches()).checkout(options.branch);
+    }
+    return table;
   }
 
   async cloneTable(