qrono 0.1.7 → 0.2.1

package/README.md

@@ -1,4 +1,4 @@
-# Qrono<small> - 🕥 Just right date time library</small>
+# <img src="docs/public/logo.svg" alt="Qrono Logo" width="48"> [Qrono](https://qronojs.dev/) - 🕥 _Just right date time library_
 
 [![MIT License][image-license]][url-license]
 [![NPM version][image-npm-version]][url-npm]
@@ -11,100 +11,122 @@ qrono('2021-08-31 12:34') < qrono('2021-09-30 12:34')
 qrono({ localtime: true }, '2021-08-31 12:34').toString() === '2021-08-31T12:34.000-04:00'
 ```
 
-[🎨 Design philosophy](#design-philosophy-) \| [📥 Getting started](#getting-started-) \| [🚀 Quick tour](#quick-tour-) \| [🌏 License](#license-)
+[🌐 Website<sup> ↗</sup>](https://qronojs.dev/) \| [🎨 Design philosophy](#design-philosophy-) \| [📥 Getting started](#getting-started-) \| [🚀 Quick tour](#quick-tour-) \| [🌏 License](#license-)
 
 ---
 
 ## Design philosophy 🎨
 
-- Provides type-safe, immutable and chainable functions necessary for most cases.
-- Locality-Agnostic.
-  - Localization can be done with the [ECMAScript® Internationalization API](https://402.ecma-international.org/#overview).
-- Supports only UTC (default) and the local time of the environment.
-  - [Other libraries](#alternatives) have larger codebases and more complicated usage to support multiple time zones and locales.
-  - In most cases, supporting only the client's time zone is sufficient.
-    [Luxon's explanation](https://moment.github.io/luxon/#/zones?id=don39t-worry) is right to the point.
-- Handles ambiguous daylight saving time strictly.
-  - This feature is possible due to the lack of support for multiple time zones and locales.
-- Follows [ISO 8601](https://www.iso.org/obp/ui/#iso:std:iso:8601:-1:ed-1:v1:en).
-- Pure JavaScript without dependencies.
-
-<details>
-  <summary id="alternatives">Alternatives</summary>
-  <ul>
-    <li>
-      <a href="https://github.com/moment/moment">Moment.js</a>
-      <br>
-      A widely used library that was the de-facto standard. It went into maintenance mode in 2020.<br>
-      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>
-    </li>
-    <li>
-      <a href="https://github.com/moment/luxon">Luxon</a>
-      <br>
-      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>
-      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>
-      It differs from other libraries in that the documentation clearly shows how it behaves with ambiguous time.<br>
-    </li>
-    <li>
-      <a href="https://github.com/iamkun/dayjs">Day.js</a>
-      <br>
-      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>
-      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>
-      Requires importing plugins each time because most functions are provided as plugins.<br>
-      Planning a major version upgrade while solving <a href="https://github.com/iamkun/dayjs/issues?q=is%3Aissue+is%3Aopen">many issues</a>.<br>
-    </li>
-    <li>
-      <a href="https://github.com/date-fns/date-fns">date-fns</a>
-      <br>
-      Provides over 200 pure functions for manipulating JavaScript `Date` objects, implemented in TypeScript and tree-shaking enabled.<br>
-      Since the JavaScript `Date` object takes the lead, problems such as mutability and month starting at 0 are inherited. <br>
-    </li>
-    <li>
-      <a href="https://tc39.es/proposal-temporal/docs/index.html">
-        The ECMA TC39 Temporal Proposal
-      </a>
-      <br>
-      An ECMAScript® API proposal that may become a future standard. The specification is rigorous, spectacular, and inspired by <a href="https://jcp.org/aboutJava/communityprocess/pfd/jsr310/JSR-310-guide.html">java.time</a>.
-    </li>
-  </ul>
-</details>
-
-### About daylight saving time transitions
+- **Type-safe, immutable, and chainable**  
+  Provides functions necessary for most cases.
+- **Locality-Agnostic**  
+  Localization can be done with the [ECMAScript® Internationalization API](https://402.ecma-international.org/#overview).
+- **UTC and Local Time Only**  
+  Supports only UTC (default) and the local time of the environment. In most cases, supporting only the client's time zone is
+sufficient.
+- **Strict DST Handling**  
+  The only library that handles ambiguous daylight saving time strictly, with dedicated APIs for DST transitions.
+- **ISO 8601 Compliant**  
+  Follows the [ISO 8601](https://www.iso.org/obp/ui/#iso:std:iso:8601:-1:ed-1:v1:en) standard.
+- **Zero Dependencies**  
+  Pure JavaScript without external dependencies.
+
+### Alternatives
+
+- **[Moment.js](https://momentjs.com/)**  
+  A widely used library that was the de-facto standard. It went into maintenance mode in 2020.  
+  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.  
+        
+- **[Luxon](https://moment.github.io/luxon/)**  
+  An immutable and rich library created by the maintainers of [Moment.js](https://github.com/moment/moment).  Sophisticated and feature-rich. Good codebase to explore.  
+  By default, it handles time in local time and [cannot strictly handle ambiguous times](https://moment.github.io/luxon/#/zones?id=ambiguous-times).  
+  It differs from other libraries in that the documentation clearly shows how it behaves with ambiguous time.  
+
+- **[Day.js](https://day.js.org/)**  
+  A [Moment.js](https://github.com/moment/moment) compatible library with small size, which has [many GitHub stars](https://github.com/iamkun/dayjs/stargazers) and is becoming the de-facto standard.  
+  3.4kB with 30+ APIs, but requires plugin imports for timezone/locale support and other functions.
+  **Qrono** achieves **3.9kB with 100+ APIs** without plugins.
+  The codebase is large due to time zone and locale support (178 source files as of 2021-11-02).  
+  Planning a major version upgrade while solving [many issues](https://github.com/iamkun/dayjs/issues?q=is%3Aissue+is%3Aopen).  
+
+- **[date-fns](https://date-fns.org/)**  
+  Provides 200+ pure functions for manipulating JavaScript `Date` objects, implemented in TypeScript and tree-shaking enabled.  
+  Since the JavaScript `Date` object takes the lead, problems such as mutability and month starting at 0 are inherited.   
+
+- **[The ECMA TC39 Temporal Proposal](https://tc39.es/proposal-temporal/docs/index.html)**  
+  An ECMAScript® API proposal that may become a future standard. The specification is rigorous, spectacular, and inspired by [java.time](https://jcp.org/aboutJava/communityprocess/pfd/jsr310/JSR-310-guide.html).
+
+None of these libraries provide APIs to detect or handle DST transitions properly. Qrono fills this gap with a balanced approach - not too simple, not too complex, just right.
+
+### Repository Size Comparison
+
+[![Comparison of repository size](docs/public/comparison-repo-size.svg)](docs/public/comparison-repo-size.svg)
+
+This comparison shows that **Qrono clearly stands out for its remarkably small codebase** among other libraries. Its compact size reflects a strong focus on minimalism and efficiency, making it well suited for situations where bundle size and simplicity are important.
+
+For many of the other libraries, their larger size is due to the fact that a significant portion of the codebase is dedicated to supporting a wide range of locales. Meanwhile, the larger size of date-fns is intentional and not a drawback. It is designed with tree-shaking in mind, so unused functions are removed at build time, and its API is intentionally fine-grained and verbose to provide clarity and flexibility. The size difference therefore represents a difference in design philosophy, not a measure of overall quality.
+
+### Supporting Only the Local Time of the Execution Environment
+
+When handling time in a globally accessible web application, careful consideration is required for local time.
+
+In general, the server does not know the user’s actual time zone or the time zone of the client environment (OS).
+If the system needs to be aware of the user’s time zone, an application-level mechanism to manage time zones becomes necessary. In practice, however, the user’s time zone is usually assumed to be the same as the client environment’s (OS) time zone.
+
+For example, a user who resides in Japan may start using the application in the United States. If the user changes the OS time zone to match the local time in the United States, this will be done automatically in most cases, such as when the environment is a smart device; the client environment's time zone will differ from the one that is managed in the server. Considering the large number of such edge cases, it is impractical for a server-side application to manage each user's intended time zone in a database-like manner.
+
+For this reason, to keep the system design simple, the server should avoid managing user-specific time zones. Instead, the server should store and handle time exclusively in UTC. All time values should be transmitted to clients in UTC (typically as ISO 8601–formatted strings), and converting them into local time should be the responsibility of the client.
+
+Even when support for multiple locales is required, storing time data in UTC is usually sufficient. In most cases, locale-specific formatting can be handled entirely on the client side by using the [ECMAScript® Internationalization API](https://402.ecma-international.org/#overview).
+
+One important caveat of this design is that the time zone database of the client environment (OS) must be properly maintained. Daylight saving time rules — for example, in Brazil — may change from year to year, and time zone definitions themselves are determined by laws that are frequently revised. This means that the underlying time zone database must be kept up to date.
+
+If the application is used in a closed or unmanaged environment where such updates cannot be applied due to special constraints, the approach described above may be insufficient.
+
+In most typical environments, this requirement is satisfied automatically through the operating system’s regular update mechanisms, so it does not pose a practical issue for the majority of applications. However, if the application is used in a closed or unmanaged environment where such updates cannot be applied due to special constraints, the approach described above may be insufficient.
+
+Considering these factors, **Qrono** is deliberately designed to forgo support for multiple time zones in order to achieve greater overall benefits, such as a **small code base and easy handling of daylight saving time transitions**.
+
+### About Daylight Saving Time
+
+Qrono is the only JavaScript date-time library with dedicated APIs for DST handling (`hasDstInYear()`, `isInDst()`, `isDstTransitionDay()`, `minutesInDay()`).
 
 JavaScript's `Date` object can behave in non-intuitive ways when handling daylight saving time transitions.
 
-For example, see the following scenario in the Central Standard Time (CST) zone of the USA.
+For example, see the following scenario in the Central Standard Time (CST) zone of the USA:
 
-```js
+```javascript
 const date = new Date('2021-03-14T03:00:00.000')
 date.setMilliseconds(-1) // results 2021-03-14 03:59:59.999 CST
 ```
 
 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`.
+
 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.
 
-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).
+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).
 
 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.
 
-This library addresses these issues by providing a more understandable approach to handling such transitions.
+**Qrono** addresses these issues by providing a more understandable approach to handling such transitions.
 
 ## Getting started 📥
 
-### Browser
+```sh
+npm  install qrono        # for npm
+deno add jsr:@urin/qrono  # for Deno
+bunx jsr add @urin/qrono  # for Bun
+pnpm add     @urin/qrono  # for pnpm
+yarn add     @urin/qrono  # for Yarn
+```
 
 ```html
+<!-- for Browser -->
 <script src="path/to/qrono.min.js"></script>
 <!-- from UNPKG -->
 <script src="https://unpkg.com/qrono/dist/qrono.min.js"></script>
 ```
 
-### Node.js
-
-```sh
-npm install qrono
-```
-
 ```js
 // as module
 import { qrono } from 'qrono'
@@ -114,6 +136,8 @@ const { qrono } = require('qrono')
 
 ## Quick tour 🚀
 
+Visit [official website](https://qronojs.dev/) for complete documentation.
+
 ### Construction
 
 ```js