chronos-ts 2.0.2 → 2.0.4

package/dist/index.d.ts

@@ -1,50 +1,2311 @@
 /**
- * Chronos v2 - A comprehensive TypeScript library for date and time manipulation
- *
- * @description
- * Chronos is a powerful, modern TypeScript library for handling dates, times,
- * intervals, periods, and timezones. Inspired by Carbon PHP, it provides an
- * intuitive and fluent API for all your time-related needs.
+ * Core type definitions for Chronos
+ * @module types
+ */
+/**
+ * All supported time units in the library
+ */
+type TimeUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'decade' | 'century' | 'millennium';
+/**
+ * Plural forms of time units
+ */
+type TimeUnitPlural = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'quarters' | 'years' | 'decades' | 'centuries' | 'millennia';
+/**
+ * Short forms of time units
+ */
+type TimeUnitShort = 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'M' | 'Q' | 'y';
+/**
+ * Combined time unit type accepting any form
+ */
+type AnyTimeUnit = TimeUnit | TimeUnitPlural | TimeUnitShort;
+/**
+ * Days of the week (0 = Sunday, 6 = Saturday)
+ */
+declare enum DayOfWeek {
+    Sunday = 0,
+    Monday = 1,
+    Tuesday = 2,
+    Wednesday = 3,
+    Thursday = 4,
+    Friday = 5,
+    Saturday = 6
+}
+/**
+ * Months of the year (1 = January, 12 = December)
+ */
+declare enum Month {
+    January = 1,
+    February = 2,
+    March = 3,
+    April = 4,
+    May = 5,
+    June = 6,
+    July = 7,
+    August = 8,
+    September = 9,
+    October = 10,
+    November = 11,
+    December = 12
+}
+/**
+ * Valid input types that can be parsed into a Chronos instance
+ */
+type DateInput = string | number | Date | ChronosLike | null | undefined;
+/**
+ * Interface for Chronos-like objects
+ */
+interface ChronosLike {
+    toDate(): Date;
+    valueOf(): number;
+}
+/**
+ * Object representing individual date/time components
+ */
+interface DateTimeComponents {
+    year?: number;
+    month?: number;
+    day?: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+}
+/**
+ * Object for setting date/time parts
+ */
+interface DateTimeSetter {
+    year?: number;
+    month?: number;
+    date?: number;
+    day?: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+}
+/**
+ * Duration object for intervals
+ */
+interface Duration {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+/**
+ * ISO 8601 duration string pattern
+ */
+type ISODuration = string;
+/**
+ * Valid timezone input types
+ */
+type TimezoneInput = string | number | TimezoneInfo;
+/**
+ * Timezone offset information
+ */
+interface TimezoneOffset {
+    /**
+     * Offset in minutes from UTC
+     */
+    minutes: number;
+    /**
+     * Offset in hours from UTC
+     */
+    hours: number;
+    /**
+     * Offset as string (e.g., "+05:30", "-08:00")
+     */
+    string: string;
+}
+/**
+ * DST transition information
+ */
+interface DSTransition {
+    /**
+     * Date of the DST transition
+     */
+    date: Date;
+    /**
+     * Offset before transition (in minutes)
+     */
+    fromOffset: number;
+    /**
+     * Offset after transition (in minutes)
+     */
+    toOffset: number;
+    /**
+     * Whether this is the start of DST (spring forward)
+     */
+    isDSTStart: boolean;
+}
+/**
+ * Timezone information object
+ */
+interface TimezoneInfo {
+    /**
+     * IANA timezone identifier
+     */
+    identifier: string;
+    /**
+     * Display name of the timezone
+     */
+    name: string;
+    /**
+     * Timezone abbreviation (e.g., EST, PST)
+     */
+    abbreviation: string;
+    /**
+     * Current UTC offset
+     */
+    offset: TimezoneOffset;
+    /**
+     * Whether DST is currently in effect
+     */
+    isDST: boolean;
+    /**
+     * Whether this timezone observes DST
+     */
+    observesDST: boolean;
+}
+/**
+ * Format token types for custom formatting
+ */
+interface FormatTokens {
+    [key: string]: ((date: Date) => string) | string;
+}
+/**
+ * Predefined format presets
+ */
+type FormatPreset = 'date' | 'time' | 'datetime' | 'iso' | 'rfc2822' | 'rfc3339' | 'atom' | 'cookie' | 'rss' | 'w3c';
+/**
+ * Comparison operators
+ */
+type CompareOperator = '<' | '<=' | '=' | '>=' | '>' | '!=';
+/**
+ * Comparison granularity options
+ */
+type CompareGranularity = TimeUnit | 'default';
+/**
+ * Period options for iteration
+ */
+interface PeriodOptions {
+    /**
+     * Exclude the start date from iteration
+     */
+    excludeStart?: boolean;
+    /**
+     * Exclude the end date from iteration
+     */
+    excludeEnd?: boolean;
+    /**
+     * Maximum number of iterations
+     */
+    recurrences?: number;
+    /**
+     * Whether period modifications return new instances
+     */
+    immutable?: boolean;
+}
+/**
+ * Period boundary options
+ */
+declare enum PeriodBoundary {
+    Open = "open",
+    Closed = "closed",
+    OpenStart = "openStart",
+    OpenEnd = "openEnd"
+}
+/**
+ * Locale configuration
+ */
+interface LocaleConfig {
+    code: string;
+    months: string[];
+    monthsShort: string[];
+    weekdays: string[];
+    weekdaysShort: string[];
+    weekdaysMin: string[];
+    ordinal: (n: number) => string;
+    formats: {
+        LT: string;
+        LTS: string;
+        L: string;
+        LL: string;
+        LLL: string;
+        LLLL: string;
+        l?: string;
+        ll?: string;
+        lll?: string;
+        llll?: string;
+    };
+    relativeTime: {
+        future: string;
+        past: string;
+        s: string;
+        ss: string;
+        m: string;
+        mm: string;
+        h: string;
+        hh: string;
+        d: string;
+        dd: string;
+        w?: string;
+        ww?: string;
+        M: string;
+        MM: string;
+        y: string;
+        yy: string;
+    };
+    meridiem?: (hour: number, minute: number, isLowercase: boolean) => string;
+    week?: {
+        dow: number;
+        doy: number;
+    };
+}
+/**
+ * Global configuration options
+ */
+interface ChronosConfig {
+    /**
+     * Default timezone
+     */
+    timezone?: string;
+    /**
+     * Default locale
+     */
+    locale?: string;
+    /**
+     * First day of week (0 = Sunday, 1 = Monday, etc.)
+     */
+    weekStartsOn?: DayOfWeek;
+    /**
+     * First week of year contains this date
+     */
+    firstWeekContainsDate?: 1 | 4;
+    /**
+     * Strict parsing mode
+     */
+    strict?: boolean;
+}
+/**
+ * Makes all properties optional recursively
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Extract numeric keys from an object type
+ */
+type NumericKeys<T> = {
+    [K in keyof T]: T[K] extends number ? K : never;
+}[keyof T];
+/**
+ * Type guard result
+ */
+type TypeGuard<T> = (value: unknown) => value is T;
+/**
+ * Chainable method return type
+ */
+type Chainable<T> = T & {
+    clone(): T;
+};
+/**
+ * Options for human-readable difference output
+ */
+interface HumanDiffOptions {
+    /**
+     * Use short form (1d vs 1 day)
+     */
+    short?: boolean;
+    /**
+     * Number of units to include
+     */
+    parts?: number;
+    /**
+     * Use absolute value
+     */
+    absolute?: boolean;
+    /**
+     * Separator between parts
+     */
+    separator?: string;
+    /**
+     * Conjunction for last part
+     */
+    conjunction?: string;
+    /**
+     * Include numeric suffix (st, nd, rd, th)
+     */
+    ordinal?: boolean;
+}
+/**
+ * Diff result with all units
+ */
+interface DiffResult {
+    years: number;
+    months: number;
+    weeks: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+    totalMilliseconds: number;
+}
+/**
+ * Serializable representation of a Chronos instance
+ */
+interface ChronosSerializable {
+    timestamp: number;
+    timezone: string;
+    offset: number;
+}
+/**
+ * JSON representation
+ */
+interface ChronosJSON {
+    iso: string;
+    timestamp: number;
+    timezone: string;
+}
+/**
+ * Represents a time range/span
+ */
+interface TimeRange {
+    start: Date;
+    end: Date;
+}
+/**
+ * Business hours configuration
+ */
+interface BusinessHours {
+    open: {
+        hour: number;
+        minute: number;
+    };
+    close: {
+        hour: number;
+        minute: number;
+    };
+    days: DayOfWeek[];
+    holidays?: Date[];
+}
+/**
+ * Calendar week representation
+ */
+interface CalendarWeek {
+    weekNumber: number;
+    year: number;
+    days: Date[];
+}
+/**
+ * Calendar month representation
+ */
+interface CalendarMonth {
+    year: number;
+    month: number;
+    weeks: CalendarWeek[];
+}
+declare const MILLISECONDS_PER_SECOND = 1000;
+declare const SECONDS_PER_MINUTE = 60;
+declare const MINUTES_PER_HOUR = 60;
+declare const HOURS_PER_DAY = 24;
+declare const DAYS_PER_WEEK = 7;
+declare const MONTHS_PER_YEAR = 12;
+declare const DAYS_PER_YEAR = 365;
+declare const DAYS_PER_LEAP_YEAR = 366;
+declare const MILLISECONDS_PER_MINUTE: number;
+declare const MILLISECONDS_PER_HOUR: number;
+declare const MILLISECONDS_PER_DAY: number;
+declare const MILLISECONDS_PER_WEEK: number;
+declare const AVERAGE_DAYS_PER_MONTH = 30.436875;
+declare const AVERAGE_DAYS_PER_YEAR = 365.2425;
+declare const MILLISECONDS_PER_MONTH: number;
+declare const MILLISECONDS_PER_YEAR: number;
+
+/**
+ * Chronos - The ultimate TypeScript date/time library
+ * @module Chronos
+ */
+
+/**
+ * Chronos - A comprehensive date/time manipulation library
  *
  * @example
  * ```typescript
- * import { Chronos, ChronosInterval, ChronosPeriod, ChronosTimezone } from 'chronos-ts';
- *
- * // Create dates
+ * // Create instances
  * const now = Chronos.now();
+ * const date = Chronos.parse('2024-01-15');
  * const birthday = Chronos.create(1990, 5, 15);
  *
  * // Manipulate
- * const nextWeek = now.addWeeks(1);
- * const endOfMonth = now.endOf('month');
+ * const future = now.add(3, 'months').startOf('day');
+ * const past = now.subtract(1, 'year').endOf('month');
  *
  * // Compare
- * if (now.isAfter(birthday)) {
- *   console.log('Birthday has passed');
- * }
+ * const isAfter = date.isAfter(birthday);
+ * const diff = date.diff(birthday, 'years');
  *
  * // Format
- * console.log(now.format('MMMM D, YYYY')); // "January 15, 2024"
+ * const formatted = now.format('YYYY-MM-DD HH:mm:ss');
+ * const relative = birthday.fromNow(); // "34 years ago"
+ * ```
+ */
+declare class Chronos implements ChronosLike {
+    private readonly _date;
+    private _locale;
+    private _timezone?;
+    /**
+     * Create a new Chronos instance
+     *
+     * @param input - Date input (string, number, Date, or Chronos)
+     * @param timezone - Optional timezone
+     */
+    private constructor();
+    /**
+     * Parse a date string
+     */
+    private parseString;
+    /**
+     * Helper to create a date from components in a specific timezone
+     */
+    private static dateFromComponents;
+    /**
+     * Create a Chronos instance from various inputs
+     *
+     * @example
+     * ```typescript
+     * Chronos.parse('2024-01-15')
+     * Chronos.parse(1705276800000)
+     * Chronos.parse(new Date())
+     * ```
+     */
+    static parse(input?: DateInput, timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance for the current moment
+     *
+     * @example
+     * ```typescript
+     * const now = Chronos.now();
+     * ```
+     */
+    static now(timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance for today at midnight
+     */
+    static today(timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance for tomorrow at midnight
+     */
+    static tomorrow(timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance for yesterday at midnight
+     */
+    static yesterday(timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance from individual components
+     * Month is 1-12 (like Carbon PHP)
+     *
+     * @example
+     * ```typescript
+     * Chronos.create(2024, 1, 15, 10, 30, 0) // Jan 15, 2024 10:30:00
+     * ```
+     */
+    static create(year: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, millisecond?: number, timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance from a Unix timestamp (seconds)
+     */
+    static fromUnix(timestamp: number, timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance from a Unix timestamp (milliseconds)
+     */
+    static fromMillis(timestamp: number, timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance from components object
+     * Month in components is 1-12 (like Carbon PHP)
+     */
+    static fromObject(components: DateTimeComponents, timezone?: string): Chronos;
+    /**
+     * Create a Chronos instance from a format string
+     *
+     * @example
+     * ```typescript
+     * Chronos.fromFormat('15-01-2024', 'DD-MM-YYYY')
+     * ```
+     */
+    static fromFormat(input: string, format: string, timezone?: string): Chronos;
+    /**
+     * Create the minimum possible date
+     */
+    static min(): Chronos;
+    /**
+     * Create the maximum possible date
+     */
+    static max(): Chronos;
+    /**
+     * Get the earliest of multiple dates
+     */
+    static earliest(...dates: (DateInput | Chronos)[]): Chronos;
+    /**
+     * Get the latest of multiple dates
+     */
+    static latest(...dates: (DateInput | Chronos)[]): Chronos;
+    /** Get the year */
+    get year(): number;
+    /** Get the month (1-12) */
+    get month(): number;
+    /** Get the day of month (1-31) */
+    get date(): number;
+    /** Alias for date */
+    get day(): number;
+    /** Get the day of week (0-6, Sunday = 0) */
+    get dayOfWeek(): DayOfWeek;
+    /** Get the hour (0-23) */
+    get hour(): number;
+    /** Get the minute (0-59) */
+    get minute(): number;
+    /** Get the second (0-59) */
+    get second(): number;
+    /** Get the millisecond (0-999) */
+    get millisecond(): number;
+    /** Get Unix timestamp (seconds) */
+    get unix(): number;
+    /** Get Unix timestamp (milliseconds) */
+    get timestamp(): number;
+    /** Get the quarter (1-4) */
+    get quarter(): number;
+    /** Get the day of year (1-366) */
+    get dayOfYear(): number;
+    /** Get the ISO week number (1-53) */
+    get week(): number;
+    /** Get the ISO week year */
+    get weekYear(): number;
+    /** Get the number of days in the current month */
+    get daysInMonth(): number;
+    /** Get the number of days in the current year */
+    get daysInYear(): number;
+    /** Get the number of weeks in the current year */
+    get weeksInYear(): number;
+    /** Check if the year is a leap year */
+    get isLeapYear(): boolean;
+    /** Get the timezone offset in minutes */
+    get offset(): number;
+    /** Get the timezone offset as string (+05:30) */
+    get offsetString(): string;
+    /**
+     * Set specific date/time components
+     * Returns a new Chronos instance
+     */
+    /**
+     * Set multiple date/time values at once
+     * Month is 1-12 (like Carbon PHP)
+     */
+    set(values: DateTimeSetter): Chronos;
+    /** Set the year */
+    setYear(year: number): Chronos;
+    /** Set the month (1-12) */
+    setMonth(month: number): Chronos;
+    /** Set the day of month (1-31) */
+    setDate(date: number): Chronos;
+    /** Set the hour (0-23) */
+    setHour(hour: number): Chronos;
+    /** Set the minute (0-59) */
+    setMinute(minute: number): Chronos;
+    /** Set the second (0-59) */
+    setSecond(second: number): Chronos;
+    /** Set the millisecond (0-999) */
+    setMillisecond(millisecond: number): Chronos;
+    /**
+     * Add time to the date
+     *
+     * @example
+     * ```typescript
+     * chronos.add(5, 'days')
+     * chronos.add(2, 'months')
+     * chronos.add({ years: 1, months: 2 })
+     * ```
+     */
+    add(amount: number | Duration, unit?: AnyTimeUnit): Chronos;
+    /**
+     * Add an amount of a single unit while respecting the instance timezone.
+     * Calendar units (day/week/month/quarter/year/…) preserve the wall-clock time
+     * in the zone (DST-safe); absolute units (hour/minute/second/millisecond) add a
+     * fixed offset to the instant. Day clamping mirrors the local-time path.
+     */
+    private addInZone;
+    /**
+     * Subtract time from the date
+     */
+    subtract(amount: number | Duration, unit?: AnyTimeUnit): Chronos;
+    /**
+     * Get the start of a time unit
+     *
+     * @example
+     * ```typescript
+     * chronos.startOf('day')   // 00:00:00.000
+     * chronos.startOf('month') // First day of month
+     * chronos.startOf('year')  // January 1st
+     * ```
+     */
+    startOf(unit: AnyTimeUnit): Chronos;
+    /**
+     * Get the end of a time unit
+     *
+     * @example
+     * ```typescript
+     * chronos.endOf('day')   // 23:59:59.999
+     * chronos.endOf('month') // Last day of month
+     * chronos.endOf('year')  // December 31st
+     * ```
+     */
+    endOf(unit: AnyTimeUnit): Chronos;
+    /**
+     * Compute the start/end boundary of a unit in the instance timezone.
+     * The plain `startOf`/`endOf` helpers operate on local wall-clock fields of the
+     * underlying Date, which is wrong when an explicit timezone is attached. Here we
+     * read the wall-clock components in the target zone, snap them to the boundary,
+     * and rebuild the instant (dateFromComponents handles DST).
+     */
+    private boundaryInZone;
+    addMilliseconds(amount: number): Chronos;
+    addSeconds(amount: number): Chronos;
+    addMinutes(amount: number): Chronos;
+    addHours(amount: number): Chronos;
+    addDays(amount: number): Chronos;
+    addWeeks(amount: number): Chronos;
+    addMonths(amount: number): Chronos;
+    addQuarters(amount: number): Chronos;
+    addYears(amount: number): Chronos;
+    subtractMilliseconds(amount: number): Chronos;
+    subtractSeconds(amount: number): Chronos;
+    subtractMinutes(amount: number): Chronos;
+    subtractHours(amount: number): Chronos;
+    subtractDays(amount: number): Chronos;
+    subtractWeeks(amount: number): Chronos;
+    subtractMonths(amount: number): Chronos;
+    subtractQuarters(amount: number): Chronos;
+    subtractYears(amount: number): Chronos;
+    /**
+     * Check if this date is before another
+     */
+    isBefore(other: DateInput, unit?: AnyTimeUnit): boolean;
+    /**
+     * Check if this date is after another
+     */
+    isAfter(other: DateInput, unit?: AnyTimeUnit): boolean;
+    /**
+     * Check if this date is the same as another
+     */
+    isSame(other: DateInput, unit?: AnyTimeUnit): boolean;
+    /**
+     * Check if this date is same or before another
+     */
+    isSameOrBefore(other: DateInput, unit?: AnyTimeUnit): boolean;
+    /**
+     * Check if this date is same or after another
+     */
+    isSameOrAfter(other: DateInput, unit?: AnyTimeUnit): boolean;
+    /**
+     * Check if this date is between two others
+     */
+    isBetween(start: DateInput, end: DateInput, unit?: AnyTimeUnit, inclusivity?: '()' | '[]' | '[)' | '(]'): boolean;
+    /** Check if this date is today */
+    isToday(): boolean;
+    /** Check if this date is tomorrow */
+    isTomorrow(): boolean;
+    /** Check if this date is yesterday */
+    isYesterday(): boolean;
+    /** Check if this date is in the past */
+    isPast(): boolean;
+    /** Check if this date is in the future */
+    isFuture(): boolean;
+    /** Check if this is a weekend (Saturday or Sunday) */
+    isWeekend(): boolean;
+    /** Check if this is a weekday (Monday-Friday) */
+    isWeekday(): boolean;
+    isSunday(): boolean;
+    isMonday(): boolean;
+    isTuesday(): boolean;
+    isWednesday(): boolean;
+    isThursday(): boolean;
+    isFriday(): boolean;
+    isSaturday(): boolean;
+    /**
+     * Get the difference between two dates in a specific unit
+     */
+    diff(other: DateInput, unit?: AnyTimeUnit, precise?: boolean): number;
+    /**
+     * Get a detailed diff breakdown
+     */
+    diffDetailed(other: DateInput): DiffResult;
+    /**
+     * Get a human-readable relative time string
+     *
+     * @example
+     * ```typescript
+     * date.fromNow()         // "2 days ago"
+     * date.from(other)       // "in 3 months"
+     * date.fromNow({ short: true }) // "2d ago"
+     * ```
+     */
+    fromNow(options?: HumanDiffOptions): string;
+    /**
+     * Get relative time from another date
+     */
+    from(other: DateInput, options?: HumanDiffOptions): string;
+    /**
+     * Get relative time to another date
+     */
+    to(other: DateInput, options?: HumanDiffOptions): string;
+    /**
+     * Get relative time to now
+     */
+    toNow(options?: HumanDiffOptions): string;
+    /**
+     * Format the date using a format string
+     *
+     * Supported tokens:
+     * - YYYY: 4-digit year
+     * - YY: 2-digit year
+     * - MMMM: Full month name
+     * - MMM: Short month name
+     * - MM: 2-digit month
+     * - M: 1-2 digit month
+     * - DD: 2-digit day
+     * - D: 1-2 digit day
+     * - dddd: Full weekday name
+     * - ddd: Short weekday name
+     * - dd: Min weekday name
+     * - d: Day of week number
+     * - HH: 2-digit hour (24h)
+     * - H: 1-2 digit hour (24h)
+     * - hh: 2-digit hour (12h)
+     * - h: 1-2 digit hour (12h)
+     * - mm: 2-digit minute
+     * - m: 1-2 digit minute
+     * - ss: 2-digit second
+     * - s: 1-2 digit second
+     * - SSS: 3-digit millisecond
+     * - A: AM/PM
+     * - a: am/pm
+     * - Z: Timezone offset (+05:00)
+     * - ZZ: Timezone offset (+0500)
+     */
+    format(formatStr?: string): string;
+    /** Format as ISO 8601 */
+    toISOString(): string;
+    /** Format as ISO date (YYYY-MM-DD) */
+    toDateString(): string;
+    /** Format as time (HH:mm:ss) */
+    toTimeString(): string;
+    /** Format as datetime (YYYY-MM-DD HH:mm:ss) */
+    toDateTimeString(): string;
+    /** Format as RFC 2822 */
+    toRFC2822(): string;
+    /** Format as RFC 3339 */
+    toRFC3339(): string;
+    /** Format as ATOM */
+    toAtomString(): string;
+    /** Format as Cookie */
+    toCookieString(): string;
+    /** Format as RSS */
+    toRSSString(): string;
+    /** Format as W3C */
+    toW3CString(): string;
+    /**
+     * Convert to a specific timezone
+     */
+    toTimezone(timezone: string): Chronos;
+    /** Convert to native Date object */
+    toDate(): Date;
+    /** Convert to array [year, month, day, hour, minute, second, millisecond] */
+    toArray(): number[];
+    /** Convert to object */
+    toObject(): DateTimeComponents;
+    /** Convert to JSON-serializable object */
+    toJSON(): ChronosJSON;
+    /** Get primitive value (timestamp) */
+    valueOf(): number;
+    /** Convert to string */
+    toString(): string;
+    /**
+     * Create a clone of this instance
+     */
+    clone(): Chronos;
+    /**
+     * Set the locale for this instance
+     */
+    locale(code: string): Chronos;
+    /**
+     * Get the current locale code
+     */
+    getLocale(): string;
+    /**
+     * Get the next occurrence of a specific day
+     */
+    next(day: DayOfWeek): Chronos;
+    /**
+     * Get the previous occurrence of a specific day
+     */
+    previous(day: DayOfWeek): Chronos;
+    /**
+     * Get the closest date (either this or other)
+     */
+    closest(date1: DateInput, date2: DateInput): Chronos;
+    /**
+     * Get the farthest date (either this or other)
+     */
+    farthest(date1: DateInput, date2: DateInput): Chronos;
+    /**
+     * Set global configuration
+     */
+    static configure(config: Partial<ChronosConfig>): void;
+    /**
+     * Get current global configuration
+     */
+    static getConfig(): ChronosConfig;
+    /**
+     * Set test time (for testing purposes)
+     */
+    static setTestNow(date?: DateInput): void;
+    /**
+     * Check if test mode is active
+     */
+    static hasTestNow(): boolean;
+    /**
+     * Get the test time
+     */
+    static getTestNow(): Chronos | null;
+    /**
+     * Check if the date is valid
+     */
+    isValid(): boolean;
+    /**
+     * Check if this date is the same day as another (regardless of time)
+     */
+    isSameDay(other: DateInput): boolean;
+    /**
+     * Check if this date is in the same month as another
+     */
+    isSameMonth(other: DateInput): boolean;
+    /**
+     * Check if this date is in the same year as another
+     */
+    isSameYear(other: DateInput): boolean;
+    /**
+     * Get calendar output for the current month
+     */
+    calendar(referenceDate?: DateInput): string;
+}
+
+/**
+ * ChronosInterval - Duration/Interval handling
+ * @module ChronosInterval
+ */
+
+/**
+ * ChronosInterval - Represents a duration/interval of time
+ *
+ * @example
+ * ```typescript
+ * // Create intervals
+ * const interval = ChronosInterval.create({ days: 5, hours: 3 });
+ * const hours = ChronosInterval.hours(24);
+ * const fromISO = ChronosInterval.fromISO('P1Y2M3D');
+ *
+ * // Arithmetic
+ * const doubled = interval.multiply(2);
+ * const combined = interval.add(hours);
+ *
+ * // Formatting
+ * console.log(interval.forHumans()); // "5 days 3 hours"
+ * console.log(interval.toISO());     // "P5DT3H"
+ * ```
+ */
+declare class ChronosInterval {
+    private _years;
+    private _months;
+    private _weeks;
+    private _days;
+    private _hours;
+    private _minutes;
+    private _seconds;
+    private _milliseconds;
+    private _locale;
+    private _inverted;
+    private constructor();
+    /**
+     * Create an interval from a duration object
+     */
+    static create(duration: Duration): ChronosInterval;
+    /**
+     * Create an interval from years
+     */
+    static years(years: number): ChronosInterval;
+    /**
+     * Create an interval from months
+     */
+    static months(months: number): ChronosInterval;
+    /**
+     * Create an interval from weeks
+     */
+    static weeks(weeks: number): ChronosInterval;
+    /**
+     * Create an interval from days
+     */
+    static days(days: number): ChronosInterval;
+    /**
+     * Create an interval from hours
+     */
+    static hours(hours: number): ChronosInterval;
+    /**
+     * Create an interval from minutes
+     */
+    static minutes(minutes: number): ChronosInterval;
+    /**
+     * Create an interval from seconds
+     */
+    static seconds(seconds: number): ChronosInterval;
+    /**
+     * Create an interval from milliseconds
+     */
+    static milliseconds(milliseconds: number): ChronosInterval;
+    /**
+     * Create a single unit interval
+     */
+    static unit(amount: number, unit: AnyTimeUnit): ChronosInterval;
+    /**
+     * Create from ISO 8601 duration string (P1Y2M3DT4H5M6S)
+     */
+    static fromISO(iso: string): ChronosInterval;
+    /**
+     * Create from a human-readable string
+     *
+     * @example
+     * ```typescript
+     * ChronosInterval.fromString('2 days 3 hours')
+     * ChronosInterval.fromString('1 year, 6 months')
+     * ```
+     */
+    static fromString(input: string): ChronosInterval;
+    /**
+     * Create a zero-length interval
+     */
+    static zero(): ChronosInterval;
+    /**
+     * Create an interval from the difference between two dates
+     *
+     * @example
+     * ```typescript
+     * const start = new Date('2024-01-01');
+     * const end = new Date('2024-03-15');
+     * const interval = ChronosInterval.between(start, end);
+     * ```
+     */
+    static between(start: Date | {
+        toDate(): Date;
+    }, end: Date | {
+        toDate(): Date;
+    }): ChronosInterval;
+    get years(): number;
+    get months(): number;
+    get weeks(): number;
+    get days(): number;
+    get hours(): number;
+    get minutes(): number;
+    get seconds(): number;
+    get milliseconds(): number;
+    get inverted(): boolean;
+    /**
+     * Get total duration in a specific unit
+     */
+    total(unit: AnyTimeUnit): number;
+    /**
+     * Get total duration in milliseconds
+     */
+    totalMilliseconds(): number;
+    /**
+     * Get total duration in seconds
+     */
+    totalSeconds(): number;
+    /**
+     * Get total duration in minutes
+     */
+    totalMinutes(): number;
+    /**
+     * Get total duration in hours
+     */
+    totalHours(): number;
+    /**
+     * Get total duration in days
+     */
+    totalDays(): number;
+    /**
+     * Get total duration in weeks
+     */
+    totalWeeks(): number;
+    /**
+     * Get total duration in months (approximate)
+     */
+    totalMonths(): number;
+    /**
+     * Get total duration in years (approximate)
+     */
+    totalYears(): number;
+    /**
+     * Add another interval to this one
+     */
+    add(other: ChronosInterval | Duration): ChronosInterval;
+    /**
+     * Subtract another interval from this one
+     */
+    subtract(other: ChronosInterval | Duration): ChronosInterval;
+    /**
+     * Multiply the interval by a factor
+     */
+    multiply(factor: number): ChronosInterval;
+    /**
+     * Divide the interval by a factor
+     */
+    divide(factor: number): ChronosInterval;
+    /**
+     * Negate the interval
+     */
+    negate(): ChronosInterval;
+    /**
+     * Get absolute value of interval
+     */
+    abs(): ChronosInterval;
+    /**
+     * Check if equal to another interval
+     */
+    equals(other: ChronosInterval): boolean;
+    /**
+     * Check if greater than another interval
+     */
+    greaterThan(other: ChronosInterval): boolean;
+    /**
+     * Check if less than another interval
+     */
+    lessThan(other: ChronosInterval): boolean;
+    /**
+     * Check if greater than or equal to another interval
+     */
+    greaterThanOrEqual(other: ChronosInterval): boolean;
+    /**
+     * Check if less than or equal to another interval
+     */
+    lessThanOrEqual(other: ChronosInterval): boolean;
+    /**
+     * Check if the interval is zero
+     */
+    isZero(): boolean;
+    /**
+     * Check if the interval is positive
+     */
+    isPositive(): boolean;
+    /**
+     * Check if the interval is negative
+     */
+    isNegative(): boolean;
+    /**
+     * Cascade units to proper values (normalize overflow)
+     *
+     * @example
+     * 90 seconds becomes 1 minute 30 seconds
+     */
+    cascade(): ChronosInterval;
+    /**
+     * Cascade without including weeks
+     */
+    cascadeWithoutWeeks(): ChronosInterval;
+    /**
+     * Format as ISO 8601 duration
+     */
+    toISO(): string;
+    /**
+     * Format for human reading
+     *
+     * @example
+     * ```typescript
+     * interval.forHumans()           // "2 days 3 hours"
+     * interval.forHumans({ short: true }) // "2d 3h"
+     * interval.forHumans({ parts: 2 })    // "2 days 3 hours" (max 2 parts)
+     * ```
+     */
+    forHumans(options?: {
+        short?: boolean;
+        parts?: number;
+        join?: string;
+        conjunction?: string;
+    }): string;
+    /**
+     * Format using a format string
+     *
+     * Tokens:
+     * - %y: years
+     * - %m: months
+     * - %w: weeks
+     * - %d: days
+     * - %h: hours
+     * - %i: minutes
+     * - %s: seconds
+     * - %f: milliseconds
+     * - %R: +/- sign
+     * - %r: +/- or empty
+     */
+    format(formatStr: string): string;
+    /**
+     * Convert to Duration object
+     */
+    toDuration(): Duration;
+    /**
+     * Convert to array
+     */
+    toArray(): number[];
+    /**
+     * Clone this interval
+     */
+    clone(): ChronosInterval;
+    /**
+     * Set locale for this interval
+     */
+    locale(code: string): ChronosInterval;
+    /**
+     * Get primitive value (total milliseconds)
+     */
+    valueOf(): number;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): Duration & {
+        iso: string;
+    };
+}
+
+/**
+ * ChronosPeriod - Date range iteration
+ * @module ChronosPeriod
+ */
+
+/**
+ * ChronosPeriod - Represents a date range with iteration capabilities
  *
- * // Intervals
- * const duration = ChronosInterval.hours(5).addMinutes(30);
- * console.log(duration.forHumans()); // "5 hours 30 minutes"
+ * Inspired by CarbonPeriod, this class provides powerful date range
+ * iteration with support for various interval types, filters, and
+ * recurrence patterns.
  *
- * // Periods
- * const week = ChronosPeriod.currentWeek();
- * for (const day of week) {
- *   console.log(day.format('dddd'));
+ * @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'));
  * }
  *
- * // Timezones
- * const tz = ChronosTimezone.create('America/New_York');
- * console.log(tz.getOffsetString()); // "-05:00"
+ * // 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);
+ * ```
+ */
+declare class ChronosPeriod implements Iterable<Chronos> {
+    private _start;
+    private _end;
+    private _interval;
+    private _recurrences;
+    private _options;
+    private _filters;
+    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;
+    /**
+     * Resolve the effective end of the period.
+     * Returns null for a truly unbounded period (no end and no recurrence limit),
+     * which avoids calling last() — that would iterate until the safety limit and throw.
+     */
+    private _resolvedEnd;
+    /**
+     * 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;
+}
+
+/**
+ * ChronosPeriodCollection - Manage collections of ChronosPeriod
+ * Inspired by spatie/period PHP library
+ * @see https://github.com/spatie/period
+ */
+
+/**
+ * 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();
  * ```
+ */
+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;
+}
+
+/**
+ * ChronosTimezone - Timezone handling and conversions
+ * @module ChronosTimezone
+ */
+
+/**
+ * Common timezone identifiers
+ */
+declare const TIMEZONES: {
+    readonly UTC: "UTC";
+    readonly GMT: "GMT";
+    readonly 'America/New_York': "America/New_York";
+    readonly 'America/Chicago': "America/Chicago";
+    readonly 'America/Denver': "America/Denver";
+    readonly 'America/Los_Angeles': "America/Los_Angeles";
+    readonly 'America/Phoenix': "America/Phoenix";
+    readonly 'America/Anchorage': "America/Anchorage";
+    readonly 'America/Toronto': "America/Toronto";
+    readonly 'America/Vancouver': "America/Vancouver";
+    readonly 'America/Mexico_City': "America/Mexico_City";
+    readonly 'America/Sao_Paulo': "America/Sao_Paulo";
+    readonly 'America/Buenos_Aires': "America/Buenos_Aires";
+    readonly 'America/Lima': "America/Lima";
+    readonly 'America/Bogota': "America/Bogota";
+    readonly 'Europe/London': "Europe/London";
+    readonly 'Europe/Paris': "Europe/Paris";
+    readonly 'Europe/Berlin': "Europe/Berlin";
+    readonly 'Europe/Madrid': "Europe/Madrid";
+    readonly 'Europe/Rome': "Europe/Rome";
+    readonly 'Europe/Amsterdam': "Europe/Amsterdam";
+    readonly 'Europe/Brussels': "Europe/Brussels";
+    readonly 'Europe/Vienna': "Europe/Vienna";
+    readonly 'Europe/Warsaw': "Europe/Warsaw";
+    readonly 'Europe/Prague': "Europe/Prague";
+    readonly 'Europe/Moscow': "Europe/Moscow";
+    readonly 'Europe/Istanbul': "Europe/Istanbul";
+    readonly 'Europe/Athens': "Europe/Athens";
+    readonly 'Europe/Helsinki': "Europe/Helsinki";
+    readonly 'Europe/Stockholm': "Europe/Stockholm";
+    readonly 'Europe/Oslo': "Europe/Oslo";
+    readonly 'Europe/Copenhagen': "Europe/Copenhagen";
+    readonly 'Europe/Dublin': "Europe/Dublin";
+    readonly 'Europe/Zurich': "Europe/Zurich";
+    readonly 'Asia/Tokyo': "Asia/Tokyo";
+    readonly 'Asia/Shanghai': "Asia/Shanghai";
+    readonly 'Asia/Hong_Kong': "Asia/Hong_Kong";
+    readonly 'Asia/Singapore': "Asia/Singapore";
+    readonly 'Asia/Seoul': "Asia/Seoul";
+    readonly 'Asia/Taipei': "Asia/Taipei";
+    readonly 'Asia/Bangkok': "Asia/Bangkok";
+    readonly 'Asia/Jakarta': "Asia/Jakarta";
+    readonly 'Asia/Manila': "Asia/Manila";
+    readonly 'Asia/Kuala_Lumpur': "Asia/Kuala_Lumpur";
+    readonly 'Asia/Ho_Chi_Minh': "Asia/Ho_Chi_Minh";
+    readonly 'Asia/Dubai': "Asia/Dubai";
+    readonly 'Asia/Kolkata': "Asia/Kolkata";
+    readonly 'Asia/Mumbai': "Asia/Mumbai";
+    readonly 'Asia/Karachi': "Asia/Karachi";
+    readonly 'Asia/Dhaka': "Asia/Dhaka";
+    readonly 'Asia/Tehran': "Asia/Tehran";
+    readonly 'Asia/Riyadh': "Asia/Riyadh";
+    readonly 'Asia/Jerusalem': "Asia/Jerusalem";
+    readonly 'Australia/Sydney': "Australia/Sydney";
+    readonly 'Australia/Melbourne': "Australia/Melbourne";
+    readonly 'Australia/Brisbane': "Australia/Brisbane";
+    readonly 'Australia/Perth': "Australia/Perth";
+    readonly 'Australia/Adelaide': "Australia/Adelaide";
+    readonly 'Pacific/Auckland': "Pacific/Auckland";
+    readonly 'Pacific/Fiji': "Pacific/Fiji";
+    readonly 'Pacific/Honolulu': "Pacific/Honolulu";
+    readonly 'Africa/Cairo': "Africa/Cairo";
+    readonly 'Africa/Johannesburg': "Africa/Johannesburg";
+    readonly 'Africa/Lagos': "Africa/Lagos";
+    readonly 'Africa/Nairobi': "Africa/Nairobi";
+    readonly 'Africa/Casablanca': "Africa/Casablanca";
+};
+type TimezoneId = keyof typeof TIMEZONES | string;
+/**
+ * ChronosTimezone - Handles timezone operations and conversions
+ *
+ * This class provides comprehensive timezone handling including:
+ * - Timezone information retrieval
+ * - Offset calculations
+ * - DST detection
+ * - Timezone conversions
+ *
+ * @example
+ * ```typescript
+ * // Get timezone info
+ * const tz = ChronosTimezone.create('America/New_York');
+ * console.log(tz.offset); // -5 or -4 depending on DST
+ *
+ * // Check DST
+ * console.log(tz.isDST(new Date())); // true/false
  *
- * @packageDocumentation
+ * // Convert between timezones
+ * const utcDate = new Date();
+ * const localDate = ChronosTimezone.convert(utcDate, 'UTC', 'America/New_York');
+ * ```
+ */
+declare class ChronosTimezone {
+    private _identifier;
+    private _originalOffset;
+    private _extraMinutes;
+    private _cachedOffset;
+    private _cachedDate;
+    /**
+     * Create a new ChronosTimezone
+     */
+    constructor(identifier?: TimezoneId);
+    /**
+     * Normalize timezone identifier
+     */
+    private _normalizeIdentifier;
+    /**
+     * Parse offset string to hours
+     */
+    private _parseOffsetString;
+    /**
+     * Create a timezone instance
+     */
+    static create(identifier?: TimezoneId): ChronosTimezone;
+    /**
+     * Create UTC timezone
+     */
+    static utc(): ChronosTimezone;
+    /**
+     * Create timezone from local system timezone
+     */
+    static local(): ChronosTimezone;
+    /**
+     * Create timezone from offset in hours
+     */
+    static fromOffset(offsetHours: number): ChronosTimezone;
+    /**
+     * Get the local system timezone identifier
+     */
+    static localIdentifier(): string;
+    /**
+     * Get timezone identifier
+     * Returns the original offset string if created from an offset, otherwise returns the IANA identifier
+     */
+    get identifier(): string;
+    /**
+     * Get the internal IANA timezone identifier (used for Intl operations)
+     */
+    get ianaIdentifier(): string;
+    /**
+     * Get timezone name (alias for identifier)
+     */
+    get name(): string;
+    /**
+     * Get timezone abbreviation for a given date
+     */
+    getAbbreviation(date?: Date): string;
+    /**
+     * Get full timezone name for a given date
+     */
+    getFullName(date?: Date): string;
+    /**
+     * Get UTC offset in minutes for a given date
+     */
+    getOffsetMinutes(date?: Date): number;
+    /**
+     * Parse Intl formatter parts to components
+     */
+    private _parseIntlParts;
+    /**
+     * Get UTC offset in hours for a given date
+     */
+    getOffsetHours(date?: Date): number;
+    /**
+     * Get UTC offset as string (e.g., "+05:30", "-08:00")
+     */
+    getOffsetString(date?: Date): string;
+    /**
+     * Get complete offset information
+     */
+    getOffset(date?: Date): TimezoneOffset;
+    /**
+     * Check if DST is in effect for a given date
+     */
+    isDST(date?: Date): boolean;
+    /**
+     * Check if timezone observes DST
+     */
+    observesDST(): boolean;
+    /**
+     * Get the next DST transition
+     */
+    getNextDSTTransition(from?: Date): DSTransition | null;
+    /**
+     * Binary search to find exact DST transition time
+     */
+    private _findExactTransition;
+    /**
+     * Convert a date to this timezone (returns formatted string)
+     */
+    format(date: Date, formatOptions?: Intl.DateTimeFormatOptions): string;
+    /**
+     * Get date components in this timezone
+     */
+    getComponents(date: Date): {
+        year: number;
+        month: number;
+        day: number;
+        hour: number;
+        minute: number;
+        second: number;
+        dayOfWeek: number;
+    };
+    /**
+     * Convert a date from one timezone to another
+     */
+    static convert(date: Date, from: TimezoneId, to: TimezoneId): Date;
+    /**
+     * Convert a UTC date to this timezone
+     */
+    fromUTC(date: Date): Date;
+    /**
+     * Convert a date in this timezone to UTC
+     */
+    toUTC(date: Date): Date;
+    /**
+     * Get comprehensive timezone information
+     */
+    getInfo(date?: Date): TimezoneInfo;
+    /**
+     * Check if two timezones are equivalent at a given moment
+     */
+    equals(other: ChronosTimezone | string, date?: Date): boolean;
+    /**
+     * Check if this is the same timezone identifier
+     */
+    isSame(other: ChronosTimezone | string): boolean;
+    /**
+     * Get all available timezone identifiers
+     * Note: This returns common timezones. Use Intl.supportedValuesOf('timeZone') for all.
+     */
+    static getAvailableTimezones(): string[];
+    /**
+     * Check if a timezone identifier is valid
+     */
+    static isValid(identifier: string): boolean;
+    /**
+     * Get timezones grouped by region
+     */
+    static getTimezonesByRegion(): Record<string, string[]>;
+    /**
+     * Find timezones that match a given offset
+     */
+    static findByOffset(offsetHours: number, date?: Date): ChronosTimezone[];
+    /**
+     * Get current time in a specific timezone
+     */
+    static now(identifier: TimezoneId): Date;
+    /**
+     * Convert to string
+     */
+    toString(): string;
+    /**
+     * Convert to JSON
+     */
+    toJSON(): object;
+    /**
+     * Get primitive value
+     */
+    valueOf(): string;
+}
+/**
+ * Pre-created timezone instances for common timezones
+ */
+declare const Timezones: {
+    readonly UTC: ChronosTimezone;
+    readonly Local: ChronosTimezone;
+    readonly Eastern: ChronosTimezone;
+    readonly Central: ChronosTimezone;
+    readonly Mountain: ChronosTimezone;
+    readonly Pacific: ChronosTimezone;
+    readonly London: ChronosTimezone;
+    readonly Paris: ChronosTimezone;
+    readonly Berlin: ChronosTimezone;
+    readonly Tokyo: ChronosTimezone;
+    readonly Shanghai: ChronosTimezone;
+    readonly Singapore: ChronosTimezone;
+    readonly Dubai: ChronosTimezone;
+    readonly Mumbai: ChronosTimezone;
+    readonly Sydney: ChronosTimezone;
+    readonly Auckland: ChronosTimezone;
+};
+
+/**
+ * Utility functions for Chronos
+ * @module utils
+ */
+
+/**
+ * Check if value is a Date object
+ */
+declare function isDate(value: unknown): value is Date;
+/**
+ * Check if value is a valid date input
+ */
+declare function isValidDateInput(value: unknown): value is DateInput;
+/**
+ * Check if value implements ChronosLike interface
+ */
+declare function isChronosLike(value: unknown): value is ChronosLike;
+/**
+ * Check if value is a Duration object
+ */
+declare function isDuration(value: unknown): value is Duration;
+/**
+ * Check if value is a valid ISO 8601 duration string
+ */
+declare function isISODuration(value: unknown): value is string;
+/**
+ * Check if a year is a leap year
+ */
+declare function isLeapYear(year: number): boolean;
+/**
+ * Normalize a time unit to its canonical form
+ */
+declare function normalizeUnit(unit: AnyTimeUnit | string): TimeUnit;
+/**
+ * Get the plural form of a time unit
+ */
+declare function pluralizeUnit(unit: TimeUnit, count: number): string;
+/**
+ * Get milliseconds for a given time unit
+ */
+declare function getMillisecondsPerUnit(unit: TimeUnit): number;
+/**
+ * Get the number of days in a specific month
+ */
+declare function getDaysInMonth(year: number, month: number): number;
+/**
+ * Get the number of days in a year
+ */
+declare function getDaysInYear(year: number): number;
+/**
+ * Get the day of year (1-366)
+ */
+declare function getDayOfYear(date: Date): number;
+/**
+ * Get the ISO week number (1-53)
+ */
+declare function getISOWeek(date: Date): number;
+/**
+ * Get the ISO week year
+ */
+declare function getISOWeekYear(date: Date): number;
+/**
+ * Get the quarter (1-4)
+ */
+declare function getQuarter(date: Date): number;
+/**
+ * Get start of a time unit
+ */
+declare function startOf(date: Date, unit: TimeUnit): Date;
+/**
+ * Get end of a time unit
+ */
+declare function endOf(date: Date, unit: TimeUnit): Date;
+/**
+ * Add a duration to a date
+ * Handles month overflow by clamping to the last day of the month
+ */
+declare function addDuration(date: Date, duration: Duration): Date;
+/**
+ * Subtract a duration from a date
+ */
+declare function subtractDuration(date: Date, duration: Duration): Date;
+/**
+ * Add a specific number of units to a date
+ */
+declare function addUnits(date: Date, amount: number, unit: TimeUnit): Date;
+/**
+ * Calculate the difference between two dates in a specific unit
+ */
+declare function diffInUnits(date1: Date, date2: Date, unit: TimeUnit): number;
+/**
+ * Parse an ISO 8601 duration string
+ */
+declare function parseISODuration(duration: string): Duration;
+/**
+ * Convert a duration to ISO 8601 format
+ */
+declare function durationToISO(duration: Duration): string;
+/**
+ * Compare two dates at a specific granularity
+ */
+declare function compareAtGranularity(date1: Date, date2: Date, unit: TimeUnit): number;
+/**
+ * Check if two dates are the same at a specific granularity
+ */
+declare function isSameAt(date1: Date, date2: Date, unit: TimeUnit): boolean;
+/**
+ * Create a deep clone of a date
+ */
+declare function cloneDate(date: Date): Date;
+/**
+ * Check if a date is valid
+ */
+declare function isValidDate(date: Date): boolean;
+/**
+ * Ensure a value is within bounds
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Get ordinal suffix for a number (1st, 2nd, 3rd, etc.)
+ */
+declare function ordinalSuffix(n: number): string;
+/**
+ * Pad a number with leading zeros
+ */
+declare function padStart(value: number | string, length: number, char?: string): string;
+
+/**
+ * Locale configuration for Chronos
+ * @module locales
+ */
+
+/**
+ * English (US) locale configuration
+ */
+declare const en: LocaleConfig;
+/**
+ * French locale configuration
+ */
+declare const fr: LocaleConfig;
+/**
+ * Spanish locale configuration
+ */
+declare const es: LocaleConfig;
+/**
+ * Italian locale configuration
+ */
+declare const it: LocaleConfig;
+/**
+ * Arabic locale configuration (Modern Standard Arabic)
+ */
+declare const ar: LocaleConfig;
+/**
+ * Russian locale configuration
+ */
+declare const ru: LocaleConfig;
+/**
+ * German locale configuration
+ */
+declare const de: LocaleConfig;
+/**
+ * Japanese locale configuration
+ */
+declare const ja: LocaleConfig;
+/**
+ * Chinese (Simplified) locale configuration
+ */
+declare const zh: LocaleConfig;
+/**
+ * Portuguese (Brazil) locale configuration
+ */
+declare const pt: LocaleConfig;
+/**
+ * Default locale
+ */
+declare const defaultLocale: LocaleConfig;
+/**
+ * Get a locale by code
+ */
+declare function getLocale(code: string): LocaleConfig;
+/**
+ * Register a new locale
+ */
+declare function registerLocale(config: LocaleConfig): void;
+/**
+ * Get available locale codes
  */
-export { Chronos, ChronosInterval, ChronosPeriod, ChronosPeriodCollection, ChronosTimezone, TIMEZONES, Timezones, type TimezoneId, } from './core';
-export { DayOfWeek, Month, PeriodBoundary, type TimeUnit, type TimeUnitPlural, type TimeUnitShort, type AnyTimeUnit, type Duration, type DateInput, type ChronosLike, type ChronosConfig, type DateTimeComponents, type DateTimeSetter, type ISODuration, type FormatTokens, type FormatPreset, type CompareOperator, type CompareGranularity, type PeriodOptions, type TimezoneInput, type TimezoneInfo, type TimezoneOffset, type DSTransition, type LocaleConfig, type HumanDiffOptions, type DiffResult, type ChronosSerializable, type ChronosJSON, type TimeRange, type BusinessHours, type CalendarWeek, type CalendarMonth, type DeepPartial, type NumericKeys, type TypeGuard, type Chainable, MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR, SECONDS_PER_MINUTE, MINUTES_PER_HOUR, HOURS_PER_DAY, DAYS_PER_WEEK, MONTHS_PER_YEAR, DAYS_PER_YEAR, DAYS_PER_LEAP_YEAR, AVERAGE_DAYS_PER_MONTH, AVERAGE_DAYS_PER_YEAR, } from './types';
-export { isDate, isValidDateInput, isChronosLike, isDuration, isISODuration, isLeapYear, isValidDate, normalizeUnit, pluralizeUnit, getMillisecondsPerUnit, getDaysInMonth, getDaysInYear, getDayOfYear, getISOWeek, getISOWeekYear, getQuarter, startOf, endOf, addDuration, subtractDuration, addUnits, diffInUnits, parseISODuration, durationToISO, compareAtGranularity, isSameAt, cloneDate, clamp, ordinalSuffix, padStart, } from './utils';
-export { getLocale, registerLocale, getAvailableLocales, defaultLocale, en, es, fr, de, ja, zh, pt, it, ar, ru, } from './locales';
-export { Chronos as default } from './core';
+declare function getAvailableLocales(): string[];
+
+export { AVERAGE_DAYS_PER_MONTH, AVERAGE_DAYS_PER_YEAR, type AnyTimeUnit, type BusinessHours, type CalendarMonth, type CalendarWeek, type Chainable, Chronos, type ChronosConfig, ChronosInterval, type ChronosJSON, type ChronosLike, ChronosPeriod, ChronosPeriodCollection, type ChronosSerializable, ChronosTimezone, type CompareGranularity, type CompareOperator, DAYS_PER_LEAP_YEAR, DAYS_PER_WEEK, DAYS_PER_YEAR, type DSTransition, type DateInput, type DateTimeComponents, type DateTimeSetter, DayOfWeek, type DeepPartial, type DiffResult, type Duration, type FormatPreset, type FormatTokens, HOURS_PER_DAY, type HumanDiffOptions, type ISODuration, type LocaleConfig, MILLISECONDS_PER_DAY, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_SECOND, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_YEAR, MINUTES_PER_HOUR, MONTHS_PER_YEAR, Month, type NumericKeys, PeriodBoundary, type PeriodOptions, SECONDS_PER_MINUTE, TIMEZONES, type TimeRange, type TimeUnit, type TimeUnitPlural, type TimeUnitShort, type TimezoneId, type TimezoneInfo, type TimezoneInput, type TimezoneOffset, Timezones, type TypeGuard, addDuration, addUnits, ar, clamp, cloneDate, compareAtGranularity, de, Chronos as default, defaultLocale, diffInUnits, durationToISO, en, endOf, es, fr, getAvailableLocales, getDayOfYear, getDaysInMonth, getDaysInYear, getISOWeek, getISOWeekYear, getLocale, getMillisecondsPerUnit, getQuarter, isChronosLike, isDate, isDuration, isISODuration, isLeapYear, isSameAt, isValidDate, isValidDateInput, it, ja, normalizeUnit, ordinalSuffix, padStart, parseISODuration, pluralizeUnit, pt, registerLocale, ru, startOf, subtractDuration, zh };