temporal-polyfill

The tree-shakeable API includes several non-standard functions that do not have a direct Temporal.* counterpart. These are categorized into three groups:

1. Narrowed forms of standard methods: Functions like addDays (which is a restricted version of .add({ days })) or toBasicString (a restricted .toString()). These allow bundlers to use simpler, cheaper internal paths.
2. Gaps the standard API doesn't fill: Operations missing from the Temporal spec, such as startOfYear on a ZonedDateTime, endOfMonth on a PlainDate, or roundToWeek.
3. Compressed multi-step operations: Helpers that perform complex logic in one call, such as diffYears(a, b), which returns a floating-point total.

Migration Path: When you transition to native Temporal using temporal-polyfill-codemod, standard functions map to native methods, while non-standard functions map to the temporal-utils package, which provides the same semantics for real Temporal objects.

The fns-to-temporal transform converts several patterns from the temporal-polyfill/fns API to standard Temporal syntax:

Constructors and Methods

Function calls are converted into constructors or instance methods:

// Before
import * as PlainDateFns from 'temporal-polyfill/fns/PlainDate'
const date = PlainDateFns.create(2024, 5, 1)
const next = PlainDateFns.addDays(date, 3)

// After
const date = new Temporal.PlainDate(2024, 5, 1)
const next = date.add({ days: 3 })

Calendar Records to IDs

Calendar record objects are converted to string IDs where Temporal expects a string:

// Before
PlainDateFns.create(2024, 5, 1, CalendarFns.getBuddhist())
// After
new Temporal.PlainDate(2024, 5, 1, 'buddhist')

Types and Type Guards

• Types: Record and option types are rewritten to their Temporal equivalents (e.g., PlainDateRecord becomes Temporal.PlainDate). If no direct equivalent exists, it falls back to temporal-utils.
• Type Guards: isRecord checks are converted to instanceof checks:

// Before
if (PlainDateFns.isRecord(value)) { /* ... */ }
// After
if (value instanceof Temporal.PlainDate) { /* ... */ }

Note on temporal-utils

If a function has no direct Temporal equivalent, the codemod rewrites it to use temporal-utils. The codemod will print a note for you to add this dependency to your package.json, but it will not edit your package.json automatically.

The goal of the fns-to-temporal codemod is to replace tree-shakeable API records (which are incompatible with real Temporal objects) with direct calls to the global Temporal object.

Transformation Strategy

• Direct Rewrites: Simple, semantically equivalent calls are rewritten directly to the global Temporal API (e.g., Temporal.PlainDate.from()).
• temporal-utils fallback: If a helper has no direct Temporal equivalent or if the arguments cannot be statically normalized (e.g., they are not object/string literals), the codemod rewrites the call to use temporal-utils.
• Unsafe Cases: If the codemod cannot prove a usage is safe to rewrite, it leaves the code unchanged and emits a diagnostic. Examples of unsafe cases include:
  • Assigning a function to a variable: const fn = PlainDateFns.addDays
  • Dynamic property access: PlainDateFns[name](date, 3)
  • Destructuring: const { create } = PlainDateFns
  • Passing functions as predicates: values.filter(PlainDateFns.isRecord)

Important: Manual Step for temporal-utils

If the codemod introduces imports from temporal-utils, you must manually install the package in your affected project(s). The codemod will print a summary notification if this occurs.

The tree-shakeable API operates on a Record object rather than a class instance. This object represents a PlainDateTime and contains the following properties:

• calendarId: string
• era: string | undefined
• eraYear: number | undefined
• year: number
• month: number
• monthCode: string
• day: number
• hour: number
• minute: number
• second: number
• millisecond: number
• microsecond: number
• nanosecond: number
• toJSON(): returns a string
• valueOf(): returns never

type Record = {
  readonly calendarId: string
  readonly era: string | undefined
  readonly eraYear: number | undefined
  readonly year: number
  readonly month: number
  readonly monthCode: string
  readonly day: number
  readonly hour: number
  readonly minute: number
  readonly second: number
  readonly millisecond: number
  readonly microsecond: number
  readonly nanosecond: number
  toJSON(): string
  valueOf(): never
}

temporal-utils provides rounding helpers to return the closest start of a named calendar unit. These are useful because native Temporal .round() APIs do not cover every large calendar unit (like years or months) in a uniform way across all date-like types.

Usage Guidelines:

• Default Mode: If options or options.roundingMode is omitted, it defaults to 'halfExpand'.
• Shorthand: You can pass a RoundingMode string directly as a shorthand for { roundingMode }.
• Constraints: RoundingMathOptions must not include smallestUnit (the helper name defines the unit). For year, month, and week helpers, roundingIncrement must be omitted or set to 1.

Recommended vs. Codemod Helpers

• Use these for manual code: roundToYear, roundToMonth, and roundToWeek.
• Avoid these in manual code: roundToDay, roundToHour, roundToMinute, roundToSecond, roundToMillisecond, and roundToMicrosecond. These are exported primarily as codemod targets. For these units, use the native Temporal .round() method instead.

import { roundToMonth, roundToWeek, roundToYear } from 'temporal-utils'

const dateTime = Temporal.PlainDateTime.from('2024-07-20T12:30:00')

roundToYear(dateTime).toString()
// '2025-01-01T00:00:00'

roundToMonth(dateTime, 'floor').toString()
// '2024-07-01T00:00:00'

roundToWeek(dateTime, { roundingMode: 'floor' }).toString()
// '2024-07-15T00:00:00'