@northguild/gmt 1.18.0 → 1.20.0

package/dist/internal/ediDateTimeWriter.js

@@ -0,0 +1,298 @@
+// Not re-exported from `internal/index.ts`, for the reason `ediDateTimeFields.ts` gives:
+// `toOffsetInstant` reads that barrel at module top level, and the `plain/validate` functions
+// import it too, so a barrel entry for this module would close a cycle. Import this file directly.
+import { Temporal } from "./temporal.js";
+import { toOffsetInstant } from "../instant/convert/toOffsetInstant.js";
+import { isValidDate } from "../plain/validate/isValidDate.js";
+import { isValidDateTime } from "../plain/validate/isValidDateTime.js";
+import { isValidTime } from "../plain/validate/isValidTime.js";
+import { MILLISECONDS_PER_DECIMAL_SECOND, ediCodeOfKind, x12TimeElementLayoutOf, } from "./ediGrammar.js";
+import { parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+const MINUTES_PER_HOUR = 60n;
+/** The first and last years a `CCYY` mask can hold: four digits and no sign. */
+const MIN_FOUR_DIGIT_YEAR = 0;
+const MAX_FOUR_DIGIT_YEAR = 9999;
+/**
+ * Write one ISO 8601 value as a single EDI date/time value in a format code of one kind: the
+ * inverse of `readEdiValue`, driven by the same layout tables (`ediGrammar.ts`), so what one
+ * writes the other reads back.
+ *
+ * - The code must be one of `kind`; a code of another kind, a period or range code and a code
+ *   that is not written return `""`.
+ * - The kind fixes the ISO 8601 string `value` must be, as the house plain functions fix theirs:
+ *   a date is what `isValidDate` accepts, a time what `isValidTime` accepts, a local date-time
+ *   what `isValidDateTime` accepts, and a date-time with an offset what `toOffsetInstant` reads
+ *   (an offset, `Z`, or a bracketed zone that agrees). Temporal then reads the fields; no digit
+ *   of the input is sliced.
+ * - Precision is cut to the mask and never refused: a fraction of a second is dropped under
+ *   every 2379 and 1250 mask (none has decimal seconds) and the seconds under a mask with no
+ *   `SS`. The cut is a truncation, never a rounding, so a written value never names a later
+ *   minute or second than its input.
+ * - A value with an offset is written on its own wall clock, never the UTC clock. `ZHHMM` holds
+ *   whole minutes and `ZZZ` whole hours, always written as the signed hour of UN/ECE
+ *   Recommendation 7 ¶12 (`+02`), never `UTC` or `GMT`. An offset the field cannot hold returns
+ *   `""`: rounding it would name another instant.
+ * - A year outside 0000–9999 returns `""`: `CCYY` is four digits and no sign.
+ * - Never throws: any failure is `""`.
+ *
+ * @param standard which element the code belongs to
+ * @param kind the kind of value the calling function writes
+ * @param code the 2379 or 1250 format code
+ * @param value one ISO 8601 string of that kind
+ * @returns the element value, or `""`
+ *
+ * @example writeEdiValue("edifact", "dateTime", "203", "2024-06-15T14:30:45") // "202406151430"
+ * @example writeEdiValue("edifact", "offsetDateTime", "303", "2024-06-15T14:30:00+02:00") // "202406151430+02"
+ * @example writeEdiValue("x12", "date", "DB", "2024-06-15") // "06152024"
+ * @example writeEdiValue("edifact", "offsetDateTime", "303", "2024-06-15T14:30:00+05:30") // "" (ZZZ holds whole hours)
+ * @example writeEdiValue("edifact", "date", "102", "2024-06-15T14:30:00") // "" (a date-time is not a date)
+ */
+export function writeEdiValue(standard, kind, code, value) {
+    try {
+        const entry = ediCodeOfKind(standard, kind, code);
+        if (entry === null || entry.layout.end !== undefined) {
+            return "";
+        }
+        return writeHalf(entry.layout.start, readHalf(entry, value)) ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Write two ISO 8601 values as an EDI period or range in a format code of one kind: the inverse
+ * of `readEdiRange`.
+ *
+ * - The code must be one of `kind`; a single-value code and a code of another kind return `""`.
+ * - Each end is read and written as `writeEdiValue` reads and writes a date or a local
+ *   date-time. The halves are joined by what the standard transmits: nothing for UNTDID 2379,
+ *   one hyphen for X12 1250.
+ * - An end that precedes its start returns `""` (**GMT rule**: a reversed period names no span
+ *   of time). The ends are compared as given, before either is cut to the mask, so an end 35
+ *   seconds before its start is reversed under a minute mask too. An end equal to its start is
+ *   written.
+ * - Never throws: any failure is `""`.
+ *
+ * @param standard which element the code belongs to
+ * @param kind the kind of period or range the calling function writes
+ * @param code the 2379 or 1250 format code
+ * @param start the first end, one ISO 8601 string of the kind's half
+ * @param end the second end, of the same kind
+ * @returns the element value, or `""`
+ *
+ * @example writeEdiRange("edifact", "datePeriod", "718", "2024-06-15", "2024-06-20") // "2024061520240620"
+ * @example writeEdiRange("x12", "dateRange", "RD8", "2024-06-15", "2024-06-20") // "20240615-20240620"
+ * @example writeEdiRange("x12", "dateRange", "RD8", "2024-06-20", "2024-06-15") // "" (the end precedes the start)
+ */
+export function writeEdiRange(standard, kind, code, start, end) {
+    try {
+        const entry = ediCodeOfKind(standard, kind, code);
+        if (entry === null || entry.layout.end === undefined) {
+            return "";
+        }
+        const first = readHalf(entry, start);
+        const second = readHalf(entry, end);
+        if (first === null || second === null || endPrecedesStart(first, second)) {
+            return "";
+        }
+        const written = [
+            writeHalf(entry.layout.start, first),
+            writeHalf(entry.layout.end, second),
+        ];
+        return written.includes(null) ? "" : written.join(entry.rangeSeparator);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Write one ISO 8601 time as an X12 data element 337 (Time) value in one of the element's four
+ * forms: the inverse of `readX12Time`, driven by the same layout table (`ediGrammar.ts`), so
+ * what one writes the other reads back.
+ *
+ * - The form is the element's own mask (`HHMM`, `HHMMSS`, `HHMMSSD`, `HHMMSSDD`), looked up
+ *   exactly and by own key. A data element 1250 code (`TM`, `TS`) and any other string return
+ *   `""`.
+ * - `value` is a time, as `isValidTime` accepts it; Temporal then reads the fields. No digit of
+ *   the input is sliced.
+ * - The form alone fixes the digits written. It is never read off the value, so the width of the
+ *   field does not depend on the data: a time with no fraction is `14300000` under `HHMMSSDD`.
+ * - Precision is cut to the mask and never refused: `D` is the whole tenths of the second and
+ *   `DD` its whole hundredths. The cut is a truncation, never a rounding, so a written value
+ *   never names a later second than its input.
+ * - Never throws: any failure is `""`.
+ *
+ * @param form the element's mask
+ * @param value one ISO 8601 time
+ * @returns the element value, or `""`
+ *
+ * @example writeX12TimeElement("HHMMSSDD", "14:30:00.12") // "14300012"
+ * @example writeX12TimeElement("HHMMSSD", "14:30:00.12") // "1430001" (cut, not rounded)
+ * @example writeX12TimeElement("HHMMSSDD", "14:30") // "14300000"
+ * @example writeX12TimeElement("HHMM", "14:30:45.999") // "1430"
+ * @example writeX12TimeElement("TS", "14:30:45") // "" (a 1250 code, not a mask)
+ * @example writeX12TimeElement("HHMM", "2024-06-15T14:30:00") // "" (a date-time is not a time)
+ */
+export function writeX12TimeElement(form, value) {
+    try {
+        const layout = x12TimeElementLayoutOf(form);
+        if (layout === null || typeof value !== "string") {
+            return "";
+        }
+        return writeHalf(layout.start, READERS.time(value)) ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+/** One ISO 8601 string read as the kind its code's halves are, or null when it is not that kind. */
+function readHalf(entry, text) {
+    return typeof text === "string" ? READERS[entry.valueKind](text) : null;
+}
+/** Each kind's reader: the public validator proves the string, then Temporal reads its fields. */
+const READERS = {
+    date: (text) => isValidDate(text)
+        ? { date: Temporal.PlainDate.from(text), time: null, offset: null }
+        : null,
+    time: (text) => isValidTime(text)
+        ? { date: null, time: Temporal.PlainTime.from(text), offset: null }
+        : null,
+    dateTime: (text) => isValidDateTime(text)
+        ? wallClockHalf(Temporal.PlainDateTime.from(text), null)
+        : null,
+    offsetDateTime: readOffsetDateTime,
+};
+/**
+ * A date-time with an offset as its own wall clock and its offset. `toOffsetInstant` reads the
+ * string (an offset, `Z`, or a bracketed zone that agrees), and the wall clock is the instant
+ * seen at that offset, so no digit of the input is sliced.
+ */
+function readOffsetDateTime(text) {
+    const pair = toOffsetInstant(text);
+    if (pair === null) {
+        return null;
+    }
+    const offset = parseUtcOffsetNanoseconds(pair.offset);
+    // An offset with a non-zero seconds part fits no mask, and is not a time zone Temporal can
+    // show a clock in. A seconds part of zero is already gone: the pair's offset is `±HH:MM`.
+    if (offset === null || offset % NANOSECONDS_PER_MINUTE !== 0n) {
+        return null;
+    }
+    const wallClock = Temporal.Instant.from(pair.instant)
+        .toZonedDateTimeISO(pair.offset)
+        .toPlainDateTime();
+    return wallClockHalf(wallClock, offset);
+}
+function wallClockHalf(wallClock, offset) {
+    return {
+        date: wallClock.toPlainDate(),
+        time: wallClock.toPlainTime(),
+        offset,
+    };
+}
+/**
+ * GMT rule: a reversed period names no span of time. The ends compare by calendar date first
+ * and by time of day, to the nanosecond, when both have one.
+ */
+function endPrecedesStart(start, end) {
+    if (start.date === null || end.date === null) {
+        return false;
+    }
+    const byDate = Temporal.PlainDate.compare(end.date, start.date);
+    if (byDate !== 0 || start.time === null || end.time === null) {
+        return byDate < 0;
+    }
+    return Temporal.PlainTime.compare(end.time, start.time) < 0;
+}
+/**
+ * One half written in its mask, or null when there is no half, its year or its offset does not
+ * fit the mask, or a part has no value to write. A field the mask does not have (seconds, a
+ * fraction of a second, or what is below its tenths or hundredths) is left out, which is the
+ * truncation.
+ */
+function writeHalf(parts, half) {
+    if (half === null ||
+        !maskHoldsYear(half.date) ||
+        !maskHoldsOffset(parts, half.offset)) {
+        return null;
+    }
+    const text = {
+        ...dateText(half.date),
+        ...timeText(half.time),
+        ...offsetText(half.offset),
+    };
+    const written = parts.map((part) => text[part] ?? null);
+    return written.includes(null) ? null : written.join("");
+}
+/** Whether `CCYY` can hold the date's year: 0000–9999. */
+function maskHoldsYear(date) {
+    return (date === null ||
+        (date.year >= MIN_FOUR_DIGIT_YEAR && date.year <= MAX_FOUR_DIGIT_YEAR));
+}
+/** Whether the mask can hold the offset: whole minutes, or whole hours where the mask has `ZZZ`. */
+function maskHoldsOffset(parts, offset) {
+    if (offset === null) {
+        return true;
+    }
+    const step = parts.includes("ZZZ")
+        ? NANOSECONDS_PER_HOUR
+        : NANOSECONDS_PER_MINUTE;
+    return offset % step === 0n;
+}
+/** The digits of each date part of a mask, read from the date's Temporal fields. */
+function dateText(date) {
+    return date === null
+        ? {}
+        : {
+            CCYY: digits(date.year, 4),
+            MM: digits(date.month, 2),
+            DD: digits(date.day, 2),
+        };
+}
+/**
+ * The digits of each time part of a mask, read from the time's Temporal fields. The two decimal
+ * parts of X12 data element 337 are the whole tenths (`SD`) and the whole hundredths (`SDD`) of
+ * the second, counted from its milliseconds: 129 ms is 1 tenth and 12 hundredths. What is below
+ * the part is cut, never rounded, and the microseconds and nanoseconds are below both.
+ */
+function timeText(time) {
+    return time === null
+        ? {}
+        : {
+            HH: digits(time.hour, 2),
+            MI: digits(time.minute, 2),
+            SS: digits(time.second, 2),
+            SD: digits(Math.trunc(time.millisecond / MILLISECONDS_PER_DECIMAL_SECOND.SD), 1),
+            SDD: digits(Math.trunc(time.millisecond / MILLISECONDS_PER_DECIMAL_SECOND.SDD), 2),
+        };
+}
+/**
+ * The sign, hours and minutes of an offset, and the `ZZZ` spelling: the signed hour of UN/ECE
+ * Recommendation 7 ¶12, never `UTC` or `GMT` (**GMT rule**, one spelling). A zero offset is
+ * written `+`.
+ */
+function offsetText(offset) {
+    if (offset === null) {
+        return {};
+    }
+    const sign = offset < 0n ? "-" : "+";
+    const magnitude = offset < 0n ? -offset : offset;
+    const hours = digits(Number(magnitude / NANOSECONDS_PER_HOUR), 2);
+    const minutes = digits(Number((magnitude / NANOSECONDS_PER_MINUTE) % MINUTES_PER_HOUR), 2);
+    return {
+        ZS: sign,
+        ZH: hours,
+        ZM: minutes,
+        ZZZ: hours === null ? null : `${sign}${hours}`,
+    };
+}
+/** `value` zero-padded to `width` digits, or null when it is not a whole number that fits. */
+function digits(value, width) {
+    if (!Number.isInteger(value) || value < 0) {
+        return null;
+    }
+    const text = String(value);
+    return text.length > width ? null : text.padStart(width, "0");
+}

package/dist/internal/ediGrammar.d.ts

@@ -0,0 +1,158 @@
+import type { EdifactDtmFormat, EdifactDtmFormatClass, X12DateTimePeriodFormat, X12DateTimePeriodFormatClass, X12TimeCode, X12TimeElementForm } from "../types/edi.js";
+/**
+ * One field of a mask, named as the standards print it. Each part is one capture group. The
+ * standards write `MM` for both month and minute; `MI` is this file's name for the minute. `ZS`,
+ * `ZH` and `ZM` are the sign, hours and minutes of the `ZHHMM` offset of codes 205 and 208.
+ * Element 337 writes `D` for tenths of a second and `DD` for hundredths, and `DD` is already the
+ * day of the month: `SD` and `SDD` are this file's names for the two.
+ */
+export type EdiPart = "CCYY" | "MM" | "DD" | "HH" | "MI" | "SS" | "SD" | "SDD" | "ZS" | "ZH" | "ZM" | "ZZZ";
+/** The kind names `classifyEdifactDtmFormat` returns: one per UN/EDIFACT kind of value. */
+export type EdifactDtmKind = EdifactDtmFormatClass["kind"];
+/** The kind names `classifyX12DateTimePeriodFormat` returns: one per X12 kind of value. */
+export type X12DateTimePeriodKind = X12DateTimePeriodFormatClass["kind"];
+/** The kind of value a format code states, in either standard's own name for it. */
+export type EdiKind = EdifactDtmKind | X12DateTimePeriodKind;
+/**
+ * What one half of a value is: the kind of ISO 8601 string the reader returns for it and the
+ * writer takes. A single value has one half; a period or range has two of the same kind.
+ */
+export type EdiValueKind = "date" | "time" | "dateTime" | "offsetDateTime";
+/** A code's value: its kind, its parts in mask order, and for a period or range the end's parts too. */
+export interface EdiLayout<Kind extends EdiKind = EdiKind> {
+    readonly kind: Kind;
+    readonly start: readonly EdiPart[];
+    readonly end?: readonly EdiPart[];
+}
+/** The standard a format code belongs to. */
+export type EdiStandard = "edifact" | "x12";
+/** One format code of one standard, as the classifier, the reader and the writer all look it up. */
+export interface EdiCode {
+    /** The kind of value the code states, as its standard's classifier names it. */
+    readonly kind: EdiKind;
+    /** What each half of the value is. */
+    readonly valueKind: EdiValueKind;
+    /** The code's parts in mask order. */
+    readonly layout: EdiLayout;
+    /** The anchored grammar of the code's value. */
+    readonly grammar: RegExp;
+    /** What the standard transmits between the halves of a period or range. */
+    readonly rangeSeparator: string;
+}
+/**
+ * The 11 UNTDID 2379 codes GMT reads, in directory order: a date (`102`), a date and time
+ * (`203`, `204`), a date and time with a `ZHHMM` offset (`205`, `208`), a date and time with
+ * three zone characters (`303`, `304`), a time (`401`, `402`) and a period (`718`, `719`).
+ *
+ * Every other 2379 code returns the sentinel; the file header lists the ones cut and why.
+ */
+export declare const EDIFACT_DTM_FORMATS: readonly EdifactDtmFormat[];
+/**
+ * UNTDID 2379 code → the anchored, flagless grammar of its value. A period's halves are run
+ * together with nothing between them: every directory read gives a period "without hyphen" (the
+ * file header quotes each entry).
+ */
+export declare const EDIFACT_DTM_GRAMMAR: Readonly<Record<EdifactDtmFormat, RegExp>>;
+/**
+ * The 10 X12 1250 codes GMT reads: a date (`D8`, `DB`), a date and time (`DT`, `RTS`), a time
+ * (`TM`, `TS`), a range of dates (`RD8`, `RD`) and a range of date-times (`RDT`, `DTS`).
+ *
+ * The other 32 of the 42 codes return the sentinel; the file header lists the ones cut and why.
+ * `TS` is also a code of data element 623, with an unrelated meaning there.
+ */
+export declare const X12_DATE_TIME_PERIOD_FORMATS: readonly X12DateTimePeriodFormat[];
+/**
+ * X12 1250 code → the anchored, flagless grammar of its value. A range's halves are joined by
+ * exactly one hyphen, the one X12 transmits.
+ */
+export declare const X12_DATE_TIME_PERIOD_GRAMMAR: Readonly<Record<X12DateTimePeriodFormat, RegExp>>;
+/**
+ * X12 data element 337 (Time), the time element of `AT7`, `G62` and `DTM-03`: "Time expressed in
+ * 24-hour clock time as follows: HHMM, or HHMMSS, or HHMMSSD, or HHMMSSDD, where H = hours
+ * (00-23), M = minutes (00-59), S = integer seconds (00-59) and DD = decimal seconds; decimal
+ * seconds are expressed as follows: D = tenths (0-9) and DD = hundredths (00-99)", length 4 to 8
+ * (release 005010, https://www.stedi.com/edi/x12-005010/element/337).
+ *
+ * Mask → its parts, keyed by the element's own four masks in the order the definition gives
+ * them. Not a 1250 table: the element has no format qualifier, its four- and six-digit forms
+ * coincide with `TM` and `TS`, and no 1250 code holds decimal seconds. Typed from the public
+ * union, so a missing form fails typecheck.
+ */
+export declare const X12_TIME_ELEMENT_LAYOUT: {
+    readonly [Form in X12TimeElementForm]: EdiLayout<"time">;
+};
+/**
+ * The four forms of X12 data element 337, shortest first: the layout table's own keys, so the
+ * list cannot name a form the table lacks.
+ */
+export declare const X12_TIME_ELEMENT_FORMS: readonly X12TimeElementForm[];
+/**
+ * Element 337 form → the anchored, flagless grammar of its value. The four masks have four
+ * lengths (4, 6, 7 and 8 digits), so a value fits one form or none, and the reader needs no
+ * qualifier to tell them apart.
+ */
+export declare const X12_TIME_ELEMENT_GRAMMAR: Readonly<Record<X12TimeElementForm, RegExp>>;
+/**
+ * The milliseconds one unit of each decimal-seconds part is worth: a tenth of a second is 100
+ * and a hundredth is 10. The reader multiplies by it and the writer divides by it, so the two
+ * agree on what `D` and `DD` mean.
+ */
+export declare const MILLISECONDS_PER_DECIMAL_SECOND: Readonly<Record<"SD" | "SDD", number>>;
+/**
+ * Look a form of X12 data element 337 up by its mask, for the writer
+ * (`writeX12TimeElement`), whose caller names the form. The reader (`readX12Time`) is given no
+ * form: it tries the grammar of each form in the same table.
+ *
+ * - Matching is exact and by own key, so `"__proto__"`, `" HHMM"` and `"hhmm"` are not forms.
+ * - Null for a data element 1250 code (`TM`, `TS`): a qualifier is not a mask.
+ * - Null for a non-string argument.
+ *
+ * @param form the element's mask: `HHMM`, `HHMMSS`, `HHMMSSD` or `HHMMSSDD`
+ * @returns the form's parts in mask order, as a single time, or null
+ *
+ * @example x12TimeElementLayoutOf("HHMMSSDD") // { kind: "time", start: ["HH", "MI", "SS", "SDD"] }
+ * @example x12TimeElementLayoutOf("TS") // null (a 1250 code, not a mask)
+ * @example x12TimeElementLayoutOf("__proto__") // null
+ */
+export declare function x12TimeElementLayoutOf(form: unknown): EdiLayout<"time"> | null;
+/**
+ * The 56 X12 623 codes, release 008010, in dictionary order: `01`–`12` (UTC+1 … UTC+12), `13`–`24`
+ * (UTC−12 … UTC−1, descending), `25`–`29` (the half-hour offsets, added in release 006010), then
+ * the 27 letter codes. Release 005010 has the 51 codes other than `25`–`29`. Membership is by
+ * this list, never by shape. `TS`, `TT`, `CD` and `MD` are also codes of data element 1250, with
+ * unrelated meanings there.
+ */
+export declare const X12_TIME_CODES: readonly X12TimeCode[];
+/**
+ * Look a format code up in its standard's tables: the one lookup the classifier, the reader and
+ * the writer share.
+ *
+ * - Matching is exact and by own key, so `"__proto__"`, `" 102"` and `"d8"` are not codes.
+ * - Null for a code that is not read (`101`, `209`, `D6`, `UN`), like an unknown code.
+ * - Null for a standard that is not `"edifact"` or `"x12"`, and for a non-string argument.
+ *
+ * @param standard which element the code belongs to
+ * @param code the 2379 or 1250 format code
+ * @returns the code's kind, layout, grammar and range separator, or null
+ *
+ * @example ediCodeOf("edifact", "718") // { kind: "datePeriod", valueKind: "date", layout: { kind: "datePeriod", start: ["CCYY", "MM", "DD"], end: [...] }, grammar: /^…$/, rangeSeparator: "" }
+ * @example ediCodeOf("x12", "RD8") // { kind: "dateRange", valueKind: "date", layout: {...}, grammar: /^…$/, rangeSeparator: "-" }
+ * @example ediCodeOf("edifact", "101") // null (a two-digit year: not read)
+ * @example ediCodeOf("edifact", "D8") // null (an X12 code)
+ */
+export declare function ediCodeOf(standard: unknown, code: unknown): EdiCode | null;
+/**
+ * Look a format code up as a code of one kind: null unless the code is in its standard's tables
+ * under exactly that kind. Each public function names its own kind here, so a code of another
+ * kind (`203` given to a date function) is refused before any value is read.
+ *
+ * @param standard which element the code belongs to
+ * @param kind the kind of value the calling function reads or writes
+ * @param code the 2379 or 1250 format code
+ * @returns the code's entry, or null when the code is not one of that kind
+ *
+ * @example ediCodeOfKind("edifact", "date", "102") // { kind: "date", … }
+ * @example ediCodeOfKind("edifact", "date", "203") // null (a date-time code)
+ * @example ediCodeOfKind("x12", "dateRange", "RD8") // { kind: "dateRange", … }
+ */
+export declare function ediCodeOfKind(standard: EdiStandard, kind: EdiKind, code: unknown): EdiCode | null;