/**
 * Provides utility methods for working with [dates](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date).
 *
 * @internal
 */
import type TimeInterval from "../time/TimeInterval.js";
import type { TimeUnit } from "./units.js";
import type { TimeZone } from "../time/types.js";

/**
 * Returns the addition or subtraction of a quantity of temporal units. Computations are performed on local dates, not UTC.
 *
 * @param date - The input date.
 * @param offset - The number of temporal units to add or subtract.
 * @param unit - The input temporal unit.
 * @param timeZone - Processing time zone.
 * @returns A new date with the added or subtracted time.
 * @internal
 * @example
 * // Construct a date representing the 18th of September 2020.
 * const currentDate = new Date(2020, 8, 18);
 *
 * // Add six months to the date.
 * const futureDate = timeUtils.offsetDate(currentDate, 6, "months");
 *
 * // Format the date using the "en-US" locale.
 * const formatter = new Intl.DateTimeFormat("en-US", {
 *   year: "numeric",
 *   month: "numeric",
 *   day: "numeric"
 * });
 * const currentDateString = formatter.format(currentDate);
 * const futureDateString = formatter.format(futureDate);
 *
 * // Print computed date to console.
 * console.log(`Six months from ${currentDateString} is ${futureDateString}`);
 * // output: "Six months from 9/15/2020 is 3/15/2020"
 */
export function offsetDate(date: Date, offset: number, unit: TimeUnit, timeZone?: TimeZone): Date;

/**
 * Truncates or "rounds down" dates to the specified time unit. Computations are performed on local dates, not UTC.
 *
 * @param date - The input date.
 * @param interval - The time interval used to round the parsed date down.
 * @param timeZone - Processing time zone.
 * @returns A new date rounded to the specified time unit.
 * @internal
 * @example
 * // Construct a date representing the 18th of September 2020.
 * const date = new Date(2020, 8, 18);
 *
 * // Compute the first day of the current decade.
 * const truncatedDate = timeUtils.truncateDate(date, "decades");
 *
 * // Format the date using the "en-us" locale.
 * const formatter = new Intl.DateTimeFormat("en-us", {
 *   year: "numeric",
 *   month: "numeric",
 *   day: "numeric"
 * });
 * const dateString = formatter.format(truncatedDate);
 *
 * // Print computed date to console.
 * console.log(`The first day of the current decade is: ${dateString}`);
 * // output: "The first day of the current decade is: 1/1/2020"
 */
export function truncateDate(date: Date, interval: TimeInterval, timeZone?: TimeZone): Date;