@northguild/gmt 1.17.0 → 1.19.0

package/dist/intermodal/format/formatX12DateTimeRange.d.ts

@@ -0,0 +1,40 @@
+import type { X12DateTimeRangeFormat } from "../../types/edi.js";
+/**
+ * Write two ISO 8601 local date-times as an X12 Date Time Period range (data element 1251) in a
+ * date-time range format qualifier (data element 1250). The inverse of `parseX12DateTimeRange`.
+ *
+ * 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" |
+ *
+ * - `start` and `end` are local date-times, as `isValidDateTime` accepts them: the two members
+ *   `parseX12DateTimeRange` returns. A date, an instant ending in `Z` and a date-time with an
+ *   offset return `""`: no 1250 code carries an offset.
+ * - **The range is written with the one hyphen X12 transmits.**
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped from
+ *   both ends, and `RDT` drops the seconds too.
+ * - **An end before its start returns `""`**: a reversed range names no span of time. The ends
+ *   are compared as given, before either is cut to the mask. An end equal to its start is
+ *   written.
+ * - A year outside 0000–9999 in either end returns `""`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param start ISO 8601 local date-time the range starts at (e.g. "2024-06-15T14:30:00")
+ * @param end ISO 8601 local date-time the range ends at (e.g. "2024-06-20T16:00:00")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the data element 1251 value, or "" on invalid input
+ *
+ * @example formatX12DateTimeRange("2024-06-15T14:30:00", "2024-06-20T16:00:00", "RDT") // "202406151430-202406201600"
+ * @example formatX12DateTimeRange("2024-06-15T14:30:45", "2024-06-20T16:00:30", "DTS") // "20240615143045-20240620160030"
+ * @example formatX12DateTimeRange("2024-06-15T14:30:45", "2024-06-20T16:00:30", "RDT") // "202406151430-202406201600" (the mask has no seconds)
+ * @example formatX12DateTimeRange("2024-06-15T14:31:00", "2024-06-15T14:30:00", "RDT") // "" (the end precedes the start)
+ * @example formatX12DateTimeRange("2024-06-15", "2024-06-20", "RDT") // "" (dates: use formatX12DateRange)
+ */
+export declare function formatX12DateTimeRange(start: string, end: string, format: X12DateTimeRangeFormat): string;

package/dist/intermodal/format/formatX12DateTimeRange.js

@@ -0,0 +1,48 @@
+import { writeEdiRange } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write two ISO 8601 local date-times as an X12 Date Time Period range (data element 1251) in a
+ * date-time range format qualifier (data element 1250). The inverse of `parseX12DateTimeRange`.
+ *
+ * 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" |
+ *
+ * - `start` and `end` are local date-times, as `isValidDateTime` accepts them: the two members
+ *   `parseX12DateTimeRange` returns. A date, an instant ending in `Z` and a date-time with an
+ *   offset return `""`: no 1250 code carries an offset.
+ * - **The range is written with the one hyphen X12 transmits.**
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped from
+ *   both ends, and `RDT` drops the seconds too.
+ * - **An end before its start returns `""`**: a reversed range names no span of time. The ends
+ *   are compared as given, before either is cut to the mask. An end equal to its start is
+ *   written.
+ * - A year outside 0000–9999 in either end returns `""`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param start ISO 8601 local date-time the range starts at (e.g. "2024-06-15T14:30:00")
+ * @param end ISO 8601 local date-time the range ends at (e.g. "2024-06-20T16:00:00")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the data element 1251 value, or "" on invalid input
+ *
+ * @example formatX12DateTimeRange("2024-06-15T14:30:00", "2024-06-20T16:00:00", "RDT") // "202406151430-202406201600"
+ * @example formatX12DateTimeRange("2024-06-15T14:30:45", "2024-06-20T16:00:30", "DTS") // "20240615143045-20240620160030"
+ * @example formatX12DateTimeRange("2024-06-15T14:30:45", "2024-06-20T16:00:30", "RDT") // "202406151430-202406201600" (the mask has no seconds)
+ * @example formatX12DateTimeRange("2024-06-15T14:31:00", "2024-06-15T14:30:00", "RDT") // "" (the end precedes the start)
+ * @example formatX12DateTimeRange("2024-06-15", "2024-06-20", "RDT") // "" (dates: use formatX12DateRange)
+ */
+export function formatX12DateTimeRange(start, end, format) {
+    try {
+        return writeEdiRange("x12", "dateTimeRange", format, start, end);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/intermodal/format/formatX12Time.d.ts

@@ -0,0 +1,42 @@
+import type { X12TimeFormat } from "../../types/edi.js";
+/**
+ * Write an ISO 8601 time as an X12 time in a time format qualifier (data element 1250). The
+ * result is also a data element 337 (Time) value: `parseX12Time` reads it back with the same
+ * qualifier, and with none.
+ *
+ * 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 |
+ * |---|---|---|
+ * | `TM` | `HHMM` | "Time Expressed in Format HHMM" |
+ * | `TS` | `HHMMSS` | "Time Expressed in Format HHMMSS" |
+ *
+ * - `value` is a time, as `isValidTime` accepts it: `HH:MM`, with seconds and a fraction of a
+ *   second if it has them. A date-time, a date or a time with an offset returns `""`.
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped, and
+ *   `TM` drops the seconds too. `14:30:45.123` is `1430` under `TM` and `143045` under `TS`.
+ * - **To write the time element of a freight segment** (`AT7-06`, `G62-04`, `DTM-03`), use
+ *   `formatX12TimeElement`: it writes all four forms of data element 337, named by the
+ *   element's own masks, tenths and hundredths of a second included. `TM` and `TS` give the same
+ *   digits as that element's `HHMM` and `HHMMSS` forms, and no 1250 code holds decimal seconds.
+ * - `TS` here is the format `HHMMSS`. As a data element 623 time code, `TS` is Atlantic Standard
+ *   Time: read that with `x12TimeCodeZone`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 time (e.g. "14:30:00")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the X12 time value, or "" on invalid input
+ *
+ * @example formatX12Time("14:30:00", "TM") // "1430"
+ * @example formatX12Time("14:30:45", "TS") // "143045"
+ * @example formatX12Time("14:30:45.123", "TM") // "1430" (the mask has no seconds)
+ * @example formatX12Time("14:30:45.9", "TS") // "143045" (cut, not rounded)
+ * @example formatX12Time("14:30", "TS") // "143000"
+ * @example formatX12Time("2024-06-15T14:30:00", "TM") // "" (a date-time is not a time)
+ * @example formatX12Time("24:00", "TM") // "" (not a real time)
+ */
+export declare function formatX12Time(value: string, format: X12TimeFormat): string;

package/dist/intermodal/format/formatX12Time.js

@@ -0,0 +1,50 @@
+import { writeEdiValue } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write an ISO 8601 time as an X12 time in a time format qualifier (data element 1250). The
+ * result is also a data element 337 (Time) value: `parseX12Time` reads it back with the same
+ * qualifier, and with none.
+ *
+ * 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 |
+ * |---|---|---|
+ * | `TM` | `HHMM` | "Time Expressed in Format HHMM" |
+ * | `TS` | `HHMMSS` | "Time Expressed in Format HHMMSS" |
+ *
+ * - `value` is a time, as `isValidTime` accepts it: `HH:MM`, with seconds and a fraction of a
+ *   second if it has them. A date-time, a date or a time with an offset returns `""`.
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped, and
+ *   `TM` drops the seconds too. `14:30:45.123` is `1430` under `TM` and `143045` under `TS`.
+ * - **To write the time element of a freight segment** (`AT7-06`, `G62-04`, `DTM-03`), use
+ *   `formatX12TimeElement`: it writes all four forms of data element 337, named by the
+ *   element's own masks, tenths and hundredths of a second included. `TM` and `TS` give the same
+ *   digits as that element's `HHMM` and `HHMMSS` forms, and no 1250 code holds decimal seconds.
+ * - `TS` here is the format `HHMMSS`. As a data element 623 time code, `TS` is Atlantic Standard
+ *   Time: read that with `x12TimeCodeZone`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 time (e.g. "14:30:00")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the X12 time value, or "" on invalid input
+ *
+ * @example formatX12Time("14:30:00", "TM") // "1430"
+ * @example formatX12Time("14:30:45", "TS") // "143045"
+ * @example formatX12Time("14:30:45.123", "TM") // "1430" (the mask has no seconds)
+ * @example formatX12Time("14:30:45.9", "TS") // "143045" (cut, not rounded)
+ * @example formatX12Time("14:30", "TS") // "143000"
+ * @example formatX12Time("2024-06-15T14:30:00", "TM") // "" (a date-time is not a time)
+ * @example formatX12Time("24:00", "TM") // "" (not a real time)
+ */
+export function formatX12Time(value, format) {
+    try {
+        return writeEdiValue("x12", "time", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/intermodal/format/formatX12TimeElement.d.ts

@@ -0,0 +1,46 @@
+import type { X12TimeElementForm } from "../../types/edi.js";
+/**
+ * Write an ISO 8601 time as an X12 data element 337 (Time) value, in the form the caller names
+ * by the element's own mask. `parseX12Time` reads the result back when it is given no qualifier.
+ *
+ * Element 337 is the time element of many X12 segments: in freight, `AT7-06`, `G62-04` and
+ * `DTM-03`. No format qualifier travels with it, so nothing in the segment says which of its
+ * four forms a value is in. The definition is release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/337); the X12
+ * text itself was not reached.
+ *
+ * ### Forms
+ * | Form | Digits | The dictionary's definition |
+ * |---|---|---|
+ * | `HHMM` | 4 | "H = hours (00-23), M = minutes (00-59)" |
+ * | `HHMMSS` | 6 | "S = integer seconds (00-59)" |
+ * | `HHMMSSD` | 7 | "D = tenths (0-9)" |
+ * | `HHMMSSDD` | 8 | "DD = hundredths (00-99)" |
+ *
+ * - `value` is a time, as `isValidTime` accepts it: `HH:MM`, with seconds and a fraction of a
+ *   second if it has them. A date-time, a date or a time with an offset returns `""`.
+ * - **The form alone fixes the digits written.** It is never read off the value, so the width of
+ *   the field does not depend on the data: a time with no fraction is `14300000` under
+ *   `HHMMSSDD`, and a time with one is `1430` under `HHMM`.
+ * - Precision is cut to the mask, never rounded. `D` is the whole tenths of the second and `DD`
+ *   its whole hundredths, so `14:30:45.999` is `1430459` under `HHMMSSD` and `14304599` under
+ *   `HHMMSSDD`. A written value never names a later second than its input.
+ * - **The form is a mask, not a data element 1250 code.** `TM` and `TS` return `""` here. To
+ *   write a time that travels with a 1250 qualifier (`DTP-03`, `DTM-06`), use `formatX12Time`.
+ * - Returns `""` for any other form and for a non-string argument.
+ *
+ * @param value ISO 8601 time (e.g. "14:30:00.12")
+ * @param form The element 337 mask to write: `HHMM`, `HHMMSS`, `HHMMSSD` or `HHMMSSDD`
+ * @returns the X12 time value, or "" on invalid input
+ *
+ * @example formatX12TimeElement("14:30:00.12", "HHMMSSDD") // "14300012"
+ * @example formatX12TimeElement("14:30:00.12", "HHMMSSD") // "1430001" (cut, not rounded)
+ * @example formatX12TimeElement("14:30:00", "HHMMSSDD") // "14300000"
+ * @example formatX12TimeElement("14:30", "HHMM") // "1430"
+ * @example formatX12TimeElement("14:30:45.999", "HHMMSS") // "143045"
+ * @example formatX12TimeElement("14:30:45.999", "HHMMSSD") // "1430459" (cut, not rounded)
+ * @example formatX12TimeElement("14:30:45", "TS") // "" (a 1250 code is not a mask)
+ * @example formatX12TimeElement("2024-06-15T14:30:00", "HHMM") // "" (a date-time is not a time)
+ * @example formatX12TimeElement("24:00", "HHMM") // "" (not a real time)
+ */
+export declare function formatX12TimeElement(value: string, form: X12TimeElementForm): string;

package/dist/intermodal/format/formatX12TimeElement.js

@@ -0,0 +1,54 @@
+import { writeX12TimeElement } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write an ISO 8601 time as an X12 data element 337 (Time) value, in the form the caller names
+ * by the element's own mask. `parseX12Time` reads the result back when it is given no qualifier.
+ *
+ * Element 337 is the time element of many X12 segments: in freight, `AT7-06`, `G62-04` and
+ * `DTM-03`. No format qualifier travels with it, so nothing in the segment says which of its
+ * four forms a value is in. The definition is release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/337); the X12
+ * text itself was not reached.
+ *
+ * ### Forms
+ * | Form | Digits | The dictionary's definition |
+ * |---|---|---|
+ * | `HHMM` | 4 | "H = hours (00-23), M = minutes (00-59)" |
+ * | `HHMMSS` | 6 | "S = integer seconds (00-59)" |
+ * | `HHMMSSD` | 7 | "D = tenths (0-9)" |
+ * | `HHMMSSDD` | 8 | "DD = hundredths (00-99)" |
+ *
+ * - `value` is a time, as `isValidTime` accepts it: `HH:MM`, with seconds and a fraction of a
+ *   second if it has them. A date-time, a date or a time with an offset returns `""`.
+ * - **The form alone fixes the digits written.** It is never read off the value, so the width of
+ *   the field does not depend on the data: a time with no fraction is `14300000` under
+ *   `HHMMSSDD`, and a time with one is `1430` under `HHMM`.
+ * - Precision is cut to the mask, never rounded. `D` is the whole tenths of the second and `DD`
+ *   its whole hundredths, so `14:30:45.999` is `1430459` under `HHMMSSD` and `14304599` under
+ *   `HHMMSSDD`. A written value never names a later second than its input.
+ * - **The form is a mask, not a data element 1250 code.** `TM` and `TS` return `""` here. To
+ *   write a time that travels with a 1250 qualifier (`DTP-03`, `DTM-06`), use `formatX12Time`.
+ * - Returns `""` for any other form and for a non-string argument.
+ *
+ * @param value ISO 8601 time (e.g. "14:30:00.12")
+ * @param form The element 337 mask to write: `HHMM`, `HHMMSS`, `HHMMSSD` or `HHMMSSDD`
+ * @returns the X12 time value, or "" on invalid input
+ *
+ * @example formatX12TimeElement("14:30:00.12", "HHMMSSDD") // "14300012"
+ * @example formatX12TimeElement("14:30:00.12", "HHMMSSD") // "1430001" (cut, not rounded)
+ * @example formatX12TimeElement("14:30:00", "HHMMSSDD") // "14300000"
+ * @example formatX12TimeElement("14:30", "HHMM") // "1430"
+ * @example formatX12TimeElement("14:30:45.999", "HHMMSS") // "143045"
+ * @example formatX12TimeElement("14:30:45.999", "HHMMSSD") // "1430459" (cut, not rounded)
+ * @example formatX12TimeElement("14:30:45", "TS") // "" (a 1250 code is not a mask)
+ * @example formatX12TimeElement("2024-06-15T14:30:00", "HHMM") // "" (a date-time is not a time)
+ * @example formatX12TimeElement("24:00", "HHMM") // "" (not a real time)
+ */
+export function formatX12TimeElement(value, form) {
+    try {
+        return writeX12TimeElement(form, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,14 @@
+export * from "./bolTimestamp.js";
+export * from "./formatEdifactDate.js";
+export * from "./formatEdifactDatePeriod.js";
+export * from "./formatEdifactDateTime.js";
+export * from "./formatEdifactDateTimePeriod.js";
+export * from "./formatEdifactOffsetDateTime.js";
+export * from "./formatEdifactTime.js";
+export * from "./formatEpcisEvent.js";
+export * from "./formatX12Date.js";
+export * from "./formatX12DateRange.js";
+export * from "./formatX12DateTime.js";
+export * from "./formatX12DateTimeRange.js";
+export * from "./formatX12Time.js";
+export * from "./formatX12TimeElement.js";

package/dist/intermodal/format/index.js

@@ -0,0 +1,14 @@
+export * from "./bolTimestamp.js";
+export * from "./formatEdifactDate.js";
+export * from "./formatEdifactDatePeriod.js";
+export * from "./formatEdifactDateTime.js";
+export * from "./formatEdifactDateTimePeriod.js";
+export * from "./formatEdifactOffsetDateTime.js";
+export * from "./formatEdifactTime.js";
+export * from "./formatEpcisEvent.js";
+export * from "./formatX12Date.js";
+export * from "./formatX12DateRange.js";
+export * from "./formatX12DateTime.js";
+export * from "./formatX12DateTimeRange.js";
+export * from "./formatX12Time.js";
+export * from "./formatX12TimeElement.js";

package/dist/intermodal/index.d.ts

@@ -1,2 +1,5 @@
 export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
+export * from "./format/index.js";
+export * from "./parse/index.js";
+export * from "./validate/index.js";

package/dist/intermodal/index.js

@@ -1,3 +1,6 @@
 // Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
 export * from "@js-temporal/polyfill";
 export * from "./calculate/index.js";
+export * from "./format/index.js";
+export * from "./parse/index.js";
+export * from "./validate/index.js";

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

@@ -0,0 +1,48 @@
+import type { EdifactDtmFormatClass } from "../../types/edi.js";
+/**
+ * Name the kind of value a UN/EDIFACT data element 2379 format code states, and return the code
+ * narrowed to that kind, so a code that arrives as data reaches the function that reads it.
+ *
+ * Each kind has its own parser, formatter and validator, and each takes only its own codes. A
+ * generic `DTM` reader holds the code as a plain string: it calls this function, tests `kind`,
+ * and passes `format` on. Testing `kind` narrows `format` to that kind's union, so the call
+ * needs no cast.
+ *
+ * ### Kinds
+ * | `kind` | Codes | Read by |
+ * |---|---|---|
+ * | `"date"` | `102` | `parseEdifactDate` |
+ * | `"time"` | `401`, `402` | `parseEdifactTime` |
+ * | `"dateTime"` | `203`, `204` | `parseEdifactDateTime` |
+ * | `"offsetDateTime"` | `205`, `208`, `303`, `304` | `parseEdifactOffsetDateTime` |
+ * | `"datePeriod"` | `718` | `parseEdifactDatePeriod` |
+ * | `"dateTimePeriod"` | `719` | `parseEdifactDateTimePeriod` |
+ *
+ * - **The narrowing pattern.** With `const classified = classifyEdifactDtmFormat(code)`, the
+ *   line `if (classified?.kind === "date") parseEdifactDate(value, classified.format)` compiles
+ *   with no cast: inside the test, `classified.format` is `EdifactDateFormat`.
+ * - Both members are always present, and each call returns a new object.
+ * - Returns `null` for every code no function reads: the two-digit-year codes (`101`, `201`,
+ *   `202`, `206`, `207`, `301`, `302`, `713`, `717`), `209`, `404`, `406` and every other 2379
+ *   code.
+ * - Matching is exact: `" 203"`, `"0203"` and the number `203` are not codes.
+ * - Returns a result exactly when `isValidEdifactDtmFormat` is true.
+ *
+ * @param format The data element 2379 format code, as it arrives (e.g. "203")
+ * @returns `{ kind, format }`, or null on invalid input
+ *
+ * @example classifyEdifactDtmFormat("102") // { kind: "date", format: "102" }
+ * @example classifyEdifactDtmFormat("401") // { kind: "time", format: "401" }
+ * @example classifyEdifactDtmFormat("402") // { kind: "time", format: "402" }
+ * @example classifyEdifactDtmFormat("203") // { kind: "dateTime", format: "203" }
+ * @example classifyEdifactDtmFormat("204") // { kind: "dateTime", format: "204" }
+ * @example classifyEdifactDtmFormat("205") // { kind: "offsetDateTime", format: "205" }
+ * @example classifyEdifactDtmFormat("208") // { kind: "offsetDateTime", format: "208" }
+ * @example classifyEdifactDtmFormat("303") // { kind: "offsetDateTime", format: "303" }
+ * @example classifyEdifactDtmFormat("304") // { kind: "offsetDateTime", format: "304" }
+ * @example classifyEdifactDtmFormat("718") // { kind: "datePeriod", format: "718" }
+ * @example classifyEdifactDtmFormat("719") // { kind: "dateTimePeriod", format: "719" }
+ * @example classifyEdifactDtmFormat("101") // null (a two-digit year is not read)
+ * @example classifyEdifactDtmFormat("602") // null (not a supported code)
+ */
+export declare function classifyEdifactDtmFormat(format: string): EdifactDtmFormatClass | null;

package/dist/intermodal/parse/classifyEdifactDtmFormat.js

@@ -0,0 +1,55 @@
+import { ediCodeOf } from "../../internal/ediGrammar.js";
+/**
+ * Name the kind of value a UN/EDIFACT data element 2379 format code states, and return the code
+ * narrowed to that kind, so a code that arrives as data reaches the function that reads it.
+ *
+ * Each kind has its own parser, formatter and validator, and each takes only its own codes. A
+ * generic `DTM` reader holds the code as a plain string: it calls this function, tests `kind`,
+ * and passes `format` on. Testing `kind` narrows `format` to that kind's union, so the call
+ * needs no cast.
+ *
+ * ### Kinds
+ * | `kind` | Codes | Read by |
+ * |---|---|---|
+ * | `"date"` | `102` | `parseEdifactDate` |
+ * | `"time"` | `401`, `402` | `parseEdifactTime` |
+ * | `"dateTime"` | `203`, `204` | `parseEdifactDateTime` |
+ * | `"offsetDateTime"` | `205`, `208`, `303`, `304` | `parseEdifactOffsetDateTime` |
+ * | `"datePeriod"` | `718` | `parseEdifactDatePeriod` |
+ * | `"dateTimePeriod"` | `719` | `parseEdifactDateTimePeriod` |
+ *
+ * - **The narrowing pattern.** With `const classified = classifyEdifactDtmFormat(code)`, the
+ *   line `if (classified?.kind === "date") parseEdifactDate(value, classified.format)` compiles
+ *   with no cast: inside the test, `classified.format` is `EdifactDateFormat`.
+ * - Both members are always present, and each call returns a new object.
+ * - Returns `null` for every code no function reads: the two-digit-year codes (`101`, `201`,
+ *   `202`, `206`, `207`, `301`, `302`, `713`, `717`), `209`, `404`, `406` and every other 2379
+ *   code.
+ * - Matching is exact: `" 203"`, `"0203"` and the number `203` are not codes.
+ * - Returns a result exactly when `isValidEdifactDtmFormat` is true.
+ *
+ * @param format The data element 2379 format code, as it arrives (e.g. "203")
+ * @returns `{ kind, format }`, or null on invalid input
+ *
+ * @example classifyEdifactDtmFormat("102") // { kind: "date", format: "102" }
+ * @example classifyEdifactDtmFormat("401") // { kind: "time", format: "401" }
+ * @example classifyEdifactDtmFormat("402") // { kind: "time", format: "402" }
+ * @example classifyEdifactDtmFormat("203") // { kind: "dateTime", format: "203" }
+ * @example classifyEdifactDtmFormat("204") // { kind: "dateTime", format: "204" }
+ * @example classifyEdifactDtmFormat("205") // { kind: "offsetDateTime", format: "205" }
+ * @example classifyEdifactDtmFormat("208") // { kind: "offsetDateTime", format: "208" }
+ * @example classifyEdifactDtmFormat("303") // { kind: "offsetDateTime", format: "303" }
+ * @example classifyEdifactDtmFormat("304") // { kind: "offsetDateTime", format: "304" }
+ * @example classifyEdifactDtmFormat("718") // { kind: "datePeriod", format: "718" }
+ * @example classifyEdifactDtmFormat("719") // { kind: "dateTimePeriod", format: "719" }
+ * @example classifyEdifactDtmFormat("101") // null (a two-digit year is not read)
+ * @example classifyEdifactDtmFormat("602") // null (not a supported code)
+ */
+export function classifyEdifactDtmFormat(format) {
+    const entry = ediCodeOf("edifact", format);
+    // The layout table is typed kind by kind from the format unions, so the kind an entry carries
+    // is the kind of the union its code belongs to.
+    return entry === null
+        ? null
+        : { kind: entry.kind, format };
+}

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

@@ -0,0 +1,50 @@
+import type { X12DateTimePeriodFormatClass } from "../../types/edi.js";
+/**
+ * Name the kind of value an X12 data element 1250 format qualifier states, and return the code
+ * narrowed to that kind, so a code that arrives as data reaches the function that reads it.
+ *
+ * Each kind has its own parser, formatter and validator, and each takes only its own codes. A
+ * generic `DTP` reader holds `DTP-02` as a plain string: it calls this function, tests `kind`,
+ * and passes `format` on. Testing `kind` narrows `format` to that kind's union, so the call
+ * needs no cast. 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.
+ *
+ * ### Kinds
+ * | `kind` | Codes | Read by |
+ * |---|---|---|
+ * | `"date"` | `D8`, `DB` | `parseX12Date` |
+ * | `"time"` | `TM`, `TS` | `parseX12Time(value, format)` |
+ * | `"dateTime"` | `DT`, `RTS` | `parseX12DateTime` |
+ * | `"dateRange"` | `RD8`, `RD` | `parseX12DateRange` |
+ * | `"dateTimeRange"` | `RDT`, `DTS` | `parseX12DateTimeRange` |
+ *
+ * - **The narrowing pattern.** With `const classified = classifyX12DateTimePeriodFormat(code)`,
+ *   the line `if (classified?.kind === "date") parseX12Date(value, classified.format)` compiles
+ *   with no cast: inside the test, `classified.format` is `X12DateFormat`.
+ * - Both members are always present, and each call returns a new object.
+ * - `RTS` is one date-time despite its `R`, and `DTS` is a range despite having none.
+ * - Returns `null` for every code no function reads: the two-digit-year codes (`D6`, `TT`, `TR`,
+ *   `RD6`, `TU`), `TC`, `EH`, `DDT`, `DTD`, `RTM`, `UN` and every other 1250 code.
+ * - This is a format qualifier, not a time code: `TS` here is the format `HHMMSS`. Classify a
+ *   data element 623 time code with `classifyX12TimeCode`.
+ * - Matching is exact: `"d8"` and `" D8"` are not codes.
+ * - Returns a result exactly when `isValidX12DateTimePeriodFormat` is true.
+ *
+ * @param format X12 data element 1250 format qualifier, as it arrives (e.g. "D8")
+ * @returns `{ kind, format }`, or null on invalid input
+ *
+ * @example classifyX12DateTimePeriodFormat("D8") // { kind: "date", format: "D8" }
+ * @example classifyX12DateTimePeriodFormat("DB") // { kind: "date", format: "DB" }
+ * @example classifyX12DateTimePeriodFormat("TM") // { kind: "time", format: "TM" }
+ * @example classifyX12DateTimePeriodFormat("TS") // { kind: "time", format: "TS" }
+ * @example classifyX12DateTimePeriodFormat("DT") // { kind: "dateTime", format: "DT" }
+ * @example classifyX12DateTimePeriodFormat("RTS") // { kind: "dateTime", format: "RTS" }
+ * @example classifyX12DateTimePeriodFormat("RD8") // { kind: "dateRange", format: "RD8" }
+ * @example classifyX12DateTimePeriodFormat("RD") // { kind: "dateRange", format: "RD" }
+ * @example classifyX12DateTimePeriodFormat("RDT") // { kind: "dateTimeRange", format: "RDT" }
+ * @example classifyX12DateTimePeriodFormat("DTS") // { kind: "dateTimeRange", format: "DTS" }
+ * @example classifyX12DateTimePeriodFormat("D6") // null (a two-digit year is not read)
+ * @example classifyX12DateTimePeriodFormat("UN") // null (unstructured: nothing to read)
+ */
+export declare function classifyX12DateTimePeriodFormat(format: string): X12DateTimePeriodFormatClass | null;

package/dist/intermodal/parse/classifyX12DateTimePeriodFormat.js

@@ -0,0 +1,57 @@
+import { ediCodeOf } from "../../internal/ediGrammar.js";
+/**
+ * Name the kind of value an X12 data element 1250 format qualifier states, and return the code
+ * narrowed to that kind, so a code that arrives as data reaches the function that reads it.
+ *
+ * Each kind has its own parser, formatter and validator, and each takes only its own codes. A
+ * generic `DTP` reader holds `DTP-02` as a plain string: it calls this function, tests `kind`,
+ * and passes `format` on. Testing `kind` narrows `format` to that kind's union, so the call
+ * needs no cast. 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.
+ *
+ * ### Kinds
+ * | `kind` | Codes | Read by |
+ * |---|---|---|
+ * | `"date"` | `D8`, `DB` | `parseX12Date` |
+ * | `"time"` | `TM`, `TS` | `parseX12Time(value, format)` |
+ * | `"dateTime"` | `DT`, `RTS` | `parseX12DateTime` |
+ * | `"dateRange"` | `RD8`, `RD` | `parseX12DateRange` |
+ * | `"dateTimeRange"` | `RDT`, `DTS` | `parseX12DateTimeRange` |
+ *
+ * - **The narrowing pattern.** With `const classified = classifyX12DateTimePeriodFormat(code)`,
+ *   the line `if (classified?.kind === "date") parseX12Date(value, classified.format)` compiles
+ *   with no cast: inside the test, `classified.format` is `X12DateFormat`.
+ * - Both members are always present, and each call returns a new object.
+ * - `RTS` is one date-time despite its `R`, and `DTS` is a range despite having none.
+ * - Returns `null` for every code no function reads: the two-digit-year codes (`D6`, `TT`, `TR`,
+ *   `RD6`, `TU`), `TC`, `EH`, `DDT`, `DTD`, `RTM`, `UN` and every other 1250 code.
+ * - This is a format qualifier, not a time code: `TS` here is the format `HHMMSS`. Classify a
+ *   data element 623 time code with `classifyX12TimeCode`.
+ * - Matching is exact: `"d8"` and `" D8"` are not codes.
+ * - Returns a result exactly when `isValidX12DateTimePeriodFormat` is true.
+ *
+ * @param format X12 data element 1250 format qualifier, as it arrives (e.g. "D8")
+ * @returns `{ kind, format }`, or null on invalid input
+ *
+ * @example classifyX12DateTimePeriodFormat("D8") // { kind: "date", format: "D8" }
+ * @example classifyX12DateTimePeriodFormat("DB") // { kind: "date", format: "DB" }
+ * @example classifyX12DateTimePeriodFormat("TM") // { kind: "time", format: "TM" }
+ * @example classifyX12DateTimePeriodFormat("TS") // { kind: "time", format: "TS" }
+ * @example classifyX12DateTimePeriodFormat("DT") // { kind: "dateTime", format: "DT" }
+ * @example classifyX12DateTimePeriodFormat("RTS") // { kind: "dateTime", format: "RTS" }
+ * @example classifyX12DateTimePeriodFormat("RD8") // { kind: "dateRange", format: "RD8" }
+ * @example classifyX12DateTimePeriodFormat("RD") // { kind: "dateRange", format: "RD" }
+ * @example classifyX12DateTimePeriodFormat("RDT") // { kind: "dateTimeRange", format: "RDT" }
+ * @example classifyX12DateTimePeriodFormat("DTS") // { kind: "dateTimeRange", format: "DTS" }
+ * @example classifyX12DateTimePeriodFormat("D6") // null (a two-digit year is not read)
+ * @example classifyX12DateTimePeriodFormat("UN") // null (unstructured: nothing to read)
+ */
+export function classifyX12DateTimePeriodFormat(format) {
+    const entry = ediCodeOf("x12", format);
+    // The layout table is typed kind by kind from the format unions, so the kind an entry carries
+    // is the kind of the union its code belongs to.
+    return entry === null
+        ? null
+        : { kind: entry.kind, format };
+}

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

@@ -0,0 +1,46 @@
+import type { X12TimeCodeClass } from "../../types/edi.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 declare function classifyX12TimeCode(timeCode: string): X12TimeCodeClass | null;