@undercroft/timespan
Version:
When dealing with time durations or intervals in JavaScript, it's often useful to have a reliable way to represent and manipulate them. The `Timespan` class provides a convenient and powerful solution for working with timespans in JavaScript.
235 lines (223 loc) • 8.47 kB
text/typescript
/**
* Represents a time frame with various units of time.
*/
interface TimeFrame {
[key: string]: number | string | undefined;
/**
* The amount of time in milliseconds.
*/
milliseconds: number;
/**
* The amount of time in seconds.
*/
seconds: number;
/**
* The amount of time in minutes.
*/
minutes: number;
/**
* The amount of time in hours.
*/
hours: number;
/**
* The amount of time in days.
*/
days: number;
/**
* The amount of time in weeks.
*/
weeks: number;
/**
* The amount of time in months.
*/
months: number;
/**
* The amount of time in years.
*/
years: number;
}
type MillisecondUnit = 'milliseconds' | 'millisecond' | 'msec' | 'mss' | 'ms';
type SecondUnit = 'seconds' | 'second' | 'secs' | 'sec' | 's';
type MinuteUnit = 'm' | 'min' | 'mins' | 'minute' | 'minutes';
type HourUnit = 'h' | 'hr' | 'hrs' | 'hour' | 'hours';
type DayUnit = 'd' | 'dys' | 'dy' | 'day' | 'days';
type WeekUnit = 'w' | 'wk' | 'wks' | 'week' | 'weeks';
type MonthUnit = 'M' | 'mo' | 'mos' | 'month' | 'months';
type YearUnit = 'y' | 'yr' | 'yrs' | 'year' | 'years';
/**
* Enumeration of time units.
*/
type TimeUnit = MillisecondUnit | SecondUnit | MinuteUnit | HourUnit | DayUnit | WeekUnit | MonthUnit | YearUnit;
/**
* Represents a time span between two dates.
*/
declare class Timespan {
/**
* The start of the time span.
*/
private readonly startDate;
/**
* The end of the time span.
*/
private readonly endDate;
/**
* We precalculate the string value when the Timespan
* is created so you don't incur as much memory cost generating
* it when you want to use it.
*/
private readonly stringValue;
/**
* We go ahead and generate the TimeFrame when the Timespan
* is created. This way you can go ahead and get the timeframe
* at only point without incurring any extra memory cost.
*/
private readonly timeFrame;
/**
* Create a new Timespan instance.
* @param start - The start date of the timespan.
* @param end - The end date of the timespan.
*/
constructor(start: Date, end: Date);
/**
* Get the start date of the timespan.
* @returns The start date.
*/
get start(): Date;
/**
* Get the end date of the timespan.
* @returns The end date.
*/
get end(): Date;
/**
* Create a Timespan instance from a string input.
* @example - "1y 2M 3w 4d 5h 6m 7s 8ms"
* @example - "1yr 2mos 3wks 4dys 5hrs 6mins 7secs 8mss"
* @example - "2years 1month 3weeks 4days"
* @param input - The input string representing the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan instance representing the parsed timespan.
* @throws Error if the input is invalid or contains an invalid unit.
*/
static fromString: (input: string, startDate?: Date) => Timespan;
/**
* Creates a Timespan from the specified number of units.
* @param amount - The number of the specified units.
* @param unit - The unit of time.
* @param startDate - The date to start from.
* @returns A Timespan object representing the specified number of time units.
*/
static fromUnits: (amount: number, unit: TimeUnit, startDate?: Date) => Timespan;
/**
* Creates a Timespan object from a specified number of milliseconds.
* @param millis - The number of milliseconds for the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan object representing the specified number of milliseconds.
*/
static fromMilliseconds: (millis: number, startDate?: Date) => Timespan;
/**
* Creates a Timespan object from a specified number of seconds.
* @param seconds - The number of seconds for the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan object representing the specified number of seconds.
*/
static fromSeconds: (seconds: number, startDate?: Date) => Timespan;
/**
* Creates a Timespan object from a specified number of minutes.
* @param minutes - The number of minutes for the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan object representing the specified number of minutes.
*/
static fromMinutes: (minutes: number, startDate?: Date) => Timespan;
/**
* Creates a Timespan object from a specified number of hours.
* @param hours - The number of hours for the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan object representing the specified number of hours.
*/
static fromHours: (hours: number, startDate?: Date) => Timespan;
/**
* Creates a Timespan object from a specified number of days.
* @param days - The number of days for the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan object representing the specified number of days.
*/
static fromDays: (days: number, startDate?: Date) => Timespan;
/**
* Creates a Timespan object from a specified number of weeks.
* @param weeks - The number of weeks for the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan object representing the specified number of weeks.
*/
static fromWeeks: (weeks: number, startDate?: Date) => Timespan;
/**
* Creates a Timespan object from a specified number of months.
* @param months - The number of months for the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan object representing the specified number of months.
*/
static fromMonths: (months: number, startDate?: Date) => Timespan;
/**
* Creates a Timespan object from a specified number of years.
* @param years - The number of years for the timespan.
* @param startDate - Optional start date for the timespan. If not provided, the current date is used.
* @returns A Timespan object representing the specified number of years.
*/
static fromYears: (years: number, startDate?: Date) => Timespan;
/**
* Convert the timespan to a TimeFrame object.
* @returns The TimeFrame object representing the timespan.
*/
toTimeframe: () => TimeFrame;
/**
* Convert the timespan to a string representation.
* @returns The string representation of the timespan.
*/
toString: () => string;
/**
* Convert the timespan to the specified unit of measurement.
* @param unit - The unit of time
* @returns The duration in the specified time unit.
*/
toUnit: (unit: TimeUnit) => number;
/**
* Convert the timespan to the total duration in milliseconds.
* @returns The duration in milliseconds.
*/
toMilliseconds: () => number;
/**
* Convert the timespan to the total duration in seconds.
* @returns The duration in seconds.
*/
toSeconds: () => number;
/**
* Convert the timespan to the total duration in minutes.
* @returns The duration in minutes.
*/
toMinutes: () => number;
/**
* Convert the timespan to the total duration in hours.
* @returns The duration in hours.
*/
toHours: () => number;
/**
* Convert the timespan to the total duration in days.
* @returns The duration in days.
*/
toDays: () => number;
/**
* Convert the timespan to the total duration in weeks.
* @returns The duration in weeks.
*/
toWeeks: () => number;
/**
* Convert the timespan to the total duration in months.
* @returns The duration in months.
*/
toMonths: () => number;
/**
* Convert the timespan to the total duration in years.
* @returns The duration in years.
*/
toYears: () => number;
}
export { Timespan, Timespan as default };