feat(domain): add monotonic ULID generator and money parsing/formatting

src/lib/domain/money.ts

@@ -0,0 +1,32 @@
+const AMOUNT_RE = /^(\d+)(?:\.(\d{1,2}))?$/;
+
+/** "12.34" -> 1234. Accepts thousands separators. Returns null for anything invalid or non-positive. */
+export function parseAmountToCents(input: string): number | null {
+	const cleaned = input.trim().replace(/,/g, '');
+	const m = AMOUNT_RE.exec(cleaned);
+	if (!m) return null;
+	const whole = Number(m[1]);
+	const frac = (m[2] ?? '').padEnd(2, '0');
+	const cents = whole * 100 + Number(frac);
+	if (!Number.isSafeInteger(cents) || cents <= 0) return null;
+	return cents;
+}
+
+/** "33.33" -> 3333 basis points. Must be in (0, 100]. */
+export function parsePercentToBp(input: string): number | null {
+	const cents = parseAmountToCents(input);
+	if (cents === null || cents > 10000) return null;
+	return cents;
+}
+
+export function formatCents(cents: number, currency: string, locale = 'en-US'): string {
+	return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(cents / 100);
+}
+
+export function centsToInput(cents: number): string {
+	return (cents / 100).toFixed(2);
+}
+
+export function bpToInput(bp: number): string {
+	return (bp / 100).toFixed(2).replace(/\.?0+$/, '');
+}

src/lib/domain/ulid.ts

@@ -0,0 +1,52 @@
+import { randomBytes } from 'node:crypto';
+
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const TIME_LEN = 10;
+const RANDOM_LEN = 16;
+
+function encodeTime(ms: number): string {
+	let out = '';
+	let t = ms;
+	for (let i = 0; i < TIME_LEN; i++) {
+		out = ENCODING[t % 32] + out;
+		t = Math.floor(t / 32);
+	}
+	return out;
+}
+
+function randomDigits(): number[] {
+	const bytes = randomBytes(RANDOM_LEN);
+	return Array.from(bytes, (b) => b % 32);
+}
+
+function incrementDigits(digits: number[]): void {
+	for (let i = digits.length - 1; i >= 0; i--) {
+		if (digits[i] < 31) {
+			digits[i]++;
+			return;
+		}
+		digits[i] = 0;
+	}
+	throw new Error('ULID random component overflow');
+}
+
+/**
+ * Returns a monotonic ULID generator: ids created in the same millisecond
+ * strictly increase, so lexical order equals creation order within a process.
+ */
+export function createUlidFactory(now: () => number = Date.now): () => string {
+	let lastTime = -1;
+	let lastRandom: number[] = [];
+	return () => {
+		const t = now();
+		if (t === lastTime) {
+			incrementDigits(lastRandom);
+		} else {
+			lastTime = t;
+			lastRandom = randomDigits();
+		}
+		return encodeTime(t) + lastRandom.map((d) => ENCODING[d]).join('');
+	};
+}
+
+export const ulid = createUlidFactory();

tests/unit/domain/money.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { formatCents, parseAmountToCents, parsePercentToBp } from '../../../src/lib/domain/money';
+
+describe('parseAmountToCents', () => {
+	it('parses whole and decimal amounts', () => {
+		expect(parseAmountToCents('12')).toBe(1200);
+		expect(parseAmountToCents('12.3')).toBe(1230);
+		expect(parseAmountToCents('12.34')).toBe(1234);
+		expect(parseAmountToCents(' 0.05 ')).toBe(5);
+		expect(parseAmountToCents('1,234.56')).toBe(123456);
+	});
+
+	it('rejects invalid input', () => {
+		expect(parseAmountToCents('')).toBeNull();
+		expect(parseAmountToCents('abc')).toBeNull();
+		expect(parseAmountToCents('12.345')).toBeNull();
+		expect(parseAmountToCents('-5')).toBeNull();
+		expect(parseAmountToCents('0')).toBeNull();
+		expect(parseAmountToCents('1e3')).toBeNull();
+	});
+});
+
+describe('parsePercentToBp', () => {
+	it('parses up to two decimals into basis points', () => {
+		expect(parsePercentToBp('50')).toBe(5000);
+		expect(parsePercentToBp('33.33')).toBe(3333);
+		expect(parsePercentToBp('0.01')).toBe(1);
+		expect(parsePercentToBp('100')).toBe(10000);
+	});
+
+	it('rejects invalid percents', () => {
+		expect(parsePercentToBp('100.01')).toBeNull();
+		expect(parsePercentToBp('0')).toBeNull();
+		expect(parsePercentToBp('12.345')).toBeNull();
+	});
+});
+
+describe('formatCents', () => {
+	it('formats with the currency symbol', () => {
+		expect(formatCents(1234, 'USD')).toBe('$12.34');
+		expect(formatCents(-500, 'USD')).toBe('-$5.00');
+		expect(formatCents(0, 'USD')).toBe('$0.00');
+	});
+});

tests/unit/domain/ulid.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { createUlidFactory, ulid } from '../../../src/lib/domain/ulid';
+
+describe('ulid', () => {
+	it('produces 26-char Crockford base32 strings', () => {
+		expect(ulid()).toMatch(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+	});
+
+	it('is monotonic within the same millisecond and sorts by time across ms', () => {
+		let t = 1_700_000_000_000;
+		const next = createUlidFactory(() => t);
+		const a = next();
+		const b = next();
+		expect(b > a).toBe(true);
+		t += 1;
+		const c = next();
+		expect(c > b).toBe(true);
+		expect(c.slice(0, 10) > a.slice(0, 10)).toBe(true);
+	});
+
+	it('encodes the timestamp in the first 10 characters', () => {
+		const next = createUlidFactory(() => 0);
+		expect(next().slice(0, 10)).toBe('0000000000');
+	});
+});