Skip to content
@northguild/gmt

formatEpcisEvent

  • Container free time, demurrage, billing deadlines, bill of lading dates and EDI timestamps.

Signature

Section titled “Signature”
formatEpcisEvent(value: OffsetInstant): EpcisEventTime | null

Write an instant-plus-offset pair as the two required time fields of a GS1 EPCIS 2.0 event.

  • EPCIS (ISO/IEC 19987) is GS1’s event standard for supply-chain visibility. Every event must carry eventTime, the instant, and eventTimeZoneOffset, the offset the local clock ran at where the event happened. The inverse of parseEpcisEvent, whose result it takes as it is.
  • eventTime is the instant in UTC, ending in Z, as Temporal.Instant.prototype.toString writes it: seconds always present, and a fraction kept to the nanosecond with no trailing zeros and no padding. It always matches epcisEventTime, the DateTimeStamp pattern of the EPCIS XSD, and so is valid in the XML binding and in the JSON one (format: date-time).
  • eventTimeZoneOffset is offset, which must match epcisTimeZoneOffset, the pattern of the EPCIS JSON schema and the rule of EPCIS Standard Release 2.0 §7.4.1 (https://ref.gs1.org/standards/epcis/): ±HH:MM from -14:00 to +14:00. That is narrower than the offsets a pair can hold, so an offset with seconds (+05:30:00, -00:44:30), one past 14 hours (+14:30) and Z return null, although fromOffsetInstant accepts some of them. Nothing is rounded to fit.
  • -00:00 matches the GS1 pattern and is written as +00:00, the spelling parseEpcisEvent returns.
  • instant is any instant isValidInstant accepts: Z, an offset, or an offset with a bracketed zone. Only the instant is read, so an offset written in instant does not have to equal offset.
  • timeZone is not read. EPCIS has no field for a zone, so a pair’s zone is dropped, and one that is invalid or disagrees with offset changes nothing. fromOffsetInstant is the function that checks a zone against its offset.
  • eventTime has a four-digit year, so an instant whose UTC year is outside 0000–9999 returns null. parseEpcisEvent can return one, from an eventTime whose own offset carries it across either end of that range, and such a result cannot be written back.
  • Returns null when value is not an object, when instant is not a valid instant, and when offset is missing, not a string, or outside the GS1 pattern.

Parameters

Section titled “Parameters”
ParameterTypeDescription
valueOffsetInstant{ instant, offset } pair, as parseEpcisEvent or toOffsetInstant returns it

Returns

Section titled “Returns”

{ eventTime, eventTimeZoneOffset }, or null on invalid input

Section titled “Related types”

Examples

Section titled “Examples”
import { formatEpcisEvent } from "@northguild/gmt/intermodal/format";


formatEpcisEvent({ instant: "2024-06-15T14:30:00Z", offset: "-05:00" }) // { eventTime: "2024-06-15T14:30:00Z", eventTimeZoneOffset: "-05:00" }
output 

Source

Section titled “Source”

intermodal/format/formatEpcisEvent.ts