chronos-date 1.1.2 → 1.2.0

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.
Files changed (4) hide show
  1. package/README.md +64 -16
  2. package/dist/plugins/timeZonePlugin.cjs +13 -7
  3. package/dist/plugins/timeZonePlugin.mjs +13 -7
  4. package/package.json +5 -5
package/README.md CHANGED
@@ -1,31 +1,79 @@
1
1
  # Chronos Date
2
2
 
3
- > A comprehensive date and time library for any JavaScript and TypeScript environment.
3
+ A lightweight, immutable, and plugin-based date-time manipulation library for JavaScript and TypeScript.
4
4
 
5
- ## Install
5
+ ![Chronos Date](https://raw.githubusercontent.com/nazmul-nhb/chronos-date/refs/heads/main/chronos.png)
6
6
 
7
- ### NPM
7
+ ## Why Chronos?
8
8
 
9
- ```bash
10
- npm i chronos-date
11
- ```
9
+ In ancient Greek mythology, **Chronos** is the primordial embodiment of time — not merely tracking moments, but **defining their very existence**. Like its mythological namesake, the `Chronos` class offers **precise, immutable, and expressive control** over time within your application.
10
+
11
+ Designed to go beyond the native `Date` object, it empowers you to manipulate, format, compare, and traverse time with **clarity, reliability, and confidence** — all while staying _immutable_ and _framework-agnostic_.
12
+
13
+ ## Key Features
12
14
 
13
- ### PNPM
15
+ - **Immutability:** Every modification returns a new `Chronos` instance. Your original dates remain intact.
16
+ - **Rich API:** From formatting to comparison, calculation, and detailed part extraction.
17
+ - **Plugin System:** Extend core capabilities seamlessly using `Chronos.use(plugin)`. Over a dozen official plugins exist for advanced operations like business hours, seasons, zodiacs, relative times, and more.
18
+ - **Time Zone Support:** Advanced formatting and tracking of UTC offsets and Native time zone properties.
19
+ - **Date Utilities:** Extra utilities, type guards, types and constants for light weight date operations without the need of core class.
20
+ - **Comprehensive TypeScript IntelliSense:** Built with first-class TypeScript types and granular tracking for strict date formatting tokens.
21
+ - **Cross-environment compatibility:** Works anywhere JS runs (Node.js, Browser, Deno, Bun).
14
22
 
15
- ```bash
23
+ ## Installation
24
+
25
+ ```sh
26
+ npm install chronos-date
27
+ # or
28
+ yarn add chronos-date
29
+ # or
16
30
  pnpm add chronos-date
17
31
  ```
18
32
 
19
- ### YARN
33
+ ## Quick Start
20
34
 
21
- ```bash
22
- yarn add chronos-date
35
+ ```ts
36
+ import { Chronos, chronos } from 'chronos-date';
37
+
38
+ // Using the constructor
39
+ const now = new Chronos();
40
+ console.log(now.format('dd, mmm DD, YYYY'));
41
+
42
+ // Using the function wrapper
43
+ const tomorrow = chronos().addDays(1);
44
+ console.log(tomorrow.formatStrict('YYYY-MM-DD'));
45
+
46
+ // Calculate differences
47
+ const eventDate = new Chronos('2025-12-31');
48
+ console.log(now.diff(eventDate, 'day')); // Days until event
23
49
  ```
24
50
 
25
- ---
51
+ ## Modular Imports
52
+
53
+ You can import specific submodules for better tree-shaking:
54
+
55
+ ```ts
56
+ // Guards
57
+ import { isValidDateInput } from "chronos-date/guards";
58
+
59
+ // Utility functions
60
+ import { formatDate } from "chronos-date/utils";
61
+
62
+ // Type definitions
63
+ import type { ChronosInput } from "chronos-date/types";
64
+
65
+ // Constants
66
+ import { MONTHS } from "chronos-date/constants";
67
+
68
+ // Plugins (imported individually)
69
+ import { timeZonePlugin } from "chronos-date/plugins/timeZonePlugin";
70
+ import { seasonPlugin } from "chronos-date/plugins/seasonPlugin";
71
+ ```
72
+
73
+ ## Documentation
74
+
75
+ For full documentation, API reference, and interactive playgrounds, visit the [**Documentation Site**](https://chronos.nazmul-nhb.dev/).
26
76
 
27
- ## Features
77
+ ## License
28
78
 
29
- >[!INFO]
30
- >
31
- > Full Docs Coming Soon...
79
+ This project is licensed under the [Apache License 2.0](LICENSE).
package/dist/plugins/timeZonePlugin.cjs CHANGED
@@ -71,11 +71,16 @@ const timeZonePlugin = ($Chronos) => {
71
71
  }
72
72
  return tzIds;
73
73
  }, /* @__PURE__ */ new Map()));
74
+ const _buildTzNameAbbrMap = () => {
75
+ const result = [];
76
+ for (const [tzAbbr, { offset, tzName }] of Object.entries(require_timezone.TIME_ZONES)) result.unshift([offset, {
77
+ tzAbbr,
78
+ tzName
79
+ }]);
80
+ return result;
81
+ };
74
82
  /** Cache to store time zone name and abbreviation against UTC offset from {@link TIME_ZONES} */
75
- const TZ_NAME_ABBR_MAP = new Map(Object.entries(require_timezone.TIME_ZONES).map(([tzAbbr, { offset, tzName }]) => [offset, {
76
- tzAbbr,
77
- tzName
78
- }]));
83
+ const TZ_NAME_ABBR_MAP = new Map(_buildTzNameAbbrMap());
79
84
  /** Get time zone identifier from {@link TZ_ID_MAP} using UTC offset */
80
85
  const _getTimeZoneId = (utc) => {
81
86
  const tzIds = TZ_ID_MAP.get(utc);
@@ -132,8 +137,8 @@ const timeZonePlugin = ($Chronos) => {
132
137
  if (!utc && tracker && _isValidTzAbbr(tracker)) return tracker;
133
138
  if (require_guards.isValidUTCOffset(tzMapKey)) {
134
139
  if (TZ_ABBR_CACHE.has(tzMapKey)) return TZ_ABBR_CACHE.get(tzMapKey);
135
- if (TZ_NAME_ABBR_MAP.has(tzMapKey)) return TZ_NAME_ABBR_MAP.get(tzMapKey)?.tzAbbr;
136
140
  const tzName = _resolveTzName(tzMapKey);
141
+ if (!tzName && TZ_NAME_ABBR_MAP.has(tzMapKey)) return TZ_NAME_ABBR_MAP.get(tzMapKey)?.tzAbbr;
137
142
  if (tzName) {
138
143
  const tzAbbr = _abbreviate(tzName);
139
144
  TZ_ABBR_CACHE.set(tzMapKey, tzAbbr);
@@ -141,9 +146,10 @@ const timeZonePlugin = ($Chronos) => {
141
146
  }
142
147
  }
143
148
  const zone = _getTimeZoneName(tzMapKey, $Date(this)) ?? UTC;
144
- if (TZ_ABBR_CACHE.has(`name-${zone}`)) return TZ_ABBR_CACHE.get(zone);
149
+ const fallbackKey = `name-${zone}`;
150
+ if (TZ_ABBR_CACHE.has(fallbackKey)) return TZ_ABBR_CACHE.get(fallbackKey);
145
151
  const customAbbr = require_guards.isValidUTCOffset(zone) ? zone : _abbreviate(zone);
146
- TZ_ABBR_CACHE.set(`name-${zone}`, customAbbr);
152
+ TZ_ABBR_CACHE.set(fallbackKey, customAbbr);
147
153
  return customAbbr;
148
154
  };
149
155
  $Chronos.prototype.getTimeZoneNameAbbr = function(utc) {
package/dist/plugins/timeZonePlugin.mjs CHANGED
@@ -70,11 +70,16 @@ const timeZonePlugin = ($Chronos) => {
70
70
  }
71
71
  return tzIds;
72
72
  }, /* @__PURE__ */ new Map()));
73
+ const _buildTzNameAbbrMap = () => {
74
+ const result = [];
75
+ for (const [tzAbbr, { offset, tzName }] of Object.entries(TIME_ZONES)) result.unshift([offset, {
76
+ tzAbbr,
77
+ tzName
78
+ }]);
79
+ return result;
80
+ };
73
81
  /** Cache to store time zone name and abbreviation against UTC offset from {@link TIME_ZONES} */
74
- const TZ_NAME_ABBR_MAP = new Map(Object.entries(TIME_ZONES).map(([tzAbbr, { offset, tzName }]) => [offset, {
75
- tzAbbr,
76
- tzName
77
- }]));
82
+ const TZ_NAME_ABBR_MAP = new Map(_buildTzNameAbbrMap());
78
83
  /** Get time zone identifier from {@link TZ_ID_MAP} using UTC offset */
79
84
  const _getTimeZoneId = (utc) => {
80
85
  const tzIds = TZ_ID_MAP.get(utc);
@@ -131,8 +136,8 @@ const timeZonePlugin = ($Chronos) => {
131
136
  if (!utc && tracker && _isValidTzAbbr(tracker)) return tracker;
132
137
  if (isValidUTCOffset(tzMapKey)) {
133
138
  if (TZ_ABBR_CACHE.has(tzMapKey)) return TZ_ABBR_CACHE.get(tzMapKey);
134
- if (TZ_NAME_ABBR_MAP.has(tzMapKey)) return TZ_NAME_ABBR_MAP.get(tzMapKey)?.tzAbbr;
135
139
  const tzName = _resolveTzName(tzMapKey);
140
+ if (!tzName && TZ_NAME_ABBR_MAP.has(tzMapKey)) return TZ_NAME_ABBR_MAP.get(tzMapKey)?.tzAbbr;
136
141
  if (tzName) {
137
142
  const tzAbbr = _abbreviate(tzName);
138
143
  TZ_ABBR_CACHE.set(tzMapKey, tzAbbr);
@@ -140,9 +145,10 @@ const timeZonePlugin = ($Chronos) => {
140
145
  }
141
146
  }
142
147
  const zone = _getTimeZoneName(tzMapKey, $Date(this)) ?? UTC;
143
- if (TZ_ABBR_CACHE.has(`name-${zone}`)) return TZ_ABBR_CACHE.get(zone);
148
+ const fallbackKey = `name-${zone}`;
149
+ if (TZ_ABBR_CACHE.has(fallbackKey)) return TZ_ABBR_CACHE.get(fallbackKey);
144
150
  const customAbbr = isValidUTCOffset(zone) ? zone : _abbreviate(zone);
145
- TZ_ABBR_CACHE.set(`name-${zone}`, customAbbr);
151
+ TZ_ABBR_CACHE.set(fallbackKey, customAbbr);
146
152
  return customAbbr;
147
153
  };
148
154
  $Chronos.prototype.getTimeZoneNameAbbr = function(utc) {
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "chronos-date",
3
- "version": "1.1.2",
4
- "description": "Flexible date-time library for any JavaScript and TypeScript environment.",
3
+ "version": "1.2.0",
4
+ "description": "A lightweight, immutable, and plugin-based date-time manipulation library for JavaScript and TypeScript.",
5
5
  "main": "./dist/index.cjs",
6
6
  "type": "module",
7
7
  "sideEffects": false,
@@ -32,7 +32,7 @@
32
32
  "type": "git",
33
33
  "url": "git+https://github.com/nazmul-nhb/chronos-date.git"
34
34
  },
35
- "homepage": "https://github.com/nazmul-nhb/chronos-date#readme",
35
+ "homepage": "https://chronos.nazmul-nhb.dev",
36
36
  "author": {
37
37
  "name": "Nazmul Hassan",
38
38
  "email": "nazmulnhb@gmail.com",
@@ -57,7 +57,7 @@
57
57
  "license": "Apache-2.0",
58
58
  "devDependencies": {
59
59
  "@biomejs/biome": "^2.4.15",
60
- "@types/node": "^25.7.0",
60
+ "@types/node": "^25.8.0",
61
61
  "husky": "^9.1.7",
62
62
  "lint-staged": "^17.0.4",
63
63
  "nhb-scripts": "^1.9.2",
@@ -154,7 +154,7 @@
154
154
  "scripts": {
155
155
  "build": "tsdown",
156
156
  "dev:pkg": "tsdown --watch",
157
- "dev:docs": "pnpm --filter chronos-date-docs dev",
157
+ "dev": "pnpm --filter chronos-date-docs dev",
158
158
  "build:docs": "pnpm --filter chronos-date-docs build",
159
159
  "typecheck": "tsc --noEmit",
160
160
  "commit": "nhb-commit",