nhb-toolbox 4.20.46 → 4.20.50

package/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.20.50] - 2025-09-25
+
+- **Fixed** _return type_ of `convertObjectValues` utility to correctly reflect the _transformed object structure_ and `keys` option is now _more strict_: **only accepts keys which values are string and/or number** and **the array cannot be left empty**.
+- **Updated** _options type_ for `with()` _static method_ of `Chronos`.
+
+## [4.20.48] - 2025-09-22
+
+- **Wrapped** `ChronosMethods` type in `LooseLiteral` to allow passing _custom method names_ without _type errors_ when creating a custom [`Chronos Plugin`](https://toolbox.nazmul-nhb.dev/docs/classes/Chronos/plugins#%EF%B8%8F-writing-your-own-custom-plugin).
+- **Updated** _error message_ in `convert` method in `Currency` class.
+
 ## [4.20.46] - 2025-09-22
 
 - `Chronos` class is now _exported via subpath_ `'nhb-toolbox/chronos'`.

package/dist/cjs/date/chronos-statics.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/number/Currency.js

@@ -56,11 +56,12 @@ class Currency {
         const url = `https://api.frankfurter.app/latest?amount=${this.#amount}&from=${this.#code}`;
         try {
             const res = await fetch(url, { redirect: 'error' });
-            if (!res.ok)
+            if (!res.ok) {
                 throw new Error(`FrankFurter Error: ${res.status}. "${res.statusText}"`);
+            }
             const data = await res.json();
             if (!data.rates?.[to]) {
-                throw new Error(`Currency "${to}" not found in FrankFurter Database!`);
+                throw new Error(`Currency "${to}" not allowed or not found in FrankFurter Database!`);
             }
             return data.rates[to] / this.#amount;
         }

package/dist/dts/date/chronos-fn.d.ts

@@ -32,11 +32,10 @@ import type { ChronosStatics } from './types';
  * **Available Static Methods:**
  *
  * ```ts
- * chronos.today(options?: FormatOptions): string;
- * chronos.yesterday(): Chronos;
- * chronos.tomorrow(): Chronos;
  * chronos.now(): number;
- * chronos.use(plugin: ChronosPlugin): void;
+ * chronos.tomorrow(): Chronos;
+ * chronos.yesterday(): Chronos;
+ * chronos.today(options?: FormatOptions): string;
  * chronos.with(options: ChronosWithOptions): Chronos;
  * chronos.parse(dateStr: string, format: string): Chronos;
  * chronos.utc(dateLike: ChronosInput): Chronos;
@@ -48,6 +47,7 @@ import type { ChronosStatics } from './types';
  * chronos.isValidChronos(value: unknown): boolean;
  * chronos.formatTimePart(time: string, format?: TimeParts): string;
  * chronos.getDatesForDay(day: WeekDay, options?: WeekdayOptions): string[];
+ * chronos.use(plugin: ChronosPlugin): void;
  * ```
  */
 declare const chronosStatics: ChronosStatics;

package/dist/dts/date/chronos-statics.d.ts

@@ -0,0 +1,290 @@
+import type { Chronos } from './Chronos';
+import type { ChronosInput, ChronosPlugin, ChronosWithOptions, DateRangeOptions, FormatOptions, RelativeRangeOptions, TimeParts, WeekDay, WeekdayOptions } from './types';
+/** All the statics methods in `Chronos` class */
+export interface ChronosStatics {
+    /**
+     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
+     *
+     * @description
+     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
+     *
+     * Accepts no arguments (defaults to now).
+     *
+     * @returns Instance of `Chronos` with all methods and properties.
+     */
+    (): Chronos;
+    /**
+     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
+     *
+     * @description
+     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
+     *
+     * @param value - A date value in `number`, it should be a timestamp (milliseconds since the Unix epoch).
+     *
+     * @returns Instance of `Chronos` with all methods and properties.
+     */
+    (value: number): Chronos;
+    /**
+     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
+     *
+     * **Note**: *If a date is provided **without a time component**, the instance will default to `00:00:00.000` UTC
+     * and convert it to the **equivalent local time** using the current environment's UTC offset.*
+     *
+     * @description
+     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
+     *
+     * @param value - A date value in `string`, it should be in a format that can be parsed by the `Date` constructor.
+     *
+     * @returns Instance of `Chronos` with all methods and properties.
+     */
+    (value: string): Chronos;
+    /**
+     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
+     *
+     * **Note**: *If a date is provided **without a time component**, the instance will default to `00:00:00.000` UTC
+     * and convert it to the **equivalent local time** using the current environment's UTC offset.*
+     *
+     * @description
+     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
+     *
+     * @param value - A date value as `Date` object, it will be used as is.
+     *
+     * @returns Instance of `Chronos` with all methods and properties.
+     */
+    (value: Date): Chronos;
+    /**
+     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
+     *
+     * **Note**: *If a date is provided **without a time component**, the instance will default to `00:00:00.000` UTC
+     * and convert it to the **equivalent local time** using the current environment's UTC offset.*
+     *
+     * @description
+     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
+     *
+     * @param value - A date value as `Chronos` object.
+     *
+     * @returns Instance of `Chronos` with all methods and properties.
+     */
+    (value: Chronos): Chronos;
+    /**
+     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
+     *
+     * @description
+     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
+     *
+     * @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.
+     *
+     * @returns Instance of `Chronos` with all methods and properties.
+     */
+    (year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, ms?: number): Chronos;
+    /**
+     * @static Injects a plugin into the `Chronos` system.
+     * @param plugin The plugin to inject.
+     *
+     * - **NOTE:** *Once a plugin is injected, all the registered methods for that plugin will be available for the whole project.*
+     * - See full list of plugins and the methods they register {@link https://toolbox.nazmul-nhb.dev/docs/classes/Chronos/plugins#-official-plugins here}.
+     */
+    use(plugin: ChronosPlugin): void;
+    /**
+     * * 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`
+     * @param options - Configure format string and whether to format using utc offset.
+     * @returns Formatted date string in desired format.
+     */
+    today(options?: FormatOptions): string;
+    /**
+     * * Returns a new `Chronos` instance representing yesterday's date.
+     *
+     * @returns A `Chronos` instance for the next calendar day.
+     */
+    yesterday(): Chronos;
+    /**
+     * * Returns a new `Chronos` instance representing tomorrow's date.
+     *
+     * @returns A `Chronos` instance for the next calendar day.
+     */
+    tomorrow(): Chronos;
+    /**
+     * * 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.
+     */
+    now(): number;
+    /**
+     * * Parses a date string with a given format (limited support only).
+     *
+     * * **Supported format tokens**:
+     * - `YYYY`: Full year (e.g., 2023)
+     * - `YY`: Two-digit year (e.g., 23 for 2023, 99 for 1999)
+     * - `MM`: Month (01-12)
+     * - `M`: 1-Digit Month (1-9)
+     * - `DD`: Day of the month (01-31)
+     * - `D`: 1-Digit Day of the month (1-9)
+     * - `HH`: Hour (00-23)
+     * - `H`: 1-Digit Hour (0-9)
+     * - `mm`: Minute (00-59)
+     * - `m`: 1-Digit Minute (0-9)
+     * - `ss`: Second (00-59)
+     * - `s`: 1-Digit Second (0-9)
+     *
+     * **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
+     * ```
+     *
+     * @param dateStr - The date string to be parsed
+     * @param format - The format of the date string. Tokens like `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss` are used to specify the structure.
+     * @returns A new `Chronos` instance representing the parsed date.
+     * @throws `Error` If the date string does not match the format.
+     */
+    parse(dateStr: string, format: string): Chronos;
+    /**
+     * * Creates a new `Chronos` instance with the provided time component(s).
+     *
+     * @param options - One or more time components to override.
+     * @returns A new `Chronos` instance with the provided time components applied.
+     *
+     * @remarks
+     * - Unspecified components are filled with the current time's (`Chronos`) respective values.
+     * - For option `month`, value should be number from `1` (January) to `12` (December).
+     * - If the `date` component is omitted and the current day is the last day of its month,
+     *   the resulting instance will also use the last day of the target month.
+     *   - _This rule does **not** apply if the `date` component is explicitly provided,
+     *     even if that value exceeds the last day of the target month._
+     *
+     * @example
+     * // Override only the year and month
+     * const c = Chronos.with({ year: 2025, month: 12 });
+     */
+    with(options: ChronosWithOptions): Chronos;
+    /**
+     * * 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.
+     */
+    utc(dateLike?: ChronosInput): Chronos;
+    /**
+     * * Formats a time-only string into a formatted time string.
+     *
+     * @param time - Time string to be formatted. Supported formats include:
+     * - `HH:mm` → e.g., `'14:50'`
+     * - `HH:mm:ss` → e.g., `'14:50:00'`
+     * - `HH:mm:ss.SSS` → e.g., `'14:50:00.800'`
+     * - `HH:mm+TimeZoneOffset(HH)` → e.g., `'14:50+06'`
+     * - `HH:mm:ss+TimeZoneOffset(HH)` → e.g., `'14:50:00+06'`
+     * - `HH:mm:ss+TimeZoneOffset(HH:mm)` → e.g., `'14:50:00+05:30'`
+     * - `HH:mm:ss.SSS+TimeZoneOffset(HH)` → e.g., `'14:50:00.800+06'`
+     * - `HH:mm:ss.SSS+TimeZoneOffset(HH:mm)` → e.g., `'14:50:00.800+06:30'`
+     *
+     * * *Input will default to today's date and assume local timezone if no offset is provided.*
+     *
+     * @param format - Format string accepted by `formatStrict()` method (`TimeParts`). Default: `hh:mm:ss a` → 02:33:36 pm.
+     * @returns Formatted time string in local (System) time.
+     */
+    formatTimePart(time: string, format?: TimeParts): string;
+    /**
+     * * Returns ISO date strings for each occurrence of a weekday from today, spanning a relative time range.
+     *
+     * @param day - The weekday to match (e.g., `'Wednesday'`, `'Sunday'`).
+     * @param options - Relative range (e.g., 7 days, 4 weeks) and output format (local with timezone or utc).
+     * @returns Array of ISO date strings in the specified format. Returns empty array if no matches in the time span.
+     *
+     * @example
+     * Chronos.getDatesForDay('Wednesday', { span: 7, unit: 'day' });
+     * //=> [ '2025-05-28T21:16:06.198+06:00', '2025-06-04T21:16:06.198+06:00' ]
+     *
+     * @example
+     * Chronos.getDatesForDay('Wednesday', {
+     *   span: 7,
+     *   unit: 'day',
+     *   format: 'utc'
+     * });
+     * //=> [ '2025-05-28T15:17:10.812Z', '2025-06-04T15:17:10.812Z' ]
+     */
+    getDatesForDay(day: WeekDay, options?: RelativeRangeOptions): string[];
+    /**
+     * * Returns ISO date strings for each occurrence of a weekday between two fixed dates.
+     *
+     * @param day - The weekday to match (e.g., `'Monday'`, `'Friday'`).
+     * @param options - Absolute date range (e.g. `'2025-06-30'`, ` new Date()`, `new Chronos()` etc.) and output format (local with timezone or utc).
+     * @returns Array of ISO date strings in the specified format. Returns empty array if no matches in the range.
+     *
+     * @example
+     * Chronos.getDatesForDay('Monday', {
+     *   from: '2025-05-28',
+     *   to: '2025-06-30',
+     *   format: 'local'
+     * });
+     * //=> [ '2025-01-06T...', '2025-01-13T...', ... ]
+     */
+    getDatesForDay(day: WeekDay, options?: DateRangeOptions): string[];
+    /**
+     * * Returns ISO date strings for each occurrence of a weekday.
+     *
+     * @param day - The weekday to match (e.g., `'Wednesday'`, `'Sunday'`).
+     * @param options - Relative range (e.g., 7 days, 4 weeks) or Absolute date range and output format.
+     * @returns Array of ISO date strings in the specified format.
+     */
+    getDatesForDay(day: WeekDay, options?: WeekdayOptions): string[];
+    /**
+     * * Returns earliest Chronos
+     * @param dates Date inputs.
+     */
+    min(...dates: ChronosInput[]): Chronos;
+    /**
+     * * Returns latest Chronos
+     * @param dates Date inputs.
+     */
+    max(...dates: ChronosInput[]): Chronos;
+    /**
+     * * Checks if the year in the date string or year (from 0 - 9999) 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.
+     *
+     * @description
+     * This method accepts different types of date inputs and extracts the year to check if it's a leap year.
+     * If the provided date is a `number`, it will be treated as a year (must be a valid year from 0 to 9999).
+     * If the year is out of this range (negative or larger than 9999), it will be treated as a Unix timestamp.
+     * If the provided date is a string or a `Date` object, it will be parsed and the year will be extracted.
+     * If a `Chronos` instance is passed, the year will be directly accessed from the instance.
+     *
+     * @param date - A `number` (year or Unix timestamp), `string`, `Date`, or `Chronos` instance representing a date.
+     * @returns `true` if the year is a leap year, `false` otherwise.
+     */
+    isLeapYear(date: ChronosInput): boolean;
+    /**
+     * * Checks if the given value is a valid `Date` object.
+     * - A value is considered valid if it is an instance of the built-in `Date` class.
+     * - This does not check whether the date itself is valid (e.g., `new Date('invalid')`).
+     * @param value - The value to test.
+     * @returns `true` if the value is a valid Date object, otherwise `false`.
+     */
+    isValidDate(value: unknown): value is Date;
+    /**
+     * * Checks if the given value is a valid date string.
+     * - A value is considered a valid date string if it is a string and can be parsed by `Date.parse()`.
+     * - This uses the native JavaScript date parser internally.
+     * @param value - The value to test.
+     * @returns `true` if the value is a valid date string, otherwise `false`.
+     */
+    isDateString(value: unknown): value is string;
+    /**
+     * * Checks if the given value is an instance of `Chronos`.
+     * - 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`.
+     */
+    isValidChronos(value: unknown): value is Chronos;
+}

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

@@ -1,8 +1,10 @@
 import type { Enumerate, NumberRange } from '../number/types';
-import type { LooseLiteral, RequireAtLeast } from '../utils/types';
+import type { LooseLiteral } from '../utils/types';
 import type { Chronos } from './Chronos';
+import type { ChronosStatics } from './chronos-statics';
 import type { DATE_FORMATS, DAY_FORMATS, DAYS, HOUR_FORMATS, MILLISECOND_FORMATS, MINUTE_FORMATS, MONTH_FORMATS, MONTHS, SECOND_FORMATS, TIME_FORMATS, TIME_ZONES, WESTERN_ZODIAC_SIGNS, YEAR_FORMATS, ZODIAC_PRESETS } from './constants';
 import type { SEASON_PRESETS } from './seasons';
+export type { ChronosStatics };
 /** - Minute in numeric string from `00` to `23` */
 export type ClockHour = `0${Enumerate<10>}` | `${NumberRange<10, 23>}`;
 /** - Minute in numeric string from `00` to `59` */
@@ -133,7 +135,7 @@ export interface ChronosInternals {
 export type WithoutOrigin = Omit<Chronos, '#ORIGIN' | 'origin'>;
 type PluginMethods = 'timeZone';
 /** Methods (both instance and static) in `Chronos` class that return `Chronos` instance. */
-export type ChronosMethods = {
+export type ChronosMethods = LooseLiteral<{
     [K in keyof WithoutOrigin]: Chronos extends {
         [key in K]: (...args: any[]) => Chronos;
     } ? K : never;
@@ -141,7 +143,7 @@ export type ChronosMethods = {
     [K in keyof typeof Chronos]: typeof Chronos extends {
         [key in K]: (...args: any[]) => Chronos;
     } ? K : never;
-}[keyof typeof Chronos] | PluginMethods;
+}[keyof typeof Chronos] | PluginMethods>;
 /**
  * * Accepted Input type for `Chronos`
  *
@@ -150,296 +152,8 @@ export type ChronosMethods = {
  *
  */
 export type ChronosInput = number | string | Date | Chronos;
-/** Represents key of `ChronosStatics` (each method and property) */
+/** Represents key of `ChronosStatics` (each static method and property) */
 export type ChronosStaticKey = keyof ChronosStatics;
-/** All the statics methods in `Chronos` class */
-export interface ChronosStatics {
-    /**
-     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
-     *
-     * @description
-     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
-     *
-     * Accepts no arguments (defaults to now).
-     *
-     * @returns Instance of `Chronos` with all methods and properties.
-     */
-    (): Chronos;
-    /**
-     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
-     *
-     * @description
-     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
-     *
-     * @param value - A date value in `number`, it should be a timestamp (milliseconds since the Unix epoch).
-     *
-     * @returns Instance of `Chronos` with all methods and properties.
-     */
-    (value: number): Chronos;
-    /**
-     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
-     *
-     * **Note**: *If a date is provided **without a time component**, the instance will default to `00:00:00.000` UTC
-     * and convert it to the **equivalent local time** using the current environment's UTC offset.*
-     *
-     * @description
-     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
-     *
-     * @param value - A date value in `string`, it should be in a format that can be parsed by the `Date` constructor.
-     *
-     * @returns Instance of `Chronos` with all methods and properties.
-     */
-    (value: string): Chronos;
-    /**
-     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
-     *
-     * **Note**: *If a date is provided **without a time component**, the instance will default to `00:00:00.000` UTC
-     * and convert it to the **equivalent local time** using the current environment's UTC offset.*
-     *
-     * @description
-     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
-     *
-     * @param value - A date value as `Date` object, it will be used as is.
-     *
-     * @returns Instance of `Chronos` with all methods and properties.
-     */
-    (value: Date): Chronos;
-    /**
-     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
-     *
-     * **Note**: *If a date is provided **without a time component**, the instance will default to `00:00:00.000` UTC
-     * and convert it to the **equivalent local time** using the current environment's UTC offset.*
-     *
-     * @description
-     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
-     *
-     * @param value - A date value as `Chronos` object.
-     *
-     * @returns Instance of `Chronos` with all methods and properties.
-     */
-    (value: Chronos): Chronos;
-    /**
-     * * Converts a date into a `Chronos` object and access to all `Chronos` methods and properties.
-     *
-     * @description
-     * This function serves as a wrapper around the `Chronos` class constructor and allows you to create a new `Chronos` instance from various types of date representations.
-     *
-     * @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.
-     *
-     * @returns Instance of `Chronos` with all methods and properties.
-     */
-    (year: number, month: number, date?: number, hours?: number, minutes?: number, seconds?: number, ms?: number): Chronos;
-    /**
-     * @static Injects a plugin into the `Chronos` system.
-     * @param plugin The plugin to inject.
-     *
-     * - **NOTE:** *Once a plugin is injected, all the registered methods for that plugin will be available for the whole project.*
-     * - See full list of plugins and the methods they register {@link https://toolbox.nazmul-nhb.dev/docs/classes/Chronos/plugins#-official-plugins here}.
-     */
-    use(plugin: ChronosPlugin): void;
-    /**
-     * * 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`
-     * @param options - Configure format string and whether to format using utc offset.
-     * @returns Formatted date string in desired format.
-     */
-    today(options?: FormatOptions): string;
-    /**
-     * * Returns a new `Chronos` instance representing yesterday's date.
-     *
-     * @returns A `Chronos` instance for the next calendar day.
-     */
-    yesterday(): Chronos;
-    /**
-     * * Returns a new `Chronos` instance representing tomorrow's date.
-     *
-     * @returns A `Chronos` instance for the next calendar day.
-     */
-    tomorrow(): Chronos;
-    /**
-     * * 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.
-     */
-    now(): number;
-    /**
-     * * Parses a date string with a given format (limited support only).
-     *
-     * * **Supported format tokens**:
-     * - `YYYY`: Full year (e.g., 2023)
-     * - `YY`: Two-digit year (e.g., 23 for 2023, 99 for 1999)
-     * - `MM`: Month (01-12)
-     * - `M`: 1-Digit Month (1-9)
-     * - `DD`: Day of the month (01-31)
-     * - `D`: 1-Digit Day of the month (1-9)
-     * - `HH`: Hour (00-23)
-     * - `H`: 1-Digit Hour (0-9)
-     * - `mm`: Minute (00-59)
-     * - `m`: 1-Digit Minute (0-9)
-     * - `ss`: Second (00-59)
-     * - `s`: 1-Digit Second (0-9)
-     *
-     * **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
-     * ```
-     *
-     * @param dateStr - The date string to be parsed
-     * @param format - The format of the date string. Tokens like `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss` are used to specify the structure.
-     * @returns A new `Chronos` instance representing the parsed date.
-     * @throws `Error` If the date string does not match the format.
-     */
-    parse(dateStr: string, format: string): Chronos;
-    /**
-     * * Creates a new `Chronos` instance with the provided time component(s).
-     *
-     * @param options - One or more time components to override.
-     * @returns A new `Chronos` instance with the provided time components applied.
-     *
-     * @remarks
-     * - Unspecified components are filled with the current time's (`Chronos`) respective values.
-     * - For option `month`, value should be number from `1` (January) to `12` (December).
-     * - If the `date` component is omitted and the current day is the last day of its month,
-     *   the resulting instance will also use the last day of the target month.
-     *   - _This rule does **not** apply if the `date` component is explicitly provided,
-     *     even if that value exceeds the last day of the target month._
-     *
-     * @example
-     * // Override only the year and month
-     * const c = Chronos.with({ year: 2025, month: 12 });
-     */
-    with(options: ChronosWithOptions): Chronos;
-    /**
-     * * 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.
-     */
-    utc(dateLike?: ChronosInput): Chronos;
-    /**
-     * * Formats a time-only string into a formatted time string.
-     *
-     * @param time - Time string to be formatted. Supported formats include:
-     * - `HH:mm` → e.g., `'14:50'`
-     * - `HH:mm:ss` → e.g., `'14:50:00'`
-     * - `HH:mm:ss.SSS` → e.g., `'14:50:00.800'`
-     * - `HH:mm+TimeZoneOffset(HH)` → e.g., `'14:50+06'`
-     * - `HH:mm:ss+TimeZoneOffset(HH)` → e.g., `'14:50:00+06'`
-     * - `HH:mm:ss+TimeZoneOffset(HH:mm)` → e.g., `'14:50:00+05:30'`
-     * - `HH:mm:ss.SSS+TimeZoneOffset(HH)` → e.g., `'14:50:00.800+06'`
-     * - `HH:mm:ss.SSS+TimeZoneOffset(HH:mm)` → e.g., `'14:50:00.800+06:30'`
-     *
-     * * *Input will default to today's date and assume local timezone if no offset is provided.*
-     *
-     * @param format - Format string accepted by `formatStrict()` method (`TimeParts`). Default: `hh:mm:ss a` → 02:33:36 pm.
-     * @returns Formatted time string in local (System) time.
-     */
-    formatTimePart(time: string, format?: TimeParts): string;
-    /**
-     * * Returns ISO date strings for each occurrence of a weekday from today, spanning a relative time range.
-     *
-     * @param day - The weekday to match (e.g., `'Wednesday'`, `'Sunday'`).
-     * @param options - Relative range (e.g., 7 days, 4 weeks) and output format (local with timezone or utc).
-     * @returns Array of ISO date strings in the specified format. Returns empty array if no matches in the time span.
-     *
-     * @example
-     * Chronos.getDatesForDay('Wednesday', { span: 7, unit: 'day' });
-     * //=> [ '2025-05-28T21:16:06.198+06:00', '2025-06-04T21:16:06.198+06:00' ]
-     *
-     * @example
-     * Chronos.getDatesForDay('Wednesday', {
-     *   span: 7,
-     *   unit: 'day',
-     *   format: 'utc'
-     * });
-     * //=> [ '2025-05-28T15:17:10.812Z', '2025-06-04T15:17:10.812Z' ]
-     */
-    getDatesForDay(day: WeekDay, options?: RelativeRangeOptions): string[];
-    /**
-     * * Returns ISO date strings for each occurrence of a weekday between two fixed dates.
-     *
-     * @param day - The weekday to match (e.g., `'Monday'`, `'Friday'`).
-     * @param options - Absolute date range (e.g. `'2025-06-30'`, ` new Date()`, `new Chronos()` etc.) and output format (local with timezone or utc).
-     * @returns Array of ISO date strings in the specified format. Returns empty array if no matches in the range.
-     *
-     * @example
-     * Chronos.getDatesForDay('Monday', {
-     *   from: '2025-05-28',
-     *   to: '2025-06-30',
-     *   format: 'local'
-     * });
-     * //=> [ '2025-01-06T...', '2025-01-13T...', ... ]
-     */
-    getDatesForDay(day: WeekDay, options?: DateRangeOptions): string[];
-    /**
-     * * Returns ISO date strings for each occurrence of a weekday.
-     *
-     * @param day - The weekday to match (e.g., `'Wednesday'`, `'Sunday'`).
-     * @param options - Relative range (e.g., 7 days, 4 weeks) or Absolute date range and output format.
-     * @returns Array of ISO date strings in the specified format.
-     */
-    getDatesForDay(day: WeekDay, options?: WeekdayOptions): string[];
-    /**
-     * * Returns earliest Chronos
-     * @param dates Date inputs.
-     */
-    min(...dates: ChronosInput[]): Chronos;
-    /**
-     * * Returns latest Chronos
-     * @param dates Date inputs.
-     */
-    max(...dates: ChronosInput[]): Chronos;
-    /**
-     * * Checks if the year in the date string or year (from 0 - 9999) 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.
-     *
-     * @description
-     * This method accepts different types of date inputs and extracts the year to check if it's a leap year.
-     * If the provided date is a `number`, it will be treated as a year (must be a valid year from 0 to 9999).
-     * If the year is out of this range (negative or larger than 9999), it will be treated as a Unix timestamp.
-     * If the provided date is a string or a `Date` object, it will be parsed and the year will be extracted.
-     * If a `Chronos` instance is passed, the year will be directly accessed from the instance.
-     *
-     * @param date - A `number` (year or Unix timestamp), `string`, `Date`, or `Chronos` instance representing a date.
-     * @returns `true` if the year is a leap year, `false` otherwise.
-     */
-    isLeapYear(date: ChronosInput): boolean;
-    /**
-     * * Checks if the given value is a valid `Date` object.
-     * - A value is considered valid if it is an instance of the built-in `Date` class.
-     * - This does not check whether the date itself is valid (e.g., `new Date('invalid')`).
-     * @param value - The value to test.
-     * @returns `true` if the value is a valid Date object, otherwise `false`.
-     */
-    isValidDate(value: unknown): value is Date;
-    /**
-     * * Checks if the given value is a valid date string.
-     * - A value is considered a valid date string if it is a string and can be parsed by `Date.parse()`.
-     * - This uses the native JavaScript date parser internally.
-     * @param value - The value to test.
-     * @returns `true` if the value is a valid date string, otherwise `false`.
-     */
-    isDateString(value: unknown): value is string;
-    /**
-     * * Checks if the given value is an instance of `Chronos`.
-     * - 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`.
-     */
-    isValidChronos(value: unknown): value is Chronos;
-}
 /** Names of time-zones */
 export type TimeZone = keyof typeof TIME_ZONES;
 /** Positive UTC hours */
@@ -639,9 +353,9 @@ export interface DateLike {
  * * Options for `Chronos` _static_ method `with()`
  *
  * @remarks
- * - At least one property must be provided.
+ * - Should provide at least one property.
  */
-export type ChronosWithOptions = RequireAtLeast<{
+export type ChronosWithOptions = Partial<{
     /** The full year (e.g., 2025). Years 0–99 are interpreted as 1900–1999. */
     year: number;
     /** Month number from 1 (January) to 12 (December). */
@@ -656,5 +370,4 @@ export type ChronosWithOptions = RequireAtLeast<{
     second: Enumerate<60>;
     /** Milliseconds of the second, from 0 to 999. */
     millisecond: Milliseconds;
-}, 1>;
-export {};
+}>;

package/dist/dts/object/convert.d.ts

@@ -1,4 +1,4 @@
-import type { DotNotationKey, GenericObject, Numberified, Stringified } from './types';
+import type { ConvertedObject, ConvertObjectOptions, GenericObject, NumericDotKey } from './types';
 /**
  * * Converts the values of specified keys in an object to numbers.
  * * Supports nested objects using dot-notation keys.
@@ -9,10 +9,7 @@ import type { DotNotationKey, GenericObject, Numberified, Stringified } from './
  *   - `convertTo`: The target type, either `"string"` or `"number"`.
  * @returns The modified object with the converted values as `"string"` or `"number"`.
  */
-export declare function convertObjectValues<T extends GenericObject, C extends 'string' | 'number'>(data: T, options: {
-    keys: DotNotationKey<T>[];
-    convertTo: C;
-}): C extends 'string' ? Stringified<T> : C extends 'number' ? Numberified<T> : never;
+export declare function convertObjectValues<T extends GenericObject, Key extends NumericDotKey<T>, C extends 'string' | 'number'>(data: T, options: ConvertObjectOptions<T, Key, C>): ConvertedObject<T, Key, C>;
 /**
  * * Converts the values of specified keys in an array of objects to numbers or strings.
  * * Supports nested objects using dot-notation keys.
@@ -23,10 +20,7 @@ export declare function convertObjectValues<T extends GenericObject, C extends '
  *   - `convertTo`: The target type, either `"string"` or `"number"`.
  * @returns The modified array of objects with the converted values as `"string"` or `"number"`.
  */
-export declare function convertObjectValues<T extends GenericObject, C extends 'string' | 'number'>(data: T[], options: {
-    keys: DotNotationKey<T>[];
-    convertTo: C;
-}): C extends 'string' ? Stringified<T>[] : C extends 'number' ? Numberified<T>[] : never;
+export declare function convertObjectValues<T extends GenericObject, Key extends NumericDotKey<T>, C extends 'string' | 'number'>(data: Array<T>, options: ConvertObjectOptions<T, Key, C>): Array<ConvertedObject<T, Key, C>>;
 /**
  * * Pick specific fields from an object and create a new object with specified fields.
  *

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

@@ -1,4 +1,5 @@
-import type { AdvancedTypes, NormalPrimitive } from '../types/index';
+import type { AdvancedTypes, NormalPrimitive, ValidArray } from '../types/index';
+import type { Prettify } from '../utils/types';
 /** - Generic object with `unknown` value */
 export type StrictObject = Record<string, unknown>;
 /** - Generic object but with `any` value */
@@ -106,12 +107,18 @@ export interface SanitizeOptions<T> {
      */
     requiredKeys?: '*' | DotNotationKey<T>[];
 }
-/** - Type of data value converted to `string` */
-export type Stringified<T> = {
-    [K in keyof T]: T[K] extends (infer U)[] ? Stringified<U>[] : T[K] extends object | null | undefined ? Stringified<T[K]> : T[K] extends string | number ? string : T[K];
-};
-/** - Type of data value converted to `number` */
-export type Numberified<T> = {
-    [K in keyof T]: T[K] extends (infer U)[] ? Numberified<U>[] : T[K] extends object | null | undefined ? Numberified<T[K]> : T[K] extends string ? number : T[K] extends number ? T[K] : number;
-};
+export interface ConvertObjectOptions<T extends GenericObject, Key extends NumericDotKey<T>, C extends 'string' | 'number'> {
+    /** Array of keys (properties) to convert to `number` or `string` */
+    keys: ValidArray<Key>;
+    /** Convert selected keys to target type: `number` or `string` */
+    convertTo: C;
+}
+/** Transform a single property */
+type ConvertProp<V, C extends 'string' | 'number'> = C extends 'string' ? V extends string | number ? string : V : C extends 'number' ? V extends string ? number : V : V;
+/** Extract sub-keys after prefix like `"props."` */
+type SubKey<S extends string, P extends string> = S extends `${P}.${infer Rest}` ? Rest : never;
+/** Transformed shape of the return type of `convertObjectValues` */
+export type ConvertedObject<T, Keys extends string, C extends 'string' | 'number'> = Prettify<{
+    [K in Extract<keyof T, string>]: K extends Keys ? ConvertProp<T[K], C> : T[K] extends AdvancedTypes ? T[K] : T[K] extends GenericObject ? ConvertedObject<T[K], SubKey<Keys, K>, C> : T[K];
+}>;
 export {};

package/dist/esm/date/chronos-statics.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/number/Currency.js

@@ -53,11 +53,12 @@ export class Currency {
         const url = `https://api.frankfurter.app/latest?amount=${this.#amount}&from=${this.#code}`;
         try {
             const res = await fetch(url, { redirect: 'error' });
-            if (!res.ok)
+            if (!res.ok) {
                 throw new Error(`FrankFurter Error: ${res.status}. "${res.statusText}"`);
+            }
             const data = await res.json();
             if (!data.rates?.[to]) {
-                throw new Error(`Currency "${to}" not found in FrankFurter Database!`);
+                throw new Error(`Currency "${to}" not allowed or not found in FrankFurter Database!`);
             }
             return data.rates[to] / this.#amount;
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.20.46",
-  "description": "A versatile collection of smart, efficient, and reusable utility functions and classes for everyday development needs.",
+  "version": "4.20.50",
+  "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",
   "types": "dist/dts/index.d.ts",
@@ -85,11 +85,17 @@
     "dayjs",
     "pluralize",
     "pluralizer",
+    "singularize",
+    "singularizer",
+    "verbalize",
+    "verbalizer",
     "date",
     "day",
     "chalk",
     "console",
     "style",
+    "stylog",
+    "log styler",
     "log",
     "status-codes",
     "http-status",