@northguild/gmt 1.17.0 → 1.19.0

package/dist/intermodal/parse/classifyX12TimeCode.js

@@ -0,0 +1,57 @@
+import { x12TimeCodeOffset } from "./x12TimeCodeOffset.js";
+import { x12TimeCodeZone } from "./x12TimeCodeZone.js";
+/**
+ * Say whether an X12 time code (data element 623) states an offset or names a zone, and return
+ * the code narrowed to the function that reads it.
+ *
+ * Data element 623 is the code beside the date and time of an X12 `AT7`, `G62` or `DTM`
+ * segment. 31 of its 56 codes state an offset from UTC and 25 name a zone, and each group has
+ * its own reader. A segment reader holds the code as a plain string: it calls this function,
+ * tests `kind`, and passes `timeCode` on. Testing `kind` narrows `timeCode` to that reader's
+ * union, so the call needs no cast. Codes are release 008010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-008010/element/623); the X12
+ * text itself was not reached.
+ *
+ * ### Kinds
+ * | `kind` | Codes | Read by |
+ * |---|---|---|
+ * | `"offset"` | `01`–`29`, `UT`, `GM` | `x12TimeCodeOffset` |
+ * | `"zone"` | `AD`, `AS`, `AT`, `CD`, `CS`, `CT`, `ED`, `ES`, `ET`, `HD`, `HS`, `HT`, `MD`, `MS`, `MT`, `ND`, `NS`, `NT`, `PD`, `PS`, `PT`, `TD`, `TS`, `TT`, `LT` | `x12TimeCodeZone` |
+ *
+ * - **The narrowing pattern.** With `const classified = classifyX12TimeCode(code)`, the line
+ *   `if (classified?.kind === "offset") x12TimeCodeOffset(classified.timeCode)` compiles with
+ *   no cast: inside the test, `classified.timeCode` is `X12OffsetTimeCode`. The `"zone"` branch
+ *   passes `classified.timeCode` to `x12TimeCodeZone` the same way.
+ * - Both members are always present, and each call returns a new object.
+ * - `GM` ("Greenwich Mean Time") is an offset code: GMT reads it as `+00:00`, as
+ *   `x12TimeCodeOffset` explains.
+ * - `25`–`29` were added in release 006010. The function takes no release, so it reads them.
+ * - This is a time code, not a format qualifier: `TS` here is Atlantic Standard Time. Classify
+ *   a data element 1250 code with `classifyX12DateTimePeriodFormat`.
+ * - Matching is exact: two characters, upper case, no padding.
+ * - Returns `null` for a code that is not one of the 56 and for a non-string. It returns a
+ *   result exactly when `isValidX12TimeCode` is true.
+ *
+ * @param timeCode X12 data element 623 time code, as it arrives (e.g. "20")
+ * @returns `{ kind, timeCode }`, or null on invalid input
+ *
+ * @example classifyX12TimeCode("20") // { kind: "offset", timeCode: "20" }
+ * @example classifyX12TimeCode("UT") // { kind: "offset", timeCode: "UT" }
+ * @example classifyX12TimeCode("GM") // { kind: "offset", timeCode: "GM" }
+ * @example classifyX12TimeCode("ES") // { kind: "zone", timeCode: "ES" }
+ * @example classifyX12TimeCode("ET") // { kind: "zone", timeCode: "ET" }
+ * @example classifyX12TimeCode("LT") // { kind: "zone", timeCode: "LT" }
+ * @example classifyX12TimeCode("EST") // null (not a 623 code)
+ * @example classifyX12TimeCode("et") // null (matching is exact)
+ */
+export function classifyX12TimeCode(timeCode) {
+    // Each reader owns the list of its codes and returns its sentinel for any other value, so a
+    // code is an offset code exactly when the offset reader reads it.
+    if (x12TimeCodeOffset(timeCode) !== "") {
+        return { kind: "offset", timeCode: timeCode };
+    }
+    if (x12TimeCodeZone(timeCode) !== null) {
+        return { kind: "zone", timeCode: timeCode };
+    }
+    return null;
+}

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

@@ -0,0 +1,18 @@
+export * from "./classifyEdifactDtmFormat.js";
+export * from "./classifyX12DateTimePeriodFormat.js";
+export * from "./classifyX12TimeCode.js";
+export * from "./parseEdifactDate.js";
+export * from "./parseEdifactDatePeriod.js";
+export * from "./parseEdifactDateTime.js";
+export * from "./parseEdifactDateTimePeriod.js";
+export * from "./parseEdifactOffsetDateTime.js";
+export * from "./parseEdifactTime.js";
+export * from "./parseEpcisEvent.js";
+export * from "./parseX12Date.js";
+export * from "./parseX12DateAndTime.js";
+export * from "./parseX12DateRange.js";
+export * from "./parseX12DateTime.js";
+export * from "./parseX12DateTimeRange.js";
+export * from "./parseX12Time.js";
+export * from "./x12TimeCodeOffset.js";
+export * from "./x12TimeCodeZone.js";

package/dist/intermodal/parse/index.js

@@ -0,0 +1,18 @@
+export * from "./classifyEdifactDtmFormat.js";
+export * from "./classifyX12DateTimePeriodFormat.js";
+export * from "./classifyX12TimeCode.js";
+export * from "./parseEdifactDate.js";
+export * from "./parseEdifactDatePeriod.js";
+export * from "./parseEdifactDateTime.js";
+export * from "./parseEdifactDateTimePeriod.js";
+export * from "./parseEdifactOffsetDateTime.js";
+export * from "./parseEdifactTime.js";
+export * from "./parseEpcisEvent.js";
+export * from "./parseX12Date.js";
+export * from "./parseX12DateAndTime.js";
+export * from "./parseX12DateRange.js";
+export * from "./parseX12DateTime.js";
+export * from "./parseX12DateTimeRange.js";
+export * from "./parseX12Time.js";
+export * from "./x12TimeCodeOffset.js";
+export * from "./x12TimeCodeZone.js";

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

@@ -0,0 +1,37 @@
+import type { EdifactDateFormat } from "../../types/edi.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a calendar date, as an ISO 8601 date.
+ *
+ * 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 code whose value is a date. 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 |
+ * |---|---|---|
+ * | `102` | `CCYYMMDD` | "Calendar date: C = Century ; Y = Year ; M = Month ; D = Day." |
+ *
+ * - The value must be the eight digits of the mask and nothing else: a hyphen, a space or a
+ *   ninth digit returns `""`.
+ * - Fields are checked, not clamped: month 13, 31 June and 29 February 2023 return `""`.
+ * - The year is the four digits as written, `0000` to `9999`.
+ * - A two-digit year (`101`, `YYMMDD`) is not read: UN/EDIFACT 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 (`203` is read by
+ *   `parseEdifactDateTime`); `classifyEdifactDtmFormat` names the kind of a code. Returns `""`
+ *   for a non-string argument.
+ *
+ * @param value The data element 2380 value (e.g. "20240615")
+ * @param format The data element 2379 format code
+ * @returns the date as `YYYY-MM-DD`, or "" on invalid input
+ *
+ * @example parseEdifactDate("20240615", "102") // "2024-06-15"
+ * @example parseEdifactDate("20240229", "102") // "2024-02-29"
+ * @example parseEdifactDate("20230229", "102") // "" (2023 has no 29 February)
+ * @example parseEdifactDate("2024-06-15", "102") // "" (the value is the digits of the mask)
+ * @example parseEdifactDate("240615", "102") // "" (a two-digit year is not read)
+ * @example parseEdifactDate("202406151430", "203") // "" (a date-time code: use parseEdifactDateTime)
+ */
+export declare function parseEdifactDate(value: string, format: EdifactDateFormat): string;

package/dist/intermodal/parse/parseEdifactDate.js

@@ -0,0 +1,45 @@
+import { readEdiValue } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a calendar date, as an ISO 8601 date.
+ *
+ * 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 code whose value is a date. 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 |
+ * |---|---|---|
+ * | `102` | `CCYYMMDD` | "Calendar date: C = Century ; Y = Year ; M = Month ; D = Day." |
+ *
+ * - The value must be the eight digits of the mask and nothing else: a hyphen, a space or a
+ *   ninth digit returns `""`.
+ * - Fields are checked, not clamped: month 13, 31 June and 29 February 2023 return `""`.
+ * - The year is the four digits as written, `0000` to `9999`.
+ * - A two-digit year (`101`, `YYMMDD`) is not read: UN/EDIFACT 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 (`203` is read by
+ *   `parseEdifactDateTime`); `classifyEdifactDtmFormat` names the kind of a code. Returns `""`
+ *   for a non-string argument.
+ *
+ * @param value The data element 2380 value (e.g. "20240615")
+ * @param format The data element 2379 format code
+ * @returns the date as `YYYY-MM-DD`, or "" on invalid input
+ *
+ * @example parseEdifactDate("20240615", "102") // "2024-06-15"
+ * @example parseEdifactDate("20240229", "102") // "2024-02-29"
+ * @example parseEdifactDate("20230229", "102") // "" (2023 has no 29 February)
+ * @example parseEdifactDate("2024-06-15", "102") // "" (the value is the digits of the mask)
+ * @example parseEdifactDate("240615", "102") // "" (a two-digit year is not read)
+ * @example parseEdifactDate("202406151430", "203") // "" (a date-time code: use parseEdifactDateTime)
+ */
+export function parseEdifactDate(value, format) {
+    try {
+        return readEdiValue("edifact", "date", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { EdiDatePeriod, EdifactDatePeriodFormat } from "../../types/edi.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a period between two calendar dates, 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 |
+ * |---|---|---|
+ * | `718` | `CCYYMMDD-CCYYMMDD` | "A period of time specified by giving the start date followed by the end date (both including century). Data is to be transmitted as consecutive characters without hyphen." |
+ *
+ * - **A period is transmitted without a hyphen, and a hyphen is rejected.** Every directory
+ *   read (twelve, from D.93A to D.22B) says so; the hyphen in the mask is notation.
+ *   `"2024061520240620"` reads and `"20240615-20240620"` returns `null`.
+ * - **`start` and `end` are the two dates as transmitted**, each `YYYY-MM-DD`. The directory
+ *   does not say whether the end date is inside the period: that is the message's to define, so
+ *   no day is added or removed. Pass the pair to the plain interval functions as `(start, end)`,
+ *   for example `intervalLengthDate(period.start, period.end, "days")`; 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: month 13, 31 June and 29 February 2023 return `null`.
+ * - A two-digit year (`717`, `YYMMDD-YYMMDD`) is not read. Split such a value in two and read
+ *   each half with `parseDateWithPattern`, a `yy` pattern and its `yearWindow` option.
+ * - Returns `null` for any other code, a code of another kind included (`719` is read by
+ *   `parseEdifactDateTimePeriod`), and for a non-string argument.
+ *
+ * @param value The data element 2380 value (e.g. "2024061520240620")
+ * @param format The data element 2379 format code
+ * @returns `{ start, end }`, two ISO 8601 dates, or null on invalid input
+ *
+ * @example parseEdifactDatePeriod("2024061520240620", "718") // { start: "2024-06-15", end: "2024-06-20" }
+ * @example parseEdifactDatePeriod("2024061520240615", "718") // { start: "2024-06-15", end: "2024-06-15" }
+ * @example parseEdifactDatePeriod("20240615-20240620", "718") // null (a period is transmitted without a hyphen)
+ * @example parseEdifactDatePeriod("2024062020240615", "718") // null (the end precedes the start)
+ * @example parseEdifactDatePeriod("2023022920240620", "718") // null (2023 has no 29 February)
+ * @example parseEdifactDatePeriod("20240615", "102") // null (a date code: use parseEdifactDate)
+ */
+export declare function parseEdifactDatePeriod(value: string, format: EdifactDatePeriodFormat): EdiDatePeriod | null;

package/dist/intermodal/parse/parseEdifactDatePeriod.js

@@ -0,0 +1,51 @@
+import { readEdiRange } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse a UN/EDIFACT `DTM` value that states a period between two calendar dates, 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 |
+ * |---|---|---|
+ * | `718` | `CCYYMMDD-CCYYMMDD` | "A period of time specified by giving the start date followed by the end date (both including century). Data is to be transmitted as consecutive characters without hyphen." |
+ *
+ * - **A period is transmitted without a hyphen, and a hyphen is rejected.** Every directory
+ *   read (twelve, from D.93A to D.22B) says so; the hyphen in the mask is notation.
+ *   `"2024061520240620"` reads and `"20240615-20240620"` returns `null`.
+ * - **`start` and `end` are the two dates as transmitted**, each `YYYY-MM-DD`. The directory
+ *   does not say whether the end date is inside the period: that is the message's to define, so
+ *   no day is added or removed. Pass the pair to the plain interval functions as `(start, end)`,
+ *   for example `intervalLengthDate(period.start, period.end, "days")`; 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: month 13, 31 June and 29 February 2023 return `null`.
+ * - A two-digit year (`717`, `YYMMDD-YYMMDD`) is not read. Split such a value in two and read
+ *   each half with `parseDateWithPattern`, a `yy` pattern and its `yearWindow` option.
+ * - Returns `null` for any other code, a code of another kind included (`719` is read by
+ *   `parseEdifactDateTimePeriod`), and for a non-string argument.
+ *
+ * @param value The data element 2380 value (e.g. "2024061520240620")
+ * @param format The data element 2379 format code
+ * @returns `{ start, end }`, two ISO 8601 dates, or null on invalid input
+ *
+ * @example parseEdifactDatePeriod("2024061520240620", "718") // { start: "2024-06-15", end: "2024-06-20" }
+ * @example parseEdifactDatePeriod("2024061520240615", "718") // { start: "2024-06-15", end: "2024-06-15" }
+ * @example parseEdifactDatePeriod("20240615-20240620", "718") // null (a period is transmitted without a hyphen)
+ * @example parseEdifactDatePeriod("2024062020240615", "718") // null (the end precedes the start)
+ * @example parseEdifactDatePeriod("2023022920240620", "718") // null (2023 has no 29 February)
+ * @example parseEdifactDatePeriod("20240615", "102") // null (a date code: use parseEdifactDate)
+ */
+export function parseEdifactDatePeriod(value, format) {
+    try {
+        return readEdiRange("edifact", "datePeriod", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { EdifactDateTimeFormat } from "../../types/edi.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 declare function parseEdifactDateTime(value: string, format: EdifactDateTimeFormat): string;

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 "";
+    }
+}