@georgevie/period-sequence/dist/core/Period.d.ts

High-performance TypeScript library for time period manipulation with immutable design and enterprise-grade performance

/**
 * High-performance Period class for date period handling
 * Immutable value object representing time spans at day-level precision
 */
import { Bounds, Duration } from './types';
export declare class Period {
    private readonly _startTime;
    private readonly _endTime;
    private readonly _bounds;
    constructor(start: Date | number | string, end: Date | number | string, bounds?: Bounds);
    /**
     * Normalize any date input to midnight UTC for consistent day-level operations
     */
    private _normalizeDateToMidnightUTC;
    /**
     * Get start date (creates new Date object only when needed)
     */
    get start(): Date;
    /**
     * Get end date (creates new Date object only when needed)
     */
    get end(): Date;
    /**
     * Get bounds type
     */
    get bounds(): Bounds;
    /**
     * Get start timestamp (high performance accessor)
     */
    get startTime(): number;
    /**
     * Get end timestamp (high performance accessor)
     */
    get endTime(): number;
    /**
     * Get duration in days (optimized for date-only operations)
     * Much faster than getDuration().days for simple day calculations
     */
    get durationInDays(): number;
    /**
     * Calculate duration with day-level precision
     */
    getDuration(): Duration;
    /**
     * Check if this period overlaps with another period
     * Periods overlap if they share any common date, with boundary rules applied
     * @param other - The period to check for overlap
     * @returns True if periods overlap, false otherwise
     */
    overlaps(other: Period): boolean;
    /**
     * Check if this period contains another period
     * Optimized for performance with inlined bounds awareness
     */
    contains(other: Period): boolean;
    /**
     * Check if this period contains a specific date
     * High-performance timestamp comparison with inlined bounds checking
     */
    containsDate(date: Date | number): boolean;
    /**
     * Check if periods touch (adjacent with no gap) - date-only version
     * For date-only periods, this means consecutive days
     */
    touches(other: Period): boolean;
    /**
     * Check if periods abut (touch at exactly one point)
     * Optimized with early returns
     */
    abuts(other: Period): boolean;
    /**
     * Fast equality check using timestamps and bounds
     * Optimized with early returns
     */
    equals(other: Period): boolean;
    /**
     * Create new period with different start date
     * Optimized constructor call
     */
    startingOn(start: Date | number): Period;
    /**
     * Create new period with different end date
     * Optimized constructor call
     */
    endingOn(end: Date | number): Period;
    /**
     * Create new period with different bounds
     * Optimized constructor call
     */
    withBounds(bounds: Bounds): Period;
    /**
     * Internal method for object pooling - reset period with new values
     * @internal
     */
    _reset(start: Date | number | string, end: Date | number | string, bounds: Bounds): void;
    /**
     * Internal method for object pooling - clear cached values
     * @internal
     */
    _clearCache(): void;
    /**
     * Create new period with specific duration from start
     * Optimized with direct timestamp calculation
     */
    withDuration(duration: import('../duration/DurationInterval').DurationInterval): Period;
    /**
     * Move period by shifting both start and end by duration
     * Optimized with direct timestamp operations
     */
    move(duration: import('../duration/DurationInterval').DurationInterval): Period;
    /**
     * Move period backward by duration
     * Convenience method for negative movement
     */
    moveBackward(duration: import('../duration/DurationInterval').DurationInterval): Period;
    /**
     * Expand period by duration in both directions
     * Optimized with single calculation
     */
    expand(duration: import('../duration/DurationInterval').DurationInterval): Period;
    /**
     * Check if period is entirely before another period
     * High-performance comparison
     */
    isBefore(other: Period): boolean;
    /**
     * Check if period is entirely after another period
     * High-performance comparison
     */
    isAfter(other: Period): boolean;
    /**
     * Get the gap between this period and another (if any)
     * Returns null if periods overlap or touch
     */
    gap(other: Period): Period | null;
    /**
     * Format period with bounds notation for date-only display
     * All formats show dates only - no time components
     */
    format(dateFormat?: 'iso' | 'short' | 'long' | 'smart'): string;
    /**
     * Create string representation with date-only formatting
     * Always shows dates only in ISO format
     */
    toString(): string;
    /**
     * Format as date only (same as toString for date-only periods)
     * Example: [2024-01-15, 2024-01-16)
     */
    toDateString(): string;
    /**
     * Calculate intersection with another period
     * Returns the overlapping period, or null if no overlap
     */
    intersection(other: Period): Period | null;
    /**
     * Merge with another period if they touch or overlap (date-only optimized)
     * For date-only operations, consecutive days can be merged based on bounds
     * Returns combined period, or null if they can't be merged
     */
    union(other: Period): Period | null;
    /**
     * Check if two consecutive day periods can be merged based on their bounds
     */
    canMergeConsecutiveDays(other: Period): boolean;
    /**
     * Format for human readability with date-only display
     * Example: "Jan 15, 2024", "Jan 15 - 20, 2024" or "Jan 15, 2024 - Feb 2, 2024"
     */
    toDisplayString(): string;
}
//# sourceMappingURL=Period.d.ts.map