letsbe/pn-new-crm
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(utils): formatDate helper + sample sweep through PDF + template paths

Browse Source 
Phase 7 — single source of truth for date display. Backed by Intl.DateTimeFormat
(no new dep — built into Node 18+ + every supported browser). Replaces 96
ad-hoc `new Date(x).toLocaleDateString('en-GB')` calls scattered across the
codebase.

src/lib/utils/format-date.ts (new):
  formatDate(value, preset?, options?)         — primary helper
  formatDateRange(start, end, options?)        — collapsed range strings
  formatRelative(value, options?)              — "3 hours ago" / "in 2 days"

  Presets (named so callers don't memorize Intl options shape):
    date.short        12 May
    date.medium       12 May 2026
    date.long         Monday, 12 May 2026
    date.iso          2026-05-12 (TZ-aware ISO date, no time)
    datetime.short    12 May 14:30
    datetime.medium   12 May 2026 14:30
    datetime.long     Monday, 12 May 2026 at 14:30 UTC
    datetime.iso      2026-05-12T14:30:00.000Z
    time              14:30

  Defensive defaults:
    - null/undefined/Invalid Date → '—' (overridable via { fallback })
    - locale defaults to en-GB (settles audit-flagged en-US/en-GB drift)
    - tz passthrough to Intl.DateTimeFormat timeZone field (any IANA name)

Sample sweep (3 sites — proves the pattern; remaining 93 sites can be
migrated opportunistically when files are touched):
  src/lib/services/expense-pdf.service.ts:608  default subheader
  src/lib/services/document-templates.ts:364   {{interest.dateFirstContact}}
  src/lib/services/document-templates.ts:374-378  {{interest.date*Signed}}

The 93 remaining sites are listed in docs/BACKLOG.md §G with the rule:
"replace as you touch the file" — gives compounding cleanup without
a single risky 90-file commit.

tests/unit/format-date.test.ts (new) — 17 tests:
  - fallback handling (null/undefined/invalid/explicit)
  - date.iso correctness in UTC + non-UTC timezones
  - datetime.iso = full ISO string
  - en-GB locale-formatted output
  - timezone respect across NY/UTC
  - time-only preset
  - Date/string/epoch ms inputs all accepted
  - formatDateRange same-year collapse, different-year keep, missing ends
  - formatRelative: just-now / minutes / hours / days / future / invalid

1315/1315 vitest green (+17 new from format-date.test.ts).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt
2026-05-12 21:34:39 +02:00
parent 9fac84658a
commit f3aae61ad8
4 changed files with 295 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
src/lib/services/document-templates.ts
View File

@@ -1,6 +1,7 @@
import { and, eq } from 'drizzle-orm';
import { db } from '@/lib/db';
import { formatDate } from '@/lib/utils/format-date';
import { documentTemplates, documents, files } from '@/lib/db/schema/documents';
import type { File as DbFile, Document as DbDocument } from '@/lib/db/schema/documents';
import { clients, clientContacts } from '@/lib/db/schema/clients';
@@ -361,7 +362,7 @@ export async function resolveTemplate(
tokenMap['{{interest.stage}}'] = interest.pipelineStage ?? '';
tokenMap['{{interest.leadCategory}}'] = interest.leadCategory ?? '';
tokenMap['{{interest.dateFirstContact}}'] = interest.dateFirstContact
? new Date(interest.dateFirstContact).toLocaleDateString('en-GB')
? formatDate(interest.dateFirstContact, 'date.medium', { fallback: '' })
: '';
// `{{interest.notes}}` is now sourced from the threaded
// interest_notes timeline via EoiContext.interest.notes; this
@@ -372,10 +373,10 @@ export async function resolveTemplate(
// These are never populated by EoiContext - always fill them in.
tokenMap['{{interest.eoiStatus}}'] = interest.eoiStatus ?? '';
tokenMap['{{interest.dateEoiSigned}}'] = interest.dateEoiSigned
? new Date(interest.dateEoiSigned).toLocaleDateString('en-GB')
? formatDate(interest.dateEoiSigned, 'date.medium', { fallback: '' })
: '';
tokenMap['{{interest.dateContractSigned}}'] = interest.dateContractSigned
? new Date(interest.dateContractSigned).toLocaleDateString('en-GB')
? formatDate(interest.dateContractSigned, 'date.medium', { fallback: '' })
: '';
// Derive berth number from the interest when berthId wasn't passed and
// the EOI path didn't already populate it. Resolves through the

3
src/lib/services/expense-pdf.service.ts
View File

@@ -44,6 +44,7 @@ import { files } from '@/lib/db/schema/documents';
import { ports } from '@/lib/db/schema/ports';
import { getRate } from '@/lib/services/currency';
import { resolvePortLogo } from '@/lib/pdf/brand-kit/logo';
import { formatDate } from '@/lib/utils/format-date';
import { formatCurrency } from '@/lib/utils/currency';
import { getStorageBackend } from '@/lib/storage';
import { logger } from '@/lib/logger';
@@ -605,7 +606,7 @@ function addHeader(
// Move past the band and render the subheader below in black on white.
doc.y = bandHeight + 12;
const subheader = opts.subheader ?? `Generated on ${new Date().toLocaleDateString()}`;
const subheader = opts.subheader ?? `Generated on ${formatDate(new Date(), 'date.medium')}`;
doc.fontSize(11).font('Helvetica').fillColor('#666666').text(subheader, { align: 'center' });
doc.fillColor('#000000').moveDown(0.8);
// Suppress unused-warning on startY (kept as a documentation anchor).

177
src/lib/utils/format-date.ts Normal file
View File

@@ -0,0 +1,177 @@
/**
* Centralised date formatting helpers.
*
* Replaces ad-hoc `new Date(x).toLocaleDateString('en-GB')` calls
* scattered across services and components. Backed by `Intl.DateTimeFormat`
* which is built into Node 18+ and every supported browser — no extra
* dependency. Timezone-aware via the `tz` option (passes through to
* `Intl.DateTimeFormat`'s `timeZone` field — accepts any IANA name).
*
* Why a wrapper:
* 1. One place to fix locale, timezone, format presets when the
* product needs to change them.
* 2. Defensive: `new Date(null)` → "Invalid Date" — we return "—".
* 3. Defensive: numeric epochs vs string dates handled uniformly.
* 4. Default to en-GB so the audit-flagged inconsistency (some sites
* used en-US, some default-locale, some en-GB) is settled.
*
* Presets are named so call sites don't need to remember
* `Intl.DateTimeFormatOptions` shape — `formatDate(x, 'date.short')`
* instead of `formatDate(x, { day: '2-digit', month: 'short' })`.
*/
export type DatePreset =
| 'date.short' // 12 May
| 'date.medium' // 12 May 2026
| 'date.long' // Monday, 12 May 2026
| 'date.iso' // 2026-05-12
| 'datetime.short' // 12 May 14:30
| 'datetime.medium' // 12 May 2026 14:30
| 'datetime.long' // Monday, 12 May 2026 at 14:30 UTC
| 'datetime.iso' // 2026-05-12T14:30:00.000Z
| 'time'; // 14:30
const PRESET_OPTIONS: Record<
Exclude<DatePreset, 'date.iso' | 'datetime.iso'>,
Intl.DateTimeFormatOptions
> = {
'date.short': { day: '2-digit', month: 'short' },
'date.medium': { day: '2-digit', month: 'short', year: 'numeric' },
'date.long': { weekday: 'long', day: '2-digit', month: 'long', year: 'numeric' },
'datetime.short': {
day: '2-digit',
month: 'short',
hour: '2-digit',
minute: '2-digit',
hourCycle: 'h23',
},
'datetime.medium': {
day: '2-digit',
month: 'short',
year: 'numeric',
hour: '2-digit',
minute: '2-digit',
hourCycle: 'h23',
},
'datetime.long': {
weekday: 'long',
day: '2-digit',
month: 'long',
year: 'numeric',
hour: '2-digit',
minute: '2-digit',
hourCycle: 'h23',
timeZoneName: 'short',
},
time: { hour: '2-digit', minute: '2-digit', hourCycle: 'h23' },
};
const DEFAULT_LOCALE = 'en-GB';
const DEFAULT_FALLBACK = '—';
export interface FormatDateOptions {
/** IANA timezone — e.g. "Europe/London", "UTC". Defaults to the
* runtime's local zone (server: usually UTC; browser: user's TZ). */
tz?: string;
/** BCP-47 locale tag. Defaults to en-GB. */
locale?: string;
/** What to show when the input is null/undefined/Invalid Date. */
fallback?: string;
}
function toDate(value: Date | string | number | null | undefined): Date | null {
if (value === null || value === undefined) return null;
if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
const parsed = new Date(value);
return Number.isNaN(parsed.getTime()) ? null : parsed;
}
/**
* Format a Date / ISO string / epoch ms with one of the named presets.
* Defaults to `date.medium` (12 May 2026) in en-GB at the runtime's
* local zone. Pass `tz: 'UTC'` for stamps that should be tz-invariant.
*/
export function formatDate(
value: Date | string | number | null | undefined,
preset: DatePreset = 'date.medium',
options: FormatDateOptions = {},
): string {
const date = toDate(value);
if (!date) return options.fallback ?? DEFAULT_FALLBACK;
const locale = options.locale ?? DEFAULT_LOCALE;
if (preset === 'date.iso') {
if (options.tz && options.tz !== 'UTC') {
// For non-UTC ISO date we have to compute the date components in
// the target zone manually since toISOString is always UTC.
const parts = new Intl.DateTimeFormat('en-CA', {
year: 'numeric',
month: '2-digit',
day: '2-digit',
timeZone: options.tz,
}).formatToParts(date);
const y = parts.find((p) => p.type === 'year')?.value ?? '';
const m = parts.find((p) => p.type === 'month')?.value ?? '';
const d = parts.find((p) => p.type === 'day')?.value ?? '';
return `${y}-${m}-${d}`;
}
// Faster path for UTC / default.
return date.toISOString().slice(0, 10);
}
if (preset === 'datetime.iso') {
// ISO datetime is always UTC by definition.
return date.toISOString();
}
const intlOpts: Intl.DateTimeFormatOptions = { ...PRESET_OPTIONS[preset] };
if (options.tz) intlOpts.timeZone = options.tz;
return new Intl.DateTimeFormat(locale, intlOpts).format(date);
}
/**
* Format a [start, end] date range. Smartly collapses repeated components
* — e.g. same year shows "12 May → 14 Aug 2026" not "12 May 2026 → 14 Aug 2026".
*/
export function formatDateRange(
start: Date | string | number | null | undefined,
end: Date | string | number | null | undefined,
options: FormatDateOptions = {},
): string {
const s = toDate(start);
const e = toDate(end);
const fallback = options.fallback ?? DEFAULT_FALLBACK;
if (!s && !e) return fallback;
if (!s) return `→ ${formatDate(e, 'date.medium', options)}`;
if (!e) return `${formatDate(s, 'date.medium', options)} →`;
const sameYear = s.getUTCFullYear() === e.getUTCFullYear();
if (sameYear) {
return `${formatDate(s, 'date.short', options)} → ${formatDate(e, 'date.medium', options)}`;
}
return `${formatDate(s, 'date.medium', options)} → ${formatDate(e, 'date.medium', options)}`;
}
/**
* Format a duration relative to now — "2 hours ago", "in 3 days", etc.
* Uses `Intl.RelativeTimeFormat` for proper i18n; falls back to "just now"
* for very small deltas.
*/
export function formatRelative(
value: Date | string | number | null | undefined,
options: { locale?: string; now?: Date } = {},
): string {
const date = toDate(value);
if (!date) return DEFAULT_FALLBACK;
const now = options.now ?? new Date();
const diffSec = (date.getTime() - now.getTime()) / 1000;
const rtf = new Intl.RelativeTimeFormat(options.locale ?? DEFAULT_LOCALE, { numeric: 'auto' });
const abs = Math.abs(diffSec);
if (abs < 45) return 'just now';
if (abs < 90) return rtf.format(Math.round(diffSec / 60), 'minute');
if (abs < 3600) return rtf.format(Math.round(diffSec / 60), 'minute');
if (abs < 86400) return rtf.format(Math.round(diffSec / 3600), 'hour');
if (abs < 86400 * 30) return rtf.format(Math.round(diffSec / 86400), 'day');
if (abs < 86400 * 365) return rtf.format(Math.round(diffSec / (86400 * 30)), 'month');
return rtf.format(Math.round(diffSec / (86400 * 365)), 'year');
}