@northguild/gmt 1.18.0 → 1.19.0

package/dist/intermodal/validate/isValidEpcisEvent.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Validate whether a value carries the two required time fields of a GS1 EPCIS 2.0 event, each in
+ * the grammar GS1 publishes for it.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility. True exactly when
+ * `isValidEpcisEventTime` is true of `eventTime` and `isValidEpcisTimeZoneOffset` is true of
+ * `eventTimeZoneOffset`: this validator calls the two, and no check needs both fields at once.
+ * `parseEpcisEvent` returns a result for exactly the same values.
+ *
+ * - `eventTime` must match `epcisEventTime` (the `DateTimeStamp` pattern of the EPCIS XSD, the
+ *   XML binding; the JSON schema says only `format: date-time`) and name a real instant: `YYYY-MM-DDTHH:MM:SS`, an optional fraction of up to nine digits, then
+ *   `Z` or a `±HH:MM` offset. A day the month does not have (`2024-02-30`) is false, although the
+ *   pattern matches it.
+ * - `eventTimeZoneOffset` must match `epcisTimeZoneOffset` (the pattern the EPCIS JSON schema
+ *   gives; the XSD types the field as a bare `xsd:string`): `±HH:MM` from `-14:00` to `+14:00`,
+ *   the rule of EPCIS Standard Release 2.0 §7.4.1 (https://ref.gs1.org/standards/epcis/). A
+ *   missing offset, `Z`, `+0200` and `+02` are false.
+ * - The two fields are independent: an `eventTime` written with one offset and an
+ *   `eventTimeZoneOffset` that is another is valid. EPCIS 2.0 §7.4.1.1 (non-normative): "there
+ *   is no requirement that the time zone specifier in the XML representation of eventTime be the
+ *   local time zone offset where the event was captured".
+ * - **GMT rule:** a fraction longer than nine digits is false. The XSD allows any length; an
+ *   instant holds nanoseconds, and `parseEpcisEvent` does not drop digits.
+ * - Only the two fields are checked. `recordTime` and every other member are ignored, so this
+ *   does not validate a whole event against the EPCIS schema.
+ * - Returns false for a value that is not an object.
+ *
+ * @param event candidate EPCIS event, or any object with `eventTime` and `eventTimeZoneOffset`
+ * @returns boolean indicating whether `parseEpcisEvent` reads the event, or false on invalid input
+ *
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-05:00" }) // true
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T10:00:00+02:00", eventTimeZoneOffset: "-05:00" }) // true (the two offsets need not agree)
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00.123456789Z", eventTimeZoneOffset: "+14:00" }) // true
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00Z" }) // false (eventTimeZoneOffset is required)
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "Z" }) // false (a designator, not an offset)
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "+0200" }) // false (no colon)
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30Z", eventTimeZoneOffset: "-05:00" }) // false (seconds are required)
+ * @example isValidEpcisEvent({ eventTime: "2024-02-30T14:30:00Z", eventTimeZoneOffset: "-05:00" }) // false (30 February)
+ * @example isValidEpcisEvent("2024-06-15T14:30:00Z") // false (not an event)
+ */
+export declare function isValidEpcisEvent(event: unknown): boolean;

package/dist/intermodal/validate/isValidEpcisEvent.js

@@ -0,0 +1,58 @@
+import { isObject } from "../../internal/index.js";
+import { isValidEpcisEventTime } from "./isValidEpcisEventTime.js";
+import { isValidEpcisTimeZoneOffset } from "./isValidEpcisTimeZoneOffset.js";
+/**
+ * Validate whether a value carries the two required time fields of a GS1 EPCIS 2.0 event, each in
+ * the grammar GS1 publishes for it.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility. True exactly when
+ * `isValidEpcisEventTime` is true of `eventTime` and `isValidEpcisTimeZoneOffset` is true of
+ * `eventTimeZoneOffset`: this validator calls the two, and no check needs both fields at once.
+ * `parseEpcisEvent` returns a result for exactly the same values.
+ *
+ * - `eventTime` must match `epcisEventTime` (the `DateTimeStamp` pattern of the EPCIS XSD, the
+ *   XML binding; the JSON schema says only `format: date-time`) and name a real instant: `YYYY-MM-DDTHH:MM:SS`, an optional fraction of up to nine digits, then
+ *   `Z` or a `±HH:MM` offset. A day the month does not have (`2024-02-30`) is false, although the
+ *   pattern matches it.
+ * - `eventTimeZoneOffset` must match `epcisTimeZoneOffset` (the pattern the EPCIS JSON schema
+ *   gives; the XSD types the field as a bare `xsd:string`): `±HH:MM` from `-14:00` to `+14:00`,
+ *   the rule of EPCIS Standard Release 2.0 §7.4.1 (https://ref.gs1.org/standards/epcis/). A
+ *   missing offset, `Z`, `+0200` and `+02` are false.
+ * - The two fields are independent: an `eventTime` written with one offset and an
+ *   `eventTimeZoneOffset` that is another is valid. EPCIS 2.0 §7.4.1.1 (non-normative): "there
+ *   is no requirement that the time zone specifier in the XML representation of eventTime be the
+ *   local time zone offset where the event was captured".
+ * - **GMT rule:** a fraction longer than nine digits is false. The XSD allows any length; an
+ *   instant holds nanoseconds, and `parseEpcisEvent` does not drop digits.
+ * - Only the two fields are checked. `recordTime` and every other member are ignored, so this
+ *   does not validate a whole event against the EPCIS schema.
+ * - Returns false for a value that is not an object.
+ *
+ * @param event candidate EPCIS event, or any object with `eventTime` and `eventTimeZoneOffset`
+ * @returns boolean indicating whether `parseEpcisEvent` reads the event, or false on invalid input
+ *
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-05:00" }) // true
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T10:00:00+02:00", eventTimeZoneOffset: "-05:00" }) // true (the two offsets need not agree)
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00.123456789Z", eventTimeZoneOffset: "+14:00" }) // true
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00Z" }) // false (eventTimeZoneOffset is required)
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "Z" }) // false (a designator, not an offset)
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "+0200" }) // false (no colon)
+ * @example isValidEpcisEvent({ eventTime: "2024-06-15T14:30Z", eventTimeZoneOffset: "-05:00" }) // false (seconds are required)
+ * @example isValidEpcisEvent({ eventTime: "2024-02-30T14:30:00Z", eventTimeZoneOffset: "-05:00" }) // false (30 February)
+ * @example isValidEpcisEvent("2024-06-15T14:30:00Z") // false (not an event)
+ */
+export function isValidEpcisEvent(event) {
+    try {
+        if (!isObject(event)) {
+            return false;
+        }
+        // Each field is read once, in the order `parseEpcisEvent` reads them.
+        const { eventTime, eventTimeZoneOffset } = event;
+        return (isValidEpcisEventTime(eventTime) &&
+            isValidEpcisTimeZoneOffset(eventTimeZoneOffset));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile argument is invalid input, not an exception.
+        return false;
+    }
+}

package/dist/intermodal/validate/isValidEpcisEventTime.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Return true when `value` is a real GS1 EPCIS 2.0 `eventTime`: the moment a supply-chain event
+ * happened, written as a date and time with `Z` or a UTC offset.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility. This is the check
+ * `isValidEpcisEvent` applies to the event's `eventTime` field: that validator calls this one.
+ *
+ * - The value must match `epcisEventTime`, the `DateTimeStamp` pattern of the EPCIS XSD:
+ *   `YYYY-MM-DDTHH:MM:SS`, an optional fraction, then `Z` or a `±HH:MM` offset up to `14:00`.
+ *   Seconds are required, `T` and `Z` are upper-case, and nothing may follow.
+ * - Checks the calendar as well as the shape. The pattern proves the shape alone, so it matches
+ *   a day the month does not have: `2024-02-30` and `2023-02-29` are false here.
+ * - **GMT rule:** a fraction longer than nine digits is false, although the pattern matches a
+ *   fraction of any length. An instant holds nanoseconds, and `parseEpcisEvent` does not drop
+ *   digits.
+ * - False for a leap second (`:60`), a space separator, an expanded year and a bracketed zone,
+ *   none of which the pattern matches.
+ * - An event also needs an `eventTimeZoneOffset`: check it with `isValidEpcisTimeZoneOffset`, or
+ *   both fields with `isValidEpcisEvent`. Read an event with `parseEpcisEvent`.
+ * - False for a non-string.
+ *
+ * @param value candidate EPCIS `eventTime` string
+ * @returns boolean indicating validity
+ *
+ * @example isValidEpcisEventTime("2024-06-15T14:30:00Z") // true
+ * @example isValidEpcisEventTime("2024-06-15T10:00:00.123+02:00") // true
+ * @example isValidEpcisEventTime("2024-02-30T14:30:00Z") // false (30 February; the epcisEventTime pattern matches it)
+ * @example isValidEpcisEventTime("2023-02-29T00:00:00Z") // false (2023 has no 29 February; the epcisEventTime pattern matches it)
+ * @example isValidEpcisEventTime("2024-06-15T14:30:00.1234567891Z") // false (finer than a nanosecond; the epcisEventTime pattern matches it)
+ * @example isValidEpcisEventTime("2024-06-15T14:30Z") // false (seconds are required)
+ * @example isValidEpcisEventTime("2024-06-15T14:30:00") // false (Z or an offset is required)
+ */
+export declare function isValidEpcisEventTime(value: string): boolean;

package/dist/intermodal/validate/isValidEpcisEventTime.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { epcisEventTime } from "../../regex/index.js";
+/**
+ * Return true when `value` is a real GS1 EPCIS 2.0 `eventTime`: the moment a supply-chain event
+ * happened, written as a date and time with `Z` or a UTC offset.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility. This is the check
+ * `isValidEpcisEvent` applies to the event's `eventTime` field: that validator calls this one.
+ *
+ * - The value must match `epcisEventTime`, the `DateTimeStamp` pattern of the EPCIS XSD:
+ *   `YYYY-MM-DDTHH:MM:SS`, an optional fraction, then `Z` or a `±HH:MM` offset up to `14:00`.
+ *   Seconds are required, `T` and `Z` are upper-case, and nothing may follow.
+ * - Checks the calendar as well as the shape. The pattern proves the shape alone, so it matches
+ *   a day the month does not have: `2024-02-30` and `2023-02-29` are false here.
+ * - **GMT rule:** a fraction longer than nine digits is false, although the pattern matches a
+ *   fraction of any length. An instant holds nanoseconds, and `parseEpcisEvent` does not drop
+ *   digits.
+ * - False for a leap second (`:60`), a space separator, an expanded year and a bracketed zone,
+ *   none of which the pattern matches.
+ * - An event also needs an `eventTimeZoneOffset`: check it with `isValidEpcisTimeZoneOffset`, or
+ *   both fields with `isValidEpcisEvent`. Read an event with `parseEpcisEvent`.
+ * - False for a non-string.
+ *
+ * @param value candidate EPCIS `eventTime` string
+ * @returns boolean indicating validity
+ *
+ * @example isValidEpcisEventTime("2024-06-15T14:30:00Z") // true
+ * @example isValidEpcisEventTime("2024-06-15T10:00:00.123+02:00") // true
+ * @example isValidEpcisEventTime("2024-02-30T14:30:00Z") // false (30 February; the epcisEventTime pattern matches it)
+ * @example isValidEpcisEventTime("2023-02-29T00:00:00Z") // false (2023 has no 29 February; the epcisEventTime pattern matches it)
+ * @example isValidEpcisEventTime("2024-06-15T14:30:00.1234567891Z") // false (finer than a nanosecond; the epcisEventTime pattern matches it)
+ * @example isValidEpcisEventTime("2024-06-15T14:30Z") // false (seconds are required)
+ * @example isValidEpcisEventTime("2024-06-15T14:30:00") // false (Z or an offset is required)
+ */
+export function isValidEpcisEventTime(value) {
+    if (typeof value !== "string" || !epcisEventTime.test(value)) {
+        return false;
+    }
+    try {
+        // The two checks the pattern cannot make: a day the month does not have, and a fraction past
+        // nine digits (Temporal's grammar stops at nanoseconds). Both are a RangeError.
+        Temporal.Instant.from(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/intermodal/validate/isValidEpcisTimeZoneOffset.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Return true when `value` is a GS1 EPCIS 2.0 `eventTimeZoneOffset`: the UTC offset the local
+ * clock ran at where a supply-chain event happened, written `±HH:MM`.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility. This is the check
+ * `isValidEpcisEvent` applies to the event's `eventTimeZoneOffset` field: that validator calls
+ * this one.
+ *
+ * - The value must match `epcisTimeZoneOffset`, the pattern the EPCIS JSON schema gives: `±HH:MM`
+ *   from `-14:00` to `+14:00`, the rule of EPCIS Standard Release 2.0 §7.4.1
+ *   (https://ref.gs1.org/standards/epcis/).
+ * - **The pattern is the whole rule for a string.** Every value it matches is an offset Temporal
+ *   reads, so this validator and `epcisTimeZoneOffset.test` agree on every string; the validator
+ *   adds only the answer false for a non-string.
+ * - `Z`, `+0200`, `+02`, an offset with seconds and an offset past `14:00` are false.
+ * - `-00:00` is true: the GS1 pattern matches it. `parseEpcisEvent` returns it as `+00:00`.
+ * - It need not agree with an offset written in the event's `eventTime`. Check that field with
+ *   `isValidEpcisEventTime`, or both with `isValidEpcisEvent`.
+ *
+ * @param value candidate EPCIS `eventTimeZoneOffset` string
+ * @returns boolean indicating validity
+ *
+ * @example isValidEpcisTimeZoneOffset("-05:00") // true
+ * @example isValidEpcisTimeZoneOffset("+14:00") // true
+ * @example isValidEpcisTimeZoneOffset("+14:01") // false (past the range GS1 allows)
+ * @example isValidEpcisTimeZoneOffset("Z") // false (a designator, not an offset)
+ * @example isValidEpcisTimeZoneOffset("+0200") // false (no colon)
+ * @example isValidEpcisTimeZoneOffset("+05:30:00") // false (seconds)
+ */
+export declare function isValidEpcisTimeZoneOffset(value: string): boolean;

package/dist/intermodal/validate/isValidEpcisTimeZoneOffset.js

@@ -0,0 +1,38 @@
+import { parseUtcOffsetNanoseconds } from "../../internal/index.js";
+import { epcisTimeZoneOffset } from "../../regex/index.js";
+/**
+ * Return true when `value` is a GS1 EPCIS 2.0 `eventTimeZoneOffset`: the UTC offset the local
+ * clock ran at where a supply-chain event happened, written `±HH:MM`.
+ *
+ * EPCIS (ISO/IEC 19987) is GS1's event standard for supply-chain visibility. This is the check
+ * `isValidEpcisEvent` applies to the event's `eventTimeZoneOffset` field: that validator calls
+ * this one.
+ *
+ * - The value must match `epcisTimeZoneOffset`, the pattern the EPCIS JSON schema gives: `±HH:MM`
+ *   from `-14:00` to `+14:00`, the rule of EPCIS Standard Release 2.0 §7.4.1
+ *   (https://ref.gs1.org/standards/epcis/).
+ * - **The pattern is the whole rule for a string.** Every value it matches is an offset Temporal
+ *   reads, so this validator and `epcisTimeZoneOffset.test` agree on every string; the validator
+ *   adds only the answer false for a non-string.
+ * - `Z`, `+0200`, `+02`, an offset with seconds and an offset past `14:00` are false.
+ * - `-00:00` is true: the GS1 pattern matches it. `parseEpcisEvent` returns it as `+00:00`.
+ * - It need not agree with an offset written in the event's `eventTime`. Check that field with
+ *   `isValidEpcisEventTime`, or both with `isValidEpcisEvent`.
+ *
+ * @param value candidate EPCIS `eventTimeZoneOffset` string
+ * @returns boolean indicating validity
+ *
+ * @example isValidEpcisTimeZoneOffset("-05:00") // true
+ * @example isValidEpcisTimeZoneOffset("+14:00") // true
+ * @example isValidEpcisTimeZoneOffset("+14:01") // false (past the range GS1 allows)
+ * @example isValidEpcisTimeZoneOffset("Z") // false (a designator, not an offset)
+ * @example isValidEpcisTimeZoneOffset("+0200") // false (no colon)
+ * @example isValidEpcisTimeZoneOffset("+05:30:00") // false (seconds)
+ */
+export function isValidEpcisTimeZoneOffset(value) {
+    // `parseEpcisEvent` reads the offset through Temporal after the pattern, so this does too. No
+    // string the pattern matches fails that read: it is here so the two cannot drift.
+    return (typeof value === "string" &&
+        epcisTimeZoneOffset.test(value) &&
+        parseUtcOffsetNanoseconds(value) !== null);
+}

package/dist/intermodal/validate/isValidX12Date.d.ts

@@ -0,0 +1,28 @@
+import type { X12DateFormat } from "../../types/edi.js";
+/**
+ * Return true when `value` is an X12 Date Time Period value (data element 1251) that states a
+ * real calendar date in a date format qualifier (data element 1250).
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `D8` | `CCYYMMDD` | "Date Expressed in Format CCYYMMDD" |
+ * | `DB` | `MMDDCCYY` | "Date Expressed in Format MMDDCCYY" |
+ *
+ * - True exactly when `parseX12Date` returns a date for the same arguments: the validator calls
+ *   the parser, so the two cannot disagree.
+ * - A value is valid only against its code: `"06152024"` is a `DB` value and not a `D8` one.
+ * - Checks the calendar as well as the shape: 31 June and 29 February 2023 are false.
+ * - False for any other code, a code of another kind included; check a code alone with
+ *   `isValidX12DateTimePeriodFormat`. False for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "20240615")
+ * @param format X12 data element 1250 format qualifier
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12Date("20240615", "D8") // true
+ * @example isValidX12Date("06152024", "DB") // true
+ * @example isValidX12Date("06152024", "D8") // false (20 is not a month)
+ * @example isValidX12Date("20230229", "D8") // false (2023 has no 29 February)
+ */
+export declare function isValidX12Date(value: string, format: X12DateFormat): boolean;

package/dist/intermodal/validate/isValidX12Date.js

@@ -0,0 +1,30 @@
+import { parseX12Date } from "../parse/parseX12Date.js";
+/**
+ * Return true when `value` is an X12 Date Time Period value (data element 1251) that states a
+ * real calendar date in a date format qualifier (data element 1250).
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `D8` | `CCYYMMDD` | "Date Expressed in Format CCYYMMDD" |
+ * | `DB` | `MMDDCCYY` | "Date Expressed in Format MMDDCCYY" |
+ *
+ * - True exactly when `parseX12Date` returns a date for the same arguments: the validator calls
+ *   the parser, so the two cannot disagree.
+ * - A value is valid only against its code: `"06152024"` is a `DB` value and not a `D8` one.
+ * - Checks the calendar as well as the shape: 31 June and 29 February 2023 are false.
+ * - False for any other code, a code of another kind included; check a code alone with
+ *   `isValidX12DateTimePeriodFormat`. False for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "20240615")
+ * @param format X12 data element 1250 format qualifier
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12Date("20240615", "D8") // true
+ * @example isValidX12Date("06152024", "DB") // true
+ * @example isValidX12Date("06152024", "D8") // false (20 is not a month)
+ * @example isValidX12Date("20230229", "D8") // false (2023 has no 29 February)
+ */
+export function isValidX12Date(value, format) {
+    return parseX12Date(value, format) !== "";
+}

package/dist/intermodal/validate/isValidX12DateAndTime.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Return true when the date and the time of an X12 segment, sent as two elements, together
+ * state a real local date and time.
+ *
+ * ### The two elements
+ * | Element | Name | The dictionary's definition |
+ * |---|---|---|
+ * | [373](https://www.stedi.com/edi/x12-005010/element/373) | Date | "Date expressed as CCYYMMDD where CC represents the first two digits of the calendar year" |
+ * | [337](https://www.stedi.com/edi/x12-005010/element/337) | Time | "Time expressed in 24-hour clock time as follows: HHMM, or HHMMSS, or HHMMSSD, or HHMMSSDD" |
+ *
+ * - True exactly when `parseX12DateAndTime` returns a date-time for the same arguments: the
+ *   validator calls the parser, so the two cannot disagree.
+ * - **Both elements are required.** A missing or empty date or time is false: check a date alone
+ *   with `isValidX12Date(value, "D8")` and a time alone with `isValidX12Time`.
+ * - Checks the calendar as well as the shape: 29 February 2023, 31 June, hour 24 and minute or
+ *   second 60 are false.
+ * - The date has a four-digit year and the time is 4, 6, 7 or 8 digits: a date of six digits and
+ *   a time of 5 or 9 digits are false.
+ * - False for a non-string argument.
+ *
+ * @param date The data element 373 date as transmitted, `CCYYMMDD` (e.g. "20240615")
+ * @param time The data element 337 time as transmitted (e.g. "1430")
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateAndTime("20240615", "1430") // true
+ * @example isValidX12DateAndTime("20240615", "14300012") // true (hundredths of a second)
+ * @example isValidX12DateAndTime("20240615", "") // false (both elements are required)
+ * @example isValidX12DateAndTime("20230229", "1430") // false (2023 has no 29 February)
+ * @example isValidX12DateAndTime("20240615", "2430") // false (hour 24)
+ * @example isValidX12DateAndTime("240615", "1430") // false (the date element has a four-digit year)
+ */
+export declare function isValidX12DateAndTime(date: string, time: string): boolean;

package/dist/intermodal/validate/isValidX12DateAndTime.js

@@ -0,0 +1,35 @@
+import { parseX12DateAndTime } from "../parse/parseX12DateAndTime.js";
+/**
+ * Return true when the date and the time of an X12 segment, sent as two elements, together
+ * state a real local date and time.
+ *
+ * ### The two elements
+ * | Element | Name | The dictionary's definition |
+ * |---|---|---|
+ * | [373](https://www.stedi.com/edi/x12-005010/element/373) | Date | "Date expressed as CCYYMMDD where CC represents the first two digits of the calendar year" |
+ * | [337](https://www.stedi.com/edi/x12-005010/element/337) | Time | "Time expressed in 24-hour clock time as follows: HHMM, or HHMMSS, or HHMMSSD, or HHMMSSDD" |
+ *
+ * - True exactly when `parseX12DateAndTime` returns a date-time for the same arguments: the
+ *   validator calls the parser, so the two cannot disagree.
+ * - **Both elements are required.** A missing or empty date or time is false: check a date alone
+ *   with `isValidX12Date(value, "D8")` and a time alone with `isValidX12Time`.
+ * - Checks the calendar as well as the shape: 29 February 2023, 31 June, hour 24 and minute or
+ *   second 60 are false.
+ * - The date has a four-digit year and the time is 4, 6, 7 or 8 digits: a date of six digits and
+ *   a time of 5 or 9 digits are false.
+ * - False for a non-string argument.
+ *
+ * @param date The data element 373 date as transmitted, `CCYYMMDD` (e.g. "20240615")
+ * @param time The data element 337 time as transmitted (e.g. "1430")
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateAndTime("20240615", "1430") // true
+ * @example isValidX12DateAndTime("20240615", "14300012") // true (hundredths of a second)
+ * @example isValidX12DateAndTime("20240615", "") // false (both elements are required)
+ * @example isValidX12DateAndTime("20230229", "1430") // false (2023 has no 29 February)
+ * @example isValidX12DateAndTime("20240615", "2430") // false (hour 24)
+ * @example isValidX12DateAndTime("240615", "1430") // false (the date element has a four-digit year)
+ */
+export function isValidX12DateAndTime(date, time) {
+    return parseX12DateAndTime(date, time) !== "";
+}

package/dist/intermodal/validate/isValidX12DateRange.d.ts

@@ -0,0 +1,29 @@
+import type { X12DateRangeFormat } from "../../types/edi.js";
+/**
+ * Return true when `value` is an X12 Date Time Period value (data element 1251) that states a
+ * range between two real calendar dates, in a date range format qualifier (data element 1250).
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `RD8` | `CCYYMMDD-CCYYMMDD` | "Range of Dates Expressed in Format CCYYMMDD-CCYYMMDD" |
+ * | `RD` | `MMDDCCYY-MMDDCCYY` | "Range of Dates Expressed in Format MMDDCCYY-MMDDCCYY" |
+ *
+ * - True exactly when `parseX12DateRange` returns a range for the same arguments: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - A range is valid with exactly one hyphen: `"2024061520240620"` is false.
+ * - A range whose end precedes its start is false; an end equal to its start is true.
+ * - Checks the calendar as well as the shape: 29 February 2023 in either date is false.
+ * - False for any other code, a code of another kind included; check a code alone with
+ *   `isValidX12DateTimePeriodFormat`. False for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "20240615-20240620")
+ * @param format X12 data element 1250 format qualifier
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateRange("20240615-20240620", "RD8") // true
+ * @example isValidX12DateRange("06152024-06202024", "RD") // true
+ * @example isValidX12DateRange("2024061520240620", "RD8") // false (a range is transmitted with its hyphen)
+ * @example isValidX12DateRange("20240620-20240615", "RD8") // false (the end precedes the start)
+ */
+export declare function isValidX12DateRange(value: string, format: X12DateRangeFormat): boolean;

package/dist/intermodal/validate/isValidX12DateRange.js

@@ -0,0 +1,31 @@
+import { parseX12DateRange } from "../parse/parseX12DateRange.js";
+/**
+ * Return true when `value` is an X12 Date Time Period value (data element 1251) that states a
+ * range between two real calendar dates, in a date range format qualifier (data element 1250).
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `RD8` | `CCYYMMDD-CCYYMMDD` | "Range of Dates Expressed in Format CCYYMMDD-CCYYMMDD" |
+ * | `RD` | `MMDDCCYY-MMDDCCYY` | "Range of Dates Expressed in Format MMDDCCYY-MMDDCCYY" |
+ *
+ * - True exactly when `parseX12DateRange` returns a range for the same arguments: the validator
+ *   calls the parser, so the two cannot disagree.
+ * - A range is valid with exactly one hyphen: `"2024061520240620"` is false.
+ * - A range whose end precedes its start is false; an end equal to its start is true.
+ * - Checks the calendar as well as the shape: 29 February 2023 in either date is false.
+ * - False for any other code, a code of another kind included; check a code alone with
+ *   `isValidX12DateTimePeriodFormat`. False for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "20240615-20240620")
+ * @param format X12 data element 1250 format qualifier
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateRange("20240615-20240620", "RD8") // true
+ * @example isValidX12DateRange("06152024-06202024", "RD") // true
+ * @example isValidX12DateRange("2024061520240620", "RD8") // false (a range is transmitted with its hyphen)
+ * @example isValidX12DateRange("20240620-20240615", "RD8") // false (the end precedes the start)
+ */
+export function isValidX12DateRange(value, format) {
+    return parseX12DateRange(value, format) !== null;
+}

package/dist/intermodal/validate/isValidX12DateTime.d.ts

@@ -0,0 +1,30 @@
+import type { X12DateTimeFormat } from "../../types/edi.js";
+/**
+ * Return true when `value` is an X12 Date Time Period value (data element 1251) that states a
+ * real date and time in a date-time format qualifier (data element 1250).
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `DT` | `CCYYMMDDHHMM` | "Date and Time Expressed in Format CCYYMMDDHHMM" |
+ * | `RTS` | `CCYYMMDDHHMMSS` | "Date and Time Expressed in Format CCYYMMDDHHMMSS" |
+ *
+ * - True exactly when `parseX12DateTime` returns a date-time for the same arguments: the
+ *   validator calls the parser, so the two cannot disagree.
+ * - A value is valid only against its code: `"202406151430"` is a `DT` value and not an `RTS`
+ *   one.
+ * - Checks the calendar as well as the shape: 31 June, 29 February 2023, hour 24 and second 60
+ *   are false.
+ * - False for any other code, a code of another kind included; check a code alone with
+ *   `isValidX12DateTimePeriodFormat`. False for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "202406151430")
+ * @param format X12 data element 1250 format qualifier
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateTime("202406151430", "DT") // true
+ * @example isValidX12DateTime("20240615143045", "RTS") // true
+ * @example isValidX12DateTime("202406151430", "RTS") // false (twelve digits is a DT value)
+ * @example isValidX12DateTime("202406152430", "DT") // false (hour 24)
+ */
+export declare function isValidX12DateTime(value: string, format: X12DateTimeFormat): boolean;

package/dist/intermodal/validate/isValidX12DateTime.js

@@ -0,0 +1,32 @@
+import { parseX12DateTime } from "../parse/parseX12DateTime.js";
+/**
+ * Return true when `value` is an X12 Date Time Period value (data element 1251) that states a
+ * real date and time in a date-time format qualifier (data element 1250).
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `DT` | `CCYYMMDDHHMM` | "Date and Time Expressed in Format CCYYMMDDHHMM" |
+ * | `RTS` | `CCYYMMDDHHMMSS` | "Date and Time Expressed in Format CCYYMMDDHHMMSS" |
+ *
+ * - True exactly when `parseX12DateTime` returns a date-time for the same arguments: the
+ *   validator calls the parser, so the two cannot disagree.
+ * - A value is valid only against its code: `"202406151430"` is a `DT` value and not an `RTS`
+ *   one.
+ * - Checks the calendar as well as the shape: 31 June, 29 February 2023, hour 24 and second 60
+ *   are false.
+ * - False for any other code, a code of another kind included; check a code alone with
+ *   `isValidX12DateTimePeriodFormat`. False for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "202406151430")
+ * @param format X12 data element 1250 format qualifier
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateTime("202406151430", "DT") // true
+ * @example isValidX12DateTime("20240615143045", "RTS") // true
+ * @example isValidX12DateTime("202406151430", "RTS") // false (twelve digits is a DT value)
+ * @example isValidX12DateTime("202406152430", "DT") // false (hour 24)
+ */
+export function isValidX12DateTime(value, format) {
+    return parseX12DateTime(value, format) !== "";
+}

package/dist/intermodal/validate/isValidX12DateTimePeriodFormat.d.ts

@@ -0,0 +1,43 @@
+import type { X12DateTimePeriodFormat } from "../../types/edi.js";
+/**
+ * Return true when `format` is an X12 data element 1250 (Date Time Period Format Qualifier) code
+ * that the X12 functions read and write.
+ *
+ * - The 10 supported codes are `D8`, `DB` (a date); `TM`, `TS` (a time); `DT`, `RTS` (a date and
+ *   time); `RD8`, `RD` (a range of dates) and `RDT`, `DTS` (a range of date-times).
+ *   `classifyX12DateTimePeriodFormat` names the kind of a code, and each kind has its own
+ *   parser, formatter and validator. 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.
+ * - A code with a two-digit year returns false: `D6`, `TT`, `TR`, `RD6` and `TU`. X12 does not
+ *   say which century `YY` belongs to; read such a value 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) return false: none states a value of one kind.
+ * - The other 21 codes of the element return false: the partial values (`CC`, `CY`, `CM`, `CQ`,
+ *   `YM`, `MD`, `DD`, `MM`, `TQ`, `YY`, `MCY`), the ranges of partial values (`DA`, `RD2`, `RD4`,
+ *   `RD5`, `RMD`, `RMY`), `RDM` (`YYMMDD-MMDD`, a range whose end names no year) and the
+ *   month-name forms (`CD`, `KA`, `YMM`).
+ * - `TS`, `TT`, `CD` and `MD` are codes of data element 623 (Time Code) too, with unrelated
+ *   meanings: here `TS` is `HHMMSS`, and `TT`, `CD` and `MD` are not read; there they name the
+ *   Atlantic, Central and Mountain zones. Check a time code with `isValidX12TimeCode`.
+ * - Matching is exact: case and spacing are not normalised.
+ * - Accepts any input type and returns false for non-string values.
+ * - A parser returns its sentinel for a code it does not read and for a bad value alike. Check
+ *   the code here to tell a code GMT does not read apart from a value that does not fit its
+ *   code.
+ *
+ * @param format candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateTimePeriodFormat("D8") // true
+ * @example isValidX12DateTimePeriodFormat("RD8") // true
+ * @example isValidX12DateTimePeriodFormat("D6") // false (a two-digit year: not read)
+ * @example isValidX12DateTimePeriodFormat("UN") // false (unstructured: nothing to read)
+ * @example isValidX12DateTimePeriodFormat("d8") // false (case is exact)
+ * @example isValidX12DateTimePeriodFormat("CM") // false (a year and month: a code GMT does not read)
+ * @example isValidX12DateTimePeriodFormat("DTM") // false (a segment name, not a 1250 code)
+ * @example isValidX12DateTimePeriodFormat(null) // false
+ */
+export declare function isValidX12DateTimePeriodFormat(format: unknown): format is X12DateTimePeriodFormat;

package/dist/intermodal/validate/isValidX12DateTimePeriodFormat.js

@@ -0,0 +1,46 @@
+import { X12_DATE_TIME_PERIOD_FORMATS } from "../../internal/index.js";
+/**
+ * Return true when `format` is an X12 data element 1250 (Date Time Period Format Qualifier) code
+ * that the X12 functions read and write.
+ *
+ * - The 10 supported codes are `D8`, `DB` (a date); `TM`, `TS` (a time); `DT`, `RTS` (a date and
+ *   time); `RD8`, `RD` (a range of dates) and `RDT`, `DTS` (a range of date-times).
+ *   `classifyX12DateTimePeriodFormat` names the kind of a code, and each kind has its own
+ *   parser, formatter and validator. 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.
+ * - A code with a two-digit year returns false: `D6`, `TT`, `TR`, `RD6` and `TU`. X12 does not
+ *   say which century `YY` belongs to; read such a value 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) return false: none states a value of one kind.
+ * - The other 21 codes of the element return false: the partial values (`CC`, `CY`, `CM`, `CQ`,
+ *   `YM`, `MD`, `DD`, `MM`, `TQ`, `YY`, `MCY`), the ranges of partial values (`DA`, `RD2`, `RD4`,
+ *   `RD5`, `RMD`, `RMY`), `RDM` (`YYMMDD-MMDD`, a range whose end names no year) and the
+ *   month-name forms (`CD`, `KA`, `YMM`).
+ * - `TS`, `TT`, `CD` and `MD` are codes of data element 623 (Time Code) too, with unrelated
+ *   meanings: here `TS` is `HHMMSS`, and `TT`, `CD` and `MD` are not read; there they name the
+ *   Atlantic, Central and Mountain zones. Check a time code with `isValidX12TimeCode`.
+ * - Matching is exact: case and spacing are not normalised.
+ * - Accepts any input type and returns false for non-string values.
+ * - A parser returns its sentinel for a code it does not read and for a bad value alike. Check
+ *   the code here to tell a code GMT does not read apart from a value that does not fit its
+ *   code.
+ *
+ * @param format candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateTimePeriodFormat("D8") // true
+ * @example isValidX12DateTimePeriodFormat("RD8") // true
+ * @example isValidX12DateTimePeriodFormat("D6") // false (a two-digit year: not read)
+ * @example isValidX12DateTimePeriodFormat("UN") // false (unstructured: nothing to read)
+ * @example isValidX12DateTimePeriodFormat("d8") // false (case is exact)
+ * @example isValidX12DateTimePeriodFormat("CM") // false (a year and month: a code GMT does not read)
+ * @example isValidX12DateTimePeriodFormat("DTM") // false (a segment name, not a 1250 code)
+ * @example isValidX12DateTimePeriodFormat(null) // false
+ */
+export function isValidX12DateTimePeriodFormat(format) {
+    return (typeof format === "string" &&
+        X12_DATE_TIME_PERIOD_FORMATS.includes(format));
+}

package/dist/intermodal/validate/isValidX12DateTimeRange.d.ts

@@ -0,0 +1,31 @@
+import type { X12DateTimeRangeFormat } from "../../types/edi.js";
+/**
+ * Return true when `value` is an X12 Date Time Period value (data element 1251) that states a
+ * range between two real local date-times, in a date-time range format qualifier (data element
+ * 1250).
+ *
+ * ### Format codes
+ * | Code | Mask | The dictionary's definition |
+ * |---|---|---|
+ * | `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" |
+ *
+ * - True exactly when `parseX12DateTimeRange` returns a range for the same arguments: the
+ *   validator calls the parser, so the two cannot disagree.
+ * - A range is valid with exactly one hyphen, and only against its code.
+ * - A range whose end precedes its start is false; an end equal to its start is true.
+ * - Checks the calendar as well as the shape: hour 24, second 60 and 29 February 2023 are
+ *   false.
+ * - False for any other code, a code of another kind included; check a code alone with
+ *   `isValidX12DateTimePeriodFormat`. False for a non-string argument.
+ *
+ * @param value The data element 1251 value (e.g. "202406151430-202406201600")
+ * @param format X12 data element 1250 format qualifier
+ * @returns boolean indicating validity
+ *
+ * @example isValidX12DateTimeRange("202406151430-202406201600", "RDT") // true
+ * @example isValidX12DateTimeRange("20240615143045-20240620160030", "DTS") // true
+ * @example isValidX12DateTimeRange("202406151430202406201600", "RDT") // false (a range is transmitted with its hyphen)
+ * @example isValidX12DateTimeRange("202406151431-202406151430", "RDT") // false (the end precedes the start)
+ */
+export declare function isValidX12DateTimeRange(value: string, format: X12DateTimeRangeFormat): boolean;