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.
430 lines (429 loc) • 11.3 kB
TypeScript
/**
* ChronosPeriod - Date range iteration
* @module ChronosPeriod
*/
import { Duration, AnyTimeUnit, DateInput, PeriodOptions } from '../types';
import { Chronos } from './chronos';
import { ChronosInterval } from './interval';
/**
* ChronosPeriod - Represents a date range with iteration capabilities
*
* Inspired by CarbonPeriod, this class provides powerful date range
* iteration with support for various interval types, filters, and
* recurrence patterns.
*
* @example
* ```typescript
* // Basic iteration
* const period = ChronosPeriod.create('2024-01-01', '2024-01-31');
* for (const date of period) {
* console.log(date.format('YYYY-MM-DD'));
* }
*
* // With custom interval
* const weekly = ChronosPeriod.create('2024-01-01', '2024-03-31')
* .setInterval(ChronosInterval.weeks(1));
*
* // With filters
* const weekdays = period.filter(date => date.dayOfWeek < 6);
*
* // Recurrence
* const recur = ChronosPeriod.recur('2024-01-01')
* .every(1, 'month')
* .times(12);
* ```
*/
export declare class ChronosPeriod implements Iterable<Chronos> {
private _start;
private _end;
private _interval;
private _recurrences;
private _options;
private _filters;
private _current;
private _locale;
/**
* Create a new ChronosPeriod
*/
constructor(start: DateInput, end?: DateInput, interval?: Duration | ChronosInterval, options?: Partial<PeriodOptions>);
/**
* Create a period between two dates
*/
static create(start: DateInput, end?: DateInput, interval?: Duration | ChronosInterval): ChronosPeriod;
/**
* Create a period from a start date with recurrences
*/
static recur(start: DateInput, interval?: Duration | ChronosInterval): ChronosPeriod;
/**
* Create a period for a specific number of days
*/
static days(start: DateInput, count: number): ChronosPeriod;
/**
* Create a period for a specific number of weeks
*/
static weeks(start: DateInput, count: number): ChronosPeriod;
/**
* Create a period for a specific number of months
*/
static months(start: DateInput, count: number): ChronosPeriod;
/**
* Create a period for a specific number of years
*/
static years(start: DateInput, count: number): ChronosPeriod;
/**
* Create a period for the current month
*/
static currentMonth(): ChronosPeriod;
/**
* Create a period for the current year
*/
static currentYear(): ChronosPeriod;
/**
* Create a period for the current week
*/
static currentWeek(): ChronosPeriod;
/**
* Create a period for the current quarter
*/
static currentQuarter(): ChronosPeriod;
/**
* Alias for currentWeek()
*/
static thisWeek(): ChronosPeriod;
/**
* Alias for currentMonth()
*/
static thisMonth(): ChronosPeriod;
/**
* Alias for currentYear()
*/
static thisYear(): ChronosPeriod;
/**
* Alias for currentQuarter()
*/
static thisQuarter(): ChronosPeriod;
/**
* Create a period for the previous week
*/
static lastWeek(): ChronosPeriod;
/**
* Create a period for the previous month
*/
static lastMonth(): ChronosPeriod;
/**
* Create a period for the previous year
*/
static lastYear(): ChronosPeriod;
/**
* Create a period for the previous quarter
*/
static lastQuarter(): ChronosPeriod;
/**
* Create a period for the next week
*/
static nextWeek(): ChronosPeriod;
/**
* Create a period for the next month
*/
static nextMonth(): ChronosPeriod;
/**
* Create a period for the next year
*/
static nextYear(): ChronosPeriod;
/**
* Create a period for the next quarter
*/
static nextQuarter(): ChronosPeriod;
/**
* Create a period between two dates (alias for create)
*/
static between(start: DateInput, end: DateInput, interval?: Duration | ChronosInterval): ChronosPeriod;
/**
* Create a period from an ISO 8601 repeating interval string
* @example
* ```typescript
* ChronosPeriod.fromISO('R5/2024-01-01/P1D') // 5 recurrences, daily from 2024-01-01
* ChronosPeriod.fromISO('2024-01-01/2024-01-31') // Date range
* ChronosPeriod.fromISO('2024-01-01/P1M') // From date with duration
* ```
*/
static fromISO(iso: string): ChronosPeriod;
/**
* Get the start date
*/
get start(): Chronos;
/**
* Get the end date
*/
get end(): Chronos | null;
/**
* Get the interval
*/
get interval(): ChronosInterval;
/**
* Get the number of recurrences
*/
get recurrences(): number | null;
/**
* Check if the period includes the start boundary
*/
get includesStart(): boolean;
/**
* Check if the period includes the end boundary
*/
get includesEnd(): boolean;
/**
* Check if the period has an end date
*/
get hasEnd(): boolean;
/**
* Check if the period is unbounded
*/
get isUnbounded(): boolean;
/**
* Set the start date
*/
setStart(start: DateInput): ChronosPeriod;
/**
* Set the end date
*/
setEnd(end: DateInput): ChronosPeriod;
/**
* Set the interval
*/
setInterval(interval: Duration | ChronosInterval): ChronosPeriod;
/**
* Set the number of recurrences
*/
times(count: number): ChronosPeriod;
/**
* Set interval by unit
*/
every(amount: number, unit: AnyTimeUnit): ChronosPeriod;
/**
* Exclude the start boundary
*/
excludeStart(): ChronosPeriod;
/**
* Exclude the end boundary
*/
excludeEnd(): ChronosPeriod;
/**
* Include the start boundary
*/
includeStart(): ChronosPeriod;
/**
* Include the end boundary
*/
includeEnd(): ChronosPeriod;
/**
* Add a filter function
*/
filter(fn: (date: Chronos, key: number) => boolean): ChronosPeriod;
/**
* Filter to only include weekdays
*/
weekdays(): ChronosPeriod;
/**
* Alias for weekdays()
*/
filterWeekdays(): ChronosPeriod;
/**
* Filter to only include weekends
*/
weekends(): ChronosPeriod;
/**
* Alias for weekends()
*/
filterWeekends(): ChronosPeriod;
/**
* Filter to only include specific days of week
*/
onlyDays(...days: number[]): ChronosPeriod;
/**
* Filter to exclude specific days of week
*/
exceptDays(...days: number[]): ChronosPeriod;
/**
* Filter to only include specific months
*/
onlyMonths(...months: number[]): ChronosPeriod;
/**
* Filter to exclude specific months
*/
exceptMonths(...months: number[]): ChronosPeriod;
/**
* Clear all filters
*/
clearFilters(): ChronosPeriod;
/**
* Get all dates in the period as an array
*/
toArray(): Chronos[];
/**
* Iterate over the period
*/
[](): Iterator<Chronos>;
/**
* Apply the interval to a date
*/
private _applyInterval;
/**
* Check if iteration should continue
*/
private _shouldContinue;
/**
* Check if a date passes all filters
*/
private _passesFilters;
/**
* Get count of dates in the period
*/
count(): number;
/**
* Get the first date in the period
*/
first(): Chronos | null;
/**
* Get the last date in the period
*/
last(): Chronos | null;
/**
* Get a date at a specific index
*/
nth(index: number): Chronos | null;
/**
* Check if a date is within the period
*/
contains(date: DateInput): boolean;
/**
* For each iteration
*/
forEach(callback: (date: Chronos, index: number) => void): void;
/**
* Map dates to another type
*/
map<T>(callback: (date: Chronos, index: number) => T): T[];
/**
* Reduce dates to a single value
*/
reduce<T>(callback: (acc: T, date: Chronos, index: number) => T, initial: T): T;
/**
* Check if two periods overlap
*/
overlaps(other: ChronosPeriod): boolean;
/**
* Get the intersection of two periods
*/
intersect(other: ChronosPeriod): ChronosPeriod | null;
/**
* Get the union of two periods
*/
union(other: ChronosPeriod): ChronosPeriod | null;
/**
* Get the difference between two periods
* Returns the parts of this period that don't overlap with the other period
*/
diff(other: ChronosPeriod): ChronosPeriod[];
/**
* Check if this period is adjacent to another
*/
private _adjacentTo;
/**
* Get the duration of the period
*/
duration(): ChronosInterval;
/**
* Get the number of days in the period
*/
days(): number;
/**
* Get the number of weeks in the period
*/
weeks(): number;
/**
* Get the number of months in the period
*/
monthCount(): number;
/**
* Get the number of years in the period
*/
yearCount(): number;
/**
* Split the period into chunks
*/
split(count: number): ChronosPeriod[];
/**
* Split by a specific interval
*/
splitBy(interval: Duration | ChronosInterval): ChronosPeriod[];
/**
* Split the period by a specified number of days
*/
splitByDays(days: number): ChronosPeriod[];
/**
* Split the period by a specified number of weeks
*/
splitByWeeks(weeks: number): ChronosPeriod[];
/**
* Split the period by a specified number of months
*/
splitByMonths(months: number): ChronosPeriod[];
/**
* Split the period by a specified number of years
*/
splitByYears(years: number): ChronosPeriod[];
/**
* Skip specific dates from the period iteration
* @param dates - Dates to exclude from iteration
*/
skip(dates: DateInput[]): ChronosPeriod;
/**
* Convert to ISO 8601 string
*/
toISO(): string;
/**
* Convert to string
*/
toString(): string;
/**
* Convert to human-readable string
*/
forHumans(): string;
/**
* Convert to JSON
*/
toJSON(): object;
/**
* Clone this period
*/
clone(): ChronosPeriod;
/**
* Clone for modification (respects immutable option)
*/
private _cloneForModification;
/**
* Set locale for this period
*/
locale(code: string): ChronosPeriod;
/**
* Create a period for a specific month
*/
static month(year: number, month: number): ChronosPeriod;
/**
* Create a period for a specific year
*/
static year(year: number): ChronosPeriod;
/**
* Create a period for a specific quarter
*/
static quarter(year: number, quarter: number): ChronosPeriod;
/**
* Create a period between two dates as weekdays only
*/
static weekdaysBetween(start: DateInput, end: DateInput): ChronosPeriod;
/**
* Create a period with business days only (weekdays, can add holidays filter)
*/
static businessDays(start: DateInput, end: DateInput, holidays?: DateInput[]): ChronosPeriod;
}