chronos-ts
Version:
A comprehensive TypeScript library for date and time manipulation, inspired by Carbon PHP. Features immutable API, intervals, periods, timezones, and i18n support.
290 lines (289 loc) • 7.07 kB
TypeScript
/**
* ChronosInterval - Duration/Interval handling
* @module ChronosInterval
*/
import { Duration, AnyTimeUnit } from '../types';
/**
* ChronosInterval - Represents a duration/interval of time
*
* @example
* ```typescript
* // Create intervals
* const interval = ChronosInterval.create({ days: 5, hours: 3 });
* const hours = ChronosInterval.hours(24);
* const fromISO = ChronosInterval.fromISO('P1Y2M3D');
*
* // Arithmetic
* const doubled = interval.multiply(2);
* const combined = interval.add(hours);
*
* // Formatting
* console.log(interval.forHumans()); // "5 days 3 hours"
* console.log(interval.toISO()); // "P5DT3H"
* ```
*/
export declare class ChronosInterval {
private _years;
private _months;
private _weeks;
private _days;
private _hours;
private _minutes;
private _seconds;
private _milliseconds;
private _locale;
private _inverted;
private constructor();
/**
* Create an interval from a duration object
*/
static create(duration: Duration): ChronosInterval;
/**
* Create an interval from years
*/
static years(years: number): ChronosInterval;
/**
* Create an interval from months
*/
static months(months: number): ChronosInterval;
/**
* Create an interval from weeks
*/
static weeks(weeks: number): ChronosInterval;
/**
* Create an interval from days
*/
static days(days: number): ChronosInterval;
/**
* Create an interval from hours
*/
static hours(hours: number): ChronosInterval;
/**
* Create an interval from minutes
*/
static minutes(minutes: number): ChronosInterval;
/**
* Create an interval from seconds
*/
static seconds(seconds: number): ChronosInterval;
/**
* Create an interval from milliseconds
*/
static milliseconds(milliseconds: number): ChronosInterval;
/**
* Create a single unit interval
*/
static unit(amount: number, unit: AnyTimeUnit): ChronosInterval;
/**
* Create from ISO 8601 duration string (P1Y2M3DT4H5M6S)
*/
static fromISO(iso: string): ChronosInterval;
/**
* Create from a human-readable string
*
* @example
* ```typescript
* ChronosInterval.fromString('2 days 3 hours')
* ChronosInterval.fromString('1 year, 6 months')
* ```
*/
static fromString(input: string): ChronosInterval;
/**
* Create a zero-length interval
*/
static zero(): ChronosInterval;
/**
* Create an interval from the difference between two dates
*
* @example
* ```typescript
* const start = new Date('2024-01-01');
* const end = new Date('2024-03-15');
* const interval = ChronosInterval.between(start, end);
* ```
*/
static between(start: Date | {
toDate(): Date;
}, end: Date | {
toDate(): Date;
}): ChronosInterval;
get years(): number;
get months(): number;
get weeks(): number;
get days(): number;
get hours(): number;
get minutes(): number;
get seconds(): number;
get milliseconds(): number;
get inverted(): boolean;
/**
* Get total duration in a specific unit
*/
total(unit: AnyTimeUnit): number;
/**
* Get total duration in milliseconds
*/
totalMilliseconds(): number;
/**
* Get total duration in seconds
*/
totalSeconds(): number;
/**
* Get total duration in minutes
*/
totalMinutes(): number;
/**
* Get total duration in hours
*/
totalHours(): number;
/**
* Get total duration in days
*/
totalDays(): number;
/**
* Get total duration in weeks
*/
totalWeeks(): number;
/**
* Get total duration in months (approximate)
*/
totalMonths(): number;
/**
* Get total duration in years (approximate)
*/
totalYears(): number;
/**
* Add another interval to this one
*/
add(other: ChronosInterval | Duration): ChronosInterval;
/**
* Subtract another interval from this one
*/
subtract(other: ChronosInterval | Duration): ChronosInterval;
/**
* Multiply the interval by a factor
*/
multiply(factor: number): ChronosInterval;
/**
* Divide the interval by a factor
*/
divide(factor: number): ChronosInterval;
/**
* Negate the interval
*/
negate(): ChronosInterval;
/**
* Get absolute value of interval
*/
abs(): ChronosInterval;
/**
* Check if equal to another interval
*/
equals(other: ChronosInterval): boolean;
/**
* Check if greater than another interval
*/
greaterThan(other: ChronosInterval): boolean;
/**
* Check if less than another interval
*/
lessThan(other: ChronosInterval): boolean;
/**
* Check if greater than or equal to another interval
*/
greaterThanOrEqual(other: ChronosInterval): boolean;
/**
* Check if less than or equal to another interval
*/
lessThanOrEqual(other: ChronosInterval): boolean;
/**
* Check if the interval is zero
*/
isZero(): boolean;
/**
* Check if the interval is positive
*/
isPositive(): boolean;
/**
* Check if the interval is negative
*/
isNegative(): boolean;
/**
* Cascade units to proper values (normalize overflow)
*
* @example
* 90 seconds becomes 1 minute 30 seconds
*/
cascade(): ChronosInterval;
/**
* Cascade without including weeks
*/
cascadeWithoutWeeks(): ChronosInterval;
/**
* Format as ISO 8601 duration
*/
toISO(): string;
/**
* Format for human reading
*
* @example
* ```typescript
* interval.forHumans() // "2 days 3 hours"
* interval.forHumans({ short: true }) // "2d 3h"
* interval.forHumans({ parts: 2 }) // "2 days 3 hours" (max 2 parts)
* ```
*/
forHumans(options?: {
short?: boolean;
parts?: number;
join?: string;
conjunction?: string;
}): string;
/**
* Format using a format string
*
* Tokens:
* - %y: years
* - %m: months
* - %w: weeks
* - %d: days
* - %h: hours
* - %i: minutes
* - %s: seconds
* - %f: milliseconds
* - %R: +/- sign
* - %r: +/- or empty
*/
format(formatStr: string): string;
/**
* Convert to Duration object
*/
toDuration(): Duration;
/**
* Convert to array
*/
toArray(): number[];
/**
* Clone this interval
*/
clone(): ChronosInterval;
/**
* Set locale for this interval
*/
locale(code: string): ChronosInterval;
/**
* Get primitive value (total milliseconds)
*/
valueOf(): number;
/**
* Convert to string
*/
toString(): string;
/**
* Convert to JSON
*/
toJSON(): Duration & {
iso: string;
};
}
export default ChronosInterval;