@northguild/gmt 1.18.0 → 1.20.0

package/dist/intermodal/parse/parseEdifactDateTime.js

@@ -0,0 +1,51 @@
+import { readEdiValue } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a date and a time with no offset, as an ISO 8601
+ * local date-time.
+ *
+ * A `DTM` segment carries its value in data element **2380** and, in data element **2379**, the
+ * format code that says how to read it. This function reads the codes whose value is a wall
+ * clock at a place the value does not name. Masks and descriptions are the UNTDID directory's,
+ * read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `203` | `CCYYMMDDHHMM` | "Calendar date including time with minutes" |
+ * | `204` | `CCYYMMDDHHMMSS` | "Calendar date including time with seconds" |
+ *
+ * - **The result is local, never UTC.** It carries no `Z` and no offset: reading a `203` value
+ *   as UTC is the most common EDI timestamp bug. Pass the result and the place's IANA zone to
+ *   `resolveLocal` to get the instant.
+ * - The value must be the digits of its code's mask: `"202406151430"` is a `203` value and not
+ *   a `204` one.
+ * - Seconds are always written in the result, `00` for `203`.
+ * - Fields are checked, not clamped: hour 24, second 60, 31 June and 29 February 2023 return
+ *   `""`.
+ * - A two-digit year (`201`, `202`) is not read: UN/EDIFACT does not say which century it
+ *   belongs to. Read one with
+ *   `parseDateTimeWithPattern("2406151430", "yyMMddHHmm", undefined, { yearWindow: 2000 })`.
+ * - Returns `""` for any other code, a code of another kind included (`205` is read by
+ *   `parseEdifactOffsetDateTime`), and for a non-string argument.
+ *
+ * @param value The data element 2380 value (e.g. "202406151430")
+ * @param format The data element 2379 format code
+ * @returns the local date-time as `YYYY-MM-DDTHH:MM:SS`, or "" on invalid input
+ *
+ * @example parseEdifactDateTime("202406151430", "203") // "2024-06-15T14:30:00"
+ * @example parseEdifactDateTime("20240615143045", "204") // "2024-06-15T14:30:45"
+ * @example parseEdifactDateTime("202406151430", "204") // "" (twelve digits is a 203 value)
+ * @example parseEdifactDateTime("202302291430", "203") // "" (2023 has no 29 February)
+ * @example parseEdifactDateTime("202406152430", "203") // "" (hour 24)
+ * @example parseEdifactDateTime("202406151430+0200", "205") // "" (an offset code: use parseEdifactOffsetDateTime)
+ */
+export function parseEdifactDateTime(value, format) {
+    try {
+        return readEdiValue("edifact", "dateTime", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/intermodal/parse/parseEdifactDateTimePeriod.d.ts

@@ -0,0 +1,45 @@
+import type { EdiDateTimePeriod, EdifactDateTimePeriodFormat } from "../../types/edi.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a period between two local date-times, as its
+ * start and end.
+ *
+ * A `DTM` segment carries its value in data element **2380** and, in data element **2379**, the
+ * format code that says how to read it. The mask and description are the UNTDID directory's,
+ * read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format code
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `719` | `CCYYMMDDHHMM-CCYYMMDDHHMM` | "A period of time which includes the century, year, month, day, hour and minute. Format of period to be given in actual message without hyphen." |
+ *
+ * - **A period is transmitted without a hyphen, and a hyphen is rejected.** The hyphen in the
+ *   mask is notation: `"202406151430202406201600"` reads and `"202406151430-202406201600"`
+ *   returns `null`.
+ * - **`start` and `end` are local date-times as transmitted**, each `YYYY-MM-DDTHH:MM:SS` with
+ *   seconds `00`. The code carries no offset, so neither names an instant: pass each and the
+ *   place's IANA zone to `resolveLocal`.
+ * - The directory does not say whether the end is inside the period. Pass the pair to the plain
+ *   interval functions as `(start, end)`, for example
+ *   `intervalLengthDateTime(period.start, period.end, "hours")`; they leave `end` outside the
+ *   interval.
+ * - **An end before its start returns `null`**: a reversed period names no span of time. An end
+ *   equal to its start is a valid period.
+ * - Fields are checked, not clamped: hour 24, minute 60 and 29 February 2023 return `null`.
+ * - A two-digit year (`713`, `YYMMDDHHMM-YYMMDDHHMM`) is not read. Split such a value in two
+ *   and read each half with `parseDateTimeWithPattern`, a `yy` pattern and its `yearWindow`
+ *   option.
+ * - Returns `null` for any other code, a code of another kind included (`718` is read by
+ *   `parseEdifactDatePeriod`), and for a non-string argument.
+ *
+ * @param value The data element 2380 value (e.g. "202406151430202406201600")
+ * @param format The data element 2379 format code
+ * @returns `{ start, end }`, two ISO 8601 local date-times, or null on invalid input
+ *
+ * @example parseEdifactDateTimePeriod("202406151430202406201600", "719") // { start: "2024-06-15T14:30:00", end: "2024-06-20T16:00:00" }
+ * @example parseEdifactDateTimePeriod("202406151430202406151430", "719") // { start: "2024-06-15T14:30:00", end: "2024-06-15T14:30:00" }
+ * @example parseEdifactDateTimePeriod("202406151430-202406201600", "719") // null (a period is transmitted without a hyphen)
+ * @example parseEdifactDateTimePeriod("202406151431202406151430", "719") // null (the end precedes the start)
+ * @example parseEdifactDateTimePeriod("2024061520240620", "718") // null (a date period code: use parseEdifactDatePeriod)
+ */
+export declare function parseEdifactDateTimePeriod(value: string, format: EdifactDateTimePeriodFormat): EdiDateTimePeriod | null;

package/dist/intermodal/parse/parseEdifactDateTimePeriod.js

@@ -0,0 +1,53 @@
+import { readEdiRange } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a period between two local date-times, as its
+ * start and end.
+ *
+ * A `DTM` segment carries its value in data element **2380** and, in data element **2379**, the
+ * format code that says how to read it. The mask and description are the UNTDID directory's,
+ * read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format code
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `719` | `CCYYMMDDHHMM-CCYYMMDDHHMM` | "A period of time which includes the century, year, month, day, hour and minute. Format of period to be given in actual message without hyphen." |
+ *
+ * - **A period is transmitted without a hyphen, and a hyphen is rejected.** The hyphen in the
+ *   mask is notation: `"202406151430202406201600"` reads and `"202406151430-202406201600"`
+ *   returns `null`.
+ * - **`start` and `end` are local date-times as transmitted**, each `YYYY-MM-DDTHH:MM:SS` with
+ *   seconds `00`. The code carries no offset, so neither names an instant: pass each and the
+ *   place's IANA zone to `resolveLocal`.
+ * - The directory does not say whether the end is inside the period. Pass the pair to the plain
+ *   interval functions as `(start, end)`, for example
+ *   `intervalLengthDateTime(period.start, period.end, "hours")`; they leave `end` outside the
+ *   interval.
+ * - **An end before its start returns `null`**: a reversed period names no span of time. An end
+ *   equal to its start is a valid period.
+ * - Fields are checked, not clamped: hour 24, minute 60 and 29 February 2023 return `null`.
+ * - A two-digit year (`713`, `YYMMDDHHMM-YYMMDDHHMM`) is not read. Split such a value in two
+ *   and read each half with `parseDateTimeWithPattern`, a `yy` pattern and its `yearWindow`
+ *   option.
+ * - Returns `null` for any other code, a code of another kind included (`718` is read by
+ *   `parseEdifactDatePeriod`), and for a non-string argument.
+ *
+ * @param value The data element 2380 value (e.g. "202406151430202406201600")
+ * @param format The data element 2379 format code
+ * @returns `{ start, end }`, two ISO 8601 local date-times, or null on invalid input
+ *
+ * @example parseEdifactDateTimePeriod("202406151430202406201600", "719") // { start: "2024-06-15T14:30:00", end: "2024-06-20T16:00:00" }
+ * @example parseEdifactDateTimePeriod("202406151430202406151430", "719") // { start: "2024-06-15T14:30:00", end: "2024-06-15T14:30:00" }
+ * @example parseEdifactDateTimePeriod("202406151430-202406201600", "719") // null (a period is transmitted without a hyphen)
+ * @example parseEdifactDateTimePeriod("202406151431202406151430", "719") // null (the end precedes the start)
+ * @example parseEdifactDateTimePeriod("2024061520240620", "718") // null (a date period code: use parseEdifactDatePeriod)
+ */
+export function parseEdifactDateTimePeriod(value, format) {
+    try {
+        return readEdiRange("edifact", "dateTimePeriod", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/intermodal/parse/parseEdifactOffsetDateTime.d.ts

@@ -0,0 +1,60 @@
+import type { EdifactOffsetDateTimeFormat } from "../../types/edi.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a date and a time with an offset from UTC, as an
+ * ISO 8601 date-time with its offset.
+ *
+ * A `DTM` segment carries its value in data element **2380** and, in data element **2379**, the
+ * format code that says how to read it. This function reads the codes whose value names an
+ * instant. Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `205` | `CCYYMMDDHHMMZHHMM` | "Calendar date including time and time zone expressed in hours and minutes." |
+ * | `208` | `CCYYMMDDHHMMSSZHHMM` | "Calendar date including time with seconds, with Time Zone" (D.12A and later) |
+ * | `303` | `CCYYMMDDHHMMZZZ` | "See 203 plus Z=Time zone." |
+ * | `304` | `CCYYMMDDHHMMSSZZZ` | "See 204 plus Z=Time zone." |
+ *
+ * - **The result is the wall clock as written, with its offset**: `YYYY-MM-DDTHH:MM:SS±HH:MM`,
+ *   on its own day and never moved to UTC. It is the string `fromOffsetInstant` writes, so
+ *   `toOffsetInstant` reads it as the instant and the offset, and every function that takes an
+ *   instant takes it.
+ * - **`ZHHMM` (`205`, `208`) is a sign, hours and minutes** (`+0200`, `-0330`). `-0000` is read
+ *   as `+00:00`.
+ * - **`ZZZ` (`303`, `304`) is read as an offset only.** A signed hour from `00` to `23` (`+02`,
+ *   `-05`) is that offset: UN/ECE Recommendation 7 ¶12 appends the difference from UTC "in hours
+ *   and minutes, or hours only, with a leading "+" or "-" sign". The literals `UTC` and `GMT`
+ *   are `+00:00`: the SMDG container-shipping guides write `UTC` in a `303` value, and
+ *   Recommendation 7 ¶12 names one scale by both names, "Co-ordinated Universal Time (formerly
+ *   known as Greenwich Mean Time)".
+ * - **Any other three characters return `""`**, letters such as `CET` included: the directory
+ *   says only "Z = Time zone", no standard defines an abbreviation, and GMT does not guess what
+ *   one means. Where a partner sends one, read the wall clock with `parseEdifactDateTime` after
+ *   removing the three letters, and resolve it in the IANA zone you map them to with
+ *   `resolveLocal`.
+ * - **Pass the unescaped element value.** `+` is the EDIFACT data element separator, so an
+ *   interchange transmits `+02` as `?+02`. Remove the release character first:
+ *   `"202406151430?+02"` returns `""`.
+ * - Seconds are always written in the result, `00` for `205` and `303`. Fields are checked, not
+ *   clamped: hour 24, second 60 and 29 February 2023 return `""`.
+ * - A two-digit year (`206`, `207`, `301`, `302`) is not read.
+ * - Returns `""` for any other code, a code of another kind included (`203` is read by
+ *   `parseEdifactDateTime`), and for a non-string argument.
+ *
+ * @param value The data element 2380 value, unescaped (e.g. "202406151430+0200")
+ * @param format The data element 2379 format code
+ * @returns the date-time with its offset as `YYYY-MM-DDTHH:MM:SS±HH:MM`, or "" on invalid input
+ *
+ * @example parseEdifactOffsetDateTime("202406151430+0200", "205") // "2024-06-15T14:30:00+02:00"
+ * @example parseEdifactOffsetDateTime("20240615143045+0530", "208") // "2024-06-15T14:30:45+05:30"
+ * @example parseEdifactOffsetDateTime("202406151430+02", "303") // "2024-06-15T14:30:00+02:00"
+ * @example parseEdifactOffsetDateTime("20240615143045-05", "304") // "2024-06-15T14:30:45-05:00"
+ * @example parseEdifactOffsetDateTime("202406151430UTC", "303") // "2024-06-15T14:30:00+00:00"
+ * @example parseEdifactOffsetDateTime("202406151430GMT", "303") // "2024-06-15T14:30:00+00:00"
+ * @example parseEdifactOffsetDateTime("202406151430CET", "303") // "" (an abbreviation names no offset)
+ * @example parseEdifactOffsetDateTime("202406151430+24", "303") // "" (not a signed hour)
+ * @example parseEdifactOffsetDateTime("202406151430?+02", "303") // "" (the release character is the caller's to remove)
+ * @example parseEdifactOffsetDateTime("202406151430", "203") // "" (a local code: use parseEdifactDateTime)
+ */
+export declare function parseEdifactOffsetDateTime(value: string, format: EdifactOffsetDateTimeFormat): string;

package/dist/intermodal/parse/parseEdifactOffsetDateTime.js

@@ -0,0 +1,68 @@
+import { readEdiValue } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a date and a time with an offset from UTC, as an
+ * ISO 8601 date-time with its offset.
+ *
+ * A `DTM` segment carries its value in data element **2380** and, in data element **2379**, the
+ * format code that says how to read it. This function reads the codes whose value names an
+ * instant. Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `205` | `CCYYMMDDHHMMZHHMM` | "Calendar date including time and time zone expressed in hours and minutes." |
+ * | `208` | `CCYYMMDDHHMMSSZHHMM` | "Calendar date including time with seconds, with Time Zone" (D.12A and later) |
+ * | `303` | `CCYYMMDDHHMMZZZ` | "See 203 plus Z=Time zone." |
+ * | `304` | `CCYYMMDDHHMMSSZZZ` | "See 204 plus Z=Time zone." |
+ *
+ * - **The result is the wall clock as written, with its offset**: `YYYY-MM-DDTHH:MM:SS±HH:MM`,
+ *   on its own day and never moved to UTC. It is the string `fromOffsetInstant` writes, so
+ *   `toOffsetInstant` reads it as the instant and the offset, and every function that takes an
+ *   instant takes it.
+ * - **`ZHHMM` (`205`, `208`) is a sign, hours and minutes** (`+0200`, `-0330`). `-0000` is read
+ *   as `+00:00`.
+ * - **`ZZZ` (`303`, `304`) is read as an offset only.** A signed hour from `00` to `23` (`+02`,
+ *   `-05`) is that offset: UN/ECE Recommendation 7 ¶12 appends the difference from UTC "in hours
+ *   and minutes, or hours only, with a leading "+" or "-" sign". The literals `UTC` and `GMT`
+ *   are `+00:00`: the SMDG container-shipping guides write `UTC` in a `303` value, and
+ *   Recommendation 7 ¶12 names one scale by both names, "Co-ordinated Universal Time (formerly
+ *   known as Greenwich Mean Time)".
+ * - **Any other three characters return `""`**, letters such as `CET` included: the directory
+ *   says only "Z = Time zone", no standard defines an abbreviation, and GMT does not guess what
+ *   one means. Where a partner sends one, read the wall clock with `parseEdifactDateTime` after
+ *   removing the three letters, and resolve it in the IANA zone you map them to with
+ *   `resolveLocal`.
+ * - **Pass the unescaped element value.** `+` is the EDIFACT data element separator, so an
+ *   interchange transmits `+02` as `?+02`. Remove the release character first:
+ *   `"202406151430?+02"` returns `""`.
+ * - Seconds are always written in the result, `00` for `205` and `303`. Fields are checked, not
+ *   clamped: hour 24, second 60 and 29 February 2023 return `""`.
+ * - A two-digit year (`206`, `207`, `301`, `302`) is not read.
+ * - Returns `""` for any other code, a code of another kind included (`203` is read by
+ *   `parseEdifactDateTime`), and for a non-string argument.
+ *
+ * @param value The data element 2380 value, unescaped (e.g. "202406151430+0200")
+ * @param format The data element 2379 format code
+ * @returns the date-time with its offset as `YYYY-MM-DDTHH:MM:SS±HH:MM`, or "" on invalid input
+ *
+ * @example parseEdifactOffsetDateTime("202406151430+0200", "205") // "2024-06-15T14:30:00+02:00"
+ * @example parseEdifactOffsetDateTime("20240615143045+0530", "208") // "2024-06-15T14:30:45+05:30"
+ * @example parseEdifactOffsetDateTime("202406151430+02", "303") // "2024-06-15T14:30:00+02:00"
+ * @example parseEdifactOffsetDateTime("20240615143045-05", "304") // "2024-06-15T14:30:45-05:00"
+ * @example parseEdifactOffsetDateTime("202406151430UTC", "303") // "2024-06-15T14:30:00+00:00"
+ * @example parseEdifactOffsetDateTime("202406151430GMT", "303") // "2024-06-15T14:30:00+00:00"
+ * @example parseEdifactOffsetDateTime("202406151430CET", "303") // "" (an abbreviation names no offset)
+ * @example parseEdifactOffsetDateTime("202406151430+24", "303") // "" (not a signed hour)
+ * @example parseEdifactOffsetDateTime("202406151430?+02", "303") // "" (the release character is the caller's to remove)
+ * @example parseEdifactOffsetDateTime("202406151430", "203") // "" (a local code: use parseEdifactDateTime)
+ */
+export function parseEdifactOffsetDateTime(value, format) {
+    try {
+        return readEdiValue("edifact", "offsetDateTime", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/intermodal/parse/parseEdifactTime.d.ts

@@ -0,0 +1,37 @@
+import type { EdifactTimeFormat } from "../../types/edi.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a time of day, as an ISO 8601 time.
+ *
+ * A `DTM` segment carries its value in data element **2380** and, in data element **2379**, the
+ * format code that says how to read it. This function reads the codes whose value is a time
+ * with no date and no offset. Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `401` | `HHMM` | "Time without seconds: H = Hour; m = Minute." |
+ * | `402` | `HHMMSS` | "Time with seconds: H = Hour; m = Minute; s = Seconds." |
+ *
+ * - The value must be the digits of its code's mask: `"1430"` is a `401` value and not a `402`
+ *   one.
+ * - Seconds are always written in the result, `00` for `401`.
+ * - Fields are checked, not clamped: hour 24, minute 60 and second 60 return `""`.
+ * - A time with an offset (`209`, `404`) is not read: with no date it names no instant. Read
+ *   the date and time together with `parseEdifactOffsetDateTime` where the partner sends `205`,
+ *   `208`, `303` or `304`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value The data element 2380 value (e.g. "1430")
+ * @param format The data element 2379 format code
+ * @returns the time as `HH:MM:SS`, or "" on invalid input
+ *
+ * @example parseEdifactTime("1430", "401") // "14:30:00"
+ * @example parseEdifactTime("143045", "402") // "14:30:45"
+ * @example parseEdifactTime("143045", "401") // "" (six digits is a 402 value)
+ * @example parseEdifactTime("2400", "401") // "" (hour 24)
+ * @example parseEdifactTime("14:30", "401") // "" (the value is the digits of the mask)
+ * @example parseEdifactTime("20240615", "102") // "" (a date code: use parseEdifactDate)
+ */
+export declare function parseEdifactTime(value: string, format: EdifactTimeFormat): string;

package/dist/intermodal/parse/parseEdifactTime.js

@@ -0,0 +1,45 @@
+import { readEdiValue } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a time of day, as an ISO 8601 time.
+ *
+ * A `DTM` segment carries its value in data element **2380** and, in data element **2379**, the
+ * format code that says how to read it. This function reads the codes whose value is a time
+ * with no date and no offset. Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `401` | `HHMM` | "Time without seconds: H = Hour; m = Minute." |
+ * | `402` | `HHMMSS` | "Time with seconds: H = Hour; m = Minute; s = Seconds." |
+ *
+ * - The value must be the digits of its code's mask: `"1430"` is a `401` value and not a `402`
+ *   one.
+ * - Seconds are always written in the result, `00` for `401`.
+ * - Fields are checked, not clamped: hour 24, minute 60 and second 60 return `""`.
+ * - A time with an offset (`209`, `404`) is not read: with no date it names no instant. Read
+ *   the date and time together with `parseEdifactOffsetDateTime` where the partner sends `205`,
+ *   `208`, `303` or `304`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value The data element 2380 value (e.g. "1430")
+ * @param format The data element 2379 format code
+ * @returns the time as `HH:MM:SS`, or "" on invalid input
+ *
+ * @example parseEdifactTime("1430", "401") // "14:30:00"
+ * @example parseEdifactTime("143045", "402") // "14:30:45"
+ * @example parseEdifactTime("143045", "401") // "" (six digits is a 402 value)
+ * @example parseEdifactTime("2400", "401") // "" (hour 24)
+ * @example parseEdifactTime("14:30", "401") // "" (the value is the digits of the mask)
+ * @example parseEdifactTime("20240615", "102") // "" (a date code: use parseEdifactDate)
+ */
+export function parseEdifactTime(value, format) {
+    try {
+        return readEdiValue("edifact", "time", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/intermodal/parse/parseEpcisEvent.d.ts

@@ -0,0 +1,95 @@
+import type { EpcisEventTime } from "../../types/index.js";
+/**
+ * When a GS1 EPCIS 2.0 event happened, read three ways: the instant, the UTC offset in force
+ * where it happened, and the local wall clock there. The result of `parseEpcisEvent`.
+ *
+ * `instant` and `offset` are the pair `formatEpcisEvent` and `fromOffsetInstant` take, so the
+ * result can be passed to either as it is.
+ */
+export interface EpcisInstant {
+    /**
+     * The moment the event happened, as an ISO 8601 instant in UTC ending in `Z`
+     * (`2024-06-15T14:30:00Z`). It orders events from every site on one timeline. A fraction is
+     * kept to the nanosecond and written without trailing zeros. An `eventTime` whose own offset
+     * carries it across either end of years 0000–9999 gives an instant with a sign and a
+     * six-digit year.
+     */
+    instant: string;
+    /**
+     * The UTC offset in force where the event happened, `±HH:MM`: the event's
+     * `eventTimeZoneOffset`, with `-00:00` written as `+00:00`. It is an offset and not a zone, so
+     * it says nothing about the local time of any other event.
+     */
+    offset: string;
+    /**
+     * The date and time on the local clock where the event happened,
+     * `YYYY-MM-DDTHH:MM:SS[.fraction]` with no offset: `instant` shown at `offset`. Its date can be
+     * the day before or after the UTC date. A year outside 0000–9999, reachable only within 14
+     * hours of either end of the four-digit range, is written with a sign and six digits.
+     */
+    local: string;
+}
+/**
+ * Read the two required time fields of a GS1 EPCIS 2.0 event as an instant, the UTC offset in
+ * force where the event happened, and the local wall clock there.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility: each event records
+ * what happened to which objects, where, when and why.
+ *
+ * - **Both fields are required**, as the EPCIS JSON schema requires them. `eventTime` fixes the
+ *   instant. `eventTimeZoneOffset` is the offset the local clock ran at where the event
+ *   happened, kept so the event can be shown in local time. Neither derives from the other, so
+ *   an event without `eventTimeZoneOffset` returns null: UTC is not assumed.
+ * - **Each field is checked against the stricter of the two bindings.** `eventTime` takes the
+ *   XML binding's pattern (the XSD's `DateTimeStamp`; the JSON schema says only
+ *   `format: date-time`). `eventTimeZoneOffset` takes the JSON schema's pattern (the XSD types
+ *   it as a bare `xsd:string`), which is the rule the standard states in prose, EPCIS Standard
+ *   Release 2.0 §7.4.1 (https://ref.gs1.org/standards/epcis/): an hour "within the range 00
+ *   through 14 (inclusive) … except that if the value of the first two digits is 14, the value
+ *   of the second two digits must be 00".
+ * - **`eventTime`** must match `epcisEventTime`, the `DateTimeStamp` pattern of the EPCIS XSD:
+ *   `YYYY-MM-DDTHH:MM:SS`, an optional fraction, then `Z` or a `±HH:MM` offset up to `14:00`.
+ *   Seconds are required, `T` and `Z` are upper-case, and nothing may follow: a space separator,
+ *   a leap second (`:60`), an expanded year and a bracketed zone or annotation return null. The
+ *   pattern checks shape only, so a day the month does not have (`2024-02-30`) is rejected by
+ *   Temporal and returns null.
+ * - **`eventTimeZoneOffset`** must match `epcisTimeZoneOffset`, the pattern the EPCIS JSON schema
+ *   gives: `±HH:MM` from `-14:00` to `+14:00`. `Z`, `+0200`, `+02` and an offset with seconds
+ *   return null.
+ * - **The two fields are independent and need not agree.** `eventTime` may carry an offset of
+ *   its own instead of `Z`; that offset only fixes the instant. The local clock always comes from
+ *   `eventTimeZoneOffset`, and a difference between the two is not an error. EPCIS 2.0 §7.4.1.1,
+ *   an explanation the standard marks non-normative: "there is no requirement that the time zone
+ *   specifier in the XML representation of eventTime be the local time zone offset where the
+ *   event was captured".
+ * - **An instant can fall outside years 0000–9999.** An `eventTime` whose own offset carries it
+ *   across either end of the four-digit years names an instant just past it, written with a sign
+ *   and a six-digit year, and `local` is written the same way when it falls outside.
+ * - `-00:00` matches the GS1 pattern and is returned as `+00:00`, as `toOffsetInstant` returns
+ *   it. RFC 9557 §2.2 reads `-00:00` as "local offset unknown"; the result cannot say that.
+ * - **GMT rule: a fraction longer than nine digits returns null.** The XSD allows a fraction of
+ *   any length and an instant holds nanoseconds. Dropping digits would report a time the event
+ *   does not state, so the value is refused instead, trailing zeros included.
+ * - `local` is the instant shown at the offset, so its date can differ from the UTC date.
+ * - Only the two fields are read. `recordTime` and every other member of the event are ignored.
+ * - Returns null when `event` is not an object, when either field is missing or not a string,
+ *   and for every case above.
+ *
+ * @param event an EPCIS event, or any object with its `eventTime` and `eventTimeZoneOffset`
+ * @returns `{ instant, offset, local }`, or null on invalid input
+ *
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-05:00" }) // { instant: "2024-06-15T14:30:00Z", offset: "-05:00", local: "2024-06-15T09:30:00" }
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T23:30:00Z", eventTimeZoneOffset: "+02:00" }) // { instant: "2024-06-15T23:30:00Z", offset: "+02:00", local: "2024-06-16T01:30:00" } (the local date is the next day)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T10:00:00+02:00", eventTimeZoneOffset: "+02:00" }) // { instant: "2024-06-15T08:00:00Z", offset: "+02:00", local: "2024-06-15T10:00:00" }
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T10:00:00+02:00", eventTimeZoneOffset: "-05:00" }) // { instant: "2024-06-15T08:00:00Z", offset: "-05:00", local: "2024-06-15T03:00:00" } (the two offsets need not agree)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00.123456789Z", eventTimeZoneOffset: "+05:45" }) // { instant: "2024-06-15T14:30:00.123456789Z", offset: "+05:45", local: "2024-06-15T20:15:00.123456789" }
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-00:00" }) // { instant: "2024-06-15T14:30:00Z", offset: "+00:00", local: "2024-06-15T14:30:00" }
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z" }) // null (eventTimeZoneOffset is required)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "Z" }) // null (a designator, not an offset)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "+0200" }) // null (no colon)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30Z", eventTimeZoneOffset: "+02:00" }) // null (seconds are required)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15 14:30:00Z", eventTimeZoneOffset: "+02:00" }) // null (a space separator)
+ * @example parseEpcisEvent({ eventTime: "2024-02-30T14:30:00Z", eventTimeZoneOffset: "+02:00" }) // null (30 February)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00.1234567891Z", eventTimeZoneOffset: "+02:00" }) // null (finer than a nanosecond)
+ */
+export declare function parseEpcisEvent(event: EpcisEventTime): EpcisInstant | null;

package/dist/intermodal/parse/parseEpcisEvent.js

@@ -0,0 +1,102 @@
+import { Temporal } from "../../internal/temporal.js";
+import { formatUtcOffset, isObject, parseUtcOffsetNanoseconds, wallClockAtOffset, } from "../../internal/index.js";
+import { epcisEventTime, epcisTimeZoneOffset } from "../../regex/index.js";
+/**
+ * Read the two required time fields of a GS1 EPCIS 2.0 event as an instant, the UTC offset in
+ * force where the event happened, and the local wall clock there.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility: each event records
+ * what happened to which objects, where, when and why.
+ *
+ * - **Both fields are required**, as the EPCIS JSON schema requires them. `eventTime` fixes the
+ *   instant. `eventTimeZoneOffset` is the offset the local clock ran at where the event
+ *   happened, kept so the event can be shown in local time. Neither derives from the other, so
+ *   an event without `eventTimeZoneOffset` returns null: UTC is not assumed.
+ * - **Each field is checked against the stricter of the two bindings.** `eventTime` takes the
+ *   XML binding's pattern (the XSD's `DateTimeStamp`; the JSON schema says only
+ *   `format: date-time`). `eventTimeZoneOffset` takes the JSON schema's pattern (the XSD types
+ *   it as a bare `xsd:string`), which is the rule the standard states in prose, EPCIS Standard
+ *   Release 2.0 §7.4.1 (https://ref.gs1.org/standards/epcis/): an hour "within the range 00
+ *   through 14 (inclusive) … except that if the value of the first two digits is 14, the value
+ *   of the second two digits must be 00".
+ * - **`eventTime`** must match `epcisEventTime`, the `DateTimeStamp` pattern of the EPCIS XSD:
+ *   `YYYY-MM-DDTHH:MM:SS`, an optional fraction, then `Z` or a `±HH:MM` offset up to `14:00`.
+ *   Seconds are required, `T` and `Z` are upper-case, and nothing may follow: a space separator,
+ *   a leap second (`:60`), an expanded year and a bracketed zone or annotation return null. The
+ *   pattern checks shape only, so a day the month does not have (`2024-02-30`) is rejected by
+ *   Temporal and returns null.
+ * - **`eventTimeZoneOffset`** must match `epcisTimeZoneOffset`, the pattern the EPCIS JSON schema
+ *   gives: `±HH:MM` from `-14:00` to `+14:00`. `Z`, `+0200`, `+02` and an offset with seconds
+ *   return null.
+ * - **The two fields are independent and need not agree.** `eventTime` may carry an offset of
+ *   its own instead of `Z`; that offset only fixes the instant. The local clock always comes from
+ *   `eventTimeZoneOffset`, and a difference between the two is not an error. EPCIS 2.0 §7.4.1.1,
+ *   an explanation the standard marks non-normative: "there is no requirement that the time zone
+ *   specifier in the XML representation of eventTime be the local time zone offset where the
+ *   event was captured".
+ * - **An instant can fall outside years 0000–9999.** An `eventTime` whose own offset carries it
+ *   across either end of the four-digit years names an instant just past it, written with a sign
+ *   and a six-digit year, and `local` is written the same way when it falls outside.
+ * - `-00:00` matches the GS1 pattern and is returned as `+00:00`, as `toOffsetInstant` returns
+ *   it. RFC 9557 §2.2 reads `-00:00` as "local offset unknown"; the result cannot say that.
+ * - **GMT rule: a fraction longer than nine digits returns null.** The XSD allows a fraction of
+ *   any length and an instant holds nanoseconds. Dropping digits would report a time the event
+ *   does not state, so the value is refused instead, trailing zeros included.
+ * - `local` is the instant shown at the offset, so its date can differ from the UTC date.
+ * - Only the two fields are read. `recordTime` and every other member of the event are ignored.
+ * - Returns null when `event` is not an object, when either field is missing or not a string,
+ *   and for every case above.
+ *
+ * @param event an EPCIS event, or any object with its `eventTime` and `eventTimeZoneOffset`
+ * @returns `{ instant, offset, local }`, or null on invalid input
+ *
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-05:00" }) // { instant: "2024-06-15T14:30:00Z", offset: "-05:00", local: "2024-06-15T09:30:00" }
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T23:30:00Z", eventTimeZoneOffset: "+02:00" }) // { instant: "2024-06-15T23:30:00Z", offset: "+02:00", local: "2024-06-16T01:30:00" } (the local date is the next day)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T10:00:00+02:00", eventTimeZoneOffset: "+02:00" }) // { instant: "2024-06-15T08:00:00Z", offset: "+02:00", local: "2024-06-15T10:00:00" }
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T10:00:00+02:00", eventTimeZoneOffset: "-05:00" }) // { instant: "2024-06-15T08:00:00Z", offset: "-05:00", local: "2024-06-15T03:00:00" } (the two offsets need not agree)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00.123456789Z", eventTimeZoneOffset: "+05:45" }) // { instant: "2024-06-15T14:30:00.123456789Z", offset: "+05:45", local: "2024-06-15T20:15:00.123456789" }
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-00:00" }) // { instant: "2024-06-15T14:30:00Z", offset: "+00:00", local: "2024-06-15T14:30:00" }
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z" }) // null (eventTimeZoneOffset is required)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "Z" }) // null (a designator, not an offset)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "+0200" }) // null (no colon)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30Z", eventTimeZoneOffset: "+02:00" }) // null (seconds are required)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15 14:30:00Z", eventTimeZoneOffset: "+02:00" }) // null (a space separator)
+ * @example parseEpcisEvent({ eventTime: "2024-02-30T14:30:00Z", eventTimeZoneOffset: "+02:00" }) // null (30 February)
+ * @example parseEpcisEvent({ eventTime: "2024-06-15T14:30:00.1234567891Z", eventTimeZoneOffset: "+02:00" }) // null (finer than a nanosecond)
+ */
+export function parseEpcisEvent(event) {
+    try {
+        if (!isObject(event)) {
+            return null;
+        }
+        const { eventTime, eventTimeZoneOffset } = event;
+        if (typeof eventTime !== "string" ||
+            typeof eventTimeZoneOffset !== "string" ||
+            !epcisEventTime.test(eventTime) ||
+            !epcisTimeZoneOffset.test(eventTimeZoneOffset)) {
+            return null;
+        }
+        // `epcisEventTime` admits no bracket, so there is no zone whose minute-rounded offset could
+        // change the reading and `Temporal.Instant.from` is the whole parse. It also does the two
+        // checks the pattern cannot: a day the month does not have, and a fraction past nine digits
+        // (Temporal's grammar stops at nanoseconds), both a RangeError.
+        const instant = Temporal.Instant.from(eventTime);
+        // Temporal reads the offset and writes it back, so `-00:00` comes out as `+00:00` and no
+        // offset digit is sliced by hand.
+        const offsetNanoseconds = parseUtcOffsetNanoseconds(eventTimeZoneOffset);
+        const offset = offsetNanoseconds === null ? null : formatUtcOffset(offsetNanoseconds);
+        if (offsetNanoseconds === null || offset === null) {
+            return null;
+        }
+        return {
+            instant: instant.toString(),
+            offset,
+            local: wallClockAtOffset(instant, offsetNanoseconds).toString(),
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

package/dist/intermodal/parse/parseX12Date.d.ts

@@ -0,0 +1,39 @@
+import type { X12DateFormat } from "../../types/edi.js";
+/**
+ * Parse an X12 Date Time Period value that states a calendar date, as an ISO 8601 date.
+ *
+ * A `DTP` segment carries a format qualifier in `DTP-02` (data element **1250**) and its value
+ * in `DTP-03` (data element **1251**); `DTM-05` and `DTM-06` carry the same pair. This function
+ * reads the codes whose value is a date. Codes are release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/1250); the X12
+ * text itself was not reached.
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `D8` | `CCYYMMDD` | "Date Expressed in Format CCYYMMDD" |
+ * | `DB` | `MMDDCCYY` | "Date Expressed in Format MMDDCCYY" |
+ *
+ * - The value must be the eight digits of its code's mask. The same digits can read two ways,
+ *   so the code decides: `"12112010"` is 11 December 2010 under `DB` and not a date under `D8`.
+ * - **`D8` also reads data element 373 (Date)**, the `CCYYMMDD` date element of `AT7`, `G62`
+ *   and `DTM-02`. To read that date and its time element together, use `parseX12DateAndTime`.
+ * - Fields are checked, not clamped: month 13, 31 June and 29 February 2023 return `""`.
+ * - A two-digit year (`D6` `YYMMDD`, `TT` `MMDDYY`) is not read: X12 does not say which century
+ *   it belongs to. Read one with
+ *   `parseDateWithPattern("240615", "yyMMdd", undefined, { yearWindow: 2000 })`.
+ * - Returns `""` for any other code, a code of another kind included (`DT` is read by
+ *   `parseX12DateTime`), and for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "20240615")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the date as `YYYY-MM-DD`, or "" on invalid input
+ *
+ * @example parseX12Date("20240615", "D8") // "2024-06-15"
+ * @example parseX12Date("06152024", "DB") // "2024-06-15"
+ * @example parseX12Date("20240615", "DB") // "" (20 is not a month)
+ * @example parseX12Date("20230229", "D8") // "" (2023 has no 29 February)
+ * @example parseX12Date("240615", "D8") // "" (a two-digit year is not read)
+ * @example parseX12Date("202406151430", "DT") // "" (a date-time code: use parseX12DateTime)
+ */
+export declare function parseX12Date(value: string, format: X12DateFormat): string;