DOCSEARCHbyAlgolia
Submit Docs

iso-fns Documentation

website·Indexed 32 days ago

https://iso-fns.org

A multi-domain, immutable, and functional DateTime package for JavaScript. It provides a comprehensive API for handling date and time operations through classes such as Iso.Date, Iso.Time, Iso.DateTime, Iso.ZonedDateTime, Iso.Instant, Iso.Duration, Iso.YearMonth, and Iso.MonthDay.

Tokens
13.6K
Snippets
93
Records
137
Agent score
54%

What's inside iso-fns

  1. Overview of iso-fns date and time domains

    iso-fns is a multi-domain, immutable, and functional DateTime package for JavaScript that mirrors the design of the Temporal Proposal. It represents date/time types as ISO8601 formatted strings, ensuring they are portable, JSON-compatible, and immutable. The library supports eight distinct domains:

    1. Instant: A fixed point in time (UTC), e.g., 1969-07-20T20:17:00Z.
    2. ZonedDateTime: A timezone-aware date/time representing a real event in a specific region, e.g., 1995-12-07T03:24:00-08:00[America/Los_Angeles].
    3. DateTime: A calendar date and wall-clock time without timezone information.
    4. Date: A calendar date without time or timezone.
    5. Time: A wall-clock time without date or timezone.
    6. YearMonth: A date without a day component (e.g., for monthly meetings).
    7. MonthDay: A date without a year component (e.g., for annual holidays).
    8. Duration: A length of time used for arithmetic and measuring differences.

  2. Overview of Iso.ZonedDateTime

    Iso.ZonedDateTime is a timezone-aware date/time type representing a specific instant from a regional perspective. It is a combination of Iso.TimeZone, Iso.Instant, and Iso.DateTime. Key features include:

    • Automatic DST adjustment based on RFC 5545.
    • Ability to create derived values without invalidating the result due to DST rules.
    • Support for measuring attributes like 'length of day' which vary by region.
    • Lossless conversion to other Iso types (except Iso.Duration).
    • Alphabetically sortable string representation containing the date/time, offset, and time zone.

  3. Overview of Iso.Time

    An Iso.Time represents a wall-clock time without any time zone. It is used for times expressed in everyday usage (e.g., a daily event that happens at the same time regardless of the time zone).

    Key characteristics:

    • It has no associated calendar date (use Iso.DateTime for specific dates).
    • Accessors and arithmetic operate at millisecond precision.
    • String representations preserve fractional-second precision (including sub-millisecond).
    • It can be converted to Iso.ZonedDateTime by combining it with Iso.Date and Iso.TimeZone via toZonedDateTime(), or to a zoneless Iso.DateTime via toDateTime() when combined with Iso.Date.

  4. Overview of Iso.Date

    An Iso.Date represents a calendar date as expressed in everyday usage, independent of any time zone. It refers to the whole of a specific day. To refer to a specific time on that day, use Iso.DateTime. An Iso.Date can be converted to an Iso.ZonedDateTime by combining it with an Iso.Time and Iso.TimeZone via toZonedDateTime(), or to a zoneless Iso.DateTime using toDateTime().

  5. Understand time representations in iso-fns

    iso-fns distinguishes between two primary types of time:

    1. Exact Time (UTC Time): A consistent global time standard, independent of local governmental changes or Daylight Saving Time (DST). It is represented by the Iso.Instant type (exact time only) or Iso.ZonedDateTime (exact time plus a time zone).
    2. Wall-Clock Time (Local Time): The time shown on a local clock, which depends on the time zone and can change abruptly due to DST or political decisions. It is represented by Iso.DateTime and narrower types like Iso.Date, Iso.Time, Iso.YearMonth, and Iso.MonthDay using the ISO 8601 calendar.

  6. Understand Iso.Instant behavior and representation

    An Iso.Instant represents a single point in time (exact time) and does not contain time zone information. Consequently, it has no concept of days, months, or hours.

    Key characteristics:

    • Representation: Represented as an ISO8601 string in Zulu time (UTC), e.g., 1970-01-01T00:00:00.000Z.
    • Precision: Accessors and arithmetic operate at millisecond precision, but the string representation preserves the fractional-second precision of the parsed input.
    • Leap Seconds: Like Unix time, Iso.Instant ignores leap seconds.
    • Interoperability: Legacy JavaScript Date instances can be converted to Iso.Instant using the toISOString() method.
    • Conversion: To convert an Iso.Instant into an Iso.DateTime, an Iso.TimeZone is required.

  7. Understand why iso-fns uses strings for date operations

    iso-fns uses strings instead of Date objects to avoid the issues associated with JSON deserialization in JavaScript. Because JSON only supports three primitive types (String, Number, Boolean) and two structural types (Object, Array), JavaScript cannot automatically transform serialized date strings back into Date objects during deserialization. To avoid unreliable hacks that rely on string format detection, iso-fns adopts a functional approach where date operations are performed on strings, ensuring data consistency across API boundaries.

  8. Core design principles of iso-fns

    iso-fns is built on three primary architectural pillars:

    1. Multi-Domain Support: Provides a comprehensive set of types for different date and time needs, including Date, Time, and ZonedDateTime.
    2. Immutability: Avoids mutable state to make code easier to read, write, and debug.
    3. Functional Approach: Utilizes pure functions without internal state to ensure consistent and predictable behavior across the library.

  9. Understand the Iso.DateTime type

    Iso.DateTime represents a calendar date and wall-clock time without a time zone. It is used for scenarios where the time zone is stored separately, for UI components like date pickers, or for events that occur at the same local time across different zones.

    Key characteristics:

    • Accessors and arithmetic operate at millisecond precision.
    • String representations preserve the fractional-second precision parsed from the source.
    • It does not represent an exact point in time; for that, use Iso.ZonedDateTime or Iso.Instant.
    • It can be converted to Iso.ZonedDateTime using an Iso.TimeZone.

  10. Understand ISO 8601 Duration notation

    An Iso.Duration is represented as a string following the ISO 8601 notation. It starts with a P (period), followed by date components (years, months, weeks, days), and a T (time) separator before time components (hours, minutes, seconds).

    Examples:

    • P1Y1M1DT1H1M1.1S: 1 year, 1 month, 1 day, 1 hour, 1 minute, 1 second, and 100ms
    • P40D: 40 days
    • PT2H30M: 2.5 hours
    • PT0.021S: 21 milliseconds

    Note: While ISO 8601-1 restricts weeks from appearing with other units and requires positive durations, ISO 8601-2 extensions allow sign characters (e.g., -P1M) and combining weeks with other units (e.g., P3W1D).

  11. Perform date and time operations using functional patterns

    iso-fns uses a functional approach where each operation is a function that takes an ISO8601 formatted string as input and returns a new ISO8601 string. This ensures immutability and follows a pattern similar to date-fns.
    // Subtract 20 days from a date string
dateFns.subtract('2000-01-15', {days: 20}) // '1999-12-26'

// Create an instant from epoch and subtract time
const instant1 = instantFns.fromEpochMilliseconds(0) // '1970-01-01T00:00:00.000Z'
const instant2 = instantFns.subtract(instant1, {hours: 3, minutes: 30}) // '1969-12-31T20:30:00.000Z'

// Convert instant to ZonedDateTime
const zDateTime1 = instantFns.toZonedDateTime(instant2, 'America/Chicago') // '1969-12-31T14:30:00.000-06:00[America/Chicago]'

  12. Convert local wall-clock time to exact time

    Local time types (Date, Time, DateTime) can be converted to an exact time type (Iso.ZonedDateTime) by providing an IANA time zone ID. Once converted to a ZonedDateTime, you can extract the exact time as an Iso.Instant or as Unix epoch milliseconds/seconds.
    // Convert a date string to ZonedDateTime (defaults to start of day)
const date = '2019-12-17';
const zdt1 = dateFns.toZonedDateTime(date, 'Asia/Tokyo');
// => 2019-12-17T00:00:00.000+09:00[Asia/Tokyo]

// Convert date and specific time to ZonedDateTime
const zdt2 = dateFns.toZonedDateTime(date, { timeZone: 'Asia/Tokyo', time: '10:00' });
// => 2019-12-17T10:00:00.000+09:00[Asia/Tokyo]

// Convert a time string and specific date to ZonedDateTime
const time = '14:35:00.000';
const zdt3 = timeFns.toZonedDateTime(time, { timeZone: 'Asia/Tokyo', date: '2020-08-27' });
// => 2020-08-27T14:35:00.000+09:00[Asia/Tokyo]

// Convert a dateTime string to ZonedDateTime
const dateTime = '2019-12-17T07:48:00.000';
const zdt4 = dateTimeFns.toZonedDateTime(dateTime, 'Asia/Tokyo');
// => 2019-12-17T07:48:00.000+09:00[Asia/Tokyo]

// Extract exact time from ZonedDateTime
const inst = zonedDateTimeFns.toInstant(zdt4);
const epochMilli = instantFns.getEpochMilliseconds(inst); // => 1576536480000
const epochSecs = instantFns.getEpochSeconds(inst); // => 1576536480