@northguild/gmt 1.17.0 → 1.19.0

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

@@ -0,0 +1,62 @@
+import type { EdifactOffsetDateTimeFormat } from "../../types/edi.js";
+/**
+ * Write an ISO 8601 date-time with an offset as a UN/EDIFACT `DTM` value (data element 2380) in
+ * a format code that carries an offset (data element 2379). The inverse of
+ * `parseEdifactOffsetDateTime`.
+ *
+ * Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `205` | `CCYYMMDDHHMMZHHMM` | "Calendar date including time and time zone expressed in hours and minutes." |
+ * | `208` | `CCYYMMDDHHMMSSZHHMM` | "Calendar date including time with seconds, with Time Zone" (D.12A and later) |
+ * | `303` | `CCYYMMDDHHMMZZZ` | "See 203 plus Z=Time zone." |
+ * | `304` | `CCYYMMDDHHMMSSZZZ` | "See 204 plus Z=Time zone." |
+ *
+ * - `value` is an ISO 8601 date-time with an offset (`2024-06-15T14:30:00+02:00`) or a `Z`
+ *   instant, as `toOffsetInstant` reads it: the string `parseEdifactOffsetDateTime` returns and
+ *   `fromOffsetInstant` writes. A local date-time, a date and a time return `""`: there is no
+ *   offset to write.
+ * - **The digits are the value's own wall clock**, never the UTC clock:
+ *   `2024-01-01T00:30:00+02:00` under `303` is `202401010030+02`. A `Z` instant is written on
+ *   the UTC clock with `+0000` or `+00`.
+ * - **`ZZZ` (`303`, `304`) is always written `±HH`**, the hours-only form of UN/ECE
+ *   Recommendation 7 ¶12, never `UTC` or `GMT`. **It holds whole hours only**: an offset such
+ *   as `+05:30` returns `""` under `303` and `304`. Write it under `205` or `208`, whose `ZHHMM`
+ *   holds hours and minutes.
+ * - **An offset with a non-zero seconds part returns `""` under every code**, `205` and `208`
+ *   included. A seconds part of zero (`+02:00:00`) is the offset `+02:00` and is written.
+ *   `ZHHMM` holds hours and minutes and `ZZZ` hours, so no mask holds the seconds of an offset
+ *   such as `-00:44:30`, the offset `Africa/Monrovia` kept until 1972. An offset is never
+ *   rounded: the value would name another instant. Write the same instant in `Z` form
+ *   instead.
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped, and
+ *   `205` and `303` drop the seconds too.
+ * - **The output is the element value, not segment text.** `+` is the EDIFACT data element
+ *   separator, so a value that holds one must be released when it is placed in a segment: write
+ *   `?+`. The function does not add the release character.
+ * - A bracketed RFC 9557 time zone is read as `toOffsetInstant` reads it: it must agree with
+ *   the offset, and beside `Z` it sets the clock the digits are written on.
+ * - A wall clock whose year is outside 0000–9999 returns `""`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 date-time with an offset or `Z` (e.g. "2024-06-15T14:30:00+02:00")
+ * @param format The data element 2379 format code
+ * @returns the data element 2380 value, unescaped, or "" on invalid input
+ *
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00+02:00", "205") // "202406151430+0200"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:45+05:30", "208") // "20240615143045+0530"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00+02:00", "303") // "202406151430+02"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:45-05:00", "304") // "20240615143045-05"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00Z", "205") // "202406151430+0000"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00Z", "303") // "202406151430+00" (never "UTC")
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:45.9+02:00", "205") // "202406151430+0200" (cut to the minute)
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00+05:30", "303") // "" (the field holds whole hours: use 205 or 208)
+ * @example formatEdifactOffsetDateTime("1960-01-01T00:20:00-00:44:30", "208") // "" (no mask holds a non-zero seconds part of an offset)
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00", "205") // "" (a local date-time has no offset to write)
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00+02:00", "203") // "" (a local code: use formatEdifactDateTime)
+ */
+export declare function formatEdifactOffsetDateTime(value: string, format: EdifactOffsetDateTimeFormat): string;

package/dist/intermodal/format/formatEdifactOffsetDateTime.js

@@ -0,0 +1,70 @@
+import { writeEdiValue } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write an ISO 8601 date-time with an offset as a UN/EDIFACT `DTM` value (data element 2380) in
+ * a format code that carries an offset (data element 2379). The inverse of
+ * `parseEdifactOffsetDateTime`.
+ *
+ * Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `205` | `CCYYMMDDHHMMZHHMM` | "Calendar date including time and time zone expressed in hours and minutes." |
+ * | `208` | `CCYYMMDDHHMMSSZHHMM` | "Calendar date including time with seconds, with Time Zone" (D.12A and later) |
+ * | `303` | `CCYYMMDDHHMMZZZ` | "See 203 plus Z=Time zone." |
+ * | `304` | `CCYYMMDDHHMMSSZZZ` | "See 204 plus Z=Time zone." |
+ *
+ * - `value` is an ISO 8601 date-time with an offset (`2024-06-15T14:30:00+02:00`) or a `Z`
+ *   instant, as `toOffsetInstant` reads it: the string `parseEdifactOffsetDateTime` returns and
+ *   `fromOffsetInstant` writes. A local date-time, a date and a time return `""`: there is no
+ *   offset to write.
+ * - **The digits are the value's own wall clock**, never the UTC clock:
+ *   `2024-01-01T00:30:00+02:00` under `303` is `202401010030+02`. A `Z` instant is written on
+ *   the UTC clock with `+0000` or `+00`.
+ * - **`ZZZ` (`303`, `304`) is always written `±HH`**, the hours-only form of UN/ECE
+ *   Recommendation 7 ¶12, never `UTC` or `GMT`. **It holds whole hours only**: an offset such
+ *   as `+05:30` returns `""` under `303` and `304`. Write it under `205` or `208`, whose `ZHHMM`
+ *   holds hours and minutes.
+ * - **An offset with a non-zero seconds part returns `""` under every code**, `205` and `208`
+ *   included. A seconds part of zero (`+02:00:00`) is the offset `+02:00` and is written.
+ *   `ZHHMM` holds hours and minutes and `ZZZ` hours, so no mask holds the seconds of an offset
+ *   such as `-00:44:30`, the offset `Africa/Monrovia` kept until 1972. An offset is never
+ *   rounded: the value would name another instant. Write the same instant in `Z` form
+ *   instead.
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped, and
+ *   `205` and `303` drop the seconds too.
+ * - **The output is the element value, not segment text.** `+` is the EDIFACT data element
+ *   separator, so a value that holds one must be released when it is placed in a segment: write
+ *   `?+`. The function does not add the release character.
+ * - A bracketed RFC 9557 time zone is read as `toOffsetInstant` reads it: it must agree with
+ *   the offset, and beside `Z` it sets the clock the digits are written on.
+ * - A wall clock whose year is outside 0000–9999 returns `""`.
+ * - Returns `""` for any other code, a code of another kind included, and for a non-string
+ *   argument.
+ *
+ * @param value ISO 8601 date-time with an offset or `Z` (e.g. "2024-06-15T14:30:00+02:00")
+ * @param format The data element 2379 format code
+ * @returns the data element 2380 value, unescaped, or "" on invalid input
+ *
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00+02:00", "205") // "202406151430+0200"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:45+05:30", "208") // "20240615143045+0530"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00+02:00", "303") // "202406151430+02"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:45-05:00", "304") // "20240615143045-05"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00Z", "205") // "202406151430+0000"
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00Z", "303") // "202406151430+00" (never "UTC")
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:45.9+02:00", "205") // "202406151430+0200" (cut to the minute)
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00+05:30", "303") // "" (the field holds whole hours: use 205 or 208)
+ * @example formatEdifactOffsetDateTime("1960-01-01T00:20:00-00:44:30", "208") // "" (no mask holds a non-zero seconds part of an offset)
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00", "205") // "" (a local date-time has no offset to write)
+ * @example formatEdifactOffsetDateTime("2024-06-15T14:30:00+02:00", "203") // "" (a local code: use formatEdifactDateTime)
+ */
+export function formatEdifactOffsetDateTime(value, format) {
+    try {
+        return writeEdiValue("edifact", "offsetDateTime", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { EdifactTimeFormat } from "../../types/edi.js";
+/**
+ * Write an ISO 8601 time as a UN/EDIFACT `DTM` value (data element 2380) in a time format code
+ * (data element 2379). The inverse of `parseEdifactTime`.
+ *
+ * Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `401` | `HHMM` | "Time without seconds: H = Hour; m = Minute." |
+ * | `402` | `HHMMSS` | "Time with seconds: H = Hour; m = Minute; s = Seconds." |
+ *
+ * - `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
+ *   `401` drops the seconds too. `14:30:59.9` is `1430` under `401` and `143059` under `402`,
+ *   and `parseEdifactTime` reads back the time the mask holds.
+ * - 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 The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactTime("14:30:00", "401") // "1430"
+ * @example formatEdifactTime("14:30:45", "402") // "143045"
+ * @example formatEdifactTime("14:30:45", "401") // "1430" (the mask has no seconds)
+ * @example formatEdifactTime("14:30:45.9", "402") // "143045" (cut, not rounded)
+ * @example formatEdifactTime("14:30", "402") // "143000"
+ * @example formatEdifactTime("2024-06-15T14:30:00", "401") // "" (a date-time is not a time)
+ * @example formatEdifactTime("24:00", "401") // "" (not a real time)
+ */
+export declare function formatEdifactTime(value: string, format: EdifactTimeFormat): string;

package/dist/intermodal/format/formatEdifactTime.js

@@ -0,0 +1,43 @@
+import { writeEdiValue } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write an ISO 8601 time as a UN/EDIFACT `DTM` value (data element 2380) in a time format code
+ * (data element 2379). The inverse of `parseEdifactTime`.
+ *
+ * Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `401` | `HHMM` | "Time without seconds: H = Hour; m = Minute." |
+ * | `402` | `HHMMSS` | "Time with seconds: H = Hour; m = Minute; s = Seconds." |
+ *
+ * - `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
+ *   `401` drops the seconds too. `14:30:59.9` is `1430` under `401` and `143059` under `402`,
+ *   and `parseEdifactTime` reads back the time the mask holds.
+ * - 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 The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactTime("14:30:00", "401") // "1430"
+ * @example formatEdifactTime("14:30:45", "402") // "143045"
+ * @example formatEdifactTime("14:30:45", "401") // "1430" (the mask has no seconds)
+ * @example formatEdifactTime("14:30:45.9", "402") // "143045" (cut, not rounded)
+ * @example formatEdifactTime("14:30", "402") // "143000"
+ * @example formatEdifactTime("2024-06-15T14:30:00", "401") // "" (a date-time is not a time)
+ * @example formatEdifactTime("24:00", "401") // "" (not a real time)
+ */
+export function formatEdifactTime(value, format) {
+    try {
+        return writeEdiValue("edifact", "time", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,47 @@
+import type { OffsetInstant } from "../../instant/convert/toOffsetInstant.js";
+import type { EpcisEventTime } from "../../types/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: "-04:00", timeZone: "America/New_York" }) // { eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-04:00" } (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 declare function formatEpcisEvent(value: OffsetInstant): EpcisEventTime | null;

package/dist/intermodal/format/formatEpcisEvent.js

@@ -0,0 +1,79 @@
+import { Temporal } from "@js-temporal/polyfill";
+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: "-04:00", timeZone: "America/New_York" }) // { eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-04:00" } (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 "";
+    }
+}