Skip to content

fix: make TemporalValue self-contained#49

Merged
wellwelwel merged 2 commits into
mysqljs:mainfrom
pdeveltere:fix/temporal-types-no-global-ns
Jul 12, 2026
Merged

fix: make TemporalValue self-contained#49
wellwelwel merged 2 commits into
mysqljs:mainfrom
pdeveltere:fix/temporal-types-no-global-ns

Conversation

@pdeveltere

Copy link
Copy Markdown
Contributor

Problem

The published lib/types.d.ts references the global Temporal.* namespace:

export type TemporalValue =
  | Temporal.Instant
  | Temporal.ZonedDateTime
  | ...

That only resolves if the consumer's tsconfig includes the ESNext.Temporal lib, which exists only in TypeScript 7. Every consumer on TypeScript < 7 (the vast majority today) gets:

error TS2503: Cannot find namespace 'Temporal'.

This surfaced when mysql2 bumped its direct dependency to sql-escaper@1.5.0 — its tsc build now fails (sidorares/node-mysql2#4216, PR sidorares/node-mysql2#4392).

Fix

Type TemporalValue structurally, branded on Symbol.toStringTag — the same signal the runtime isTemporal check already uses:

export type TemporalValue = {
  readonly [Symbol.toStringTag]: `Temporal.${string}`;
  readonly epochMilliseconds?: number;
  toString(): string;
};
  • No dependency on the global Temporal namespace → resolves on any TypeScript version, no lib or polyfill types needed downstream.
  • Any real Temporal value (Instant, PlainDate, PlainTime, Duration, …) still assigns — verified against @js-temporal/polyfill.
  • temporalToString's guard switched from 'epochMilliseconds' in value to typeof value.epochMilliseconds === 'number' (equivalent at runtime, narrows the optional cleanly).
  • Dropped ESNext.Temporal from the build lib since nothing references the global anymore.

Existing tests (incl. temporal.test.ts) pass; build and lint are green.

…pace

The emitted types.d.ts referenced `Temporal.*` bare, so consumers whose
tsconfig lacks the `ESNext.Temporal` lib (all of TypeScript < 7) failed with
`TS2503: Cannot find namespace 'Temporal'` — e.g. mysql2's typecheck after
bumping to sql-escaper 1.5.0 (sidorares/node-mysql2#4216).

Type TemporalValue structurally, branded on Symbol.toStringTag to match the
runtime isTemporal check. Real Temporal values still assign; no global
namespace, no ESNext.Temporal lib required downstream.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@codecov-commenter

codecov-commenter commented Jul 12, 2026

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (479d3a5) to head (b07f328).
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files
@@            Coverage Diff            @@
##              main       #49   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            1         1           
  Lines          561       561           
  Branches       170       170           
=========================================
  Hits           561       561           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment thread src/types.ts Outdated
@wellwelwel wellwelwel changed the title fix: make TemporalValue self-contained, not the global Temporal namespace fix: make TemporalValue self-contained Jul 12, 2026
@wellwelwel wellwelwel changed the title fix: make TemporalValue self-contained fix: make TemporalValue self-contained Jul 12, 2026
@wellwelwel
wellwelwel merged commit f655fe1 into mysqljs:main Jul 12, 2026
11 checks passed
pdeveltere added a commit to pdeveltere/node-mysql2 that referenced this pull request Jul 12, 2026
sql-escaper v1.5.x adds Temporal API support (Temporal.Instant,
PlainDate, PlainTime, PlainDateTime, ZonedDateTime) when escaping
values. Bumping the direct dependency ensures existing installations
pick up the support on `npm update` rather than only on fresh installs.

1.5.1 is required: 1.5.0's emitted types referenced the global Temporal
namespace, breaking `tsc` for consumers without the ESNext.Temporal lib
(fixed in mysqljs/sql-escaper#49).

Refs sidorares#4216

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
wellwelwel pushed a commit to sidorares/node-mysql2 that referenced this pull request Jul 13, 2026
sql-escaper v1.5.x adds Temporal API support (Temporal.Instant,
PlainDate, PlainTime, PlainDateTime, ZonedDateTime) when escaping
values. Bumping the direct dependency ensures existing installations
pick up the support on `npm update` rather than only on fresh installs.

1.5.1 is required: 1.5.0's emitted types referenced the global Temporal
namespace, breaking `tsc` for consumers without the ESNext.Temporal lib
(fixed in mysqljs/sql-escaper#49).

Refs #4216

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants