date-and-time 3.6.0 → 4.0.0

package/docs/MIGRATION.md

@@ -0,0 +1,226 @@
+# Migration Guide
+
+Version `4.x` has been completely rewritten in TypeScript and some features from `3.x` are no longer compatible. This section explains the changes to each feature and the migration methods.
+
+## Install
+
+Version `4.x` adopts a modern development style and no longer supports older browsers. Module imports are only supported in `ESModules` or `CommonJS` style. Additionally, since functions can now be imported directly, there is a higher possibility of reducing the final module size through bundler tree shaking.
+
+- ESModules:
+
+```typescript
+import { format } from 'date-and-time';
+
+format(new Date(), 'ddd, MMM DD YYYY');
+// => Wed, Jul 09 2025
+```
+
+- CommonJS:
+
+```typescript
+const { format } = require('date-and-time');
+
+format(new Date(), 'ddd, MMM DD YYYY');
+// => Wed, Jul 09 2025
+```
+
+## API
+
+### format
+
+The third argument has been changed from `boolean` to `FormatterOptions`. With `FormatterOptions`, you can now specify timezone and locale settings. If you previously set the third argument to `true` to output in UTC timezone, you can achieve the same output as follows:
+
+```typescript
+import { format } from 'date-and-time';
+
+format(new Date(), 'ddd, MMM DD YYYY hh:mm A [GMT]Z', { timeZone: 'UTC' });
+// => Fri, Jan 02 2015 07:14 AM GMT+0000
+```
+
+Additionally, since the `timezone` plugin has been integrated into the main library, the `formatTZ` function has been deprecated. Timezones are now imported as modules rather than using `IANA time zone names` (except for UTC timezone).
+
+```typescript
+import { format } from 'date-and-time';
+import New_York from 'date-and-time/timezones/America/New_York';
+
+format(now, 'dddd, MMMM D, YYYY [at] H:mm:ss.SSS [GMT]ZZ', { timeZone: New_York });
+// => Wednesday, July 23, 2025 at 3:28:27.443 GMT-04:00
+```
+
+### parse
+
+The third argument has been changed from `boolean` to `ParserOptions`. With `ParserOptions`, you can now specify timezone and locale settings. If you previously set the third argument to `true` to parse input in UTC timezone, you can achieve the same output as follows:
+
+```typescript
+import { parse } from 'date-and-time';
+
+parse('11:14:05 PM', 'h:mm:ss A', { timeZone: 'UTC' });
+// => Jan 02 1970 23:14:05 GMT+0000
+```
+
+Additionally, since the `timezone` plugin has been integrated into the main library, the `parseTZ` function has been deprecated. Timezones are now imported as modules rather than using `IANA time zone names` (except for UTC timezone).
+
+```typescript
+import { parse } from 'date-and-time';
+import Paris from 'date-and-time/timezones/Europe/Paris';
+import fr from 'date-and-time/locales/fr';
+
+parse(
+  '02 janv. 2015, 11:14:05 PM', 'DD MMM YYYY, h:mm:ss A',
+  { timeZone: Paris, locale: fr }
+);
+// => Jan 02 2015 23:14:05 GMT+0100
+```
+
+### preparse
+
+The third argument has been changed from `boolean` to `ParserOptions`. With `ParserOptions`, you can now specify timezone and locale settings. If you previously set the third argument to `true` to parse input in UTC timezone, you can achieve the same output as follows:
+
+```typescript
+import { preparse } from 'date-and-time';
+
+preparse('11:14:05 PM', 'h:mm:ss A', { timeZone: 'UTC' });
+
+{
+  A: 1,
+  h: 11,
+  m: 14,
+  s: 5,
+  _index: 11,
+  _length: 11,
+  _match: 4
+}
+```
+
+Additionally, the `PreparseResult` object returned by the `preparse` function has the following changes:
+
+- Properties for tokens that were not read are not included. For example, in the code example above, since the string does not contain a date part, properties representing dates such as `Y`, `M`, and `D` are not included.
+- Read values are returned as-is. For example, previously, time read in 12-hour format was converted to 24-hour format, but this is no longer done.
+
+### isValid
+
+The following usage that takes `PreparseResult` as an argument has been deprecated.
+
+```typescript
+import { isValid, preparse } from 'date-and-time';
+
+const pr = preparse('11:14:05 PM', 'h:mm:ss A');
+
+// This usage is no longer supported
+isValid(pr);
+```
+
+Other changes are the same as for the `parse` function.
+
+### transform
+
+The fourth argument has been changed from `boolean` to `FormatterOptions`. With `FormatterOptions`, you can now specify timezone and locale settings. Additionally, `ParserOptions` has been added as a parameter before `FormatterOptions`. Since the `timezone` plugin has been integrated into the main library, the `transformTZ` function has been deprecated.
+
+```typescript
+import { transform } from 'date-and-time';
+import New_York from 'date-and-time/timezones/America/New_York';
+import Los_Angeles from 'date-and-time/timezones/America/Los_Angeles';
+
+// Convert 24-hour format to 12-hour format
+transform('13:05', 'HH:mm', 'hh:mm A', { timeZone: 'UTC' }, { timeZone: 'UTC' });
+// => 01:05 PM
+
+// Convert East Coast time to West Coast time
+transform(
+  '3/8/2020 1:05 PM', 'D/M/YYYY h:mm A', 'D/M/YYYY h:mm A',
+  { timeZone: New_York }, { timeZone: Los_Angeles }
+);
+// => 3/8/2020 10:05 AM
+```
+
+### addYears
+
+The third argument has been changed from `boolean` to `TimeZone | UTC`. If you previously set the third argument to `true` to calculate in UTC timezone, you can achieve the same output as follows:
+
+```typescript
+import { addYears } from 'date-and-time';
+
+const now = new Date(Date.UTC(2024, 2, 11, 1));
+// => Mar 11 2024 01:00:00 GMT+0000
+
+addYears(now, 1, 'UTC');
+// => Mar 11 2025 01:00:00 GMT+0000
+```
+
+Additionally, since the `timezone` plugin has been integrated into the main library, the `addYearsTZ` function has been deprecated. Timezones are now imported as modules rather than using `IANA time zone names` (except for UTC timezone).
+
+```typescript
+import Los_Angeles from 'date-and-time/timezones/America/Los_Angeles';
+
+const now = new Date(2024, 2, 11, 1);
+// => Mar 11 2024 01:00:00 GMT-07:00
+
+addYears(now, 1, Los_Angeles);
+// => Mar 11 2025 01:00:00 GMT-07:00
+```
+
+### addMonths
+
+The changes are the same as for the `addYears` function.
+
+### addDays
+
+The changes are the same as for the `addYears` function.
+
+### subtract
+
+The calculation order has been reversed. Previously, the second argument was subtracted from the first argument, but now the first argument is subtracted from the second argument.
+Additionally, the return value object has been changed to `Duration`. You can achieve the same output as before as follows:
+
+```typescript
+import { subtract } from 'date-and-time';
+
+const yesterday = new Date(2015, 0, 1);
+const today = new Date(2015, 0, 2);
+
+subtract(yesterday, today).toDays().value;         // => 1
+subtract(yesterday, today).toHours().value;        // => 24
+subtract(yesterday, today).toMinutes().value;      // => 1440
+subtract(yesterday, today).toSeconds().value;      // => 86400
+subtract(yesterday, today).toMilliseconds().value; // => 86400000
+```
+
+### timeSpan
+
+The `timespan` plugin has been deprecated as it has been integrated into the main library's `subtract` function. Please note that the argument order of the `subtract` function has changed. You can achieve the same output as before as follows:
+
+```typescript
+import { subtract } from 'date-and-time';
+
+const new_years_day = new Date(2020, 0, 1);
+const now = new Date(2020, 2, 5, 1, 2, 3, 4);
+
+subtract(new_years_day, now).toDays().format('D HH:mm:ss.SSS');
+// => 64 01:02:03.004
+
+subtract(new_years_day, now).toHours().format('H [hours] m [minutes] s [seconds]');
+// => 1537 hours 2 minutes 3 seconds
+
+subtract(new_years_day, now).toMinutes().format('mmmmmmmmmm [minutes]');
+// => 0000092222 minutes
+```
+
+## Locale
+
+The method for switching locales has changed. Previously, the locale used throughout the library was switched, but now it is specified as a function argument. Below is a code example for the `format` function.
+
+```typescript
+import { format } from 'date-and-time';
+import es from 'date-and-time/locales/es';
+
+format(new Date(), 'dddd, D [de] MMMM [de] YYYY, h:mm aa [GMT]ZZ', { locale: es });
+// => miércoles, 23 de julio de 2025, 12:38 a.m. GMT-07:00
+```
+
+## Plugins
+
+The following plugins have been deprecated as they have been integrated into the main library:
+
+- `meridiem`
+- `timespan`
+- `timezone`

package/docs/PLUGINS.md

@@ -0,0 +1,206 @@
+# Plugins
+
+`date-and-time` adopts a plugin system. Special tokens that are considered to be used relatively infrequently are provided as plugins outside the main library. By adding plugins as needed, you can use those tokens in `Formatter` and `Parser`. Here, `Formatter` refers to the output engine used by the `format` function, and `Parser` refers to the parsing engine used by the `parse`, `preparse`, and `isValid` functions. These engines are extended by adding plugins as arguments to these functions.
+
+## Install
+
+- ESModules:
+
+```typescript
+import { format } from 'date-and-time';
+import foobar from 'date-and-time/plugins/foobar';
+
+format(new Date(), 'ddd, MMM DD YYYY', { plugins: [foobar] });
+```
+
+- CommonJS:
+
+```typescript
+const { format } = require('date-and-time');
+const foobar = require('date-and-time/plugins/foobar');
+
+format(new Date(), 'ddd, MMM DD YYYY', { plugins: [foobar] });
+```
+
+## Plugin List
+
+<details open>
+<summary><strong>day-of-week</strong></summary>
+
+You can add tokens to the `Parser` to read day of the week. Since day of the week is not information that can identify a specific date, it is actually a meaningless token, but it can be used to skip that portion when the string you want to read contains a day of the week.
+
+`Parser`:
+
+| Token    | Meaning                            | Input Examples |
+|:---------|:-----------------------------------|:---------------|
+| dddd     | Full day name                      | Friday, Sunday |
+| ddd      | Short day name                     | Fri, Sun       |
+| dd       | Very short day name                | Fr, Su         |
+
+```typescript
+import { parse } from 'date-and-time';
+import day_of_week from 'date-and-time/plugins/day_of_week';
+
+parse(
+  'Thursday, March 05, 2020', 'dddd, MMMM, D YYYY',
+  { plugins: [day_of_week] }
+);
+```
+
+</details>
+
+<details open>
+<summary><strong>microsecond</strong></summary>
+
+You can add tokens to the `Parser` to read microseconds. Since the precision of JavaScript's Date type is milliseconds, these tokens are actually meaningless, but they can be used to skip that portion when the string you want to read contains microseconds.
+
+`Parser`:
+
+| Token     | Meaning                          | Input Examples |
+|:----------|:---------------------------------|:---------------|
+| SSSSSS    | 6-digit milliseconds             | 123456, 000001 |
+| SSSSS     | 5-digit milliseconds             | 12345, 00001   |
+| SSSS      | 4-digit milliseconds             | 1234, 0001     |
+| fff       | 3-digit microseconds             | 753, 022       |
+| ff        | 2-digit microseconds             | 75, 02         |
+| f         | 1-digit microseconds             | 7, 0           |
+
+```typescript
+import { parse } from 'date-and-time';
+import microsecond from 'date-and-time/plugins/microsecond';
+
+parse('12:34:56.123456', 'HH:mm:ss.SSSSSS', { plugins: [microsecond] });
+parse('12:34:56 123.456', 'HH:mm:ss SSS.fff', { plugins: [microsecond] });
+```
+
+</details>
+
+<details open>
+<summary><strong>nanosecond</strong></summary>
+
+You can add tokens to the `Parser` to read nanoseconds. Since the precision of JavaScript's Date type is milliseconds, these tokens are actually meaningless, but they can be used to skip that portion when the string you want to read contains nanoseconds.
+
+`Parser`:
+
+| Token     | Meaning                          | Input Examples       |
+|:----------|:---------------------------------|:---------------------|
+| SSSSSSSSS | 9-digit milliseconds             | 123456789, 000000001 |
+| SSSSSSSS  | 8-digit milliseconds             | 12345678, 00000001   |
+| SSSSSSS   | 7-digit milliseconds             | 1234567, 0000001     |
+| FFF       | 3-digit nanoseconds              | 753, 022             |
+| FF        | 2-digit nanoseconds              | 75, 02               |
+| F         | 1-digit nanoseconds              | 7, 0                 |
+
+```typescript
+import { parse } from 'date-and-time';
+import microsecond from 'date-and-time/plugins/microsecond';
+import nanosecond from 'date-and-time/plugins/nanosecond';
+
+parse(
+  '12:34:56.123456789',
+  'HH:mm:ss.SSSSSSSSS',
+  { plugins: [microsecond, nanosecond] }
+);
+
+parse(
+  '12:34:56 123456.789',
+  'HH:mm:ss SSSSSS.FFF',
+  { plugins: [microsecond, nanosecond] }
+);
+```
+
+</details>
+
+<details open>
+<summary><strong>ordinal</strong></summary>
+
+You can add tokens to the `Formatter` and `Parser` to output or read ordinal representations of days. This ordinal representation is limited to English and is not supported for locales other than English.
+
+`Formatter`:
+
+| Token     | Meaning                          | Output Examples      |
+|:----------|:---------------------------------|:---------------------|
+| DDD       | Ordinal representation of day    | 1st, 2nd, 3rd        |
+
+```typescript
+import { format } from 'date-and-time';
+import ordinal from 'date-and-time/plugins/ordinal';
+
+format(new Date(), 'MMM DDD YYYY', { plugins: [ordinal] });
+// => Jan 1st 2019
+```
+
+`Parser`:
+
+| Token     | Meaning                          | Input Examples       |
+|:----------|:---------------------------------|:---------------------|
+| DDD       | Ordinal representation of day    | 1st, 2nd, 3rd        |
+
+```typescript
+import { parse } from 'date-and-time';
+import ordinal from 'date-and-time/plugins/ordinal';
+
+parse('Jan 1st 2019', 'MMM DDD YYYY', { plugins: [ordinal] });
+```
+
+</details>
+
+<details open>
+<summary><strong>two-digit-year</strong></summary>
+
+You can add tokens to the `Parser` to read 2-digit years. This token identifies years based on the following rules:
+
+- Values of 70 or above are interpreted as 1900s
+- Values of 69 or below are interpreted as 2000s
+
+`Parser`:
+
+| Token     | Meaning                          | Input Examples       |
+|:----------|:---------------------------------|:---------------------|
+| YY        | 2-digit year                     | 90, 00, 08, 19       |
+
+```typescript
+import { parse } from 'date-and-time';
+import two_digit_year from 'date-and-time/plugins/two-digit-year';
+
+parse('Dec 25 69', 'MMM DD YY', { plugins: [two_digit_year] });
+// => Dec 25 2069
+parse('Dec 25 70', 'MMM DD YY', { plugins: [two_digit_year] });
+// => Dec 25 1970
+```
+
+</details>
+
+<details open>
+<summary><strong>zonename</strong></summary>
+
+You can add tokens to the `Formatter` to output timezone names. These timezone names are limited to English and are not supported for locales other than English.
+
+`Formatter`:
+
+| Token    | Meaning                          | Output Examples       |
+|:---------|:---------------------------------|:----------------------|
+| z        | Short timezone name             | PST, EST              |
+| zz       | Long timezone name              | Pacific Standard Time |
+
+```typescript
+import { parse } from 'date-and-time';
+import zonename from 'date-and-time/plugins/zonename';
+import Tokyo from 'date-and-time/timezones/Asia/Tokyo';
+
+format(
+  new Date(),
+  'MMMM DD YYYY H:mm zz',
+  { plugins: [zonename] }
+);
+// March 14 2021 1:59 Pacific Standard Time
+
+format(
+  new Date(),
+  'MMMM DD YYYY H:mm z',
+  { plugins: [zonename], timeZone: Tokyo }
+);
+// March 14 2021 18:59 JST
+```
+
+</details>

package/package.json

@@ -1,58 +1,74 @@
 {
   "name": "date-and-time",
-  "version": "3.6.0",
-  "description": "A Minimalist DateTime utility for Node.js and the browser",
-  "main": "date-and-time.js",
-  "module": "esm/date-and-time.es.js",
-  "types": "date-and-time.d.ts",
-  "unpkg": "date-and-time.min.js",
+  "version": "4.0.0",
+  "description": "The simplest and most user-friendly date and time manipulation library",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./date-and-time.d.ts",
-      "import": "./esm/date-and-time.mjs",
-      "require": "./date-and-time.js",
-      "browser": "./esm/date-and-time.es.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     },
-    "./locale/*": {
-      "types": "./locale/*.d.ts",
-      "import": "./esm/locale/*.mjs",
-      "require": "./locale/*.js",
-      "browser": "./esm/locale/*.es.js"
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "require": "./dist/plugin.cjs"
     },
-    "./plugin/*": {
-      "types": "./plugin/*.d.ts",
-      "import": "./esm/plugin/*.mjs",
-      "require": "./plugin/*.js",
-      "browser": "./esm/plugin/*.es.js"
+    "./locales/*": {
+      "import": "./dist/locales/*.js",
+      "require": "./dist/locales/*.cjs"
+    },
+    "./numerals/*": {
+      "import": "./dist/numerals/*.js",
+      "require": "./dist/numerals/*.cjs"
+    },
+    "./plugins/*": {
+      "types": "./dist/plugins/*.d.ts",
+      "import": "./dist/plugins/*.js",
+      "require": "./dist/plugins/*.cjs"
+    },
+    "./timezones/*": {
+      "import": "./dist/timezones/*.js",
+      "require": "./dist/timezones/*.cjs"
     }
   },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist/",
+    "docs/"
+  ],
   "scripts": {
     "build": "rollup -c",
-    "test": "./test.sh",
-    "test:ts": "tsd ./test/ts"
+    "build-watch": "rollup -c --watch",
+    "build:ts": "rollup -c --config-ts",
+    "build:types": "rollup -c --config-types",
+    "lint": "eslint src",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "timezone": "tsx tools/timezone.ts",
+    "zonename": "tsx tools/zonename.ts"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/knowledgecode/date-and-time.git"
-  },
-  "keywords": [
-    "date",
-    "time",
-    "format",
-    "parse",
-    "utility"
-  ],
   "author": "KNOWLEDGECODE",
   "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/knowledgecode/date-and-time/issues"
-  },
-  "homepage": "https://github.com/knowledgecode/date-and-time",
+  "type": "module",
   "devDependencies": {
     "@rollup/plugin-terser": "^0.4.4",
-    "expect.js": "^0.3.1",
-    "mocha": "^10.7.3",
-    "rollup": "^4.22.5",
-    "tsd": "^0.31.2"
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/node": "^24.1.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.32.0",
+    "glob": "^11.0.3",
+    "globals": "^16.3.0",
+    "jiti": "^2.5.1",
+    "prettier": "^3.6.2",
+    "rollup": "^4.46.1",
+    "rollup-plugin-dts": "^6.2.1",
+    "rollup-plugin-esbuild": "^6.2.1",
+    "tsx": "^4.20.3",
+    "typescript-eslint": "^8.38.0",
+    "vitest": "^3.2.4"
   }
 }

package/EXTEND.md

@@ -1,107 +0,0 @@
-# Extension
-
-The easiest way to extend the default formatter and parser is to use plugins, but if the existing plugins do not meet your requirements, you can extend them yourself.
-
-## Token
-
-Tokens in this library have the following rules:
-
-- All of the characters must be the same alphabet (`A-Z, a-z`).
-
-```javascript
-'E'           // Good
-'EE'          // Good
-'EEEEEEEEEE'  // Good, but why so long!?
-'EES'         // Not good
-'???'         // Not good
-```
-
-- It is case sensitive.
-
-```javascript
-'eee'         // Good
-'Eee'         // Not good
-```
-
-- Only tokens consisting of the following alphabets can be added to the parser.
-
-```javascript
-'Y'           // Year
-'M'           // Month
-'D'           // Day
-'H'           // 24-hour
-'A'           // AM PM
-'h'           // 12-hour
-'s'           // Second
-'S'           // Millisecond
-'Z'           // Timezone offset
-```
-
-- Existing tokens cannot be overwritten.
-
-```javascript
-'YYY'         // This is OK because the same token does not exists.
-'SSS'         // This cannot be added because the exact same token exists.
-'EEE'         // This is OK for the formatter, but cannot be added to the parser.
-```
-
-## Examples
-
-### Example 1
-
-Add `E` token to the formatter. This new token will output "decade" like this:
-
-```javascript
-const d1 =  new Date(2020, 0, 1);
-const d2 =  new Date(2019, 0, 1);
-
-date.format(d1, '[The year] YYYY [is] E[s].');  // => "The year 2020 is 2020s."
-date.format(d2, '[The year] YYYY [is] E[s].');  // => "The year 2019 is 2010s."
-```
-
-Source code example is here:
-
-```javascript
-const date = require('date-and-time');
-
-date.extend({
-  formatter: {
-    E: function (d) {
-      return (d.getFullYear() / 10 | 0) * 10;
-    }
-  }
-});
-```
-
-### Example 2
-
-Add `MMMMM` token to the parser. This token ignores case:
-
-```javascript
-date.parse('Dec 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019
-date.parse('dec 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019
-date.parse('DEC 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019
-```
-
-Source code example is here:
-
-```javascript
-const date = require('date-and-time');
-
-date.extend({
-  parser: {
-    MMMMM: function (str) {
-      const mmm = this.res.MMM.map(m => m.toLowerCase());
-      const result = this.find(mmm, str.toLowerCase());
-      result.value++;
-      return result;
-    }
-  }
-});
-```
-
-Extending the parser may be a bit difficult. Refer to the library source code to grasp the default behavior.
-
-## Caveats
-
-Note that switching locales or applying plugins after extending the library will be cleared all extensions. In such cases, you need to extend the library again.