@northguild/gmt 1.17.0 → 1.19.0

package/dist/precision/convert/toExcelSerial.js

@@ -1,5 +1,6 @@
 import { EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, floorDivide, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, parseInstantNanoseconds, } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /**
  * Convert an ISO 8601 instant string to an Excel day serial.
  *
@@ -11,8 +12,6 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   compatibility. No instant maps to serial 60: 1900-02-28 is 59 and 1900-03-01 is 61.
  *   Silently "fixing" this would put GMT one day out from Excel for every date before March
  *   1900.
- * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01. The
- *   same instant is exactly 1462 lower there than in the 1900 system.
  * - **Instants outside Excel's own serial range are invalid input**, not an out-of-range
  *   number: the 1900 system runs from serial 1 (1900-01-01) to 2958465 (9999-12-31), the
  *   1904 system from serial 0 (1904-01-01) to 2957003. Serial 0 in the 1900 system is
@@ -29,7 +28,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  *   that Excel rejects on the way in.
  *
  * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
- * @param options optional: system ("1900" (default) | "1904")
+ * @param options Which Excel date system the serial is in
  * @returns Excel day serial as a number, or null on invalid input
  *
  * @example toExcelSerial("1900-01-01T00:00:00Z") // 1 — Excel's first serial
@@ -47,7 +46,7 @@ export function toExcelSerial(isoString, options) {
         if (!isOptionsArgument(options)) {
             return null;
         }
-        const system = options?.system === undefined ? "1900" : options.system;
+        const system = optionOrDefault(options?.system, "1900");
         if (system !== "1900" && system !== "1904") {
             return null;
         }

package/dist/precision/convert/toNanoseconds.d.ts

@@ -3,11 +3,15 @@
  *
  * - Requires an offset designator (`Z`, `±HH:MM`), as `Temporal.Instant` does — date-only
  *   and offset-less strings are rejected.
- * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation, both
- *   ignored as `Temporal.Instant.from` ignores them (an instant has no calendar).
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation. The
+ *   calendar is ignored, as `Temporal.Instant.from` ignores it (an instant has no calendar).
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing.
  * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
  *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and an hour-only time or offset return `0n`, although
@@ -29,7 +33,8 @@
  * @example toNanoseconds("2024-03-10T12:00:00.123456789Z") // 1710072000123456789n
  * @example toNanoseconds("1969-12-31T23:59:59Z") // -1000000000n
  * @example toNanoseconds("2024-03-10T12:00:00-05:00[America/New_York]") // 1710090000000000000n
- * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is ignored
+ * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is not checked
+ * @example toNanoseconds("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // -315615330000000000n — the zone's −00:44:30, which `-00:45` rounds
  * @example toNanoseconds("2024-03-10T12:00:00") // 0n — no offset designator
  * @example toNanoseconds("20240310T120000Z") // 0n — basic format
  * @example toNanoseconds("invalid") // 0n

package/dist/precision/convert/toNanoseconds.js

@@ -4,11 +4,15 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  *
  * - Requires an offset designator (`Z`, `±HH:MM`), as `Temporal.Instant` does — date-only
  *   and offset-less strings are rejected.
- * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation, both
- *   ignored as `Temporal.Instant.from` ignores them (an instant has no calendar).
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation. The
+ *   calendar is ignored, as `Temporal.Instant.from` ignores it (an instant has no calendar).
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing.
  * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
  *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and an hour-only time or offset return `0n`, although
@@ -30,7 +34,8 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  * @example toNanoseconds("2024-03-10T12:00:00.123456789Z") // 1710072000123456789n
  * @example toNanoseconds("1969-12-31T23:59:59Z") // -1000000000n
  * @example toNanoseconds("2024-03-10T12:00:00-05:00[America/New_York]") // 1710090000000000000n
- * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is ignored
+ * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is not checked
+ * @example toNanoseconds("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // -315615330000000000n — the zone's −00:44:30, which `-00:45` rounds
  * @example toNanoseconds("2024-03-10T12:00:00") // 0n — no offset designator
  * @example toNanoseconds("20240310T120000Z") // 0n — basic format
  * @example toNanoseconds("invalid") // 0n

package/dist/precision/validate/isValidInstant.d.ts

@@ -9,9 +9,18 @@
  *
  * - Requires an offset designator (`Z`, `±HH:MM`); a bracketed IANA zone may follow, but a
  *   bracket alone is not enough.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, at the first and last instants of the range too, where the
+ *   written offset's own reading can fall just outside it
+ *   (`-271821-04-19T23:58:45-00:01[Europe/London]` is the first instant). One exception, which
+ *   is Temporal's own: a wall time repeated inside a sub-minute offset change, written with a
+ *   minute-rounded offset, reads as its first pass (for example `1952-10-15T23:59:59-11:20[Pacific/Niue]`,
+ *   where the zone moved from −11:19:40 to −11:20:00, is the pass at −11:19:40). Otherwise the bracket is not checked: a
+ *   zone that does not exist, or that disagrees with the offset, changes nothing. Validity never depends
+ *   on the bracket.
  * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
  *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and an hour-only time or offset return `false`, although

package/dist/precision/validate/isValidInstant.js

@@ -10,9 +10,18 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  *
  * - Requires an offset designator (`Z`, `±HH:MM`); a bracketed IANA zone may follow, but a
  *   bracket alone is not enough.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
- *   with the offset is not checked.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, at the first and last instants of the range too, where the
+ *   written offset's own reading can fall just outside it
+ *   (`-271821-04-19T23:58:45-00:01[Europe/London]` is the first instant). One exception, which
+ *   is Temporal's own: a wall time repeated inside a sub-minute offset change, written with a
+ *   minute-rounded offset, reads as its first pass (for example `1952-10-15T23:59:59-11:20[Pacific/Niue]`,
+ *   where the zone moved from −11:19:40 to −11:20:00, is the pass at −11:19:40). Otherwise the bracket is not checked: a
+ *   zone that does not exist, or that disagrees with the offset, changes nothing. Validity never depends
+ *   on the bracket.
  * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
  *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
  *   lower-case `z` and an hour-only time or offset return `false`, although

package/dist/regex/epcis.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RegExp matching a GS1 EPCIS 2.0 `eventTimeZoneOffset`: the `pattern` the EPCIS JSON schema
+ * (https://ref.gs1.org/standards/epcis/epcis-json-schema.json, a normative artefact of EPCIS 2.0 /
+ * ISO/IEC 19987) gives for the field, verbatim: `^([+]|[-])((0[0-9]|1[0-3]):([0-5][0-9])|14:00)$`.
+ *
+ * - The pattern is the JSON binding's. The XML binding's XSD types the same field as a bare
+ *   `xsd:string` and gives no pattern.
+ * - The rule both bindings carry is the standard's prose, EPCIS Standard Release 2.0 §7.4.1
+ *   (https://ref.gs1.org/standards/epcis/): the value "SHALL be a string consisting of the
+ *   character '+' or the character '-', followed by two digits whose value is within the range
+ *   00 through 14 (inclusive), followed by a colon character ':', followed by two digits whose
+ *   value is within the range 00 through 59 (inclusive), except that if the value of the first
+ *   two digits is 14, the value of the second two digits must be 00." The pattern is that
+ *   sentence as a regular expression.
+ * - `±HH:MM` from `-13:59` through `+13:59`, plus `±14:00`. GS1 published the grammar, so it is
+ *   neither loosened nor tightened here: `-14:00` matches because the sign group is independent
+ *   of the `14:00` alternative, and `-00:00` matches.
+ * - `Z` does not match: it is `eventTime`'s designator, and this field records the offset in
+ *   force where the event happened. `+0200` (no colon) and `+02` (hours only) do not match.
+ * - Shape only. `parseEpcisEvent` reads the value through Temporal, and returns `-00:00` as
+ *   `+00:00`. To check a value that may not be a string, use `isValidEpcisTimeZoneOffset`: for a
+ *   string it gives this pattern's answer.
+ *
+ * Capture groups: 1 sign, 2 the hours-and-minutes or `14:00`, 3 hours, 4 minutes (3 and 4 are
+ * `undefined` for `14:00`).
+ *
+ * @example epcisTimeZoneOffset.test("-05:00") // true
+ * @example epcisTimeZoneOffset.test("+14:00") // true
+ * @example epcisTimeZoneOffset.test("+14:01") // false (past the range GS1 allows)
+ * @example epcisTimeZoneOffset.test("Z")      // false (a designator, not an offset)
+ * @example epcisTimeZoneOffset.test("+0200")  // false (no colon)
+ */
+export declare const epcisTimeZoneOffset: RegExp;
+/**
+ * RegExp matching a GS1 EPCIS 2.0 `eventTime` (and `recordTime`): the `DateTimeStamp` pattern of
+ * the EPCIS XSD (https://ref.gs1.org/standards/epcis/epcglobal-epcis-2_0.xsd, a normative
+ * artefact of EPCIS 2.0 / ISO/IEC 19987), verbatim and anchored.
+ *
+ * - The pattern is the XML binding's. The JSON schema types the same field as a string with
+ *   `format: date-time` and gives no pattern, so this is the stricter of the two bindings.
+ * - A date-time with seconds required, an optional fraction of any length, then `Z` or an offset
+ *   in the same range as `epcisTimeZoneOffset`.
+ * - GS1 published the grammar, so it is neither loosened nor tightened here: four-digit years
+ *   only, upper-case `T` and `Z`, a colon in the offset, no space separator.
+ * - Shape only; calendar validity is Temporal's (`2023-02-29T00:00:00Z` matches and
+ *   `Temporal.Instant.from` rejects it). To check that a string is a real `eventTime`, use
+ *   `isValidEpcisEventTime`: this pattern also matches a day that does not exist and a fraction
+ *   longer than nine digits.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second, 7 fraction with its
+ * period (optional), 8 `Z` or the offset, 9 the offset, 10 sign, 11 hours-and-minutes or
+ * `14:00`, 12 hours, 13 minutes.
+ *
+ * @example epcisEventTime.test("2024-06-15T14:30:00Z")           // true
+ * @example epcisEventTime.test("2024-06-15T14:30:00.123-05:00")  // true
+ * @example epcisEventTime.test("2024-06-15T14:30Z")              // false (seconds are required)
+ * @example epcisEventTime.test("2024-06-15T14:30:00")            // false (Z or an offset is required)
+ * @example epcisEventTime.test("2024-06-15T14:30:00+15:00")      // false (offset past the range GS1 allows)
+ */
+export declare const epcisEventTime: RegExp;

package/dist/regex/epcis.js

@@ -0,0 +1,60 @@
+/**
+ * RegExp matching a GS1 EPCIS 2.0 `eventTimeZoneOffset`: the `pattern` the EPCIS JSON schema
+ * (https://ref.gs1.org/standards/epcis/epcis-json-schema.json, a normative artefact of EPCIS 2.0 /
+ * ISO/IEC 19987) gives for the field, verbatim: `^([+]|[-])((0[0-9]|1[0-3]):([0-5][0-9])|14:00)$`.
+ *
+ * - The pattern is the JSON binding's. The XML binding's XSD types the same field as a bare
+ *   `xsd:string` and gives no pattern.
+ * - The rule both bindings carry is the standard's prose, EPCIS Standard Release 2.0 §7.4.1
+ *   (https://ref.gs1.org/standards/epcis/): the value "SHALL be a string consisting of the
+ *   character '+' or the character '-', followed by two digits whose value is within the range
+ *   00 through 14 (inclusive), followed by a colon character ':', followed by two digits whose
+ *   value is within the range 00 through 59 (inclusive), except that if the value of the first
+ *   two digits is 14, the value of the second two digits must be 00." The pattern is that
+ *   sentence as a regular expression.
+ * - `±HH:MM` from `-13:59` through `+13:59`, plus `±14:00`. GS1 published the grammar, so it is
+ *   neither loosened nor tightened here: `-14:00` matches because the sign group is independent
+ *   of the `14:00` alternative, and `-00:00` matches.
+ * - `Z` does not match: it is `eventTime`'s designator, and this field records the offset in
+ *   force where the event happened. `+0200` (no colon) and `+02` (hours only) do not match.
+ * - Shape only. `parseEpcisEvent` reads the value through Temporal, and returns `-00:00` as
+ *   `+00:00`. To check a value that may not be a string, use `isValidEpcisTimeZoneOffset`: for a
+ *   string it gives this pattern's answer.
+ *
+ * Capture groups: 1 sign, 2 the hours-and-minutes or `14:00`, 3 hours, 4 minutes (3 and 4 are
+ * `undefined` for `14:00`).
+ *
+ * @example epcisTimeZoneOffset.test("-05:00") // true
+ * @example epcisTimeZoneOffset.test("+14:00") // true
+ * @example epcisTimeZoneOffset.test("+14:01") // false (past the range GS1 allows)
+ * @example epcisTimeZoneOffset.test("Z")      // false (a designator, not an offset)
+ * @example epcisTimeZoneOffset.test("+0200")  // false (no colon)
+ */
+export const epcisTimeZoneOffset = /^([+]|[-])((0[0-9]|1[0-3]):([0-5][0-9])|14:00)$/;
+/**
+ * RegExp matching a GS1 EPCIS 2.0 `eventTime` (and `recordTime`): the `DateTimeStamp` pattern of
+ * the EPCIS XSD (https://ref.gs1.org/standards/epcis/epcglobal-epcis-2_0.xsd, a normative
+ * artefact of EPCIS 2.0 / ISO/IEC 19987), verbatim and anchored.
+ *
+ * - The pattern is the XML binding's. The JSON schema types the same field as a string with
+ *   `format: date-time` and gives no pattern, so this is the stricter of the two bindings.
+ * - A date-time with seconds required, an optional fraction of any length, then `Z` or an offset
+ *   in the same range as `epcisTimeZoneOffset`.
+ * - GS1 published the grammar, so it is neither loosened nor tightened here: four-digit years
+ *   only, upper-case `T` and `Z`, a colon in the offset, no space separator.
+ * - Shape only; calendar validity is Temporal's (`2023-02-29T00:00:00Z` matches and
+ *   `Temporal.Instant.from` rejects it). To check that a string is a real `eventTime`, use
+ *   `isValidEpcisEventTime`: this pattern also matches a day that does not exist and a fraction
+ *   longer than nine digits.
+ *
+ * Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second, 7 fraction with its
+ * period (optional), 8 `Z` or the offset, 9 the offset, 10 sign, 11 hours-and-minutes or
+ * `14:00`, 12 hours, 13 minutes.
+ *
+ * @example epcisEventTime.test("2024-06-15T14:30:00Z")           // true
+ * @example epcisEventTime.test("2024-06-15T14:30:00.123-05:00")  // true
+ * @example epcisEventTime.test("2024-06-15T14:30Z")              // false (seconds are required)
+ * @example epcisEventTime.test("2024-06-15T14:30:00")            // false (Z or an offset is required)
+ * @example epcisEventTime.test("2024-06-15T14:30:00+15:00")      // false (offset past the range GS1 allows)
+ */
+export const epcisEventTime = /^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9]+)?(Z|(([+]|[-])((0[0-9]|1[0-3]):([0-5][0-9])|14:00)))$/;

package/dist/regex/http-date.d.ts

@@ -1,13 +1,15 @@
 /**
- * RegExp matching RFC 9110 §5.6.7 IMF-fixdate — the only form GMT's `formatHttp` emits and
+ * RegExp matching RFC 9110 §5.6.7 IMF-fixdate — the only form GMT's `formatHttpDate` emits and
  * the preferred HTTP-date form. Day, year, and time-of-day fields are all fixed-width per the
  * grammar (unlike RFC 5322's leniently-sized day); the trailing "GMT" literal is mandatory,
  * never a numeric offset.
  *
  * - **IMF-fixdate only.** RFC 9110 requires a recipient to accept all three HTTP-date formats;
- *   the obsolete rfc850-date and asctime-date do not match this pattern. `parseHttp` reads all
+ *   the obsolete rfc850-date and asctime-date do not match this pattern. `parseHttpDate` reads all
  *   three.
- * - The day name is not checked against the date; `parseHttp` does check it.
+ * - The day name is not checked against the date; `parseHttpDate` does check it.
+ * - To check that a string is a real HTTP-date, use `isValidHttpDate`: this pattern also matches
+ *   a day that does not exist and an hour out of range.
  *
  * Capture groups: 1 day-of-week, 2 day, 3 month, 4 year, 5 hour, 6 minute, 7 second.
  *
@@ -15,6 +17,6 @@
  * @example httpDate.test("Jun 09 2021 10:18:14 GMT")      // false (missing day-of-week)
  * @example httpDate.test("Wed, 9 Jun 2021 10:18:14 GMT")  // false (single-digit day)
  * @example httpDate.test("Wed, 09 Jun 2021 10:18:14 +0000") // false (numeric offset)
- * @example httpDate.test("Wednesday, 09-Jun-21 10:18:14 GMT") // false (rfc850-date: parseHttp reads it)
+ * @example httpDate.test("Wednesday, 09-Jun-21 10:18:14 GMT") // false (rfc850-date: parseHttpDate reads it)
  */
 export declare const httpDate: RegExp;

package/dist/regex/http-date.js

@@ -1,13 +1,15 @@
 /**
- * RegExp matching RFC 9110 §5.6.7 IMF-fixdate — the only form GMT's `formatHttp` emits and
+ * RegExp matching RFC 9110 §5.6.7 IMF-fixdate — the only form GMT's `formatHttpDate` emits and
  * the preferred HTTP-date form. Day, year, and time-of-day fields are all fixed-width per the
  * grammar (unlike RFC 5322's leniently-sized day); the trailing "GMT" literal is mandatory,
  * never a numeric offset.
  *
  * - **IMF-fixdate only.** RFC 9110 requires a recipient to accept all three HTTP-date formats;
- *   the obsolete rfc850-date and asctime-date do not match this pattern. `parseHttp` reads all
+ *   the obsolete rfc850-date and asctime-date do not match this pattern. `parseHttpDate` reads all
  *   three.
- * - The day name is not checked against the date; `parseHttp` does check it.
+ * - The day name is not checked against the date; `parseHttpDate` does check it.
+ * - To check that a string is a real HTTP-date, use `isValidHttpDate`: this pattern also matches
+ *   a day that does not exist and an hour out of range.
  *
  * Capture groups: 1 day-of-week, 2 day, 3 month, 4 year, 5 hour, 6 minute, 7 second.
  *
@@ -15,6 +17,6 @@
  * @example httpDate.test("Jun 09 2021 10:18:14 GMT")      // false (missing day-of-week)
  * @example httpDate.test("Wed, 9 Jun 2021 10:18:14 GMT")  // false (single-digit day)
  * @example httpDate.test("Wed, 09 Jun 2021 10:18:14 +0000") // false (numeric offset)
- * @example httpDate.test("Wednesday, 09-Jun-21 10:18:14 GMT") // false (rfc850-date: parseHttp reads it)
+ * @example httpDate.test("Wednesday, 09-Jun-21 10:18:14 GMT") // false (rfc850-date: parseHttpDate reads it)
  */
 export const httpDate = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\d{2}) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{4}) (\d{2}):(\d{2}):(\d{2}) GMT$/;

package/dist/regex/index.d.ts

@@ -3,6 +3,7 @@ export * from "./calendar-date.js";
 export * from "./calendar-zoned-date-time.js";
 export * from "./date.js";
 export * from "./date-time.js";
+export * from "./epcis.js";
 export * from "./http-date.js";
 export * from "./leap-second.js";
 export * from "./nanoseconds.js";

package/dist/regex/index.js

@@ -4,6 +4,7 @@ export * from "./calendar-date.js";
 export * from "./calendar-zoned-date-time.js";
 export * from "./date.js";
 export * from "./date-time.js";
+export * from "./epcis.js";
 export * from "./http-date.js";
 export * from "./leap-second.js";
 export * from "./nanoseconds.js";

package/dist/regex/rfc-2822.d.ts

@@ -13,6 +13,8 @@
  *   `parseRfc2822` reads the full receiver grammar — use it to decode a header, and this
  *   pattern only to check that a string has the strict shape.
  * - The day-of-week is not checked against the date; `parseRfc2822` does check it.
+ * - To check that a string is a real RFC 5322 date-time, use `isValidRfc2822DateTime`: this
+ *   pattern also matches a day that does not exist and an hour or zone out of range.
  *
  * Capture groups: 1 day-of-week (optional, for weekday-prefixed form), 2 day, 3 month,
  * 4 year, 5 hour, 6 minute, 7 second (optional), 8 zone.

package/dist/regex/rfc-2822.js

@@ -13,6 +13,8 @@
  *   `parseRfc2822` reads the full receiver grammar — use it to decode a header, and this
  *   pattern only to check that a string has the strict shape.
  * - The day-of-week is not checked against the date; `parseRfc2822` does check it.
+ * - To check that a string is a real RFC 5322 date-time, use `isValidRfc2822DateTime`: this
+ *   pattern also matches a day that does not exist and an hour or zone out of range.
  *
  * Capture groups: 1 day-of-week (optional, for weekday-prefixed form), 2 day, 3 month,
  * 4 year, 5 hour, 6 minute, 7 second (optional), 8 zone.

package/dist/regex/rfc-3339.d.ts

@@ -11,7 +11,9 @@
  *   `:59`), and the fraction is capped at 9 digits (`time-secfrac` is `1*DIGIT`; Temporal keeps
  *   nanoseconds).
  * - Shape-only validation; real calendar validation is delegated to
- *   `Temporal.PlainDateTime.from(...).toZonedDateTime(offset)` in `parseRfc3339`.
+ *   `Temporal.PlainDateTime.from(...).toZonedDateTime(offset)` in `parseRfc3339`. To check that a
+ *   string is a real RFC 3339 date-time, use `isValidRfc3339DateTime`: this pattern also matches
+ *   a day that does not exist, such as 29 February 2023.
  * - Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second,
  *   7 fractional (optional), 8 offset.
  *

package/dist/regex/rfc-3339.js

@@ -11,7 +11,9 @@
  *   `:59`), and the fraction is capped at 9 digits (`time-secfrac` is `1*DIGIT`; Temporal keeps
  *   nanoseconds).
  * - Shape-only validation; real calendar validation is delegated to
- *   `Temporal.PlainDateTime.from(...).toZonedDateTime(offset)` in `parseRfc3339`.
+ *   `Temporal.PlainDateTime.from(...).toZonedDateTime(offset)` in `parseRfc3339`. To check that a
+ *   string is a real RFC 3339 date-time, use `isValidRfc3339DateTime`: this pattern also matches
+ *   a day that does not exist, such as 29 February 2023.
  * - Capture groups: 1 year, 2 month, 3 day, 4 hour, 5 minute, 6 second,
  *   7 fractional (optional), 8 offset.
  *

package/dist/regex/sql-date-time.d.ts

@@ -16,7 +16,8 @@
  * - SECOND `60`–`61` does not match, although Table 10 allows them: GMT rejects leap seconds
  *   because Temporal would read one as `:59`.
  * - Shape-only validation; the calendar date is checked by `Temporal.PlainDateTime.from` in
- *   `parseSql`.
+ *   `parseSqlDateTime`. To check that a string is a real SQL timestamp literal, use
+ *   `isValidSqlDateTime`: this pattern also matches a day that does not exist, such as 30 February.
  *
  * Capture groups: 1 month, 2 day, 3 hour. The year, minute, second and fraction are not
  * captured.

package/dist/regex/sql-date-time.js

@@ -16,7 +16,8 @@
  * - SECOND `60`–`61` does not match, although Table 10 allows them: GMT rejects leap seconds
  *   because Temporal would read one as `:59`.
  * - Shape-only validation; the calendar date is checked by `Temporal.PlainDateTime.from` in
- *   `parseSql`.
+ *   `parseSqlDateTime`. To check that a string is a real SQL timestamp literal, use
+ *   `isValidSqlDateTime`: this pattern also matches a day that does not exist, such as 30 February.
  *
  * Capture groups: 1 month, 2 day, 3 hour. The year, minute, second and fraction are not
  * captured.

package/dist/regex/time-zone-like.d.ts

@@ -1,11 +1,12 @@
 /**
  * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
- * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
+ * (§13.31, the ISO 8601 / RFC 9557 grammar),
+ * `TimeZoneIdentifier ::: UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
  *
  * - An offset identifier (`UTCOffset[~SubMinutePrecision]`): an ASCII sign and a two-digit hour
  *   `00`–`23`, optionally followed by two minute digits `00`–`59`, with or without `:` (`+05`,
  *   `+0530`, `-08:00`). No seconds and no fraction. `Intl.DateTimeFormat` accepts the same
- *   offsets (ECMA-402 `IsTimeZoneOffsetString`).
+ *   offsets (ECMA-262 `IsTimeZoneOffsetString`, which ECMA-402 calls).
  * - An IANA name (`TimeZoneIANAName`): one or more `/`-separated components. Each starts with a
  *   letter, `.` or `_` (`TZLeadingChar`) and continues with letters, digits, `.`, `_`, `-` or `+`
  *   (`TZChar`). So single-component names match (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`,

package/dist/regex/time-zone-like.js

@@ -1,11 +1,12 @@
 /**
  * RegExp matching the shape of a time zone identifier: Temporal's `TimeZoneIdentifier` grammar
- * (§14.6.2 Time Zone Identifiers), `UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
+ * (§13.31, the ISO 8601 / RFC 9557 grammar),
+ * `TimeZoneIdentifier ::: UTCOffset[~SubMinutePrecision] | TimeZoneIANAName`.
  *
  * - An offset identifier (`UTCOffset[~SubMinutePrecision]`): an ASCII sign and a two-digit hour
  *   `00`–`23`, optionally followed by two minute digits `00`–`59`, with or without `:` (`+05`,
  *   `+0530`, `-08:00`). No seconds and no fraction. `Intl.DateTimeFormat` accepts the same
- *   offsets (ECMA-402 `IsTimeZoneOffsetString`).
+ *   offsets (ECMA-262 `IsTimeZoneOffsetString`, which ECMA-402 calls).
  * - An IANA name (`TimeZoneIANAName`): one or more `/`-separated components. Each starts with a
  *   letter, `.` or `_` (`TZLeadingChar`) and continues with letters, digits, `.`, `_`, `-` or `+`
  *   (`TZChar`). So single-component names match (`UTC`, `Japan`, `Zulu`, `EST5EDT`, `GMT+0`,

package/dist/regex/utc-offset.d.ts

@@ -12,7 +12,8 @@
  * - Sub-second offsets are rejected. ISO 8601 permits them and `Temporal.Instant.from` parses
  *   them, but no zone, and no standard that stores this pair, has ever used one.
  * - Shape only. Whether the offset is in Temporal's representable range is a separate check —
- *   `internal/utcOffsetString.ts` applies both.
+ *   `internal/utcOffsetString.ts` applies both. To check a value that may not be a string, use
+ *   `isValidUtcOffset`: for a string it gives this pattern's answer.
  *
  * @example utcOffset.test("-04:00") // true
  * @example utcOffset.test("+05:45") // true

package/dist/regex/utc-offset.js

@@ -12,7 +12,8 @@
  * - Sub-second offsets are rejected. ISO 8601 permits them and `Temporal.Instant.from` parses
  *   them, but no zone, and no standard that stores this pair, has ever used one.
  * - Shape only. Whether the offset is in Temporal's representable range is a separate check —
- *   `internal/utcOffsetString.ts` applies both.
+ *   `internal/utcOffsetString.ts` applies both. To check a value that may not be a string, use
+ *   `isValidUtcOffset`: for a string it gives this pattern's answer.
  *
  * @example utcOffset.test("-04:00") // true
  * @example utcOffset.test("+05:45") // true

package/dist/span/calculate/spanMs.d.ts

@@ -16,9 +16,14 @@
  *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
  *   which is the one string shape `spanWallClock` accepts and these two do not. The
  *   endpoints need not share a zone; an instant is an instant.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
- *   with the offset is not checked. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing. `spanWallClock`, by
+ *   contrast, rejects a mismatched offset.
  * - Returns `null` on invalid input, not `0` — `0` is the span between an instant and itself.
  *   `null`, not `NaN`, because that is GMT's sentinel for every number-returning function:
  *   it is the one a caller already checks for, and the only one `strictNullChecks` forces
@@ -45,7 +50,8 @@
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z") // 123.456789
  * @example spanMs("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 82800000 — 23 hours, not 24
- * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is ignored
+ * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is not checked
+ * @example spanMs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0 — the zone's −00:44:30, which `-00:45` rounds
  * @example spanMs("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // null — past the safe integer range, use spanNs
  * @example spanMs("2024-03-10T12:00:00Z", "invalid") // null
  */

package/dist/span/calculate/spanMs.js

@@ -28,9 +28,14 @@ const MAX_SAFE_NANOSECONDS = BigInt(Number.MAX_SAFE_INTEGER) * NANOSECONDS_PER_M
  *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
  *   which is the one string shape `spanWallClock` accepts and these two do not. The
  *   endpoints need not share a zone; an instant is an instant.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
- *   with the offset is not checked. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing. `spanWallClock`, by
+ *   contrast, rejects a mismatched offset.
  * - Returns `null` on invalid input, not `0` — `0` is the span between an instant and itself.
  *   `null`, not `NaN`, because that is GMT's sentinel for every number-returning function:
  *   it is the one a caller already checks for, and the only one `strictNullChecks` forces
@@ -57,7 +62,8 @@ const MAX_SAFE_NANOSECONDS = BigInt(Number.MAX_SAFE_INTEGER) * NANOSECONDS_PER_M
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0
  * @example spanMs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00.123456789Z") // 123.456789
  * @example spanMs("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 82800000 — 23 hours, not 24
- * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is ignored
+ * @example spanMs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000 — offsets decide, the zone is not checked
+ * @example spanMs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0 — the zone's −00:44:30, which `-00:45` rounds
  * @example spanMs("-271821-04-20T00:00:00Z", "+275760-09-13T00:00:00Z") // null — past the safe integer range, use spanNs
  * @example spanMs("2024-03-10T12:00:00Z", "invalid") // null
  */

package/dist/span/calculate/spanNs.d.ts

@@ -14,9 +14,14 @@
  *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
  *   which is the one string shape `spanWallClock` accepts and these two do not. The
  *   endpoints need not share a zone; an instant is an instant.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
- *   with the offset is not checked. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing. `spanWallClock`, by
+ *   contrast, rejects a mismatched offset.
  * - Returns `null` on invalid input, not `0n` — `0n` is the span between an instant and
  *   itself. This is why it does not simply subtract two `toNanoseconds` results, which
  *   return `0n` for both the epoch and a rejected string.
@@ -37,7 +42,8 @@
  * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0n
  * @example spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z") // 1n
  * @example spanNs("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
- * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is ignored
+ * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is not checked
+ * @example spanNs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0n — the zone's −00:44:30, which `-00:45` rounds
  * @example spanNs("2024-03-10T12:00:00Z", "invalid") // null
  */
 export declare function spanNs(start: string, end: string): bigint | null;

package/dist/span/calculate/spanNs.js

@@ -15,9 +15,14 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  *   required, optionally followed by a bracketed IANA zone — a bracket alone is not enough,
  *   which is the one string shape `spanWallClock` accepts and these two do not. The
  *   endpoints need not share a zone; an instant is an instant.
- * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
- *   ignored: each offset alone fixes its instant, and a zone that does not exist or disagrees
- *   with the offset is not checked. `spanWallClock`, by contrast, rejects a mismatched offset.
+ * - **The offset fixes the instant; a bracketed zone only resolves a rounded one.** An offset
+ *   written to the minute that is the bracketed zone's sub-minute offset rounded
+ *   (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the zone gives, as
+ *   `Temporal.ZonedDateTime.from` reads it, so a zoned string Temporal wrote is read back as
+ *   the instant it was written for, except a wall time repeated inside a sub-minute offset
+ *   change, which reads as its first pass (see `isValidInstant`). Otherwise the bracket is not
+ *   checked: a zone that does not exist, or that disagrees with the offset, changes nothing. `spanWallClock`, by
+ *   contrast, rejects a mismatched offset.
  * - Returns `null` on invalid input, not `0n` — `0n` is the span between an instant and
  *   itself. This is why it does not simply subtract two `toNanoseconds` results, which
  *   return `0n` for both the epoch and a rejected string.
@@ -38,7 +43,8 @@ import { parseInstantNanoseconds } from "../../internal/index.js";
  * @example spanNs("2024-03-10T12:00:00Z", "2024-03-10T12:00:00Z") // 0n
  * @example spanNs("2024-03-10T12:00:00.123456789Z", "2024-03-10T12:00:00.123456790Z") // 1n
  * @example spanNs("2024-03-10T07:00:00-05:00[America/New_York]", "2024-03-10T12:00:00Z") // 0n — same instant, different zones
- * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is ignored
+ * @example spanNs("2024-03-10T12:00:00+05:00[America/New_York]", "2024-03-10T12:00:00-04:00[America/New_York]") // 32400000000000n — offsets decide, the zone is not checked
+ * @example spanNs("1960-01-01T01:04:30Z", "1960-01-01T00:20:00-00:45[Africa/Monrovia]") // 0n — the zone's −00:44:30, which `-00:45` rounds
  * @example spanNs("2024-03-10T12:00:00Z", "invalid") // null
  */
 export function spanNs(start, end) {