Time zones are the bug that keeps on giving.
Most JavaScript applications either ship a separate time-zone database to the browser or quietly get daylight saving time (DST) wrong twice a year.
While building TimeThen, a website of world clocks and time-zone tools, I ended up building a small engine that does neither.
It's now open source on npm as @timethen/time-engine.
npm install @timethen/time-engine What makes it interesting?
- 9 kB packed
- Zero runtime dependencies
- ESM support
- TypeScript declarations included
- No bundled time-zone database
- Uses the time-zone information exposed by the JavaScript runtime through
Intl - DST transition detection with minute-level precision
- DST-safe local-time-to-timestamp conversion
- Working-hours overlap calculations across multiple time zones
Let's look at how it works and why I built it.
The trick: let Intl do the heavy lifting
JavaScript's Intl.DateTimeFormat already provides access to IANA time-zone identifiers and the time-zone rules available in the underlying runtime.
That means you don't necessarily need to ship another time-zone database just to answer common questions.
However, Intl doesn't provide a convenient high-level API for many practical time-zone operations.
For example:
- What's the current UTC offset in Kolkata?
- When will New York clocks change next?
- What exact instant corresponds to 9:00 AM on Christmas Day in London?
- Is a particular location currently observing daylight saving time?
That's where @timethen/time-engine comes in.
It wraps these operations in a small collection of focused, tested functions.
import {
formatUtcOffset,
getOffsetMinutes,
getWallTime
} from '@timethen/time-engine';
const at = Date.UTC(2026, 10, 16, 15, 0);
// 16 November 2026, 15:00 UTC
formatUtcOffset(getOffsetMinutes('Asia/Kolkata', at));
// 'UTC+05:30'
getWallTime('America/New_York', at);
// {
// year: 2026,
// month: 11,
// day: 16,
// hour: 10,
// minute: 0,
// second: 0,
// weekday: 1
// } No manually maintained offset tables. No separate database download.
The runtime supplies the underlying time-zone information, while the engine handles the calculations.
One important detail: different runtimes and browser versions can contain different versions of time-zone data. The results therefore depend on the data available in the environment where the code runs.
Daylight saving time, down to the minute
DST transitions are one of the most frustrating parts of working with time zones.
A location might move its clocks forward in spring and backward in autumn. Other locations might not observe DST at all. Some governments even change their time-zone rules with relatively little notice.
The nextTransition function finds the next instant at which a time zone's UTC offset changes.
It samples the offset once per day and then uses binary search to narrow down the transition to minute-level precision.
This avoids maintaining a hard-coded transition table for every location.
import {
getDstStatus,
nextTransition
} from '@timethen/time-engine';
getDstStatus('Europe/London', at);
// {
// observesDst: true,
// isDstNow: false,
// standardOffset: 0,
// currentOffset: 0
// }
const next = nextTransition('America/New_York', at);
new Date(next.atMs).toISOString();
// '2027-03-14T07:00:00.000Z'
[next.fromOffset, next.toOffset];
// [-300, -240] In this example, New York moves from UTC-05:00 to UTC-04:00 when daylight saving time begins on 14 March 2027.
The distinction between minute-level precision and an exact transition instant matters, particularly when dealing with historical time-zone changes that may involve seconds.
Real-world time-zone changes
One of the biggest advantages of relying on runtime-provided time-zone data is that the engine can benefit from database updates without shipping its own separate database.
For example, the IANA Time Zone Database introduced several significant Canadian changes during 2026:
- 2026b: British Columbia moved towards permanent UTC-07:00.
- 2026c: Alberta adopted permanent UTC-06:00.
- 2026d: The Northwest Territories adopted permanent UTC-06:00.
- 2026e: Manitoba moved to permanent UTC-05:00.
The latest IANA release as of November 2026 is 2026f.
These changes demonstrate why time-zone handling should rely on maintained regional rules rather than assuming that offsets and DST schedules will remain unchanged.
You can see the results in action on TimeThen's Canadian daylight saving time pages.
The important caveat is that updating the library itself does not automatically update the runtime's time-zone database. Node.js, Deno, Bun and browsers depend on the time-zone data available in their respective environments.
Local time → instant, without the 2 AM bugs
Converting a local date and time into a Unix timestamp sounds straightforward.
Until daylight saving time gets involved.
1. A local time that doesn't exist
When clocks move forward, certain local times are skipped.
For example, if clocks jump from 01:59 to 03:00, 02:30 never happens.
2. A local time that happens twice
When clocks move backward, an hour is repeated.
That means a local time such as 01:30 can correspond to two different UTC instants.
Simply constructing a JavaScript Date doesn't give you a complete solution for these ambiguities.
That's why zonedTimeToEpoch provides an explicit disambiguation option.
It supports four modes:
-
'compatible'— the default, following Temporal's compatible disambiguation behaviour. -
'earlier'— chooses the earlier possible instant. -
'later'— chooses the later possible instant. -
'reject'— throws aLocalTimeErrorwhen the local time is ambiguous or nonexistent.
Here's a straightforward example:
import { zonedTimeToEpoch } from '@timethen/time-engine';
const timestamp = zonedTimeToEpoch(
'Europe/London',
{
year: 2026,
month: 12,
day: 25,
hour: 9
}
);
new Date(timestamp).toISOString();
// '2026-12-25T09:00:00.000Z' Because London observes UTC+00:00 in December, 9:00 AM local time corresponds to 09:00 UTC.
This is particularly useful for scheduling systems, booking applications, reminders and calendar integrations where the intended local time matters more than simply storing an offset.
When can two teams actually meet?
Time-zone conversion is one thing. Finding a suitable meeting window across multiple locations is another.
Imagine a team split between New York and London.
You want to find a time when both teams are within their working hours, without manually comparing clocks.
That's what findWorkingOverlap is designed to handle.
import {
describeDifference,
findWorkingOverlap,
offsetDifferenceMinutes
} from '@timethen/time-engine';
findWorkingOverlap(
['America/New_York', 'Europe/London'],
Date.UTC(2026, 10, 16),
24
);
// Example:
// [{ startMs: ..., endMs: ... }]
//
// 14:00–17:00 UTC
// 09:00–12:00 in New York
// 14:00–17:00 in London The example illustrates a three-hour overlap during the specified 24-hour search window.
You can also describe the time difference between two locations:
describeDifference(
offsetDifferenceMinutes(
'Asia/Tokyo',
'Europe/London',
at
)
);
// '9 hours behind' London is nine hours behind Tokyo at the specified instant.
These are the same kinds of calculations powering TimeThen's meeting planner and the Best Time to Call panel on its city pages.
What about Temporal?
Temporal is the long-term direction for date and time handling in JavaScript.
It provides a much more expressive API than the traditional Date object, including better ways to work with time zones, calendar dates, durations and ambiguous local times.
When Temporal is available in the runtimes you target, it's worth considering.
Until then, @timethen/time-engine serves as a small bridge.
It provides a focused set of functions without requiring a Temporal polyfill, while using the same 'compatible' disambiguation behaviour as its default.
The goal isn't to replace Temporal.
It's to solve practical time-zone problems today without making migration unnecessarily difficult later.
Try it yourself
The package is open source under the MIT licence.
Here are a few places to start:
-
npm:
@timethen/time-engine - Time Zone Converter: time zone converter
- Unix Timestamp Converter: Unix timestamp converter
- Daylight Saving Time: daylight saving time dates
- Meeting Planner: meeting planner
If you're working with JavaScript dates, scheduling, global applications or international teams, I'd be interested to hear what you think.
What time-zone bug has bitten you the hardest?
Was it a DST transition, a duplicated local time, a missed meeting, or an unexpected change in a country's time-zone rules?
I'd love to hear which edge cases you'd want covered next.
Top comments (0)