feat(domain): compute net balances and simplified debts

src/lib/domain/balances.ts

@@ -0,0 +1,48 @@
+import type { Expense, Settlement } from './types';
+
+export interface Debt {
+	from: string;
+	to: string;
+	cents: number;
+}
+
+/** Positive = is owed money; negative = owes money. Only users touched by any item appear. */
+export function computeNets(expenses: Iterable<Expense>, settlements: Iterable<Settlement>): Map<string, number> {
+	const nets = new Map<string, number>();
+	const add = (id: string, delta: number) => nets.set(id, (nets.get(id) ?? 0) + delta);
+	for (const e of expenses) {
+		add(e.paidBy, e.amountCents);
+		for (const [uid, cents] of Object.entries(e.shares)) add(uid, -cents);
+	}
+	for (const s of settlements) {
+		add(s.from, s.amountCents);
+		add(s.to, -s.amountCents);
+	}
+	return nets;
+}
+
+const byMagnitudeThenId = (a: [string, number], b: [string, number]) =>
+	Math.abs(b[1]) - Math.abs(a[1]) || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+
+/** Greedy pairing of largest debtor with largest creditor. Deterministic; at most n-1 transfers. */
+export function simplifyDebts(nets: Map<string, number>): Debt[] {
+	const creditors = [...nets].filter(([, v]) => v > 0).sort(byMagnitudeThenId);
+	const debtors = [...nets]
+		.filter(([, v]) => v < 0)
+		.map(([id, v]) => [id, -v] as [string, number])
+		.sort(byMagnitudeThenId);
+	const debts: Debt[] = [];
+	let i = 0;
+	let j = 0;
+	while (i < debtors.length && j < creditors.length) {
+		const [debtor, owes] = debtors[i];
+		const [creditor, owed] = creditors[j];
+		const cents = Math.min(owes, owed);
+		debts.push({ from: debtor, to: creditor, cents });
+		debtors[i] = [debtor, owes - cents];
+		creditors[j] = [creditor, owed - cents];
+		if (debtors[i][1] === 0) i++;
+		if (creditors[j][1] === 0) j++;
+	}
+	return debts;
+}

tests/unit/domain/balances.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { computeNets, simplifyDebts } from '../../../src/lib/domain/balances';
+import type { Expense, Settlement } from '../../../src/lib/domain/types';
+
+const audit = { createdBy: 'a', createdAt: '2026-01-01T00:00:00.000Z', updatedBy: 'a', updatedAt: '2026-01-01T00:00:00.000Z' };
+const exp = (paidBy: string, amountCents: number, shares: Record<string, number>): Expense => ({
+	id: `e_${Math.random()}`, version: 1, description: 'x', amountCents, currency: 'USD', date: '2026-01-01',
+	paidBy, split: { mode: 'exact', cents: shares }, shares, ...audit
+});
+const pay = (from: string, to: string, amountCents: number): Settlement => ({
+	id: `s_${Math.random()}`, version: 1, from, to, amountCents, date: '2026-01-01', ...audit
+});
+
+describe('computeNets', () => {
+	it('credits payer and debits participants', () => {
+		const nets = computeNets([exp('a', 3000, { a: 1000, b: 1000, c: 1000 })], []);
+		expect(nets).toEqual(new Map([['a', 2000], ['b', -1000], ['c', -1000]]));
+	});
+
+	it('applies settlements', () => {
+		const nets = computeNets([exp('a', 3000, { a: 1000, b: 1000, c: 1000 })], [pay('b', 'a', 1000)]);
+		expect(nets.get('a')).toBe(1000);
+		expect(nets.get('b')).toBe(0);
+	});
+
+	it('nets always sum to zero (property)', () => {
+		const nets = computeNets(
+			[exp('a', 1001, { a: 334, b: 333, c: 334 }), exp('b', 77, { c: 77 }), exp('c', 5, { a: 2, b: 3 })],
+			[pay('c', 'a', 50), pay('a', 'b', 7)]
+		);
+		expect([...nets.values()].reduce((x, y) => x + y, 0)).toBe(0);
+	});
+});
+
+describe('simplifyDebts', () => {
+	it('returns nothing when everyone is settled', () => {
+		expect(simplifyDebts(new Map([['a', 0], ['b', 0]]))).toEqual([]);
+	});
+
+	it('produces transfers that exactly settle all nets, using at most n-1 transfers', () => {
+		const nets = new Map([['a', 5000], ['b', -2000], ['c', -3000], ['d', 1000], ['e', -1000]]);
+		const debts = simplifyDebts(nets);
+		expect(debts.length).toBeLessThanOrEqual(4);
+		const after = new Map(nets);
+		for (const d of debts) {
+			expect(d.cents).toBeGreaterThan(0);
+			after.set(d.from, (after.get(d.from) ?? 0) + d.cents);
+			after.set(d.to, (after.get(d.to) ?? 0) - d.cents);
+		}
+		expect([...after.values()].every((v) => v === 0)).toBe(true);
+	});
+
+	it('is deterministic', () => {
+		const nets = new Map([['b', -100], ['a', 100], ['c', -50], ['d', 50]]);
+		expect(simplifyDebts(nets)).toEqual(simplifyDebts(new Map([...nets].reverse())));
+	});
+});