prefer-temporal-conversion.md

prefer-temporal-conversion

📝 Prefer direct Temporal conversion methods.

💼 This rule is enabled in the following configs: ✅ recommended, ☑️ unopinionated.

🔧💡 This rule is automatically fixable by the --fix CLI option and manually fixable by editor suggestions.

Temporal conversion methods convert directly between Temporal types. They avoid indirect static conversions and manual reconstruction from fields or serialized strings, removing boilerplate and preserving information that reconstruction can lose, such as submillisecond precision and calendars.

Examples

const zoned = Temporal.ZonedDateTime.from('2024-01-02T03:04:05.123456789+00:00[UTC]');

// ❌
Temporal.Instant.from(zoned);
Temporal.Instant.fromEpochMilliseconds(zoned.epochMilliseconds);
Temporal.Instant.fromEpochNanoseconds(zoned.epochNanoseconds);
Temporal.PlainDate.from(zoned.toString());
new Temporal.PlainDate(zoned.year, zoned.month, zoned.day);

// ✅
zoned.toInstant();
zoned.toPlainDate();

const dateTime = Temporal.PlainDateTime.from('2024-01-02T03:04:05.123456789');

// ❌
Temporal.PlainDate.from(dateTime);
Temporal.PlainDate.from({year: dateTime.year, month: dateTime.month, day: dateTime.day});
Temporal.PlainTime.from(dateTime.toJSON());

// ✅
dateTime.toPlainDate();
dateTime.toPlainTime();

Supported conversions

Source	Target	Method
Temporal.ZonedDateTime	Temporal.Instant	.toInstant()
Temporal.ZonedDateTime	Temporal.PlainDateTime	.toPlainDateTime()
Temporal.ZonedDateTime or Temporal.PlainDateTime	Temporal.PlainDate	.toPlainDate()
Temporal.ZonedDateTime or Temporal.PlainDateTime	Temporal.PlainTime	.toPlainTime()

The rule checks direct one-argument .from(source) conversions, epoch milliseconds and nanoseconds, .from(source.toString()), .from(source.toJSON()), and constructors or property bags copying all fields of the target type. Time reconstructions must include all six time fields, through nanosecond. Date property bags can use month or monthCode, and can include calendar: source.calendarId.

TypeScript assertions, satisfies, and non-null assertions around conversion inputs are supported.

Sources must be identifiable from canonical Temporal.* constructors, .from() factories, Temporal.Now.zonedDateTimeISO(), Temporal.Now.plainDateTimeISO(), constant bindings, or explicit TypeScript types. TypeScript type information is used when available. Polyfill imports work when the local binding remains named Temporal, for example import {Temporal} from '@js-temporal/polyfill'. Renamed imports are not tracked. Unknown receivers and ordinary data objects are ignored.

The rule does not check partial or modified fields, extra properties, mixed receivers, spreads, optional chaining, computed names, parsing or serialization options, calendar arguments or properties other than source.calendarId, same-type cloning, string manipulation, Date interoperability, or conversions requiring extra arguments or intermediate types. It does not infer arbitrary method chains.

Fixes and suggestions

Exact conversions are automatically fixable: direct one-argument conversions, nanosecond-based instant reconstruction, serialization into plain types, complete time-field reconstruction, and date-bearing property bags explicitly retaining the source calendar.

The following receive editor suggestions because replacing them can change the result:

• Millisecond-based instant reconstruction discards submillisecond precision.
• Serialization into an instant can lose seconds because ZonedDateTime serialization rounds historical timezone offsets to minutes.
• Date-bearing property bags without a calendar default to ISO 8601.
• Date-bearing constructors interpret their numeric arguments as ISO fields, even when a calendar is supplied.

Use an explicit rounding operation when discarding precision is intentional. Fixes and suggestions are withheld when they would remove comments.