workclock 0.0.0-stage → 0.1.1

package/pkg/node/workclock.d.ts

@@ -0,0 +1,209 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/** A day of the week. */
+export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+
+/**
+ * Working hours (`"workday"`) or time off within them (`"break"`) on some days
+ * of the week. Times are wall-clock times in the rule's time zone, written
+ * `HH:MM`, `HH:MM:SS` or `HH:MM:SS.fff` on a 24-hour clock, such as `"09:00"`
+ * or `"17:30:00"`.
+ */
+export interface HoursRule {
+    type: "workday" | "break";
+    /** Wall-clock start, such as `"09:00"`. */
+    start: string;
+    /** Wall-clock end; at or before `start` means the hours end the next day. */
+    end: string;
+    /**
+     * Days on which the hours start. Defaults to Monday to Friday, for breaks
+     * too, so a break on a weekend workday needs its own `days`.
+     */
+    days?: readonly Weekday[];
+    /** IANA time zone; defaults to the schedule's. */
+    timeZone?: string;
+}
+
+/** Dates that are not worked, each from 00:00 to the next 00:00. */
+export interface HolidaysRule {
+    type: "holidays";
+    /** Dates such as `"2026-12-25"`. */
+    dates: readonly string[];
+    /** IANA time zone; defaults to the schedule's. */
+    timeZone?: string;
+}
+
+/**
+ * One rule of a schedule. Working time is the time inside workdays and
+ * outside breaks and holidays.
+ */
+export type Rule = HoursRule | HolidaysRule;
+
+/** What `new Schedule` takes. */
+export interface ScheduleOptions {
+    /** IANA time zone for rules without their own; defaults to `"UTC"`. */
+    timeZone?: string;
+    /** The rules, in any order. */
+    rules: readonly Rule[];
+}
+
+/** A `Date`, or an ISO 8601 string with a UTC offset. */
+export type Instant = Date | string;
+
+/** A period: a maximal stretch of working time. */
+export interface Period {
+    start: Date;
+    end: Date;
+}
+
+/**
+ * Batch methods. Instants come as an array of `Instant`s, returning numbers or
+ * `Date`s, or as a `Float64Array` of milliseconds since the epoch, returning a
+ * `Float64Array`. Durations come as one number for every item, or one per item.
+ * A failing item throws, naming its index.
+ */
+export interface Schedule {
+    /**
+     * `between` for each pair.
+     * @throws {RangeError} If `a` and `b` differ in length.
+     */
+    betweenMany(a: Float64Array, b: Float64Array): Float64Array;
+    betweenMany(a: readonly Instant[], b: readonly Instant[]): number[];
+    betweenMany(a: Float64Array | readonly Instant[], b: Float64Array | readonly Instant[]): Float64Array | number[];
+    /** `add` for each instant. */
+    addMany(t: Float64Array, ms: number | readonly number[] | Float64Array): Float64Array;
+    addMany(t: readonly Instant[], ms: number | readonly number[] | Float64Array): Date[];
+    addMany(t: Float64Array | readonly Instant[], ms: number | readonly number[] | Float64Array): Float64Array | Date[];
+    /** `sub` for each instant. */
+    subMany(t: Float64Array, ms: number | readonly number[] | Float64Array): Float64Array;
+    subMany(t: readonly Instant[], ms: number | readonly number[] | Float64Array): Date[];
+    subMany(t: Float64Array | readonly Instant[], ms: number | readonly number[] | Float64Array): Float64Array | Date[];
+}
+
+
+
+/**
+ * Working time defined by rules, evaluated in IANA time zones.
+ *
+ * Instants are `Date`s or ISO 8601 strings with a UTC offset, and durations
+ * are numbers of milliseconds. Results are exact to the millisecond.
+ */
+export class Schedule {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Finds the instant a given amount of working time after another.
+     *
+     * @param t The instant to count from.
+     * @param ms Working time in milliseconds; a negative amount counts back.
+     * @returns The earliest instant with `ms` of working time after `t`, or
+     * `t` itself when `ms` is zero.
+     * @throws {NoWorkingTimeError} If no working time is found within 366
+     * days, plus seven days per holiday date.
+     * @throws {OutOfRangeError} If `t` or the result is outside the supported
+     * range.
+     * @throws {TypeError} If `t` is neither a `Date` nor a string, or `ms` is
+     * not a number.
+     * @throws {RangeError} If `t` is malformed, or `ms` is not a whole number
+     * within ±`Number.MAX_SAFE_INTEGER`.
+     * @example
+     * ```js
+     * const due = support.add("2026-12-24T16:30:00Z", 8 * 3_600_000);
+     * due.toISOString(); // "2026-12-30T09:30:00.000Z"
+     * ```
+     */
+    add(t: Instant, ms: number): Date;
+    /**
+     * Measures the working time between two instants.
+     *
+     * @param a The start.
+     * @param b The end.
+     * @returns The working time in milliseconds; negative when `b` is before
+     * `a`.
+     * @throws {OutOfRangeError} If an instant is outside the supported range.
+     * @throws {TypeError} If an instant is neither a `Date` nor a string.
+     * @throws {RangeError} If an instant is an invalid `Date` or a string
+     * without a UTC offset.
+     * @example
+     * ```js
+     * support.between("2026-01-05T09:00:00Z", "2026-01-06T09:00:00Z"); // 25200000, 7 hours
+     * ```
+     */
+    between(a: Instant, b: Instant): number;
+    /**
+     * Builds a schedule from its rules.
+     *
+     * @param options The default time zone and the rules.
+     * @throws {UnknownZoneError} If a time zone is not in the IANA database.
+     * @throws {NoWorkingTimeError} If the working hours minus the breaks are
+     * empty.
+     * @throws {TypeError} If `options` or a rule has the wrong shape; the
+     * message names the rule, such as `rules[1]`.
+     * @throws {RangeError} If a time, day or date cannot be read.
+     * @example
+     * ```js
+     * const support = new Schedule({
+     *   timeZone: "Europe/London",
+     *   rules: [
+     *     { type: "workday", start: "09:00", end: "17:00" },
+     *     { type: "break", start: "12:00", end: "13:00" },
+     *     { type: "holidays", dates: ["2026-12-25", "2026-12-28"] },
+     *   ],
+     * });
+     * ```
+     */
+    constructor(options: ScheduleOptions);
+    /**
+     * Finds the period of working time at or after an instant.
+     *
+     * @param t The instant to search from.
+     * @returns The period that contains `t`, starting at `t`, or else the
+     * first one after it.
+     * @throws {NoWorkingTimeError} If no working time is found within 366
+     * days, plus seven days per holiday date.
+     * @throws {OutOfRangeError} If `t` is outside the supported range, or the
+     * search reaches its end.
+     * @throws {TypeError} If `t` is neither a `Date` nor a string.
+     * @throws {RangeError} If `t` is malformed.
+     */
+    nextPeriod(t: Instant): Period;
+    /**
+     * Finds the period of working time at or before an instant.
+     *
+     * @param t The instant to search back from.
+     * @returns The period that contains `t`, ending at `t`, or else the last
+     * one before it.
+     * @throws {NoWorkingTimeError} If no working time is found within 366
+     * days, plus seven days per holiday date.
+     * @throws {OutOfRangeError} If `t` is outside the supported range, or the
+     * search reaches its start.
+     * @throws {TypeError} If `t` is neither a `Date` nor a string.
+     * @throws {RangeError} If `t` is malformed.
+     */
+    previousPeriod(t: Instant): Period;
+    /**
+     * Finds the instant a given amount of working time before another.
+     *
+     * @param t The instant to count back from.
+     * @param ms Working time in milliseconds; a negative amount counts
+     * forward.
+     * @returns The latest instant with `ms` of working time before `t`, or
+     * `t` itself when `ms` is zero.
+     * @throws {NoWorkingTimeError} If no working time is found within 366
+     * days, plus seven days per holiday date.
+     * @throws {OutOfRangeError} If `t` or the result is outside the supported
+     * range.
+     * @throws {TypeError} If `t` is neither a `Date` nor a string, or `ms` is
+     * not a number.
+     * @throws {RangeError} If `t` is malformed, or `ms` is not a whole number
+     * within ±`Number.MAX_SAFE_INTEGER`.
+     */
+    sub(t: Instant, ms: number): Date;
+}
+
+/**
+ * Returns the version of workclock this module was built from, such as
+ * `"0.1.0"`.
+ */
+export function version(): string;