duration.ts

/*
 * Copyright 2026, Salesforce, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { Optional } from '@salesforce/ts-types';

/**
 * A simple utility class for converting durations between minutes, seconds, and milliseconds.
 */
export class Duration {
  /**
   * The number of milliseconds in one second.
   */
  public static readonly MILLIS_IN_SECONDS: number = 1000;

  /**
   * The number of seconds in one minute.
   */
  public static readonly SECONDS_IN_MINUTE: number = 60;

  /**
   * The number of minutes in one hour.
   */
  public static readonly MINUTES_IN_HOUR: number = 60;

  /**
   * The number of hours in one day.
   */
  public static readonly HOURS_IN_DAY: number = 24;

  /**
   * The number of days in one week.
   */
  public static readonly DAYS_IN_WEEK: number = 7;

  public readonly quantity: number;
  public readonly unit: Duration.Unit;

  public constructor(quantity: number, unit: Duration.Unit = Duration.Unit.MINUTES) {
    this.quantity = quantity;
    this.unit = unit;
  }

  /**
   * Returns the current number of minutes represented by this `Duration` instance, rounded to the nearest integer
   * value.
   */
  public get minutes(): number {
    switch (this.unit) {
      case Duration.Unit.MILLISECONDS:
        return Math.round(this.quantity / Duration.MILLIS_IN_SECONDS / Duration.SECONDS_IN_MINUTE);
      case Duration.Unit.SECONDS:
        return Math.round(this.quantity / Duration.SECONDS_IN_MINUTE);
      case Duration.Unit.MINUTES:
        return this.quantity;
      case Duration.Unit.HOURS:
        return this.quantity * Duration.MINUTES_IN_HOUR;
      case Duration.Unit.DAYS:
        return this.quantity * Duration.MINUTES_IN_HOUR * Duration.HOURS_IN_DAY;
      case Duration.Unit.WEEKS:
        return this.quantity * Duration.MINUTES_IN_HOUR * Duration.HOURS_IN_DAY * Duration.DAYS_IN_WEEK;
    }
  }

  /**
   * Returns the current number of hours represented by this `Duration` instance.
   */
  public get hours(): number {
    switch (this.unit) {
      case Duration.Unit.MILLISECONDS:
        return Math.round(
          this.quantity / Duration.MILLIS_IN_SECONDS / Duration.SECONDS_IN_MINUTE / Duration.MINUTES_IN_HOUR
        );
      case Duration.Unit.SECONDS:
        return Math.round(this.quantity / Duration.SECONDS_IN_MINUTE / Duration.MINUTES_IN_HOUR);
      case Duration.Unit.MINUTES:
        return Math.round(this.quantity / Duration.MINUTES_IN_HOUR);
      case Duration.Unit.HOURS:
        return this.quantity;
      case Duration.Unit.DAYS:
        return this.quantity * Duration.HOURS_IN_DAY;
      case Duration.Unit.WEEKS:
        return this.quantity * Duration.HOURS_IN_DAY * Duration.DAYS_IN_WEEK;
    }
  }

  /**
   * Returns the current number of milliseconds represented by this `Duration` instance.
   */
  public get milliseconds(): number {
    switch (this.unit) {
      case Duration.Unit.MILLISECONDS:
        return this.quantity;
      case Duration.Unit.SECONDS:
        return this.quantity * Duration.MILLIS_IN_SECONDS;
      case Duration.Unit.MINUTES:
        return this.quantity * Duration.MILLIS_IN_SECONDS * Duration.SECONDS_IN_MINUTE;
      case Duration.Unit.HOURS:
        return this.quantity * Duration.MILLIS_IN_SECONDS * Duration.SECONDS_IN_MINUTE * Duration.MINUTES_IN_HOUR;
      case Duration.Unit.DAYS:
        return (
          this.quantity *
          Duration.MILLIS_IN_SECONDS *
          Duration.SECONDS_IN_MINUTE *
          Duration.MINUTES_IN_HOUR *
          Duration.HOURS_IN_DAY
        );
      case Duration.Unit.WEEKS:
        return (
          this.quantity *
          Duration.MILLIS_IN_SECONDS *
          Duration.SECONDS_IN_MINUTE *
          Duration.MINUTES_IN_HOUR *
          Duration.HOURS_IN_DAY *
          Duration.DAYS_IN_WEEK
        );
    }
  }

  /**
   * Returns the current number of seconds represented by this `Duration` instance, rounded to the nearest integer
   * value.
   */
  public get seconds(): number {
    switch (this.unit) {
      case Duration.Unit.MILLISECONDS:
        return Math.round(this.quantity / Duration.MILLIS_IN_SECONDS);
      case Duration.Unit.SECONDS:
        return this.quantity;
      case Duration.Unit.MINUTES:
        return this.quantity * Duration.SECONDS_IN_MINUTE;
      case Duration.Unit.HOURS:
        return this.quantity * Duration.SECONDS_IN_MINUTE * Duration.MINUTES_IN_HOUR;
      case Duration.Unit.DAYS:
        return this.quantity * Duration.SECONDS_IN_MINUTE * Duration.MINUTES_IN_HOUR * Duration.HOURS_IN_DAY;
      case Duration.Unit.WEEKS:
        return (
          this.quantity *
          Duration.SECONDS_IN_MINUTE *
          Duration.MINUTES_IN_HOUR *
          Duration.HOURS_IN_DAY *
          Duration.DAYS_IN_WEEK
        );
    }
  }

  /**
   * Returns the current number of days represented by this `Duration` instance.
   */
  public get days(): number {
    switch (this.unit) {
      case Duration.Unit.MILLISECONDS:
        return Math.round(
          this.quantity /
            Duration.MILLIS_IN_SECONDS /
            Duration.SECONDS_IN_MINUTE /
            Duration.MINUTES_IN_HOUR /
            Duration.HOURS_IN_DAY
        );
      case Duration.Unit.SECONDS:
        return Math.round(
          this.quantity / Duration.SECONDS_IN_MINUTE / Duration.MINUTES_IN_HOUR / Duration.HOURS_IN_DAY
        );
      case Duration.Unit.MINUTES:
        return Math.round(this.quantity / Duration.MINUTES_IN_HOUR / Duration.HOURS_IN_DAY);
      case Duration.Unit.HOURS:
        return Math.round(this.quantity / Duration.HOURS_IN_DAY);
      case Duration.Unit.DAYS:
        return this.quantity;
      case Duration.Unit.WEEKS:
        return this.quantity * Duration.DAYS_IN_WEEK;
    }
  }

  /**
   * Returns the current number of weeks represented by this `Duration` instance.
   */
  public get weeks(): number {
    switch (this.unit) {
      case Duration.Unit.MILLISECONDS:
        return Math.round(
          this.quantity /
            Duration.MILLIS_IN_SECONDS /
            Duration.SECONDS_IN_MINUTE /
            Duration.MINUTES_IN_HOUR /
            Duration.HOURS_IN_DAY /
            Duration.DAYS_IN_WEEK
        );
      case Duration.Unit.SECONDS:
        return Math.round(
          this.quantity /
            Duration.SECONDS_IN_MINUTE /
            Duration.MINUTES_IN_HOUR /
            Duration.HOURS_IN_DAY /
            Duration.DAYS_IN_WEEK
        );
      case Duration.Unit.MINUTES:
        return Math.round(this.quantity / Duration.MINUTES_IN_HOUR / Duration.HOURS_IN_DAY / Duration.DAYS_IN_WEEK);
      case Duration.Unit.HOURS:
        return Math.round(this.quantity / Duration.HOURS_IN_DAY / Duration.DAYS_IN_WEEK);
      case Duration.Unit.DAYS:
        return Math.round(this.quantity / Duration.DAYS_IN_WEEK);
      case Duration.Unit.WEEKS:
        return this.quantity;
    }
  }

  /**
   * Returns a new `Duration` instance created from the specified number of milliseconds.
   *
   * @param quantity The number of milliseconds.
   */
  public static milliseconds(quantity: number): Duration {
    return new Duration(quantity, Duration.Unit.MILLISECONDS);
  }

  /**
   * Returns a new `Duration` instance created from the specified number of seconds.
   *
   * @param quantity The number of seconds.
   */
  public static seconds(quantity: number): Duration {
    return new Duration(quantity, Duration.Unit.SECONDS);
  }

  /**
   * Returns a new `Duration` instance created from the specified number of minutes.
   *
   * @param quantity The number of minutes.
   */
  public static minutes(quantity: number): Duration {
    return new Duration(quantity, Duration.Unit.MINUTES);
  }

  /**
   * Returns a new `Duration` instance created from the specified number of hours.
   *
   * @param quantity The number of hours.
   */
  public static hours(quantity: number): Duration {
    return new Duration(quantity, Duration.Unit.HOURS);
  }

  /**
   * Returns a new `Duration` instance created from the specified number of days.
   *
   * @param quantity The number of days.
   */
  public static days(quantity: number): Duration {
    return new Duration(quantity, Duration.Unit.DAYS);
  }

  /**
   * Returns a new `Duration` instance created from the specified number of weeks.
   *
   * @param quantity The number of weeks.
   */
  public static weeks(quantity: number): Duration {
    return new Duration(quantity, Duration.Unit.WEEKS);
  }

  /**
   * The string representation of this `Duration`. e.g. "645 seconds"
   */
  public toString(): string {
    return pluralize(this.quantity, this.unit);
  }
}

export namespace Duration {
  /**
   * Units of duration.
   */
  // eslint-disable-next-line no-shadow
  export enum Unit {
    MINUTES,
    MILLISECONDS,
    SECONDS,
    HOURS,
    DAYS,
    WEEKS,
  }
}

/**
 * An abstraction for any interruptable operation.
 */
export type Interruptable = {
  interrupt: () => void;
};

/**
 * A promise of result type `T` that can be interrupted prematurely, resulting in an early resolution.
 */
export type InterruptablePromise<T> = Promise<T> & Interruptable;

/**
 * Sleeps for a given `Duration`. This is essentially a promisified version of `setTimeout`. May be interrupted
 * by calling `interrupt()` on the returned `InterruptablePromise`.
 *
 * @param duration The duration to wait.
 *
 * ```
 * // sleep 5 seconds
 * await sleep(Duration.seconds(5));
 *
 * // sleep 10 minutes unless interrupted by an event
 * const promise = sleep(Duration.minutes(10));
 * events.on('someEvent', promise.interrupt);
 * await promise;
 * ```
 */
export function sleep(duration: Duration): InterruptablePromise<void>;
/**
 * Sleeps for a given duration, with units defaulting to milliseconds. This is essentially a promisified version
 * of `setTimeout`. May be interrupted by calling `interrupt()` on the returned `InterruptablePromise`.
 *
 * @param quantity The quantity of duration to wait.
 * @param unit The `Duration.Unit` in which quantity is specified, defaulting to milliseconds.
 *
 * ```
 * // sleep 5 seconds
 * await sleep(5000);
 *
 * // sleep 10 minutes unless interrupted by an event
 * const promise = sleep(10, Duration.Unit.MINUTES);
 * events.on('someEvent', promise.interrupt);
 * await promise;
 * ```
 */
export function sleep(quantity: number, unit?: Duration.Unit): InterruptablePromise<void>;
// underlying function
export function sleep(
  durationOrQuantity: Duration | number,
  unit: Duration.Unit = Duration.Unit.MILLISECONDS
): InterruptablePromise<void> {
  const duration = durationOrQuantity instanceof Duration ? durationOrQuantity : new Duration(durationOrQuantity, unit);
  let handle: Optional<NodeJS.Timeout>;
  let doResolve: () => void;
  const wake = (): undefined => {
    if (!handle) return;
    clearTimeout(handle);
    handle = undefined;
    doResolve();
  };
  const promise = new Promise<void>((resolve) => {
    doResolve = resolve;
    handle = setTimeout(wake, duration.milliseconds);
  });
  return Object.assign(promise, { interrupt: wake });
}

const pluralize = (num: number, unit: Duration.Unit): string => {
  const name = Duration.Unit[unit].toLowerCase();
  return `${num} ${num === 1 ? name.slice(0, name.length - 1) : name}`;
};