BC-DCBOR TypeScript Library - v1.0.0-alpha.13
    Preparing search index...

    Class CborDate

    A CBOR-friendly representation of a date and time.

    The CborDate type provides a wrapper around JavaScript's native Date that supports encoding and decoding to/from CBOR with tag 1, following the CBOR date/time standard specified in RFC 8949.

    When encoded to CBOR, dates are represented as tag 1 followed by a numeric value representing the number of seconds since (or before) the Unix epoch (1970-01-01T00:00:00Z). The numeric value can be a positive or negative integer, or a floating-point value for dates with fractional seconds.

    Features

    • Supports UTC dates with optional fractional seconds
    • Provides convenient constructors for common date creation patterns
    • Implements the CborTagged, CborTaggedEncodable, and CborTaggedDecodable interfaces
    • Supports arithmetic operations with durations and between dates
    import { CborDate } from './date';

    // Create a date from a timestamp (seconds since Unix epoch)
    const date = CborDate.fromTimestamp(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

    Methods

    fromDatetime fromYmd fromYmdHms fromTimestamp fromString now withDurationFromNow datetime timestamp add subtract difference cborTags untaggedCbor taggedCbor fromUntaggedCbor fromTaggedCbor fromTaggedCbor fromUntaggedCbor toString equals compare toJSON

    Methods

    • Creates a new CborDate from the given JavaScript Date.

      This method creates a new CborDate instance by wrapping a JavaScript Date.

      Parameters

      • dateTime: Date

        A Date instance to wrap

      Returns CborDate

      A new CborDate instance

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

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

      This method creates a new CborDate with the time set to 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);

      Error if the provided components do not form a valid date.

    • 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);

      Error if the provided components do not form a valid date and time.

    • Creates a new CborDate from seconds since (or before) the Unix epoch.

      This method creates a new CborDate representing the specified number of seconds since the Unix epoch (1970-01-01T00:00:00Z). Negative values represent times before the epoch.

      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

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

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

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

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

      This method parses a string representation of a date or date-time in ISO-8601/RFC-3339 format and creates a new CborDate instance. It supports both full date-time strings (e.g., "2023-02-08T15:30:45Z") and date-only strings (e.g., "2023-02-08").

      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

      Error if the string cannot be parsed as a valid date or date-time

      // 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 the underlying JavaScript Date object.

      This method provides access to the wrapped JavaScript Date instance.

      Returns Date

      The wrapped Date instance

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

    • Returns the CborDate as the number of seconds since the Unix epoch.

      This method converts the date to a floating-point number representing the number of seconds since the Unix epoch (1970-01-01T00:00:00Z). Negative values represent times before the epoch. The fractional part represents sub-second precision.

      Returns number

      Seconds since the Unix epoch as a number

      const date = CborDate.fromYmd(2023, 2, 8);
      const timestamp = date.timestamp();

    • 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)

    • Implementation of the CborTagged interface for CborDate.

      This implementation specifies that CborDate values are tagged with CBOR tag 1, which is the standard CBOR tag for date/time values represented as seconds since the Unix epoch per RFC 8949.

      Returns Tag[]

      A vector containing tag 1

    • Implementation of the CborTaggedEncodable interface for CborDate.

      Converts this CborDate to an untagged CBOR value.

      The date is converted to a numeric value representing the number of seconds since the Unix epoch. This value 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

    • Implementation of the CborTaggedDecodable interface for CborDate.

      Creates a CborDate from an untagged CBOR value.

      The CBOR value must be a numeric value (integer or floating-point) representing the number of seconds since the Unix epoch.

      Parameters

      • cbor: Cbor

        The untagged CBOR value

      Returns CborDate

      This CborDate instance (mutated)

      Error if the CBOR value is not a valid timestamp

    • Static method to create a CborDate from tagged CBOR.

      Parameters

      • cbor: Cbor

        Tagged CBOR value

      Returns CborDate

      New CborDate instance

    • Static method to create a CborDate from untagged CBOR.

      Parameters

      • cbor: Cbor

        Untagged CBOR value

      Returns CborDate

      New CborDate instance

    • Implementation of the toString method for CborDate.

      This implementation provides a string representation of a CborDate in ISO-8601 format. For dates with time exactly at midnight (00:00:00), only the date part is shown. For other times, a full date-time string is shown.

      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:45.000Z"
      console.log(date2.toString());

    • Compare two dates for equality.

      Parameters

      • other: CborDate

        Other CborDate to compare

      Returns boolean

      true if dates represent the same moment in time

    • Compare two dates.

      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

    Features
    Methods