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

nodejs/__test__/table.test.ts

@@ -89,8 +89,12 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
       await table.add([{ id: 1 }]);
       expect(await table.countRows()).toBe(1);
 
+      // a handle opened normally tracks main
+      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 +113,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,