qrono 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +42 -25
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -15,18 +15,17 @@ qrono({ localtime: true }, '2021-08-31 12:34').toString() === '2021-08-31T12:34.
|
|
|
15
15
|
|
|
16
16
|
---
|
|
17
17
|
|
|
18
|
-
|
|
19
18
|
## Design philosophy 🎨
|
|
20
19
|
|
|
21
|
-
- Provides immutable and
|
|
20
|
+
- Provides type-safe, immutable and chainable functions necessary for most cases.
|
|
22
21
|
- Locality-Agnostic.
|
|
23
|
-
- Localization
|
|
24
|
-
- Supports only UTC (
|
|
25
|
-
- [Other libraries](#alternatives)
|
|
26
|
-
- In most cases,
|
|
27
|
-
|
|
28
|
-
-
|
|
29
|
-
- This feature
|
|
22
|
+
- Localization can be done with the [ECMAScript® Internationalization API](https://402.ecma-international.org/#overview).
|
|
23
|
+
- Supports only UTC (default) and the local time of the environment.
|
|
24
|
+
- [Other libraries](#alternatives) have larger codebases and more complicated usage to support multiple time zones and locales.
|
|
25
|
+
- In most cases, supporting only the client's time zone is sufficient.
|
|
26
|
+
[Luxon's explanation](https://moment.github.io/luxon/#/zones?id=don39t-worry) is right to the point.
|
|
27
|
+
- Handles ambiguous daylight saving time strictly.
|
|
28
|
+
- This feature is possible due to the lack of support for multiple time zones and locales.
|
|
30
29
|
- Follows [ISO 8601](https://www.iso.org/obp/ui/#iso:std:iso:8601:-1:ed-1:v1:en).
|
|
31
30
|
- Pure JavaScript without dependencies.
|
|
32
31
|
|
|
@@ -36,29 +35,29 @@ qrono({ localtime: true }, '2021-08-31 12:34').toString() === '2021-08-31T12:34.
|
|
|
36
35
|
<li>
|
|
37
36
|
<a href="https://github.com/moment/moment">Moment.js</a>
|
|
38
37
|
<br>
|
|
39
|
-
|
|
40
|
-
It has a fundamental problem
|
|
38
|
+
A widely used library that was the de-facto standard. It went into maintenance mode in 2020.<br>
|
|
39
|
+
It has a fundamental problem with mutable objects, making it prone to bugs. The later date-time libraries introduced below are all designed to be immutable.<br>
|
|
41
40
|
</li>
|
|
42
41
|
<li>
|
|
43
42
|
<a href="https://github.com/moment/luxon">Luxon</a>
|
|
44
43
|
<br>
|
|
45
|
-
An immutable and rich library created by the maintainers of <a href="https://github.com/moment/moment">Moment.js</a>. Sophisticated and feature-rich. Good
|
|
46
|
-
By default, it handles time in local time
|
|
47
|
-
It
|
|
44
|
+
An immutable and rich library created by the maintainers of <a href="https://github.com/moment/moment">Moment.js</a>. Sophisticated and feature-rich. Good codebase to explore.<br>
|
|
45
|
+
By default, it handles time in local time and <a href="https://moment.github.io/luxon/#/zones?id=ambiguous-times">cannot strictly handle ambiguous times</a>.<br>
|
|
46
|
+
It differs from other libraries in that the documentation clearly shows how it behaves with ambiguous time.<br>
|
|
48
47
|
</li>
|
|
49
48
|
<li>
|
|
50
49
|
<a href="https://github.com/iamkun/dayjs">Day.js</a>
|
|
51
50
|
<br>
|
|
52
51
|
A <a href="https://github.com/moment/moment">Moment.js</a> compatible library with a minimum size of 2KB, which has <a href="https://github.com/iamkun/dayjs/stargazers">many GitHub stars</a> and is becoming the de-facto standard. The code readability is not high.<br>
|
|
53
|
-
The
|
|
54
|
-
Requires
|
|
55
|
-
Planning a major version upgrade
|
|
52
|
+
The codebase is large due to time zone and locale support (178 source files as of 2021-11-02), but the effective size can be reduced if tree-shaking is available.<br>
|
|
53
|
+
Requires importing plugins each time because most functions are provided as plugins.<br>
|
|
54
|
+
Planning a major version upgrade while solving <a href="https://github.com/iamkun/dayjs/issues?q=is%3Aissue+is%3Aopen">many issues</a>.<br>
|
|
56
55
|
</li>
|
|
57
56
|
<li>
|
|
58
57
|
<a href="https://github.com/date-fns/date-fns">date-fns</a>
|
|
59
58
|
<br>
|
|
60
|
-
|
|
61
|
-
Since the JavaScript Date object takes the lead, problems such as
|
|
59
|
+
Provides over 200 pure functions for manipulating JavaScript `Date` objects, implemented in TypeScript and tree-shaking enabled.<br>
|
|
60
|
+
Since the JavaScript `Date` object takes the lead, problems such as mutability and month starting at 0 are inherited. <br>
|
|
62
61
|
</li>
|
|
63
62
|
<li>
|
|
64
63
|
<a href="https://tc39.es/proposal-temporal/docs/index.html">
|
|
@@ -70,6 +69,25 @@ qrono({ localtime: true }, '2021-08-31 12:34').toString() === '2021-08-31T12:34.
|
|
|
70
69
|
</ul>
|
|
71
70
|
</details>
|
|
72
71
|
|
|
72
|
+
### About daylight saving time transitions
|
|
73
|
+
|
|
74
|
+
JavaScript's `Date` object can behave in non-intuitive ways when handling daylight saving time transitions.
|
|
75
|
+
|
|
76
|
+
For example, see the following scenario in the Central Standard Time (CST) zone of the USA.
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
const date = new Date('2021-03-14T03:00:00.000')
|
|
80
|
+
date.setMilliseconds(-1) // results 2021-03-14 03:59:59.999 CST
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
On March 14, 2021, daylight saving time begins. The time jumps directly from `2021-03-14 01:59:59 CST` to `2021-03-14 03:00:00 CST`.
|
|
84
|
+
In this example, subtracting 1 millisecond from `2021-03-14 03:00:00.000 CST` results in `2021-03-14 03:59:59.999 CST`. This appears to be a simple subtraction of 1 millisecond, but it actually advances the time by 1 hour.
|
|
85
|
+
|
|
86
|
+
This behavior is not a bug but a result of strictly following the ECMAScript specification (https://262.ecma-international.org/11.0/#sec-local-time-zone-adjustment).
|
|
87
|
+
|
|
88
|
+
Additionally, a `Date` object created from a duplicated time during daylight saving time (DST) transition always refers to the time before DST ends. In other words, there is no simple way to obtain a `Date` object that refers to the UTC time **after** the end of DST from a duplicated time.
|
|
89
|
+
|
|
90
|
+
This library addresses these issues by providing a more understandable approach to handling such transitions.
|
|
73
91
|
|
|
74
92
|
## Getting started 📥
|
|
75
93
|
|
|
@@ -101,10 +119,10 @@ const { qrono } = require('qrono')
|
|
|
101
119
|
```js
|
|
102
120
|
// now
|
|
103
121
|
qrono()
|
|
104
|
-
// from various
|
|
122
|
+
// from various types of arguments
|
|
105
123
|
qrono('2022-12-31') // => 2022-12-31T00:00:00.000Z
|
|
106
124
|
qrono(new Date())
|
|
107
|
-
//
|
|
125
|
+
// the following are the same 2022-12-31T15:23:11.321Z
|
|
108
126
|
qrono('2022-12-31 15:23:11.321')
|
|
109
127
|
qrono(1672500191321)
|
|
110
128
|
qrono(2022, 12, 31, 15, 23, 11, 321)
|
|
@@ -147,7 +165,7 @@ qrono('2000-01-01').numeric() // => 946,684,800,000 milliseconds from UNIX epoch
|
|
|
147
165
|
const time = qrono('2000-01-02 03:04:05.006')
|
|
148
166
|
time.toObject() // => { year: 2000, month: 1, day: 2, hour: 3, minute: 4, second: 5, millisecond: 6 }
|
|
149
167
|
time.toArray() // => [2000, 1, 2, 3, 4, 5, 6]
|
|
150
|
-
time.nativeDate() // => JavaScript native Date instance
|
|
168
|
+
time.nativeDate() // => JavaScript native `Date` instance
|
|
151
169
|
```
|
|
152
170
|
|
|
153
171
|
### Calculation
|
|
@@ -165,8 +183,8 @@ qrono('2021-12-31').minus({ month: 1 }) // => 2021-11-30T00:00:00
|
|
|
165
183
|
|
|
166
184
|
const today = qrono()
|
|
167
185
|
const yesterday = today.minus({ day: 1 })
|
|
168
|
-
const
|
|
169
|
-
today.isBetween(yesterday,
|
|
186
|
+
const tomorrow = today.plus({ day: 1 })
|
|
187
|
+
today.isBetween(yesterday, tomorrow) // => true
|
|
170
188
|
```
|
|
171
189
|
|
|
172
190
|
### Short-hands
|
|
@@ -227,4 +245,3 @@ Copyright (c) 2021 [Urin](https://github.com/urin)
|
|
|
227
245
|
|
|
228
246
|
[image-size]: https://img.badgesize.io/https://unpkg.com/qrono/dist/qrono.min.js?compression=gzip&color=blue
|
|
229
247
|
[url-size]: https://unpkg.com/qrono/dist/qrono.min.js
|
|
230
|
-
|