Strict ISO 8601 (RFC 3339) Date Regex

This repository contains a fully validated strict ISO 8601 (RFC 3339) datetime regular expression and a comprehensive test suite written with Node’s built-in node:test module. It ensures that timestamps strictly follow ISO 8601 formatting and RFC 3339 strictness with full calendar correctness, including leap-year validation, month-day ranges, and time zone offsets.

Why

1. After compilation, RegExp are fast and reliable
2. Gregorian DateTime logic does not change — it is essentially static
3. Because Date does not validate it semantically (eg. calendar correctness)

new Date('2025-11-31T00:00:00Z')
// 2025-12-01T00:00:00.000Z

In this example, passing November 31st will convert to 1st of December, which can lead to VERY nasty bugs and exploits in some contexts (eg. money, enforcing contract dates, etc).

Usage

Test for strict RFC 3339 correctness

import { ISO8601Date } from 'iso-8601-regex';

ISO8601Date.test('2025-11-02T00:00:00.000Z'); // true — within boundaries
ISO8601Date.test('2025-11-31T00:00:00.000Z'); // false — only 30 days in November

ISO8601Date.test('2024-02-29T00:00:00.000Z'); // true — 2024 was a leap year
ISO8601Date.test('2025-02-29T00:00:00.000Z'); // false — not a leap year

When you get as input any ISO 8601 string, just use this to check its correctness.

if (!ISO8601Date.test(request.startDate)) {
  throw new Error('Invalid ISO 8601 DateString');
}

// safe startDate without temperings
const startDate = new Date(request.startDate);

Using group captured values

This regex provides named capturing groups for every major datetime component. You can use RegExp.prototype.exec() (or .match() with the d flag in future ECMAScript versions) to access them directly.

import { ISO8601Date } from 'iso-8601-regex';

const match = ISO8601Date.exec('2025-11-02T10:20:30.123+09:30');

if (match) {
  const g = match.groups;
  console.log(g);
  /*
  {
    year: '2025',
    month: '11',
    day: '02',
    hour: '10',
    minute: '20',
    second: '30',
    millisecond: '123',
    timezone: '+09:30'
  }
  */
}

Examples

| Input string | Captured values | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | 2025-11-02T10:20:30Z | { year: '2025', month: '11', day: '02', hour: '10', minute: '20', second: '30', millisecond: undefined, timezone: 'Z' } | | 2038-01-19T03:14:07.045+13:59 | { year: '2038', month: '01', day: '19', hour: '03', minute: '14', second: '07', millisecond: '045', timezone: '+13:59' } | | 2000-02-29T00:00:00-12:00 | { year: '2000', month: '02', day: '29', hour: '00', minute: '00', second: '00', millisecond: undefined, timezone: '-12:00' } | | 2024-06-10T09:08:07.5+14:00 | { year: '2024', month: '06', day: '10', hour: '09', minute: '08', second: '07', millisecond: '5', timezone: '+14:00' } |

Tip: The millisecond field may be undefined if no fractional component is present. This is especially useful when normalizing ISO timestamps or building custom date-time parsers.

Mechanics

The regex matches only valid and complete ISO 8601 datetime strings of the form:

YYYY-MM-DDTHH:mm:ss(.SSS)?(Z|±HH:MM)

Examples that match

| Example | Description | | ------------------------------- | --------------------- | | 2025-11-02T10:20:30Z | Basic UTC timestamp | | 2025-11-02T10:20:30.123Z | With milliseconds | | 2025-11-02T10:20:30+09:30 | With positive offset | | 2024-02-29T12:00:00Z | Leap year February 29 | | 2025-04-30T23:59:59.999+00:00 | Month with 30 days |

Examples that do not match

| Example | Reason | | ----------------------- | ------------------------------- | | 2025-11-02T10:20:30 | Missing Z or offset | | 2025-11-02 10:20:30Z | Space instead of T | | 2025-04-31T12:00:00Z | April has only 30 days | | 2025-11-02T24:00:00Z | Hour overflow | | 1900-02-29T00:00:00Z | 1900 not a leap year | | 2025-11-02T10:20:30Z | Leading space (anchored at ^) |

Regex Features

Enforces

• Year: 0000–9999
• Month: 01–12
• Day: 01–31 (valid per month, leap-year aware)
• Hours: 00–23
• Minutes: 00–59
• Seconds: 00–59
• Milliseconds: optional 1–3 digits
• Time zone: Z or ±HH:MM (00–23h / 00–59m)
• Anchored at both ends (^…$) — no leading/trailing characters allowed

Leap Year Logic

Leap years match the Gregorian rule:

• Divisible by 4 → leap year
• Except years divisible by 100 → not leap year
• Except years divisible by 400 → leap year again

• 2000, 2016, 2024 are leap years
• 1900, 2100 are not

Test Coverage

The test suite verifies:

| Category | Examples tested | | -------------------- | -------------------------------------------------------- | | Basic formats | UTC (Z), fractional seconds, positive/negative offsets | | Time boundaries | 00:00:00–23:59:59, offsets ±00:00–±23:59 | | Month/day bounds | Correct 30- vs 31-day months | | Invalid overflow | Hours ≥24, minutes/seconds ≥60, too many ms digits | | Non-ISO shapes | Wrong separators, missing parts, trailing junk | | Leap years | Accepts Feb 29 only in leap years | | Common years | Rejects Feb 29 on non-leap years | | Anchors | Rejects leading/trailing spaces and extra characters | | Regression cases | Valid timestamps across centuries and time zones |

Running the Tests

Make sure you’re using Node.js v20+, then run:

npm test

Notes & Limitations

• Performance: This regex is large but optimized for correctness over speed.
• Scope: Designed for datetime strings, not partial ISO dates (YYYY-MM, YYYY-Wxx, etc.).
• Whitespace: Leading/trailing spaces cause rejection; trim inputs before testing.
• Calendar bounds: Days per month and leap-year rules are enforced; invalid combinations (e.g. April 31) fail.

References

• ISO 8601:2019 — Date and time format specification
• RFC 3339 — Date and Time on the Internet: Timestamps
• ECMAScript Date.toISOString()

Changelog

v0.2.4 — 2025-11-12

• Security enhancement, added provenance files

v0.2.3 — 2025-11-12

• Added CommonJS export
• Improved test suite with performance tests
• Moved to a proper repository

v0.2.2 — 2025-11-04

• Update import example in README.md

v0.2.1 — 2025-11-04

• Changing README.md title
• Update homepage URL in package.json

v0.2.0 — 2025-11-03

Breaking

• Validate strict timezone range −12:00…+14:00

Added

• Named capturing groups: year, month, day, hour, minute, second, millisecond, and timezone.
• New section in README: “Using group captured values”, with examples and table of captured outputs.
• Extended test suite for group extraction (node:test).

Improved

• Simplified month capture pattern (0[1-9]|1[0-2]) for readability and correctness.
• Refined timezone range enforcement: now validates strictly within −12:00 … +14:00, rejecting −12:01…−12:59 and +14:01…+14:59.
• Unified spelling to millisecond across code and documentation.

v0.1.1 — 2025-11-02

Added

• Strict ISO 8601 regex with full Gregorian calendar correctness (month/day validation and leap-year logic).
• Test suite using Node’s native node:test and assert/strict modules.
• Validation of fractional seconds, offsets, and anchors.

Improved

• Leap-year computation: accepts 2000, 2400, rejects 1900, 2100.
• Tests covering non-ISO shapes and extended formats.

v0.1.0 — 2025-11-02

Initial release: foundational strict ISO 8601 validation for UTC.

License

MIT License

Copyright 2025 [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.