{"id":48502220,"url":"https://github.com/zerodep/piso","last_synced_at":"2026-04-07T15:02:39.449Z","repository":{"id":229782058,"uuid":"744850432","full_name":"zerodep/piso","owner":"zerodep","description":"ISO 8601 date, duration, and interval parser","archived":false,"fork":false,"pushed_at":"2026-01-20T05:23:22.000Z","size":159,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-20T13:36:01.603Z","etag":null,"topics":["date","duration","interval","iso8601","isomorphic","javascript","parser"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zerodep.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-18T06:07:59.000Z","updated_at":"2026-01-20T05:23:27.000Z","dependencies_parsed_at":"2024-03-26T08:32:16.783Z","dependency_job_id":"8c806a0b-46c2-4e8e-9a54-d674fa8beaab","html_url":"https://github.com/zerodep/piso","commit_stats":null,"previous_names":["zerodep/piso"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/zerodep/piso","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodep%2Fpiso","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodep%2Fpiso/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodep%2Fpiso/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodep%2Fpiso/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zerodep","download_url":"https://codeload.github.com/zerodep/piso/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodep%2Fpiso/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31516839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["date","duration","interval","iso8601","isomorphic","javascript","parser"],"created_at":"2026-04-07T15:02:38.108Z","updated_at":"2026-04-07T15:02:39.440Z","avatar_url":"https://github.com/zerodep.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# piso\n\n[![Build](https://github.com/zerodep/piso/actions/workflows/build.yaml/badge.svg)](https://github.com/zerodep/piso/actions/workflows/build.yaml)[![Coverage Status](https://coveralls.io/repos/github/zerodep/piso/badge.svg?branch=main)](https://coveralls.io/github/zerodep/piso?branch=main)\n\nISO 8601 date, duration, and interval parsing package as declared on [Wikipedia ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).\n\n\u003e In Spain, piso refers to the whole apartment, whereas in Mexico, it refers only to the floor of your departamento.\n\u003e But the above has nothing to do with this project.\n\n## Contents\n\n- [Api](#api)\n  - [`parseInterval(iso8601Interval[, enforceUTC])`](#parseintervaliso8601interval-enforceutc)\n  - [`parseDuration(iso8601Duration)`](#parsedurationiso8601duration)\n  - [`getDate(iso8601Date[, enforceUTC])`](#getdateiso8601date-enforceutc)\n  - [`getISOWeekString([date])`](#getisoweekstringdate)\n  - [`getUTCWeekNumber([date])`](#getutcweeknumberdate)\n  - [`getUTCLastWeekOfYear(Y)`](#getutclastweekofyeary)\n  - [`getUTCWeekOneDate(Y)`](#getutcweekonedatey)\n\n## Api\n\n### `parseInterval(iso8601Interval[, enforceUTC])`\n\nParse interval from an ISO 8601 interval string.\n\n- `iso8601Interval`: string with ISO 8601 interval source\n- `enforceUTC`: optional boolean, enforce UTC if source lacks time zone offset\n\nReturns [ISOInterval](#new-isointervalsource-enforceutc).\n\n```javascript\nimport { parseInterval, ISOInterval } from '@0dep/piso';\n\nconst viableIntervals = [\n  '2007-03-01/2007-04-01',\n  'P2Y/2007-03-01T13:00:00Z',\n  '2007-03-01T13:00:00Z/P2Y',\n  'R5/P1Y/2025-05-01T13:00:00Z',\n  'R-1/2009-07-01T00:00Z/P1M',\n  'R-1/1972-07-01T00:02Z/PT1H3M',\n  'R-1/P1M/2024-07-27T00:00Z',\n  '2007-318/2007-319',\n  '2007-318/319T24:00:00Z',\n];\n\nfor (const i of viableIntervals) {\n  console.log({ [i]: parseInterval(i).getExpireAt(), utc: parseInterval(i, true).getExpireAt() });\n}\n```\n\n### `parseDuration(iso8601Duration)`\n\nParse duration from an ISO 8601 duration string.\n\n- `iso8601Duration`: string with ISO 8601 duration source\n\nReturns [ISODuration](#new-isodurationsource-offset).\n\n```javascript\nimport { parseDuration } from '@0dep/piso';\n\nconst viableDurations = [\n  'PT1M5S',\n  'PT1M0.5S',\n  'PT0.5S',\n  'PT0.01S',\n  'PT0.001S',\n  'PT0.0001S',\n  'PT0.5M',\n  'PT0.5H',\n  'PT1.5H',\n  'P0.5D',\n  'P1W',\n  'P0.5W',\n  'P0.5M',\n  'P0.5D',\n  'P1Y',\n  'P1Y2M3W4DT5H6M7S',\n  'PT0S',\n  'P0D',\n];\n\nfor (const d of viableDurations) {\n  console.log({ [d]: parseDuration(d).getExpireAt() });\n}\n\ntry {\n  // fractions are only allowed on the smallest unit\n  parseDuration('P0.5YT3S');\n} catch (err) {\n  console.log({ err });\n}\n```\n\n### `getDate(iso8601Date[, enforceUTC])`\n\nGet Date from an ISO 8601 date time string.\n\n- `iso8601Date`: string with ISO 8601 date source, date and number are also accepted\n- `enforceUTC`: optional boolean, enforce UTC if source lacks time zone offset\n\nReturns date.\n\n```javascript\nimport { getDate } from '@0dep/piso';\n\nconst viableDates = [\n  '2024-01-27',\n  '2024-02-28',\n  '2024-02-29',\n  '2020-02-29',\n  '2016-02-29',\n  '2024-W03-2',\n  '2024-01',\n  '2024-12',\n  '20240127',\n  '2024-012',\n  '2024012',\n  '2024-012T08:06:30',\n  '2024-02-27T08:06:30',\n  '2024-02-27T08:06:30.001',\n  '2024-02-27T08:06:30.0011',\n  '2024-02-27T08:06:30.0',\n  '2024-02-27T08:06:30,001',\n  '2024-02-27T08:06:30Z',\n  '2024-02-03T08:06:30+02:00',\n  '2024-02-03T08:06:30.5+02:00',\n  '20240203T080630+0200',\n  '2024-02-03T08:06:30-02:30',\n  '2024-02-03T08:06:30-02',\n  '2025-01-01T12:00:42.01-02:00',\n  '2025-01-01T12:00:42.01+02:30',\n  '2025-01-01T12:00:42.01+02:30:30',\n  '2025-01-01T23:59',\n  '2025-01-01T24:00',\n  '2025-01-01T24:00:00',\n  '2025-01-01T24:00:00.000',\n  '2025-01-01T24:00Z',\n  '2025-01-01T24:00+01',\n  '2025-01-01T24:00:00+01',\n  '2025-01-01T24:00:00.00+01',\n  '20240127T1200',\n  '20240127T120001',\n  '20240127T120001,001',\n  new Date(2024, 3, 22),\n  0,\n  Date.UTC(2024, 3, 22),\n];\n\nfor (const d of viableDates) {\n  console.log({ [d]: getDate(d), utc: getDate(d, true) });\n}\n\ntry {\n  getDate('2023-02-29');\n} catch (err) {\n  console.log({ err });\n}\n\ntry {\n  // not this year\n  getDate('2023-W53-1T12:00');\n} catch (err) {\n  console.log({ err });\n}\n\ntry {\n  // unbalanced separators\n  getDate('2023-02-28T1200');\n} catch (err) {\n  console.log({ err });\n}\n```\n\n\u003e 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.\n\n### `getUTCLastWeekOfYear(Y)`\n\nGet last week of year\n\n- `Y`: full year\n\nReturns 52 or 53.\n\n```javascript\nimport { getUTCLastWeekOfYear } from '@0dep/piso';\n\nconsole.log('last week number', getUTCLastWeekOfYear(2024));\n```\n\n### `getUTCWeekOneDate(Y)`\n\nGet Monday week one date\n\n- `Y`: full year\n\nReturns date Monday week one\n\n```javascript\nimport { getUTCWeekOneDate } from '@0dep/piso';\n\nconsole.log('Monday week one', getUTCWeekOneDate(2021));\n```\n\n### `getISOWeekString([date])`\n\nGet ISO week date string from date.\n\n- `date`: optional date, defaults to now\n\n```javascript\nimport { getISOWeekString } from '@0dep/piso';\n\nconsole.log('date as week', getISOWeekString(new Date(2021, 11, 28)));\n```\n\n### `getUTCWeekNumber([date])`\n\nGet weeknumber from date.\n\n- `date`: optional date, defaults to now\n\nReturns:\n\n- `Y`: full year representation of week date\n- `W`: week number\n- `weekday`:\n\n```javascript\nimport { getUTCWeekNumber } from '@0dep/piso';\n\nconsole.log(getUTCWeekNumber(new Date(2016, 0, 1)));\n```\n\n## `new ISOInterval(source[, enforceUTC])`\n\nInterval instance.\n\n**Constructor:**\n\n- `source`: ISO8601 interval source\n- `enforceUTC`: optional boolean, enforce UTC if source lacks time zone offset\n\n**Properties:**\n\n- `repeat`: number of repeats\n- `start`: start date as [ISODate](#new-isodatesource-options)\n- `duration`: duration as [ISODuration](#new-isodurationsource-offset)\n- `end`: end date as [ISODate](#new-isodatesource-options)\n- `type`: [interval type](#intervaltype)\n- `get startDate`: start date as date, requires [parse()](#intervalparse) to be called\n- `get endDate`: end date as date, requires [parse()](#intervalparse) to be called\n\n### `interval.type`\n\nNumber representing the interval type flags. Available after [parse](#intervalparse).\n\n- `1`: Repeat\n- `2`: Start date\n- `4`: Duration\n- `8`: End date\n\n**Example flags**\n\n- `3`: Repeat and start date, rather pointless but possible nevertheless\n- `5`: Repeat and duration\n- `6`: Start date and duration\n- `7`: Repeat, start date, and duration\n- `10`: Start- and end date\n- `12`: Duration and end date\n- `13`: Repeat, duration, and end date\n\n\u003e Do I have repeat in my interval?\n\n```javascript\nimport { parseInterval } from '@0dep/piso';\n\nconsole.log((parseInterval('R3/P1Y').type \u0026 1) === 1 ? 'Yes' : 'No');\n// Yes\n\nconsole.log((parseInterval('R-1/P1Y').type \u0026 1) === 1 ? 'Yes' : 'No');\n// Yes, indefinite number of repetititions\n\nconsole.log((parseInterval('R-1/2024-03-27/P1Y').type \u0026 1) === 1 ? 'Yes' : 'No');\n// Yes, indefinite number of repetititions from start date\n\nconsole.log((parseInterval('R-1/P1Y/2024-03-27').type \u0026 1) === 1 ? 'Yes' : 'No');\n// Yes, indefinite number of repetititions until end date\n\nconsole.log((parseInterval('R0/P1Y').type \u0026 1) === 1 ? 'Yes' : 'No');\n// No, zero is equal to once\n\nconsole.log((parseInterval('R1/P1Y').type \u0026 1) === 1 ? 'Yes' : 'No');\n// No, since it's just once\n\nconsole.log((parseInterval('R1/2024-03-28').type \u0026 1) === 1 ? 'Yes' : 'No');\n// No, pointless repeat\n\nconsole.log((parseInterval('R1/2024-03-28/31').type \u0026 1) === 1 ? 'Yes' : 'No');\n// No, pointless repeat\n\nconsole.log((parseInterval('R1/P1Y/2024-03-28').type \u0026 1) === 1 ? 'Yes' : 'No');\n// No\n```\n\n\u003e Is start date defined in my interval?\n\n```javascript\nimport { parseInterval } from '@0dep/piso';\n\nconst interval = parseInterval('R-1/2024-03-28/P1Y');\n\nconsole.log((interval.type | 2) === interval.type ? 'Yes' : 'No');\n```\n\n### `interval.parse()`\n\nReturns [ISOInterval](#new-isointervalsource-enforceutc).\n\nThrows `RangeError` if something is off.\n\n### `interval.toJSON()`\n\nGet interval represented as JavaScript Object Notation.\n\n```javascript\nimport { ISOInterval } from '@0dep/piso';\n\nconsole.log(JSON.stringify({ interval: new ISOInterval('R2/P1Y/2024-03-28') }, null, 2));\n```\n\n## `new ISODate(source[, options])`\n\nISO date instance.\n\n**Constructor**:\n\n- `source`: ISO 8601 date source string\n- `options`: optional parsing options\n  - `offset`: source string offset column number, -1 is default\n  - `endChars`: string with optional characters that mark the end of the ISO date, e.g. `/`\n  - `enforceSeparators`: boolean that will require time part separators such as `-` and `:`\n  - `enforceUTC`: optional boolean, enforce UTC if source lacks time zone offset\n\n**Properties:**\n\n- `result`:\n  - `Y`: full year\n  - `M`: javascript month\n  - `D`: date or ordinal day\n  - `H`: hours\n  - `m`: minutes\n  - `S`: seconds\n  - `F`: milliseconds\n  - `Z`: Z, +, −, or -\n  - `OH`: offset hours\n  - `Om`: offset minutes\n  - `OS`: offset seconds\n  - `isValid`: boolean indicating if parse was successful\n\n### `date.parse()`\n\n### `date.parsePartialDate(Y, M, D, W)`\n\nParse partial date as compared to passed date part arguments.\n\n- `Y`: required full year\n- `M`: optional javascript month, required is not ordinal day\n- `D`: required date, weekday (1 = Monday .. 7 = Sunday) if `W` is passed, or ordinal day\n- `W`: optional week number, then `D` is the week day\n\nReturns [ISODate](#new-isodatesource-options)\n\n### `date.toDate([enforceUTC])`\n\nGet Date represented by source.\n\n- `enforceUTC`: optional boolean, enforce UTC if source lacks time zone offset\n\n### `date.toJSON()`\n\nGet Date represented as JavaScript Object Notation.\n\n## `new ISODuration(source[, offset])`\n\nDuration instance.\n\n**Constructor**:\n\n- `source`: duration source string\n- `offset`: optional source string offset column number\n\n**Properties:**\n\n- `result`:\n  - `Y`: years\n  - `M`: months\n  - `W`: weeks\n  - `D`: days\n  - `H`: hours\n  - `m`: minutes\n  - `S`: seconds\n\n### `duration.toMilliseconds([startDate])`\n\nGet duration in milliseconds from optional start date.\n\n### `duration.untilMilliseconds([endDate])`\n\nGet duration in milliseconds until optional end date.\n\n## Example\n\nAn example to get start and end date:\n\n```javascript\nimport { parseInterval } from '@0dep/piso';\n\nconst source = '2007-03-01T13:00:00Z/P1Y2M10DT2H30M';\n\nconst interval = parseInterval(source);\n\nconsole.log('starts at', interval.getStartAt());\nconsole.log('expires at', interval.getExpireAt());\nconsole.log('duration milliseconds', interval.duration.toMilliseconds());\n```\n\nAn example to get duration milliseconds:\n\n```javascript\nimport { parseDuration } from '@0dep/piso';\n\nconst duration = parseDuration('PT2H30M');\n\nconsole.log('duration millisecods', duration.toMilliseconds(new Date()));\n```\n\n## Repetitions\n\n### With end date\n\n`R4/P2Y/2007-08-01`\n\n| Repetition | start at   | expire at  |\n| ---------: | ---------- | ---------- |\n|          4 | 1999-08-01 | 2001-08-01 |\n|          3 | 2001-08-01 | 2003-08-01 |\n|          2 | 2003-08-01 | 2005-08-01 |\n|          1 | 2005-08-01 | 2007-08-01 |\n\n## Benchmarking\n\nSeems to run 3 times more efficient than RegExp implementations. But date parsing is, of course, slower compared to `new Date('2024-03-26')`. 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.\n\n### Interval\n\n| Capability         | piso | luxon |\n| ------------------ | ---- | ----- |\n| start/end          | ✓    | ✓     |\n| start/duration     | ✓    | ✓     |\n| duration/end       | ✓    | ✓     |\n| Repeating interval | ✓    | ❌    |\n| Relative end date  | ✓    | ❌    |\n\n### Duration\n\n| Capability                        | piso | iso8601-duration | luxon | [temporal](https://www.npmjs.com/package/@js-temporal/polyfill) |\n| --------------------------------- | ---- | ---------------- | ----- | --------------------------------------------------------------- |\n| Fractional time designator        | ✓    | ✓                | ✓     | ✓                                                               |\n| Invalid if more than one fraction | ✓    | ✓                | ✓     | ✓                                                               |\n| Year designator                   | ✓    | ✓                | ✓     | ❌                                                              |\n| Fractional date designator        | ✓    | ❌               | ✓     | ❌                                                              |\n| Comma as fraction separator       | ✓    | ✓                | ❌    | ✓                                                               |\n| Repeated duration instruction     | ✓    | ❌\\*             | ❌    | ❌                                                              |\n\n\u003e \\* ignored\n\n### Date\n\n| Capability                  | piso | luxon | node 24 |\n| --------------------------- | ---- | ----- | ------- |\n| The 24:th hour              | ✓    | ✓     | ✓       |\n| Year +10000                 | ✓    | ✓     | ✓       |\n| Year 9999                   | ✓    | ✓     | ✓       |\n| BC dates                    | ✓    | ✓     | ✓       |\n| Week                        | ✓    | ✓     | ❌      |\n| Ordinal date                | ✓    | ✓     | ❌\\*    |\n| Without separators          | ✓    | ✓     | ❌      |\n| Without offset minutes      | ✓    | ✓     | ❌      |\n| Comma as fraction separator | ✓    | ✓     | ❌      |\n| Throw on invalid leap year  | ✓    | ✓     | ❌\\*\\*  |\n| Offset unicode minus (−)    | ✓    | ❌    | ❌      |\n| Offset seconds              | ✓    | ❌    | ❌      |\n| 36 fractions of a second    | ❌   | ❌    | ✓       |\n\n\u003e \\* node misinterprets `2024-012` as December and fails when `2024-013` or `2024-012T07:30` is passed\u003cbr/\u003e\n\u003e \\*\\* node is benevolent when parsing `2100-02-29` as `2100-03-01`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodep%2Fpiso","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerodep%2Fpiso","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodep%2Fpiso/lists"}