# @antongolub/iso8601

> Strict ISO8601 datetime parser

Latest version **1.2.2** (published 2022-02-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install @antongolub/iso8601
pnpm add @antongolub/iso8601
yarn add @antongolub/iso8601
bun add @antongolub/iso8601
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.2 |
| Published | 2022-02-12 |
| First published | 2018-03-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 929.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Anton Golub |
| Maintainers | antongolub |
| Keywords | iso8601, ISO 8601, datetime, date, time, parser |

## Links

- npm: https://www.npmjs.com/package/@antongolub/iso8601
- Repository: https://github.com/antongolub/iso8601
- Homepage: https://github.com/antongolub/iso8601#readme
- Issues: https://github.com/antongolub/iso8601/issues
- npm.io page: https://npm.io/package/@antongolub/iso8601

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 1.2.2 (latest) — 2022-02-12
- 1.2.1 — 2019-12-17
- 1.2.0 — 2019-09-10
- 1.1.0 — 2019-08-28
- 1.0.1 — 2019-08-24
- 1.0.0 — 2019-08-22
- 0.2.0 — 2019-08-22
- 0.1.1 — 2018-08-17
- 0.1.0 — 2018-06-20
- 0.0.3 — 2018-04-21
- 0.0.2 — 2018-03-15

## README

# ISO 8601
> Strict ISO8601 datetime parser

[![Build Status](https://travis-ci.com/antongolub/iso8601.svg?branch=master)](https://travis-ci.com/antongolub/iso8601)
[![npm (tag)](https://img.shields.io/npm/v/@antongolub/iso8601/latest.svg)](https://www.npmjs.com/package/@antongolub/iso8601)
[![Maintainability](https://api.codeclimate.com/v1/badges/ed234c819b9e225b2bab/maintainability)](https://codeclimate.com/github/antongolub/iso8601/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/ed234c819b9e225b2bab/test_coverage)](https://codeclimate.com/github/antongolub/iso8601/test_coverage)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com)

## Yet another one date parser?
It's 20** and if you operate with dates, you should take one of these:
* [momentjs](https://momentjs.com/)
* [date-fns](https://date-fns.org/)

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

## Install
```bash
npm add @antongolub/iso8601
yarn add @antongolub/iso8601
```

## Usage
```javascript
    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
```javascript
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()`
```javascript
    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
```

---
_Source: https://npm.io/package/@antongolub/iso8601 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._