toZonedTime
Convert to a timezone-aware ZonedDateTime
Convert a UTC ISO string, Unix timestamp, Date, Instant, or ZonedDateTime to a ZonedDateTime in the specified timezone.
Signature
function toZonedTime(
input: string | number | Date | Temporal.Instant | Temporal.ZonedDateTime,
timezone: Timezone
): Temporal.ZonedDateTime
type Timezone = 'UTC' | string;Parameters
| Parameter | Type | Description |
|---|---|---|
input | string | number | Date | Temporal.Instant | Temporal.ZonedDateTime | A UTC ISO 8601 string, Unix timestamp (milliseconds), Date object, Temporal.Instant, or Temporal.ZonedDateTime |
timezone | Timezone | IANA timezone identifier (e.g., "America/New_York", "Europe/London") or "UTC" |
Returns
A Temporal.ZonedDateTime in the specified timezone.
Examples
Server-side: Convert to UTC
import { toZonedTime } from '@gobrand/tiempo';
const utcTime = toZonedTime("2025-01-20T20:00:00Z", "UTC");Server-side: Convert to user's timezone
import { toZonedTime } from '@gobrand/tiempo';
// Get timezone from user preferences (stored in DB)
const userTime = toZonedTime("2025-01-20T20:00:00Z", user.timezone);Client-side: Convert to browser's timezone
import { toZonedTime, browserTimezone } from '@gobrand/tiempo';
const localTime = toZonedTime("2025-01-20T20:00:00Z", browserTimezone());From Unix timestamp
// Common with database BIGINT timestamps or API responses
const timestamp = 1737403200000;
const zoned = toZonedTime(timestamp, "America/New_York");From Date (e.g., from Drizzle ORM)
const date = new Date("2025-01-20T20:00:00.000Z");
const zoned = toZonedTime(date, "America/New_York");From Instant
const instant = Temporal.Instant.from("2025-01-20T20:00:00Z");
const zoned = toZonedTime(instant, "Asia/Tokyo");From ZonedDateTime (convert to different timezone)
const nyTime = Temporal.ZonedDateTime.from("2025-01-20T15:00:00-05:00[America/New_York]");
const tokyoTime = toZonedTime(nyTime, "Asia/Tokyo");Common Patterns
ORM Integration
import { toZonedTime } from '@gobrand/tiempo';
// Reading: Convert database Date to user's timezone
const post = await db.query.posts.findFirst();
const localTime = toZonedTime(post.createdAt, userTimezone);