Choosing Between Host Timezone Database and Embedded IANA Database for Consistent ClojureScript Date Conversion

Host versus embedded IANA timezone database for ClojureScript date conversion

When compiling ClojureScript to JavaScript, achieving portable, timezone-aware date conversion requires choosing how zone information is resolved at runtime. The host js/Date API defers to the browser or Node.js timezone database, which varies across versions and builds. The cljs-time wrapper and similar libraries let developers specify IANA zone strings, but must decide between embedding a static IANA bundle or trusting the host data.

Likely explanation

Modern mainstream browsers and current Node.js releases ship with the full ICU library, which includes the IANA timezone database. Using Intl.DateTimeFormat with the timeZone option yields consistent offsets for dates near the present, across runs on the same host type. Divergence appears on older runtimes, Node builds compiled with small-icu, or when evaluating dates far in the future or after recent legislative DST changes. Embedding a static IANA database (e.g., via a bundled tzdata package or a library like js-joda with its timezone data) freezes the rule set at build time, guaranteeing identical offsets on any JavaScript runtime, including embedded or exotic environments, but adds tens to hundreds of kilobytes to the bundle and requires redeployment when governments update DST rules.

Confirmed facts

• js/Date has no native IANA zone support; zone-aware conversion in JavaScript depends on the host Intl API or a library carrying its own tzdata.
• Modern browsers and Node.js ship full ICU with the IANA database, so Intl-based conversion is consistent for current dates across mainstream hosts.
• Embedding tzdata guarantees identical offsets everywhere, including exotic/embedded runtimes, at the cost of bundle size that depends on how many zones are included.
• A bundled database freezes DST rules at build time; rule changes by governments require a rebuild and redeploy to remain correct.
• Runtime performance differences are small for typical conversion volumes; Intl calls cross into the engine and are slightly slower per call than pure table lookups, but this rarely matters outside tight loops.
• For JVM/JS sharing, the practical pattern is to define a platform-agnostic abstraction (protocol or cljc namespace) mapping to java.time.ZonedDateTime on the JVM and to one chosen JS strategy, keeping instants as epoch-millis at the boundaries.

Steps for this case

1. Identify the target runtimes: browser, Node.js version, embedded JS, and JVM.
2. For mainstream browser and current Node.js, use the host Intl.DateTimeFormat with the desired IANA zone string; verify with a test instant spanning a DST transition.
3. If the Node.js build may use small-icu or the code must run on embedded/older runtimes, evaluate the gzipped bundle size increase from embedding a tzdata package and confirm the update-frequency trade-off.
4. Define a platform-agnostic abstraction (protocol/cljc) that maps to java.time.ZonedDateTime on the JVM and to the chosen JS strategy (Intl vs bundled) on JavaScript, normalizing to epoch-millis at the boundaries.
5. Run the verification checks before locking in the strategy.

Missing diagnostic detail

Does the deployment environment include a Node.js or JavaScript runtime built with small-icu, or is the target exclusively modern browsers and full-ICU Node builds? Answering this will determine whether embedding a static IANA database is necessary or if the host Intl API suffices.

Quick verification

node -e 'console.log(Intl.DateTimeFormat().resolvedOptions().timeZone)'

Confirm the output matches your target zone; repeat on Node builds you suspect may use small-icu.