@blockchaincommons/dcbor - v1.0.0-beta.3
    Preparing search index...

    Class CborDate

    A UTC date and time, encoded as CBOR tag 1 (RFC 8949 epoch-based date/time).

    The instant is held as whole seconds since the Unix epoch plus nanoseconds. On the wire it is tag 1 followed by the seconds since (or before) 1970-01-01T00:00:00Z: an integer for whole seconds, a float otherwise. Implements the CborTagged interface and the ToCbor protocol.

    import { CborDate } from "@blockchaincommons/dcbor";

    // Create a date from a timestamp (seconds since Unix epoch)
    const date = CborDate.fromEpochSeconds(1675854714.0);

    // Create a date from year, month, day
    const date2 = CborDate.fromYmd(2023, 2, 8);

    // Convert to CBOR
    const cborValue = date.taggedCbor();

    // Decode from CBOR
    const decoded = CborDate.fromTaggedCbor(cborValue);

    Implements

    Index
    [toStringTag] epochSeconds codec
    fromDate fromYmd fromYmdHms fromEpochSeconds fromString now withDurationFromNow toDate add subtract difference cborTags untaggedCbor taggedCbor toCbor fromUntaggedCbor fromTaggedCbor fromTaggedCbor fromUntaggedCbor toString equals compare toJSON
    • get "[toStringTag]"(): string

      Debug label: Object.prototype.toString reports [object CborDate].

      Returns string

    • get epochSeconds(): number

      The date as the number of seconds since the Unix epoch (1970-01-01T00:00:00Z), as a floating-point number. Negative values represent times before the epoch; the fractional part is sub-second precision.

      This is the reference's timestamp(): whole seconds plus nanoseconds over 10⁹, computed in f64, and it is the value that goes on the wire.

      Returns number

      const date = CborDate.fromYmd(2023, 2, 8);
      const timestamp = date.epochSeconds;
    • get codec(): CborCodec<CborDate>
      Beta

      The CborCodec exemplar: a runtime witness that binds T = CborDate for decodeWith(bytes, CborDate.codec).

      A lazy getter (memoized) rather than a static field: the date ↔ tags module cycle makes an eager initializer hit the temporal dead zone.

      Returns CborCodec<CborDate>

    • Creates a new CborDate from the given JavaScript Date.

      Parameters

      • dateTime: Date

        A Date instance

      Returns CborDate

      A new CborDate instance

      InvalidDate for an invalid Date (NaN time) or one outside the reference's representable range (years −262143 to 262142), which a chrono value handed to Date::from_datetime can never be.

      const datetime = new Date();
      const date = CborDate.fromDate(datetime);

    • Creates a new CborDate from year, month, and day components, at 00:00:00 UTC.

      Parameters

      • year: number

        The year component (e.g., 2023)

      • month: number

        The month component (1-12)

      • day: number

        The day component (1-31)

      Returns CborDate

      A new CborDate instance

      // Create February 8, 2023
      const date = CborDate.fromYmd(2023, 2, 8);

      InvalidDate if the components do not form a valid date (the reference panics there).

    • Creates a new CborDate from year, month, day, hour, minute, and second components.

      Parameters

      • year: number

        The year component (e.g., 2023)

      • month: number

        The month component (1-12)

      • day: number

        The day component (1-31)

      • hour: number

        The hour component (0-23)

      • minute: number

        The minute component (0-59)

      • second: number

        The second component (0-59)

      Returns CborDate

      A new CborDate instance

      // Create February 8, 2023, 15:30:45 UTC
      const date = CborDate.fromYmdHms(2023, 2, 8, 15, 30, 45);

      InvalidDate if the components do not form a valid date and time — the checks the reference's with_ymd_and_hms(…).unwrap() panics on: a year outside −262143…+262142, an impossible month or day, or a time past 23:59:59 (no leap second here; fromString accepts :60).

    • Creates a new CborDate from seconds since the Unix epoch (1970-01-01T00:00:00Z); negative values are before the epoch.

      The value is split as the reference's from_timestamp splits it: whole seconds by truncation toward zero, then the fraction in nanoseconds (truncated, never negative), so -1.5 is the instant -1 and 1.0000000001 is 1. NaN is the epoch, as the reference's saturating cast makes it.

      Parameters

      • secondsSinceUnixEpoch: number

        Seconds from the Unix epoch (positive or negative), which can include a fractional part for sub-second precision

      Returns CborDate

      A new CborDate instance

      InvalidDate for ±Infinity, or when the whole seconds fall outside the reference's representable range (years −262143 to 262142), where the reference panics.

      // Create a date from a timestamp
      const date = CborDate.fromEpochSeconds(1675854714.0);

      // Create a date one second before the Unix epoch
      const beforeEpoch = CborDate.fromEpochSeconds(-1.0);

      // Create a date with fractional seconds
      const withFraction = CborDate.fromEpochSeconds(1675854714.5);

    • Creates a new CborDate from a string containing an ISO-8601 (RFC-3339) date (with or without time).

      Accepts exactly what the reference's Date::from_string accepts:

      • An RFC 3339 date-time (2023-02-08T15:30:45Z, …45.123456789+05:30), with T, t or a space between date and time, up to nine fraction digits kept (further digits are ignored), Z/z or an offset within ±23:59, and the :60 leap second (read as second 59 plus one second, as chrono represents it).
      • A bare date read as UTC midnight, in chrono's %Y-%m-%d form: one to four year digits or a signed year of any length (-0001-01-01, +12023-02-08), one- or two-digit month and day, with whitespace allowed before each number (2023-2-8, 2023-02-08).

      The fraction is kept exactly as nanoseconds, so a decimal fraction encodes to the same bytes on both sides (timestamp(): whole seconds plus nanoseconds over 10⁹) and a leap second still displays as :60.

      Parameters

      • value: string

        A string containing a date or date-time in ISO-8601/RFC-3339 format

      Returns CborDate

      A new CborDate instance if parsing succeeds

      InvalidDate if the string cannot be parsed as a valid date or date-time (an impossible calendar date, a time past 23:59:60, an offset beyond ±23:59, a missing offset, or trailing characters).

      // Parse a date-time string
      const date = CborDate.fromString("2023-02-08T15:30:45Z");

      // Parse a date-only string (time will be set to 00:00:00)
      const date2 = CborDate.fromString("2023-02-08");

    • Creates a new CborDate containing the current date and time.

      Returns CborDate

      A new CborDate instance representing the current UTC date and time

      const now = CborDate.now();

    • Creates a new CborDate containing the current date and time plus the given duration.

      Parameters

      • durationMs: number

        The duration in milliseconds to add to the current time

      Returns CborDate

      A new CborDate instance representing the current UTC date and time plus the duration

      // Get a date 1 hour from now
      const oneHourLater = CborDate.withDurationFromNow(3600 * 1000);

    • Returns a new JavaScript Date for this instant (millisecond precision; sub-millisecond digits are lost).

      Returns Date

      A new Date instance

      const date = CborDate.now();
      const datetime = date.toDate();
      const year = datetime.getFullYear();

    • Add seconds to this date.

      Parameters

      • seconds: number

        Seconds to add (can be fractional)

      Returns CborDate

      New CborDate instance

      const date = CborDate.fromYmd(2022, 3, 21);
      const tomorrow = date.add(24 * 60 * 60);

    • Subtract seconds from this date.

      Parameters

      • seconds: number

        Seconds to subtract (can be fractional)

      Returns CborDate

      New CborDate instance

      const date = CborDate.fromYmd(2022, 3, 21);
      const yesterday = date.subtract(24 * 60 * 60);

    • Get the difference in seconds between this date and another.

      Parameters

      • other: CborDate

        Other CborDate to compare with

      Returns number

      Difference in seconds (this - other)

      const date1 = CborDate.fromYmd(2022, 3, 22);
      const date2 = CborDate.fromYmd(2022, 3, 21);
      const diff = date1.difference(date2);
      // Returns 86400 (one day in seconds)

    • The CBOR tags for CborDate: tag 1, the RFC 8949 epoch-based date/time.

      The tag carries whatever name the global tags store has for 1 at the time of the call (tags_for_values in the reference): date once registerStandardTags() has run, otherwise none. That name is what a WrongTag error prints as the expected tag.

      Returns Tag[]

      An array containing tag 1

    • Converts this CborDate to its untagged CBOR content: the epoch-seconds numeric value. It may be an integer or a floating-point number, depending on whether the date has fractional seconds.

      Returns Cbor

      A CBOR value representing the timestamp

    • Converts this CborDate to a tagged CBOR value with tag 1.

      Returns Cbor

      Tagged CBOR value

    • The ToCbor protocol: dates encode as their tagged form.

      Returns Cbor

    • Creates a CborDate from an untagged CBOR value, which must be a number (integer or floating-point) of seconds since the Unix epoch. The static CborDate.fromUntaggedCbor is the usual entry point; this instance form exists for the CborTagged protocol and returns a new instance.

      Parameters

      • cbor: Cbor

        The untagged CBOR value

      Returns CborDate

      The decoded date

      WrongType for a non-numeric value, OutOfRange for an integer f64 cannot hold exactly, InvalidDate beyond the representable range. A float NaN is the epoch, as in the reference.

    • Creates a CborDate from a tag-1 CBOR value (the CborTagged protocol's instance form; returns a new instance).

      Parameters

      • cbor: Cbor

        Tagged CBOR value

      Returns CborDate

      The decoded date

      WrongType if the value is not tagged, WrongTag for a tag other than 1, or what fromUntaggedCbor throws for the content

    • Static method to create a CborDate from tagged CBOR.

      Parameters

      • cbor: Cbor

        Tagged CBOR value

      Returns CborDate

      New CborDate instance

    • The date in ISO-8601 format: only the date part when the time is exactly midnight (00:00:00), otherwise a date-time to the second with Z.

      Returns string

      String representation in ISO-8601 format

      // A date at midnight will display as just the date
      const date = CborDate.fromYmd(2023, 2, 8);
      // Returns "2023-02-08"
      console.log(date.toString());

      // A date with time will display as date and time
      const date2 = CborDate.fromYmdHms(2023, 2, 8, 15, 30, 45);
      // Returns "2023-02-08T15:30:45Z"
      console.log(date2.toString());

    • Compare two dates for equality: the same whole seconds and the same nanoseconds (chrono's PartialEq). A leap second 23:59:60 is a different instant from the following 00:00:00, although both encode to the same wire value.

      Parameters

      • other: CborDate

        Other CborDate to compare

      Returns boolean

      true if dates represent the same moment in time

    • Compare two dates: by whole seconds, then by nanoseconds (chrono's Ord, so a leap second sorts after :59.999999999 and before the next :00).

      Parameters

      • other: CborDate

        Other CborDate to compare

      Returns number

      -1 if this < other, 0 if equal, 1 if this > other

    • Convert to JSON (returns ISO 8601 string).

      Returns string

      ISO 8601 string

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods