@northguild/gmt 1.18.0 → 1.20.0

package/dist/intermodal/parse/parseX12Date.js

@@ -0,0 +1,47 @@
+import { readEdiValue } from "../../internal/ediDateTimeFields.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 function parseX12Date(value, format) {
+    try {
+        return readEdiValue("x12", "date", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Read the date and the time of an X12 segment, sent as two elements, as one ISO 8601 local
+ * date-time.
+ *
+ * X12 freight segments carry a moment as separate elements, and this function takes the two as
+ * they are transmitted: `AT7-05` and `AT7-06` (in a 214 shipment status), `G62-02` and `G62-04`
+ * (a 204 load tender) and `DTM-02` and `DTM-03`. Definitions are release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/segment/DTM); the X12
+ * text itself was not reached.
+ *
+ * ### The two elements
+ * | Element | Name | The dictionary's definition |
+ * |---|---|---|
+ * | [373](https://www.stedi.com/edi/x12-005010/element/373) | Date | "Date expressed as CCYYMMDD where CC represents the first two digits of the calendar year" |
+ * | [337](https://www.stedi.com/edi/x12-005010/element/337) | Time | "Time expressed in 24-hour clock time as follows: HHMM, or HHMMSS, or HHMMSSD, or HHMMSSDD" |
+ *
+ * - **The result is local, never UTC.** It has no `Z` and no offset. `AT7` says what a blank
+ *   time code means: "If AT707 is not present then AT706 represents local time of the status".
+ *   Reading the value as UTC is the most common EDI timestamp bug.
+ * - **The time code beside them (data element 623) says where the clock was.** For a code that
+ *   states an offset, resolve the result at that offset:
+ *   `resolveLocal(parseX12DateAndTime("20240615", "1430"), x12TimeCodeOffset("20"))` is
+ *   `"2024-06-15T19:30:00Z"`. For a code that names a zone (`x12TimeCodeZone`), pass the result
+ *   and the IANA zone you map the name to, to `resolveLocal`.
+ * - **Both elements are required.** A missing or empty date or time returns `""`: read a date
+ *   alone with `parseX12Date(value, "D8")` and a time alone with `parseX12Time`.
+ * - The time is one of the four element 337 forms, 4, 6, 7 or 8 digits. Seconds are always
+ *   written, `00` for `HHMM`. Tenths and hundredths become the fraction of the second exactly:
+ *   `14300012` is `14:30:00.12`. A zero fraction is not written.
+ * - **To write the two elements back**, write the date with `formatX12Date(date, "D8")` and the
+ *   time with `formatX12TimeElement`, naming the element 337 form by its mask:
+ *   `formatX12TimeElement("14:30:00.12", "HHMMSSDD")` is `14300012`.
+ * - Fields are checked, not clamped: 29 February 2023, 31 June, hour 24, minute or second 60
+ *   and a time of 5 or 9 digits return `""`.
+ * - The date has a four-digit year. Before release 004010, element 373 was `YYMMDD`: read such
+ *   a date with `parseDateWithPattern("240615", "yyMMdd", undefined, { yearWindow: 2000 })`.
+ * - Returns `""` for a non-string argument.
+ *
+ * @param date The data element 373 date as transmitted, `CCYYMMDD` (e.g. "20240615")
+ * @param time The data element 337 time as transmitted (e.g. "1430")
+ * @returns the local date-time as `YYYY-MM-DDTHH:MM:SS`, with a fraction when the time has one, or "" on invalid input
+ *
+ * @example parseX12DateAndTime("20240615", "1430") // "2024-06-15T14:30:00"
+ * @example parseX12DateAndTime("20240615", "143045") // "2024-06-15T14:30:45"
+ * @example parseX12DateAndTime("20240615", "14300012") // "2024-06-15T14:30:00.12" (hundredths of a second)
+ * @example parseX12DateAndTime("20240615", "") // "" (both elements are required)
+ * @example parseX12DateAndTime("", "1430") // "" (both elements are required)
+ * @example parseX12DateAndTime("20230229", "1430") // "" (2023 has no 29 February)
+ * @example parseX12DateAndTime("20240615", "2430") // "" (hour 24)
+ * @example parseX12DateAndTime("240615", "1430") // "" (the date element has a four-digit year)
+ */
+export declare function parseX12DateAndTime(date: string, time: string): string;

package/dist/intermodal/parse/parseX12DateAndTime.js

@@ -0,0 +1,61 @@
+import { readX12DateAndTime } from "../../internal/ediDateTimeFields.js";
+/**
+ * Read the date and the time of an X12 segment, sent as two elements, as one ISO 8601 local
+ * date-time.
+ *
+ * X12 freight segments carry a moment as separate elements, and this function takes the two as
+ * they are transmitted: `AT7-05` and `AT7-06` (in a 214 shipment status), `G62-02` and `G62-04`
+ * (a 204 load tender) and `DTM-02` and `DTM-03`. Definitions are release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/segment/DTM); the X12
+ * text itself was not reached.
+ *
+ * ### The two elements
+ * | Element | Name | The dictionary's definition |
+ * |---|---|---|
+ * | [373](https://www.stedi.com/edi/x12-005010/element/373) | Date | "Date expressed as CCYYMMDD where CC represents the first two digits of the calendar year" |
+ * | [337](https://www.stedi.com/edi/x12-005010/element/337) | Time | "Time expressed in 24-hour clock time as follows: HHMM, or HHMMSS, or HHMMSSD, or HHMMSSDD" |
+ *
+ * - **The result is local, never UTC.** It has no `Z` and no offset. `AT7` says what a blank
+ *   time code means: "If AT707 is not present then AT706 represents local time of the status".
+ *   Reading the value as UTC is the most common EDI timestamp bug.
+ * - **The time code beside them (data element 623) says where the clock was.** For a code that
+ *   states an offset, resolve the result at that offset:
+ *   `resolveLocal(parseX12DateAndTime("20240615", "1430"), x12TimeCodeOffset("20"))` is
+ *   `"2024-06-15T19:30:00Z"`. For a code that names a zone (`x12TimeCodeZone`), pass the result
+ *   and the IANA zone you map the name to, to `resolveLocal`.
+ * - **Both elements are required.** A missing or empty date or time returns `""`: read a date
+ *   alone with `parseX12Date(value, "D8")` and a time alone with `parseX12Time`.
+ * - The time is one of the four element 337 forms, 4, 6, 7 or 8 digits. Seconds are always
+ *   written, `00` for `HHMM`. Tenths and hundredths become the fraction of the second exactly:
+ *   `14300012` is `14:30:00.12`. A zero fraction is not written.
+ * - **To write the two elements back**, write the date with `formatX12Date(date, "D8")` and the
+ *   time with `formatX12TimeElement`, naming the element 337 form by its mask:
+ *   `formatX12TimeElement("14:30:00.12", "HHMMSSDD")` is `14300012`.
+ * - Fields are checked, not clamped: 29 February 2023, 31 June, hour 24, minute or second 60
+ *   and a time of 5 or 9 digits return `""`.
+ * - The date has a four-digit year. Before release 004010, element 373 was `YYMMDD`: read such
+ *   a date with `parseDateWithPattern("240615", "yyMMdd", undefined, { yearWindow: 2000 })`.
+ * - Returns `""` for a non-string argument.
+ *
+ * @param date The data element 373 date as transmitted, `CCYYMMDD` (e.g. "20240615")
+ * @param time The data element 337 time as transmitted (e.g. "1430")
+ * @returns the local date-time as `YYYY-MM-DDTHH:MM:SS`, with a fraction when the time has one, or "" on invalid input
+ *
+ * @example parseX12DateAndTime("20240615", "1430") // "2024-06-15T14:30:00"
+ * @example parseX12DateAndTime("20240615", "143045") // "2024-06-15T14:30:45"
+ * @example parseX12DateAndTime("20240615", "14300012") // "2024-06-15T14:30:00.12" (hundredths of a second)
+ * @example parseX12DateAndTime("20240615", "") // "" (both elements are required)
+ * @example parseX12DateAndTime("", "1430") // "" (both elements are required)
+ * @example parseX12DateAndTime("20230229", "1430") // "" (2023 has no 29 February)
+ * @example parseX12DateAndTime("20240615", "2430") // "" (hour 24)
+ * @example parseX12DateAndTime("240615", "1430") // "" (the date element has a four-digit year)
+ */
+export function parseX12DateAndTime(date, time) {
+    try {
+        return readX12DateAndTime(date, time);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,44 @@
+import type { EdiDatePeriod, X12DateRangeFormat } from "../../types/edi.js";
+/**
+ * Parse an X12 Date Time Period value that states a range between two calendar dates, as its
+ * start and end.
+ *
+ * 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. 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 |
+ * |---|---|---|
+ * | `RD8` | `CCYYMMDD-CCYYMMDD` | "Range of Dates Expressed in Format CCYYMMDD-CCYYMMDD" |
+ * | `RD` | `MMDDCCYY-MMDDCCYY` | "Range of Dates Expressed in Format MMDDCCYY-MMDDCCYY" |
+ *
+ * - **A range is transmitted with exactly one hyphen.** Each definition gives the format with
+ *   its hyphen: `"20240615-20240620"` reads, and `"2024061520240620"` returns `null`.
+ * - **`start` and `end` are the two dates as transmitted**, each `YYYY-MM-DD`. X12 does not say
+ *   here whether the end date is inside the range: that is the segment's to define, so no day
+ *   is added or removed. Pass the pair to the plain interval functions as `(start, end)`, for
+ *   example `intervalLengthDate(range.start, range.end, "days")`; they leave `end` outside the
+ *   interval.
+ * - **An end before its start returns `null`**: a reversed range names no span of time. An end
+ *   equal to its start is a valid range.
+ * - Fields are checked, not clamped: month 13, 31 June and 29 February 2023 return `null`.
+ * - A two-digit year (`RD6`, `YYMMDD-YYMMDD`) is not read. Split such a value at its hyphen 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 (`RDT` is read by
+ *   `parseX12DateTimeRange`), and for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "20240615-20240620")
+ * @param format X12 data element 1250 format qualifier
+ * @returns `{ start, end }`, two ISO 8601 dates, or null on invalid input
+ *
+ * @example parseX12DateRange("20240615-20240620", "RD8") // { start: "2024-06-15", end: "2024-06-20" }
+ * @example parseX12DateRange("06152024-06202024", "RD") // { start: "2024-06-15", end: "2024-06-20" }
+ * @example parseX12DateRange("2024061520240620", "RD8") // null (a range is transmitted with its hyphen)
+ * @example parseX12DateRange("20240620-20240615", "RD8") // null (the end precedes the start)
+ * @example parseX12DateRange("20230229-20240620", "RD8") // null (2023 has no 29 February)
+ * @example parseX12DateRange("20240615", "D8") // null (a date code: use parseX12Date)
+ */
+export declare function parseX12DateRange(value: string, format: X12DateRangeFormat): EdiDatePeriod | null;

package/dist/intermodal/parse/parseX12DateRange.js

@@ -0,0 +1,52 @@
+import { readEdiRange } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse an X12 Date Time Period value that states a range between two calendar dates, as its
+ * start and end.
+ *
+ * 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. 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 |
+ * |---|---|---|
+ * | `RD8` | `CCYYMMDD-CCYYMMDD` | "Range of Dates Expressed in Format CCYYMMDD-CCYYMMDD" |
+ * | `RD` | `MMDDCCYY-MMDDCCYY` | "Range of Dates Expressed in Format MMDDCCYY-MMDDCCYY" |
+ *
+ * - **A range is transmitted with exactly one hyphen.** Each definition gives the format with
+ *   its hyphen: `"20240615-20240620"` reads, and `"2024061520240620"` returns `null`.
+ * - **`start` and `end` are the two dates as transmitted**, each `YYYY-MM-DD`. X12 does not say
+ *   here whether the end date is inside the range: that is the segment's to define, so no day
+ *   is added or removed. Pass the pair to the plain interval functions as `(start, end)`, for
+ *   example `intervalLengthDate(range.start, range.end, "days")`; they leave `end` outside the
+ *   interval.
+ * - **An end before its start returns `null`**: a reversed range names no span of time. An end
+ *   equal to its start is a valid range.
+ * - Fields are checked, not clamped: month 13, 31 June and 29 February 2023 return `null`.
+ * - A two-digit year (`RD6`, `YYMMDD-YYMMDD`) is not read. Split such a value at its hyphen 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 (`RDT` is read by
+ *   `parseX12DateTimeRange`), and for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "20240615-20240620")
+ * @param format X12 data element 1250 format qualifier
+ * @returns `{ start, end }`, two ISO 8601 dates, or null on invalid input
+ *
+ * @example parseX12DateRange("20240615-20240620", "RD8") // { start: "2024-06-15", end: "2024-06-20" }
+ * @example parseX12DateRange("06152024-06202024", "RD") // { start: "2024-06-15", end: "2024-06-20" }
+ * @example parseX12DateRange("2024061520240620", "RD8") // null (a range is transmitted with its hyphen)
+ * @example parseX12DateRange("20240620-20240615", "RD8") // null (the end precedes the start)
+ * @example parseX12DateRange("20230229-20240620", "RD8") // null (2023 has no 29 February)
+ * @example parseX12DateRange("20240615", "D8") // null (a date code: use parseX12Date)
+ */
+export function parseX12DateRange(value, format) {
+    try {
+        return readEdiRange("x12", "dateRange", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,45 @@
+import type { X12DateTimeFormat } from "../../types/edi.js";
+/**
+ * Parse an X12 Date Time Period value that states a date and a time, as an ISO 8601 local
+ * date-time.
+ *
+ * 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 one date-time. 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 |
+ * |---|---|---|
+ * | `DT` | `CCYYMMDDHHMM` | "Date and Time Expressed in Format CCYYMMDDHHMM" |
+ * | `RTS` | `CCYYMMDDHHMMSS` | "Date and Time Expressed in Format CCYYMMDDHHMMSS" |
+ *
+ * - **The result is local, never UTC.** No 1250 code carries an offset, so the result has no
+ *   `Z` and no offset. Pass it and the place's IANA zone to `resolveLocal` to get the instant.
+ * - `RTS` is one date-time, despite the `R` that marks a range in other codes.
+ * - The value must be the digits of its code's mask: `"202406151430"` is a `DT` value and not
+ *   an `RTS` one.
+ * - Seconds are always written in the result, `00` for `DT`.
+ * - Fields are checked, not clamped: hour 24, second 60, 31 June and 29 February 2023 return
+ *   `""`.
+ * - **A freight segment sends the date and the time as two elements** (373 and 337 in `AT7`,
+ *   `G62` and `DTM-02`/`03`), not as one 1250 value: read those with `parseX12DateAndTime`.
+ * - A two-digit year (`TR`, `DDMMYYHHMM`) is not read: X12 does not say which century it
+ *   belongs to. Read one with
+ *   `parseDateTimeWithPattern("1506241430", "ddMMyyHHmm", undefined, { yearWindow: 2000 })`.
+ * - Returns `""` for any other code, a code of another kind included (`D8` is read by
+ *   `parseX12Date`), and for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "202406151430")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the local date-time as `YYYY-MM-DDTHH:MM:SS`, or "" on invalid input
+ *
+ * @example parseX12DateTime("202406151430", "DT") // "2024-06-15T14:30:00"
+ * @example parseX12DateTime("20240615143045", "RTS") // "2024-06-15T14:30:45"
+ * @example parseX12DateTime("202406151430", "RTS") // "" (twelve digits is a DT value)
+ * @example parseX12DateTime("202302291430", "DT") // "" (2023 has no 29 February)
+ * @example parseX12DateTime("202406152430", "DT") // "" (hour 24)
+ * @example parseX12DateTime("20240615", "D8") // "" (a date code: use parseX12Date)
+ */
+export declare function parseX12DateTime(value: string, format: X12DateTimeFormat): string;

package/dist/intermodal/parse/parseX12DateTime.js

@@ -0,0 +1,53 @@
+import { readEdiValue } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse an X12 Date Time Period value that states a date and a time, as an ISO 8601 local
+ * date-time.
+ *
+ * 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 one date-time. 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 |
+ * |---|---|---|
+ * | `DT` | `CCYYMMDDHHMM` | "Date and Time Expressed in Format CCYYMMDDHHMM" |
+ * | `RTS` | `CCYYMMDDHHMMSS` | "Date and Time Expressed in Format CCYYMMDDHHMMSS" |
+ *
+ * - **The result is local, never UTC.** No 1250 code carries an offset, so the result has no
+ *   `Z` and no offset. Pass it and the place's IANA zone to `resolveLocal` to get the instant.
+ * - `RTS` is one date-time, despite the `R` that marks a range in other codes.
+ * - The value must be the digits of its code's mask: `"202406151430"` is a `DT` value and not
+ *   an `RTS` one.
+ * - Seconds are always written in the result, `00` for `DT`.
+ * - Fields are checked, not clamped: hour 24, second 60, 31 June and 29 February 2023 return
+ *   `""`.
+ * - **A freight segment sends the date and the time as two elements** (373 and 337 in `AT7`,
+ *   `G62` and `DTM-02`/`03`), not as one 1250 value: read those with `parseX12DateAndTime`.
+ * - A two-digit year (`TR`, `DDMMYYHHMM`) is not read: X12 does not say which century it
+ *   belongs to. Read one with
+ *   `parseDateTimeWithPattern("1506241430", "ddMMyyHHmm", undefined, { yearWindow: 2000 })`.
+ * - Returns `""` for any other code, a code of another kind included (`D8` is read by
+ *   `parseX12Date`), and for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "202406151430")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the local date-time as `YYYY-MM-DDTHH:MM:SS`, or "" on invalid input
+ *
+ * @example parseX12DateTime("202406151430", "DT") // "2024-06-15T14:30:00"
+ * @example parseX12DateTime("20240615143045", "RTS") // "2024-06-15T14:30:45"
+ * @example parseX12DateTime("202406151430", "RTS") // "" (twelve digits is a DT value)
+ * @example parseX12DateTime("202302291430", "DT") // "" (2023 has no 29 February)
+ * @example parseX12DateTime("202406152430", "DT") // "" (hour 24)
+ * @example parseX12DateTime("20240615", "D8") // "" (a date code: use parseX12Date)
+ */
+export function parseX12DateTime(value, format) {
+    try {
+        return readEdiValue("x12", "dateTime", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,46 @@
+import type { EdiDateTimePeriod, X12DateTimeRangeFormat } from "../../types/edi.js";
+/**
+ * Parse an X12 Date Time Period value that states a range between two local date-times, as its
+ * start and end.
+ *
+ * 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. 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 |
+ * |---|---|---|
+ * | `RDT` | `CCYYMMDDHHMM-CCYYMMDDHHMM` | "Range of Date and Time, Expressed in Format CCYYMMDDHHMM-CCYYMMDDHHMM" |
+ * | `DTS` | `CCYYMMDDHHMMSS-CCYYMMDDHHMMSS` | "Range of Date and Time Expressed in Format CCYYMMDDHHMMSS-CCYYMMDDHHMMSS" |
+ *
+ * - **A range is transmitted with exactly one hyphen**: `"202406151430-202406201600"` reads,
+ *   and the same digits run together return `null`.
+ * - **`start` and `end` are local date-times as transmitted**, each `YYYY-MM-DDTHH:MM:SS`, with
+ *   seconds `00` for `RDT`. No 1250 code carries an offset, so neither names an instant: pass
+ *   each and the place's IANA zone to `resolveLocal`.
+ * - X12 does not say here whether the end is inside the range. Pass the pair to the plain
+ *   interval functions as `(start, end)`, for example
+ *   `intervalLengthDateTime(range.start, range.end, "hours")`; they leave `end` outside the
+ *   interval.
+ * - `DTS` is a range, despite having no `R`.
+ * - **An end before its start returns `null`**: a reversed range names no span of time. An end
+ *   equal to its start is a valid range.
+ * - Fields are checked, not clamped: hour 24, second 60 and 29 February 2023 return `null`.
+ * - A range with a date on one side and a date-time on the other (`DDT`, `DTD`) is not read,
+ *   and neither is a range of times with no date (`RTM`).
+ * - Returns `null` for any other code, a code of another kind included (`RD8` is read by
+ *   `parseX12DateRange`), and for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "202406151430-202406201600")
+ * @param format X12 data element 1250 format qualifier
+ * @returns `{ start, end }`, two ISO 8601 local date-times, or null on invalid input
+ *
+ * @example parseX12DateTimeRange("202406151430-202406201600", "RDT") // { start: "2024-06-15T14:30:00", end: "2024-06-20T16:00:00" }
+ * @example parseX12DateTimeRange("20240615143045-20240620160030", "DTS") // { start: "2024-06-15T14:30:45", end: "2024-06-20T16:00:30" }
+ * @example parseX12DateTimeRange("202406151430202406201600", "RDT") // null (a range is transmitted with its hyphen)
+ * @example parseX12DateTimeRange("202406151431-202406151430", "RDT") // null (the end precedes the start)
+ * @example parseX12DateTimeRange("20240615-20240620", "RD8") // null (a date range code: use parseX12DateRange)
+ */
+export declare function parseX12DateTimeRange(value: string, format: X12DateTimeRangeFormat): EdiDateTimePeriod | null;

package/dist/intermodal/parse/parseX12DateTimeRange.js

@@ -0,0 +1,54 @@
+import { readEdiRange } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse an X12 Date Time Period value that states a range between two local date-times, as its
+ * start and end.
+ *
+ * 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. 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 |
+ * |---|---|---|
+ * | `RDT` | `CCYYMMDDHHMM-CCYYMMDDHHMM` | "Range of Date and Time, Expressed in Format CCYYMMDDHHMM-CCYYMMDDHHMM" |
+ * | `DTS` | `CCYYMMDDHHMMSS-CCYYMMDDHHMMSS` | "Range of Date and Time Expressed in Format CCYYMMDDHHMMSS-CCYYMMDDHHMMSS" |
+ *
+ * - **A range is transmitted with exactly one hyphen**: `"202406151430-202406201600"` reads,
+ *   and the same digits run together return `null`.
+ * - **`start` and `end` are local date-times as transmitted**, each `YYYY-MM-DDTHH:MM:SS`, with
+ *   seconds `00` for `RDT`. No 1250 code carries an offset, so neither names an instant: pass
+ *   each and the place's IANA zone to `resolveLocal`.
+ * - X12 does not say here whether the end is inside the range. Pass the pair to the plain
+ *   interval functions as `(start, end)`, for example
+ *   `intervalLengthDateTime(range.start, range.end, "hours")`; they leave `end` outside the
+ *   interval.
+ * - `DTS` is a range, despite having no `R`.
+ * - **An end before its start returns `null`**: a reversed range names no span of time. An end
+ *   equal to its start is a valid range.
+ * - Fields are checked, not clamped: hour 24, second 60 and 29 February 2023 return `null`.
+ * - A range with a date on one side and a date-time on the other (`DDT`, `DTD`) is not read,
+ *   and neither is a range of times with no date (`RTM`).
+ * - Returns `null` for any other code, a code of another kind included (`RD8` is read by
+ *   `parseX12DateRange`), and for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "202406151430-202406201600")
+ * @param format X12 data element 1250 format qualifier
+ * @returns `{ start, end }`, two ISO 8601 local date-times, or null on invalid input
+ *
+ * @example parseX12DateTimeRange("202406151430-202406201600", "RDT") // { start: "2024-06-15T14:30:00", end: "2024-06-20T16:00:00" }
+ * @example parseX12DateTimeRange("20240615143045-20240620160030", "DTS") // { start: "2024-06-15T14:30:45", end: "2024-06-20T16:00:30" }
+ * @example parseX12DateTimeRange("202406151430202406201600", "RDT") // null (a range is transmitted with its hyphen)
+ * @example parseX12DateTimeRange("202406151431-202406151430", "RDT") // null (the end precedes the start)
+ * @example parseX12DateTimeRange("20240615-20240620", "RD8") // null (a date range code: use parseX12DateRange)
+ */
+export function parseX12DateTimeRange(value, format) {
+    try {
+        return readEdiRange("x12", "dateTimeRange", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,65 @@
+import type { X12TimeFormat } from "../../types/edi.js";
+/**
+ * Parse an X12 time as an ISO 8601 time: a data element 337 value with no qualifier, or a time
+ * that arrives with a data element 1250 format qualifier.
+ *
+ * X12 sends a time two ways, and `format` says which the caller holds:
+ *
+ * - **With no qualifier**: the time element of a freight segment (`AT7-06`, `G62-04`,
+ *   `DTM-03`) is data element 337, which fixes its own four forms. Omit `format`.
+ * - **With a qualifier**: a `DTP` segment (`DTP-02` and `DTP-03`), and `DTM-05` and `DTM-06`,
+ *   send a data element 1250 format qualifier beside the value. Pass it as `format`, and the
+ *   value is read against that qualifier's mask alone.
+ *
+ * Definitions are release 005010, read from Stedi's X12-licensed dictionary
+ * ([337](https://www.stedi.com/edi/x12-005010/element/337),
+ * [1250](https://www.stedi.com/edi/x12-005010/element/1250)); the X12 text itself was not
+ * reached.
+ *
+ * ### Forms
+ * | `format` | Digits | Mask | The dictionary's definition |
+ * |---|---|---|---|
+ * | omitted | 4, 6, 7 or 8 | `HHMM`, `HHMMSS`, `HHMMSSD`, `HHMMSSDD` | Element 337: "H = hours (00-23), M = minutes (00-59), S = integer seconds (00-59) … D = tenths (0-9) and DD = hundredths (00-99)" |
+ * | `TM` | 4 | `HHMM` | "Time Expressed in Format HHMM" |
+ * | `TS` | 6 | `HHMMSS` | "Time Expressed in Format HHMMSS" |
+ *
+ * - **A qualifier is strict.** `"143045"` is a `TS` value and returns `""` under `TM`, and no
+ *   1250 code holds decimal seconds, so a 7- or 8-digit value returns `""` under either
+ *   qualifier. The same values read when `format` is omitted.
+ * - **A `format` that is present and is not `TM` or `TS` returns `""`**, never the unqualified
+ *   read: a code of another kind (`D8`), a code that is not read (`RTM`, `TT`), an empty string
+ *   and a non-string. Only an omitted or `undefined` format means "no qualifier".
+ * - Seconds are always written in the result, `00` for `HHMM`.
+ * - With no qualifier, tenths and hundredths become the fraction of the second exactly:
+ *   `1430001` is `14:30:00.1` and `14300012` is `14:30:00.12`. A zero fraction is not written
+ *   (`14300000` is `14:30:00`).
+ * - **To write the value back**, use `formatX12TimeElement` for an element 337 time and name
+ *   the form by its mask: `formatX12TimeElement("14:30:00.12", "HHMMSSDD")` is `14300012`. Use
+ *   `formatX12Time` for a time that travels with a `TM` or `TS` qualifier.
+ * - Fields are checked, not clamped: hour 24, minute 60, second 60 and a value of 5 or 9 digits
+ *   return `""`.
+ * - **The time is local to a place the value does not name.** In a freight segment the time
+ *   code beside it (data element 623) says where the clock was: classify it with
+ *   `classifyX12TimeCode`. To read the date and time elements together, use
+ *   `parseX12DateAndTime`.
+ * - A range of times (`RTM`, `HHMM-HHMM`) is not read.
+ * - Returns `""` for a non-string value.
+ *
+ * @param value The time as transmitted (e.g. "1430")
+ * @param format X12 data element 1250 format qualifier the time arrived with; omit it for a data element 337 value
+ * @returns the time as `HH:MM:SS`, with a fraction of one or two digits when a 337 value has one, or "" on invalid input
+ *
+ * @example parseX12Time("1430") // "14:30:00"
+ * @example parseX12Time("1430", "TM") // "14:30:00"
+ * @example parseX12Time("143045", "TS") // "14:30:45"
+ * @example parseX12Time("143045") // "14:30:45"
+ * @example parseX12Time("1430001") // "14:30:00.1" (a tenth of a second)
+ * @example parseX12Time("14300012") // "14:30:00.12" (hundredths of a second)
+ * @example parseX12Time("14300000") // "14:30:00" (a zero fraction is not written)
+ * @example parseX12Time("143045", "TM") // "" (six digits is a TS value)
+ * @example parseX12Time("14300012", "TS") // "" (no 1250 code holds decimal seconds)
+ * @example parseX12Time("2430") // "" (hour 24)
+ * @example parseX12Time("14304") // "" (five digits is not an element 337 form)
+ * @example parseX12Time("14:30") // "" (the value is the digits of the element)
+ */
+export declare function parseX12Time(value: string, format?: X12TimeFormat): string;

package/dist/intermodal/parse/parseX12Time.js

@@ -0,0 +1,77 @@
+import { readEdiValue, readX12Time } from "../../internal/ediDateTimeFields.js";
+/**
+ * Parse an X12 time as an ISO 8601 time: a data element 337 value with no qualifier, or a time
+ * that arrives with a data element 1250 format qualifier.
+ *
+ * X12 sends a time two ways, and `format` says which the caller holds:
+ *
+ * - **With no qualifier**: the time element of a freight segment (`AT7-06`, `G62-04`,
+ *   `DTM-03`) is data element 337, which fixes its own four forms. Omit `format`.
+ * - **With a qualifier**: a `DTP` segment (`DTP-02` and `DTP-03`), and `DTM-05` and `DTM-06`,
+ *   send a data element 1250 format qualifier beside the value. Pass it as `format`, and the
+ *   value is read against that qualifier's mask alone.
+ *
+ * Definitions are release 005010, read from Stedi's X12-licensed dictionary
+ * ([337](https://www.stedi.com/edi/x12-005010/element/337),
+ * [1250](https://www.stedi.com/edi/x12-005010/element/1250)); the X12 text itself was not
+ * reached.
+ *
+ * ### Forms
+ * | `format` | Digits | Mask | The dictionary's definition |
+ * |---|---|---|---|
+ * | omitted | 4, 6, 7 or 8 | `HHMM`, `HHMMSS`, `HHMMSSD`, `HHMMSSDD` | Element 337: "H = hours (00-23), M = minutes (00-59), S = integer seconds (00-59) … D = tenths (0-9) and DD = hundredths (00-99)" |
+ * | `TM` | 4 | `HHMM` | "Time Expressed in Format HHMM" |
+ * | `TS` | 6 | `HHMMSS` | "Time Expressed in Format HHMMSS" |
+ *
+ * - **A qualifier is strict.** `"143045"` is a `TS` value and returns `""` under `TM`, and no
+ *   1250 code holds decimal seconds, so a 7- or 8-digit value returns `""` under either
+ *   qualifier. The same values read when `format` is omitted.
+ * - **A `format` that is present and is not `TM` or `TS` returns `""`**, never the unqualified
+ *   read: a code of another kind (`D8`), a code that is not read (`RTM`, `TT`), an empty string
+ *   and a non-string. Only an omitted or `undefined` format means "no qualifier".
+ * - Seconds are always written in the result, `00` for `HHMM`.
+ * - With no qualifier, tenths and hundredths become the fraction of the second exactly:
+ *   `1430001` is `14:30:00.1` and `14300012` is `14:30:00.12`. A zero fraction is not written
+ *   (`14300000` is `14:30:00`).
+ * - **To write the value back**, use `formatX12TimeElement` for an element 337 time and name
+ *   the form by its mask: `formatX12TimeElement("14:30:00.12", "HHMMSSDD")` is `14300012`. Use
+ *   `formatX12Time` for a time that travels with a `TM` or `TS` qualifier.
+ * - Fields are checked, not clamped: hour 24, minute 60, second 60 and a value of 5 or 9 digits
+ *   return `""`.
+ * - **The time is local to a place the value does not name.** In a freight segment the time
+ *   code beside it (data element 623) says where the clock was: classify it with
+ *   `classifyX12TimeCode`. To read the date and time elements together, use
+ *   `parseX12DateAndTime`.
+ * - A range of times (`RTM`, `HHMM-HHMM`) is not read.
+ * - Returns `""` for a non-string value.
+ *
+ * @param value The time as transmitted (e.g. "1430")
+ * @param format X12 data element 1250 format qualifier the time arrived with; omit it for a data element 337 value
+ * @returns the time as `HH:MM:SS`, with a fraction of one or two digits when a 337 value has one, or "" on invalid input
+ *
+ * @example parseX12Time("1430") // "14:30:00"
+ * @example parseX12Time("1430", "TM") // "14:30:00"
+ * @example parseX12Time("143045", "TS") // "14:30:45"
+ * @example parseX12Time("143045") // "14:30:45"
+ * @example parseX12Time("1430001") // "14:30:00.1" (a tenth of a second)
+ * @example parseX12Time("14300012") // "14:30:00.12" (hundredths of a second)
+ * @example parseX12Time("14300000") // "14:30:00" (a zero fraction is not written)
+ * @example parseX12Time("143045", "TM") // "" (six digits is a TS value)
+ * @example parseX12Time("14300012", "TS") // "" (no 1250 code holds decimal seconds)
+ * @example parseX12Time("2430") // "" (hour 24)
+ * @example parseX12Time("14304") // "" (five digits is not an element 337 form)
+ * @example parseX12Time("14:30") // "" (the value is the digits of the element)
+ */
+export function parseX12Time(value, format) {
+    try {
+        // No qualifier: the element fixes its own forms. With one, the value is read against that
+        // code's mask, and a code that is not a time code is refused there.
+        return format === undefined
+            ? readX12Time(value)
+            : readEdiValue("x12", "time", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}