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);

On this page