<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Ismail Ariffin</title>
    <description>The latest articles on DEV Community by Ismail Ariffin (@ismal).</description>
    <link>https://dev.to/ismal</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3481422%2F18607105-8fad-4b82-84ce-42167b0e1150.jpg</url>
      <title>DEV Community: Ismail Ariffin</title>
      <link>https://dev.to/ismal</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/ismal"/>
    <language>en</language>
    <item>
      <title>I Built a Tiny JavaScript Time Zone Engine - No Dependencies, No Bundled Time Zone Database</title>
      <dc:creator>Ismail Ariffin</dc:creator>
      <pubDate>Tue, 17 Nov 2026 09:00:04 +0000</pubDate>
      <link>https://dev.to/ismal/i-built-a-tiny-javascript-time-zone-engine-no-dependencies-no-bundled-time-zone-database-5a72</link>
      <guid>https://dev.to/ismal/i-built-a-tiny-javascript-time-zone-engine-no-dependencies-no-bundled-time-zone-database-5a72</guid>
      <description>&lt;p&gt; Time zones are the bug that keeps on giving. &lt;/p&gt; &lt;p&gt; Most JavaScript applications either ship a separate time-zone database to the browser or quietly get daylight saving time (DST) wrong twice a year. &lt;/p&gt; &lt;p&gt; While building &lt;a href="https://timethen.com/" rel="noopener noreferrer"&gt;TimeThen&lt;/a&gt;, a website of world clocks and time-zone tools, I ended up building a small engine that does neither. &lt;/p&gt; &lt;p&gt; It's now open source on npm as &lt;a href="https://www.npmjs.com/package/@timethen/time-engine" rel="noopener noreferrer"&gt;&lt;code&gt;@timethen/time-engine&lt;/code&gt;&lt;/a&gt;. &lt;/p&gt; &lt;pre&gt;&lt;code&gt;npm install @timethen/time-engine&lt;/code&gt;&lt;/pre&gt; &lt;h2&gt;What makes it interesting?&lt;/h2&gt; &lt;ul&gt; &lt;li&gt;&lt;strong&gt;9 kB packed&lt;/strong&gt;&lt;/li&gt; &lt;li&gt;&lt;strong&gt;Zero runtime dependencies&lt;/strong&gt;&lt;/li&gt; &lt;li&gt;ESM support&lt;/li&gt; &lt;li&gt;TypeScript declarations included&lt;/li&gt; &lt;li&gt;No bundled time-zone database&lt;/li&gt; &lt;li&gt;Uses the time-zone information exposed by the JavaScript runtime through &lt;code&gt;Intl&lt;/code&gt;
&lt;/li&gt; &lt;li&gt;DST transition detection with minute-level precision&lt;/li&gt; &lt;li&gt;DST-safe local-time-to-timestamp conversion&lt;/li&gt; &lt;li&gt;Working-hours overlap calculations across multiple time zones&lt;/li&gt; &lt;/ul&gt; &lt;p&gt;Let's look at how it works and why I built it.&lt;/p&gt; &lt;h2&gt;The trick: let &lt;code&gt;Intl&lt;/code&gt; do the heavy lifting&lt;/h2&gt; &lt;p&gt; JavaScript's &lt;code&gt;Intl.DateTimeFormat&lt;/code&gt; already provides access to IANA time-zone identifiers and the time-zone rules available in the underlying runtime. &lt;/p&gt; &lt;p&gt; That means you don't necessarily need to ship another time-zone database just to answer common questions. &lt;/p&gt; &lt;p&gt; However, &lt;code&gt;Intl&lt;/code&gt; doesn't provide a convenient high-level API for many practical time-zone operations. &lt;/p&gt; &lt;p&gt;For example:&lt;/p&gt; &lt;ul&gt; &lt;li&gt;What's the current UTC offset in Kolkata?&lt;/li&gt; &lt;li&gt;When will New York clocks change next?&lt;/li&gt; &lt;li&gt;What exact instant corresponds to 9:00 AM on Christmas Day in London?&lt;/li&gt; &lt;li&gt;Is a particular location currently observing daylight saving time?&lt;/li&gt; &lt;/ul&gt; &lt;p&gt; That's where &lt;code&gt;@timethen/time-engine&lt;/code&gt; comes in. &lt;/p&gt; &lt;p&gt; It wraps these operations in a small collection of focused, tested functions. &lt;/p&gt; &lt;pre&gt;&lt;code&gt;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
// }&lt;/code&gt;&lt;/pre&gt; &lt;p&gt; No manually maintained offset tables. No separate database download. &lt;/p&gt; &lt;p&gt; The runtime supplies the underlying time-zone information, while the engine handles the calculations. &lt;/p&gt; &lt;p&gt; 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. &lt;/p&gt; &lt;h2&gt;Daylight saving time, down to the minute&lt;/h2&gt; &lt;p&gt; DST transitions are one of the most frustrating parts of working with time zones. &lt;/p&gt; &lt;p&gt; 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. &lt;/p&gt; &lt;p&gt; The &lt;code&gt;nextTransition&lt;/code&gt; function finds the next instant at which a time zone's UTC offset changes. &lt;/p&gt; &lt;p&gt; It samples the offset once per day and then uses binary search to narrow down the transition to minute-level precision. &lt;/p&gt; &lt;p&gt; This avoids maintaining a hard-coded transition table for every location. &lt;/p&gt; &lt;pre&gt;&lt;code&gt;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]&lt;/code&gt;&lt;/pre&gt; &lt;p&gt; In this example, New York moves from UTC-05:00 to UTC-04:00 when daylight saving time begins on 14 March 2027. &lt;/p&gt; &lt;p&gt; The distinction between minute-level precision and an exact transition instant matters, particularly when dealing with historical time-zone changes that may involve seconds. &lt;/p&gt; &lt;h3&gt;Real-world time-zone changes&lt;/h3&gt; &lt;p&gt; 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. &lt;/p&gt; &lt;p&gt; For example, the IANA Time Zone Database introduced several significant Canadian changes during 2026: &lt;/p&gt; &lt;ul&gt; &lt;li&gt;
&lt;strong&gt;2026b:&lt;/strong&gt; British Columbia moved towards permanent UTC-07:00.&lt;/li&gt; &lt;li&gt;
&lt;strong&gt;2026c:&lt;/strong&gt; Alberta adopted permanent UTC-06:00.&lt;/li&gt; &lt;li&gt;
&lt;strong&gt;2026d:&lt;/strong&gt; The Northwest Territories adopted permanent UTC-06:00.&lt;/li&gt; &lt;li&gt;
&lt;strong&gt;2026e:&lt;/strong&gt; Manitoba moved to permanent UTC-05:00.&lt;/li&gt; &lt;/ul&gt; &lt;p&gt; The latest IANA release as of November 2026 is 2026f. &lt;/p&gt; &lt;p&gt; These changes demonstrate why time-zone handling should rely on maintained regional rules rather than assuming that offsets and DST schedules will remain unchanged. &lt;/p&gt; &lt;p&gt; You can see the results in action on TimeThen's &lt;a href="https://timethen.com/daylight-saving-time/canada/" rel="noopener noreferrer"&gt;Canadian daylight saving time pages&lt;/a&gt;. &lt;/p&gt; &lt;p&gt; 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. &lt;/p&gt; &lt;h2&gt;Local time → instant, without the 2 AM bugs&lt;/h2&gt; &lt;p&gt; Converting a local date and time into a Unix timestamp sounds straightforward. &lt;/p&gt; &lt;p&gt;Until daylight saving time gets involved.&lt;/p&gt; &lt;p&gt;&lt;strong&gt;1. A local time that doesn't exist&lt;/strong&gt;&lt;/p&gt; &lt;p&gt; When clocks move forward, certain local times are skipped. &lt;/p&gt; &lt;p&gt; For example, if clocks jump from 01:59 to 03:00, 02:30 never happens. &lt;/p&gt; &lt;p&gt;&lt;strong&gt;2. A local time that happens twice&lt;/strong&gt;&lt;/p&gt; &lt;p&gt; When clocks move backward, an hour is repeated. &lt;/p&gt; &lt;p&gt; That means a local time such as 01:30 can correspond to two different UTC instants. &lt;/p&gt; &lt;p&gt; Simply constructing a JavaScript &lt;code&gt;Date&lt;/code&gt; doesn't give you a complete solution for these ambiguities. &lt;/p&gt; &lt;p&gt; That's why &lt;code&gt;zonedTimeToEpoch&lt;/code&gt; provides an explicit disambiguation option. &lt;/p&gt; &lt;p&gt;It supports four modes:&lt;/p&gt; &lt;ul&gt; &lt;li&gt;
&lt;code&gt;'compatible'&lt;/code&gt; — the default, following Temporal's compatible disambiguation behaviour.&lt;/li&gt; &lt;li&gt;
&lt;code&gt;'earlier'&lt;/code&gt; — chooses the earlier possible instant.&lt;/li&gt; &lt;li&gt;
&lt;code&gt;'later'&lt;/code&gt; — chooses the later possible instant.&lt;/li&gt; &lt;li&gt;
&lt;code&gt;'reject'&lt;/code&gt; — throws a &lt;code&gt;LocalTimeError&lt;/code&gt; when the local time is ambiguous or nonexistent.&lt;/li&gt; &lt;/ul&gt; &lt;p&gt;Here's a straightforward example:&lt;/p&gt; &lt;pre&gt;&lt;code&gt;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'&lt;/code&gt;&lt;/pre&gt; &lt;p&gt; Because London observes UTC+00:00 in December, 9:00 AM local time corresponds to 09:00 UTC. &lt;/p&gt; &lt;p&gt; 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. &lt;/p&gt; &lt;h2&gt;When can two teams actually meet?&lt;/h2&gt; &lt;p&gt; Time-zone conversion is one thing. Finding a suitable meeting window across multiple locations is another. &lt;/p&gt; &lt;p&gt; Imagine a team split between New York and London. &lt;/p&gt; &lt;p&gt; You want to find a time when both teams are within their working hours, without manually comparing clocks. &lt;/p&gt; &lt;p&gt; That's what &lt;code&gt;findWorkingOverlap&lt;/code&gt; is designed to handle. &lt;/p&gt; &lt;pre&gt;&lt;code&gt;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&lt;/code&gt;&lt;/pre&gt; &lt;p&gt; The example illustrates a three-hour overlap during the specified 24-hour search window. &lt;/p&gt; &lt;p&gt; You can also describe the time difference between two locations: &lt;/p&gt; &lt;pre&gt;&lt;code&gt;describeDifference(
  offsetDifferenceMinutes(
    'Asia/Tokyo',
    'Europe/London',
    at
  )
);

// '9 hours behind'&lt;/code&gt;&lt;/pre&gt; &lt;p&gt; London is nine hours behind Tokyo at the specified instant. &lt;/p&gt; &lt;p&gt; These are the same kinds of calculations powering TimeThen's &lt;a href="https://timethen.com/meeting-planner/" rel="noopener noreferrer"&gt;meeting planner&lt;/a&gt; and the &lt;strong&gt;Best Time to Call&lt;/strong&gt; panel on its city pages. &lt;/p&gt; &lt;h2&gt;What about Temporal?&lt;/h2&gt; &lt;p&gt; &lt;code&gt;Temporal&lt;/code&gt; is the long-term direction for date and time handling in JavaScript. &lt;/p&gt; &lt;p&gt; It provides a much more expressive API than the traditional &lt;code&gt;Date&lt;/code&gt; object, including better ways to work with time zones, calendar dates, durations and ambiguous local times. &lt;/p&gt; &lt;p&gt; When Temporal is available in the runtimes you target, it's worth considering. &lt;/p&gt; &lt;p&gt; Until then, &lt;code&gt;@timethen/time-engine&lt;/code&gt; serves as a small bridge. &lt;/p&gt; &lt;p&gt; It provides a focused set of functions without requiring a Temporal polyfill, while using the same &lt;code&gt;'compatible'&lt;/code&gt; disambiguation behaviour as its default. &lt;/p&gt; &lt;p&gt; The goal isn't to replace Temporal. &lt;/p&gt; &lt;p&gt; It's to solve practical time-zone problems today without making migration unnecessarily difficult later. &lt;/p&gt; &lt;h2&gt;Try it yourself&lt;/h2&gt; &lt;p&gt; The package is open source under the MIT licence. &lt;/p&gt; &lt;p&gt;Here are a few places to start:&lt;/p&gt; &lt;ul&gt; &lt;li&gt;
&lt;strong&gt;npm:&lt;/strong&gt; &lt;a href="https://www.npmjs.com/package/@timethen/time-engine" rel="noopener noreferrer"&gt;&lt;code&gt;@timethen/time-engine&lt;/code&gt;&lt;/a&gt;
&lt;/li&gt; &lt;li&gt;
&lt;strong&gt;Time Zone Converter:&lt;/strong&gt; &lt;a href="https://timethen.com/converter/" rel="noopener noreferrer"&gt;time zone converter&lt;/a&gt;
&lt;/li&gt; &lt;li&gt;
&lt;strong&gt;Unix Timestamp Converter:&lt;/strong&gt; &lt;a href="https://timethen.com/unix-timestamp-converter/" rel="noopener noreferrer"&gt;Unix timestamp converter&lt;/a&gt;
&lt;/li&gt; &lt;li&gt;
&lt;strong&gt;Daylight Saving Time:&lt;/strong&gt; &lt;a href="https://timethen.com/daylight-saving-time/" rel="noopener noreferrer"&gt;daylight saving time dates&lt;/a&gt;
&lt;/li&gt; &lt;li&gt;
&lt;strong&gt;Meeting Planner:&lt;/strong&gt; &lt;a href="https://timethen.com/meeting-planner/" rel="noopener noreferrer"&gt;meeting planner&lt;/a&gt;
&lt;/li&gt; &lt;/ul&gt; &lt;p&gt; If you're working with JavaScript dates, scheduling, global applications or international teams, I'd be interested to hear what you think. &lt;/p&gt; &lt;h2&gt;What time-zone bug has bitten you the hardest?&lt;/h2&gt; &lt;p&gt; Was it a DST transition, a duplicated local time, a missed meeting, or an unexpected change in a country's time-zone rules? &lt;/p&gt; &lt;p&gt; I'd love to hear which edge cases you'd want covered next. &lt;/p&gt; 

</description>
      <category>javascript</category>
      <category>typescript</category>
      <category>opensource</category>
    </item>
  </channel>
</rss>
