chronos-ts 1.1.0 → 2.0.0

package/dist/core/period.d.ts

@@ -0,0 +1,428 @@
+/**
+ * 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
+     */
+    [Symbol.iterator](): 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
+     */
+    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;
+}