@antongolub/iso8601

ISO 8601

Strict ISO8601 datetime parser

Yet another one date parser?

It's 20** and if you operate with dates, you should take one of these:

• momentjs
• date-fns

But if you need only iso strings and bundle size matters, try out this lib.

Install

npm add @antongolub/iso8601
yarn add @antongolub/iso8601

Usage

    import parser from '@antongolub/iso8601'

    const date1 = parser('2004002T10,26')  // YYYYWwwDThh,hh → new Date(2004, 0, 2, 10, 15, 36, 0)
    
    // 4.3.3 Representations other than complete
    // For reduced accuracy, decimal or expanded representations of date and time of day,
    // any of the representations in 4.1.2 (calendar dates), 4.1.3 (ordinal dates) 
    // or 4.1.4 (week dates) followed immediately by the time designator [T] 
    // may be combined with any of the representations in 4.2.2.2 through 4.2.2.4 (local time),
    // 4.2.4 (UTC of day) or 4.2.5.2 (local time and the difference from UTC) provided that
    
    const date2 = parser('2015-W02-4')    // YYYYWWWD (4.1.4 Week date) → new Date(2015, 0, 8)
    const date3 = parser('19')            // YY (century) → new Date(1900, 0)
    const date4 = parser('1969-12-31T12:00:00-12:00')  // Full dataTime → new Date(0)

API

parser (value: string, group?: string | string[], date?: Date | number | string): Date | void

• value — ISO string
• group — optional pattern group name to specify parsing case. For example, 1900 matches to hhmm (4.2.2.3 p. a) and YYYY (4.1.2.3 p. b) and requires clarification. Supported values: date, time / localtime, datetime and all
• date — optional date reference to resolve local time values. Defaults to Date.now()

    const date5 = parser('12:00') // 2019-09-03T09:00:00.000Z based on Date.now() for Moscow TZ (+03:00)
    const date6 = parser('12:00', 'localtime', new Date(Date.UTC(2010, 0, 1))) // 2000-01-01T09:00:00.000Z