Instant, ZonedDateTime, or PlainDate?
Answer two quick questions about what you are modeling. Get the exact JavaScript Temporal type, the code to construct it, and the PostgreSQL column it maps to.
How the Temporal Type Picker works
- 1
Describe what you are representing
Pick one of three starting points: a specific point in time, a calendar date or time of day, or an amount of time (a duration). This first choice splits the six Temporal types into the right branch.
- 2
Answer one follow-up question
On the point-in-time path, the tool asks whether the timezone matters. On the calendar path, it asks which parts you need (date, date and time, or time only). Durations resolve immediately with no follow-up.
- 3
Read the recommended type and why
The result card names the exact Temporal type and explains in one or two sentences why it fits your case, including the DST or timezone reasoning where it matters.
- 4
Copy the constructor code
Every result includes a working code snippet showing how to build and use the type, with a one-click copy button. Paste it straight into your API code.
- 5
Check the storage mapping
Each result also shows the matching PostgreSQL column type and the JSON wire format, so you know how to persist the value and return it in a response.
- 6
Or browse all six at once
Prefer to scan the full set? The "Show all six types" view lists every Temporal type with a one-line use case and its database column, no questions required.
What each Temporal type means
Temporal.Instant
TIMESTAMPTZAn exact point in time in UTC, with no timezone or calendar attached. The default for created_at, updated_at, and any "when did this happen" field. Triggered when you pick a specific point in time and say the timezone does not matter.
Temporal.ZonedDateTime
TIMESTAMPTZ + TEXTAn Instant paired with a named IANA timezone, so it also knows the wall-clock time. Use it when DST behavior matters, like a recurring 9 AM local meeting. Triggered when you pick a specific point in time and say the timezone matters.
Temporal.PlainDate
DATEA calendar date with no time and no timezone. The same date everywhere in the world: birthdays, deadlines, holidays. Triggered on the calendar path when you need date only.
Temporal.PlainDateTime
TIMESTAMPA date and time with no timezone attached. Useful for a local appointment time captured before you know which zone applies. Triggered on the calendar path when you need date and time but no zone.
Temporal.PlainTime
TIMEA time of day with no date and no timezone, like a store opening time or a daily cutoff. Triggered on the calendar path when you need a time of day only.
Temporal.Duration
INTERVAL or INTEGERAn amount of time ("3 hours, 30 minutes"), a length rather than a point. Estimates, timeouts, video lengths. Triggered when you pick "an amount of time" as your first answer.
Constructor syntax reference
Temporal.Instant
Temporal.Now.instant();
Temporal.Instant.from('2026-06-15T14:30:00Z');Temporal.ZonedDateTime
Temporal.ZonedDateTime.from({
year: 2026, month: 6, day: 15, hour: 9,
timeZone: 'America/New_York',
});Temporal.PlainDate
Temporal.PlainDate.from('1990-06-15');Temporal.PlainDateTime
Temporal.PlainDateTime.from('2026-06-15T14:30');Temporal.PlainTime
Temporal.PlainTime.from('09:00');Temporal.Duration
Temporal.Duration.from({ hours: 3, minutes: 30 });When to use each type
| Scenario | Recommended type | Why |
|---|---|---|
| created_at / updated_at timestamp | Instant | An exact UTC moment, timezone irrelevant to storage |
| Recurring 9 AM local meeting | ZonedDateTime | Wall-clock time must survive DST shifts |
| User birthday | PlainDate | Same calendar date everywhere, no time or zone |
| Contract deadline / holiday | PlainDate | A date with no time of day attached |
| Local appointment before zone is known | PlainDateTime | Date and time captured, timezone applied later |
| Store opening time (09:00) | PlainTime | A time of day repeated across dates, no zone |
| Estimated task time / timeout | Duration | A length of time, not a point in time |
Frequently Asked Questions
What does the Temporal Type Picker do?
It maps a plain-English description of what you are modeling (a timestamp, a birthday, a recurring meeting, a duration) onto the correct JavaScript Temporal type. Instead of reading through the documentation for all six types and self-selecting, you answer at most two questions and get the exact type, a copy-paste constructor snippet, and the matching PostgreSQL column type.
What is the difference between Temporal.Instant and Temporal.ZonedDateTime?
An Instant is a bare point in time in UTC, with no timezone attached. Use it for created_at, updated_at, and event logs. A ZonedDateTime is an Instant paired with a named IANA timezone, so it also knows the wall-clock time in that zone.
The practical rule: if the timezone matters for how the value displays or recurs (a meeting that must stay at 9 AM local across DST changes), you need ZonedDateTime. If you only need the moment itself, use Instant.
How is this different from an ISO 8601 or Unix timestamp converter?
| ISO / Unix converters | Temporal Type Picker | |
|---|---|---|
| What it answers | Convert between string formats (Unix, RFC 2822, SQL) | Which conceptual Temporal type to use |
| Input | A date string or timestamp | A plain-English description of your field |
| Output | The same moment in another format | A Temporal type + constructor code + DB column |
Temporal's six types are a JavaScript-specific type system, not a string format. Generic converters do not address them at all.
Is my data sent to any server?
No. The Temporal Type Picker is a pure decision-tree tool that runs entirely in your browser. Your answers drive a static lookup table that returns the matching type and code. Nothing is typed, saved, or sent anywhere.
How do I store a ZonedDateTime in PostgreSQL?
Store the underlying Instant in a TIMESTAMPTZ column and the IANA zone name in a separate TEXT column, then reconstruct the ZonedDateTime on read. Do not try to keep the zone in the TIMESTAMPTZ column, PostgreSQL normalizes to UTC and discards it.
// write
await pool.query(
'INSERT INTO meetings (next_occurrence, timezone_name) VALUES ($1, $2)',
[zoned.toInstant().toString(), zoned.timeZoneId]
);
// read
const restored = Temporal.Instant.from(row.next_occurrence)
.toZonedDateTimeISO(row.timezone_name);When should I pick PlainDate over PlainDateTime?
Pick PlainDate when there is no time of day at all, a birthday, a deadline, a holiday, which is the same calendar date everywhere. Pick PlainDateTime when you have a date and a wall-clock time but no timezone yet, such as a local appointment captured before you know the user's zone. If neither fits cleanly, run the picker above and it will resolve the ambiguity in one question.