denoland / denoland/std

proposal: deprecate @std/datetime in favor of Temporal

Open
#7,262 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
3.6k
Forks
681
PR merge metrics
No merged PRs in 30d

Description

Temporal is stable as of Deno 2.7, so I propose we deprecate `@std/datetime`. This was already the stated plan in #4804: "It is likely that most of `datetime` APIs will be deprecated after Temporal is available." That condition is now met.

## Why now

- Deno 2.7 (February 2026) shipped Temporal unflagged, following Chrome 144.
- `@std/datetime` is unstable at 0.225.7, so deprecation carries no semver cost.
- The package has 60 dependents on JSR. The earlier we point them at Temporal, the fewer migrations we cause later.

## What Temporal replaces

| `@std/datetime` export | Replacement |
| --- | --- |
| `dayOfYear` | `Temporal.PlainDate.prototype.dayOfYear` |
| `isLeap` | `Temporal.PlainDate.prototype.inLeapYear` |
| `weekOfYear` | `Temporal.PlainDate.prototype.weekOfYear` |
| `difference` | `Temporal.PlainDate.prototype.since` / `until` |
| `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK` | `Temporal.Duration` |
| `format` | `Intl.DateTimeFormat` / `toLocaleString` (see below) |
| `parse` | `Temporal.PlainDate.from` for ISO strings (see below) |

## The one gap: custom format strings

`format` and `parse` accept format strings like `"yyyy-MM-dd"`. Temporal has no equivalent: it parses ISO 8601 only, and formatting goes through `Intl.DateTimeFormat`. I still propose deprecating both, pointing `format` users at `Intl` and `parse` users at ISO strings or a userland library. Keeping a two-function package alive doesn't seem worth the maintenance. If maintainers would rather keep them, the rest of this proposal works unchanged.

## Plan

1. Settle scope in this issue: whole package, or keep `format`/`parse`.
2. PR: add `@deprecated` JSDoc tags to every affected export, each naming its Temporal replacement, plus a before/after migration example per symbol so it shows up in the JSR docs.
3. PR: update the module doc to state the package is deprecated and link this issue.
4. Release as 0.226.0 so dependents see the tags in their editors.
5. Remove the package in a later release, following whatever grace period the earlier package removals used.

I'm happy to send the PRs for steps 2 and 3 once scope is settled.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.