chronos-ts 1.1.0 → 2.0.0

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

@@ -0,0 +1,205 @@
+/**
+ * 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;
+}