piso

ISO 8601 date, duration, and interval parsing package as declared on Wikipedia ISO 8601.

In Spain, piso refers to the whole apartment, whereas in Mexico, it refers only to the floor of your departamento. But the above has nothing to do with this project.

Contents

• Api
  • parseInterval(iso8601Interval[, enforceUTC])
  • parseDuration(iso8601Duration)
  • getDate(iso8601Date[, enforceUTC])
  • getISOWeekString([date])
  • getUTCWeekNumber([date])
  • getUTCLastWeekOfYear(Y)
  • getUTCWeekOneDate(Y)

Api

parseInterval(iso8601Interval[, enforceUTC])

Parse interval from an ISO 8601 interval string.

• iso8601Interval: string with ISO 8601 interval source
• enforceUTC: optional boolean, enforce UTC if source lacks time zone offset

Returns ISOInterval.

Interval sources are bounded by their field limits: repetitions accept at most 17 digits, a maximal date — signed 17 digit year, 17 second fractions, and offset with seconds — is 60 characters, and a maximal duration is 129 characters. Consequently a valid interval never exceeds 209 characters.

import { parseInterval, ISOInterval } from '@0dep/piso';

const viableIntervals = [
  '2007-03-01/2007-04-01',
  'P2Y/2007-03-01T13:00:00Z',
  '2007-03-01T13:00:00Z/P2Y',
  'R5/P1Y/2025-05-01T13:00:00Z',
  'R-1/2009-07-01T00:00Z/P1M',
  'R-1/1972-07-01T00:02Z/PT1H3M',
  'R-1/P1M/2024-07-27T00:00Z',
  '2007-318/2007-319',
  '2007-318/319T24:00:00Z',
  '2026-09-01T10:00:00Z',
];

for (const i of viableIntervals) {
  console.log({ [i]: parseInterval(i).getExpireAt(), utc: parseInterval(i, true).getExpireAt() });
}

parseDuration(iso8601Duration)

Parse duration from an ISO 8601 duration string.

• iso8601Duration: string with ISO 8601 duration source

Returns ISODuration.

Each duration designator value accepts at most 17 digits, so a valid duration never exceeds 129 characters — more throws RangeError.

A leading minus (- or unicode minus −) as of ISO 8601-2:2019 negates the duration, e.g. -P1D, and is only accepted by parseDuration and ISODuration — not in intervals. The parsed result then has sign: -1, getExpireAt subtracts the duration and getStartAt adds it.

import { parseDuration } from '@0dep/piso';

const yesterday = parseDuration('-P1D');

console.log(yesterday.result.sign, yesterday.getExpireAt(new Date(Date.UTC(2024, 2, 1))).toISOString());

import { parseDuration } from '@0dep/piso';

const viableDurations = [
  'PT1M5S',
  'PT1M0.5S',
  'PT0.5S',
  'PT0.01S',
  'PT0.001S',
  'PT0.0001S',
  'PT0.5M',
  'PT0.5H',
  'PT1.5H',
  'P0.5D',
  'P1W',
  'P0.5W',
  'P0.5M',
  'P0.5D',
  'P1Y',
  'P1Y2M3W4DT5H6M7S',
  'PT0S',
  'P0D',
];

for (const d of viableDurations) {
  console.log({ [d]: parseDuration(d).getExpireAt() });
}

try {
  // fractions are only allowed on the smallest unit
  parseDuration('P0.5YT3S');
} catch (err) {
  console.log({ err });
}

getDate(iso8601Date[, enforceUTC])

Get Date from an ISO 8601 date time string.

• iso8601Date: string with ISO 8601 date source, date and number are also accepted
• enforceUTC: optional boolean, enforce UTC if source lacks time zone offset

Returns date.

import { getDate } from '@0dep/piso';

const viableDates = [
  '2024-01-27',
  '2024-02-28',
  '2024-02-29',
  '2020-02-29',
  '2016-02-29',
  '2024-W03-2',
  '2024-01',
  '2024-12',
  '20240127',
  '2024-012',
  '2024012',
  '2024-012T08:06:30',
  '2024-02-27T08:06:30',
  '2024-02-27T08:06:30.001',
  '2024-02-27T08:06:30.0011',
  '2024-02-27T08:06:30.0',
  '2024-02-27T08:06:30,001',
  '2024-02-27T08:06:30Z',
  '2024-02-03T08:06:30+02:00',
  '2024-02-03T08:06:30.5+02:00',
  '20240203T080630+0200',
  '2024-02-03T08:06:30-02:30',
  '2024-02-03T08:06:30-02',
  '2025-01-01T12:00:42.01-02:00',
  '2025-01-01T12:00:42.01+02:30',
  '2025-01-01T12:00:42.01+02:30:30',
  '2025-01-01T23:59',
  '2025-01-01T24:00',
  '2025-01-01T24:00:00',
  '2025-01-01T24:00:00.000',
  '2025-01-01T24:00Z',
  '2025-01-01T24:00+01',
  '2025-01-01T24:00:00+01',
  '2025-01-01T24:00:00.00+01',
  '20240127T1200',
  '20240127T120001',
  '20240127T120001,001',
  '2024',
  '+102024',
  '-00000012',
  new Date(2024, 3, 22),
  0,
  Date.UTC(2024, 3, 22),
];

for (const d of viableDates) {
  console.log({ [d]: getDate(d), utc: getDate(d, true) });
}

try {
  getDate('2023-02-29');
} catch (err) {
  console.log({ err });
}

try {
  // not this year
  getDate('2023-W53-1T12:00');
} catch (err) {
  console.log({ err });
}

try {
  // unbalanced separators
  getDate('2023-02-28T1200');
} catch (err) {
  console.log({ err });
}

NB! string without timezone precision is considered local date, or as Wikipedia put it "If no UTC relation information is given with a time representation, the time is assumed to be in local time". Unless, of course, enforce UTC instruction is used.

getUTCLastWeekOfYear(Y)

Get last week of year

• Y: full year

Returns 52 or 53.

import { getUTCLastWeekOfYear } from '@0dep/piso';

console.log('last week number', getUTCLastWeekOfYear(2024));

getUTCWeekOneDate(Y)

Get Monday week one date

• Y: full year

Returns date Monday week one

import { getUTCWeekOneDate } from '@0dep/piso';

console.log('Monday week one', getUTCWeekOneDate(2021));

getISOWeekString([date])

Get ISO week date string from date.

• date: optional date, defaults to now

import { getISOWeekString } from '@0dep/piso';

console.log('date as week', getISOWeekString(new Date(2021, 11, 28)));

getUTCWeekNumber([date])

Get weeknumber from date.

• date: optional date, defaults to now

Returns:

• Y: full year representation of week date
• W: week number
• weekday:

import { getUTCWeekNumber } from '@0dep/piso';

console.log(getUTCWeekNumber(new Date(2016, 0, 1)));

new ISOInterval(source[, enforceUTC])

Interval instance.

Constructor:

• source: ISO8601 interval source
• enforceUTC: optional boolean, enforce UTC if source lacks time zone offset

Properties:

• repeat: number of repeats
• start: start date as ISODate
• duration: duration as ISODuration
• end: end date as ISODate
• type: interval type
• get startDate: start date as date, requires parse() to be called
• get endDate: end date as date, requires parse() to be called

interval.type

Number representing the interval type flags. Available after parse.

• 1: Repeat
• 2: Start date
• 4: Duration
• 8: End date

Example flags

• 2: Start date only, a point in time where start and expire dates coincide
• 3: Repeat and start date, rather pointless but possible nevertheless
• 5: Repeat and duration
• 6: Start date and duration
• 7: Repeat, start date, and duration
• 10: Start- and end date
• 12: Duration and end date
• 13: Repeat, duration, and end date

Do I have repeat in my interval?

import { parseInterval } from '@0dep/piso';

console.log((parseInterval('R3/P1Y').type & 1) === 1 ? 'Yes' : 'No');
// Yes

console.log((parseInterval('R-1/P1Y').type & 1) === 1 ? 'Yes' : 'No');
// Yes, indefinite number of repetititions

console.log((parseInterval('R-1/2024-03-27/P1Y').type & 1) === 1 ? 'Yes' : 'No');
// Yes, indefinite number of repetititions from start date

console.log((parseInterval('R-1/P1Y/2024-03-27').type & 1) === 1 ? 'Yes' : 'No');
// Yes, indefinite number of repetititions until end date

console.log((parseInterval('R0/P1Y').type & 1) === 1 ? 'Yes' : 'No');
// No, zero is equal to once

console.log((parseInterval('R1/P1Y').type & 1) === 1 ? 'Yes' : 'No');
// No, since it's just once

console.log((parseInterval('R1/2024-03-28').type & 1) === 1 ? 'Yes' : 'No');
// No, pointless repeat

console.log((parseInterval('R1/2024-03-28/31').type & 1) === 1 ? 'Yes' : 'No');
// No, pointless repeat

console.log((parseInterval('R1/P1Y/2024-03-28').type & 1) === 1 ? 'Yes' : 'No');
// No

Is start date defined in my interval?

import { parseInterval } from '@0dep/piso';

const interval = parseInterval('R-1/2024-03-28/P1Y');

console.log((interval.type | 2) === interval.type ? 'Yes' : 'No');

Start date only

An interval consisting of only a start date is a point in time, start and expire dates are the same.

import { parseInterval } from '@0dep/piso';

const interval = parseInterval('2026-09-01T10:00:00Z');

console.log(interval.type);
// 2

console.log(interval.getStartAt().toISOString());
// 2026-09-01T10:00:00.000Z

console.log(interval.getExpireAt().toISOString());
// 2026-09-01T10:00:00.000Z

interval.parse()

Returns ISOInterval.

Throws RangeError if something is off.

interval.toJSON()

Get interval represented as JavaScript Object Notation.

import { ISOInterval } from '@0dep/piso';

console.log(JSON.stringify({ interval: new ISOInterval('R2/P1Y/2024-03-28') }, null, 2));

new ISODate(source[, options])

ISO date instance.

Constructor:

• source: ISO 8601 date source string
• options: optional parsing options
  • offset: source string offset column number, -1 is default
  • endChars: string with optional characters that mark the end of the ISO date, e.g. /
  • enforceSeparators: boolean that will require time part separators such as - and :
  • enforceUTC: optional boolean, enforce UTC if source lacks time zone offset

Properties:

• result:
  • Y: full year
  • M: javascript month
  • D: date or ordinal day
  • H: hours
  • m: minutes
  • S: seconds
  • F: milliseconds, including fractional milliseconds when the source has more than 3 fraction digits; at most 17 fraction digits are accepted, more throws RangeError
  • Z: Z, +, −, or -
  • OH: offset hours
  • Om: offset minutes
  • OS: offset seconds
  • isValid: boolean indicating if parse was successful

date.parse()

date.parsePartialDate(Y, M, D, W)

Parse partial date as compared to passed date part arguments.

• Y: required full year
• M: optional javascript month, required is not ordinal day
• D: required date, weekday (1 = Monday .. 7 = Sunday) if W is passed, or ordinal day
• W: optional week number, then D is the week day

Returns ISODate

date.toDate([enforceUTC])

Get Date represented by source.

• enforceUTC: optional boolean, enforce UTC if source lacks time zone offset

date.toJSON()

Get Date represented as JavaScript Object Notation.

new ISODuration(source[, offset])

Duration instance.

Constructor:

• source: duration source string
• offset: optional source string offset column number

Properties:

• result:
  • Y: years
  • M: months
  • W: weeks
  • D: days
  • H: hours
  • m: minutes
  • S: seconds

duration.toMilliseconds([startDate])

Get duration in milliseconds from optional start date.

duration.untilMilliseconds([endDate])

Get duration in milliseconds until optional end date.

Example

An example to get start and end date:

import { parseInterval } from '@0dep/piso';

const source = '2007-03-01T13:00:00Z/P1Y2M10DT2H30M';

const interval = parseInterval(source);

console.log('starts at', interval.getStartAt());
console.log('expires at', interval.getExpireAt());
console.log('duration milliseconds', interval.duration.toMilliseconds());

An example to get duration milliseconds:

import { parseDuration } from '@0dep/piso';

const duration = parseDuration('PT2H30M');

console.log('duration millisecods', duration.toMilliseconds(new Date()));

Repetitions

With end date

R4/P2Y/2007-08-01

| Repetition | start at | expire at | | ---------: | ---------- | ---------- | | 4 | 1999-08-01 | 2001-08-01 | | 3 | 2001-08-01 | 2003-08-01 | | 2 | 2003-08-01 | 2005-08-01 | | 1 | 2005-08-01 | 2007-08-01 |

Benchmarking

How piso stacks up against the RegExp-based implementations depends on the capability, so speed and functionality are compared per capability below.

Benchmarks and functionality comparison against luxon, iso8601-duration, temporal, and native Date live in the bench workspace. npm run bench measures parse throughput as well as parse-and-apply throughput — duration to expire at and milliseconds, interval to expire at and start at — and npm run compare executes each capability below against every library and prints ✓/✗ tables from actual behavior:

npm install
npm run bench
npm run compare

Interval

Parses intervals 6–11 times faster than luxon, depending on the interval form.

| Capability | piso | luxon | | ------------------ | ---- | ----- | | start/end | ✓ | ✓ | | start/duration | ✓ | ✓ | | duration/end | ✓ | ✓ | | Repeating interval | ✓ | ❌ | | Start date only | ✓ | ❌ | | Relative end date | ✓ | ❌* |

* 2007-11-13/15 parses but the relative end resolves to a time of day instead of a date

Duration

Parses durations 1.1–2.3 times faster than luxon and iso8601-duration, and 1.9–4.3 times faster than temporal.

| Capability | piso | iso8601-duration | luxon | temporal | | --------------------------------- | ---- | ---------------- | ----- | --------------------------------------------------------------- | | Fractional time designator | ✓ | ✓ | ✓ | ✓ | | Invalid if more than one fraction | ✓ | ✓ | ❌ | ✓ | | Year designator | ✓ | ✓ | ✓ | ❌ | | Fractional date designator | ✓ | ❌ | ✓ | ❌ | | Comma as fraction separator | ✓ | ✓ | ❌ | ✓ | | Repeated duration instruction | ✓ | ❌* | ❌ | ❌ | | Negative duration instruction | ✓ | ❌* | ✓ | ✓ |

* parses but the instruction is ignored

Applying durations and intervals

Parsing is only half the job, so bench/suites/apply.js measures the outcome: parse a duration and get its expire at date or milliseconds, parse an interval and get its expire at or start at date. Every library is verified to produce the same result before timing.

| Outcome | piso vs luxon | piso vs temporal | piso vs iso8601-duration | | --------------------------------------------- | ------------- | ---------------- | ------------------------ | | Duration P1Y2M10DT2H30M expire at from date | 2.9× | 7× | n/a* | | Negative duration -P1D expire at from date | 7.7× | 18× | n/a* | | Duration PT2H30M milliseconds | 1.4× | 11× | 5.7× | | Interval start/duration expire at | 4.3× | n/a | n/a | | Interval duration/end start at | 4.5× | n/a | n/a | | Interval start/end expire at | 6× | n/a | n/a |

* iso8601-duration end() applies the duration in local time so it is not comparable with the UTC results of the others.

Date

Parses dates 6–7 times faster than luxon and 2–4 times faster than temporal. Native new Date('2024-03-26') is, of course, still faster — about 3 times in the benchmark. On the other hand new Date('2024-03-26') resolves to UTC while new Date(2024, 2, 26) does not. Not sure what to expect but IMHO new Date('2024-03-26') should be a local date.

| Capability | piso | luxon | temporal | node 20 | | --------------------------- | ------ | ----- | -------- | ------- | | The 24:th hour | ✓ | ✓ | ❌ | ✓ | | Year +10000 | ✓ | ✓ | ✓ | ✓ | | Year 9999 | ✓ | ✓ | ✓ | ✓ | | Year only (YYYY) | ✓ | ✓ | ❌ | ✓ | | BC dates | ✓ | ✓ | ✓ | ✓ | | Week | ✓ | ✓ | ❌ | ❌ | | Ordinal date | ✓ | ✓ | ❌ | ❌ | | Without separators | ✓ | ✓ | ✓ | ❌ | | Without offset minutes | ✓ | ✓ | ✓ | ❌ | | Comma as fraction separator | ✓ | ✓ | ✓ | ❌ | | Throw on invalid leap year | ✓ | ✓ | ✓ | ❌* | | Offset unicode minus (−) | ✓ | ❌ | ❌ | ❌ | | Offset seconds | ✓ | ❌ | ✓ | ❌ | | 36 fractions of a second | ❌** | ❌ | ❌ | ✓ |

* node is benevolent when parsing 2100-02-29 as 2100-03-01 ** piso accepts at most 17 fraction digits, more throws RangeError