nhb-toolbox
Version:
A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.
445 lines (444 loc) • 24.8 kB
TypeScript
import type { Enumerate, NumberRange } from '../../number/types';
import type { RangeTuple } from '../../utils/types';
import type { $Chronos, AcademicYear, BusinessOptionsBasic, BusinessOptionsWeekends, ChronosInput, Quarter } from '../types';
declare module '../Chronos' {
interface Chronos {
/**
* @instance Checks if the current date falls on a weekend using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. The number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns `true` if the current date is a weekend day according to the provided parameters; otherwise `false`.
*
* @description
* Determines whether the current date is considered part of the weekend.
*
* **Behavior:**
* - By default (`weekStartsOn = 0`, `weekendLength = 2`), Saturday (6) and Friday (5) are considered weekend.
* - `weekStartsOn` sets the start of the week for calculating weekend days.
* - `weekendLength` sets how many days at the end of the week are treated as weekend.
*
* @example
* // Default: Saturday & Friday are weekend
* new Chronos().isWeekend();
*
* // Custom week start (Monday) with 2-day weekend (Saturday & Sunday)
* new Chronos().isWeekend(1, 2);
*
* // Custom 3-day weekend (Friday, Saturday, Sunday)
* new Chronos().isWeekend(1, 3);
*/
isWeekend(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): boolean;
/**
* @instance Checks if the current date falls on a weekend using indices of weekend days.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Can pass only 1-4 elements.
* @returns `true` if the current date is a weekend day according to the provided `weekendDays`; otherwise `false`.
*
* @description
* Determines whether the current date is considered part of the weekend.
*
* **Behavior:**
* - `weekendDays` is used directly as the weekend days instead of calculating from `weekStartsOn` + `weekendLength`.
*
* @example
* // Fully custom weekend days (Sunday, Friday, Saturday)
* new Chronos().isWeekend([0, 5, 6]);
*/
isWeekend(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): boolean;
/**
* @instance Checks if the current date is a workday (non-weekend day) using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. The number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns `true` if the current date is a work day according to the provided parameters; otherwise `false`.
*
* @description
* Determines whether the current date is considered as workday. Internally uses {@link isWeekend} method.
*
* **Behavior:**
* - By default (`weekStartsOn = 0`, `weekendLength = 2`), Saturday (6) and Friday (5) are considered weekend.
* - `weekStartsOn` sets the start of the week for calculating weekend days.
* - `weekendLength` sets how many days at the end of the week are treated as weekend.
*/
isWorkday(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): boolean;
/**
* @instance Checks if the current date is a workday (non-weekend day) using indices of weekend days.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Can pass only 1-4 elements.
* @returns `true` if the current date is a work day according to the provided `weekendDays`; otherwise `false`.
*
* @description
* Determines whether the current date is considered as workday. Internally uses {@link isWeekend} method.
*
* **Behavior:**
* - `weekendDays` is used directly as the weekend days instead of calculating from `weekStartsOn` + `weekendLength`.
*/
isWorkday(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): boolean;
/**
* @instance Returns the next business day (workday) after the current date using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. The number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns A new `Chronos` instance representing the next business day (work day), normalized to the start of that day.
*
* @description
* Moves forward one day at a time to find the nearest day that is **not** considered a weekend.
*
* **Behavior:**
* - Weekend days are automatically calculated from `weekStartsOn` and `weekendLength`.
* - The search begins on the day immediately after the current date.
* - Always returns a new immutable `Chronos` instance, normalized to the start of the day.
*
* @example
* // Default weekend (Friday & Saturday)
* new Chronos('2025-01-23').nextWorkday();
*
* // Custom start of week (Monday) with 2-day weekend (Saturday & Sunday)
* new Chronos().nextWorkday(1, 2);
*
* // Custom 3-day weekend (Fri, Sat, Sun)
* new Chronos().nextWorkday(1, 3);
*/
nextWorkday(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): Chronos;
/**
* @instance Returns the next business day (workday) after the current date using custom weekend day indices.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain between 1 and 4 elements.
* @returns A new `Chronos` instance representing the next business day (workday), normalized to the start of that day.
*
* @description
* Moves forward one day at a time until a day is reached that is **not** included in `weekendDays`.
*
* **Behavior:**
* - `weekendDays` is used directly and overrides any automatic weekend calculation.
* - The search starts from the day immediately following the current date.
* - Returns a new immutable `Chronos` instance every time, normalized to the start of the day.
*
* @example
* // Custom weekend days (Friday, Saturday, Sunday)
* new Chronos().nextWorkday([5, 6, 0]);
*/
nextWorkday(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): Chronos;
/**
* @instance Returns the next weekend day after the current date using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. The number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns A new `Chronos` instance representing the next weekend day, normalized to the start of that day.
*
* @description
* Moves forward one day at a time until a weekend day is reached.
*
* **Behavior:**
* - Weekend days are automatically determined from `weekStartsOn` and `weekendLength`.
* - The scan begins on the next calendar day.
* - Produces a new immutable `Chronos` instance, normalized to the start of the day.
*
* @example
* // Default weekend (Friday & Saturday)
* new Chronos('2025-01-23').nextWeekend();
*
* // Custom start of week (Monday) with 2-day weekend (Saturday & Sunday)
* new Chronos().nextWeekend(1, 2);
*
* // Custom 3-day weekend (Fri, Sat, Sun)
* new Chronos().nextWeekend(1, 3);
*/
nextWeekend(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): Chronos;
/**
* @instance Returns the next weekend day after the current date using custom weekend day indices.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain 1–4 elements.
* @returns A new `Chronos` instance representing the next weekend day, normalized to the start of that day.
*
* @description
* Moves ahead through the calendar until the date matches one of the provided `weekendDays`.
*
* **Behavior:**
* - `weekendDays` is used exactly as provided, skipping automatic weekend computation.
* - The search begins from the next day.
* - Always yields a new immutable `Chronos` instance, normalized to the start of the day.
*
* @example
* // Custom weekend days (Sunday, Friday, Saturday)
* new Chronos().nextWeekend([0, 5, 6]);
*/
nextWeekend(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): Chronos;
/**
* @instance Returns the previous workday before the current date using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. The number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns A new `Chronos` instance representing the previous workday, normalized to the start of that day.
*
* @description
* Moves backward one day at a time to find the nearest day that is **not** considered a weekend.
*
* **Behavior:**
* - Weekend days are automatically calculated from `weekStartsOn` and `weekendLength`.
* - The search begins on the day immediately before the current date.
* - Always returns a new immutable `Chronos` instance.
*
* @example
* // Default weekend (Friday & Saturday)
* new Chronos('2025-01-23').previousWorkday();
*
* // Custom start of week (Monday) with 2-day weekend (Saturday & Sunday)
* new Chronos().previousWorkday(1, 2);
*
* // Custom 3-day weekend (Fri, Sat, Sun)
* new Chronos().previousWorkday(1, 3);
*/
previousWorkday(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): Chronos;
/**
* @instance Returns the previous workday before the current date using custom weekend day indices.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain between 1 and 4 elements.
* @returns A new `Chronos` instance representing the previous workday, normalized to the start of that day.
*
* @description
* Moves backward one day at a time until a day is reached that is **not** included in `weekendDays`.
*
* **Behavior:**
* - `weekendDays` is used directly and overrides any automatic weekend calculation.
* - The search starts from the day immediately before the current date.
* - Returns a new immutable `Chronos` instance every time.
*
* @example
* // Custom weekend days (Friday, Saturday, Sunday)
* new Chronos().previousWorkday([5, 6, 0]);
*/
previousWorkday(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): Chronos;
/**
* @instance Returns the previous weekend day before the current date using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. The number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns A new `Chronos` instance representing the previous weekend day, normalized to the start of that day.
*
* @description
* Moves backward one day at a time until a weekend day is reached.
*
* **Behavior:**
* - Weekend days are automatically determined from `weekStartsOn` and `weekendLength`.
* - The scan begins on the previous calendar day.
* - Produces a new immutable `Chronos` instance.
*
* @example
* // Default weekend (Friday & Saturday)
* new Chronos('2025-01-23').previousWeekend();
*
* // Custom start of week (Monday) with 2-day weekend (Saturday & Sunday)
* new Chronos().previousWeekend(1, 2);
*
* // Custom 3-day weekend (Fri, Sat, Sun)
* new Chronos().previousWeekend(1, 3);
*/
previousWeekend(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): Chronos;
/**
* @instance Returns the previous weekend day before the current date using custom weekend day indices.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain 1–4 elements.
* @returns A new `Chronos` instance representing the previous weekend day, normalized to the start of that day.
*
* @description
* Moves backward through the calendar until the date matches one of the provided `weekendDays`.
*
* **Behavior:**
* - `weekendDays` is used exactly as provided, skipping automatic weekend computation.
* - The search begins from the previous day.
* - Always yields a new immutable `Chronos` instance.
*
* @example
* // Custom weekend days (Sunday, Friday, Saturday)
* new Chronos().previousWeekend([0, 5, 6]);
*/
previousWeekend(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): Chronos;
/**
* @instance Calculates the number of workdays between the current date and another using week start day and weekend length.
*
* @param other The target date to compare against.
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. Number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns The total count of workdays between the two dates.
*
* @remarks This calculation is exclusive of the starting date and inclusive of the ending date.
*
* @example
* new Chronos('2025-12-15').workdaysBetween('2025-12-21');
* // default weekend Friday & Saturday -> 4
*/
workdaysBetween(other: ChronosInput, weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): number;
/**
* @instance Calculates the number of workdays between the current date and another using custom weekend days.
*
* @param other The target date to compare against.
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain 1–4 elements.
* @returns The total count of workdays between the two dates.
*
* @remarks This calculation is exclusive of the starting date and inclusive of the ending date.
*
* @example
* new Chronos('2025-12-15').workdaysBetween('2025-12-20', [0, 6]);
* // custom weekend Sunday & Saturday -> 4
*/
workdaysBetween(other: ChronosInput, weekendDays: RangeTuple<Enumerate<7>, 1, 4>): number;
/**
* @instance Calculates the number of weekends between the current date and another using week start day and weekend length.
*
* @param other The target date to compare against.
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. Number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns The total count of weekends between the two dates.
*
* @remarks This calculation is exclusive of the starting date and inclusive of the ending date.
*
* @example
* new Chronos('2025-12-15').weekendsBetween('2025-12-21');
* // default weekend Friday & Saturday -> 2
*/
weekendsBetween(other: ChronosInput, weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): number;
/**
* @instance Calculates the number of weekends between the current date and another using custom weekend days.
*
* @param other The target date to compare against.
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain 1–4 elements.
* @returns The total count of weekends between the two dates.
*
* @remarks This calculation is exclusive of the starting date and inclusive of the ending date.
*
* @example
* new Chronos('2025-12-15').weekendsBetween('2025-12-20', [0, 6]);
* // custom weekend Sunday & Saturday -> 1
*/
weekendsBetween(other: ChronosInput, weekendDays: RangeTuple<Enumerate<7>, 1, 4>): number;
/**
* @instance Counts the number of workdays in the current month using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. Number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns Number of workdays in the current month.
*
* @example
* new Chronos('2025-01-01').workdaysInMonth(); // default weekend Friday & Saturday -> 22
*/
workdaysInMonth(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): number;
/**
* @instance Counts the number of workdays in the current month using custom weekend days.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain 1–4 elements.
* @returns Number of workdays in the current month.
*
* @example
* new Chronos('2025-01-01').workdaysInMonth([0, 6]); // Sunday & Saturday are weekends
*/
workdaysInMonth(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): number;
/**
* @instance Counts the number of weekends in the current month using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. Number of consecutive days at the end of the week considered as weekend. Must be between 1 and 4. Default is `2`.
* @returns Number of weekends in the current month.
*
* @example
* new Chronos('2025-01-01').weekendsInMonth(); // default weekend Friday & Saturday -> 8
*/
weekendsInMonth(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): number;
/**
* @instance Counts the number of weekends in the current month using custom weekend days.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain 1–4 elements.
* @returns Number of weekends in the current month.
*
* @example
* new Chronos('2025-01-01').weekendsInMonth([0, 6]); // Sunday & Saturday are weekends
*/
weekendsInMonth(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): number;
/**
* @instance Counts the number of workdays in the current year using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. Number of consecutive days at the end of the week considered as weekend. Must be between 1–4. Default is `2`.
* @returns Number of workdays in the current year.
*
* @example
* new Chronos('2025-01-01').workdaysInYear(); // default weekend Friday & Saturday -> 261
*/
workdaysInYear(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): number;
/**
* @instance Counts the number of workdays in the current year using custom weekend days.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain 1–4 elements.
* @returns Number of workdays in the current year.
*
* @example
* new Chronos('2025-01-01').workdaysInYear([0, 6]); // Sunday & Saturday are weekends
*/
workdaysInYear(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): number;
/**
* @instance Counts the number of weekends in the current year using week start day and weekend length.
*
* @param weekStartsOn Optional. The day index (0–6) that the week starts on. Default is `0` (Sunday).
* @param weekendLength Optional. Number of consecutive days at the end of the week considered as weekend. Must be between 1–4. Default is `2`.
* @returns Number of weekends in the current year.
*
* @example
* new Chronos('2025-01-01').weekendsInYear(); // default weekend Friday & Saturday -> 104
*/
weekendsInYear(weekStartsOn?: Enumerate<7>, weekendLength?: NumberRange<1, 4>): number;
/**
* @instance Counts the number of weekends in the current year using custom weekend days.
*
* @param weekendDays A tuple of custom weekend day indices (0–6). Must contain 1–4 elements.
* @returns Number of weekends in the current year.
*
* @example
* new Chronos('2025-01-01').weekendsInYear([0, 6]); // Sunday & Saturday are weekends
*/
weekendsInYear(weekendDays: RangeTuple<Enumerate<7>, 1, 4>): number;
/**
* @instance Checks if the current time fall within business hours using week start day and weekend length & other options.
*
* @param options Options to configure business hour and weekends.
*
* @returns Whether the current time is within business hours.
*
* @remarks
* - Business hours are typically 9 AM to 5 PM on weekdays.
* - Supports standard and overnight business hours. Overnight means `end < start`.
* - Example: `businessStartHour = 22`, `businessEndHour = 6` will cover 10 PM to 6 AM next day.
*
* - *Weekends are determined by `weekStartsOn` and `weekendLength` using the {@link isWorkday} method.*
*/
isBusinessHour(options?: BusinessOptionsBasic): boolean;
/**
* @instance Checks if the current time fall within business hours using indices of weekend days & other options.
*
* @param options Options to configure business hour and weekends.
*
* @returns Whether the current time is within business hours.
*
* @remarks
* - Business hours are typically 9 AM to 5 PM on weekdays.
* - Supports standard and overnight business hours. Overnight means `end < start`.
* - Example: `businessStartHour = 22`, `businessEndHour = 6` will cover 10 PM to 6 AM next day.
*
* - *Weekends are determined by `weekendDays` tuple using the {@link isWorkday} method.*
*/
isBusinessHour(options?: BusinessOptionsWeekends): boolean;
/**
* @instance Returns the academic year based on a typical start in `July` and end in `June`.
* @returns The academic year in format `YYYY-YYYY`.
*/
toAcademicYear(): AcademicYear;
/**
* @instance Returns the fiscal quarter based on custom fiscal year start (defaults to July).
* @param startMonth - The fiscal year start month (1-12), default is July (`7`).
* @returns The fiscal quarter (1-4).
*/
toFiscalQuarter(startMonth?: NumberRange<1, 12>): Quarter;
}
}
/** * Plugin to inject `business` related methods */
export declare const businessPlugin: ($Chronos: $Chronos) => void;