• Public
  • Public/Protected
  • All

Class Timestamp

This class provides the additional semantics necessary for Ion timestamp values.


  • Timestamp




  • new Timestamp(date: Date): Timestamp
  • new Timestamp(localOffset: number, year: number, month?: number | null, day?: number | null, hour?: number | null, minutes?: number | null, seconds?: number | Decimal | null): Timestamp
  • Creates a new Ion Timestamp with millisecond precision from a JavaScript Date.

    Logically, an instance of this class represents an instant in time based on an offset from UTC and the other provided parameters.


    • date: Date

      a valid JavaScript date object

    Returns Timestamp

  • Creates a new Timestamp, with precision determined by which parameters are provided. If a parameter is not specified, it defaults to its lowest valid value; defaulted values are not used when determining the precision.

    Logically, an instance of this class represents an instant in time based on an offset from UTC and the other provided parameters.


    • localOffset: number

      Local offset from UTC (range: [-(23*60+59):(23*60+59)])

    • year: number

      the year (range: [1-9999])

    • Optional month: number | null

      the month (range: [1-12])

    • Optional day: number | null

      the day of the month (range: [1-31])

    • Optional hour: number | null

      the hour of the day (range: [0-23])

    • Optional minutes: number | null

      number of minutes (range: [0-59])

    • Optional seconds: number | Decimal | null

      number of seconds specified as a number (range: [0-59]), or a Decimal (range: [0.0-60.0)) in order to express whole seconds along with some fractional seconds

    Returns Timestamp



  • Compares this Timestamp with another and returns -1, 0, or 1 if the instant represented by this Timestamp occurs before, at the same time, or after the other Timestamp.

    Note that a return value of 0 from this method doesn't guarantee that equals() will return true, as compareTo() doesn't require the values to have the same precision and local offset to be considered the same instant, whereas equals() does. The following table illustrates this behavior:

    Timestamp 1 Timestamp 2 compareTo equals
    2001T 2001T 0 true
    2001-01-01T 2001-01-01T 0 true
    2001-01-01T00:00:00.000Z 2001-01-01T00:00:00.000Z 0 true
    2001T 2001-01-01T 0 false
    2001T 2001-01-01T00:00:00.000Z 0 false
    2001-01-01T00:00Z 2000-12-31T23:59-00:01 0 false


    Returns number


  • Compares this Timestamp with another and returns true if they represent the same instant and have the same precision. Note that this differs from compareTo(), which doesn't require precision to match when returning 0.


    Returns boolean


  • Returns a Date representing the value of this Timestamp. Note that this may be a lossy operation, as a Date cannot fully represent all Timestamp values. Specifically:

    • fractional seconds of a Timestamp beyond millisecond precision are rounded to the nearest millisecond in the returned Date
    • if the precision of this Timestamp is YEAR or MONTH, the returned Date's month and day are set to January 1
    • the returned Date object is not aware of this Timestamp's local offset property

    With the exception of the discrepancies noted above, the returned Date will represent the same instant in time as this Timestamp. However, most methods of the Date API will return properties in the local date and time of the instant, which may differ from the local offset of the Timestamp. The Date class also provides methods for retrieving the properties of the instant in UTC.

    Returns Date


  • getLocalOffset(): number




  • getSecondsInt(): number
  • Returns the number of seconds as an integer value; any fractional seconds are truncated.

    Returns number


  • toJSON(): string
  • Converts this Timestamp to a ISO8601-formatted string when being serialized with JSON.stringify().

    Returns string


  • toString(): string

Static parse