@northguild/gmt 1.17.0 → 1.19.0

package/dist/intermodal/calculate/multimodalETA.js

@@ -0,0 +1,145 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { exactDurationNanoseconds } from "../../internal/index.js";
+import { formatHourDuration } from "../../internal/hourDurationString.js";
+import { scheduleDelivery, } from "../../transport/calculate/scheduleDelivery.js";
+import { isObject } from "../../internal/isObject.js";
+/**
+ * Every field of a `Leg`, each read once into a plain copy. Typed as a record of `keyof Leg`, so a
+ * field added to `Leg` and missing here, or a key here that `Leg` does not have, fails to compile
+ * rather than being dropped from the copy.
+ */
+const LEG_FIELDS = {
+    departure: true,
+    duration: true,
+    timeZone: true,
+    dwellAfter: true,
+    mode: true,
+    origin: true,
+    destination: true,
+};
+const LEG_KEYS = Object.keys(LEG_FIELDS);
+/**
+ * A plain copy of one leg with every field read exactly once, so the schedule and the totals are
+ * computed from the same values even when a field is a getter. An undefined field stays absent,
+ * which `scheduleDelivery` reads as omitted either way. A leg that is not an object is passed
+ * through for `scheduleDelivery` to refuse.
+ */
+function snapshotLeg(leg) {
+    if (!isObject(leg)) {
+        return leg;
+    }
+    const copy = {};
+    for (const key of LEG_KEYS) {
+        const value = Reflect.get(leg, key);
+        if (value !== undefined) {
+            copy[key] = value;
+        }
+    }
+    return copy;
+}
+/**
+ * Compute an end-to-end ETA across the legs of a multimodal move, and report the time in transit
+ * and the time in dwell separately.
+ *
+ * A truck→ship→rail move spends its time two ways: moving, and sitting at a handoff. The two are
+ * forecast differently and fail differently, so one opaque total hides the part a planner needs.
+ * `multimodalETA` schedules the legs with `scheduleDelivery` and splits the elapsed time from the
+ * first departure to the ETA into the two.
+ *
+ * - **The legs are `scheduleDelivery`'s.** Each leg's arrival plus its `dwellAfter` is the next
+ *   leg's departure unless the next leg names a scheduled `departure`; a scheduled departure
+ *   inside the dwell is a missed connection. Departures, zones and every validity rule are that
+ *   function's, and `eta` is its `eta`.
+ * - **Local-time resolution policy (`"compatible"`), as `scheduleDelivery` applies it.** A zoneless
+ *   first departure read in `startTimeZone`, a zoneless later-leg departure read in the previous
+ *   leg's `timeZone`, and a zoned departure written without an offset are wall times. An
+ *   **ambiguous** one (a fall-back hour the clock ran through twice) resolves to the **earlier**
+ *   instant and a **nonexistent** one (a spring-forward hour the clock skipped) to the **later**
+ *   instant, except that on any leg but the first a repeated hour takes the earliest pass at or
+ *   after the previous arrival plus its dwell, the first the cargo can catch. Write the offset to
+ *   pick a pass yourself.
+ * - **`totalTransit` is every leg's `duration` added up.** Durations are exact time: a day is 24
+ *   hours, and years, months and weeks return `null`. The sum is elapsed time, so a leg across a
+ *   DST change counts the hours that passed, not the change in the wall clock.
+ * - **`totalDwell` is the time actually spent at the handoffs**: each leg's departure minus the
+ *   previous leg's arrival. When every leg after the first chains from its predecessor, that is the
+ *   sum of the `dwellAfter` values. When a leg waits for a scheduled departure, the wait is dwell
+ *   too: the cargo is at the handoff either way. Dwell is never estimated; it is the caller's
+ *   `dwellAfter` and schedule.
+ * - **Transit plus dwell is the elapsed time** from the first departure to the ETA, exactly.
+ * - **The last leg's `dwellAfter` is not dwell.** There is no handoff after it, so it moves
+ *   nothing; it is still checked as a duration, as `scheduleDelivery` checks it.
+ * - Both totals are ISO 8601 durations with hours as the largest unit (`"PT400H"`, `"PT2H15M"`),
+ *   as `crossingTime` and `dwellTime` report elapsed time; they do not depend on any zone.
+ * - Each leg's fields are read once, so the totals always agree with the schedule.
+ * - An empty legs array returns `{ eta: "", totalLegs: 0, totalTransit: "PT0S", totalDwell: "PT0S" }`.
+ *   Returns `null` on invalid input: a non-array, a malformed leg, a missed connection, an invalid
+ *   `startTimeZone`, or an arrival outside the instant range.
+ * - An offset with seconds (`-00:44:30`) as a leg's `timeZone` or as `startTimeZone` returns
+ *   `null`, as in `scheduleDelivery`. A written zone cannot carry seconds (RFC 9557 §4.1), so `eta`
+ *   could not name it. Pass the IANA name.
+ *
+ * @param legs the journey's legs, in travel order
+ * @param options The zone a zoneless first-leg departure is read in
+ * @returns the ETA, the number of legs, and the total transit and dwell, or null on invalid input
+ *
+ * @example multimodalETA([{ departure: "2024-06-10T08:00:00+08:00[Asia/Shanghai]", duration: "PT6H", timeZone: "Asia/Shanghai", dwellAfter: "P2D" }, { duration: "P14DT6H", timeZone: "America/Los_Angeles", dwellAfter: "PT36H" }, { duration: "PT52H", timeZone: "America/Chicago" }]) // { eta: "2024-06-29T23:00:00-05:00[America/Chicago]", totalLegs: 3, totalTransit: "PT400H", totalDwell: "PT84H" } (truck, ship and rail: 484 hours door to door)
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { duration: "PT5H", timeZone: "Asia/Tokyo" }]) // { eta: "2024-06-16T02:00:00+09:00[Asia/Tokyo]", totalLegs: 2, totalTransit: "PT15H", totalDwell: "PT2H" }
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T13:00:00Z", duration: "PT1H", timeZone: "UTC" }]) // { eta: "2024-06-15T14:00:00+00:00[UTC]", totalLegs: 2, totalTransit: "PT11H", totalDwell: "PT3H" } (two hours' handling and an hour's wait for the 13:00 departure)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00Z", duration: "PT36H", timeZone: "Asia/Tokyo", dwellAfter: "PT5H" }]) // { eta: "2024-06-17T07:00:00+09:00[Asia/Tokyo]", totalLegs: 1, totalTransit: "PT36H", totalDwell: "PT0S" } (no handoff after the last leg)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00", duration: "PT1H", timeZone: "UTC" }], { startTimeZone: "America/New_York" }) // { eta: "2024-06-15T15:00:00+00:00[UTC]", totalLegs: 1, totalTransit: "PT1H", totalDwell: "PT0S" } (a published 10:00 wall time, read in New York)
+ * @example multimodalETA([]) // { eta: "", totalLegs: 0, totalTransit: "PT0S", totalDwell: "PT0S" }
+ * @example multimodalETA([{ departure: "2024-06-15T00:00:00Z", duration: "PT10H", timeZone: "UTC", dwellAfter: "PT2H" }, { departure: "2024-06-15T11:00:00Z", duration: "PT1H", timeZone: "UTC" }]) // null (the connection leaves inside the dwell: missed)
+ * @example multimodalETA([{ departure: "2024-06-15T10:00:00Z", duration: "P1M", timeZone: "UTC" }]) // null (calendar units have no exact length)
+ * @example multimodalETA("legs") // null
+ */
+export function multimodalETA(legs, options) {
+    try {
+        if (!Array.isArray(legs)) {
+            return null;
+        }
+        const snapshot = legs.map(snapshotLeg);
+        const schedule = scheduleDelivery(snapshot, options);
+        if (schedule === null) {
+            return null;
+        }
+        const first = schedule.legTimes.at(0);
+        const last = schedule.legTimes.at(-1);
+        if (first === undefined || last === undefined) {
+            return {
+                eta: "",
+                totalLegs: 0,
+                totalTransit: "PT0S",
+                totalDwell: "PT0S",
+            };
+        }
+        // scheduleDelivery has accepted every duration as exact and not negative.
+        const durations = snapshot.map((leg) => exactDurationNanoseconds(leg.duration));
+        if (durations.some((nanoseconds) => nanoseconds === null)) {
+            return null;
+        }
+        const transit = durations.reduce((sum, ns) => sum + ns, 0n);
+        // Arrivals are the Z strings scheduleDelivery wrote. The first leg left its own duration
+        // before it arrived; the time between that departure and the last arrival that was not spent
+        // moving was spent at the handoffs.
+        const departure = Temporal.Instant.from(first.arrival).epochNanoseconds -
+            durations[0];
+        const elapsed = Temporal.Instant.from(last.arrival).epochNanoseconds - departure;
+        const totalTransit = formatHourDuration(transit);
+        const totalDwell = formatHourDuration(elapsed - transit);
+        if (totalTransit === "" || totalDwell === "") {
+            return null;
+        }
+        return {
+            eta: schedule.eta,
+            totalLegs: snapshot.length,
+            totalTransit,
+            totalDwell,
+        };
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Which date on a bill of lading a value is rendered for, one per dated field of the DCSA
+ * Bill of Lading 3.0 `TransportDocument`:
+ *
+ * - `issue`: the date the B/L was issued, local to the place of issue (DCSA `issueDate`).
+ * - `received`: the date the last container was in the terminal, customs-cleared against the
+ *   intended vessel, on a received-for-shipment B/L (DCSA `receivedForShipmentDate`).
+ * - `shippedOnBoard`: the date the last container was loaded aboard the vessel, on a
+ *   shipped-on-board B/L (DCSA `shippedOnBoardDate`).
+ *
+ * All three are local calendar dates, so each renders the same way.
+ */
+export type BillOfLadingEvent = "issue" | "received" | "shippedOnBoard";
+/** Options for `bolTimestamp`. */
+export interface BolTimestampOptions {
+    /**
+     * The zone of the place the event happened, as an IANA name or a UTC offset: the place of issue
+     * for `issue`, and the terminal at the port of loading for `received` and `shippedOnBoard`. A UTC
+     * offset is a time zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`,
+     * what `getTimeZoneOffset` returns). It is required, because every B/L date is local and a UTC
+     * date is a different date for part of every day.
+     */
+    timeZone: string;
+}
+/**
+ * Render an instant as the date a bill of lading carries for an event: the calendar date on the
+ * local clock where the event happened.
+ *
+ * A B/L date is a contractual date, not a timestamp. The DCSA Bill of Lading 3.0 standard
+ * (`TransportDocument`) types `issueDate` ("Local date when the transport document has been
+ * issued"), `receivedForShipmentDate` and `shippedOnBoardDate` as `format: date`: a date with no
+ * time and no offset. A system that records the loading as an instant has to turn it back into
+ * that local date, and taking the UTC date gets it wrong in both directions: 21:00 in New York is
+ * 01:00Z the next day, and 07:00 in Shanghai is 23:00Z the day before.
+ *
+ * - **The result is a date with no time component**, `YYYY-MM-DD`, as
+ *   `Temporal.PlainDate.prototype.toString` writes it. A year outside 0000–9999 is written with a
+ *   sign and six digits (`"+275760-09-13"`).
+ * - **`timeZone` is required.** Every B/L date is local, so there is no UTC default and no
+ *   system zone: omitting it returns `""`. The zone is the caller's fact; GMT does not resolve a
+ *   port or a place of issue to a zone.
+ * - **`event` names which date this is** and is checked against the three `BillOfLadingEvent`
+ *   values; anything else returns `""`. All three are local calendar dates, so they render the
+ *   same way: the event keeps the call site honest about which field it fills, and the zone is the
+ *   one that differs by event.
+ * - `value` is any instant `isValidInstant` accepts: `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read; a bracketed zone in `value` is not the zone the date
+ *   is read in, `timeZone` is. An offset written to the minute that is the bracketed zone's
+ *   sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the
+ *   zone gives. A zoneless wall time or a bare date names no moment and returns `""`.
+ * - **No disambiguation arises.** The input is a moment, and a moment has exactly one local date
+ *   in any zone. The date changes at the zone's real midnight. A date the zone deleted is never
+ *   returned (`Pacific/Apia` skipped 2011-12-30), and after a fall-back that re-enters the
+ *   previous date the result is that date again, as the clock showed it (`America/Goose_Bay`,
+ *   7 November 2010).
+ * - Returns `""` when `value` is not an instant, `event` is not one of the three, `options` is not
+ *   an object, or `timeZone` is missing or invalid.
+ *
+ * @param value ISO 8601 instant string of the event (e.g. "2024-06-16T01:00:00Z")
+ * @param event which B/L date the value is rendered for
+ * @param options The zone of the place the event happened
+ * @returns the local calendar date as "YYYY-MM-DD", or "" on invalid input
+ *
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "America/New_York" }) // "2024-06-15" (loaded at 21:00 local; the UTC date is the 16th)
+ * @example bolTimestamp("2024-06-14T23:00:00Z", "shippedOnBoard", { timeZone: "Asia/Shanghai" }) // "2024-06-15" (loaded at 07:00 local; the UTC date is the 14th)
+ * @example bolTimestamp("2024-06-15T21:00:00-04:00", "received", { timeZone: "America/New_York" }) // "2024-06-15"
+ * @example bolTimestamp("2024-06-16T09:00:00+08:00[Asia/Shanghai]", "issue", { timeZone: "America/New_York" }) // "2024-06-15" (the bracketed zone is not the zone the date is read in)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "+08:00" }) // "2024-06-16" (a fixed offset)
+ * @example bolTimestamp("2011-12-30T10:00:00Z", "shippedOnBoard", { timeZone: "Pacific/Apia" }) // "2011-12-31" (Samoa deleted 30 December)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard") // "" (every B/L date is local: the zone is required)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "loaded", { timeZone: "America/New_York" }) // "" (not a B/L event)
+ * @example bolTimestamp("2024-06-15T21:00:00", "shippedOnBoard", { timeZone: "America/New_York" }) // "" (no offset: not a moment)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "America/Nowhere" }) // ""
+ * @example bolTimestamp("1970-01-01T00:30:00Z", "issue", { timeZone: "-00:44:30" }) // "1969-12-31" (23:45:30 the day before, at a stored offset with seconds)
+ */
+export declare function bolTimestamp(value: string, event: BillOfLadingEvent, options: BolTimestampOptions): string;

package/dist/intermodal/format/bolTimestamp.js

@@ -0,0 +1,78 @@
+import { frameWallClock, instantFrom, isOptionsArgument, zoneFrame, } from "../../internal/index.js";
+import { isValidInstant } from "../../precision/validate/isValidInstant.js";
+/** The three `BillOfLadingEvent` values. */
+const BILL_OF_LADING_EVENTS = new Set([
+    "issue",
+    "received",
+    "shippedOnBoard",
+]);
+/**
+ * Render an instant as the date a bill of lading carries for an event: the calendar date on the
+ * local clock where the event happened.
+ *
+ * A B/L date is a contractual date, not a timestamp. The DCSA Bill of Lading 3.0 standard
+ * (`TransportDocument`) types `issueDate` ("Local date when the transport document has been
+ * issued"), `receivedForShipmentDate` and `shippedOnBoardDate` as `format: date`: a date with no
+ * time and no offset. A system that records the loading as an instant has to turn it back into
+ * that local date, and taking the UTC date gets it wrong in both directions: 21:00 in New York is
+ * 01:00Z the next day, and 07:00 in Shanghai is 23:00Z the day before.
+ *
+ * - **The result is a date with no time component**, `YYYY-MM-DD`, as
+ *   `Temporal.PlainDate.prototype.toString` writes it. A year outside 0000–9999 is written with a
+ *   sign and six digits (`"+275760-09-13"`).
+ * - **`timeZone` is required.** Every B/L date is local, so there is no UTC default and no
+ *   system zone: omitting it returns `""`. The zone is the caller's fact; GMT does not resolve a
+ *   port or a place of issue to a zone.
+ * - **`event` names which date this is** and is checked against the three `BillOfLadingEvent`
+ *   values; anything else returns `""`. All three are local calendar dates, so they render the
+ *   same way: the event keeps the call site honest about which field it fills, and the zone is the
+ *   one that differs by event.
+ * - `value` is any instant `isValidInstant` accepts: `Z`, an offset, or an offset with a
+ *   bracketed zone. Only the instant is read; a bracketed zone in `value` is not the zone the date
+ *   is read in, `timeZone` is. An offset written to the minute that is the bracketed zone's
+ *   sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for −00:44:30) names the instant the
+ *   zone gives. A zoneless wall time or a bare date names no moment and returns `""`.
+ * - **No disambiguation arises.** The input is a moment, and a moment has exactly one local date
+ *   in any zone. The date changes at the zone's real midnight. A date the zone deleted is never
+ *   returned (`Pacific/Apia` skipped 2011-12-30), and after a fall-back that re-enters the
+ *   previous date the result is that date again, as the clock showed it (`America/Goose_Bay`,
+ *   7 November 2010).
+ * - Returns `""` when `value` is not an instant, `event` is not one of the three, `options` is not
+ *   an object, or `timeZone` is missing or invalid.
+ *
+ * @param value ISO 8601 instant string of the event (e.g. "2024-06-16T01:00:00Z")
+ * @param event which B/L date the value is rendered for
+ * @param options The zone of the place the event happened
+ * @returns the local calendar date as "YYYY-MM-DD", or "" on invalid input
+ *
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "America/New_York" }) // "2024-06-15" (loaded at 21:00 local; the UTC date is the 16th)
+ * @example bolTimestamp("2024-06-14T23:00:00Z", "shippedOnBoard", { timeZone: "Asia/Shanghai" }) // "2024-06-15" (loaded at 07:00 local; the UTC date is the 14th)
+ * @example bolTimestamp("2024-06-15T21:00:00-04:00", "received", { timeZone: "America/New_York" }) // "2024-06-15"
+ * @example bolTimestamp("2024-06-16T09:00:00+08:00[Asia/Shanghai]", "issue", { timeZone: "America/New_York" }) // "2024-06-15" (the bracketed zone is not the zone the date is read in)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "+08:00" }) // "2024-06-16" (a fixed offset)
+ * @example bolTimestamp("2011-12-30T10:00:00Z", "shippedOnBoard", { timeZone: "Pacific/Apia" }) // "2011-12-31" (Samoa deleted 30 December)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard") // "" (every B/L date is local: the zone is required)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "loaded", { timeZone: "America/New_York" }) // "" (not a B/L event)
+ * @example bolTimestamp("2024-06-15T21:00:00", "shippedOnBoard", { timeZone: "America/New_York" }) // "" (no offset: not a moment)
+ * @example bolTimestamp("2024-06-16T01:00:00Z", "shippedOnBoard", { timeZone: "America/Nowhere" }) // ""
+ * @example bolTimestamp("1970-01-01T00:30:00Z", "issue", { timeZone: "-00:44:30" }) // "1969-12-31" (23:45:30 the day before, at a stored offset with seconds)
+ */
+export function bolTimestamp(value, event, options) {
+    try {
+        if (options === undefined || !isOptionsArgument(options)) {
+            return "";
+        }
+        const frame = zoneFrame(options.timeZone);
+        if (frame === null ||
+            !BILL_OF_LADING_EVENTS.has(event) ||
+            !isValidInstant(value)) {
+            return "";
+        }
+        return frameWallClock(instantFrom(value), frame).toPlainDate().toString();
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,34 @@
+import type { EdifactDateFormat } from "../../types/edi.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 declare function formatEdifactDate(value: string, format: EdifactDateFormat): string;

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