feat: add factory method for locale aware formatter

Author: MikeSpa

src/format/formatters.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { createFormatters } from './formatters';
+
+describe('createFormatters', () => {
+  it('binds the given locale by default', () => {
+    const fmt = createFormatters('de-DE');
+    expect(fmt.formatNumber(1234567)).toBe('1.234.567');
+    expect(fmt.formatCompact(1200)).toBe('1200');
+  });
+
+  it('formats dates and currency in the bound locale', () => {
+    const fmt = createFormatters('de-DE');
+    expect(fmt.formatDate('2026-06-19')).toBe('19.6.2026');
+    expect(fmt.formatCurrency(1234.5, { currency: 'EUR' })).toMatch(/1\.234,50/);
+  });
+
+  it('formats relative time in the bound locale', () => {
+    const fmt = createFormatters('de-DE');
+    const now = new Date('2026-06-19T12:00:00Z');
+    expect(fmt.formatRelative(new Date('2026-06-19T09:00:00Z'), { now })).toMatch(/Stunden/);
+  });
+
+  it('allows overriding the locale per call', () => {
+    const fmt = createFormatters('de-DE');
+    // fr-CH uses U+202F (narrow no-break space) as thousands separator
+    expect(fmt.formatNumber(1234567, { locale: 'fr-CH' })).toBe('1 234 567');
+  });
+
+  it('is independent across instances (no shared state)', () => {
+    const de = createFormatters('de-DE');
+    const fr = createFormatters('fr-CH');
+    expect(de.formatNumber(1234567)).toBe('1.234.567');
+    expect(fr.formatNumber(1234567)).toBe('1 234 567');
+  });
+});

src/format/formatters.ts

@@ -0,0 +1,36 @@
+import { formatDate, formatTime, formatDateTime, formatRelative } from './date';
+import { formatNumber, formatCompact, formatCurrency, formatPercent } from './number';
+
+/**
+ * Returns the locale-aware `format*` functions pre-bound to `locale`, so call sites
+ * don't need to repeat `{ locale }` on every call. Each returned function still accepts
+ * its normal options and can override the locale per-call if needed. Stateless: safe to
+ * call once per request/component, no shared state across concurrent calls.
+ */
+export function createFormatters(locale: string) {
+  return {
+    formatDate: (input: Parameters<typeof formatDate>[0], options: Parameters<typeof formatDate>[1] = {}) =>
+      formatDate(input, { locale, ...options }),
+
+    formatTime: (input: Parameters<typeof formatTime>[0], options: Parameters<typeof formatTime>[1] = {}) =>
+      formatTime(input, { locale, ...options }),
+
+    formatDateTime: (input: Parameters<typeof formatDateTime>[0], options: Parameters<typeof formatDateTime>[1] = {}) =>
+      formatDateTime(input, { locale, ...options }),
+
+    formatRelative: (input: Parameters<typeof formatRelative>[0], options: Parameters<typeof formatRelative>[1] = {}) =>
+      formatRelative(input, { locale, ...options }),
+
+    formatNumber: (value: Parameters<typeof formatNumber>[0], options: Parameters<typeof formatNumber>[1] = {}) =>
+      formatNumber(value, { locale, ...options }),
+
+    formatCompact: (value: Parameters<typeof formatCompact>[0], options: Parameters<typeof formatCompact>[1] = {}) =>
+      formatCompact(value, { locale, ...options }),
+
+    formatCurrency: (value: Parameters<typeof formatCurrency>[0], options: Parameters<typeof formatCurrency>[1] = {}) =>
+      formatCurrency(value, { locale, ...options }),
+
+    formatPercent: (value: Parameters<typeof formatPercent>[0], options: Parameters<typeof formatPercent>[1] = {}) =>
+      formatPercent(value, { locale, ...options }),
+  };
+}

src/format/index.ts

@@ -2,3 +2,4 @@ export * from './number';
 export * from './date';
 export * from './duration';
 export * from './swiss';
+export * from './formatters';