feat: add table branch support to remote tables and Python/TS bindings

nodejs/__test__/remote.test.ts

@@ -191,30 +191,36 @@ describe("remote connection", () => {
     );
   });
 
-  it("allows version on remote but rejects a non-main branch", async () => {
+  it("supports version time-travel and branches on remote", async () => {
     await withMockDatabase(
-      (_req, res) => {
-        // describe (table open + version validation) always succeeds
-        const body = JSON.stringify({
-          name: "t",
-          version: 2,
-          schema: { fields: [] },
-        });
+      (req, res) => {
+        const body = req.url?.includes("/branches/list")
+          ? JSON.stringify({
+              branches: {
+                exp: { parentVersion: 1, createAt: 1, manifestSize: 1 },
+              },
+            })
+          : JSON.stringify({ name: "t", version: 2, schema: { fields: [] } });
         res.writeHead(200, { "Content-Type": "application/json" }).end(body);
       },
       async (db) => {
-        // version-only (and "main" + version) is allowed: remote supports
-        // version time-travel even though it has no branches
-        await db.openTable("t", undefined, { version: 2 });
-        await db.openTable("t", undefined, { branch: "main", version: 2 });
+        // version-only (and "main" + version) time-travel the main chain
+        const v2 = await db.openTable("t", undefined, { version: 2 });
+        expect(v2.currentBranch()).toBeNull();
+        const mainV2 = await db.openTable("t", undefined, {
+          branch: "main",
+          version: 2,
+        });
+        expect(mainV2.currentBranch()).toBeNull();
 
-        // a non-main branch is rejected, with or without a version
-        await expect(
-          db.openTable("t", undefined, { branch: "exp" }),
-        ).rejects.toThrow(/branching/);
-        await expect(
-          db.openTable("t", undefined, { branch: "exp", version: 2 }),
-        ).rejects.toThrow(/branching/);
+        // a non-main branch opens a handle scoped to that branch
+        const exp = await db.openTable("t", undefined, { branch: "exp" });
+        expect(exp.currentBranch()).toBe("exp");
+        const expV2 = await db.openTable("t", undefined, {
+          branch: "exp",
+          version: 2,
+        });
+        expect(expV2.currentBranch()).toBe("exp");
       },
     );
   });

nodejs/__test__/table.test.ts

@@ -89,8 +89,11 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
       await table.add([{ id: 1 }]);
       expect(await table.countRows()).toBe(1);
 
+      expect(table.currentBranch()).toBeNull();
+
       // fork an isolated, writable branch from main
       const branch = await (await table.branches()).create("exp");
+      expect(branch.currentBranch()).toBe("exp");
       expect(await branch.countRows()).toBe(1);
       await branch.add([{ id: 2 }]);
       expect(await branch.countRows()).toBe(2);
@@ -109,6 +112,7 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
 
       // checkout returns a handle scoped to the branch's latest
       const checkedOut = await (await table.branches()).checkout("exp");
+      expect(checkedOut.currentBranch()).toBe("exp");
       expect(await checkedOut.countRows()).toBe(2);
 
       // delete removes it

nodejs/lancedb/table.ts

@@ -663,6 +663,14 @@ export abstract class Table {
    */
   abstract branches(): Promise<Branches>;
 
+  /**
+   * The branch this table handle is scoped to, or `null` for the main branch.
+   *
+   * A handle returned by {@link Branches.create} or {@link Branches.checkout}
+   * reports the branch it targets; a handle opened normally reports `null`.
+   */
+  abstract currentBranch(): string | null;
+
   /**
    * Restore the table to the currently checked out version
    *
@@ -1122,6 +1130,10 @@ export class LocalTable extends Table {
     return new Branches(await this.inner.branches());
   }
 
+  currentBranch(): string | null {
+    return this.inner.currentBranch() ?? null;
+  }
+
   async optimize(options?: Partial<OptimizeOptions>): Promise<OptimizeStats> {
     let cleanupOlderThanMs;
     if (

nodejs/src/table.rs

@@ -487,6 +487,12 @@ impl Table {
         })
     }
 
+    /// The branch this handle is scoped to, or `null` for the main branch.
+    #[napi]
+    pub fn current_branch(&self) -> napi::Result<Option<String>> {
+        Ok(self.inner_ref()?.current_branch())
+    }
+
     #[napi(catch_unwind)]
     pub async fn optimize(
         &self,