join — label-based DataFrame join

What it does

join(left, right, options?) aligns two DataFrames by their index labels (or a key column). Unlike the general-purpose merge(), join() defaults to a left join on index — the idiomatic way to combine DataFrames that already share an index.

Left join (default)

import { DataFrame, join } from "tsb";

const employees = DataFrame.fromColumns(
  { dept: ["Engineering", "Marketing", "Engineering"] },
  { index: ["alice", "bob", "charlie"] },
);

const salaries = DataFrame.fromColumns(
  { salary: [90_000, 75_000] },
  { index: ["alice", "charlie"] },
);

join(employees, salaries);
// dept          salary
// alice    Engineering  90000
// bob      Marketing    null    ← no salary for bob
// charlie  Engineering  75000

Inner / outer / right join

join(employees, salaries, { how: "inner" });
// Only alice and charlie (keys in BOTH DataFrames)

join(employees, salaries, { how: "outer" });
// All keys from either DataFrame (nulls where absent)

join(employees, salaries, { how: "right" });
// All keys from salaries: alice and charlie

Overlapping columns — use lsuffix / rsuffix

const a = DataFrame.fromColumns({ score: [10, 20] }, { index: ["x", "y"] });
const b = DataFrame.fromColumns({ score: [15, 25] }, { index: ["x", "y"] });

// This would throw — 'score' exists in both without suffix disambiguation:
// join(a, b);

join(a, b, { lsuffix: "_a", rsuffix: "_b" });
// score_a  score_b
// x  10    15
// y  20    25

Join on a column key

const orders = DataFrame.fromColumns({
  customerId: ["C1", "C2", "C1"],
  amount:     [100, 200, 150],
});
const customers = DataFrame.fromColumns(
  { name: ["Alice", "Bob"] },
  { index: ["C1", "C2"] },
);

// Join orders.customerId against customers index
join(orders, customers, { on: "customerId", how: "left" });
// customerId  amount  name
// C1          100     Alice
// C2          200     Bob
// C1          150     Alice

joinAll — chain multiple joins

import { joinAll } from "tsb";

const base = DataFrame.fromColumns({ A: [1,2,3] }, { index: ["K0","K1","K2"] });
const b1   = DataFrame.fromColumns({ B: [10,20,30] }, { index: ["K0","K1","K2"] });
const b2   = DataFrame.fromColumns({ C: [100,200,300] }, { index: ["K0","K1","K2"] });

joinAll(base, [b1, b2]);
// A  B   C
// 1  10  100
// 2  20  200
// 3  30  300

crossJoin — Cartesian product

import { crossJoin } from "tsb";

const colors = DataFrame.fromColumns({ color: ["red", "blue"] });
const sizes  = DataFrame.fromColumns({ size:  ["S", "M", "L"] });

crossJoin(colors, sizes);
// color  size
// red    S
// red    M
// red    L
// blue   S
// blue   M
// blue   L

API reference

JoinOptions