chronos-date 1.0.0

package/dist/plugins/businessPlugin.d.cts

@@ -0,0 +1,446 @@
+import { C as $Chronos, D as ChronosInput, Dn as RangeTuple, Tn as NumberRange, Tt as Quarter, a as BusinessOptionsWeekends, i as BusinessOptionsBasic, r as AcademicYear, wn as Enumerate } from "../types-DPTQ_yLx.cjs";
+
+//#region src/plugins/businessPlugin.d.ts
+declare module '../' {
+  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 */
+declare const businessPlugin: ($Chronos: $Chronos) => void;
+//#endregion
+export { businessPlugin };