Iso
toISOString
Converts a timestamp (milliseconds since epoch) to an ISO-8601 string without constructing a JavaScript
Date
object. Fast and allocation-free.
reference/iso/toISOString.ts
import { toISOString } from "datezone";
// Current timestamp
const now = Date.now();
// Example: Convert timestamps to ISO strings in different timezones
console.log("Converting timestamps to ISO strings:");
// UTC timezone
console.log(`UTC: ${toISOString(now, "UTC")}`);
// America/New_York (EST/EDT)
console.log(`Eastern: ${toISOString(now, "America/New_York")}`);
// Asia/Tokyo (JST)
console.log(`Tokyo: ${toISOString(now, "Asia/Tokyo")}`);
// Europe/London (GMT/BST)
console.log(`London: ${toISOString(now, "Europe/London")}`);
// Local timezone (system timezone)
console.log(`Local: ${toISOString(now, null)}`);
// Historical date during daylight saving time
const summer = new Date("2023-07-15T12:00:00Z").getTime();
console.log(`\nSummer (DST): ${toISOString(summer, "America/New_York")}`);
// Historical date during standard time
const winter = new Date("2023-01-15T12:00:00Z").getTime();
console.log(`Winter (EST): ${toISOString(winter, "America/New_York")}`);
// Note about fixed offset timezones
console.log(
"\nNote: Fixed offset strings like '+05:30' are supported at runtime",
);
console.log("but not included in the TypeZone type for strict typing.");
fromISOString
Parses an ISO-8601 string into a UTC timestamp (milliseconds since epoch). Significantly faster than
Date.parse()
and works the same in every runtime.
reference/iso/fromISOString.ts
import { fromISOString } from "datezone";
// Parse different ISO string formats
console.log("Parsing various ISO string formats:");
// UTC timezone (with Z)
const utcString = "2023-12-25T15:30:45.123Z";
const utcTimestamp = fromISOString(utcString);
console.log(`UTC: ${utcString} → ${utcTimestamp}`);
// With timezone offset
const offsetString = "2023-12-25T15:30:45.123+05:30";
const offsetTimestamp = fromISOString(offsetString);
console.log(`With offset: ${offsetString} → ${offsetTimestamp}`);
// Local time (no timezone)
const localString = "2023-12-25T15:30:45.123";
const localTimestamp = fromISOString(localString);
console.log(`Local: ${localString} → ${localTimestamp}`);
// Without milliseconds
const noMsString = "2023-12-25T15:30:45-08:00";
const noMsTimestamp = fromISOString(noMsString);
console.log(`No ms: ${noMsString} → ${noMsTimestamp}`);
parseISO
Parses an ISO 8601 is a compability shortcut for fromISOString
to be consistent with other date libraries.
reference/iso/parseISO.ts
// Example usage of the 'parseISO' export from datezone
import { parseISO } from "datezone";
const isoString = "2024-06-01T12:34:56Z";
const date = parseISO(isoString);
console.log("Parsed timestamp:", date);