@northguild/gmt 1.18.0 → 1.19.0

package/dist/types/edi.d.ts

@@ -0,0 +1,407 @@
+/**
+ * The UN/EDIFACT data element 2379 (Date or time or period format code) value that states a
+ * calendar date. 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).
+ *
+ * - `102` `CCYYMMDD`: "Calendar date: C = Century ; Y = Year ; M = Month ; D = Day."
+ *
+ * Taken by `parseEdifactDate`, `formatEdifactDate` and `isValidEdifactDate`.
+ */
+export type EdifactDateFormat = "102";
+/**
+ * The UN/EDIFACT data element 2379 values that state a time of day with no date and no offset.
+ * 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).
+ *
+ * - `401` `HHMM`: "Time without seconds: H = Hour; m = Minute."
+ * - `402` `HHMMSS`: "Time with seconds: H = Hour; m = Minute; s = Seconds."
+ *
+ * Taken by `parseEdifactTime`, `formatEdifactTime` and `isValidEdifactTime`.
+ */
+export type EdifactTimeFormat = "401" | "402";
+/**
+ * The UN/EDIFACT data element 2379 values that state a date and a time with no offset: a local
+ * time at a place the value does not name. 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).
+ *
+ * - `203` `CCYYMMDDHHMM`: "Calendar date including time with minutes".
+ * - `204` `CCYYMMDDHHMMSS`: "Calendar date including time with seconds".
+ *
+ * Taken by `parseEdifactDateTime`, `formatEdifactDateTime` and `isValidEdifactDateTime`.
+ */
+export type EdifactDateTimeFormat = "203" | "204";
+/**
+ * The UN/EDIFACT data element 2379 values that state a date and a time with an offset from UTC.
+ * 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).
+ *
+ * - `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",
+ *   where "Z = leading plus/minus sign, HHMM = difference to UTC in Hours and Minutes". In
+ *   directories D.12A and later.
+ * - `303` `CCYYMMDDHHMMZZZ`: "See 203 plus Z=Time zone."
+ * - `304` `CCYYMMDDHHMMSSZZZ`: "See 204 plus Z=Time zone."
+ *
+ * The three `ZZZ` characters of `303` and `304` are read as an offset only: a signed hour
+ * (`+02`, `-05`) or the literals `UTC` and `GMT`. Taken by `parseEdifactOffsetDateTime`,
+ * `formatEdifactOffsetDateTime` and `isValidEdifactOffsetDateTime`.
+ */
+export type EdifactOffsetDateTimeFormat = "205" | "208" | "303" | "304";
+/**
+ * The UN/EDIFACT data element 2379 value that states a period between two calendar dates. 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).
+ *
+ * - `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."
+ *
+ * Taken by `parseEdifactDatePeriod`, `formatEdifactDatePeriod` and `isValidEdifactDatePeriod`.
+ */
+export type EdifactDatePeriodFormat = "718";
+/**
+ * The UN/EDIFACT data element 2379 value that states a period between two local date-times.
+ * 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).
+ *
+ * - `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."
+ *
+ * Taken by `parseEdifactDateTimePeriod`, `formatEdifactDateTimePeriod` and
+ * `isValidEdifactDateTimePeriod`.
+ */
+export type EdifactDateTimePeriodFormat = "719";
+/**
+ * The UN/EDIFACT data element 2379 (Date or time or period format code) values GMT reads and
+ * writes: 11 codes, each in the union of the one kind of value it states. Twelve directories
+ * were read: UNECE's own
+ * [D.21B](http://web.archive.org/web/20240303123657/https://service.unece.org/trade/untdid/d21b/tred/tred2379.htm)
+ * and
+ * [D.22B](http://web.archive.org/web/20260311101223/https://service.unece.org/trade/untdid/d22b/tred/tred2379.htm)
+ * pages, archived, and mirrors of D.93A, D.96A, D.01B, D.01C, D.03A, D.03B, D.04B, D.11B, D.12A
+ * and D.13B. No mask of a code GMT reads changed across them.
+ *
+ * Every other 2379 code returns the sentinel from every function. Among them:
+ *
+ * - The codes with a two-digit year, `101`, `201`, `202`, `206`, `207`, `301`, `302`, `713` and
+ *   `717`: no standard says which century `YY` belongs to. Read one with `parseDateWithPattern`
+ *   or `parseDateTimeWithPattern`, a `yy` pattern and its `yearWindow` option.
+ * - `209` and `404` (a time with an offset and no date) and `406` (an offset alone): none names
+ *   a date, a time, a date-time or an instant.
+ * - The day-first and month-first forms `2`–`5`, `10` (`CCYYMMDDTHHMM`), the week date `103`,
+ *   the ordinal date `105`, the time period `210`, `307` (milliseconds), the zoned period `308`,
+ *   the time spans `501`–`503`, `711`, the partial values (a century, a year, a month, a week or
+ *   a day of month alone), the weekday period `720` and the quantities (`801` and up).
+ *
+ * Narrow a candidate with `isValidEdifactDtmFormat`, and name its kind with
+ * `classifyEdifactDtmFormat`.
+ */
+export type EdifactDtmFormat = EdifactDateFormat | EdifactTimeFormat | EdifactDateTimeFormat | EdifactOffsetDateTimeFormat | EdifactDatePeriodFormat | EdifactDateTimePeriodFormat;
+/**
+ * A UN/EDIFACT data element 2379 format code with the kind of value it states: the result of
+ * `classifyEdifactDtmFormat`.
+ *
+ * The two members are tied together: testing `kind` narrows `format` to that kind's own union,
+ * so a code that arrived as a plain string can be passed to the kind's parser, formatter and
+ * validator with no cast.
+ */
+export type EdifactDtmFormatClass = {
+    /** The kind of value the code states: a calendar date, read by `parseEdifactDate`. */
+    kind: "date";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: EdifactDateFormat;
+} | {
+    /** The kind of value the code states: a time of day, read by `parseEdifactTime`. */
+    kind: "time";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: EdifactTimeFormat;
+} | {
+    /** The kind of value the code states: a local date and time, read by `parseEdifactDateTime`. */
+    kind: "dateTime";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: EdifactDateTimeFormat;
+} | {
+    /** The kind of value the code states: a date and time with an offset from UTC, read by `parseEdifactOffsetDateTime`. */
+    kind: "offsetDateTime";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: EdifactOffsetDateTimeFormat;
+} | {
+    /** The kind of value the code states: a period between two dates, read by `parseEdifactDatePeriod`. */
+    kind: "datePeriod";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: EdifactDatePeriodFormat;
+} | {
+    /** The kind of value the code states: a period between two local date-times, read by `parseEdifactDateTimePeriod`. */
+    kind: "dateTimePeriod";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: EdifactDateTimePeriodFormat;
+};
+/**
+ * The X12 data element 1250 (Date Time Period Format Qualifier) values that state a calendar
+ * date. Release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/1250); the X12
+ * text itself was not reached.
+ *
+ * - `D8` `CCYYMMDD`: "Date Expressed in Format CCYYMMDD".
+ * - `DB` `MMDDCCYY`: "Date Expressed in Format MMDDCCYY".
+ *
+ * Taken by `parseX12Date`, `formatX12Date` and `isValidX12Date`.
+ */
+export type X12DateFormat = "D8" | "DB";
+/**
+ * The X12 data element 1250 values that state a time of day. Release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/1250); the X12
+ * text itself was not reached.
+ *
+ * - `TM` `HHMM`: "Time Expressed in Format HHMM".
+ * - `TS` `HHMMSS`: "Time Expressed in Format HHMMSS".
+ *
+ * Taken by `formatX12Time`, and by `parseX12Time` and `isValidX12Time` as their optional
+ * qualifier. Both are also forms of data element 337 (Time), which `parseX12Time` reads when no
+ * qualifier is given and `formatX12TimeElement` writes by the element's own mask
+ * (`X12TimeElementForm`). `TS` is a code of data element 623 too (`X12TimeCode`), where it means
+ * Atlantic Standard Time.
+ */
+export type X12TimeFormat = "TM" | "TS";
+/**
+ * The four forms of X12 data element 337 (Time), each named by the element's own mask. Release
+ * 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/337); the X12
+ * text itself was not reached. The dictionary's definition: "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)".
+ *
+ * - `HHMM`: hours and minutes, 4 digits.
+ * - `HHMMSS`: hours, minutes and seconds, 6 digits.
+ * - `HHMMSSD`: with tenths of a second, 7 digits.
+ * - `HHMMSSDD`: with hundredths of a second, 8 digits.
+ *
+ * These are the element's own masks, not data element 1250 codes. Element 337 has no format
+ * qualifier, so no code names its form: the caller names it by the mask. `TM` and `TS`
+ * (`X12TimeFormat`) are the 1250 codes for the first two masks, and no 1250 code holds decimal
+ * seconds.
+ *
+ * Taken by `formatX12TimeElement`. `parseX12Time` reads all four forms when it is given no
+ * qualifier.
+ */
+export type X12TimeElementForm = "HHMM" | "HHMMSS" | "HHMMSSD" | "HHMMSSDD";
+/**
+ * The X12 data element 1250 values that state a date and a time with no offset: a local time at
+ * a place the value does not name. Release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/1250); the X12
+ * text itself was not reached.
+ *
+ * - `DT` `CCYYMMDDHHMM`: "Date and Time Expressed in Format CCYYMMDDHHMM".
+ * - `RTS` `CCYYMMDDHHMMSS`: "Date and Time Expressed in Format CCYYMMDDHHMMSS". One date-time,
+ *   despite the `R`.
+ *
+ * Taken by `parseX12DateTime`, `formatX12DateTime` and `isValidX12DateTime`.
+ */
+export type X12DateTimeFormat = "DT" | "RTS";
+/**
+ * The X12 data element 1250 values that state a range between two calendar dates, transmitted
+ * with its hyphen. Release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/1250); the X12
+ * text itself was not reached.
+ *
+ * - `RD8` `CCYYMMDD-CCYYMMDD`: "Range of Dates Expressed in Format CCYYMMDD-CCYYMMDD".
+ * - `RD` `MMDDCCYY-MMDDCCYY`: "Range of Dates Expressed in Format MMDDCCYY-MMDDCCYY".
+ *
+ * Taken by `parseX12DateRange`, `formatX12DateRange` and `isValidX12DateRange`.
+ */
+export type X12DateRangeFormat = "RD8" | "RD";
+/**
+ * The X12 data element 1250 values that state a range between two local date-times,
+ * transmitted with its hyphen. Release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/1250); the X12
+ * text itself was not reached.
+ *
+ * - `RDT` `CCYYMMDDHHMM-CCYYMMDDHHMM`: "Range of Date and Time, Expressed in Format
+ *   CCYYMMDDHHMM-CCYYMMDDHHMM".
+ * - `DTS` `CCYYMMDDHHMMSS-CCYYMMDDHHMMSS`: "Range of Date and Time Expressed in Format
+ *   CCYYMMDDHHMMSS-CCYYMMDDHHMMSS". A range, despite having no `R`.
+ *
+ * Taken by `parseX12DateTimeRange`, `formatX12DateTimeRange` and `isValidX12DateTimeRange`.
+ */
+export type X12DateTimeRangeFormat = "RDT" | "DTS";
+/**
+ * The X12 data element 1250 (Date Time Period Format Qualifier) values GMT reads and writes: 10
+ * codes, each in the union of the one kind of value it states. Release 005010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-005010/element/1250); the X12
+ * text itself was not reached. The 42-code list is the same in release 008010.
+ *
+ * The other 32 codes of the element return the sentinel from every function. Among them:
+ *
+ * - The codes with a two-digit year, `D6`, `TT`, `TR`, `RD6` and `TU`: X12 does not say which
+ *   century `YY` belongs to. Read one with `parseDateWithPattern` or `parseDateTimeWithPattern`,
+ *   a `yy` pattern and its `yearWindow` option.
+ * - `TC` and `EH` (a day of the year with no whole year), `DDT` and `DTD` (a range with a date
+ *   on one side and a date-time on the other), `RTM` (a range of times with no date) and `UN`
+ *   (Unstructured).
+ * - `CC`, `CD`, `CM`, `CQ`, `CY`, `DA`, `DD`, `KA`, `MCY`, `MD`, `MM`, `RD2`, `RD4`, `RD5`,
+ *   `RDM`, `RMD`, `RMY`, `TQ`, `YM`, `YMM` and `YY`.
+ *
+ * Narrow a candidate with `isValidX12DateTimePeriodFormat`, and name its kind with
+ * `classifyX12DateTimePeriodFormat`.
+ */
+export type X12DateTimePeriodFormat = X12DateFormat | X12TimeFormat | X12DateTimeFormat | X12DateRangeFormat | X12DateTimeRangeFormat;
+/**
+ * An X12 data element 1250 format qualifier with the kind of value it states: the result of
+ * `classifyX12DateTimePeriodFormat`.
+ *
+ * The two members are tied together: testing `kind` narrows `format` to that kind's own union,
+ * so a code that arrived as a plain string can be passed to the kind's parser, formatter and
+ * validator with no cast.
+ */
+export type X12DateTimePeriodFormatClass = {
+    /** The kind of value the code states: a calendar date, read by `parseX12Date`. */
+    kind: "date";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: X12DateFormat;
+} | {
+    /** The kind of value the code states: a time of day, read by `parseX12Time(value, format)`. */
+    kind: "time";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: X12TimeFormat;
+} | {
+    /** The kind of value the code states: a local date and time, read by `parseX12DateTime`. */
+    kind: "dateTime";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: X12DateTimeFormat;
+} | {
+    /** The kind of value the code states: a range between two dates, read by `parseX12DateRange`. */
+    kind: "dateRange";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: X12DateRangeFormat;
+} | {
+    /** The kind of value the code states: a range between two local date-times, read by `parseX12DateTimeRange`. */
+    kind: "dateTimeRange";
+    /** The code itself, narrowed to the codes of that kind, so it fits the kind's functions. */
+    format: X12DateTimeRangeFormat;
+};
+/**
+ * The 56 X12 data element 623 (Time Code) values, release 008010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-008010/element/623); the X12
+ * text itself was not reached.
+ *
+ * [Release 005010](https://www.stedi.com/edi/x12-005010/element/623) has 51 of them: `25`–`29`
+ * were added in release 006010 and are not valid in an 004010 or 005010 interchange. The type
+ * names no release, so it is the superset.
+ *
+ * - `01`–`12`: UTC+1 through UTC+12 ("Equivalent to ISO P01" … `P12`).
+ * - `13`–`24`: UTC−12 through UTC−1, in **descending** order (`M12` … `M01`): `13` is UTC−12 and
+ *   `24` is UTC−1.
+ * - `25`–`29`: the half-hour offsets `M2:30`, `M3:30`, `P5:30`, `P9:30`, `P10:30`.
+ * - `UT` ("Universal Time Coordinate") and `GM` ("Greenwich Mean Time"): UTC.
+ * - `AD`/`AS`/`AT` Alaska, `CD`/`CS`/`CT` Central, `ED`/`ES`/`ET` Eastern, `HD`/`HS`/`HT`
+ *   Hawaii-Aleutian, `MD`/`MS`/`MT` Mountain, `ND`/`NS`/`NT` Newfoundland, `PD`/`PS`/`PT`
+ *   Pacific, `TD`/`TS`/`TT` Atlantic: a named zone, daylight (`D`), standard (`S`) or unstated
+ *   (`T`). X12 states no offset for these.
+ * - `LT`: local time of the event, whose place is elsewhere in the message.
+ *
+ * `TS`, `TT`, `CD` and `MD` are also codes of data element 1250, where they mean something
+ * unrelated: `TS` there is the format `HHMMSS` (`X12TimeFormat`). Narrow a candidate with
+ * `isValidX12TimeCode`; `X12OffsetTimeCode` and `X12ZoneTimeCode` split the list in two, and
+ * `classifyX12TimeCode` says which of the two a code belongs to.
+ */
+export type X12TimeCode = "01" | "02" | "03" | "04" | "05" | "06" | "07" | "08" | "09" | "10" | "11" | "12" | "13" | "14" | "15" | "16" | "17" | "18" | "19" | "20" | "21" | "22" | "23" | "24" | "25" | "26" | "27" | "28" | "29" | "AD" | "AS" | "AT" | "CD" | "CS" | "CT" | "ED" | "ES" | "ET" | "GM" | "HD" | "HS" | "HT" | "LT" | "MD" | "MS" | "MT" | "ND" | "NS" | "NT" | "PD" | "PS" | "PT" | "TD" | "TS" | "TT" | "UT";
+/**
+ * The 31 X12 data element 623 time codes that state an offset from UTC, the codes
+ * `x12TimeCodeOffset` reads. Release 008010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-008010/element/623); the X12
+ * text itself was not reached.
+ *
+ * - `01`–`12`: UTC+1 through UTC+12 ("Equivalent to ISO P01" … `P12`).
+ * - `13`–`24`: UTC−12 through UTC−1, in **descending** order (`M12` … `M01`): `13` is UTC−12 and
+ *   `24` is UTC−1.
+ * - `25`–`29`: the half-hour offsets `M2:30`, `M3:30`, `P5:30`, `P9:30`, `P10:30`. Added in
+ *   release 006010.
+ * - `UT` ("Universal Time Coordinate") and `GM` ("Greenwich Mean Time"): UTC.
+ */
+export type X12OffsetTimeCode = "01" | "02" | "03" | "04" | "05" | "06" | "07" | "08" | "09" | "10" | "11" | "12" | "13" | "14" | "15" | "16" | "17" | "18" | "19" | "20" | "21" | "22" | "23" | "24" | "25" | "26" | "27" | "28" | "29" | "GM" | "UT";
+/**
+ * The 25 X12 data element 623 time codes that name a zone and state no offset, the codes
+ * `x12TimeCodeZone` reads. Release 008010, read from
+ * [Stedi's X12-licensed dictionary](https://www.stedi.com/edi/x12-008010/element/623); the X12
+ * text itself was not reached.
+ *
+ * - `AD`/`AS`/`AT` Alaska, `CD`/`CS`/`CT` Central, `ED`/`ES`/`ET` Eastern, `HD`/`HS`/`HT`
+ *   Hawaii-Aleutian, `MD`/`MS`/`MT` Mountain, `ND`/`NS`/`NT` Newfoundland, `PD`/`PS`/`PT`
+ *   Pacific, `TD`/`TS`/`TT` Atlantic: daylight (`D`), standard (`S`) or unstated (`T`).
+ * - `LT`: local time of the event, whose place is elsewhere in the message.
+ */
+export type X12ZoneTimeCode = "AD" | "AS" | "AT" | "CD" | "CS" | "CT" | "ED" | "ES" | "ET" | "HD" | "HS" | "HT" | "LT" | "MD" | "MS" | "MT" | "ND" | "NS" | "NT" | "PD" | "PS" | "PT" | "TD" | "TS" | "TT";
+/**
+ * The zone an X12 data element 623 time code names: the result of `x12TimeCodeZone`. X12 states
+ * no offset for a named code, so the result carries none.
+ */
+export interface X12NamedZone {
+    /**
+     * X12's own name for the zone, as its definition writes it: `Alaska`, `Central`, `Eastern`,
+     * `Hawaii-Aleutian`, `Mountain`, `Newfoundland`, `Pacific` or `Atlantic`, and `Local` for `LT`.
+     * It is a name, not an IANA identifier and not an offset: the caller maps it to a zone.
+     */
+    zone: string;
+    /**
+     * Whether the code says daylight time. `true` for a `D` code (`ED`), `false` for an `S` code
+     * (`ES`), and `null` for a code that says neither (`ET`, `LT`), where the date decides.
+     */
+    daylight: boolean | null;
+}
+/**
+ * An X12 data element 623 time code with what it states: the result of `classifyX12TimeCode`.
+ *
+ * The two members are tied together: testing `kind` narrows `timeCode` to the codes of one
+ * reader, so a code that arrived as a plain string can be passed to `x12TimeCodeOffset` or
+ * `x12TimeCodeZone` with no cast.
+ */
+export type X12TimeCodeClass = {
+    /** The code states an offset from UTC: read it with `x12TimeCodeOffset`. */
+    kind: "offset";
+    /** The code itself, narrowed to the 31 codes that state an offset. */
+    timeCode: X12OffsetTimeCode;
+} | {
+    /** The code names a zone and states no offset: read it with `x12TimeCodeZone`. */
+    kind: "zone";
+    /** The code itself, narrowed to the 25 codes that name a zone. */
+    timeCode: X12ZoneTimeCode;
+};
+/**
+ * A period between two calendar dates, as a UN/EDIFACT period (`718`) or an X12 range (`RD8`,
+ * `RD`) states it: the result of `parseEdifactDatePeriod` and `parseX12DateRange`.
+ *
+ * Neither standard says whether the end date is inside the period: that is the message's to
+ * define, so the two dates are returned as transmitted. The pair can be passed to the plain
+ * interval functions as `(start, end)`, for example
+ * `intervalLengthDate(period.start, period.end, "days")`; those functions leave `end` outside
+ * the interval.
+ */
+export interface EdiDatePeriod {
+    /** The date the period starts on, `YYYY-MM-DD`. */
+    start: string;
+    /** The date the period ends on, `YYYY-MM-DD`. It is never before `start`, and may equal it. */
+    end: string;
+}
+/**
+ * A period between two local date-times, as a UN/EDIFACT period (`719`) or an X12 range (`RDT`,
+ * `DTS`) states it: the result of `parseEdifactDateTimePeriod` and `parseX12DateTimeRange`.
+ *
+ * Both ends are wall clocks at a place the value does not name: no code that states a period
+ * carries an offset, so neither end is an instant. Neither standard says whether the end is
+ * inside the period. The pair can be passed to the plain interval functions as `(start, end)`,
+ * for example `intervalLengthDateTime(period.start, period.end, "hours")`; those functions leave
+ * `end` outside the interval.
+ */
+export interface EdiDateTimePeriod {
+    /** The local date-time the period starts at, `YYYY-MM-DDTHH:MM:SS`. Seconds are always written. */
+    start: string;
+    /**
+     * The local date-time the period ends at, `YYYY-MM-DDTHH:MM:SS`. Seconds are always written. It
+     * is never before `start`, and may equal it.
+     */
+    end: string;
+}

package/dist/types/epcis.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The two time fields every GS1 EPCIS 2.0 (ISO/IEC 19987) event must carry.
+ *
+ * The EPCIS JSON schema lists both under `required`. `eventTime` says when the event happened;
+ * `eventTimeZoneOffset` says what the local clock was offset by where it happened. Neither
+ * derives from the other, so a system that keeps only `eventTime` cannot show the event in local
+ * time again. Read a pair with `parseEpcisEvent`, write one with `formatEpcisEvent` and check one
+ * with `isValidEpcisEvent`.
+ */
+export interface EpcisEventTime {
+    /**
+     * When the event happened, in the `DateTimeStamp` grammar of the EPCIS XSD, the XML binding
+     * (`epcisEventTime`): `YYYY-MM-DDTHH:MM:SS`, an optional fraction, then `Z` or a `±HH:MM`
+     * offset. It fixes the instant and nothing else: an offset written here is not the event's
+     * local offset, and it does not have to equal `eventTimeZoneOffset` (EPCIS 2.0 §7.4.1.1).
+     */
+    eventTime: string;
+    /**
+     * The UTC offset in force where the event happened, in the pattern the EPCIS JSON schema gives
+     * (`epcisTimeZoneOffset`), which is the rule of EPCIS 2.0 §7.4.1: `±HH:MM` from `-14:00` to
+     * `+14:00`, never `Z`. It sets the local clock the event is shown on and does not move the
+     * instant. It cannot be worked out from `eventTime`.
+     */
+    eventTimeZoneOffset: string;
+}

package/dist/types/exact-duration-unit.d.ts

@@ -0,0 +1,8 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * The plural name of a duration field that has an exact length: `"days"`, or a time field from
+ * `"hours"` down to `"nanoseconds"`. A day is 24 hours when nothing anchors it, as
+ * TC39 Temporal's `Duration.prototype.total` reads one without `relativeTo`. Years, months and
+ * weeks are left out: Temporal gives them no length without a date to measure from.
+ */
+export type ExactDurationUnit = keyof Pick<Temporal.DurationLike, "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds">;

package/dist/types/free-time-options.d.ts

@@ -23,9 +23,10 @@ export type FreeTimeOptions = {
      */
     basis: FreeTimeBasis;
     /**
-     * The time zone of the terminal, depot or yard whose local midnight ends a day: an IANA name or a
-     * UTC offset. GMT does not resolve a port or terminal code to a zone. A UTC offset such as
-     * `"+02:00"` observes no DST.
+     * The time zone of the terminal, depot or yard whose local midnight ends a day, an IANA name or
+     * UTC offset: a time zone identifier (`+05:30`, `+0530`, `-08`) or a stored offset
+     * (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns). GMT does not resolve a port or terminal code
+     * to a zone. A UTC offset such as `"+02:00"` observes no DST.
      */
     timeZone: string;
     /**

package/dist/types/index.d.ts

@@ -11,6 +11,10 @@ export * from "./datetime-format-options.js";
 export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
+export * from "./duty.js";
+export * from "./edi.js";
+export * from "./epcis.js";
+export * from "./exact-duration-unit.js";
 export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
 export * from "./free-time-options.js";
@@ -31,6 +35,7 @@ export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
 export * from "./transport-timestamps.js";
+export * from "./two-digit-year.js";
 export * from "./unix-now-unit.js";
 export * from "./utc-now-unit.js";
 export * from "./zone-bucket-unit.js";

package/dist/types/index.js

@@ -11,6 +11,10 @@ export * from "./datetime-format-options.js";
 export * from "./disambiguation.js";
 export * from "./duration-relative-to.js";
 export * from "./duration-string-options.js";
+export * from "./duty.js";
+export * from "./edi.js";
+export * from "./epcis.js";
+export * from "./exact-duration-unit.js";
 export * from "./fiscal-calendar.js";
 export * from "./fractional-digit.js";
 export * from "./free-time-options.js";
@@ -31,6 +35,7 @@ export * from "./time-cycle-field.js";
 export * from "./time-duration-unit.js";
 export * from "./time-unit.js";
 export * from "./transport-timestamps.js";
+export * from "./two-digit-year.js";
 export * from "./unix-now-unit.js";
 export * from "./utc-now-unit.js";
 export * from "./zone-bucket-unit.js";

package/dist/types/operating-schedule.d.ts

@@ -44,8 +44,9 @@ export type OperatingOverride = {
  */
 export type OperatingSchedule = {
     /**
-     * The time zone the windows are read in: an IANA name or a UTC offset. A UTC offset such as
-     * `"+02:00"` observes no DST.
+     * The time zone the windows are read in, an IANA name or UTC offset: a time zone identifier
+     * (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset`
+     * returns). A UTC offset such as `"+02:00"` observes no DST.
      */
     timeZone: string;
     /**

package/dist/types/two-digit-year.d.ts

@@ -0,0 +1,23 @@
+/**
+ * How a two-digit year (`yy` in a pattern, `YYMMDD` in an EDI value) gets its century.
+ *
+ * No standard says which century a two-digit year belongs to, so GMT holds no cut-off of its own:
+ * the caller names the hundred-year window. A two-digit year is a legacy form; a four-digit year
+ * is the one to ask a data source for.
+ */
+export interface TwoDigitYearOptions {
+    /**
+     * The hundred-year window a two-digit year falls in. A number is the first year of a fixed
+     * window, an integer from 0 to 9900: `2000` reads `00`–`99` as 2000–2099; `1950` reads `50`–`99`
+     * as 1950–1999 and `00`–`49` as 2000–2049. A fixed window gives the same answer in any year,
+     * so it is the form for stored data, archives and anything re-processed later. `"rolling"` is
+     * the hundred years around today: from 50 years before the current UTC calendar year to 49
+     * years after it (in 2026, 1976–2075). It is the form for live messages and never needs
+     * maintenance, but it gives a different answer for the same stored value as years pass. Any
+     * other value returns the function's sentinel.
+     *
+     * @defaultValue None. A value with a two-digit year returns the sentinel: no standard says which
+     * century it belongs to, so the caller states it.
+     */
+    yearWindow?: "rolling" | number;
+}

package/dist/types/zone-bucket-unit.d.ts

@@ -8,4 +8,4 @@
  *
  * Narrow a candidate unit with `isValidZoneBucketUnit`.
  */
-export type ZoneBucketUnit = "hour" | "day" | "week" | "month";
+export type ZoneBucketUnit = "month" | "week" | "day" | "hour";

package/dist/unix/calculate/addUnix.d.ts

@@ -7,6 +7,12 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
  * - Returns null for invalid input.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
@@ -19,6 +25,7 @@ import type { UnixUnit } from "../validate/isValidUnixUnit.js";
  * @example addUnix(1.5, { days: 1 }) // null (not an integer epoch)
  * @example addUnix("1706659200000", { days: 1 }) // 1706745600000 (digit string)
  * @example addUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
+ * @example addUnix(45870000, { days: 1 }, { timeZone: "-00:44:30" }) // 132270000 (a stored offset with seconds)
  */
 export declare function addUnix(value: number | string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
     /**
@@ -29,8 +36,10 @@ export declare function addUnix(value: number | string, units: Partial<Record<Da
      */
     epochUnit?: UnixUnit;
     /**
-     * The time zone the calendar arithmetic runs in: an IANA name, a UTC offset, or `"local"` for
-     * the system time zone. An unknown zone returns `null`.
+     * The time zone the calendar arithmetic runs in: an IANA name, a UTC offset (a time zone
+     * identifier such as `+05:30`, `+0530` or `-08`, or a stored offset `±HH:MM[:SS]`, what
+     * `getTimeZoneOffset` returns), or `"local"` for the system time zone. An unknown zone returns
+     * `null`.
      *
      * @defaultValue `"UTC"`
      */

package/dist/unix/calculate/addUnix.js

@@ -1,5 +1,4 @@
-import { addToZoned, isValidAmount, resolveOverflow } from "../../internal/index.js";
-import { normalizeTimeZone } from "../../internal/normalizeTimeZone.js";
+import { addToZoned, frameInstant, frameZoned, normalizeZoneFrame, readDurationUnits, resolveOverflow, } from "../../internal/index.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "../../internal/unixEpochValue.js";
 import { isValidDateTimeDurationUnit } from "../../plain/validate/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
@@ -10,6 +9,12 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * - Validates duration units and values.
  * - `value` is a safe integer or a digit string (`"1706659200000"`); anything else returns null.
  * - Returns null for invalid input.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `null`. An offset to the minute has no
+ *   such limit.
  *
  * @param value Unix epoch: a safe integer, or a string of optionally negative ASCII digits
  * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to add
@@ -22,6 +27,7 @@ import { isOptionsArgument } from "../../internal/isObject.js";
  * @example addUnix(1.5, { days: 1 }) // null (not an integer epoch)
  * @example addUnix("1706659200000", { days: 1 }) // 1706745600000 (digit string)
  * @example addUnix(1706659200000, { days: 1 }, { timeZone: "Mars/Olympus" }) // null (unknown zone)
+ * @example addUnix(45870000, { days: 1 }, { timeZone: "-00:44:30" }) // 132270000 (a stored offset with seconds)
  */
 export function addUnix(value, units, options) {
     try {
@@ -29,15 +35,12 @@ export function addUnix(value, units, options) {
             return null;
         }
         const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-        const timeZone = normalizeTimeZone(options?.timeZone);
+        const frame = normalizeZoneFrame(options?.timeZone);
         const overflow = resolveOverflow(options?.overflow);
-        if (!timeZone || epochUnit === null)
+        if (frame === null || epochUnit === null)
             return null;
-        const validUnits = typeof units === "object" &&
-            units !== null &&
-            Object.keys(units).every(isValidDateTimeDurationUnit);
-        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
-        if (!validUnits || !validAmounts) {
+        const amounts = readDurationUnits(units, isValidDateTimeDurationUnit);
+        if (amounts === null) {
             return null;
         }
         const instant = unixEpochToInstant(value, epochUnit);
@@ -45,8 +48,8 @@ export function addUnix(value, units, options) {
             return null;
         }
         try {
-            const zdt = instant.toZonedDateTimeISO(timeZone);
-            return toUnixEpoch(addToZoned(zdt, units, { overflow }), epochUnit);
+            const zdt = frameZoned(instant, frame);
+            return toUnixEpoch(frameInstant(addToZoned(zdt, amounts, { overflow }), frame), epochUnit);
         }
         catch {
             return null;