nhb-toolbox 4.26.1 → 4.26.10

package/CHANGELOG.md

@@ -6,6 +6,30 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.26.10] - 2025-11-09
+
+### 🕧 Updates in Chronos
+
+- **Fixed** *timezone conversion issues* by updating `TIME_ZONE_IDS`, and `TIME_ZONES` constants:
+  - Now both the constants have similar *type definitions* and used with `as const` in the codebase.
+
+    ```ts
+    // Example structure after unification
+    const TIME_ZONE_IDS: Record<string, { tzName: string; offset: UTCOffSet }> = {
+      'Asia/Dhaka': { tzName: 'Bangladesh Standard Time', offset: 'UTC+06:00' },
+      // ...
+    };
+
+    const TIME_ZONES: Record<string, { tzName: string; offset: UTCOffSet }> = {
+      BST: { tzName: 'Bangladesh Standard Time', offset: 'UTC+06:00' },
+      // ...
+    };
+    ```
+
+- **Added** new *protected property* `$tzTracker`. **Updated** `withOrigin` and `#withOrigin` methods.
+- **Added** *3 overload signatures* and *internal caching mechanism* for `timeZonePlugin` methods.
+- **Updated** *tsdoc* for some `Chronos` methods. **Created** new type `TimeZoneName` and *more*.
+
 ## [4.26.1] - 2025-11-08
 
 - **Updated** *tsdoc* for some `Chronos` *methods* and *public properties*.

package/README.md

@@ -45,9 +45,9 @@
   </a>
 </p>
 
-## TypeScript Utility Library
+## JavaScript/TypeScript Utility Library
 
-**NHB Toolbox** provides battle-tested utilities for professional TypeScript development. Carefully crafted to solve common challenges with elegant, production-ready solutions:
+**NHB Toolbox** provides battle-tested utilities for professional JavaScript/TypeScript development. Carefully crafted to solve common challenges with elegant, production-ready solutions:
 
 - **Helper Functions & Classes**: Reusable solutions for everyday tasks
 - **Type Guards & Predicates**: Runtime safety with perfect type inference

package/dist/cjs/date/Chronos.js

@@ -1,7 +1,7 @@
 "use strict";
 var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Chronos = void 0;
+exports.chronos = exports.Chronos = void 0;
 const non_primitives_1 = require("../guards/non-primitives");
 const primitives_1 = require("../guards/primitives");
 const utilities_1 = require("../number/utilities");
@@ -20,8 +20,8 @@ class Chronos {
         offset(instance) {
             return instance.#offset;
         },
-        withOrigin(instance, method, offset, tzName, tzId) {
-            return instance.#withOrigin(method, offset, tzName, tzId);
+        withOrigin(instance, method, offset, tzName, tzId, tzTracker) {
+            return instance.#withOrigin(method, offset, tzName, tzId, tzTracker);
         },
         toNewDate(instance, value) {
             return instance.#toNewDate(value);
@@ -32,6 +32,7 @@ class Chronos {
     utcOffset;
     timeZoneName;
     timeZoneId;
+    $tzTracker;
     constructor(valueOrYear, month, date, hours, minutes, seconds, ms) {
         if (typeof valueOrYear === 'number' && typeof month === 'number') {
             this.#date = new Date(valueOrYear, month - 1, date ?? 1, hours ?? 0, minutes ?? 0, seconds ?? 0, ms ?? 0);
@@ -80,9 +81,9 @@ class Chronos {
             case 'timeZone':
             case 'toUTC':
             case 'utc':
-                return string.replace(this.toISOString().replace(/\.\d+(Z|[+-]\d{2}:\d{2})?$/, ''), replacement);
+                return string.replace(this.#isoTzRemoved(), replacement);
             default:
-                return string.replace(this.toLocalISOString().replace(/\.\d+(Z|[+-]\d{2}:\d{2})?$/, ''), replacement);
+                return string.replace(this.#isoTzRemoved(true), replacement);
         }
     }
     [Symbol.search](string) {
@@ -90,9 +91,9 @@ class Chronos {
             case 'timeZone':
             case 'toUTC':
             case 'utc':
-                return string.indexOf(this.toISOString().replace(/\.\d+(Z|[+-]\d{2}:\d{2})?$/, ''));
+                return string.indexOf(this.#isoTzRemoved());
             default:
-                return string.indexOf(this.toLocalISOString().replace(/\.\d+(Z|[+-]\d{2}:\d{2})?$/, ''));
+                return string.indexOf(this.#isoTzRemoved(true));
         }
     }
     [Symbol.split](string) {
@@ -100,9 +101,9 @@ class Chronos {
             case 'timeZone':
             case 'toUTC':
             case 'utc':
-                return string.split(this.toISOString().replace(/\.\d+(Z|[+-]\d{2}:\d{2})?$/, ''));
+                return string.split(this.#isoTzRemoved());
             default:
-                return string.split(this.toLocalISOString().replace(/\.\d+(Z|[+-]\d{2}:\d{2})?$/, ''));
+                return string.split(this.#isoTzRemoved(true));
         }
     }
     [Symbol.match](string) {
@@ -144,7 +145,7 @@ class Chronos {
         }
         return date;
     }
-    #withOrigin(origin, offset, tzName, tzId) {
+    #withOrigin(origin, offset, tzName, tzId, tzTracker) {
         const instance = new _a(this.#date);
         instance.#ORIGIN = origin;
         instance.origin = origin;
@@ -152,12 +153,12 @@ class Chronos {
             instance.#offset = offset;
             instance.utcOffset = offset;
         }
-        if (tzName) {
+        if (tzName)
             instance.timeZoneName = tzName;
-        }
-        if (tzId) {
+        if (tzId)
             instance.timeZoneId = tzId;
-        }
+        if (tzTracker)
+            instance.$tzTracker = tzTracker;
         instance.native = instance.toDate();
         return instance;
     }
@@ -228,6 +229,11 @@ class Chronos {
         const pad = (n, p = 2) => String(n).padStart(p, '0');
         return `${this.year}-${pad(this.month + 1)}-${pad(this.date)}T${pad(this.hour)}:${pad(this.minute)}:${pad(this.second)}.${pad(this.millisecond, 3)}${this.getUTCOffset()}`;
     }
+    #isoTzRemoved(local = false) {
+        return local ?
+            this.toLocalISOString().replace(/\.\d+(Z|[+-]\d{2}:\d{2})?$/, '')
+            : this.toISOString().replace(/\.\d+(Z|[+-]\d{2}:\d{2})?$/, '');
+    }
     #normalizeDuration(result, absolute, isFuture) {
         const entries = Object.entries(result);
         const updated = { ...result };
@@ -1050,3 +1056,5 @@ class Chronos {
 }
 exports.Chronos = Chronos;
 _a = Chronos;
+var chronos_fn_1 = require("./chronos-fn");
+Object.defineProperty(exports, "chronos", { enumerable: true, get: function () { return chronos_fn_1.chronos; } });

package/dist/cjs/date/guards.js

@@ -7,6 +7,7 @@ exports.isLeapYear = isLeapYear;
 exports.isDateLike = isDateLike;
 const primitives_1 = require("../guards/primitives");
 const specials_1 = require("../guards/specials");
+const utilities_1 = require("../number/utilities");
 const timezone_1 = require("./timezone");
 function isValidTime(value) {
     if (!(0, primitives_1.isString)(value))
@@ -25,7 +26,8 @@ function isValidTimeZoneId(value) {
     return (0, primitives_1.isString)(value) ? value in timezone_1.TIME_ZONE_IDS : false;
 }
 function isLeapYear(year) {
-    return (Number(year) % 4 === 0 && Number(year) % 100 !== 0) || Number(year) % 400 === 0;
+    const $year = (0, utilities_1.normalizeNumber)(year);
+    return $year ? ($year % 4 === 0 && $year % 100 !== 0) || $year % 400 === 0 : false;
 }
 function isDateLike(value) {
     if (value instanceof Date)

package/dist/cjs/date/plugins/timeZonePlugin.js

@@ -8,66 +8,94 @@ const utils_1 = require("../utils");
 const timeZonePlugin = (ChronosClass) => {
     const internal = ChronosClass[constants_1.INTERNALS];
     const $Date = internal.internalDate;
-    const getTimeZoneId = (utc) => {
-        const obj = { ...timezone_1.TIME_ZONE_IDS };
-        const tzIds = Object.keys(obj).filter((key) => obj[key] === utc);
-        if (!tzIds || tzIds.length === 0)
+    const _isLabelKey = (offset) => {
+        return offset in timezone_1.TIME_ZONE_LABELS;
+    };
+    const _resolveTzName = (offset) => {
+        if (_isLabelKey(offset)) {
+            return timezone_1.TIME_ZONE_LABELS[offset];
+        }
+        return undefined;
+    };
+    const _getTimeZoneName = (zone) => {
+        if ((0, guards_1.isValidUTCOffSet)(zone)) {
+            return _resolveTzName(zone);
+        }
+        else if ((0, guards_1.isValidTimeZoneId)(zone)) {
+            const record = timezone_1.TIME_ZONE_IDS[zone];
+            return record?.tzName ?? _resolveTzName(record?.offset);
+        }
+        else {
+            return zone in timezone_1.TIME_ZONES ?
+                timezone_1.TIME_ZONES[zone].tzName
+                : _resolveTzName(timezone_1.TIME_ZONES[zone].offset);
+        }
+    };
+    const TZ_ID_CACHE = new Map(Object.entries(timezone_1.TIME_ZONE_IDS).reduce((acc, [id, { offset }]) => {
+        const arr = acc.get(offset) ?? [];
+        arr.push(id);
+        acc.set(offset, arr);
+        return acc;
+    }, new Map()));
+    const _getTimeZoneId = (utc) => {
+        const tzIds = TZ_ID_CACHE.get(utc);
+        if (!tzIds || tzIds?.length === 0)
             return undefined;
-        if (tzIds.length === 1)
+        if (tzIds?.length === 1)
             return tzIds[0];
         return tzIds;
     };
     ChronosClass.prototype.timeZone = function (zone) {
-        let targetOffset;
-        let stringOffset;
+        let offset;
         let tzId;
         if ((0, guards_1.isValidUTCOffSet)(zone)) {
-            targetOffset = (0, utils_1.extractMinutesFromUTC)(zone);
-            stringOffset = zone;
-            tzId = getTimeZoneId(stringOffset) || stringOffset;
+            offset = zone;
+            tzId = _getTimeZoneId(offset) || offset;
         }
         else if ((0, guards_1.isValidTimeZoneId)(zone)) {
-            stringOffset = timezone_1.TIME_ZONE_IDS[zone];
-            targetOffset = (0, utils_1.extractMinutesFromUTC)(stringOffset);
+            offset = timezone_1.TIME_ZONE_IDS[zone].offset;
             tzId = zone;
         }
         else {
-            targetOffset = timezone_1.TIME_ZONES?.[zone] ?? timezone_1.TIME_ZONES['UTC'];
-            stringOffset = (0, utils_1.formatUTCOffset)(targetOffset);
-            tzId = getTimeZoneId(stringOffset) || stringOffset;
+            offset = zone in timezone_1.TIME_ZONES ? timezone_1.TIME_ZONES[zone].offset : timezone_1.TIME_ZONES['UTC'].offset;
+            tzId = _getTimeZoneId(offset) || offset;
         }
+        const tzName = _getTimeZoneName(zone) ?? timezone_1.TIME_ZONES['UTC'].offset;
+        const targetOffset = (0, utils_1.extractMinutesFromUTC)(offset);
         const previousOffset = this.getTimeZoneOffsetMinutes();
         const relativeOffset = targetOffset - previousOffset;
         const adjustedTime = new Date($Date(this).getTime() + relativeOffset * 60 * 1000);
         const instance = new ChronosClass(adjustedTime);
-        return internal.withOrigin(instance, 'timeZone', stringOffset, this.getTimeZoneName(stringOffset), tzId);
+        return internal.withOrigin(instance, `timeZone`, offset, tzName, tzId, zone);
     };
     ChronosClass.prototype.getTimeZoneName = function (utc) {
-        const UTC = utc ?? `UTC${this.getTimeZoneOffset()}`;
-        return timezone_1.TIME_ZONE_LABELS?.[UTC] ?? UTC;
+        const UTC = utc ?? this.utcOffset;
+        return _getTimeZoneName(this?.$tzTracker ?? UTC) ?? UTC;
     };
+    const TZ_SHORT_CACHE = new Map();
     ChronosClass.prototype.getTimeZoneNameShort = function (utc) {
-        const mins = utc ? (0, utils_1.extractMinutesFromUTC)(utc) : this.getTimeZoneOffsetMinutes();
-        const UTC = (0, utils_1.formatUTCOffset)(mins);
-        const timeZone = timezone_1.TIME_ZONE_LABELS?.[UTC];
-        let result = timeZone
-            ?.split(/\s+/)
-            ?.filter(Boolean)
-            ?.map((part) => part?.[0])
-            ?.join('')
-            ?.replace(/\W/g, '');
-        if (!result) {
-            const zones = Object.entries(timezone_1.TIME_ZONES);
-            result = zones.find((zone) => zone?.[1] === mins)?.[0];
-        }
-        return result ?? (0, utils_1.formatUTCOffset)(mins);
+        const tracker = this?.$tzTracker;
+        if (!utc && tracker && tracker in timezone_1.TIME_ZONES)
+            return tracker;
+        const zone = this.getTimeZoneName(utc);
+        if (TZ_SHORT_CACHE.has(zone))
+            return TZ_SHORT_CACHE.get(zone);
+        const customAbbr = (0, guards_1.isValidUTCOffSet)(zone) || (0, guards_1.isValidTimeZoneId)(zone) ?
+            zone
+            : zone
+                .split(/\s+/)
+                .map((w) => w?.[0])
+                .join('')
+                .replace(/\W/g, '');
+        TZ_SHORT_CACHE.set(zone, customAbbr);
+        return customAbbr;
     };
     ChronosClass.prototype.toString = function () {
-        const offset = internal.offset(this);
+        const offset = this.utcOffset;
         switch (this.origin) {
             case 'timeZone': {
                 const gmt = offset.replace('UTC', 'GMT').replace(':', '');
-                const label = timezone_1.TIME_ZONE_LABELS[offset] ?? offset;
+                const label = this.getTimeZoneName();
                 return $Date(this)
                     .toString()
                     .replace(/GMT[+-]\d{4}\s+\([^)]+\)/, `${gmt} (${label})`);