@col/format

Versie: 1.0.0 Toegevoegd: 2026-08-06

Herkomst

Vier apps schreven elk hun eigen Nederlandse formattering. growerportal2/src/lib/format.ts is de meest complete: formatCurrency, formatCurrencyDetailed, formatNumber, formatPrice, formatDate, formatTime, formatFileSize — 283 aanroepen over 37 bestanden. floriday api/src/features/supply-search/format.ts is kleiner maar het meest doordacht: gepind op nl-NL en UTC, met een bewust behandeld negatief getal en een bewust behandelde onherkende valutacode. supplier-onboarding-vercel/src/lib/i18n.ts formatteert datum/tijd per taal via een Language → locale-mapping (nl, en, es, it). voorraadbeheer heeft geen gedeeld bestand: formatCurrency- en toLocaleDateString-aanroepen staan letterlijk gekopieerd op zes of meer pagina's, met een eigen localeMap per aanroepplek.

Dit item combineert de vier: de functieset van growerportal2, de edge-case-discipline van floriday, en de eis van supplier-onboarding/voorraadbeheer dat de locale een parameter is, geen aanname.

Waarvoor

Vijf pure functies voor het formatteren van een datum, tijd, getal, bedrag of bestandsgrootte naar een leesbare string — geen state, geen React, geen Intl-kennis nodig bij de aanroeper. Pak dit voor elke plek waar een Date, number of bytes-aantal aan een gebruiker getoond wordt. Gebruik het niet voor parsen (invoervelden, formuliervalidatie) — dit item gaat één kant op, waarde naar weergavestring.

Wat je app moet leveren

Niets — geen props, geen backend-contract. Vijf functies, direct importeren en aanroepen:

import { formatDate, formatTime, formatNumber, formatCurrency, formatFileSize } from '@/lib/format'

formatDate(new Date())                              // "06-08-2026"
formatDate(request.createdAt, { locale: 'en-GB' })   // "06/08/2026"
formatDate(auctionDate, { timeZone: 'UTC' })         // pin op UTC voor een tijdzone-loze datum

formatTime(new Date())                               // "14:05"

formatNumber(1234567.891)                            // "1.234.567,891"
formatNumber(count, { maximumFractionDigits: 0 })     // "1.235"

formatCurrency(1234.5)                                // "€ 1.234,50" (NBSP na €)
formatCurrency(total, { decimals: false })            // "€ 1.235"
formatCurrency(stukprijs, { decimals: 3 })            // "€ 1,500" — exact aantal decimalen
formatCurrency(amount, { locale: 'en-US', currency: 'USD' })

formatFileSize(file.size)                             // "2.4 MB"

function formatDate(value: Date | string, options?: Intl.DateTimeFormatOptions & { locale?: string }): string
function formatTime(value: Date | string, options?: Intl.DateTimeFormatOptions & { locale?: string }): string
function formatNumber(value: number, options?: Intl.NumberFormatOptions & { locale?: string }): string
function formatCurrency(value: number, options?: { locale?: string; currency?: string; decimals?: boolean | number }): string
function formatFileSize(bytes: number): string

formatDate/formatTime accepteren zowel een Date als een ISO-string, zodat een waarde rechtstreeks uit een API-response (JSON kent geen Date-type) zonder tussenstap geformatteerd kan worden.

Bestanden

Geen registryDependencies, geen cssVars. Eén bestand, geen dependencies.

Gebruikt door

growerportal2 (283 aanroepen, 37 bestanden), floriday-middleware, supplier-onboarding-vercel en voorraadbeheer hebben elk hun eigen versie — dat is precies waar dit item uit samengesteld is (zie Herkomst). Wie een migratie oppakt: doe dat als eigen taak, niet als bijvangst (zie docs/specs/2026-08-06-v10-basisitems.md, Risico's) — growerportal2 alleen al is een grote zoek-en-vervang. Voeg hier een regel toe zodra een app is overgezet.

Bewuste keuzes

• Locale als parameter op elke functie, geen module-brede standaard. growerportal2 en floriday zijn allebei Nederlandstalige apps en pinnen nl-NL hardcoded; supplier-onboarding- vercel heeft vier talen (NL/EN/ES/IT) en voorraadbeheer heeft een eigen localeMap per taal. Een module-brede standaard zou de twee laatste apps dwingen om na elke --overwrite een eigen wrapper eromheen te blijven onderhouden. nl-NL blijft wel de default-waarde — drie van de vier bronapps zijn Nederlandstalig — maar altijd overschrijfbaar per aanroep.
• Geen standaard tijdzone. floriday-middleware pint formatDate bewust op UTC, voor determinisme in een feature die met tijdzone-loze synchronisatiedata werkt (auctionDate is een database-datum zonder tijdzone). De andere drie apps volgen de tijdzone van de browser of het Node-proces. UTC als standaard zetten zou die drie apps tijden een uur naast de werkelijkheid laten tonen zonder dat iemand het merkt — een stille regressie die pas opvalt bij een klacht over een verkeerde tijd. In plaats daarvan gaat options.timeZone ongewijzigd door naar Intl.DateTimeFormat/Intl.NumberFormat (impliciet via de spread), zodat floriday zelf { timeZone: 'UTC' } meegeeft en de rest niets hoeft te doen. Getest in tests/format.test.ts: één test bewijst dat een expliciete timeZone het resultaat verandert (Tokio vs. UTC voor hetzelfde tijdstip), een tweede zet process.env.TZ op een tijdzone ver van UTC (Pacific/Kiritimati, UTC+14) en bewijst dat formatDate zónder timeZone-optie exact hetzelfde teruggeeft als een rechtstreekse Intl-aanroep zonder tijdzone — een regressie naar een hardcoded UTC-standaard zou die test laten falen.
• formatFileSize is binair (1024), niet decimaal (1000). growerportal2's origineel gebruikt al 1024 met de labels "B"/"KB"/"MB"/"GB" — dezelfde conventie als een Windows- of macOS-bestandenoverzicht, ook al is dat strikt genomen niet de SI-betekenis van "kilo". Dat is bewust aangehouden: een bestandsgrootte in deze apps komt altijd van een OS- of browser-bestandskiezer, en die tonen zelf ook 1024-gebaseerde groottes. Andere labels gebruiken (KiB/MiB, de correcte binaire notatie) zouden een leesbaarheidswinst voor niemand opleveren en een breuk zijn met wat gebruikers al gewend zijn.
• formatCurrency's decimals is boolean | number, geen vrij minimumFractionDigits. growerportal2 heeft drie aparte functies voor bedragen: formatCurrency (0 decimalen, 18 aanroepen), formatCurrencyDetailed (2 decimalen, 56 aanroepen — de meerderheid) en formatPrice (3 decimalen, voor een stuksprijs, 18 aanroepen). true/weglaten en false dekken de eerste twee — true (2 decimalen) is de standaard, omdat die in de brondata het vaakst voorkomt en overeenkomt met hoe voorraadbeheer en floriday hun Intl-aanroep ongewijzigd laten (Intl's eigen standaard voor EUR is 2 decimalen). Voor de derde — formatPrice's 3 decimalen — accepteert decimals ook een getal, dat rechtstreeks als minimumFractionDigits en maximumFractionDigits dient. Het alternatief (formatNumber met een handmatig voorgeplakt valutateken) zou precies weggooien waar formatCurrency voor bestaat: de automatische symboolplaatsing en de locale-correcte spatiëring (de NBSP bij nl-NL), en de overdraagbaarheid naar een andere valuta of locale zonder de aanroeper daarover te laten nadenken.
• Onherkende valutacode gooit geen fout. Intl.NumberFormat gooit een RangeError op een ongeldige ISO-4217-code. floriday's formatPrice ving dat al af (de valutacode in hun feed komt soms rechtstreeks uit externe data). Dat gedrag is overgenomen: formatCurrency valt terug op "<bedrag> <code>" met toFixed, in plaats van de rij (of pagina) die deze functie aanroept mee te trekken in een crash.
• Negatieve getallen worden niet gedressed als positief. floriday's formatInteger- documentatie noemt expliciet dat de brondata (numberOfPieces) legitiem negatief kan zijn — 349 rijen, tot -98.200, vermoedelijk correcties in de Floriday-feed. formatNumber en formatCurrency doen niets bijzonders met een negatief getal; Intl toont het teken gewoon. Een Math.abs zou dat stilzwijgend verkeerd voorstellen.
• formatDate/formatTime accepteren Date | string, niet alleen Date. growerportal2 en supplier-onboarding-vercel doen dat al (new Date(date) binnen de functie); dat scheelt de aanroeper een handmatige conversie bij elke API-response, waar een datum als ISO-string uit JSON komt.

Bekende beperkingen

• De standaard datumvorm wijkt af van wat sommige apps nu tonen. formatDate's standaard is dd-mm-jjjj met voorloopnullen (06-08-2026) — growerportal2's vorm. supplier-onboarding-vercel roept nu toLocaleDateString(locale) aan zonder opties, wat in nl-NL geen voorloopnullen geeft (5-1-2026); floriday gebruikt { month: 'short' } (6 aug 2026). Beide zijn bij migratie bereikbaar via options, maar wie formatDate zonder opties aanroept in een van die twee apps ziet zijn datums stilzwijgend van vorm veranderen ten opzichte van wat er nu staat.
• Geen valuta-symbool-positie-controle. Intl bepaalt zelf of het symbool voor of na het bedrag komt, en met welk scheidingsteken (inclusief de NBSP die nl-NL gebruikt tussen € en het bedrag). Dat is bewust Intl's beslissing, niet dit item — een test die een string vergelijkt met een handmatig getypte spatie in plaats van een NBSP faalt op een manier die in de diff niet van een gewone spatie te onderscheiden is. tests/format.test.ts gebruikt daarom een NBSP-constante in plaats van een letterlijke spatie in de verwachte string.
• Intl-uitvoer is niet gegarandeerd stabiel tussen Node-versies. De exacte tekens (spatie- variant, wel of geen punt achter een verkorte maandnaam) komen uit de ICU-data die met de gebruikte Node-versie is meegeleverd. Dit item is getest tegen de ICU-data van de Node-versie in deze repo (node -v bij het schrijven: v24) — een consumerende app op een andere Node-versie kan een net iets andere string krijgen voor dezelfde aanroep. Voor de vijf functies hier (datum/tijd/getal/bedrag/bestandsgrootte) is dat verschil altijd cosmetisch (spatie-teken, wel/geen punt), nooit functioneel.
• Geen relatieve tijd ("3 uur geleden", "gisteren"). Geen van de vier bronapps had dat nodig; Intl.RelativeTimeFormat is een aparte API met een eigen vormvrijheid en hoort, als de behoefte ontstaat, in een eigen functie of eigen item.