temporal-spec

temporal-spec

TypeScript type definitions for Temporal, the successor to the JavaScript Date object.

This package ships only type declarations — no runtime code. It describes the shape of the Temporal API (plus the Temporal-related additions to Intl and Date) so that any Temporal implementation, polyfill, or application can share a single, accurate set of types.

Table of Contents

• Why This Exists
• Installation
• Entry Points
  • Namespaced (no global pollution)
  • Global
• What's Included
• TypeScript Version Notes
• For Polyfill Authors
• Provenance & License

Why This Exists

Temporal is a Stage 4 TC39 proposal that, until recently, no version of TypeScript shipped types for. Implementations each had to carry their own copy of the declarations, and they tended to drift apart.

temporal-spec centralizes those declarations into a standalone, dependency-free package. It's the type layer behind temporal-polyfill, and it's published separately so other Temporal implementations can reuse the exact same types.

Installation

npm install temporal-spec

Because it contains nothing but .d.ts files, it's a devDependency for most consumers.

Entry Points

There are two ways to pull in the types, depending on whether you want Temporal to be a global.

Namespaced (no global pollution)

Import the Temporal (and Intl) namespaces explicitly. This has no side effects — it does not touch the global TypeScript scope, so it's the right choice for libraries:

import type { Temporal } from 'temporal-spec'

function format(zdt: Temporal.ZonedDateTime): string {
  return zdt.toString()
}

Global

Import for its side effects to augment the global scope, making Temporal available everywhere without an explicit import (mirrors how the real API will behave once shipped):

import 'temporal-spec/global'

function format(zdt: Temporal.ZonedDateTime): string {
  return zdt.toString()
}

What's Included

Both entry points cover the full surface of the proposal:

• The Temporal namespace — Instant, ZonedDateTime, PlainDate, PlainTime, PlainDateTime, PlainYearMonth, PlainMonthDay, Duration, Now, and all of their supporting *Like / options types.
• Intl.DateTimeFormat augmentations, so format, formatToParts, formatRange, and formatRangeToParts accept Temporal objects.
• Date.prototype.toTemporalInstant (exposed as a standalone toTemporalInstant function from the namespaced entry point), for bridging legacy Date values into Temporal.

TypeScript Version Notes

TypeScript 6.0+ bundles Temporal types in its built-in lib files (esnext.temporal), so if you're on a recent TypeScript and only need the global types, you may not need this package at all — just enable the lib:

{
  "compilerOptions": {
+   "lib": ["esnext"]
  }
}

Or with more granularity:

{
  "compilerOptions": {
+   "lib": ["esnext.temporal", "esnext.intl", "esnext.date"]
  }
}

temporal-spec remains useful when you:

• are on TypeScript < 6.0, which has no built-in Temporal types
• want the namespaced (non-global) form, which lib does not provide
• are authoring a polyfill and want types decoupled from the consumer's TypeScript version

For Polyfill Authors

If you're building your own Temporal implementation, temporal-spec lets you type-check your output against the same declarations everyone else uses, instead of vendoring a copy that slowly drifts from the spec. Depend on it, point your public types at the Temporal namespace, and stay in sync as the proposal evolves.

Provenance & License

These declarations are derived from the TypeScript project's lib files (esnext.temporal.d.ts, esnext.intl.d.ts, and esnext.date.d.ts), which are Copyright (c) Microsoft Corporation.

Licensed under the Apache License, Version 2.0.