@northguild/gmt 1.18.0 → 1.20.0

package/dist/intermodal/format/formatEdifactDate.js

@@ -0,0 +1,42 @@
+import { writeEdiValue } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write an ISO 8601 date as a UN/EDIFACT `DTM` value (data element 2380) in a date format code
+ * (data element 2379). The inverse of `parseEdifactDate`: what one writes, the other reads back.
+ *
+ * The mask and description are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format code
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `102` | `CCYYMMDD` | "Calendar date: C = Century ; Y = Year ; M = Month ; D = Day." |
+ *
+ * - `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.
+ * - A year outside 0000–9999 returns `""`: `CCYY` is four digits and no sign.
+ * - No function writes a two-digit year (`101`, `YYMMDD`): the one date code that is written
+ *   holds the whole year.
+ * - 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 The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactDate("2024-06-15", "102") // "20240615"
+ * @example formatEdifactDate("0987-01-05", "102") // "09870105"
+ * @example formatEdifactDate("2024-06-15T14:30:00", "102") // "" (a date-time is not a date)
+ * @example formatEdifactDate("2023-02-29", "102") // "" (not a real date)
+ * @example formatEdifactDate("+010000-01-01", "102") // "" (the mask holds four digits of year)
+ * @example formatEdifactDate("2024-06-15", "203") // "" (a date-time code: use formatEdifactDateTime)
+ */
+export function formatEdifactDate(value, format) {
+    try {
+        return writeEdiValue("edifact", "date", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { EdifactDatePeriodFormat } from "../../types/edi.js";
+/**
+ * Write two ISO 8601 dates as a UN/EDIFACT `DTM` period (data element 2380) in a date period
+ * format code (data element 2379). The inverse of `parseEdifactDatePeriod`.
+ *
+ * The mask and description are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format code
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `718` | `CCYYMMDD-CCYYMMDD` | "A period of time specified by giving the start date followed by the end date (both including century). Data is to be transmitted as consecutive characters without hyphen." |
+ *
+ * - `start` and `end` are dates, as `isValidDate` accepts them: the two members
+ *   `parseEdifactDatePeriod` returns. A date-time or an instant returns `""`.
+ * - **The period is written without a hyphen**, as every directory read says it is
+ *   transmitted: 15 to 20 June 2024 is `2024061520240620`.
+ * - **An end before its start returns `""`**: a reversed period 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 period starts on (e.g. "2024-06-15")
+ * @param end ISO 8601 date the period ends on (e.g. "2024-06-20")
+ * @param format The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactDatePeriod("2024-06-15", "2024-06-20", "718") // "2024061520240620"
+ * @example formatEdifactDatePeriod("2024-06-15", "2024-06-15", "718") // "2024061520240615"
+ * @example formatEdifactDatePeriod("2024-06-20", "2024-06-15", "718") // "" (the end precedes the start)
+ * @example formatEdifactDatePeriod("2024-06-15T14:30", "2024-06-20", "718") // "" (a date-time is not a date)
+ * @example formatEdifactDatePeriod("2024-06-15", "2023-02-29", "718") // "" (not a real date)
+ */
+export declare function formatEdifactDatePeriod(start: string, end: string, format: EdifactDatePeriodFormat): string;

package/dist/intermodal/format/formatEdifactDatePeriod.js

@@ -0,0 +1,43 @@
+import { writeEdiRange } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write two ISO 8601 dates as a UN/EDIFACT `DTM` period (data element 2380) in a date period
+ * format code (data element 2379). The inverse of `parseEdifactDatePeriod`.
+ *
+ * The mask and description are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format code
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `718` | `CCYYMMDD-CCYYMMDD` | "A period of time specified by giving the start date followed by the end date (both including century). Data is to be transmitted as consecutive characters without hyphen." |
+ *
+ * - `start` and `end` are dates, as `isValidDate` accepts them: the two members
+ *   `parseEdifactDatePeriod` returns. A date-time or an instant returns `""`.
+ * - **The period is written without a hyphen**, as every directory read says it is
+ *   transmitted: 15 to 20 June 2024 is `2024061520240620`.
+ * - **An end before its start returns `""`**: a reversed period 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 period starts on (e.g. "2024-06-15")
+ * @param end ISO 8601 date the period ends on (e.g. "2024-06-20")
+ * @param format The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactDatePeriod("2024-06-15", "2024-06-20", "718") // "2024061520240620"
+ * @example formatEdifactDatePeriod("2024-06-15", "2024-06-15", "718") // "2024061520240615"
+ * @example formatEdifactDatePeriod("2024-06-20", "2024-06-15", "718") // "" (the end precedes the start)
+ * @example formatEdifactDatePeriod("2024-06-15T14:30", "2024-06-20", "718") // "" (a date-time is not a date)
+ * @example formatEdifactDatePeriod("2024-06-15", "2023-02-29", "718") // "" (not a real date)
+ */
+export function formatEdifactDatePeriod(start, end, format) {
+    try {
+        return writeEdiRange("edifact", "datePeriod", format, start, end);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,37 @@
+import type { EdifactDateTimeFormat } from "../../types/edi.js";
+/**
+ * Write an ISO 8601 local date-time as a UN/EDIFACT `DTM` value (data element 2380) in a format
+ * code with no offset (data element 2379). The inverse of `parseEdifactDateTime`.
+ *
+ * Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `203` | `CCYYMMDDHHMM` | "Calendar date including time with minutes" |
+ * | `204` | `CCYYMMDDHHMMSS` | "Calendar date including time with seconds" |
+ *
+ * - `value` is a local date-time, as `isValidDateTime` accepts it. A date, a time, an instant
+ *   ending in `Z` and a date-time with an offset return `""`: these codes hold no offset. Write
+ *   an instant with `formatEdifactOffsetDateTime`.
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped, and
+ *   `203` drops the seconds too. `2024-06-15T14:30:45.9` is `202406151430` under `203` and
+ *   `20240615143045` under `204`.
+ * - 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 The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactDateTime("2024-06-15T14:30:00", "203") // "202406151430"
+ * @example formatEdifactDateTime("2024-06-15T14:30:45", "204") // "20240615143045"
+ * @example formatEdifactDateTime("2024-06-15T14:30:45", "203") // "202406151430" (the mask has no seconds)
+ * @example formatEdifactDateTime("2024-06-15T14:30:45.9", "204") // "20240615143045" (cut, not rounded)
+ * @example formatEdifactDateTime("2024-06-15", "203") // "" (a date is not a date-time)
+ * @example formatEdifactDateTime("2024-06-15T14:30:00Z", "203") // "" (the code holds no offset)
+ * @example formatEdifactDateTime("2023-02-29T14:30:00", "203") // "" (not a real date)
+ */
+export declare function formatEdifactDateTime(value: string, format: EdifactDateTimeFormat): string;

package/dist/intermodal/format/formatEdifactDateTime.js

@@ -0,0 +1,45 @@
+import { writeEdiValue } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write an ISO 8601 local date-time as a UN/EDIFACT `DTM` value (data element 2380) in a format
+ * code with no offset (data element 2379). The inverse of `parseEdifactDateTime`.
+ *
+ * Masks and descriptions are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format codes
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `203` | `CCYYMMDDHHMM` | "Calendar date including time with minutes" |
+ * | `204` | `CCYYMMDDHHMMSS` | "Calendar date including time with seconds" |
+ *
+ * - `value` is a local date-time, as `isValidDateTime` accepts it. A date, a time, an instant
+ *   ending in `Z` and a date-time with an offset return `""`: these codes hold no offset. Write
+ *   an instant with `formatEdifactOffsetDateTime`.
+ * - Precision is cut to the mask, never rounded: a fraction of a second is always dropped, and
+ *   `203` drops the seconds too. `2024-06-15T14:30:45.9` is `202406151430` under `203` and
+ *   `20240615143045` under `204`.
+ * - 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 The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactDateTime("2024-06-15T14:30:00", "203") // "202406151430"
+ * @example formatEdifactDateTime("2024-06-15T14:30:45", "204") // "20240615143045"
+ * @example formatEdifactDateTime("2024-06-15T14:30:45", "203") // "202406151430" (the mask has no seconds)
+ * @example formatEdifactDateTime("2024-06-15T14:30:45.9", "204") // "20240615143045" (cut, not rounded)
+ * @example formatEdifactDateTime("2024-06-15", "203") // "" (a date is not a date-time)
+ * @example formatEdifactDateTime("2024-06-15T14:30:00Z", "203") // "" (the code holds no offset)
+ * @example formatEdifactDateTime("2023-02-29T14:30:00", "203") // "" (not a real date)
+ */
+export function formatEdifactDateTime(value, format) {
+    try {
+        return writeEdiValue("edifact", "dateTime", format, value);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,40 @@
+import type { EdifactDateTimePeriodFormat } from "../../types/edi.js";
+/**
+ * Write two ISO 8601 local date-times as a UN/EDIFACT `DTM` period (data element 2380) in a
+ * date-time period format code (data element 2379). The inverse of
+ * `parseEdifactDateTimePeriod`.
+ *
+ * The mask and description are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format code
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `719` | `CCYYMMDDHHMM-CCYYMMDDHHMM` | "A period of time which includes the century, year, month, day, hour and minute. Format of period to be given in actual message without hyphen." |
+ *
+ * - `start` and `end` are local date-times, as `isValidDateTime` accepts them: the two members
+ *   `parseEdifactDateTimePeriod` returns. A date, an instant ending in `Z` and a date-time with
+ *   an offset return `""`: the code holds no offset.
+ * - **The period is written without a hyphen**: 15 June 14:30 to 20 June 16:00 is
+ *   `202406151430202406201600`.
+ * - Precision is cut to the mask, never rounded: seconds and a fraction of a second are dropped
+ *   from both ends.
+ * - **An end before its start returns `""`**: a reversed period names no span of time. The ends
+ *   are compared as given, before either is cut to the minute. 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 period starts at (e.g. "2024-06-15T14:30:00")
+ * @param end ISO 8601 local date-time the period ends at (e.g. "2024-06-20T16:00:00")
+ * @param format The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactDateTimePeriod("2024-06-15T14:30:00", "2024-06-20T16:00:00", "719") // "202406151430202406201600"
+ * @example formatEdifactDateTimePeriod("2024-06-15T14:30:45", "2024-06-20T16:00:59", "719") // "202406151430202406201600" (the mask has no seconds)
+ * @example formatEdifactDateTimePeriod("2024-06-15T14:31:00", "2024-06-15T14:30:00", "719") // "" (the end precedes the start)
+ * @example formatEdifactDateTimePeriod("2024-06-15", "2024-06-20", "719") // "" (dates: use formatEdifactDatePeriod)
+ * @example formatEdifactDateTimePeriod("2024-06-15T14:30:00Z", "2024-06-20T16:00:00Z", "719") // "" (the code holds no offset)
+ */
+export declare function formatEdifactDateTimePeriod(start: string, end: string, format: EdifactDateTimePeriodFormat): string;

package/dist/intermodal/format/formatEdifactDateTimePeriod.js

@@ -0,0 +1,48 @@
+import { writeEdiRange } from "../../internal/ediDateTimeWriter.js";
+/**
+ * Write two ISO 8601 local date-times as a UN/EDIFACT `DTM` period (data element 2380) in a
+ * date-time period format code (data element 2379). The inverse of
+ * `parseEdifactDateTimePeriod`.
+ *
+ * The mask and description are the UNTDID directory's, read from
+ * [UNECE's D.21B page as archived](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm).
+ *
+ * ### Format code
+ * | Code | Mask | The directory's description |
+ * |---|---|---|
+ * | `719` | `CCYYMMDDHHMM-CCYYMMDDHHMM` | "A period of time which includes the century, year, month, day, hour and minute. Format of period to be given in actual message without hyphen." |
+ *
+ * - `start` and `end` are local date-times, as `isValidDateTime` accepts them: the two members
+ *   `parseEdifactDateTimePeriod` returns. A date, an instant ending in `Z` and a date-time with
+ *   an offset return `""`: the code holds no offset.
+ * - **The period is written without a hyphen**: 15 June 14:30 to 20 June 16:00 is
+ *   `202406151430202406201600`.
+ * - Precision is cut to the mask, never rounded: seconds and a fraction of a second are dropped
+ *   from both ends.
+ * - **An end before its start returns `""`**: a reversed period names no span of time. The ends
+ *   are compared as given, before either is cut to the minute. 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 period starts at (e.g. "2024-06-15T14:30:00")
+ * @param end ISO 8601 local date-time the period ends at (e.g. "2024-06-20T16:00:00")
+ * @param format The data element 2379 format code
+ * @returns the data element 2380 value, or "" on invalid input
+ *
+ * @example formatEdifactDateTimePeriod("2024-06-15T14:30:00", "2024-06-20T16:00:00", "719") // "202406151430202406201600"
+ * @example formatEdifactDateTimePeriod("2024-06-15T14:30:45", "2024-06-20T16:00:59", "719") // "202406151430202406201600" (the mask has no seconds)
+ * @example formatEdifactDateTimePeriod("2024-06-15T14:31:00", "2024-06-15T14:30:00", "719") // "" (the end precedes the start)
+ * @example formatEdifactDateTimePeriod("2024-06-15", "2024-06-20", "719") // "" (dates: use formatEdifactDatePeriod)
+ * @example formatEdifactDateTimePeriod("2024-06-15T14:30:00Z", "2024-06-20T16:00:00Z", "719") // "" (the code holds no offset)
+ */
+export function formatEdifactDateTimePeriod(start, end, format) {
+    try {
+        return writeEdiRange("edifact", "dateTimePeriod", format, start, end);
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return "";
+    }
+}

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: "+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 declare function formatEpcisEvent(value: OffsetInstant): EpcisEventTime | null;