temporal-workdays 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,8 +1,4 @@
-/**
- * The parts of a `Temporal.PlainDate` this library relies on. Described structurally so that
- * native Temporal, `temporal-polyfill`, `@js-temporal/polyfill` and their TypeScript types all work,
- * with no global `Temporal` type required.
- */
+/** The parts of a `Temporal.PlainDate` this library relies on. */
 interface PlainDateLike {
     readonly calendarId: string;
     readonly year: number;
@@ -49,17 +45,176 @@ type HolidayInput = string | PlainDateLike | PlainMonthDayLike;
 type HolidayPredicate = {
     bivarianceHack(date: PlainDateLike): boolean;
 }['bivarianceHack'];
+/** Which days are workdays. */
 interface WorkdayOptions {
     /** Non-working days of the week. Default `[6, 7]` (Saturday, Sunday). */
-    weekend?: readonly DayOfWeek[];
+    readonly weekend?: readonly DayOfWeek[] | undefined;
     /** Holiday dates, or a function that decides whether a date is a holiday. */
-    holidays?: Iterable<HolidayInput> | HolidayPredicate;
+    readonly holidays?: Iterable<HolidayInput> | HolidayPredicate | undefined;
     /**
      * Dates that count as workdays even if they fall on the weekend or a holiday
      * (for example, make-up working Saturdays). Single dates only.
      */
-    extraWorkdays?: Iterable<string | PlainDateLike>;
+    readonly extraWorkdays?: Iterable<string | PlainDateLike> | undefined;
+}
+/** The parts of a `Temporal.PlainTime` this library relies on. */
+interface PlainTimeLike {
+    readonly hour: number;
+    readonly minute: number;
+    readonly second: number;
+    readonly millisecond: number;
+    readonly microsecond: number;
+    readonly nanosecond: number;
+}
+/** Calendar and clock fields, as accepted by `Temporal.PlainDateTime#with`. */
+interface DateTimeFields {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+    microsecond: number;
+    nanosecond: number;
+}
+/** A duration of clock time. `Temporal.Duration` and plain objects such as `{ hours: 4 }` both fit. */
+interface DurationInput {
+    readonly years?: number | undefined;
+    readonly months?: number | undefined;
+    readonly weeks?: number | undefined;
+    readonly days?: number | undefined;
+    readonly hours?: number | undefined;
+    readonly minutes?: number | undefined;
+    readonly seconds?: number | undefined;
+    readonly milliseconds?: number | undefined;
+    readonly microseconds?: number | undefined;
+    readonly nanoseconds?: number | undefined;
+}
+/** The parts of a `Temporal.Duration` this library relies on. */
+interface DurationLike {
+    add(other: {
+        seconds: number;
+        nanoseconds: number;
+    }): DurationLike;
+    round(options: {
+        largestUnit: 'hours';
+    }): DurationLike;
+}
+/** The parts of a `Temporal.PlainDateTime` this library relies on. */
+interface PlainDateTimeLike extends PlainTimeLike {
+    readonly calendarId: string;
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    withCalendar(calendar: string): PlainDateTimeLike;
+    with(fields: DateTimeFields): PlainDateTimeLike;
+    /** Only ever called as `x.until(x)` to obtain a zero Duration; `never` accepts every implementation's signature. */
+    until(other: never): DurationLike;
+    toPlainDate(): PlainDateLike;
+    add(duration: {
+        days: number;
+    }): PlainDateTimeLike;
 }
+/** The parts of a `Temporal.ZonedDateTime` this library relies on. */
+interface ZonedDateTimeLike extends PlainTimeLike {
+    readonly calendarId: string;
+    readonly timeZoneId: string;
+    readonly epochNanoseconds: bigint;
+    readonly offsetNanoseconds: number;
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    withCalendar(calendar: string): ZonedDateTimeLike;
+    withTimeZone(timeZone: string): ZonedDateTimeLike;
+    with(fields: DateTimeFields, options: {
+        disambiguation: 'compatible';
+        offset: 'ignore';
+    }): ZonedDateTimeLike;
+    /** Only ever called as `x.until(x)` to obtain a zero Duration; `never` accepts every implementation's signature. */
+    until(other: never): DurationLike;
+    toPlainDate(): PlainDateLike;
+    add(duration: {
+        days?: number;
+        seconds?: number;
+        nanoseconds?: number;
+    }): ZonedDateTimeLike;
+    getTimeZoneTransition(direction: 'next' | 'previous'): ZonedDateTimeLike | null;
+}
+/** A date with a time of day: `Temporal.PlainDateTime` or `Temporal.ZonedDateTime`. */
+type DateTimeInput = PlainDateTimeLike | ZonedDateTimeLike;
+/** The `Temporal.Duration` type of the Temporal implementation that `T` comes from. */
+type DurationOf<T> = T extends {
+    until(...args: never[]): infer D;
+} ? D : never;
+/** A time of day: `'HH:MM'`, `'HH:MM:SS'`, `'HH:MM:SS.fffffffff'` or a `Temporal.PlainTime`. */
+type TimeInput = string | PlainTimeLike;
+/** A working period within one day, `[start, end)`. `'24:00'` is allowed as an end. */
+type TimeRange = readonly [start: TimeInput, end: TimeInput];
+/** The working periods of one day, e.g. `[['09:00', '12:00'], ['13:00', '17:00']]`. */
+type DayHours = readonly TimeRange[];
+/** A normalized working period as returned by this library, e.g. `['09:00', '17:30']`. */
+type TimeRangeText = readonly [start: string, end: string];
+/** Hours per ISO day of week (1 = Monday … 7 = Sunday); `default` applies to days not listed. */
+type WeeklyHours = Readonly<Partial<Record<DayOfWeek, DayHours>>> & {
+    readonly default?: DayHours;
+};
+/** The same hours on every workday, or hours per day of week. */
+type WorkingHours = DayHours | WeeklyHours;
+/**
+ * Decides the hours of a specific date. Receives an ISO `Temporal.PlainDate` and that date's
+ * regular hours (empty on weekends and holidays). Return `undefined` to keep the regular hours,
+ * `[]` to close, or other hours.
+ */
+type SpecialHoursFunction = {
+    bivarianceHack(date: PlainDateLike, regular: readonly TimeRangeText[]): DayHours | undefined;
+}['bivarianceHack'];
+/** Hours for specific dates, keyed by `'YYYY-MM-DD'` (`[]` = closed), or a function. */
+type SpecialHours = Readonly<Record<string, DayHours>> | SpecialHoursFunction;
+/** Workdays plus working hours, for the working-time functions. */
+interface WorkingTimeOptions extends WorkdayOptions {
+    /** Working hours on workdays. Weekends and holidays have no working hours. */
+    readonly hours: WorkingHours;
+    /** Overrides for specific dates (half days, extended hours, closures). Takes precedence over everything else. */
+    readonly specialHours?: SpecialHours | undefined;
+}
+
+/** Workday helpers bound to one configuration. See the standalone functions for details. */
+interface WorkCalendar {
+    /** A frozen snapshot of the options the calendar was created with. */
+    readonly options: Readonly<WorkdayOptions>;
+    isWorkday(date: DateInput): boolean;
+    isWeekend(date: DateInput): boolean;
+    isHoliday(date: DateInput): boolean;
+    addWorkdays<T extends DateInput>(date: T, amount: number): T;
+    subtractWorkdays<T extends DateInput>(date: T, amount: number): T;
+    nextWorkday<T extends DateInput>(date: T): T;
+    previousWorkday<T extends DateInput>(date: T): T;
+    rollForward<T extends DateInput>(date: T): T;
+    rollBackward<T extends DateInput>(date: T): T;
+    workdaysBetween(start: DateInput, end: DateInput): number;
+    eachWorkday<T extends DateInput>(start: T, end: DateInput): Generator<T, void>;
+}
+/** A calendar created with `hours`: workday helpers plus working-time helpers. */
+interface WorkTimeCalendar extends WorkCalendar {
+    readonly options: Readonly<WorkingTimeOptions>;
+    isWorkingTime(dateTime: DateTimeInput): boolean;
+    addWorkingTime<T extends DateTimeInput>(dateTime: T, duration: DurationInput): T;
+    subtractWorkingTime<T extends DateTimeInput>(dateTime: T, duration: DurationInput): T;
+    workingTimeBetween<T extends DateTimeInput>(start: T, end: NoInfer<T>): DurationOf<T>;
+    rollForwardToWorkingTime<T extends DateTimeInput>(dateTime: T): T;
+    rollBackwardToWorkingTime<T extends DateTimeInput>(dateTime: T): T;
+    getWorkingHours(date: DateInput): readonly TimeRangeText[];
+}
+/**
+ * Creates helpers bound to one configuration. The options are validated and read
+ * immediately (holidays and hours are parsed once), so later changes to the passed-in
+ * arrays don't affect the calendar. Prefer this over the standalone functions when the
+ * same configuration is used repeatedly. With `hours`, the working-time helpers are included.
+ */
+declare function createWorkCalendar(options: WorkingTimeOptions): WorkTimeCalendar;
+declare function createWorkCalendar(options?: WorkdayOptions): WorkCalendar;
+
 /** `true` if the date falls on a configured weekend day (ignores holidays and `extraWorkdays`). */
 declare function isWeekend(date: DateInput, options?: WorkdayOptions): boolean;
 /** `true` if the date is a configured holiday and not listed in `extraWorkdays`. */
@@ -93,27 +248,73 @@ declare function workdaysBetween(start: DateInput, end: DateInput, options?: Wor
  * Yields every workday from `start` to `end`, both inclusive, in ascending order.
  * Values have the type of `start` (time of day / zone preserved). Yields nothing if `end < start`.
  */
-declare function eachWorkday<T extends DateInput>(start: T, end: DateInput, options?: WorkdayOptions): Generator<T>;
-/** A set of workday helpers bound to one configuration. Holidays are parsed once. */
-interface WorkCalendar {
-    readonly options: Readonly<WorkdayOptions>;
-    isWorkday(date: DateInput): boolean;
-    isWeekend(date: DateInput): boolean;
-    isHoliday(date: DateInput): boolean;
-    addWorkdays<T extends DateInput>(date: T, amount: number): T;
-    subtractWorkdays<T extends DateInput>(date: T, amount: number): T;
-    nextWorkday<T extends DateInput>(date: T): T;
-    previousWorkday<T extends DateInput>(date: T): T;
-    rollForward<T extends DateInput>(date: T): T;
-    rollBackward<T extends DateInput>(date: T): T;
-    workdaysBetween(start: DateInput, end: DateInput): number;
-    eachWorkday<T extends DateInput>(start: T, end: DateInput): Generator<T>;
+declare function eachWorkday<T extends DateInput>(start: T, end: DateInput, options?: WorkdayOptions): Generator<T, void>;
+
+/** `true` if `dateTime` is inside working hours (periods are `[start, end)`: 17:00 is not working time in 09:00–17:00). */
+declare function isWorkingTime(dateTime: DateTimeInput, options: WorkingTimeOptions): boolean;
+/**
+ * Adds working time: only time inside working hours counts. Negative durations go back.
+ * Starting outside working hours, counting begins at the next working period. Landing
+ * exactly at the end of a period returns that end (`16:00 + 1h` → `17:00`, not the next morning).
+ *
+ * The result has the type of the input. For `ZonedDateTime`, elapsed time is exact across DST changes.
+ */
+declare function addWorkingTime<T extends DateTimeInput>(dateTime: T, duration: DurationInput, options: WorkingTimeOptions): T;
+/** Subtracts working time. Landing exactly at the start of a period returns that start. */
+declare function subtractWorkingTime<T extends DateTimeInput>(dateTime: T, duration: DurationInput, options: WorkingTimeOptions): T;
+/**
+ * Working time in `[start, end)` as a `Temporal.Duration` balanced up to hours (e.g. `PT27H30M`);
+ * negative when `end` is before `start`. Use `.total('hours')` for a number.
+ */
+declare function workingTimeBetween<T extends DateTimeInput>(start: T, end: NoInfer<T>, options: WorkingTimeOptions): DurationOf<T>;
+/** `dateTime` itself if it is working time, otherwise the start of the next working period. */
+declare function rollForwardToWorkingTime<T extends DateTimeInput>(dateTime: T, options: WorkingTimeOptions): T;
+/** `dateTime` itself if it is working time, otherwise the end of the previous working period. */
+declare function rollBackwardToWorkingTime<T extends DateTimeInput>(dateTime: T, options: WorkingTimeOptions): T;
+/** The working periods of a date after weekends, holidays and special hours, e.g. `[['09:00', '17:00']]`. */
+declare function getWorkingHours(date: DateInput, options: WorkingTimeOptions): readonly TimeRangeText[];
+
+/** The parts of a `date-holidays` holiday this adapter uses. */
+interface DateHolidaysEntry {
+    /** Local start, `'YYYY-MM-DD hh:mm:ss'`, optionally with a `' -0600'`-style shift (eve-start holidays). */
+    readonly date: string;
+    /** `'public'`, `'bank'`, `'school'`, `'optional'` or `'observance'`. */
+    readonly type: string;
+    readonly start: Date;
+    readonly end: Date;
+}
+/** The parts of a `date-holidays` `Holidays` instance this adapter uses. */
+interface DateHolidaysSource {
+    getHolidays(year: number): readonly DateHolidaysEntry[];
+}
+interface FromDateHolidaysOptions {
+    /** Holiday types that close the business. Default `['public']`. */
+    readonly types?: readonly string[] | undefined;
+}
+/** Spread into calendar options: `createWorkCalendar({ ...fromDateHolidays(hd), hours })`. */
+interface DateHolidaysOptions {
+    /** `true` for dates that a holiday covers completely. */
+    readonly holidays: HolidayPredicate;
+    /** Regular hours minus partial-day closures (e.g. closing at 14:00 on Christmas Eve). */
+    readonly specialHours: SpecialHoursFunction;
 }
 /**
- * Creates helpers bound to one configuration. The options are validated and copied
- * immediately, so later changes to the passed-in arrays don't affect the calendar.
+ * Turns a `date-holidays` instance into `holidays` and `specialHours` options:
+ *
+ * ```ts
+ * import Holidays from 'date-holidays';
+ * const cal = createWorkCalendar({
+ *   ...fromDateHolidays(new Holidays('DE', 'BY'), { types: ['public', 'bank'] }),
+ *   hours: [['09:00', '17:00']],
+ * });
+ * ```
+ *
+ * Days a holiday covers completely are holidays. Days it covers partly (Christmas Eve from
+ * 14:00) stay workdays with reduced hours. Holidays that `date-holidays` starts on the
+ * evening before (Hijri and Hebrew calendar holidays) are taken as it reports them.
+ * Results are cached per year.
  */
-declare function createWorkCalendar(options?: WorkdayOptions): WorkCalendar;
+declare function fromDateHolidays(source: DateHolidaysSource, options?: FromDateHolidaysOptions): DateHolidaysOptions;
 
-export { addWorkdays, createWorkCalendar, eachWorkday, isHoliday, isWeekend, isWorkday, nextWorkday, previousWorkday, rollBackward, rollForward, subtractWorkdays, workdaysBetween };
-export type { DateInput, DateTimeLike, DayOfWeek, HolidayInput, HolidayPredicate, PlainDateLike, PlainMonthDayLike, WorkCalendar, WorkdayOptions };
+export { addWorkdays, addWorkingTime, createWorkCalendar, eachWorkday, fromDateHolidays, getWorkingHours, isHoliday, isWeekend, isWorkday, isWorkingTime, nextWorkday, previousWorkday, rollBackward, rollBackwardToWorkingTime, rollForward, rollForwardToWorkingTime, subtractWorkdays, subtractWorkingTime, workdaysBetween, workingTimeBetween };
+export type { DateHolidaysEntry, DateHolidaysOptions, DateHolidaysSource, DateInput, DateTimeFields, DateTimeInput, DateTimeLike, DayHours, DayOfWeek, DurationInput, DurationLike, DurationOf, FromDateHolidaysOptions, HolidayInput, HolidayPredicate, PlainDateLike, PlainDateTimeLike, PlainMonthDayLike, PlainTimeLike, SpecialHours, SpecialHoursFunction, TimeInput, TimeRange, TimeRangeText, WeeklyHours, WorkCalendar, WorkTimeCalendar, WorkdayOptions, WorkingHours, WorkingTimeOptions, ZonedDateTimeLike };