@northguild/gmt 1.18.0 → 1.20.0

package/dist/intermodal/format/formatEpcisEvent.js

@@ -0,0 +1,79 @@
+import { Temporal } from "../../internal/temporal.js";
+import { formatUtcOffset, isObject, parseInstantNanoseconds, parseUtcOffsetNanoseconds, } from "../../internal/index.js";
+import { epcisEventTime, epcisTimeZoneOffset } from "../../regex/index.js";
+/**
+ * Write an instant-plus-offset pair as the two required time fields of a GS1 EPCIS 2.0 event.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility. Every event must
+ * carry `eventTime`, the instant, and `eventTimeZoneOffset`, the offset the local clock ran at
+ * where the event happened. The inverse of `parseEpcisEvent`, whose result it takes as it is.
+ *
+ * - **`eventTime` is the instant in UTC, ending in `Z`**, as `Temporal.Instant.prototype.toString`
+ *   writes it: seconds always present, and a fraction kept to the nanosecond with no trailing
+ *   zeros and no padding. It always matches `epcisEventTime`, the `DateTimeStamp` pattern of
+ *   the EPCIS XSD, and so is valid in the XML binding and in the JSON one (`format: date-time`).
+ * - **`eventTimeZoneOffset` is `offset`**, which must match `epcisTimeZoneOffset`, the pattern
+ *   of the EPCIS JSON schema and the rule of EPCIS Standard Release 2.0 §7.4.1
+ *   (https://ref.gs1.org/standards/epcis/): `±HH:MM` from `-14:00` to `+14:00`. That is narrower than the offsets a pair can hold, so an offset with
+ *   seconds (`+05:30:00`, `-00:44:30`), one past 14 hours (`+14:30`) and `Z` return null, although
+ *   `fromOffsetInstant` accepts some of them. Nothing is rounded to fit.
+ * - `-00:00` matches the GS1 pattern and is written as `+00:00`, the spelling `parseEpcisEvent`
+ *   returns.
+ * - `instant` is any instant `isValidInstant` accepts: `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read, so an offset written in `instant` does not have to
+ *   equal `offset`.
+ * - **`timeZone` is not read.** EPCIS has no field for a zone, so a pair's zone is dropped, and
+ *   one that is invalid or disagrees with `offset` changes nothing. `fromOffsetInstant` is the
+ *   function that checks a zone against its offset.
+ * - `eventTime` has a four-digit year, so an instant whose UTC year is outside 0000–9999 returns
+ *   null. `parseEpcisEvent` can return one, from an `eventTime` whose own offset carries it
+ *   across either end of that range, and such a result cannot be written back.
+ * - Returns null when `value` is not an object, when `instant` is not a valid instant, and when
+ *   `offset` is missing, not a string, or outside the GS1 pattern.
+ *
+ * @param value `{ instant, offset }` pair, as `parseEpcisEvent` or `toOffsetInstant` returns it
+ * @returns `{ eventTime, eventTimeZoneOffset }`, or null on invalid input
+ *
+ * @example formatEpcisEvent({ instant: "2024-06-15T14:30:00Z", offset: "-05:00" }) // { eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-05:00" }
+ * @example formatEpcisEvent({ instant: "2024-06-15T09:30:00-05:00", offset: "-05:00" }) // { eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-05:00" } (the instant is written in UTC)
+ * @example formatEpcisEvent({ instant: "2024-06-15T14:30:00.120Z", offset: "+05:45" }) // { eventTime: "2024-06-15T14:30:00.12Z", eventTimeZoneOffset: "+05:45" }
+ * @example formatEpcisEvent({ instant: "2024-06-15T14:30:00Z", offset: "+05:30", timeZone: "Asia/Kolkata" }) // { eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "+05:30" } (EPCIS carries no zone)
+ * @example formatEpcisEvent({ instant: "2024-06-15T14:30:00Z", offset: "-00:00" }) // { eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "+00:00" }
+ * @example formatEpcisEvent({ instant: "2024-06-15T14:30:00Z", offset: "+14:30" }) // null (past the range GS1 allows)
+ * @example formatEpcisEvent({ instant: "2024-06-15T14:30:00Z", offset: "+05:30:00" }) // null (GS1 offsets have no seconds)
+ * @example formatEpcisEvent({ instant: "2024-06-15T14:30:00Z", offset: "Z" }) // null (a designator, not an offset)
+ * @example formatEpcisEvent({ instant: "2024-06-15T14:30:00", offset: "-05:00" }) // null (no offset: not an instant)
+ * @example formatEpcisEvent({ instant: "+010000-01-01T00:00:00Z", offset: "-05:00" }) // null (eventTime has a four-digit year)
+ */
+export function formatEpcisEvent(value) {
+    try {
+        if (!isObject(value)) {
+            return null;
+        }
+        const { instant, offset } = value;
+        // GS1's pattern is tested on the offset as written, before it is canonicalised: `+05:30:00`
+        // names the same offset as `+05:30`, and it is still not a value the field can hold.
+        if (typeof offset !== "string" || !epcisTimeZoneOffset.test(offset)) {
+            return null;
+        }
+        const epochNanoseconds = parseInstantNanoseconds(instant);
+        // Temporal reads the offset and writes it back, so `-00:00` comes out as `+00:00`, as it
+        // does from `parseEpcisEvent`.
+        const offsetNanoseconds = parseUtcOffsetNanoseconds(offset);
+        const eventTimeZoneOffset = offsetNanoseconds === null ? null : formatUtcOffset(offsetNanoseconds);
+        if (epochNanoseconds === null || eventTimeZoneOffset === null) {
+            return null;
+        }
+        const eventTime = Temporal.Instant.fromEpochNanoseconds(epochNanoseconds).toString();
+        // Temporal writes a year outside 0000–9999 with a sign and six digits, which `eventTime`
+        // cannot carry. The pattern is the check, so no year is compared by hand.
+        return epcisEventTime.test(eventTime)
+            ? { eventTime, eventTimeZoneOffset }
+            : null;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { X12DateFormat } from "../../types/edi.js";
+/**
+ * Write an ISO 8601 date as an X12 Date Time Period value (data element 1251) in a date format
+ * qualifier (data element 1250). The inverse of `parseX12Date`.
+ *
+ * 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" |
+ *
+ * - `value` is a date, as `isValidDate` accepts it. A date-time, an instant or a time returns
+ *   `""`, as `formatDate` returns `""` for them: pass the date alone.
+ * - Each field is zero-padded to the width the mask gives it.
+ * - **`D8` also writes data element 373 (Date)**, the `CCYYMMDD` date element of `AT7`, `G62`
+ *   and `DTM-02`.
+ * - A year outside 0000–9999 returns `""`: `CCYY` is four digits and no sign.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 date (e.g. "2024-06-15")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the data element 1251 value, or "" on invalid input
+ *
+ * @example formatX12Date("2024-06-15", "D8") // "20240615"
+ * @example formatX12Date("2024-06-15", "DB") // "06152024"
+ * @example formatX12Date("2024-06-15T14:30", "D8") // "" (a date-time is not a date)
+ * @example formatX12Date("2023-02-29", "D8") // "" (not a real date)
+ * @example formatX12Date("2024-06-15", "DT") // "" (a date-time code: use formatX12DateTime)
+ */
+export declare function formatX12Date(value: string, format: X12DateFormat): string;

package/dist/intermodal/format/formatX12Date.js

@@ -0,0 +1,43 @@
+import { writeEdiValue } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write an ISO 8601 date as an X12 Date Time Period value (data element 1251) in a date format
+ * qualifier (data element 1250). The inverse of `parseX12Date`.
+ *
+ * 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" |
+ *
+ * - `value` is a date, as `isValidDate` accepts it. A date-time, an instant or a time returns
+ *   `""`, as `formatDate` returns `""` for them: pass the date alone.
+ * - Each field is zero-padded to the width the mask gives it.
+ * - **`D8` also writes data element 373 (Date)**, the `CCYYMMDD` date element of `AT7`, `G62`
+ *   and `DTM-02`.
+ * - A year outside 0000–9999 returns `""`: `CCYY` is four digits and no sign.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 date (e.g. "2024-06-15")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the data element 1251 value, or "" on invalid input
+ *
+ * @example formatX12Date("2024-06-15", "D8") // "20240615"
+ * @example formatX12Date("2024-06-15", "DB") // "06152024"
+ * @example formatX12Date("2024-06-15T14:30", "D8") // "" (a date-time is not a date)
+ * @example formatX12Date("2023-02-29", "D8") // "" (not a real date)
+ * @example formatX12Date("2024-06-15", "DT") // "" (a date-time code: use formatX12DateTime)
+ */
+export function formatX12Date(value, format) {
+    try {
+        return writeEdiValue("x12", "date", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,37 @@
+import type { X12DateRangeFormat } from "../../types/edi.js";
+/**
+ * Write two ISO 8601 dates as an X12 Date Time Period range (data element 1251) in a date range
+ * format qualifier (data element 1250). The inverse of `parseX12DateRange`.
+ *
+ * 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" |
+ *
+ * - `start` and `end` are dates, as `isValidDate` accepts them: the two members
+ *   `parseX12DateRange` returns. A date-time, an instant or a time returns `""`.
+ * - **The range is written with the one hyphen X12 transmits**: 15 to 20 June 2024 is
+ *   `20240615-20240620` under `RD8`.
+ * - **An end before its start returns `""`**: a reversed range names no span of time. An end
+ *   equal to its start is written.
+ * - A year outside 0000–9999 in either date returns `""`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param start ISO 8601 date the range starts on (e.g. "2024-06-15")
+ * @param end ISO 8601 date the range ends on (e.g. "2024-06-20")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the data element 1251 value, or "" on invalid input
+ *
+ * @example formatX12DateRange("2024-06-15", "2024-06-20", "RD8") // "20240615-20240620"
+ * @example formatX12DateRange("2024-06-15", "2024-06-20", "RD") // "06152024-06202024"
+ * @example formatX12DateRange("2024-06-20", "2024-06-15", "RD8") // "" (the end precedes the start)
+ * @example formatX12DateRange("2024-06-15T14:30", "2024-06-20", "RD8") // "" (a date-time is not a date)
+ * @example formatX12DateRange("2024-06-15", "2023-02-29", "RD8") // "" (not a real date)
+ */
+export declare function formatX12DateRange(start: string, end: string, format: X12DateRangeFormat): string;

package/dist/intermodal/format/formatX12DateRange.js

@@ -0,0 +1,45 @@
+import { writeEdiRange } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write two ISO 8601 dates as an X12 Date Time Period range (data element 1251) in a date range
+ * format qualifier (data element 1250). The inverse of `parseX12DateRange`.
+ *
+ * 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" |
+ *
+ * - `start` and `end` are dates, as `isValidDate` accepts them: the two members
+ *   `parseX12DateRange` returns. A date-time, an instant or a time returns `""`.
+ * - **The range is written with the one hyphen X12 transmits**: 15 to 20 June 2024 is
+ *   `20240615-20240620` under `RD8`.
+ * - **An end before its start returns `""`**: a reversed range names no span of time. An end
+ *   equal to its start is written.
+ * - A year outside 0000–9999 in either date returns `""`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param start ISO 8601 date the range starts on (e.g. "2024-06-15")
+ * @param end ISO 8601 date the range ends on (e.g. "2024-06-20")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the data element 1251 value, or "" on invalid input
+ *
+ * @example formatX12DateRange("2024-06-15", "2024-06-20", "RD8") // "20240615-20240620"
+ * @example formatX12DateRange("2024-06-15", "2024-06-20", "RD") // "06152024-06202024"
+ * @example formatX12DateRange("2024-06-20", "2024-06-15", "RD8") // "" (the end precedes the start)
+ * @example formatX12DateRange("2024-06-15T14:30", "2024-06-20", "RD8") // "" (a date-time is not a date)
+ * @example formatX12DateRange("2024-06-15", "2023-02-29", "RD8") // "" (not a real date)
+ */
+export function formatX12DateRange(start, end, format) {
+    try {
+        return writeEdiRange("x12", "dateRange", format, start, end);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { X12DateTimeFormat } from "../../types/edi.js";
+/**
+ * Write an ISO 8601 local date-time as an X12 Date Time Period value (data element 1251) in a
+ * date-time format qualifier (data element 1250). The inverse of `parseX12DateTime`.
+ *
+ * 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" |
+ *
+ * - `value` is a local date-time, as `isValidDateTime` accepts it. A date and a time return
+ *   `""`.
+ * - **No 1250 code carries an offset**, so an instant ending in `Z` and a date-time with an
+ *   offset return `""`: an instant is not written as a wall clock. Pass the local date-time.
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped, and
+ *   `DT` drops the seconds too. `2024-06-15T14:30:45.9` is `202406151430` under `DT` and
+ *   `20240615143045` under `RTS`.
+ * - A year outside 0000–9999 returns `""`: `CCYY` is four digits and no sign.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 local date-time (e.g. "2024-06-15T14:30:00")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the data element 1251 value, or "" on invalid input
+ *
+ * @example formatX12DateTime("2024-06-15T14:30:00", "DT") // "202406151430"
+ * @example formatX12DateTime("2024-06-15T14:30:45", "RTS") // "20240615143045"
+ * @example formatX12DateTime("2024-06-15T14:30:45", "DT") // "202406151430" (the mask has no seconds)
+ * @example formatX12DateTime("2024-06-15T14:30:45.9", "RTS") // "20240615143045" (cut, not rounded)
+ * @example formatX12DateTime("2024-06-15", "DT") // "" (a date is not a date-time)
+ * @example formatX12DateTime("2024-06-15T14:30:00Z", "DT") // "" (no 1250 code carries an offset)
+ * @example formatX12DateTime("2023-02-29T14:30:00", "DT") // "" (not a real date)
+ */
+export declare function formatX12DateTime(value: string, format: X12DateTimeFormat): string;

package/dist/intermodal/format/formatX12DateTime.js

@@ -0,0 +1,47 @@
+import { writeEdiValue } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write an ISO 8601 local date-time as an X12 Date Time Period value (data element 1251) in a
+ * date-time format qualifier (data element 1250). The inverse of `parseX12DateTime`.
+ *
+ * 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" |
+ *
+ * - `value` is a local date-time, as `isValidDateTime` accepts it. A date and a time return
+ *   `""`.
+ * - **No 1250 code carries an offset**, so an instant ending in `Z` and a date-time with an
+ *   offset return `""`: an instant is not written as a wall clock. Pass the local date-time.
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped, and
+ *   `DT` drops the seconds too. `2024-06-15T14:30:45.9` is `202406151430` under `DT` and
+ *   `20240615143045` under `RTS`.
+ * - A year outside 0000–9999 returns `""`: `CCYY` is four digits and no sign.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 local date-time (e.g. "2024-06-15T14:30:00")
+ * @param format X12 data element 1250 format qualifier
+ * @returns the data element 1251 value, or "" on invalid input
+ *
+ * @example formatX12DateTime("2024-06-15T14:30:00", "DT") // "202406151430"
+ * @example formatX12DateTime("2024-06-15T14:30:45", "RTS") // "20240615143045"
+ * @example formatX12DateTime("2024-06-15T14:30:45", "DT") // "202406151430" (the mask has no seconds)
+ * @example formatX12DateTime("2024-06-15T14:30:45.9", "RTS") // "20240615143045" (cut, not rounded)
+ * @example formatX12DateTime("2024-06-15", "DT") // "" (a date is not a date-time)
+ * @example formatX12DateTime("2024-06-15T14:30:00Z", "DT") // "" (no 1250 code carries an offset)
+ * @example formatX12DateTime("2023-02-29T14:30:00", "DT") // "" (not a real date)
+ */
+export function formatX12DateTime(value, format) {
+    try {
+        return writeEdiValue("x12", "dateTime", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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