feat: Add temporal support by DecimalTurn · Pull Request #230 · DecimalTurn/toml-patch

DecimalTurn · 2026-06-20T04:46:53Z

This pull request introduces support for the (new) JavaScript Temporal API.

The implementation is opt-in via a new temporal option.

Temporal API Integration:

Added a new temporal: boolean option to ParseOptions, allowing TOML date/time values to be parsed as Temporal objects when enabled.
Implemented duck-typed detection of Temporal objects in utility functions, ensuring robust handling across different JS realms.
Updated parsing and serialization logic to convert between TOML date/time types and their corresponding Temporal types, both when reading TOML and when stringifying JS objects.

Copilot

Pull request overview

Adds opt-in support for parsing TOML date/time values into JavaScript Temporal objects, and extends stringify/patch logic to accept Temporal inputs while keeping existing Date-subclass behavior as the default for backward compatibility.

Changes:

Introduces ParseOptions.temporal and threads it through parse() / TomlDocument / toJS() so TOML date/time nodes can return Temporal objects.
Adds Temporal duck-typing utilities plus Temporal-aware diffing/patching/stringification paths.
Adds Temporal-focused documentation and a new Jest test suite (with polyfill).

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
`src/utils.ts`	Adds Temporal detection + Temporal-aware equality/stable stringification helpers.
`src/toml-document.ts`	Stores and applies the new `temporal` parse option when producing JS objects.
`src/to-js.ts`	Threads `temporal` option and converts TOML custom Date subclasses into Temporal values when enabled.
`src/temporal-global.d.ts`	Adds a minimal Temporal typing shim (currently as a global declaration).
`src/patch.ts`	Auto-detects Temporal in `updated`, threads temporal mode through `toJS`, and preserves Temporal date/time serialization.
`src/parse-options.ts`	Documents and adds the new `temporal?: boolean` option.
`src/parse-js.ts`	Detects Temporal inputs during stringify and routes them through Temporal-aware CST generation.
`src/index.ts`	Documents and forwards `options.temporal` through `parse()`.
`src/generate.ts`	Adds `generateTemporalDateTime()` to serialize Temporal objects to TOML date/time nodes.
`src/__tests__/temporal.test.ts`	Adds Temporal integration tests using `@js-temporal/polyfill`.
`README.md`	Documents default Date-subclass behavior vs opt-in Temporal behavior + examples.
`package.json` / `pnpm-lock.yaml`	Adds `@js-temporal/polyfill` dev dependency for tests.
`CHANGELOG.md`	Notes Temporal support additions.
`PLAN-temporal.md`	Adds implementation plan/notes for Temporal support.
`.github/workflows/test-and-build.yml`	Expands CI Node matrix to include Node 26.x.
`.github/workflows/node-engine-check.yml`	Updates engine check job to Node 26.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

socket-security · 2026-06-21T06:54:09Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@js-temporal/polyfill@0.5.1

View full report

@js-temporal/polyfill does not provide getISOFields; only native Temporal implementations do. Keep the equals check which exists on both.

ZonedDateTime.toString() includes IANA annotations that TOML strips, causing spurious diffs. Use temporalToTomlString for consistency.

TOML only supports offset timezones. ZonedDateTime with IANA annotations now throws a clear error. Offset timezones are still accepted. Fixed dateValueToTemporal to use +00:00 instead of UTC.

temporalToTomlString always emits T, but the existing TOML may use a space separator. Re-apply the separator from existing.raw.

…ralDateTime Centralizes TOML validation (bracket rejection, Z normalization) through temporalToTomlString instead of raw toString().

Temporarily remove globalThis.Temporal to verify the runtime guard throws a clear error.

Copilot

Pull request overview

Copilot reviewed 16 out of 18 changed files in this pull request and generated 10 comments.

Files not reviewed (1)

pnpm-lock.yaml: Generated file

+  if (value instanceof LocalDateTime) {
+    return T.PlainDateTime.from(value.toISOString());
+  }


+  if (value instanceof OffsetDateTime) {
+    const iso = value.toISOString();
+    // Extract offset: e.g. "2024-01-15T10:30:00+05:30" or "2024-01-15T10:30:00Z"
+    const offsetMatch = iso.match(/([+-]\d{2}:\d{2}|Z)$/);
+    const offset = offsetMatch ? offsetMatch[1] : 'Z';
+    // Strip offset suffix to get the plain datetime
+    const plainIso = iso.replace(/([+-]\d{2}:\d{2}|Z)$/, '');
+    // ZonedDateTime.from requires a timezone. Use the offset itself so the
+    // resulting object has an offset timezone (not IANA), which TOML can represent.
+    const tz = offset === 'Z' ? '+00:00' : offset;
+    return T.ZonedDateTime.from(`${plainIso}${offset}[${tz}]`);
+  }


+    if (truncateZeroTimeInDates) {
+      const T = (globalThis as any).Temporal;
+      const plainDate = T.PlainDate.from(value.toString().split('T')[0]);
+      if (plainDate.toString() + 'T00:00:00' === value.toString().slice(0, 19)) {


+    // Normalize +00:00 to Z
+    return full.replace(/\[.*\]$/, '').replace('+00:00', 'Z');
+  }


+
+  return value.toString();
+}


+stringify({
+  start: Temporal.PlainDate.from('2024-01-15'),
+  due: Temporal.ZonedDateTime.from('2024-12-31T23:59:59Z[UTC]')
+});
+// start = 2024-01-15
+// due = 2024-12-31T23:59:59Z
+
+patch('d = 2024-01-15\n', {
+  d: Temporal.PlainDateTime.from('2025-06-01T12:00:00')
+});
+// d = 2025-06-01T12:00:00
+```
+
+> **Note:** TOML only supports timezone offsets (`+05:30`, `Z`), not IANA timezone names. When a `Temporal.ZonedDateTime` with an IANA annotation (e.g. `[Asia/Kolkata]`) is serialized, only the offset portion is kept.
+


+### Added
+
+- Parsing: New `temporal` option in `ParseOptions`. When `true`, TOML date/time values are returned as [Temporal](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Temporal) objects (`Temporal.PlainDate`, `Temporal.PlainTime`, `Temporal.PlainDateTime`, `Temporal.ZonedDateTime`) instead of custom `Date` subclasses.
+- Stringify: Auto-detect Temporal objects in the input JS and serialize them to the correct TOML date/time type. `ZonedDateTime` IANA annotations are stripped (TOML only supports offsets).


+   * The Temporal API must be available in the runtime (it is Stage 4
+   * and shipping in modern browsers and Node.js).
+   *


+1. **`temporal` is opt-in (default `false`).** This avoids a breaking change. In a future major version it could become opt-out or the default once Temporal reaches Baseline.
+2. **Temporal detection in serialize path is automatic.** If a user has a Temporal object in their JS, we want it to serialize correctly without extra configuration.
+3. **Duck-typing for Temporal detection** rather than `instanceof` checks, because Temporal objects may come from different realms (e.g., iframes, vm contexts).
+4. **For `ZonedDateTime` with IANA timezone**, we strip the IANA annotation and keep only the offset in TOML output. TOML does not support IANA timezone names.


+ * Uses @js-temporal/polyfill because Node.js 24 does not yet ship
+ * Temporal natively (Stage 4 spec, expected in a future release).
+ * The polyfill is set on globalThis so the library code can access it
+ * the same way it would access the native Temporal global.


…cies

LocalDateTime and OffsetDateTime toISOString() return a space separator when the original TOML used one. Temporal.from() requires T.

…cate branch

… on all Temporal types

DecimalTurn added 6 commits June 19, 2026 21:43

docs: planning temporal support

88181c9

test: add temporal tests

5f9a7dc

feat: add temporal support

d72546d

test: add temporal tests with roundtrip and fixture validations

f39dab3

docs: update README and CHANGELOG

8186963

ci: update to include Node v26

3dd0597

DecimalTurn changed the title ~~feat: Add temporal support and related tests~~ feat: Add temporal support Jun 20, 2026

DecimalTurn added 2 commits June 20, 2026 01:30

style: linting

686f288

force checks

7bfc287

DecimalTurn requested a review from Copilot June 20, 2026 07:40

Copilot started reviewing on behalf of DecimalTurn June 20, 2026 07:41 View session

Copilot AI reviewed Jun 20, 2026

View reviewed changes

Comment thread src/utils.ts

Comment thread src/utils.ts

Comment thread src/patch.ts

Comment thread src/utils.ts

Comment thread src/__tests__/temporal.test.ts

Comment thread src/generate.ts Outdated

Comment thread src/generate.ts Outdated

Comment thread src/generate.ts Outdated

DecimalTurn added 3 commits June 20, 2026 12:46

refactor: use internal config object for parsing

dc5a34e

docs: update

d924831

fix: improve isTemporal function to check for Temporal API methods

ea016c0

DecimalTurn added 7 commits June 21, 2026 03:01

test: add failing test for ZonedDateTime IANA annotation mismatch

2d08e6b

fix: remove getISOFields from isTemporal — not available on polyfill

f9e9a93

@js-temporal/polyfill does not provide getISOFields; only native Temporal implementations do. Keep the equals check which exists on both.

fix: use temporalToTomlString in datesEqual and stableStringify

542eec9

ZonedDateTime.toString() includes IANA annotations that TOML strips, causing spurious diffs. Use temporalToTomlString for consistency.

fix: reject IANA timezones, error instead of silently stripping

f3d76d5

TOML only supports offset timezones. ZonedDateTime with IANA annotations now throws a clear error. Offset timezones are still accepted. Fixed dateValueToTemporal to use +00:00 instead of UTC.

fix: preserve space separator when patching with Temporal

5aa5797

temporalToTomlString always emits T, but the existing TOML may use a space separator. Re-apply the separator from existing.raw.

fix: use temporalToTomlString for all Temporal types in generateTempo…

cbcc3cf

…ralDateTime Centralizes TOML validation (bracket rejection, Z normalization) through temporalToTomlString instead of raw toString().

test: replace placeholder with real error-path test

04c5d97

Temporarily remove globalThis.Temporal to verify the runtime guard throws a clear error.

DecimalTurn requested a review from Copilot June 22, 2026 02:05

Copilot started reviewing on behalf of DecimalTurn June 22, 2026 02:06 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

DecimalTurn added 4 commits June 21, 2026 22:25

chore(renovate): enforce commitMessageTopic for non-major devDependen…

89a0fa3

…cies

fix: normalize space separator to T before passing to Temporal.from()

785e150

LocalDateTime and OffsetDateTime toISOString() return a space separator when the original TOML used one. Temporal.from() requires T.

fix: add Temporal availability guard in generateTemporalDateTime trun…

4b34da1

…cate branch

fix: anchor +00:00->Z replacement to offset suffix, validate brackets…

111cc25

… on all Temporal types

test: add space-separated offset datetime roundtrip

dac598d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add temporal support#230

feat: Add temporal support#230
DecimalTurn wants to merge 23 commits into
latestfrom
dev-temporal

DecimalTurn commented Jun 20, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

socket-security Bot commented Jun 21, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

DecimalTurn commented Jun 20, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

socket-security Bot commented Jun 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

socket-security Bot commented Jun 21, 2026 •

edited

Loading