Skip to content

Latest commit

 

History

History
453 lines (397 loc) · 44.4 KB

CHANGELOG.md

File metadata and controls

453 lines (397 loc) · 44.4 KB

0.5.1

Bug fixes:

  • Fix infinite recursion in Node 23.x with Intl.DurationFormat (fixes #329).
  • Include correct package-lock.json (fixes #328).
  • Don't override TIMEOUT when running npm run test262.

Non-breaking changes:

  • Support Node 22.x and 23.x and test them in CI (fixes #323).
  • The polyfilled Intl.DateTimeFormat object now supports offset time zone identifiers (e.g., -02:30) in Node 23.x. Note that the native Intl.DateTimeFormat in Node 23.x also supports them, but in a nonstandard way, so you should use the polyfilled Intl.DateTimeFormat in your code.
  • Add migration guide for 0.4.x → 0.5.0.
  • Reduce production bundle size by deleting assertions and minifying function names.

0.5.0

Breaking changes:

This major update reflects all changes to the Temporal proposal adopted by TC39 between May 2023 and March 2025.

The majority of these changes were made in the June 2024 TC39 meeting (slides here) where the scope of Temporal was reduced at the request of JS engine implementers who were concerned about the size impact of adding Temporal to distributions on limited-capacity devices like low-end Android phones and Apple Watch.

  • User-defined calendars have been removed. Calendars are now represented by strings representing built-in calendars. Without custom calendars, the huge surface area of Temporal.Calendar was not necessary, and that type was removed from the proposal.
  • User-defined time zones have been removed. Time zones are now only represented by string identifiers representing built-in time zones: either a Zone or Link name from the IANA Time Zone Database, or a time zone offset with minutes precision. Temporal.TimeZone has also been removed, and its methods replaced by the following:
    • getPreviousTransition/getNextTransition - use the new getTimeZoneTransition method of Temporal.ZoneDateTime.
    • equals - use ZonedDateTime.prototype.equals using the same instant and calendar.
    • Other Temporal.TimeZone methods can use the corresponding methods on Temporal.ZonedDateTime.
  • Many convenience methods have been removed. In all cases, the same functionality is available using other Temporal methods:
    • Removed getISOFields() methods. Instead use withCalendar('iso8601') and the individual property getters.
    • Removed withPlainDate() methods. Instead use with({ year, monthCode, day }).
    • Removed toPlainDateTime() and toZonedDateTime() methods of Temporal.PlainTime. Instead use the same-named methods on Temporal.PlainDate to combine a date and a time.
    • Removed epochSeconds and epochMicroseconds properties. Instead calculate epoch seconds with Math.floor(epochMilliseconds / 1000) and epoch microseconds with epochNanoseconds / 1000n + ((epochNanoseconds % 1000n) < 0n ? -1n : 0n).
    • Removed toPlainYearMonth() and toPlainMonthDay() methods of Temporal.PlainDateTime and Temporal.ZonedDateTime. Instead use toPlainDate() and then the methods on Temporal.PlainDate.
    • Removed Temporal.Instant.prototype.toZonedDateTime and Temporal.Now.zonedDateTime. Instead use toZonedDateTimeISO()/zonedDateTimeISO() to create a Temporal.ZonedDateTime object using the ISO8601 calendar, and then use withCalendar() if a non-ISO calendar is desired.
  • The relativeTo parameter is no longer accepted in Temporal.Duration.prototype.add and subtract. Instead take the relativeTo object, add the two durations to it, and difference it with the original using until().
  • Throw if there are multiple calendar annotations in a string and one has the critical flag (Proposal PR)
  • Changed the way calculations are done with Temporal.Duration, and placed limits on each of the units. Years, months, and weeks are each limited to 2³²−1. The other units (days through nanoseconds) are collectively limited: taken together, they must be less than Number.MAX_SAFE_INTEGER seconds plus 999,999,999 nanoseconds. This has few user-visible changes, but it does mean that some durations are no longer allowed (for example, Temporal.Duration.from({ seconds: Number.MAX_VALUE }).) (Proposal PR 1, PR 2, PR 3)
  • Offset time zones are now limited to minutes precision. That is, you can have [+01:01] but not [+01:00:01] or [+01:00:00.000000001] (Proposal PR)
  • For APIs that take a string, other primitives are no longer coerced to strings. Technically, you could previously do Temporal.PlainDate.from(20230711) and it would be treated as Temporal.PlainDate.from("20230711"). This is no longer the case. (Proposal PR)
  • Temporal.PlainYearMonth.prototype.toPlainDate and Temporal.PlainMonthDay.prototype.toPlainDate now have clamping behaviour instead of throwing if the resulting PlainDate would be invalid. For example, birthday.toPlainDate({ year: 2025 }) will now return February 28, 2025 if the birthday in question if February 29. (Proposal PR)
    • If you still want the throwing behaviour, you can get it more verbosely:
    const { monthCode, day } = birthday;
Temporal.PlainDate.from({ year: 2025, monthCode, day }, { overflow: 'reject' });
  • Not all calendars have a week numbering scheme, so weekOfYear and yearOfWeek methods may now return undefined (Proposal PR)
  • In Temporal.Duration.prototype.round(), rounding to a >1 increment of a calendar smallestUnit while simultaneously balancing to a calendar largestUnit is now disallowed and will throw (Proposal PR)
  • Creating a Temporal.MonthDay in a non-ISO8601 calendar will now throw if the year is too far (>¼ million years) in the future or past (Proposal PR)

Bug fixes:

  • Fixed several bugs in duration calculations, particularly rounding (Proposal PR 1, PR 2, PR 3, PR 4, PR 5)
  • Fixed a bug in start-of-day calculations (Proposal PR)
  • Many small bug fixes to bring the polyfill into better compliance with the Temporal proposal

Non-breaking changes

  • Many improvements in performance and bundle size
  • Remove runtime dependency on tslib. Now this package has only one runtime dependency: JSBI (a polyfill for BigInt)
  • Update dev dependencies
  • Support Node 20.x and test it in CI

0.4.4

Breaking changes:

  • Temporal.ZonedDateTime objects are no longer supported as parameters to Intl.DateTimeFormat formatting methods. (12071fb0, see also Upstream PR, Upstream PR 2)
    • To format using Temporal.ZonedDateTime's time zone, use Temporal.ZonedDateTime.prototype.toLocaleString. This method:
      1. Creates a new Intl.DateTimeFormat instance in the same time zone and calendar as the Temporal.ZonedDateTime instance
      2. Creates a Temporal.Instant from the Temporal.ZonedDateTime instance.
      3. Formats that Temporal.Instant instance using the created Intl.DateTimeFormat instance.
    • To format in a time zone that does not match the time zone of the Temporal.ZonedDateTime instance:
      1. Create a new Temporal.ZonedDateTime instance in the right time zone using Temporal.ZonedDateTime.prototype.withTimeZone.
        • To get the current system time zone, use Temporal.Now.timeZoneId(). Be careful when caching the current system time zone (or an Intl.DateTimeFormat instance using that time zone), because the system time zone can change during the lifetime of your program (e.g. when a user on a mobile device crosses a time zone boundary or when a user manually edits time zone settings).
      2. Follow the steps above.
    • Generally, try to always include the timeZone property when creating an Intl.DateTimeFormat instance to avoid an ambiguity about which time zone the formatted results will be in.
    • Intl.DateTimeFormat instances can be expensive to create. For performance-sensitive code where the same calendar and time zone are used repeatedly for formatting, we recommend creating and reusing an Intl.DateTimeFormat instance with the desired timeZone and calendar options, and then formatting using the value of Temporal.ZonedDateTime.prototype.epochMilliseconds. Intl.DateTimeFormat instances may also require a lot of RAM, so indefinitely caching large numbers of them is not recommended for memory-constrained environments.
  • The .calendar property on Temporal types has been replaced with a .calendarId property that returns the string calendar identifier and a .getCalendar() method that returns an object that implements Temporal.CalendarProtocol.
    • getCalendar() will always return a new object if the containing instance was constructed using a built-in calendar identifier string. However, if the containing instance was constructed using a calendar object (either a built-in calendar or custom calendar), then the same object is returned. (cc701b45, see also Upstream issue)
    • Temporal will compare calendars by testing for string equality between calendar identifiers. When a calendar is an object, its id property will be used for comparison. (3916e547, see also Upstream issue)
    • The .calendar property has been entirely removed from Temporal.PlainTime. (0727d86e, see also Issue 1, Issue 2)
  • The .timeZone property on Temporal.ZonedDateTime has been replaced with a .timeZoneId property that returns the string time zone identifier and a .getTimeZone() method that returns an object that implements Temporal.TimeZoneProtocol. ([d3263f0], see also Upstream issue)
    • getTimeZone() will always return a new object if the Temporal.ZonedDateTime instance was constructed using a built-in time zone identifier string. However, if the instance was constructed using a time zone object (either a built-in time zone or custom time zone), then the same object is returned.
    • Termporal.Now.timeZone() is replaced by Temporal.Now.timeZoneId(), which returns a time zone identifier string, not a Temporal.TimeZone instance. (600f0cc7, see also Upstream issue)
    • Temporal will compare time zones by testing for string equality between calendar identifiers. When a calendar is an object, its id property will be used for comparison. (d6cb2862, see also Upstream issue)
  • Require the id property and make overriding toString optional (but recommended!) for Temporal.TimeZoneProtocol. (97637bbc)
  • Remove support for nested time zone and calendar property bags. (9b7f61ae, 0c38267b, see also Discussion)
  • Require the remainder returned by the NanosecondsToDays internal operation to be less than the length of one calendar day. This could happen due to shenanigans in a custom time zone's getOffsetNanosecondsFor or getPossibleInstantsFor methods, or a custom calendar's dateAdd method. (44b00a38, see also Upstream issue
  • Set an upper limit of 1e9 on rounding increments. (5d78c815)
  • Require fields and mergeFields methods for Temporal.CalendarProtocol (custom calendar) objects. (5ad63274)
  • Reject Z designators when parsing Temporal.PlainTime strings.

Bug fixes:

  • Read field identifiers from a calendar's fields() method during dateFromFields(), yearMonthFromFields(), and monthDayFromFields(). Previously, these methods only referenced hardcoded 'era' and 'eraYear' field identifiers. (375a4ad9)
  • Avoid precision loss in AddDuration operations. (c0f7349a)
  • Fix an infinite-loop bug and a RangeError during non-ISO calendar calculations. (d94c1cd9, see also proposal-temporal PR, Issue 1, Issue 2)
  • Avoid rounding errors in BalanceTime operations. (9260a8a0)
  • Avoid precision loss in NanosecondsToDays operations. (e02f0626)
  • Require that results from NanosecondsToDays calls don't flip sign. (0b238ccf)
  • Fix bugs introduced while restricting the creation of Temporal.Duration using non-numeric inputs. (46c4132d, see also Upstream issue)
  • Fix bugs when passing fractional numbers to CreateTemporalDuration. (856a5460, see also Upstream issue)
  • Always return a Number of nanoseconds from RoundDuration. (8d3c1f1b)
  • Use BigInt math in RoundDuration to avoid problems when the values are larger than Number.MAX_SAFE_INTEGER. (955323f8)
  • Always start at the end of 1972 when computing a Temporal.PlainMonthDay from fields, preventing the reference year from accidentally being in 1971. (ef4a0c4b)
  • Apply the overflow behaviour to year/month/day values in monthDayFromFields. (7ebd0f96)
  • Preserve the day of month when constraining a nonexistent leap month, instead of defaulting to the end of the closest corresponding regular month. (996f8fa1)
  • Allow month codes 'M01L' and 'M12L' in the Chinese calendar. (696f2c7e)
  • Avoid overflows in GetNamedTimeZoneOffsetNanoseconds. (c42570b8)
  • Fix calendar validation in various ToTemporal___ operations. (e3913974, see also Upstream issue)
  • Don't call GetMethod on a string calendar. (fe698d8d, see also Upstream issue)
  • Avoid rounding errors in BalanceDurationRelative and UnbalanceDurationRelative. (a907acf0)
  • Check for negative day length in Temporal.ZonedDateTime.prototype.round. (0d2d60ec, see also Spec PR) This change avoids a common bug where a UTC timestamp is accidentally interpreted as if it were a local time in a real time zone. If you do want to parse the time portion of a UTC timestamp string, use: Temporal.Instant.from(s).toZonedDateTimeISO('UTC').toPlainTime(). (a7a50eac)
  • Reject 0-value components when parsing Temporal.Duration strings, and avoid rounding errors when nanoseconds components are present. (58b5601a)
  • Reject relativeTo string options that are neither valid Temporal.PlainDate nor Temporal.ZonedDateTime strings, such as '2022-08-18T17:01Z'. (4db15c41)
  • Add validation for the return values from calendar operations. (d88cfa4d)
  • Validate required methods of Temporal.TimeZoneProtocol and Temporal.CalendarProtocol. (84563cea, 755c7620, see also Discussion)
  • Throw earlier when users might mix up positional Temporal.TimeZone and Temporal.Calendar arguments with each other, to prevent bugs like new Temporal.ZonedDateTime(0n, cal, tz) where the switched calendar and time zone arguments would cause exceptions to be thrown later. (7922f1f9)

Non-breaking changes:

  • Implement yearOfWeek methods that complement existing weekOfYear methods. The new method returns the year associated with weekOfYear, which may (see https://en.wikipedia.org/wiki/ISO_week_date) vary from year in some calendars like 'iso8601'. This new method can be useful for formatting IS0 8601 strings using the year-week-day format like 1981-W53-7. (bf08ca56)
  • Support new Internet Extended Date-Time (IXDTF) Annotations
    • See the Temporal + IXDTF tracking issue.
    • Align ISO 8601 grammar with annotations from IXDTF specification. Calendar and time zone annotations are now allowed to contain a "critical" flag ('!') prefix. Critical flags have no effect when parsing input strings because Temporal already treats unknown or inconsistent inputs as errors by default. (e8b2e71c)
      • There can be multiple types of annotations in an IXDTF string. Temporal only recognizes time zone and calendar annotations. Unrecognized non-critical annotations will be ignored. Unrecognized critical annotations will cause the parsing method to throw an exception.
    • Allow toString() methods for Temporal.PlainDate, Temporal.PlainDateTime, Temporal.PlainYearMonth, Temporal.PlainMonthDay, and Temporal.ZonedDateTime to emit critical IXDTF annotations using the 'critical' option. Use this option with care, because the platform that you're communicating with may not understand this syntax. calendarName: 'critical' behaves like calendarName: 'always' and timeZoneName: 'critical' behaves like timeZoneName: 'always', but they also output a '!' prefix in the corresponding annotation. (50a64f16) Critical flags are never used by Temporal, but could be consumed by other programs.
    • Ignore calendar annotations when parsing Temporal.Instant strings. (b86b87f0)
    • Allow calendar and/or time zone annotations after strings without a time part: YYYY-MM-DD, YYYY-MM, and MM-DD. (acd6464f)
    • Disallow UTC offsets in YYYY-MM and MM-DD strings because they could cause ambiguity between an offset and the day of a YYYY-MM-DD string. (acd6464f)
    • Reject ambiguous time strings even with calendar annotations. (af875275)
  • Implement the full set of rounding modes. New modes include 'expand', 'halfCeil', 'halfFloor', 'halfTrunc', and 'halfEven'. (eb5404d1)
  • Treat calendar names as case-insensitive. (9e730d68)
  • Improve cross-binary compatibility of polyfill objects by storing internals on globalThis. (73a0bf36, see also GitHub Issue)
  • Allow various Temporal.Calendar methods to return 0. (8a49023b)
  • Improve error messages when converting fields to a Temporal.PlainMonthDay. (e1cd4170)
  • Round towards the Big Bang in epoch time getters. (6d124a56, see also Upstream issue, Spec change)
  • Improve performance when operating on large numbers in BalanceISODate. (d2a23dd5)
  • Optimize Temporal.TimeZone.prototype.getNextTransition() for dates that predate 1847, which is the earliest data in the IANA time zone database. (9591af3b)
  • Improve performance when out-of-range finding transition points for named time zones. (3b61abfe)
  • Special-case zones with precomputed DST transition points in GetPreviousTransition. (5922bdf1)

Other:

  • Bump required dependency versions. (c65455a5)
  • Fix sourcemaps so they point directly to TS source files. (6b462d49, see also GitHub PR)

0.4.3

Bug fixes:

  • Fix an off-by-one error when dates in the Hebrew calendar were created using monthCode, the year was a leap year, and the month was after the leap month (f3d0ca9f)
  • Fix addition of months and years for lunisolar calendars (4f8b04c1)
  • Fix the ISO8601 representation of years between 1 BCE and 999 BCE (b251dc0e).
  • Fix a bug causing time to appear to go backwards for a small number of milliseconds (bb59ca97)
  • Always validate ISO8601 time components as well as date components (34662a05)
  • Fix comparison of dates that might have a differing number of hours in their respective days (a4c60241)
  • Include calendar reference information when calendarName='always' is passed to various Temporal toString method's options bags (54fcc4f3)
  • Fix a nonconformant use of the relativeTo property bag (9992f9b1)
  • Fix ZonedDateTime.prototype.withPlainTime(null) to throw a TypeError, instead of treating it as midnight (ec2b0546)
  • Fix parsing of some valid Instant strings when they would be out of range before considering the UTC offset (d9de9e74)
  • Bail out early in non-ISO calendar implementations to avoid an infinte loop when calculating the duration between two identical dates. (6f3c42c9)
  • Fix type resolution when using TypeScript Node16 and transpiling to CJS (9bab0eb5, see also the relevant TypeScript issue)

Non-breaking changes:

  • Consistently call observable operations with undefined options arguments, instead of empty objects (297b8f38)

0.4.2

This version is a patch version enabling TypeScript Node16 support for this package.

Bug Fixes:

  • Add types to exports/./import to support Typescript Node16 (304c86dd)

0.4.1

This version is a patch version enabling polyfill compatibility with Safari versions <15.1 (October 2021 and earlier).

Bug fixes:

  • Remove erroneous options from Safari's Intl.DateTimeFormat resolvedOptions bag. The underlying bug in Safari was fixed in Safari 15.1.

0.4.0

This version roughly corresponds with all the changes made to the Temporal polyfill as of the January 2022 TC39 Plenary meeting.

Breaking changes:

  • Use JSBI instead of big-integer for Big Integer math operations. If your codebase does not need to polyfill BigInt, consider using the JSBI Babel plugin to transpile these operations to native BigInt.
  • Reject plain date-only strings (b733c213, see also Spec PR, proposal-temporal polyfill PR)
  • Reject '-000000' as an extended year value (670cda6b, see also Spec PR)
  • Add missing branding checks for Calendar and Timezone classes to match spec changes (670cda6b, see also Spec PR)

Bug fixes:

Non-breaking changes:

  • Rename public ...FromFields types (3554d7f1)
  • Add validation for hard-coded Era data in Calendar.ts (08e84c9f)
  • Improve code in Calendar.ts to handle calendar with a constant era but a variable number of months in a year (ef8c588b)
  • Add an optional calendar to PlainTime, PlainDateTime, and PlainMonthDay (f8837367, see also Spec PR)
  • Only require a year in Gregorian calendar implementations, not a full date (02aec1c3)
  • Include valueOf in the Temporal.Duration type (b1dd7eb3)
  • Expand the types allowed to be used as TimezoneLike and CalendarLike to match the spec (9d54c646)
  • Improve worse-case performance when finding Timezone transition points by over 1000X! (e70d6324)
  • Change Calendar.fields to return an Array, not an Iterable (3145c6c4, see also Spec PR)

Other:

  • Update build dependencies (500b4c97)
  • Run tests against Node 17 on CI (db63e22a)

0.3.0

This version roughly corresponds with all the changes made to the Temporal polyfill as of the October 2021 TC39 Plenary meeting.

Breaking changes:

  • Timezones now require a getOffsetNanosecondsFor method, and no longer fall back to the intrinsic definition (previously provided by Temporal.Timezone#getOffsetNanosecondsFor) if not provided. (08346dc5, see also proposal-temporal polyfill PR)
  • Disallow Z designators when parsing strings for Plain Temporal types (f3f8a994, see also Spec PR)
  • Allow ISO strings with "Z" + a bracketed IANA name (70bd9898, see also Spec PR)
  • Emit ES2020 builds for newer browsers, and emit ES5 for older browsers. (2331468d, 9e95c62b)
  • Temporal.Duration constructor will now throw if given a non-integer (9df5d068, see also Spec PR)
  • Remove support for sub-minute offsets in ISO strings (766e5037, see also Spec PR, Spec PR)
  • Throw TypeError on missing options from Duration.total (4ec075f0, see also Spec PR)
  • Reject non-integer Duration fields in Duration.with() (e6b2488d, see also Spec PR)
  • Ensure an Object is returned from calendar.mergeFields() (4e63f25f, see also Spec PR)

Bug fixes:

Non-breaking changes:

  • Various #round and #total methods now accept string parameters or options bags. Strings are interpreted as the smallestUnit option (or unit for Temporal.Duration#total). (068e801f, see also Spec PR)
  • Add @@toStringTag to TS types (41ab6bc0)
  • Accept string Calendar names in PlainMonthDay and PlainYearMonth constructors (27b4c7e8)
  • Make options optional in Calendar method TS types (3a09d00d)
  • Align implementation of RoundDuration with adjusted spec text (4a0d0264, see also Spec PR)

Other: