Validate DateTime object instants before construction

[fubhy]

Summary

DateTime.make returns Some for NaN and out-of-range object instants, and makeUnsafe can construct unusable values.

Important

This PR starts with focused failing reproduction tests. Add the implementation fix to this same branch; CI is expected to fail until that fix is included.

Object instants bypass validity and range checks

Module: DateTime
Audit ID: core-a-f-datetime-object-instant-validation
Severity / confidence: medium / high

What happens

DateTime.make returns Some for NaN and out-of-range object instants, and makeUnsafe can construct unusable values.

Why it happens

The object-instant branch calls makeUtc(input.epochMilliseconds) directly, unlike number and Date inputs that pass through JavaScript Date validation.

Expected behavior

{ epochMilliseconds: number } is supported, DateTime.make returns None when construction would produce an invalid date-time, and makeUnsafe rejects construction failures.

Relevant implementation

These links and excerpts are pinned to audit base c9b56ab507f224426ee8388dc450da447ec4715f.

• packages/effect/src/internal/dateTime.ts:217-225
• packages/effect/src/internal/dateTime.ts:296-297
• packages/effect/src/DateTime.ts:224-233
• packages/effect/src/DateTime.ts:742-755

View problematic code at packages/effect/src/internal/dateTime.ts:217-225

export const makeUnsafe = <A extends DateTime.DateTime.Input>(input: A): DateTime.DateTime.PreserveZone<A> => {
  if (isDateTime(input)) {
    return input as DateTime.DateTime.PreserveZone<A>
  } else if (input instanceof Date) {
    return fromDateUnsafe(input) as DateTime.DateTime.PreserveZone<A>
  } else if (typeof input === "object") {
    if ("epochMilliseconds" in input) {
      return makeUtc(input.epochMilliseconds) as DateTime.DateTime.PreserveZone<A>
    }

View exact lines on GitHub

View problematic code at packages/effect/src/internal/dateTime.ts:296-297

export const make: <A extends DateTime.DateTime.Input>(input: A) => Option.Option<DateTime.DateTime.PreserveZone<A>> =
  Option.liftThrowable(makeUnsafe)

View exact lines on GitHub

View problematic code at packages/effect/src/DateTime.ts:224-233

  /**
   * Object input representing an absolute instant as milliseconds since the Unix
   * epoch.
   *
   * @category models
   * @since 4.0.0
   */
  export interface Instant {
    readonly epochMilliseconds: number
  }

View exact lines on GitHub

View problematic code at packages/effect/src/DateTime.ts:742-755

/**
 * Creates a `DateTime` safely from supported input values.
 *
 * **Details**
 *
 * - A `DateTime`
 * - A JavaScript `Date`
 * - The number of milliseconds since the Unix epoch
 * - An object with date and time parts
 * - A string that can be parsed as a date
 *
 * Returns `Some` with the constructed `DateTime` when the input is valid, or
 * `None` when construction would fail, including invalid `Date` instances or
 * unparseable strings.

View exact lines on GitHub

Reproduction

pnpm test --run packages/effect/test/DateTimeInstantValidation.test.ts

Observed failure: A direct Node 24 source probe returned Some for both NaN and out-of-range object instants.

Implementation handoff

The initial reproduction tests on this branch are the regression specification for the implementation fix that should follow in this PR.

1. Start with the pinned implementation excerpts and the Why it happens analysis above.
2. Change the implementation so it satisfies the stated Expected behavior; do not weaken or remove the reproduction assertions.
3. Run the focused reproduction command(s) and confirm the observed failures become passing tests:

pnpm test --run packages/effect/test/DateTimeInstantValidation.test.ts

4. Run the affected package's existing tests, then the repository lint and type checks before requesting review.

Audit provenance

• Audit base: c9b56ab507f224426ee8388dc450da447ec4715f
• Reproduction base: c9b56ab507f224426ee8388dc450da447ec4715f
• Findings: core-a-f-datetime-object-instant-validation
• Initial patch: focused reproduction tests; implementation fix pending

[changeset-bot]

⚠️ No Changeset found

Latest commit: 603c65c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pullfrog]

ℹ️ Minor suggestions only — the regression test is focused and correct, but it should also cover DateTime.makeUnsafe so the implementation fix cannot miss that path.

Reviewed changes

Reviewed the initial failing regression test added to packages/effect/test/DateTimeInstantValidation.test.ts; the implementation fix described in the PR is not present yet on the reviewed commit.

• Adds a focused regression test that DateTime.make({ epochMilliseconds: NaN }) and DateTime.make({ epochMilliseconds: 8_640_000_000_000_001 }) both return None.
• The assertion values match JavaScript Date validation behavior (new Date(8640000000000001).getTime() is NaN), confirming the object-instant branch is the one missing validation.

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

The PR description also says makeUnsafe can construct unusable values. Consider adding assertions for DateTime.makeUnsafe({ epochMilliseconds: NaN }) and DateTime.makeUnsafe({ epochMilliseconds: 8_640_000_000_000_001 }) throwing, so the implementation fix covers both APIs.