nhb-toolbox 4.21.4 → 4.21.11

package/CHANGELOG.md

@@ -6,6 +6,11 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.21.10] - 2025-10-13
+
+- **Moved** `round` method to `Chronos` *plugin system*, usable via `roundPlugin`.
+- **Updated** *tsdoc* for some `Chronos` methods with *proper references.*
+
 ## [4.21.4] - 2025-10-13
 
 - **Added** new type `$UTCOffset` and applied in corresponding `Chronos` methods.

package/README.md

@@ -7,8 +7,8 @@
   <a href="https://www.npmjs.com/package/nhb-toolbox" aria-label="NPM Downloads">
     <img src="https://img.shields.io/npm/dm/nhb-toolbox.svg?label=DOWNLOADS&style=flat&color=red&logo=npm" alt="Downloads" />
   </a>
-  <a href="https://www.npmjs.com/package/nhb-toolbox" aria-label="NPM Version">
-    <img src="https://img.shields.io/npm/v/nhb-toolbox.svg?label=VERSION&style=flat&color=teal&logo=npm" alt="Latest Version" />
+  <a href="https://www.npmjs.com/package/nhb-toolbox" aria-label="Latest Version">
+    <img src="https://img.shields.io/npm/v/nhb-toolbox.svg?label=NPM&style=flat&color=teal&logo=npm" alt="Latest Version" />
   </a>
   <a href="https://bundlephobia.com/result?p=nhb-toolbox" aria-label="Bundle Size">
     <img src="https://img.shields.io/bundlephobia/minzip/nhb-toolbox?style=flat&color=purple&label=SIZE&logo=nodedotjs" alt="Bundle Size" />
@@ -88,15 +88,15 @@ yarn add nhb-toolbox
 
 ---
 
+### Installing from GitHub Packages
+  
+GitHub Packages requires authentication and scoped package names.
+
 <details>
 
   <summary>
-
-### Installing from GitHub Packages
-
+    <strong>Details</strong>
   </summary>
-  
-GitHub Packages requires authentication and scoped package names.
 
 #### Step 1: Authenticate with GitHub Packages
 
@@ -172,7 +172,7 @@ Example `.npmrc` snippet:
 
 | Registry        | Package Name              | Registry URL                                             | Requires Auth?                 |
 | --------------- | ------------------------- | -------------------------------------------------------- | ------------------------------ |
-| NPM Registry       | `nhb-toolbox`             | [https://registry.npmjs.org](https://registry.npmjs.org) | No                             |
+| NPM Registry    | `nhb-toolbox`             | [https://registry.npmjs.org](https://registry.npmjs.org) | No                             |
 | GitHub Packages | `@nazmul-nhb/nhb-toolbox` | [https://npm.pkg.github.com](https://npm.pkg.github.com) | Yes (PAT with `read:packages`) |
 
 ---

package/dist/cjs/date/Chronos.js

@@ -432,6 +432,8 @@ class Chronos {
                 return t > s && t <= e;
             case '()':
                 return t > s && t < e;
+            default:
+                return false;
         }
     }
     isDST() {
@@ -736,81 +738,6 @@ class Chronos {
         const localTime = new Date(this.#date.getTime() - relativeOffset * 60 * 1000);
         return new _a(localTime).#withOrigin('toLocal');
     }
-    round(unit, nearest = 1) {
-        const date = new Date(this.#date);
-        switch (unit) {
-            case 'millisecond': {
-                const rounded = (0, utilities_1.roundToNearest)(date.getMilliseconds(), nearest);
-                date.setMilliseconds(rounded);
-                break;
-            }
-            case 'second': {
-                const fullSecond = date.getSeconds() + date.getMilliseconds() / 1000;
-                const rounded = (0, utilities_1.roundToNearest)(fullSecond, nearest);
-                date.setSeconds(rounded, 0);
-                break;
-            }
-            case 'minute': {
-                const fullMinute = date.getMinutes() + date.getSeconds() / 60 + date.getMilliseconds() / 60000;
-                const rounded = (0, utilities_1.roundToNearest)(fullMinute, nearest);
-                date.setMinutes(rounded, 0, 0);
-                break;
-            }
-            case 'hour': {
-                const fullHour = date.getHours() +
-                    date.getMinutes() / 60 +
-                    date.getSeconds() / 3600 +
-                    date.getMilliseconds() / 3600000;
-                const rounded = (0, utilities_1.roundToNearest)(fullHour, nearest);
-                date.setHours(rounded, 0, 0, 0);
-                break;
-            }
-            case 'day': {
-                const fullDay = date.getDate() +
-                    (date.getHours() / 24 +
-                        date.getMinutes() / 1440 +
-                        date.getSeconds() / 86400 +
-                        date.getMilliseconds() / 86400000);
-                const rounded = (0, utilities_1.roundToNearest)(fullDay, nearest);
-                date.setDate(rounded);
-                date.setHours(0, 0, 0, 0);
-                break;
-            }
-            case 'week': {
-                const weekday = this.#date.getDay();
-                const offsetToMonday = (weekday + 6) % 7;
-                const startOfWeek = new Date(this.#date);
-                startOfWeek.setDate(startOfWeek.getDate() - offsetToMonday);
-                startOfWeek.setHours(0, 0, 0, 0);
-                const endOfWeek = new Date(startOfWeek);
-                endOfWeek.setDate(endOfWeek.getDate() + 7);
-                const diffToStart = Math.abs(this.#date.getTime() - startOfWeek.getTime());
-                const diffToEnd = Math.abs(endOfWeek.getTime() - this.#date.getTime());
-                const rounded = diffToEnd < diffToStart ? endOfWeek : startOfWeek;
-                return new _a(rounded).#withOrigin('round');
-            }
-            case 'month': {
-                const fullMonth = date.getMonth() + date.getDate() / this.lastDateOfMonth;
-                const roundedMonth = (0, utilities_1.roundToNearest)(fullMonth, nearest);
-                date.setMonth(roundedMonth, 1);
-                date.setHours(0, 0, 0, 0);
-                break;
-            }
-            case 'year': {
-                const dayOfYear = Math.floor((date.getTime() - new Date(date.getFullYear(), 0, 1).getTime()) / 86400000);
-                const isLeap = new Date(date.getFullYear(), 1, 29).getDate() === 29;
-                const totalDays = isLeap ? 366 : 365;
-                const fullYear = date.getFullYear() + dayOfYear / totalDays;
-                const roundedYear = (0, utilities_1.roundToNearest)(fullYear, nearest);
-                date.setFullYear(roundedYear, 0, 1);
-                date.setHours(0, 0, 0, 0);
-                break;
-            }
-            default:
-                return this;
-        }
-        return new _a(date).#withOrigin('round');
-    }
     duration(toTime, absolute = true) {
         const now = this.#date;
         const target = this.#toNewDate(toTime);

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

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.roundPlugin = void 0;
+const utilities_1 = require("../../number/utilities");
+const constants_1 = require("../constants");
+const roundPlugin = (ChronosClass) => {
+    const internal = ChronosClass[constants_1.INTERNALS];
+    ChronosClass.prototype.round = function (unit, nearest = 1) {
+        const date = internal.internalDate(this);
+        switch (unit) {
+            case 'millisecond': {
+                const rounded = (0, utilities_1.roundToNearest)(date.getMilliseconds(), nearest);
+                date.setMilliseconds(rounded);
+                break;
+            }
+            case 'second': {
+                const fullSecond = date.getSeconds() + date.getMilliseconds() / 1000;
+                const rounded = (0, utilities_1.roundToNearest)(fullSecond, nearest);
+                date.setSeconds(rounded, 0);
+                break;
+            }
+            case 'minute': {
+                const fullMinute = date.getMinutes() + date.getSeconds() / 60 + date.getMilliseconds() / 60000;
+                const rounded = (0, utilities_1.roundToNearest)(fullMinute, nearest);
+                date.setMinutes(rounded, 0, 0);
+                break;
+            }
+            case 'hour': {
+                const fullHour = date.getHours() +
+                    date.getMinutes() / 60 +
+                    date.getSeconds() / 3600 +
+                    date.getMilliseconds() / 3600000;
+                const rounded = (0, utilities_1.roundToNearest)(fullHour, nearest);
+                date.setHours(rounded, 0, 0, 0);
+                break;
+            }
+            case 'day': {
+                const fullDay = date.getDate() +
+                    (date.getHours() / 24 +
+                        date.getMinutes() / 1440 +
+                        date.getSeconds() / 86400 +
+                        date.getMilliseconds() / 86400000);
+                const rounded = (0, utilities_1.roundToNearest)(fullDay, nearest);
+                date.setDate(rounded);
+                date.setHours(0, 0, 0, 0);
+                break;
+            }
+            case 'week': {
+                const weekday = date.getDay();
+                const offsetToMonday = (weekday + 6) % 7;
+                const startOfWeek = new Date(date);
+                startOfWeek.setDate(startOfWeek.getDate() - offsetToMonday);
+                startOfWeek.setHours(0, 0, 0, 0);
+                const endOfWeek = new Date(startOfWeek);
+                endOfWeek.setDate(endOfWeek.getDate() + 7);
+                const diffToStart = Math.abs(date.getTime() - startOfWeek.getTime());
+                const diffToEnd = Math.abs(endOfWeek.getTime() - date.getTime());
+                const rounded = diffToEnd < diffToStart ? endOfWeek : startOfWeek;
+                return internal.withOrigin(new ChronosClass(rounded), 'round');
+            }
+            case 'month': {
+                const fullMonth = date.getMonth() + date.getDate() / this.lastDateOfMonth;
+                const roundedMonth = (0, utilities_1.roundToNearest)(fullMonth, nearest);
+                date.setMonth(roundedMonth, 1);
+                date.setHours(0, 0, 0, 0);
+                break;
+            }
+            case 'year': {
+                const dayOfYear = Math.floor((date.getTime() - new Date(date.getFullYear(), 0, 1).getTime()) / 86400000);
+                const isLeap = new Date(date.getFullYear(), 1, 29).getDate() === 29;
+                const totalDays = isLeap ? 366 : 365;
+                const fullYear = date.getFullYear() + dayOfYear / totalDays;
+                const roundedYear = (0, utilities_1.roundToNearest)(fullYear, nearest);
+                date.setFullYear(roundedYear, 0, 1);
+                date.setHours(0, 0, 0, 0);
+                break;
+            }
+            default:
+                return this;
+        }
+        return internal.withOrigin(new ChronosClass(date), 'round');
+    };
+};
+exports.roundPlugin = roundPlugin;

package/dist/dts/date/Chronos.d.ts

@@ -12,7 +12,7 @@ import type { $UTCOffset, ChronosInput, ChronosInternals, ChronosMethods, Chrono
  * - If a string is provided, it should be in a format that can be parsed by the Date constructor.
  * - If a number is provided, it should be a timestamp (milliseconds since the Unix epoch).
  * - If a Date object is provided, it will be used as is.
- * - If a Chronos object is provided, it will be converted to a Date object.
+ * - If a `Chronos` object is provided, it will be converted to a Date object.
  *
  * **It also accepts number values as following:**
  * - **`year, month, date, hours, minutes, seconds, milliseconds`**: Individual components of a date-time to construct a `Chronos` instance.
@@ -31,7 +31,7 @@ export declare class Chronos {
     /** Use `readonly and/or private` methods outside `Chronos`. Purpose: Plugin creation. */
     protected static [INTERNALS]: ChronosInternals;
     /**
-     * * Chronos date/time in Native JS `Date` format.
+     * * `Chronos` date/time in Native JS `Date` format.
      *
      * - **NOTE**: It is **HIGHLY** advised *not to rely* on this public property to access native JS `Date`. It's not reliable when timezone and/or UTC related operations are performed. If you really need to use native `Date`, use `toDate` method.  THis property is purely for developer convenience and sugar.
      */
@@ -94,12 +94,12 @@ export declare class Chronos {
      * and convert it to the **equivalent local time** using the current environment's UTC offset.*
      *
      * @param year The full year designation is required for cross-century date accuracy. If year is between 0 and 99, year is assumed to be 1900 + year.
-     * @param month The month as a number between 1 and 12 (January to December).
-     * @param date The date as a number between 1 and 31.
-     * @param hours Must be supplied if minutes is supplied. A number from 0 to 23 (midnight to 11pm) that specifies the hour.
-     * @param minutes Must be supplied if seconds is supplied. A number from 0 to 59 that specifies the minutes.
-     * @param seconds Must be supplied if milliseconds is supplied. A number from 0 to 59 that specifies the seconds.
-     * @param ms A number from 0 to 999 that specifies the milliseconds.
+     * @param month The month as a `number` between 1 and 12 (January to December).
+     * @param date The date as a `number` between 1 and 31.
+     * @param hours Must be supplied if minutes is supplied. A `number` from 0 to 23 (midnight to 11pm) that specifies the hour.
+     * @param minutes Must be supplied if seconds is supplied. A `number` from 0 to 59 that specifies the minutes.
+     * @param seconds Must be supplied if milliseconds is supplied. A `number` from 0 to 59 that specifies the seconds.
+     * @param ms A `number` from 0 to 999 that specifies the milliseconds.
      *
      * @returns Instance of `Chronos` with all methods and properties.
      */
@@ -111,10 +111,10 @@ export declare class Chronos {
      * and convert it to the **equivalent local time** using the current environment's UTC offset.*
      *
      * @param value - A date value (`number`, `string`, `Date`, or `Chronos` object).
-     * - If a string is provided, it should be in a format that can be parsed by the `Date` constructor.
-     * - If a number is provided, it should be a timestamp (milliseconds since the Unix epoch).
-     * - If a Date object is provided, it will be used as is.
-     * - If a Chronos object is provided, it will be used directly.
+     * - If a `string` is provided, it should be in a format that can be parsed by the `Date` constructor.
+     * - If a `number` is provided, it should be a timestamp (milliseconds since the Unix epoch).
+     * - If a `Date` object is provided, it will be used as is.
+     * - If a `Chronos` object is provided, it will be used directly.
      *
      * @returns Instance of `Chronos` with all methods and properties.
      */
@@ -164,7 +164,7 @@ export declare class Chronos {
     toJSON(): string;
     /** @instance Enables arithmetic and comparison operations (e.g., +new Chronos()). */
     valueOf(): number;
-    /** @instance Clones and returns a new Chronos instance with the same date. */
+    /** @instance Clones and returns a new `Chronos` instance with the same date. */
     clone(): Chronos;
     /** @instance Gets the native `Date` instance (read-only). */
     toDate(): Date;
@@ -206,7 +206,7 @@ export declare class Chronos {
     /**
      * @instance Formats the date into a predefined strict string format using local time or UTC.
      *
-     * @remarks Offers over 21,000 predefined formats with full IntelliSense support.
+     * @remarks Offers `over 21,000` predefined formats with full IntelliSense support.
      *
      * @param format - The desired format string. Defaults to `'dd, mmm DD, YYYY HH:mm:ss'`
      *                 (e.g., `'Sun, Apr 06, 2025 16:11:55'`).
@@ -346,30 +346,30 @@ export declare class Chronos {
     isFirstDayOfMonth(): boolean;
     /** @instance Checks if current day is the last day of the current month. */
     isLastDayOfMonth(): boolean;
-    /** @instance Returns a new Chronos instance set to the first day of the current month. */
+    /** @instance Returns a new `Chronos` instance set to the first day of the current month. */
     firstDayOfMonth(): Chronos;
-    /** @instance Returns a new Chronos instance set to the last day of the current month. */
+    /** @instance Returns a new `Chronos` instance set to the last day of the current month. */
     lastDayOfMonth(): Chronos;
     /**
-     * @instance Returns a new Chronos instance at the start of a given unit.
+     * @instance Returns a new `Chronos` instance at the start of a given unit.
      * @param unit The unit to reset (e.g., year, month, day).
      * @param weekStartsOn Optional: Day the week starts on (0 = Sunday, 1 = Monday). Applicable if week day is required. Default is `0`.
      */
     startOf(unit: TimeUnit, weekStartsOn?: Enumerate<7>): Chronos;
     /**
-     * @instance Returns a new Chronos instance at the end of a given unit.
+     * @instance Returns a new `Chronos` instance at the end of a given unit.
      * @param unit The unit to adjust (e.g., year, month, day).
      * @param weekStartsOn Optional: Day the week starts on (0 = Sunday, 1 = Monday). Applicable if week day is required. Default is `0`.
      */
     endOf(unit: TimeUnit, weekStartsOn?: Enumerate<7>): Chronos;
     /**
-     * @instance Returns a new Chronos instance with the specified unit added.
+     * @instance Returns a new `Chronos` instance with the specified unit added.
      * @param number The number of time unit to add (can be negative).
      * @param unit The time unit to add.
      */
     add(number: number, unit: TimeUnit): Chronos;
     /**
-     * @instance Returns a new Chronos instance with the specified unit subtracted.
+     * @instance Returns a new `Chronos` instance with the specified unit subtracted.
      * @param number The number of time unit to subtract (can be negative).
      * @param unit The time unit to add.
      */
@@ -380,7 +380,7 @@ export declare class Chronos {
      */
     get(unit: TimeUnit): number;
     /**
-     * @instance Returns a new Chronos instance with the specified unit set to the given value.
+     * @instance Returns a new `Chronos` instance with the specified unit set to the given value.
      * @param unit The unit to modify.
      * @param value The value to set for the unit.
      */
@@ -403,7 +403,7 @@ export declare class Chronos {
      * This method assumes ISO week logic, where week 1 is the week containing January 4th.
      *
      * @param week The ISO week number (1–53) to set the date to.
-     * @returns A new Chronos instance set to the start (Monday) of the specified week.
+     * @returns A new `Chronos` instance set to the start (Monday) of the specified week.
      */
     setWeek(week: NumberRange<1, 53>): Chronos;
     /**
@@ -462,7 +462,7 @@ export declare class Chronos {
     /**
      * @instance Returns the system's current UTC offset formatted as `+06:00` or `-07:00`.
      *
-     * - *Unlike `Date.prototype.getTimezoneOffset()`, which returns the offset in minutes **behind** UTC (positive for locations west of UTC and negative for east), this method returns the more intuitive sign format used in time zone representations (e.g., `UTC+06:00` means 6 hours **ahead** of UTC).*
+     * - *Unlike JavaScript's {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTimezoneOffset `Date.prototype.getTimezoneOffset()`}, which returns the offset in minutes **behind** UTC (positive for locations west of UTC and negative for east), this method returns the more intuitive sign format used in time zone representations (e.g., `+06:00` means 6 hours **ahead** of UTC).*
      *
      * @returns The (local) system's UTC offset in `±HH:mm` format.
      */
@@ -470,7 +470,7 @@ export declare class Chronos {
     /**
      * @instance Returns the timezone offset of this `Chronos` instance in `+06:00` or `-07:00` format maintaining current timezone.
      *
-     * - *Unlike `Date.prototype.getTimezoneOffset()`, which returns the offset in minutes **behind** UTC (positive for locations west of UTC and negative for east), this method returns the more intuitive sign format used in time zone representations (e.g., `UTC+06:00` means 6 hours **ahead** of UTC).*
+     * - *Unlike JavaScript's {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTimezoneOffset Date.prototype.getTimezoneOffset()}, which returns the offset in minutes **behind** UTC (positive for locations west of UTC and negative for east), this method returns the more intuitive sign format used in time zone representations (e.g., `+06:00` means 6 hours **ahead** of UTC).*
      *
      * @returns The timezone offset string in `±HH:mm` format maintaining the current timezone regardless of system having different one.
      */
@@ -478,7 +478,7 @@ export declare class Chronos {
     /**
      * @instance Returns the system's UTC offset in minutes.
      *
-     * - *Unlike JavaScript's `Date.prototype.getTimezoneOffset()`, this method returns a positive value if the local time is ahead of UTC, and negative if behind UTC.*
+     * - *Unlike JavaScript's {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTimezoneOffset Date.prototype.getTimezoneOffset()}, this method returns a positive value if the local time is ahead of UTC, and negative if behind UTC.*
      *
      * For example, for `UTC+06:00`, this returns `360`; for `UTC-05:30`, this returns `-330`.
      *
@@ -488,7 +488,7 @@ export declare class Chronos {
     /**
      * @instance Returns the current `Chronos` instance's UTC offset in minutes.
      *
-     * This reflects the parsed or stored offset used internally by Chronos and follows the same
+     * This reflects the parsed or stored offset used internally by `Chronos` and follows the same
      * sign convention: positive for timezones ahead of UTC, negative for behind.
      *
      * @returns The UTC offset in minutes maintaining the current timezone regardless of system having different one.
@@ -504,28 +504,10 @@ export declare class Chronos {
      * - If no match is found (which is rare), it falls back to returning the UTC offset (e.g. `"UTC+06:00"`).
      */
     getTimeZoneName(utc?: UTCOffSet): LooseLiteral<UTCOffSet>;
-    /** @instance Returns new Chronos instance in UTC */
+    /** @instance Returns new `Chronos` instance in UTC */
     toUTC(): Chronos;
-    /** @instance Returns new Chronos instance in local time */
+    /** @instance Returns new `Chronos` instance in local time */
     toLocal(): Chronos;
-    /**
-     * @instance Rounds the current date-time to the nearest specified unit and interval.
-     *
-     * - *Rounding is based on proximity to the start or end of the specified unit.*
-     * - *For example, rounding `2025-05-23` by 'day' returns either midnight of May 23 or May 24, depending on the time of day.*
-     *
-     * @param unit - The time unit to round to (`year`, `month`, `week`, `day`, `hour`, `minute`, `second`, `millisecond`).
-     * @param nearest - Optional granularity of rounding. (Defaults to `1`).
-     *
-     * @returns A new `Chronos` instance at the nearest rounded point in time. For wrong unit returns current instance.
-     *
-     * @remarks
-     * - Rounding for `'month'` is based on how far into the month the date is. If past the midpoint, it rounds to the next month.
-     *   - Month indices are 0-based internally (January = 0), but the resulting date reflects the correct calendar month.
-     * - For `'week'` unit, rounding is performed by comparing proximity to the start and end of the ISO week (Monday to Sunday).
-     *   - If the date is closer to the next Monday, it rounds forward; otherwise, it rounds back to the previous Monday.
-     */
-    round(unit: TimeUnit, nearest?: number): Chronos;
     /**
      * @instance Returns the full time duration breakdown between current input (start) and another time (to).
      * @param toTime The time to compare with. Defaults to now.
@@ -535,14 +517,14 @@ export declare class Chronos {
     duration(toTime?: ChronosInput, absolute?: boolean): TimeDuration;
     /**
      * @instance Returns the name of the current day or optional day index.
-     * @param index Optional day index (0–6, where 0 is Sunday) to override current day.
-     * @returns Name of the weekday.
+     * @param index Optional day index (`0–6`, where `0` is `Sunday`) to override current day.
+     * @returns Name of the weekday, e.g., `'Monday'`, `'Tuesday'` etc.
      */
     day(index?: Enumerate<7>): WeekDay;
     /**
      * @instance Returns the name of the current month or optional month index.
-     * @param index Optional month index (0–11, where 0 is January) to override current month.
-     * @returns Name of the month.
+     * @param index Optional month index (`0–11`, where `0` is `January`) to override current month.
+     * @returns Name of the month, e.g., `'January'`, `'February'` etc.
      */
     monthName(index?: Enumerate<12>): MonthName;
     /**
@@ -621,7 +603,7 @@ export declare class Chronos {
      * **Example**:
      * ```ts
      * Chronos.parse('23-12-31 15:30:45', 'YY-MM-DD HH:mm:ss');
-     * // returns Chronos instance with the parsed date 2023-12-31T15:30:45
+     * // returns `Chronos` instance with the parsed date 2023-12-31T15:30:45
      * ```
      *
      * @param dateStr - The date string to be parsed
@@ -675,14 +657,14 @@ export declare class Chronos {
      */
     static now(): number;
     /**
-     * @static Creates a UTC-based Chronos instance.
+     * @static Creates a UTC-based `Chronos` instance.
      * If no date is provided, it uses the current date and time.
      *
      * **This is the base time, meaning conversion in other timezone will consider UTC time as the base time.**
      *
      * @param dateLike Optional input date to base the UTC time on.
      * If omitted, the current system date/time is used.
-     * @returns A new Chronos instance representing the UTC equivalent of the input.
+     * @returns A new `Chronos` instance representing the UTC equivalent of the input.
      */
     static utc(dateLike?: ChronosInput): Chronos;
     /**
@@ -789,7 +771,7 @@ export declare class Chronos {
     static isDateString(value: unknown): value is string;
     /**
      * @static Checks if the given value is an instance of `Chronos`.
-     * - Useful for verifying Chronos objects in type guards or validations.
+     * - Useful for verifying `Chronos` objects in type guards or validations.
      * @param value - The value to test.
      * @returns `true` if the value is an instance of `Chronos`, otherwise `false`.
      */

package/dist/dts/date/plugins/roundPlugin.d.ts

@@ -0,0 +1,28 @@
+import type { TimeUnit } from '../types';
+type ChronosConstructor = import('../Chronos').Chronos;
+type MainChronos = typeof import('../Chronos').Chronos;
+declare module '../Chronos' {
+    interface Chronos {
+        /**
+         * @instance Rounds the current date-time to the nearest specified unit and interval.
+         *
+         * - *Rounding is based on proximity to the start or end of the specified unit.*
+         * - *For example, rounding `2025-05-23` by 'day' returns either midnight of May 23 or May 24, depending on the time of day.*
+         *
+         * @param unit - The time unit to round to (`year`, `month`, `week`, `day`, `hour`, `minute`, `second`, `millisecond`).
+         * @param nearest - Optional granularity of rounding. (Defaults to `1`).
+         *
+         * @returns A new `Chronos` instance at the nearest rounded point in time. For wrong unit returns current instance.
+         *
+         * @remarks
+         * - Rounding for `'month'` is based on how far into the month the date is. If past the midpoint, it rounds to the next month.
+         *   - Month indices are 0-based internally (January = 0), but the resulting date reflects the correct calendar month.
+         * - For `'week'` unit, rounding is performed by comparing proximity to the start and end of the ISO week (Monday to Sunday).
+         *   - If the date is closer to the next Monday, it rounds forward; otherwise, it rounds back to the previous Monday.
+         */
+        round(unit: TimeUnit, nearest?: number): ChronosConstructor;
+    }
+}
+/** * Plugin to inject `round` method */
+export declare const roundPlugin: (ChronosClass: MainChronos) => void;
+export {};

package/dist/dts/date/types.d.ts

@@ -132,7 +132,7 @@ export interface ChronosInternals {
      * @param label - Optional UTC offset label
      * @returns A new Chronos instance
      */
-    withOrigin(instance: Chronos, method: ChronosMethods, label?: UTCOffSet): Chronos;
+    withOrigin(instance: Chronos, method: PluginMethods, label?: UTCOffSet): Chronos;
     /**
      * * Access to `#toNewDate` private method
      * * Creates a new `Date` object from a Chronos input
@@ -171,7 +171,9 @@ export type $StaticMethods = {
     } ? Method : never;
 }[keyof $Chronos];
 /** * Plugin methods that return `Chronos` instance */
-export type $PluginMethods = LooseLiteral<'timeZone'>;
+export type $PluginMethods = 'timeZone' | 'round';
+/** * Plugin methods that return `Chronos` instance + any custom name */
+export type PluginMethods = LooseLiteral<'timeZone' | 'round'>;
 /** Methods (both instance and static) in `Chronos` class that return `Chronos` instance. */
 export type ChronosMethods = $InstanceMethods | $StaticMethods | $PluginMethods;
 /**
@@ -394,7 +396,7 @@ export interface DateLike {
 /**
  * * Options for `Chronos` _static_ method `with()`
  *
- * @remarks Should provide at least one property.
+ * @remarks Should provide at least one property, otherwise use the current date and time.
  */
 export type ChronosWithOptions = Partial<{
     /** The full year (e.g., 2025). Years 0–99 are interpreted as 1900–1999. */

package/dist/esm/date/Chronos.js

@@ -1,7 +1,7 @@
 var _a;
 import { isValidArray } from '../guards/non-primitives.js';
 import { isString } from '../guards/primitives.js';
-import { getOrdinal, roundToNearest } from '../number/utilities.js';
+import { getOrdinal } from '../number/utilities.js';
 import { DAYS, INTERNALS, MONTHS, SORTED_TIME_FORMATS, TIME_ZONE_LABELS } from './constants.js';
 import { isLeapYear } from './guards.js';
 import { extractMinutesFromUTC } from './utils.js';
@@ -429,6 +429,8 @@ export class Chronos {
                 return t > s && t <= e;
             case '()':
                 return t > s && t < e;
+            default:
+                return false;
         }
     }
     isDST() {
@@ -733,81 +735,6 @@ export class Chronos {
         const localTime = new Date(this.#date.getTime() - relativeOffset * 60 * 1000);
         return new _a(localTime).#withOrigin('toLocal');
     }
-    round(unit, nearest = 1) {
-        const date = new Date(this.#date);
-        switch (unit) {
-            case 'millisecond': {
-                const rounded = roundToNearest(date.getMilliseconds(), nearest);
-                date.setMilliseconds(rounded);
-                break;
-            }
-            case 'second': {
-                const fullSecond = date.getSeconds() + date.getMilliseconds() / 1000;
-                const rounded = roundToNearest(fullSecond, nearest);
-                date.setSeconds(rounded, 0);
-                break;
-            }
-            case 'minute': {
-                const fullMinute = date.getMinutes() + date.getSeconds() / 60 + date.getMilliseconds() / 60000;
-                const rounded = roundToNearest(fullMinute, nearest);
-                date.setMinutes(rounded, 0, 0);
-                break;
-            }
-            case 'hour': {
-                const fullHour = date.getHours() +
-                    date.getMinutes() / 60 +
-                    date.getSeconds() / 3600 +
-                    date.getMilliseconds() / 3600000;
-                const rounded = roundToNearest(fullHour, nearest);
-                date.setHours(rounded, 0, 0, 0);
-                break;
-            }
-            case 'day': {
-                const fullDay = date.getDate() +
-                    (date.getHours() / 24 +
-                        date.getMinutes() / 1440 +
-                        date.getSeconds() / 86400 +
-                        date.getMilliseconds() / 86400000);
-                const rounded = roundToNearest(fullDay, nearest);
-                date.setDate(rounded);
-                date.setHours(0, 0, 0, 0);
-                break;
-            }
-            case 'week': {
-                const weekday = this.#date.getDay();
-                const offsetToMonday = (weekday + 6) % 7;
-                const startOfWeek = new Date(this.#date);
-                startOfWeek.setDate(startOfWeek.getDate() - offsetToMonday);
-                startOfWeek.setHours(0, 0, 0, 0);
-                const endOfWeek = new Date(startOfWeek);
-                endOfWeek.setDate(endOfWeek.getDate() + 7);
-                const diffToStart = Math.abs(this.#date.getTime() - startOfWeek.getTime());
-                const diffToEnd = Math.abs(endOfWeek.getTime() - this.#date.getTime());
-                const rounded = diffToEnd < diffToStart ? endOfWeek : startOfWeek;
-                return new _a(rounded).#withOrigin('round');
-            }
-            case 'month': {
-                const fullMonth = date.getMonth() + date.getDate() / this.lastDateOfMonth;
-                const roundedMonth = roundToNearest(fullMonth, nearest);
-                date.setMonth(roundedMonth, 1);
-                date.setHours(0, 0, 0, 0);
-                break;
-            }
-            case 'year': {
-                const dayOfYear = Math.floor((date.getTime() - new Date(date.getFullYear(), 0, 1).getTime()) / 86400000);
-                const isLeap = new Date(date.getFullYear(), 1, 29).getDate() === 29;
-                const totalDays = isLeap ? 366 : 365;
-                const fullYear = date.getFullYear() + dayOfYear / totalDays;
-                const roundedYear = roundToNearest(fullYear, nearest);
-                date.setFullYear(roundedYear, 0, 1);
-                date.setHours(0, 0, 0, 0);
-                break;
-            }
-            default:
-                return this;
-        }
-        return new _a(date).#withOrigin('round');
-    }
     duration(toTime, absolute = true) {
         const now = this.#date;
         const target = this.#toNewDate(toTime);

package/dist/esm/date/plugins/roundPlugin.js

@@ -0,0 +1,80 @@
+import { roundToNearest } from '../../number/utilities.js';
+import { INTERNALS } from '../constants.js';
+export const roundPlugin = (ChronosClass) => {
+    const internal = ChronosClass[INTERNALS];
+    ChronosClass.prototype.round = function (unit, nearest = 1) {
+        const date = internal.internalDate(this);
+        switch (unit) {
+            case 'millisecond': {
+                const rounded = roundToNearest(date.getMilliseconds(), nearest);
+                date.setMilliseconds(rounded);
+                break;
+            }
+            case 'second': {
+                const fullSecond = date.getSeconds() + date.getMilliseconds() / 1000;
+                const rounded = roundToNearest(fullSecond, nearest);
+                date.setSeconds(rounded, 0);
+                break;
+            }
+            case 'minute': {
+                const fullMinute = date.getMinutes() + date.getSeconds() / 60 + date.getMilliseconds() / 60000;
+                const rounded = roundToNearest(fullMinute, nearest);
+                date.setMinutes(rounded, 0, 0);
+                break;
+            }
+            case 'hour': {
+                const fullHour = date.getHours() +
+                    date.getMinutes() / 60 +
+                    date.getSeconds() / 3600 +
+                    date.getMilliseconds() / 3600000;
+                const rounded = roundToNearest(fullHour, nearest);
+                date.setHours(rounded, 0, 0, 0);
+                break;
+            }
+            case 'day': {
+                const fullDay = date.getDate() +
+                    (date.getHours() / 24 +
+                        date.getMinutes() / 1440 +
+                        date.getSeconds() / 86400 +
+                        date.getMilliseconds() / 86400000);
+                const rounded = roundToNearest(fullDay, nearest);
+                date.setDate(rounded);
+                date.setHours(0, 0, 0, 0);
+                break;
+            }
+            case 'week': {
+                const weekday = date.getDay();
+                const offsetToMonday = (weekday + 6) % 7;
+                const startOfWeek = new Date(date);
+                startOfWeek.setDate(startOfWeek.getDate() - offsetToMonday);
+                startOfWeek.setHours(0, 0, 0, 0);
+                const endOfWeek = new Date(startOfWeek);
+                endOfWeek.setDate(endOfWeek.getDate() + 7);
+                const diffToStart = Math.abs(date.getTime() - startOfWeek.getTime());
+                const diffToEnd = Math.abs(endOfWeek.getTime() - date.getTime());
+                const rounded = diffToEnd < diffToStart ? endOfWeek : startOfWeek;
+                return internal.withOrigin(new ChronosClass(rounded), 'round');
+            }
+            case 'month': {
+                const fullMonth = date.getMonth() + date.getDate() / this.lastDateOfMonth;
+                const roundedMonth = roundToNearest(fullMonth, nearest);
+                date.setMonth(roundedMonth, 1);
+                date.setHours(0, 0, 0, 0);
+                break;
+            }
+            case 'year': {
+                const dayOfYear = Math.floor((date.getTime() - new Date(date.getFullYear(), 0, 1).getTime()) / 86400000);
+                const isLeap = new Date(date.getFullYear(), 1, 29).getDate() === 29;
+                const totalDays = isLeap ? 366 : 365;
+                const fullYear = date.getFullYear() + dayOfYear / totalDays;
+                const roundedYear = roundToNearest(fullYear, nearest);
+                date.setFullYear(roundedYear, 0, 1);
+                date.setHours(0, 0, 0, 0);
+                break;
+            }
+            default:
+                return this;
+        }
+        return internal.withOrigin(new ChronosClass(date), 'round');
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.21.4",
+  "version": "4.21.11",
   "description": "A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -203,6 +203,11 @@
       "import": "./dist/esm/date/plugins/relativeTimePlugin.js",
       "require": "./dist/cjs/date/plugins/relativeTimePlugin.js"
     },
+    "./plugins/roundPlugin": {
+      "types": "./dist/dts/date/plugins/roundPlugin.d.ts",
+      "import": "./dist/esm/date/plugins/roundPlugin.js",
+      "require": "./dist/cjs/date/plugins/roundPlugin.js"
+    },
     "./plugins/seasonPlugin": {
       "types": "./dist/dts/date/plugins/seasonPlugin.d.ts",
       "import": "./dist/esm/date/plugins/seasonPlugin.js",
@@ -284,6 +289,9 @@
       "plugins/relativeTimePlugin": [
         "dist/dts/date/plugins/relativeTimePlugin.d.ts"
       ],
+      "plugins/roundPlugin": [
+        "dist/dts/date/plugins/roundPlugin.d.ts"
+      ],
       "plugins/seasonPlugin": [
         "dist/dts/date/plugins/seasonPlugin.d.ts"
       ],