[Replacement]: timezone-support

[SantaClaas]

Package to replace

timezone-support

Suggested replacement(s)

timezone-support listTimeZones can be replaced by Intl.supportedValuesOf("timeZone")

Manifest type

native (replaceable by a built-in platform feature)

Rationale

listTimeZones is a utility that duplicates native functionality.
The package includes all time zone strings which increases the bundle size when this data is provided by browsers/runtime.
There are other APIs that can probably be replaced. Most of them by Temporal but from what I read you only want baseline widely available and Temporal isn't yet.

Availability

Baseline widely available

Node 18 (2022-04-19)
Chrome 99 (2022-03-01)
Firefox 93 (2021-10-05)
Safari 15.4 (2022-03-14)

According to MDN

Code example (optional)

// Before
const { listTimeZones } = require('timezone-support');
const timeZones = listTimeZones();
console.log(timeZones);

// After
const timeZones = Intl.supportedValuesOf("timeZone");
console.log(timeZones);

Intl and Temporal API Replacements for timezone-support

Examples and original API concepts adapted from the timezone-support API documentation.

---

convertDateToTime

Before

const { convertDateToTime } = require('timezone-support');

const date = new Date();
const localTime = convertDateToTime(date);
console.log(localTime);

After

const date = new Date();
const localTime = date.toTemporalInstant().toZonedDateTimeISO(Temporal.Now.timeZoneId());
console.log(localTime);

---

convertTimeToDate

Before

const { convertTimeToDate } = require('timezone-support');

const localTime = { 
  year: 2018, month: 9, day: 2, hours: 10, minutes: 0,
  zone: { abbreviation: 'CEST', offset: -120 } 
};
const date = convertTimeToDate(localTime);
console.log(date);

After

const zdt = Temporal.ZonedDateTime.from({
  timeZone: "Europe/Berlin",
  year: 2018,
  month: 9,
  day: 2,
  hour: 10,
  minute: 0,
  second: 0,
});

const date = new Date(zdt.epochMilliseconds);
console.log(date);

Caveats

• Does not natively support timezone abbreviations (e.g., CEST).

---

findTimeZone

Before

const { findTimeZone } = require('timezone-support');

const berlin = findTimeZone('Europe/Berlin');

After

const berlin = Intl.DateTimeFormat(undefined, { timeZone: 'Europe/Berlin' });

Caveats

• Does not support deprecated time zone names.
• There is no dedicated object to represent time zones; they are represented strictly as strings.

---

formatZonedTime

Before

const { formatZonedTime } = require('timezone-support/parse-format');

const time = { 
  year: 2018, month: 9, day: 2, hours: 10, minutes: 0,
  zone: { abbreviation: 'CEST', offset: -120 } 
};
const format = 'D.M.YYYY H:mm zZ';
const output = formatZonedTime(time, format);

After

const zdt = Temporal.ZonedDateTime.from({
  timeZone: "Europe/Berlin",
  year: 2018,
  month: 9,
  day: 2,
  hour: 10,
  minute: 0,
  second: 0,
});

// Use Intl.DateTimeFormat options for custom localization output
const output = new Intl.DateTimeFormat('de-DE', {
  dateStyle: 'medium',
  timeStyle: 'short',
  timeZone: zdt.timeZoneId
}).format(zdt);

Caveats

• Does not support manual/arbitrary format description strings (e.g., 'D.M.YYYY'). Use Intl.DateTimeFormat configurations instead.

---

getUnixTime

Before

const { findTimeZone, getUnixTime } = require('timezone-support');

const berlin = findTimeZone('Europe/Berlin');
const berlinTime = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0 };
const date = getUnixTime(berlinTime, berlin);
// Returns the UNIX timestamp (UTC) in milliseconds

After

const zdt = Temporal.ZonedDateTime.from({
  timeZone: "Europe/Berlin",
  year: 2018,
  month: 9,
  day: 2,
  hour: 10,
  minute: 0,
  second: 0,
});

const date = zdt.epochMilliseconds;

---

getUTCOffset

Before

const { findTimeZone, getUTCOffset } = require('timezone-support');

const berlin = findTimeZone('Europe/Berlin');
const date = new Date();
const timeZoneOffset = getUTCOffset(date, berlin);
// Returns { abbreviation: 'CET', offset: -60 }

After

const date = Temporal.Now.plainDateTimeISO().withTimeZone('Europe/Berlin');

// String representation (e.g., "+02:00")
const offsetString = date.offset;

// Numeric nanosecond difference
const offsetNano = date.offsetNanoseconds;

---

getZonedTime

Before

const { findTimeZone, getZonedTime } = require('timezone-support');

const berlin = findTimeZone('Europe/Berlin');
const date = new Date();
const time = getZonedTime(date, berlin);
// Returns { year, month, day, hours, minutes, seconds, milliseconds, dayOfWeek, epoch, zone: { abbreviation, offset } }

After

// Native Temporal ZonedDateTime object contains all equivalent fields
const time = Temporal.Now.zonedDateTimeISO('Europe/Berlin');

// Or instantiating directly from an existing Date object
const date = new Date();
const time2 = date.toTemporalInstant().toZonedDateTimeISO('Europe/Berlin');

---

listTimeZones

Before

const { listTimeZones } = require('timezone-support');

const timeZones = listTimeZones();
// Returns ['Africa/Abidjan', ...]

After

const timeZones = Intl.supportedValuesOf("timeZone");

---

parseZonedTime

Before

const { parseZonedTime } = require('timezone-support/parse-format');

const input = '2.9.2018 10:00 CEST+02:00';
const format = 'D.M.YYYY H:mm zZ';
const time = parseZonedTime(input, format);

After

// Requires standard ISO 8601 string formats with standard time zone extensions
const time = Temporal.ZonedDateTime.from(
  "2018-09-02T10:00:00+02:00[Europe/Berlin]",
);

Caveats

• Does not support arbitrary custom format strings.

---

setTimeZone

Before

const { findTimeZone, setTimeZone } = require('timezone-support');

const berlin = findTimeZone('Europe/Berlin');
const time = { year: 2018, month: 9, day: 2, hours: 10, minutes: 0 };
const berlinTime = setTimeZone(time, berlin);

After

const dt = Temporal.PlainDateTime.from({
  year: 2018,
  month: 9,
  day: 2,
  hour: 10,
  minute: 0,
  second: 0,
});

const berlinTime = dt.toZonedDateTime('Europe/Berlin');

[43081j]

what about the other exports timezone-support has? do they also have native equivalents?

we don't currently have a way to flag specific usages of a package, so we need to ensure the suggested replacements cover all common use cases

[SantaClaas]

@43081j The other exports can likely be replaced with Temporal. I will create a list and check if everything has a replacement or not

[SantaClaas]

@43081j I updated the description with all the replacements. They mostly rely on Temporal but I don't know if that is a good replacement yet due to availability of Temporal. What do you think?