@intech-software/chronera 0.1.4 → 0.1.6

package/dist/operations/business-days.js

@@ -1,28 +1,82 @@
 import { getIsoDayOfWeek } from "../core/iso-week.js";
+import { localDate } from "../core/local-date.js";
+import { gregorianFromAbsoluteDay } from "../calendar/gregory/absolute-day.js";
 import { ChroneraError } from "../errors/errors.js";
 import { addDays, getAbsoluteDay } from "./convenience.js";
+import { isPublicHoliday } from "./holidays.js";
+import { getHolidayCalendar } from "../holidays/registry.js";
 /**
- * Returns true if the specified date falls on a weekend (Saturday or Sunday).
- * Works across all calendars (Gregorian, Thai Buddhist, Japanese, Hijri, etc.).
+ * Checks whether a given absolute day is a weekend according to options or country defaults.
  */
-export function isWeekend(date) {
-    const abs = getAbsoluteDay(date);
+function isWeekendForOptions(abs, options) {
     const dow = getIsoDayOfWeek(abs);
+    if (options?.weekendDays && options.weekendDays.length > 0) {
+        return options.weekendDays.includes(dow);
+    }
+    if (typeof options?.holidays === "string" ||
+        (typeof options?.holidays === "object" &&
+            options?.holidays !== null &&
+            "country" in options.holidays)) {
+        try {
+            const cal = getHolidayCalendar(options.holidays);
+            if (cal.defaultWeekendDays) {
+                return cal.defaultWeekendDays.includes(dow);
+            }
+        }
+        catch {
+            // Fallback to standard Saturday & Sunday
+        }
+    }
     return dow === 6 || dow === 7;
 }
 /**
- * Returns true if the specified date falls on a weekday (Monday through Friday).
- * Works across all calendars (Gregorian, Thai Buddhist, Japanese, Hijri, etc.).
+ * Returns true if the specified absolute day is a non-working day (weekend or holiday).
+ */
+function isNonWorkingDay(abs, options) {
+    if (isWeekendForOptions(abs, options)) {
+        return true;
+    }
+    const holidays = options?.holidays;
+    if (!holidays) {
+        return false;
+    }
+    const gFields = gregorianFromAbsoluteDay(abs);
+    const gDate = localDate(gFields.year, gFields.month, gFields.day);
+    if (typeof holidays === "function") {
+        return holidays(gDate);
+    }
+    if (typeof holidays === "string" || "rules" in holidays) {
+        return isPublicHoliday(gDate, holidays);
+    }
+    return holidays.some((hDate) => getAbsoluteDay(hDate) === abs);
+}
+/**
+ * Returns true if the specified date falls on a weekend.
+ * Supports custom weekend definitions per country (e.g. Thursday & Friday for Iran).
+ */
+export function isWeekend(date, options) {
+    const abs = getAbsoluteDay(date);
+    return isWeekendForOptions(abs, options);
+}
+/**
+ * Returns true if the specified date falls on a weekday.
+ */
+export function isWeekday(date, options) {
+    return !isWeekend(date, options);
+}
+/**
+ * Returns true if the specified date is a business day (neither weekend nor public holiday).
  */
-export function isWeekday(date) {
-    return !isWeekend(date);
+export function isBusinessDay(date, options) {
+    const abs = getAbsoluteDay(date);
+    return !isNonWorkingDay(abs, options);
 }
 /**
- * Adds business days to a LocalDate or CalendarDate, skipping Saturdays and Sundays.
+ * Adds business days to a LocalDate or CalendarDate, skipping weekends and optionally public holidays.
  * Supports positive, negative, and zero day additions.
- * Uses O(1) mathematical week advancement for large intervals while preserving exact calendar semantics.
+ * Uses O(1) mathematical week advancement when no holidays are provided, or iterative evaluation with holiday constraints.
  */
-export function addBusinessDays(date, amount) {
+export function addBusinessDays(date, amount, options) {
     if (!Number.isFinite(amount)) {
         throw new ChroneraError("CHRONERA_OUT_OF_RANGE", "Amount must be a finite integer.");
     }
@@ -34,17 +88,31 @@ export function addBusinessDays(date, amount) {
     let currentAbs = startAbs;
     let remaining = intAmount;
     const step = remaining > 0 ? 1 : -1;
-    while (remaining !== 0) {
-        const currentDow = getIsoDayOfWeek(currentAbs);
-        if (currentDow !== 6 && currentDow !== 7 && Math.abs(remaining) >= 5) {
-            const fullWeeks = Math.trunc(remaining / 5);
-            currentAbs += fullWeeks * 7;
-            remaining %= 5;
+    // Fast-path: no holidays or custom weekends
+    const hasHolidays = Boolean(options?.holidays);
+    const hasCustomWeekends = Boolean(options?.weekendDays);
+    if (!hasHolidays && !hasCustomWeekends) {
+        while (remaining !== 0) {
+            const currentDow = getIsoDayOfWeek(currentAbs);
+            if (currentDow !== 6 && currentDow !== 7 && Math.abs(remaining) >= 5) {
+                const fullWeeks = Math.trunc(remaining / 5);
+                currentAbs += fullWeeks * 7;
+                remaining %= 5;
+            }
+            else {
+                currentAbs += step;
+                const dow = getIsoDayOfWeek(currentAbs);
+                if (dow !== 6 && dow !== 7) {
+                    remaining -= step;
+                }
+            }
         }
-        else {
+    }
+    else {
+        // Exact evaluation with holiday and custom weekend constraints
+        while (remaining !== 0) {
             currentAbs += step;
-            const dow = getIsoDayOfWeek(currentAbs);
-            if (dow !== 6 && dow !== 7) {
+            if (!isNonWorkingDay(currentAbs, options)) {
                 remaining -= step;
             }
         }
@@ -53,39 +121,49 @@ export function addBusinessDays(date, amount) {
     return addDays(date, deltaDays);
 }
 /**
- * Subtracts business days from a LocalDate or CalendarDate, skipping weekends.
+ * Subtracts business days from a LocalDate or CalendarDate, skipping weekends and optional holidays.
  */
-export function subtractBusinessDays(date, amount) {
-    return addBusinessDays(date, -amount);
+export function subtractBusinessDays(date, amount, options) {
+    return addBusinessDays(date, -amount, options);
 }
 /**
  * Returns the signed count of business days between two dates (left - right).
  * Positive if left is after right, negative if left is before right, 0 if identical.
- * Works across all calendar systems with O(1) mathematical week acceleration.
  */
-export function diffInBusinessDays(left, right) {
+export function diffInBusinessDays(left, right, options) {
     const absLeft = getAbsoluteDay(left);
     const absRight = getAbsoluteDay(right);
     if (absLeft === absRight) {
         return 0;
     }
     if (absLeft < absRight) {
-        return -diffInBusinessDays(right, left);
+        return -diffInBusinessDays(right, left, options);
     }
     let count = 0;
     let current = absRight;
-    // O(1) acceleration: any consecutive 7 calendar days contains exactly 5 business days
-    const fullWeeks = Math.floor((absLeft - current) / 7);
-    if (fullWeeks > 0) {
-        count += fullWeeks * 5;
-        current += fullWeeks * 7;
+    const hasHolidays = Boolean(options?.holidays);
+    const hasCustomWeekends = Boolean(options?.weekendDays);
+    if (!hasHolidays && !hasCustomWeekends) {
+        // Fast-path O(1) acceleration: any consecutive 7 calendar days contains exactly 5 business days
+        const fullWeeks = Math.floor((absLeft - current) / 7);
+        if (fullWeeks > 0) {
+            count += fullWeeks * 5;
+            current += fullWeeks * 7;
+        }
+        while (current < absLeft) {
+            current++;
+            const dow = getIsoDayOfWeek(current);
+            if (dow !== 6 && dow !== 7) {
+                count++;
+            }
+        }
     }
-    // Step through remainder (at most 6 days)
-    while (current < absLeft) {
-        current++;
-        const dow = getIsoDayOfWeek(current);
-        if (dow !== 6 && dow !== 7) {
-            count++;
+    else {
+        while (current < absLeft) {
+            current++;
+            if (!isNonWorkingDay(current, options)) {
+                count++;
+            }
         }
     }
     return count;

package/dist/operations/business-days.js.map

@@ -1 +1 @@
-{"version":3,"file":"business-days.js","sourceRoot":"","sources":["../../src/operations/business-days.ts"],"names":[],"mappings":"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","sourcesContent":["import { getIsoDayOfWeek } from \"../core/iso-week.js\";\nimport { ChroneraError } from \"../errors/errors.js\";\nimport { addDays, getAbsoluteDay } from \"./convenience.js\";\n\nimport type { DateOrCalendarDate } from \"../public-types.js\";\n\n/**\n * Returns true if the specified date falls on a weekend (Saturday or Sunday).\n * Works across all calendars (Gregorian, Thai Buddhist, Japanese, Hijri, etc.).\n */\nexport function isWeekend(date: DateOrCalendarDate): boolean {\n  const abs = getAbsoluteDay(date);\n  const dow = getIsoDayOfWeek(abs);\n  return dow === 6 || dow === 7;\n}\n\n/**\n * Returns true if the specified date falls on a weekday (Monday through Friday).\n * Works across all calendars (Gregorian, Thai Buddhist, Japanese, Hijri, etc.).\n */\nexport function isWeekday(date: DateOrCalendarDate): boolean {\n  return !isWeekend(date);\n}\n\n/**\n * Adds business days to a LocalDate or CalendarDate, skipping Saturdays and Sundays.\n * Supports positive, negative, and zero day additions.\n * Uses O(1) mathematical week advancement for large intervals while preserving exact calendar semantics.\n */\nexport function addBusinessDays<T extends DateOrCalendarDate>(\n  date: T,\n  amount: number,\n): T {\n  if (!Number.isFinite(amount)) {\n    throw new ChroneraError(\n      \"CHRONERA_OUT_OF_RANGE\",\n      \"Amount must be a finite integer.\",\n    );\n  }\n\n  const intAmount = Math.trunc(amount);\n  if (intAmount === 0) {\n    return date;\n  }\n\n  const startAbs = getAbsoluteDay(date);\n  let currentAbs = startAbs;\n  let remaining = intAmount;\n  const step = remaining > 0 ? 1 : -1;\n\n  while (remaining !== 0) {\n    const currentDow = getIsoDayOfWeek(currentAbs);\n    if (currentDow !== 6 && currentDow !== 7 && Math.abs(remaining) >= 5) {\n      const fullWeeks = Math.trunc(remaining / 5);\n      currentAbs += fullWeeks * 7;\n      remaining %= 5;\n    } else {\n      currentAbs += step;\n      const dow = getIsoDayOfWeek(currentAbs);\n      if (dow !== 6 && dow !== 7) {\n        remaining -= step;\n      }\n    }\n  }\n\n  const deltaDays = currentAbs - startAbs;\n  return addDays(date, deltaDays);\n}\n\n/**\n * Subtracts business days from a LocalDate or CalendarDate, skipping weekends.\n */\nexport function subtractBusinessDays<T extends DateOrCalendarDate>(\n  date: T,\n  amount: number,\n): T {\n  return addBusinessDays(date, -amount);\n}\n\n/**\n * Returns the signed count of business days between two dates (left - right).\n * Positive if left is after right, negative if left is before right, 0 if identical.\n * Works across all calendar systems with O(1) mathematical week acceleration.\n */\nexport function diffInBusinessDays(\n  left: DateOrCalendarDate,\n  right: DateOrCalendarDate,\n): number {\n  const absLeft = getAbsoluteDay(left);\n  const absRight = getAbsoluteDay(right);\n\n  if (absLeft === absRight) {\n    return 0;\n  }\n\n  if (absLeft < absRight) {\n    return -diffInBusinessDays(right, left);\n  }\n\n  let count = 0;\n  let current = absRight;\n\n  // O(1) acceleration: any consecutive 7 calendar days contains exactly 5 business days\n  const fullWeeks = Math.floor((absLeft - current) / 7);\n  if (fullWeeks > 0) {\n    count += fullWeeks * 5;\n    current += fullWeeks * 7;\n  }\n\n  // Step through remainder (at most 6 days)\n  while (current < absLeft) {\n    current++;\n    const dow = getIsoDayOfWeek(current);\n    if (dow !== 6 && dow !== 7) {\n      count++;\n    }\n  }\n\n  return count;\n}\n"]}
+{"version":3,"file":"business-days.js","sourceRoot":"","sources":["../../src/operations/business-days.ts"],"names":[],"mappings":"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","sourcesContent":["import { getIsoDayOfWeek } from \"../core/iso-week.js\";\nimport { localDate } from \"../core/local-date.js\";\nimport { gregorianFromAbsoluteDay } from \"../calendar/gregory/absolute-day.js\";\nimport { ChroneraError } from \"../errors/errors.js\";\nimport { addDays, getAbsoluteDay } from \"./convenience.js\";\nimport { isPublicHoliday } from \"./holidays.js\";\nimport { getHolidayCalendar } from \"../holidays/registry.js\";\n\nimport type { CountryCode, HolidayCalendar } from \"../holidays/types.js\";\nimport type { DateOrCalendarDate, LocalDate } from \"../public-types.js\";\n\n/**\n * Options for business days arithmetic and queries.\n */\nexport interface BusinessDaysOptions {\n  /**\n   * Country code (e.g. \"TH\", \"JP\", \"US\") or custom HolidayCalendar or holiday date list or holiday predicate.\n   */\n  readonly holidays?:\n    | CountryCode\n    | string\n    | HolidayCalendar\n    | readonly DateOrCalendarDate[]\n    | ((date: LocalDate) => boolean);\n  /**\n   * Custom weekend days (defaults to [6, 7], or [4, 5] if country is Iran, etc.).\n   */\n  readonly weekendDays?: readonly number[];\n}\n\n/**\n * Checks whether a given absolute day is a weekend according to options or country defaults.\n */\nfunction isWeekendForOptions(\n  abs: number,\n  options?: BusinessDaysOptions,\n): boolean {\n  const dow = getIsoDayOfWeek(abs);\n  if (options?.weekendDays && options.weekendDays.length > 0) {\n    return options.weekendDays.includes(dow);\n  }\n\n  if (\n    typeof options?.holidays === \"string\" ||\n    (typeof options?.holidays === \"object\" &&\n      options?.holidays !== null &&\n      \"country\" in options.holidays)\n  ) {\n    try {\n      const cal = getHolidayCalendar(options.holidays);\n      if (cal.defaultWeekendDays) {\n        return cal.defaultWeekendDays.includes(dow);\n      }\n    } catch {\n      // Fallback to standard Saturday & Sunday\n    }\n  }\n\n  return dow === 6 || dow === 7;\n}\n\n/**\n * Returns true if the specified absolute day is a non-working day (weekend or holiday).\n */\nfunction isNonWorkingDay(abs: number, options?: BusinessDaysOptions): boolean {\n  if (isWeekendForOptions(abs, options)) {\n    return true;\n  }\n\n  const holidays = options?.holidays;\n  if (!holidays) {\n    return false;\n  }\n\n  const gFields = gregorianFromAbsoluteDay(abs);\n  const gDate = localDate(gFields.year, gFields.month, gFields.day);\n\n  if (typeof holidays === \"function\") {\n    return holidays(gDate);\n  }\n\n  if (typeof holidays === \"string\" || \"rules\" in holidays) {\n    return isPublicHoliday(gDate, holidays);\n  }\n\n  return holidays.some((hDate) => getAbsoluteDay(hDate) === abs);\n}\n\n/**\n * Returns true if the specified date falls on a weekend.\n * Supports custom weekend definitions per country (e.g. Thursday & Friday for Iran).\n */\nexport function isWeekend(\n  date: DateOrCalendarDate,\n  options?: Pick<BusinessDaysOptions, \"weekendDays\" | \"holidays\">,\n): boolean {\n  const abs = getAbsoluteDay(date);\n  return isWeekendForOptions(abs, options);\n}\n\n/**\n * Returns true if the specified date falls on a weekday.\n */\nexport function isWeekday(\n  date: DateOrCalendarDate,\n  options?: Pick<BusinessDaysOptions, \"weekendDays\" | \"holidays\">,\n): boolean {\n  return !isWeekend(date, options);\n}\n\n/**\n * Returns true if the specified date is a business day (neither weekend nor public holiday).\n */\nexport function isBusinessDay(\n  date: DateOrCalendarDate,\n  options?: BusinessDaysOptions,\n): boolean {\n  const abs = getAbsoluteDay(date);\n  return !isNonWorkingDay(abs, options);\n}\n\n/**\n * Adds business days to a LocalDate or CalendarDate, skipping weekends and optionally public holidays.\n * Supports positive, negative, and zero day additions.\n * Uses O(1) mathematical week advancement when no holidays are provided, or iterative evaluation with holiday constraints.\n */\nexport function addBusinessDays<T extends DateOrCalendarDate>(\n  date: T,\n  amount: number,\n  options?: BusinessDaysOptions,\n): T {\n  if (!Number.isFinite(amount)) {\n    throw new ChroneraError(\n      \"CHRONERA_OUT_OF_RANGE\",\n      \"Amount must be a finite integer.\",\n    );\n  }\n\n  const intAmount = Math.trunc(amount);\n  if (intAmount === 0) {\n    return date;\n  }\n\n  const startAbs = getAbsoluteDay(date);\n  let currentAbs = startAbs;\n  let remaining = intAmount;\n  const step = remaining > 0 ? 1 : -1;\n\n  // Fast-path: no holidays or custom weekends\n  const hasHolidays = Boolean(options?.holidays);\n  const hasCustomWeekends = Boolean(options?.weekendDays);\n\n  if (!hasHolidays && !hasCustomWeekends) {\n    while (remaining !== 0) {\n      const currentDow = getIsoDayOfWeek(currentAbs);\n      if (currentDow !== 6 && currentDow !== 7 && Math.abs(remaining) >= 5) {\n        const fullWeeks = Math.trunc(remaining / 5);\n        currentAbs += fullWeeks * 7;\n        remaining %= 5;\n      } else {\n        currentAbs += step;\n        const dow = getIsoDayOfWeek(currentAbs);\n        if (dow !== 6 && dow !== 7) {\n          remaining -= step;\n        }\n      }\n    }\n  } else {\n    // Exact evaluation with holiday and custom weekend constraints\n    while (remaining !== 0) {\n      currentAbs += step;\n      if (!isNonWorkingDay(currentAbs, options)) {\n        remaining -= step;\n      }\n    }\n  }\n\n  const deltaDays = currentAbs - startAbs;\n  return addDays(date, deltaDays);\n}\n\n/**\n * Subtracts business days from a LocalDate or CalendarDate, skipping weekends and optional holidays.\n */\nexport function subtractBusinessDays<T extends DateOrCalendarDate>(\n  date: T,\n  amount: number,\n  options?: BusinessDaysOptions,\n): T {\n  return addBusinessDays(date, -amount, options);\n}\n\n/**\n * Returns the signed count of business days between two dates (left - right).\n * Positive if left is after right, negative if left is before right, 0 if identical.\n */\nexport function diffInBusinessDays(\n  left: DateOrCalendarDate,\n  right: DateOrCalendarDate,\n  options?: BusinessDaysOptions,\n): number {\n  const absLeft = getAbsoluteDay(left);\n  const absRight = getAbsoluteDay(right);\n\n  if (absLeft === absRight) {\n    return 0;\n  }\n\n  if (absLeft < absRight) {\n    return -diffInBusinessDays(right, left, options);\n  }\n\n  let count = 0;\n  let current = absRight;\n\n  const hasHolidays = Boolean(options?.holidays);\n  const hasCustomWeekends = Boolean(options?.weekendDays);\n\n  if (!hasHolidays && !hasCustomWeekends) {\n    // Fast-path O(1) acceleration: any consecutive 7 calendar days contains exactly 5 business days\n    const fullWeeks = Math.floor((absLeft - current) / 7);\n    if (fullWeeks > 0) {\n      count += fullWeeks * 5;\n      current += fullWeeks * 7;\n    }\n\n    while (current < absLeft) {\n      current++;\n      const dow = getIsoDayOfWeek(current);\n      if (dow !== 6 && dow !== 7) {\n        count++;\n      }\n    }\n  } else {\n    while (current < absLeft) {\n      current++;\n      if (!isNonWorkingDay(current, options)) {\n        count++;\n      }\n    }\n  }\n\n  return count;\n}\n"]}

package/dist/operations/business-hours.d.ts

@@ -0,0 +1,137 @@
+import type { CountryCode, HolidayCalendar } from "../holidays/types.js";
+import type { BusinessDaysOptions } from "./business-days.js";
+import type { Instant, LocalDate, LocalDateTime, LocalTime, TimeZoneId } from "../public-types.js";
+/**
+ * Defines an active working shift window within a day.
+ */
+export interface ShiftWindow {
+    /**
+     * Shift start time as "HH:mm", "HH:mm:ss", or a LocalTime object (e.g. "08:30").
+     */
+    readonly start: string | LocalTime;
+    /**
+     * Shift end time as "HH:mm", "HH:mm:ss", or a LocalTime object (e.g. "17:30").
+     */
+    readonly end: string | LocalTime;
+}
+/**
+ * Business schedule configuration for working hours, shifts, weekends, and holidays.
+ */
+export interface BusinessSchedule {
+    /**
+     * Working days of the week as ISO weekday numbers (1 = Monday, 7 = Sunday).
+     * Defaults to [1, 2, 3, 4, 5] (Monday to Friday), or country weekend defaults.
+     */
+    readonly workDays?: readonly number[];
+    /**
+     * Standard daily shifts. Defaults to a single shift 09:00 - 17:00.
+     */
+    readonly shifts?: readonly ShiftWindow[];
+    /**
+     * Day-of-week specific shift overrides (e.g. `{ 5: [{ start: "08:30", end: "12:00" }] }` for Friday half-day).
+     */
+    readonly dayShifts?: Partial<Record<number, readonly ShiftWindow[]>>;
+    /**
+     * Country code (e.g. "th", "jp", "us", "gb", "de") or custom HolidayCalendar for automatic holiday exclusion.
+     */
+    readonly country?: CountryCode | string | HolidayCalendar;
+    /**
+     * Custom holiday list, holiday predicate, or holiday calendar.
+     */
+    readonly holidays?: BusinessDaysOptions["holidays"];
+    /**
+     * Custom weekend days (e.g. [6, 7] for Sat-Sun, or [4, 5] for Iran).
+     */
+    readonly weekendDays?: readonly number[];
+    /**
+     * TimeZone identifier (e.g. "Asia/Bangkok", "America/New_York", "UTC").
+     * Required when evaluating Instant or Date across specific local working hours.
+     */
+    readonly timeZone?: TimeZoneId;
+}
+/**
+ * Normalized shift representation in milliseconds from midnight [0, 86_400_000].
+ */
+export interface NormalizedShift {
+    readonly startMs: number;
+    readonly endMs: number;
+    readonly durationMs: number;
+}
+/**
+ * Result representing an upcoming or active business shift window.
+ */
+export interface NextBusinessShiftResult<T> {
+    readonly start: T;
+    readonly end: T;
+}
+export type BusinessTimeInput = LocalDateTime | Instant | Date | LocalDate;
+/**
+ * Checks whether the given timestamp falls inside an active working shift on a working day.
+ * Returns false during non-working days, holidays, weekends, lunch breaks, or outside shift hours.
+ *
+ * @param input - LocalDateTime, Instant, Date, or LocalDate to check.
+ * @param schedule - Working schedule, shift windows, and holiday configuration.
+ */
+export declare function isBusinessHour(input: BusinessTimeInput, schedule?: BusinessSchedule): boolean;
+/**
+ * Adds business hours to a timestamp, skipping non-working hours, breaks, weekends, and statutory holidays.
+ * If the starting timestamp falls outside business hours (e.g. at night or during lunch),
+ * the SLA calculation automatically starts ticking from the start of the next active shift.
+ *
+ * @param input - The starting LocalDateTime, Instant, Date, or LocalDate.
+ * @param hours - Number of business hours to add (supports fractional hours like 2.5).
+ * @param schedule - Business schedule defining shift windows, weekends, holidays, and timezone.
+ * @returns The resulting deadline in the same type as the input.
+ */
+export declare function addBusinessHours(input: LocalDate, hours: number, schedule?: BusinessSchedule): LocalDateTime;
+export declare function addBusinessHours<T extends LocalDateTime | Instant | Date>(input: T, hours: number, schedule?: BusinessSchedule): T;
+export declare function addBusinessHours(input: BusinessTimeInput, hours: number, schedule?: BusinessSchedule): LocalDateTime | Instant | Date;
+/**
+ * Subtracts business hours from a timestamp backwards, skipping non-working hours, breaks, weekends, and holidays.
+ *
+ * @param input - The starting LocalDateTime, Instant, Date, or LocalDate.
+ * @param hours - Number of business hours to subtract (supports fractional hours).
+ * @param schedule - Business schedule configuration.
+ * @returns The resulting earlier timestamp in the same type as the input.
+ */
+export declare function subtractBusinessHours(input: LocalDate, hours: number, schedule?: BusinessSchedule): LocalDateTime;
+export declare function subtractBusinessHours<T extends LocalDateTime | Instant | Date>(input: T, hours: number, schedule?: BusinessSchedule): T;
+export declare function subtractBusinessHours(input: BusinessTimeInput, hours: number, schedule?: BusinessSchedule): LocalDateTime | Instant | Date;
+/**
+ * Computes the exact signed number of business hours elapsed between two timestamps (left - right).
+ * Non-working hours, lunch breaks, weekends, and statutory holidays are excluded.
+ *
+ * @param left - The later or earlier timestamp.
+ * @param right - The reference timestamp.
+ * @param schedule - Business schedule configuration.
+ * @returns Fractional business hours elapsed (positive if left > right, negative if left < right, 0 if equal).
+ */
+export declare function diffInBusinessHours(left: BusinessTimeInput, right: BusinessTimeInput, schedule?: BusinessSchedule): number;
+/**
+ * Options for resolving the next business shift window.
+ */
+export interface NextBusinessShiftOptions {
+    /**
+     * If true (default), returns the currently ongoing shift if the timestamp falls inside it.
+     * If false, strictly returns the next upcoming shift after the timestamp.
+     */
+    readonly includeCurrent?: boolean;
+}
+/**
+ * Resolves the next upcoming (or currently active) business shift window.
+ *
+ * @param input - The reference timestamp.
+ * @param schedule - Business schedule configuration.
+ * @param options - Options for including the currently active shift.
+ */
+export declare function nextBusinessShift(input: LocalDate, schedule?: BusinessSchedule, options?: NextBusinessShiftOptions): NextBusinessShiftResult<LocalDateTime>;
+export declare function nextBusinessShift<T extends LocalDateTime | Instant | Date>(input: T, schedule?: BusinessSchedule, options?: NextBusinessShiftOptions): NextBusinessShiftResult<T>;
+export declare function nextBusinessShift(input: BusinessTimeInput, schedule?: BusinessSchedule, options?: NextBusinessShiftOptions): NextBusinessShiftResult<LocalDateTime | Instant | Date>;
+/**
+ * Returns the earliest shift start time for a given date as a LocalDateTime.
+ */
+export declare function startOfBusinessDay(date: LocalDate | LocalDateTime | Date, schedule?: BusinessSchedule): LocalDateTime;
+/**
+ * Returns the latest shift end time for a given date as a LocalDateTime.
+ */
+export declare function endOfBusinessDay(date: LocalDate | LocalDateTime | Date, schedule?: BusinessSchedule): LocalDateTime;