nhb-toolbox 3.7.7 → 3.7.99

package/dist/date/Chronos.js

@@ -1,7 +1,6 @@
-import { DAYS, MONTHS, sortedFormats, TIME_ZONES } from './constants';
+import { DAYS, MONTHS, ORIGIN, sortedFormats, TIME_ZONES } from './constants';
 import { isValidUTCOffSet } from './guards';
 import { extractMinutesFromUTC } from './utils';
-const ORIGIN = Symbol('origin');
 export class Chronos {
     #date;
     [ORIGIN];
@@ -24,27 +23,13 @@ export class Chronos {
         yield ['month', this.month];
         yield ['isoMonth', this.month + 1];
         yield ['date', this.date];
-        yield ['day', this.day];
-        yield ['isoDay', this.day + 1];
+        yield ['weekDay', this.weekDay];
+        yield ['isoWeekDay', this.weekDay + 1];
         yield ['hour', this.hour];
         yield ['minute', this.minute];
         yield ['second', this.second];
         yield ['millisecond', this.millisecond];
     }
-    #withOrigin(origin) {
-        const instance = new Chronos(this.#date);
-        instance[ORIGIN] = origin;
-        return instance;
-    }
-    get [Symbol.toStringTag]() {
-        switch (this[ORIGIN]) {
-            case 'toUTC':
-            case 'utc':
-                return this.#toLocalISOString().replace(this.getUTCOffset(), 'Z');
-            default:
-                return this.#toLocalISOString();
-        }
-    }
     /**
      * * Enables primitive coercion like `console.log`, `${chronos}`, etc.
      * @param hint - The type hint provided by the JS engine.
@@ -55,144 +40,26 @@ export class Chronos {
             return this.valueOf();
         return this.toLocalISOString();
     }
-    /** Returns a debug-friendly string for console.log or util.inspect */
-    inspect() {
-        return `[Chronos ${this.toLocalISOString()}]`;
-    }
-    /** * Clones and returns a new Chronos instance with the same date. */
-    clone() {
-        return new Chronos(this.#date);
-    }
-    /** * Enables JSON.stringify and console logging to show readable output. */
-    toJSON() {
-        return this.toLocalISOString();
-    }
-    /** * Enables arithmetic and comparison operations (e.g., +new Chronos()). */
-    valueOf() {
-        return this.getTimeStamp();
-    }
-    /** * Gets the native `Date` instance (read-only). */
-    toDate() {
-        return new Date(this.#date);
-    }
-    /** * Returns a string representation of a date. The format of the string depends on the locale. */
-    toString() {
-        switch (this[ORIGIN]) {
-            case 'toUTC':
-            case 'utc': {
-                const mins = extractMinutesFromUTC(`UTC${this.getUTCOffset()}`);
-                const date = this.addMinutes(mins);
-                return date.toString();
-            }
-            default:
-                return this.#date.toString();
-        }
-    }
-    /** * Returns ISO string with local time zone offset */
-    #toLocalISOString() {
-        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()}`;
-    }
-    /** * Returns ISO string with local time zone offset */
-    toLocalISOString() {
-        switch (this[ORIGIN]) {
-            case 'toUTC':
-            case 'utc': {
-                const mins = extractMinutesFromUTC(`UTC${this.getUTCOffset()}`);
-                const date = this.addMinutes(mins);
-                return date.#toLocalISOString();
-            }
-            default:
-                return this.#toLocalISOString();
-        }
-    }
-    /** * Returns a date as a string value in ISO format. */
-    toISOString() {
+    get [Symbol.toStringTag]() {
         switch (this[ORIGIN]) {
             case 'toUTC':
             case 'utc':
                 return this.#toLocalISOString().replace(this.getUTCOffset(), 'Z');
             default:
-                return this.#date.toISOString();
+                return this.#toLocalISOString();
         }
     }
-    /**
-     *  * Wrapper over native `toLocaleString`
-     * @description Converts a date and time to a string by using the current or specified locale.
-     *
-     * @param locales A locale string, array of locale strings, Intl.Locale object, or array of Intl.Locale objects that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used.
-     * @param options An object that contains one or more properties that specify comparison options.
-     */
-    toLocaleString(locale, options) {
-        return this.#date.toLocaleString(locale, options);
-    }
-    /** * Returns the time value in milliseconds since midnight, January 1, 1970 UTC. */
-    getTimeStamp() {
-        return this.#date.getTime();
-    }
-    /** * Returns the time value in milliseconds since midnight, January 1, 1970 UTC. */
-    get unix() {
-        return this.#date.getTime();
-    }
-    get year() {
-        return this.#date.getFullYear();
-    }
-    get month() {
-        return this.#date.getMonth();
-    }
-    get date() {
-        return this.#date.getDate();
-    }
-    get day() {
-        return this.#date.getDay();
-    }
-    get hour() {
-        return this.#date.getHours();
-    }
-    get minute() {
-        return this.#date.getMinutes();
-    }
-    get second() {
-        return this.#date.getSeconds();
-    }
-    get millisecond() {
-        return this.#date.getMilliseconds();
-    }
-    /** * ISO weekday: 1 = Monday, 7 = Sunday */
-    get isoWeekday() {
-        const day = this.day;
-        return day === 0 ? 7 : day;
-    }
-    /**
-     * @instance Returns the current date and time in a specified format in local time.
-     * * Default format is dd, `MMM DD, YYYY HH:mm:ss` = `Sun, Apr 06, 2025 16:11:55:379`
-     * @param options - Configure format string and whether to format using utc offset.
-     * @returns Formatted date string in desired format.
-     */
-    today(options) {
-        const { format = 'dd, MMM DD, YYYY HH:mm:ss', useUTC = false } = options || {};
-        const today = new Date();
-        return new Chronos(today).#format(format, useUTC);
-    }
-    /**
-     * @static Returns the current date and time in a specified format in local time.
-     * * Default format is dd, `MMM DD, YYYY HH:mm:ss` = `Sun, Apr 06, 2025 16:11:55:379`
-     * @param options - Configure format string and whether to format using utc offset.
-     * @returns Formatted date string in desired format.
-     */
-    static today(options) {
-        const { format = 'dd, MMM DD, YYYY HH:mm:ss', useUTC = false } = options || {};
-        const today = new Date();
-        return new Chronos(today).#format(format, useUTC);
+    /** @private @instance Method to tag origin of the `Chronos` instance. */
+    #withOrigin(origin) {
+        const instance = new Chronos(this.#date);
+        instance[ORIGIN] = origin;
+        return instance;
     }
     /**
-     * * Returns the number of milliseconds elapsed since midnight, January 1, 1970 Universal Coordinated Time (UTC).
-     * * It basically calls `Date.now()`.
-     * @returns The number of milliseconds elapsed since the Unix epoch.
+     * @private @instance Method to create native `Date` instance from date-like data types.
+     * @param value The value to convert into `Date`.
+     * @returns Instance of native Date object.
      */
-    static now() {
-        return Date.now();
-    }
     #toNewDate(value) {
         const date = value instanceof Chronos ?
             value.toDate()
@@ -204,7 +71,7 @@ export class Chronos {
         return date;
     }
     /**
-     * @private Formats the current `Chronos` date using the specified template.
+     * @private @instance Formats the current `Chronos` date using the specified template.
      *
      * @param format - The desired date format.
      * @param useUTC - Whether to use UTC or local time.
@@ -276,8 +143,140 @@ export class Chronos {
         }
         return result;
     }
+    /** @private @instance Returns ISO string with local time zone offset */
+    #toLocalISOString() {
+        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()}`;
+    }
+    /** Gets the full year of the date. */
+    get year() {
+        return this.#date.getFullYear();
+    }
+    /** Gets the month (0-11) of the date. */
+    get month() {
+        return this.#date.getMonth();
+    }
+    /** Gets the day of the month (1-31). */
+    get date() {
+        return this.#date.getDate();
+    }
+    /** Gets the day of the week (0-6, where 0 is Sunday). */
+    get weekDay() {
+        return this.#date.getDay();
+    }
+    /** Gets the hour (0-23) of the date. */
+    get hour() {
+        return this.#date.getHours();
+    }
+    /** Gets the minute (0-59) of the date. */
+    get minute() {
+        return this.#date.getMinutes();
+    }
+    /** Gets the second (0-59) of the date. */
+    get second() {
+        return this.#date.getSeconds();
+    }
+    /** Gets the millisecond (0-999) of the date. */
+    get millisecond() {
+        return this.#date.getMilliseconds();
+    }
+    /** Gets ISO weekday: 1 = Monday, 7 = Sunday */
+    get isoWeekday() {
+        const day = this.weekDay;
+        return day === 0 ? 7 : day;
+    }
+    /** Gets ISO month (1–12 instead of 0–11) */
+    get isoMonth() {
+        return this.month + 1;
+    }
+    /** Gets the time value in milliseconds since midnight, January 1, 1970 UTC. */
+    get unix() {
+        return this.#date.getTime();
+    }
+    /** @public @instance Returns a debug-friendly string for console.log or util.inspect */
+    inspect() {
+        return `[Chronos ${this.toLocalISOString()}]`;
+    }
+    /** @public @instance Clones and returns a new Chronos instance with the same date. */
+    clone() {
+        return new Chronos(this.#date).#withOrigin(this[ORIGIN]);
+    }
+    /** @public @instance Enables JSON.stringify and console logging to show readable output. */
+    toJSON() {
+        return this.toLocalISOString();
+    }
+    /** @public @instance Enables arithmetic and comparison operations (e.g., +new Chronos()). */
+    valueOf() {
+        return this.getTimeStamp();
+    }
+    /** @public @instance Gets the native `Date` instance (read-only). */
+    toDate() {
+        return new Date(this.#date);
+    }
+    /** @public @instance Returns a string representation of a date. The format of the string depends on the locale. */
+    toString() {
+        switch (this[ORIGIN]) {
+            case 'toUTC':
+            case 'utc': {
+                const mins = extractMinutesFromUTC(`UTC${this.getUTCOffset()}`);
+                const date = this.addMinutes(mins);
+                return date.toString();
+            }
+            default:
+                return this.#date.toString();
+        }
+    }
+    /** @public @instance Returns ISO string with local time zone offset */
+    toLocalISOString() {
+        switch (this[ORIGIN]) {
+            case 'toUTC':
+            case 'utc': {
+                const mins = extractMinutesFromUTC(`UTC${this.getUTCOffset()}`);
+                const date = this.addMinutes(mins);
+                return date.#toLocalISOString();
+            }
+            default:
+                return this.#toLocalISOString();
+        }
+    }
+    /** @public @instance Returns a date as a string value in ISO format. */
+    toISOString() {
+        switch (this[ORIGIN]) {
+            case 'toUTC':
+            case 'utc':
+                return this.#toLocalISOString().replace(this.getUTCOffset(), 'Z');
+            default:
+                return this.#date.toISOString();
+        }
+    }
+    /**
+     * @public @instance Wrapper over native `toLocaleString`
+     * @description Converts a date and time to a string by using the current or specified locale.
+     *
+     * @param locales A locale string, array of locale strings, Intl.Locale object, or array of Intl.Locale objects that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used.
+     * @param options An object that contains one or more properties that specify comparison options.
+     */
+    toLocaleString(locale, options) {
+        return this.#date.toLocaleString(locale, options);
+    }
+    /** @public @instance Returns the time value in milliseconds since midnight, January 1, 1970 UTC. */
+    getTimeStamp() {
+        return this.#date.getTime();
+    }
+    /**
+     * @public @instance Returns the current date and time in a specified format in local time.
+     * @description Default format is dd, `MMM DD, YYYY HH:mm:ss` = `Sun, Apr 06, 2025 16:11:55:379`
+     *
+     * @param options - Configure format string and whether to format using utc offset.
+     * @returns Formatted date string in desired format.
+     */
+    today(options) {
+        const { format = 'dd, MMM DD, YYYY HH:mm:ss', useUTC = false } = options || {};
+        const today = new Date();
+        return new Chronos(today).#format(format, useUTC);
+    }
     /**
-     * * Formats the date into a custom string format (local time).
+     * @public @instance Formats the date into a custom string format (local time).
      *
      * @param format - The desired format (Default format is `dd, MMM DD, YYYY HH:mm:ss:mss` = `Sun, Apr 06, 2025 16:11:55:379`).
      * @param useUTC - Optional `useUTC` to get the formatted time using UTC Offset, defaults to `false`. Equivalent to `formatUTC()` method if set to `true`.
@@ -287,7 +286,7 @@ export class Chronos {
         return this.#format(format, useUTC);
     }
     /**
-     * * Formats the date into a custom string format (UTC time).
+     * @public @instance Formats the date into a custom string format (UTC time).
      *
      * @param format - The desired format (Default format is `dd, MMM DD, YYYY HH:mm:ss:mss` = `Sun, Apr 06, 2025 16:11:55:379`).
      * @returns Formatted date string in desired format (UTC time).
@@ -302,85 +301,67 @@ export class Chronos {
         }
     }
     /**
-     * * Adds seconds and returns a new immutable instance.
+     * @public @instance Adds seconds and returns a new immutable instance.
      * @param seconds - Number of seconds to add.
      * @returns A new `Chronos` instance with the updated date.
      */
     addSeconds(seconds) {
         const newDate = new Date(this.#date);
         newDate.setSeconds(newDate.getSeconds() + seconds);
-        return new Chronos(newDate);
+        return new Chronos(newDate).#withOrigin('addSeconds');
     }
     /**
-     * * Adds minutes and returns a new immutable instance.
+     * @public @instance Adds minutes and returns a new immutable instance.
      * @param minutes - Number of minutes to add.
      * @returns A new `Chronos` instance with the updated date.
      */
     addMinutes(minutes) {
         const newDate = new Date(this.#date);
         newDate.setMinutes(newDate.getMinutes() + minutes);
-        return new Chronos(newDate);
+        return new Chronos(newDate).#withOrigin('addMinutes');
     }
     /**
-     * * Adds hours and returns a new immutable instance.
+     * @public @instance Adds hours and returns a new immutable instance.
      * @param hours - Number of hours to add.
      * @returns A new `Chronos` instance with the updated date.
      */
     addHours(hours) {
         const newDate = new Date(this.#date);
         newDate.setHours(newDate.getHours() + hours);
-        return new Chronos(newDate);
+        return new Chronos(newDate).#withOrigin('addHours');
     }
     /**
-     * * Adds days and returns a new immutable instance.
+     * @public @instance Adds days and returns a new immutable instance.
      * @param days - Number of days to add.
      * @returns A new `Chronos` instance with the updated date.
      */
     addDays(days) {
         const newDate = new Date(this.#date);
         newDate.setDate(newDate.getDate() + days);
-        return new Chronos(newDate);
+        return new Chronos(newDate).#withOrigin('addDays');
     }
     /**
-     * * Adds months and returns a new immutable instance.
+     * @public @instance Adds months and returns a new immutable instance.
      * @param months - Number of months to add.
      * @returns A new `Chronos` instance with the updated date.
      */
     addMonths(months) {
         const newDate = new Date(this.#date);
         newDate.setMonth(newDate.getMonth() + months);
-        return new Chronos(newDate);
+        return new Chronos(newDate).#withOrigin('addMonths');
     }
     /**
-     * * Adds years and returns a new immutable instance.
+     * @public @instance Adds years and returns a new immutable instance.
      * @param years - Number of years to add.
      * @returns A new `Chronos` instance with the updated date.
      */
     addYears(years) {
         const newDate = new Date(this.#date);
         newDate.setFullYear(newDate.getFullYear() + years);
-        return new Chronos(newDate);
-    }
-    /**
-     * * Subtracts days and returns a new immutable instance.
-     * @param days - Number of days to subtract.
-     * @returns A new `Chronos` instance with the updated date.
-     */
-    subtractDays(days) {
-        return this.addDays(-days);
+        return new Chronos(newDate).#withOrigin('addYears');
     }
     /**
-     * * Checks if the year is a leap year.
-     * - A year is a leap year if it is divisible by 4, but not divisible by 100, unless it is also divisible by 400.
-     * - For example, 2000 and 2400 are leap years, but 1900 and 2100 are not.
-     * @returns `true` if the year is a leap year, `false` otherwise.
-     */
-    isLeapYear() {
-        const year = this.#date.getFullYear();
-        return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
-    }
-    /**
-     * * Create a new instance of `Chronos` in the specified timezone.
+     * @public @instance Create a new instance of `Chronos` in the specified timezone.
      *
      * @param zone - Standard timezone abbreviation (e.g., 'IST', 'UTC', 'EST') or UTC Offset in `UTC-01:30` format.
      * @returns A new instance of `Chronos` with time in the given timezone. Invalid input sets time-zone to `UTC`.
@@ -395,22 +376,97 @@ export class Chronos {
         }
         const utc = this.#date.getTime() + this.#date.getTimezoneOffset() * 60 * 1000;
         const adjusted = new Date(utc + offset * 60 * 1000);
-        return new Chronos(adjusted);
+        return new Chronos(adjusted).#withOrigin('timeZone');
     }
-    /** - Checks if the current date is today. */
+    /**
+     * @public @instance Checks if the year is a leap year.
+     * - A year is a leap year if it is divisible by 4, but not divisible by 100, unless it is also divisible by 400.
+     * - For example, 2000 and 2400 are leap years, but 1900 and 2100 are not.
+     * @returns `true` if the year is a leap year, `false` otherwise.
+     */
+    isLeapYear() {
+        const year = this.#date.getFullYear();
+        return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    }
+    /** @public @instance Checks if the current date is today. */
     isToday() {
         return this.getRelativeDay() === 0;
     }
-    /** - Checks if the current date is tomorrow. */
+    /** @public @instance Checks if the current date is tomorrow. */
     isTomorrow() {
         return this.getRelativeDay() === 1;
     }
-    /** - Checks if the current date is yesterday. */
+    /** @public @instance Checks if the current date is yesterday. */
     isYesterday() {
         return this.getRelativeDay() === -1;
     }
     /**
-     * * Returns full time difference from now (or a specified time) down to a given level.
+     * @public @instance Checks if another date is the same as this one in a specific unit.
+     * @param other The other date to compare.
+     * @param unit The unit to compare.
+     */
+    isSame(other, unit) {
+        const time = new Chronos(other);
+        return (this.startOf(unit).toDate().getTime() ===
+            time.startOf(unit).toDate().getTime());
+    }
+    /**
+     * @public @instance Checks if this date is before another date in a specific unit.
+     * @param other The other date to compare.
+     * @param unit The unit to compare.
+     */
+    isBefore(other, unit) {
+        const time = new Chronos(other);
+        return (this.startOf(unit).toDate().getTime() <
+            time.startOf(unit).toDate().getTime());
+    }
+    /**
+     * @public @instance Checks if this date is after another date in a specific unit.
+     * @param other The other date to compare.
+     * @param unit The unit to compare.
+     */
+    isAfter(other, unit) {
+        const time = new Chronos(other);
+        return (this.startOf(unit).toDate().getTime() >
+            time.startOf(unit).toDate().getTime());
+    }
+    /**
+     * @public @instance Checks if the current date is between the given start and end dates.
+     *
+     * @param start - The start of the range.
+     * @param end - The end of the range.
+     * @param inclusive - Specifies whether the comparison is inclusive or exclusive:
+     * - `'[]'`: inclusive of both start and end (≥ start and ≤ end)
+     * - `'[)'`: inclusive of start, exclusive of end (≥ start and < end)
+     * - `'(]'`: exclusive of start, inclusive of end (> start and ≤ end)
+     * - `'()'`: exclusive of both start and end (> start and < end)
+     *
+     * @returns `true` if the current date is within the specified range based on the `inclusive` mode.
+     */
+    isBetween(start, end, inclusive = '()') {
+        const s = new Chronos(start).valueOf();
+        const e = new Chronos(end).valueOf();
+        const t = this.valueOf();
+        switch (inclusive) {
+            case '[]':
+                return t >= s && t <= e;
+            case '[)':
+                return t >= s && t < e;
+            case '(]':
+                return t > s && t <= e;
+            case '()':
+                return t > s && t < e;
+        }
+    }
+    /** @public @instance Checks if currently in DST */
+    isDST() {
+        const jan = new Date(this.year, 0, 1);
+        const jul = new Date(this.year, 6, 1);
+        return (Math.min(jan.getTimezoneOffset(), jul.getTimezoneOffset()) !==
+            this.#date.getTimezoneOffset());
+    }
+    /**
+     * @public @instance Returns full time difference from now (or a specified time) down to a given level.
      *
      * @param level Determines the smallest unit to include in the output (e.g., 'minute' will show up to minutes, ignoring seconds). Defaults to `minute`.
      * @param withSuffixPrefix If `true`, adds `"in"` or `"ago"` depending on whether the time is in the future or past. Defaults to `true`.
@@ -493,7 +549,7 @@ export class Chronos {
         return `${prefix}${parts.join(' ')}${suffix}`;
     }
     /**
-     * * Returns the number of full years between the input date and now.
+     * @public @instance Returns the number of full years between the input date and now.
      * @param time Optional time to compare with the `Chronos` date/time.
      * @returns The difference in number, negative is `Chronos` time is a past time else positive.
      */
@@ -509,7 +565,7 @@ export class Chronos {
         return years;
     }
     /**
-     * * Returns the number of full months between the input date and now.
+     * @public @instance Returns the number of full months between the input date and now.
      * @param time Optional time to compare with the `Chronos` date/time.
      * @returns The difference in number, negative is `Chronos` time is a past time else positive.
      */
@@ -524,7 +580,7 @@ export class Chronos {
         return months;
     }
     /**
-     * * Determines if the given date is today, tomorrow, yesterday or any relative day.
+     * @public @instance Determines if the given date is today, tomorrow, yesterday or any relative day.
      * @param date - The date to compare (Date object).
      * @param time Optional time to compare with the `Chronos` date/time.
      * @returns
@@ -545,7 +601,7 @@ export class Chronos {
         return diffDays;
     }
     /**
-     * * Returns the number of full hours between the input date and now.
+     * @public @instance Returns the number of full hours between the input date and now.
      * @param time Optional time to compare with the `Chronos` date/time.
      * @returns The difference in number, negative is `Chronos` time is a past time else positive.
      */
@@ -554,7 +610,7 @@ export class Chronos {
         return Math.floor(diff / (1000 * 60 * 60));
     }
     /**
-     * * Returns the number of full minutes between the input date and now.
+     * @public @instance Returns the number of full minutes between the input date and now.
      * @param time Optional time to compare with the `Chronos` date/time.
      * @returns The difference in number, negative is `Chronos` time is a past time else positive.
      */
@@ -563,7 +619,7 @@ export class Chronos {
         return Math.floor(diff / (1000 * 60));
     }
     /**
-     *  * Returns the number of full seconds between the input date and now.
+     * @public @instance Returns the number of full seconds between the input date and now.
      * @param time Optional time to compare with the `Chronos` date/time.
      * @returns The difference in number, negative is `Chronos` time is a past time else positive.
      */
@@ -572,7 +628,7 @@ export class Chronos {
         return Math.floor(diff / 1000);
     }
     /**
-     * * Returns the number of milliseconds between the input date and now.
+     * @public @instance Returns the number of milliseconds between the input date and now.
      * @param time Optional time to compare with the `Chronos` date/time.
      * @returns The difference in number, negative is `Chronos` time is a past time else positive.
      */
@@ -580,7 +636,7 @@ export class Chronos {
         return this.#date.getTime() - this.#toNewDate(time).getTime();
     }
     /**
-     * * Compares the stored date with now, returning the difference in the specified unit.
+     * @public @instance Compares the stored date with now, returning the difference in the specified unit.
      *
      * @param unit The time unit to compare by. Defaults to 'minute'.
      * @param time Optional time to compare with the `Chronos` date/time.
@@ -607,7 +663,7 @@ export class Chronos {
         }
     }
     /**
-     * * Returns a new Chronos instance at the start of a given unit.
+     * @public @instance Returns a new Chronos instance at the start of a given unit.
      * @param unit The unit to reset (e.g., year, month, day).
      */
     startOf(unit) {
@@ -643,17 +699,20 @@ export class Chronos {
             case 'millisecond':
                 break;
         }
-        return new Chronos(d);
+        return new Chronos(d).#withOrigin('startOf');
     }
     /**
-     * * Returns a new Chronos instance at the end of a given unit.
+     * @public @instance Returns a new Chronos instance at the end of a given unit.
      * @param unit The unit to adjust (e.g., year, month, day).
      */
     endOf(unit) {
-        return this.startOf(unit).add(1, unit).add(-1, 'millisecond');
+        return this.startOf(unit)
+            .add(1, unit)
+            .add(-1, 'millisecond')
+            .#withOrigin('endOf');
     }
     /**
-     * * Returns a new Chronos instance with the specified unit added.
+     * @public @instance Returns a new Chronos instance with the specified unit added.
      * @param amount The amount to add (can be negative).
      * @param unit The time unit to add.
      */
@@ -682,10 +741,18 @@ export class Chronos {
                 d.setFullYear(d.getFullYear() + amount);
                 break;
         }
-        return new Chronos(d);
+        return new Chronos(d).#withOrigin('add');
+    }
+    /**
+     * @public @instance Returns a new Chronos instance with the specified unit subtracted.
+     * @param amount The amount to subtract (can be negative).
+     * @param unit The time unit to add.
+     */
+    subtract(amount, unit) {
+        return this.add(-amount, unit).#withOrigin('subtract');
     }
     /**
-     * * Gets the value of a specific time unit from the date.
+     * @public @instance Gets the value of a specific time unit from the date.
      * @param unit The unit to retrieve.
      */
     get(unit) {
@@ -707,7 +774,7 @@ export class Chronos {
         }
     }
     /**
-     * Returns a new Chronos instance with the specified unit set to the given value.
+     * @public @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.
      */
@@ -736,10 +803,10 @@ export class Chronos {
                 d.setMilliseconds(value);
                 break;
         }
-        return new Chronos(d);
+        return new Chronos(d).#withOrigin('set');
     }
     /**
-     * * Returns the difference between this and another date in the given unit.
+     * @public @instance Returns the difference between this and another date in the given unit.
      * @param other The other date to compare.
      * @param unit The unit in which to return the difference.
      */
@@ -765,37 +832,7 @@ export class Chronos {
         }
     }
     /**
-     * * Checks if another date is the same as this one in a specific unit.
-     * @param other The other date to compare.
-     * @param unit The unit to compare.
-     */
-    isSame(other, unit) {
-        const time = new Chronos(other);
-        return (this.startOf(unit).toDate().getTime() ===
-            time.startOf(unit).toDate().getTime());
-    }
-    /**
-     * * Checks if this date is before another date in a specific unit.
-     * @param other The other date to compare.
-     * @param unit The unit to compare.
-     */
-    isBefore(other, unit) {
-        const time = new Chronos(other);
-        return (this.startOf(unit).toDate().getTime() <
-            time.startOf(unit).toDate().getTime());
-    }
-    /**
-     * * Checks if this date is after another date in a specific unit.
-     * @param other The other date to compare.
-     * @param unit The unit to compare.
-     */
-    isAfter(other, unit) {
-        const time = new Chronos(other);
-        return (this.startOf(unit).toDate().getTime() >
-            time.startOf(unit).toDate().getTime());
-    }
-    /**
-     * * Returns a human-readable relative calendar time like "Today at 3:00 PM"
+     * @public @instance Returns a human-readable relative calendar time like "Today at 3:00 PM"
      * @param baseDate Optional base date to compare with.
      */
     calendar(baseDate) {
@@ -822,7 +859,7 @@ export class Chronos {
             minute: '2-digit',
         });
     }
-    /** * Returns a short human-readable string like "2h ago", "in 5m" */
+    /** @public @instance Returns a short human-readable string like "2h ago", "in 5m" */
     fromNowShort() {
         const now = new Chronos();
         const diffInSeconds = this.diff(now, 'second');
@@ -848,7 +885,7 @@ export class Chronos {
             return `${suffix}${Math.floor(abs / 31536000)}y${postfix}`;
         }
     }
-    /** * Returns ISO week number */
+    /** @public @instance Returns ISO week number */
     getWeek() {
         // ISO week starts on Monday
         const target = this.startOf('week').add(3, 'day');
@@ -859,84 +896,68 @@ export class Chronos {
         const week = Math.floor(daysDiff / 7) + 1;
         return week;
     }
-    /** * Returns ISO week year */
+    /** @public @instance Returns ISO week year */
     getWeekYear() {
         const d = this.startOf('week').add(3, 'day'); // Thursday of current ISO week
         return d.year;
     }
-    /** * Returns day of year (1 - 366) */
+    /** @public @instance Returns day of year (1 - 366) */
     getDayOfYear() {
         const start = new Date(this.year, 0, 1);
         const diff = this.#date.getTime() - start.getTime();
         return Math.floor(diff / 86400000) + 1;
     }
-    /**
-     * * Checks if the current date is between the given start and end dates.
-     *
-     * @param start - The start of the range.
-     * @param end - The end of the range.
-     * @param inclusive - Specifies whether the comparison is inclusive or exclusive:
-     * - `'[]'`: inclusive of both start and end (≥ start and ≤ end)
-     * - `'[)'`: inclusive of start, exclusive of end (≥ start and < end)
-     * - `'(]'`: exclusive of start, inclusive of end (> start and ≤ end)
-     * - `'()'`: exclusive of both start and end (> start and < end)
-     *
-     * @returns `true` if the current date is within the specified range based on the `inclusive` mode.
-     */
-    isBetween(start, end, inclusive = '()') {
-        const s = new Chronos(start).valueOf();
-        const e = new Chronos(end).valueOf();
-        const t = this.valueOf();
-        switch (inclusive) {
-            case '[]':
-                return t >= s && t <= e;
-            case '[)':
-                return t >= s && t < e;
-            case '(]':
-                return t > s && t <= e;
-            case '()':
-                return t > s && t < e;
-        }
-    }
-    /** * Returns number of days in current month */
+    /** @public @instance Returns number of days in current month */
     daysInMonth() {
         return new Date(this.year, this.month + 1, 0).getDate();
     }
-    /** * Converts to object with all date unit parts */
+    /** @public @instance Converts to object with all date unit parts */
     toObject() {
         return Object.fromEntries([...this]);
     }
-    /** * Converts to array with all date unit parts */
+    /** @public @instance Converts to array with all date unit parts */
     toArray() {
         return Object.values(this.toObject());
     }
-    /** * Returns offset like +06:00 */
+    /** @public @instance Returns offset like +06:00 */
     getUTCOffset() {
         const offset = -this.#date.getTimezoneOffset();
         const sign = offset >= 0 ? '+' : '-';
         const pad = (n) => String(Math.floor(Math.abs(n))).padStart(2, '0');
         return `${sign}${pad(offset / 60)}:${pad(offset % 60)}`;
     }
-    /** * Checks if currently in DST */
-    isDST() {
-        const jan = new Date(this.year, 0, 1);
-        const jul = new Date(this.year, 6, 1);
-        return (Math.min(jan.getTimezoneOffset(), jul.getTimezoneOffset()) !==
-            this.#date.getTimezoneOffset());
-    }
-    /** * Returns new Chronos instance in UTC */
+    /** @public @instance Returns new Chronos instance in UTC */
     toUTC() {
         const date = this.#date;
         const utc = new Date(date.getTime() + date.getTimezoneOffset() * 60000);
         return new Chronos(utc).#withOrigin('toUTC');
     }
-    /** * Returns new Chronos instance in local time */
+    /** @public @instance Returns new Chronos instance in local time */
     toLocal() {
         const date = this.#date;
         const utc = new Date(date.getTime() - date.getTimezoneOffset() * 60000);
         return new Chronos(utc).#withOrigin('toLocal');
     }
-    /** @static Parses a date string with a given format (partial support) */
+    /**
+     * @public @static Returns the current date and time in a specified format in local time.
+     * * Default format is dd, `MMM DD, YYYY HH:mm:ss` = `Sun, Apr 06, 2025 16:11:55:379`
+     * @param options - Configure format string and whether to format using utc offset.
+     * @returns Formatted date string in desired format.
+     */
+    static today(options) {
+        const { format = 'dd, MMM DD, YYYY HH:mm:ss', useUTC = false } = options || {};
+        const today = new Date();
+        return new Chronos(today).#format(format, useUTC);
+    }
+    /**
+     * @public @static Returns the number of milliseconds elapsed since midnight, January 1, 1970 Universal Coordinated Time (UTC).
+     * * It basically calls `Date.now()`.
+     * @returns The number of milliseconds elapsed since the Unix epoch.
+     */
+    static now() {
+        return Date.now();
+    }
+    /** @public @static Parses a date string with a given format (partial support) */
     static parse(dateStr, format) {
         const formatMap = {
             YYYY: 'year',
@@ -960,10 +981,10 @@ export class Chronos {
             }
             return acc;
         }, {});
-        return new Chronos(new Date(values.year ?? 1970, (values.month ?? 1) - 1, values.date ?? 1, values.hour ?? 0, values.minute ?? 0, values.second ?? 0));
+        return new Chronos(new Date(values.year ?? 1970, (values.month ?? 1) - 1, values.date ?? 1, values.hour ?? 0, values.minute ?? 0, values.second ?? 0)).#withOrigin('parse');
     }
     /**
-     * @static Creates UTC Chronos
+     * @public @static Creates UTC Chronos
      * @param dateLike Date input to create utc time.
      */
     static utc(dateLike) {
@@ -972,17 +993,17 @@ export class Chronos {
         return new Chronos(utc).#withOrigin('utc');
     }
     /**
-     * @static Returns earliest Chronos
+     * @public @static Returns earliest Chronos
      * @param dates Date inputs.
      */
     static min(...dates) {
-        return new Chronos(Math.min(...dates.map((d) => new Chronos(d).valueOf())));
+        return new Chronos(Math.min(...dates.map((d) => new Chronos(d).valueOf()))).#withOrigin('min');
     }
     /**
-     * @static Returns latest Chronos
+     * @public @static Returns latest Chronos
      * @param dates Date inputs.
      */
     static max(...dates) {
-        return new Chronos(Math.max(...dates.map((d) => new Chronos(d).valueOf())));
+        return new Chronos(Math.max(...dates.map((d) => new Chronos(d).valueOf()))).#withOrigin('max');
     }
 }