chronos-ts/dist/core/period-collection.d.ts

A comprehensive TypeScript library for date and time manipulation, inspired by Carbon PHP. Features immutable API, intervals, periods, timezones, and i18n support.

/**
 * ChronosPeriodCollection - Manage collections of ChronosPeriod
 * Inspired by spatie/period PHP library
 * @see https://github.com/spatie/period
 */
import { ChronosPeriod } from './period';
import { Chronos } from './chronos';
import { DateInput } from '../types';
/**
 * ChronosPeriodCollection - A collection of periods with powerful operations
 *
 * Inspired by spatie/period, this class provides a rich API for working with
 * collections of time periods including overlap detection, gap analysis,
 * and set operations.
 *
 * @example
 * ```typescript
 * const collection = new ChronosPeriodCollection([
 *   ChronosPeriod.create('2024-01-01', '2024-01-15'),
 *   ChronosPeriod.create('2024-01-10', '2024-01-25'),
 *   ChronosPeriod.create('2024-02-01', '2024-02-15'),
 * ]);
 *
 * // Find overlapping periods
 * const overlapping = collection.overlapAll();
 *
 * // Get gaps between periods
 * const gaps = collection.gaps();
 *
 * // Get boundaries
 * const boundaries = collection.boundaries();
 * ```
 */
export declare class ChronosPeriodCollection implements Iterable<ChronosPeriod> {
    private _periods;
    constructor(periods?: ChronosPeriod[]);
    /**
     * Create a new collection from periods
     */
    static create(...periods: ChronosPeriod[]): ChronosPeriodCollection;
    /**
     * Create an empty collection
     */
    static empty(): ChronosPeriodCollection;
    /**
     * Create a collection from an array of date pairs
     */
    static fromDatePairs(pairs: Array<[DateInput, DateInput]>): ChronosPeriodCollection;
    /** Add a period to the collection */
    add(period: ChronosPeriod): this;
    /** Add multiple periods */
    addAll(periods: ChronosPeriod[]): this;
    /** Get a shallow copy of periods */
    toArray(): ChronosPeriod[];
    /** Get the number of periods in the collection */
    get length(): number;
    /** Check if collection is empty */
    isEmpty(): boolean;
    /** Check if collection is not empty */
    isNotEmpty(): boolean;
    /** Get a period at a specific index */
    get(index: number): ChronosPeriod | undefined;
    /** Get the first period */
    first(): ChronosPeriod | undefined;
    /** Get the last period */
    last(): ChronosPeriod | undefined;
    /** Clear collection */
    clear(): this;
    /** Iterator implementation */
    [Symbol.iterator](): Iterator<ChronosPeriod>;
    /** ForEach iteration */
    forEach(callback: (period: ChronosPeriod, index: number) => void): void;
    /** Map periods to a new array */
    map<T>(callback: (period: ChronosPeriod, index: number) => T): T[];
    /** Filter periods */
    filter(predicate: (period: ChronosPeriod, index: number) => boolean): ChronosPeriodCollection;
    /** Reduce periods to a single value */
    reduce<T>(callback: (acc: T, period: ChronosPeriod, index: number) => T, initial: T): T;
    /** Find a period matching a predicate */
    find(predicate: (period: ChronosPeriod, index: number) => boolean): ChronosPeriod | undefined;
    /** Check if any period matches a predicate */
    some(predicate: (period: ChronosPeriod, index: number) => boolean): boolean;
    /** Check if all periods match a predicate */
    every(predicate: (period: ChronosPeriod, index: number) => boolean): boolean;
    /**
     * Get the overall boundaries of the collection
     * Returns a period from the earliest start to the latest end
     */
    boundaries(): ChronosPeriod | null;
    /**
     * Get the earliest start date across all periods
     */
    start(): Chronos | null;
    /**
     * Get the latest end date across all periods
     */
    end(): Chronos | null;
    /** Normalize and merge overlapping/adjacent periods */
    normalize(): ChronosPeriod[];
    /** Check if any period overlaps with the provided period */
    overlaps(period: ChronosPeriod): boolean;
    /**
     * Check if any period in the collection overlaps with any other period
     * in the collection (internal overlaps)
     */
    overlapAny(): boolean;
    /**
     * Get all overlapping period segments across the collection
     * Returns periods where two or more periods in the collection overlap
     */
    overlapAll(): ChronosPeriodCollection;
    /** Return intersections between collection and a given period */
    intersect(period: ChronosPeriod): ChronosPeriodCollection;
    /**
     * Get intersection of all periods in the collection
     * Returns the period where ALL periods overlap (if any)
     */
    intersectAll(): ChronosPeriod | null;
    /** Return the union (merged) of all periods in the collection */
    union(): ChronosPeriodCollection;
    /**
     * Alias for normalize() - returns merged periods
     * @deprecated Use union() instead
     */
    unionAll(): ChronosPeriod[];
    /** Merge collection into a single union period if contiguous/overlapping */
    mergeToSingle(): ChronosPeriod | null;
    /** Return gaps between merged periods */
    gaps(): ChronosPeriodCollection;
    /**
     * Check if there are any gaps between periods
     */
    hasGaps(): boolean;
    /**
     * Subtract a period from all periods in the collection
     * Returns periods with the subtracted portion removed
     */
    subtract(period: ChronosPeriod): ChronosPeriodCollection;
    /**
     * Subtract multiple periods from the collection
     */
    subtractAll(periods: ChronosPeriod[]): ChronosPeriodCollection;
    /**
     * Check if any period touches (is adjacent to) the given period
     * Two periods touch if one ends exactly where the other begins
     */
    touchesWith(period: ChronosPeriod): boolean;
    /**
     * Check if two periods touch (are adjacent)
     */
    private _periodsTouch;
    /**
     * Get all periods that touch the given period
     */
    touchingPeriods(period: ChronosPeriod): ChronosPeriodCollection;
    /**
     * Check if a date is contained in any period of the collection
     */
    contains(date: DateInput): boolean;
    /**
     * Check if a period is fully contained in any period of the collection
     */
    containsPeriod(period: ChronosPeriod): boolean;
    /**
     * Check if two collections are equal (same periods)
     */
    equals(other: ChronosPeriodCollection): boolean;
    /**
     * Get periods sorted by start date
     */
    private _sortedByStart;
    /**
     * Sort periods by start date (ascending)
     */
    sortByStart(): ChronosPeriodCollection;
    /**
     * Sort periods by end date (ascending)
     */
    sortByEnd(): ChronosPeriodCollection;
    /**
     * Sort periods by duration (ascending)
     */
    sortByDuration(): ChronosPeriodCollection;
    /**
     * Reverse the order of periods
     */
    reverse(): ChronosPeriodCollection;
    /**
     * Convert to JSON
     */
    toJSON(): object[];
    /**
     * Convert to string
     */
    toString(): string;
    /**
     * Get total duration across all periods (in days)
     * Note: Overlapping portions may be counted multiple times
     */
    totalDays(): number;
    /**
     * Get total unique duration (merged periods, no double-counting)
     */
    uniqueDays(): number;
}