datetick 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1227 @@
+type DateUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'date' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+type DateFormatPreset = 'short' | 'medium' | 'long' | 'full' | 'dateOnly' | 'timeOnly' | 'weekdayTime' | 'isoStyle12h' | 'isoStyle24h';
+type DateGettableUnit = DateUnit | 'dayOfYear' | 'isoDay' | 'isoWeek' | 'isoWeekYear' | 'isoWeeksInYear' | 'weekYear' | 'weekday' | 'weeksInYear' | 'daysInMonth';
+type CalendarDiffUnit = 'date' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/**
+ * Per-side bound inclusivity for {@link DateTick.isBetween}: `(` / `)` are exclusive, `[` / `]` are inclusive.
+ * For example `'[)'` includes the start bound but excludes the end bound.
+ */
+type Inclusivity = '()' | '[]' | '(]' | '[)';
+type DateArray = [
+    year: number,
+    month: number,
+    date: number,
+    hour?: number,
+    minute?: number,
+    second?: number,
+    millisecond?: number
+];
+interface DateObject {
+    year: number;
+    month: number;
+    date: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+}
+interface DatePartsObject extends Required<DateObject> {
+    day: number;
+}
+/**
+ * Anything that can be resolved to a point in time: a native Date, an ISO/parsable string,
+ * a Unix timestamp in milliseconds, or another DateTick instance.
+ */
+type DateInput = Date | string | number | DateTick | DateObject | DateArray;
+/**
+ * A localized weekday label for a calendar grid header.
+ */
+interface CalendarWeekday {
+    day: number;
+    isoDay: number;
+    long: string;
+    short: string;
+    narrow: string;
+}
+/**
+ * A single date cell in a calendar month grid.
+ */
+interface CalendarDate {
+    value: DateTick;
+    isoDate: string;
+    formatted: string;
+    year: number;
+    month: number;
+    date: number;
+    day: number;
+    isoDay: number;
+    isCurrentMonth: boolean;
+    isToday: boolean;
+    isSelected: boolean;
+}
+/**
+ * Options for calendar month generation.
+ */
+interface CalendarMonthOptions {
+    selected?: DateInput | false;
+    dateFormat?: string | Intl.DateTimeFormatOptions | ((date: DateTick) => string);
+}
+/**
+ * Token patterns used by {@link DateTick.calendar} for calendar-style relative labels.
+ */
+interface CalendarDisplayFormats {
+    sameDay?: string | ((date: DateTick) => string);
+    nextDay?: string | ((date: DateTick) => string);
+    nextWeek?: string | ((date: DateTick) => string);
+    lastDay?: string | ((date: DateTick) => string);
+    lastWeek?: string | ((date: DateTick) => string);
+    sameElse?: string | ((date: DateTick) => string);
+}
+/**
+ * Calendar data for rendering a month view.
+ */
+interface CalendarMonth {
+    year: number;
+    month: number;
+    label: string;
+    weekdays: CalendarWeekday[];
+    days: CalendarDate[];
+    weeks: CalendarDate[][];
+}
+/**
+ * A bag of calendar components used to construct a Duration.
+ */
+interface DurationInput {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+/**
+ * Produces the ordinal form of a number (e.g. `1` -> `'1st'` in English, `'1er'` in French). Supplied
+ * via the factory to localize `ordinal()` and the `Do`/`wo`/`Wo` tokens, which are English by default.
+ */
+type OrdinalFn = (n: number) => string;
+/**
+ * Locale metadata for a {@link DateTick}, resolved through `Intl` — the Day.js `localeData()` equivalent.
+ */
+interface LocaleData {
+    /** Long month names, index 0 = January. */
+    months(): string[];
+    /** Short month names, index 0 = January. */
+    monthsShort(): string[];
+    /** Long weekday names, index 0 = Sunday. */
+    weekdays(): string[];
+    /** Short weekday names, index 0 = Sunday. */
+    weekdaysShort(): string[];
+    /** Narrow (minimal) weekday names, index 0 = Sunday. */
+    weekdaysMin(): string[];
+    /** The configured first day of the week (0 = Sunday … 6 = Saturday). */
+    firstDayOfWeek(): number;
+    /** The locale's AM/PM markers. */
+    meridiems(): {
+        am: string;
+        pm: string;
+    };
+    /** The AM or PM marker for a 0-23 hour (lowercased when `isLowercase`). */
+    meridiem(hour: number, isLowercase?: boolean): string;
+    /** The ordinal form of a number (e.g. `1` -> `'1st'`). */
+    ordinal(n: number): string;
+}
+/**
+ * Overrides the cutoffs {@link DateTick.timeAgo} uses to step up from one unit to the next. Each value is
+ * the largest count of that unit still shown before switching to the next larger unit (e.g. `second: 60`
+ * shows seconds up to 59, then minutes). Months use a 30-day approximation and years a 365-day one.
+ */
+interface RelativeTimeThresholds {
+    /** Max seconds before switching to minutes (default 60). */
+    second?: number;
+    /** Max minutes before switching to hours (default 60). */
+    minute?: number;
+    /** Max hours before switching to days (default 24). */
+    hour?: number;
+    /** Max days before switching to months (default 30). */
+    day?: number;
+    /** Max months before switching to years (default 12). */
+    month?: number;
+}
+/**
+ * Receives live relative-time labels from {@link DateTick.timeAgoLive}.
+ */
+type TimeAgoListener = (value: string) => void;
+/**
+ * A dependency-free live relative-time subscription.
+ */
+interface TimeAgoLive {
+    subscribe(listener: TimeAgoListener): () => void;
+    unsubscribe(): void;
+}
+
+/**
+ * An immutable length of time, independent of any particular instant.
+ *
+ * Conversions use fixed ratios (1 month = 30 days, 1 year = 365 days). `humanize()` is locale-aware via `Intl`.
+ *
+ * @class Duration
+ */
+declare class Duration {
+    private readonly _locale;
+    private readonly _ms;
+    /**
+     * Creates a Duration.
+     *
+     * @param {number | string | DurationInput} value - A millisecond amount, an amount paired with `unit`,
+     * an ISO 8601 duration string (e.g. 'P1Y2M10DT2H30M'), or a components object
+     * @param {DateUnit} [unit] - The unit when `value` is a number (defaults to milliseconds)
+     * @param {string} [locale='en'] - The locale used by `humanize()`
+     * @throws {Error} If `value` is a string that is not a valid ISO 8601 duration
+     * @memberof Duration
+     */
+    constructor(value: number | string | DurationInput, unit?: DateUnit, locale?: string);
+    /**
+     * Checks whether a value is a Duration instance.
+     *
+     * @param {unknown} value - The value to check
+     * @returns {boolean} True if the value is a Duration
+     * @memberof Duration
+     */
+    static isDuration(value: unknown): value is Duration;
+    /**
+     * Returns a new Duration with the given amount added
+     *
+     * @param {number} value - The amount to add
+     * @param {DateUnit} [unit='millisecond'] - The unit of the amount
+     * @returns {Duration} The new Duration
+     * @memberof Duration
+     */
+    add(value: number, unit?: DateUnit): Duration;
+    /**
+     * The whole duration expressed in a chosen unit.
+     *
+     * @param {DateUnit} unit - The target unit
+     * @returns {number} The duration in that unit
+     * @memberof Duration
+     */
+    as(unit: DateUnit): number;
+    /**
+     * The whole duration expressed in days (fractional)
+     *
+     * @returns {number} The duration in days
+     * @memberof Duration
+     */
+    asDays(): number;
+    /**
+     * The whole duration expressed in hours (fractional)
+     *
+     * @returns {number} The duration in hours
+     * @memberof Duration
+     */
+    asHours(): number;
+    /**
+     * The whole duration expressed in milliseconds
+     *
+     * @returns {number} The duration in milliseconds
+     * @memberof Duration
+     */
+    asMilliseconds(): number;
+    /**
+     * The whole duration expressed in minutes (fractional)
+     *
+     * @returns {number} The duration in minutes
+     * @memberof Duration
+     */
+    asMinutes(): number;
+    /**
+     * The whole duration expressed in months (fractional, 1 month = 30 days)
+     *
+     * @returns {number} The duration in months
+     * @memberof Duration
+     */
+    asMonths(): number;
+    /**
+     * The whole duration expressed in seconds (fractional)
+     *
+     * @returns {number} The duration in seconds
+     * @memberof Duration
+     */
+    asSeconds(): number;
+    /**
+     * The whole duration expressed in weeks (fractional)
+     *
+     * @returns {number} The duration in weeks
+     * @memberof Duration
+     */
+    asWeeks(): number;
+    /**
+     * The whole duration expressed in years (fractional, 1 year = 365 days)
+     *
+     * @returns {number} The duration in years
+     * @memberof Duration
+     */
+    asYears(): number;
+    /**
+     * The days component after extracting whole years and months
+     *
+     * @returns {number} The days component
+     * @memberof Duration
+     */
+    days(): number;
+    /**
+     * Formats the duration with Day.js-style duration tokens.
+     *
+     * Supported tokens: `Y` `YY` `YYYY` `M` `MM` `D` `DD` `H` `HH` `m` `mm` `s` `ss` `SSS`.
+     * Wrap literal text in `[square brackets]`.
+     *
+     * @param {string} [pattern='HH:mm:ss'] - The token pattern
+     * @returns {string} The formatted duration
+     * @memberof Duration
+     */
+    format(pattern?: string): string;
+    /**
+     * Returns the duration component for a unit.
+     *
+     * @param {DateUnit} unit - The component unit
+     * @returns {number} The component value
+     * @memberof Duration
+     */
+    get(unit: DateUnit): number;
+    /**
+     * The hours component
+     *
+     * @returns {number} The hours component
+     * @memberof Duration
+     */
+    hours(): number;
+    /**
+     * Returns a human-readable, locale-aware string for the duration (e.g. '2 days', 'in 2 days')
+     *
+     * @param {boolean} [withSuffix=false] - Include a relative suffix (past/future) based on the sign
+     * @returns {string} The humanized string
+     * @memberof Duration
+     */
+    humanize(withSuffix?: boolean): string;
+    /**
+     * The milliseconds component
+     *
+     * @returns {number} The milliseconds component
+     * @memberof Duration
+     */
+    milliseconds(): number;
+    /**
+     * The minutes component
+     *
+     * @returns {number} The minutes component
+     * @memberof Duration
+     */
+    minutes(): number;
+    /**
+     * The months component after extracting whole years
+     *
+     * @returns {number} The months component
+     * @memberof Duration
+     */
+    months(): number;
+    /**
+     * The seconds component
+     *
+     * @returns {number} The seconds component
+     * @memberof Duration
+     */
+    seconds(): number;
+    /**
+     * Returns a new Duration with the given amount subtracted
+     *
+     * @param {number} value - The amount to subtract
+     * @param {DateUnit} [unit='millisecond'] - The unit of the amount
+     * @returns {Duration} The new Duration
+     * @memberof Duration
+     */
+    subtract(value: number, unit?: DateUnit): Duration;
+    /**
+     * Returns the ISO 8601 duration representation (e.g. 'P1Y2M3DT4H5M6S')
+     *
+     * @returns {string} The ISO 8601 duration string
+     * @memberof Duration
+     */
+    toISOString(): string;
+    /**
+     * Serializes the duration as its ISO 8601 string (so `JSON.stringify` works)
+     *
+     * @returns {string} The ISO 8601 duration string
+     * @memberof Duration
+     */
+    toJSON(): string;
+    /**
+     * The total duration in milliseconds (enables numeric coercion, e.g. `+duration`)
+     *
+     * @returns {number} The duration in milliseconds
+     * @memberof Duration
+     */
+    valueOf(): number;
+    /**
+     * The years component
+     *
+     * @returns {number} The years component
+     * @memberof Duration
+     */
+    years(): number;
+    private absComponents;
+    /**
+     * Decomposes the absolute duration into signed calendar components (years → milliseconds).
+     */
+    private components;
+}
+
+/**
+ * Framework-agnostic, fully timezone-aware date utility class.
+ *
+ * Instances are immutable: every getter/setter-style method returns a brand new
+ * `DateTick` rather than mutating the current one, so it is safe to share instances
+ * across Angular components, React renders, Vue computed properties, or plain scripts.
+ *
+ * Every calendar operation — reading components, setting them, `add`/`subtract`,
+ * `startOf`/`endOf`, week/quarter math and formatting — is resolved through the configured
+ * IANA `timezone`, so a single absolute instant is consistently interpreted in one zone.
+ *
+ * @class DateTick
+ * @author Andreas Nicolaou <anicolaou66@gmail.com>
+ */
+declare class DateTick {
+    private readonly _date;
+    private readonly _locale;
+    private readonly _ordinal?;
+    private readonly _timezone;
+    private readonly _weekStartsOn;
+    /**
+     * Creates a new DateTick instance.
+     *
+     * @param {string} [locale='en'] - The BCP 47 locale used for formatting
+     * @param {string} [timezone] - The IANA timezone all calendar operations resolve through (defaults to the runtime's timezone)
+     * @param {DateInput} [date] - The wrapped instant or zoned wall-clock parts (defaults to now). Date instances are cloned defensively.
+     * @param {number} [weekStartsOn=0] - First day of the week (0 = Sunday … 6 = Saturday), used by `week()` and `startOf`/`endOf('week')`
+     * @param {OrdinalFn} [ordinal] - Overrides the English ordinal used by `ordinal()` and the `Do`/`wo`/`Wo` tokens
+     * @memberof DateTick
+     */
+    constructor(locale?: string, timezone?: string, date?: DateInput, weekStartsOn?: number, ordinal?: OrdinalFn);
+    /**
+     * Creates a {@link Duration} representing a length of time.
+     *
+     * @param {number | string | DurationInput} value - A millisecond amount, an amount paired with `unit`,
+     * an ISO 8601 duration string (e.g. 'P1Y2M10DT2H30M'), or a components object
+     * @param {DateUnit} [unit] - The unit when `value` is a number (defaults to milliseconds)
+     * @param {string} [locale='en'] - The locale used by `humanize()`
+     * @returns {Duration} The duration
+     * @example DateTick.duration(2, 'hour').humanize() // '2 hours'
+     * @memberof DateTick
+     */
+    static duration(value: number | string | DurationInput, unit?: DateUnit, locale?: string): Duration;
+    /**
+     * Returns the runtime's best-guess IANA timezone.
+     *
+     * @returns {string} The guessed IANA timezone
+     * @memberof DateTick
+     */
+    static guessTimezone(): string;
+    /**
+     * Checks whether a value is a DateTick instance.
+     *
+     * @param {unknown} value - The value to check
+     * @returns {boolean} True if the value is a DateTick
+     * @memberof DateTick
+     */
+    static isDateTick(value: unknown): value is DateTick;
+    /**
+     * Checks if a date value is valid
+     *
+     * @param {DateInput} date - The date to validate
+     * @returns {boolean} True if valid, false otherwise
+     * @memberof DateTick
+     */
+    static isValid(date: DateInput): boolean;
+    /**
+     * Returns the maximum (latest) date from a list
+     *
+     * @param {...DateInput[]} dates - Dates to compare
+     * @returns {Date} The latest date
+     * @memberof DateTick
+     */
+    static max(...dates: DateInput[]): Date;
+    /**
+     * Returns the minimum (earliest) date from a list
+     *
+     * @param {...DateInput[]} dates - Dates to compare
+     * @returns {Date} The earliest date
+     * @memberof DateTick
+     */
+    static min(...dates: DateInput[]): Date;
+    /**
+     * Parses a string into a DateTick using an explicit token pattern, interpreting the wall-clock
+     * values in the given timezone. Supported tokens mirror {@link DateTick.formatPattern}; anything
+     * else (and text wrapped in `[square brackets]`) is treated as a literal.
+     *
+     * @param {string} input - The string to parse (e.g. '25/06/2026 22:23')
+     * @param {string} pattern - The token pattern (e.g. 'DD/MM/YYYY HH:mm')
+     * @param {string} [locale='en'] - The BCP 47 locale (also used to resolve month names)
+     * @param {string} [timezone] - The IANA timezone the wall-clock values belong to
+     * @returns {DateTick} The parsed DateTick
+     * @throws {Error} If the input does not match the pattern
+     * @memberof DateTick
+     */
+    static parse(input: string, pattern: string, locale?: string, timezone?: string): DateTick;
+    private static inputParts;
+    private static resolveInput;
+    /**
+     * Adds a specified amount of time to the wrapped date (chainable, immutable).
+     *
+     * Calendar units (`date`/`day`, `week`, `month`, `quarter`, `year`) preserve the wall-clock
+     * time in the configured timezone (so they survive DST). Fixed-duration units
+     * (`millisecond`/`second`/`minute`/`hour`) add absolute time. Month/year additions clamp the day
+     * to the last day of the resulting month instead of overflowing (Jan 31 + 1 month -> Feb 28/29).
+     *
+     * @param {number} amount - The amount to add (negative values subtract)
+     * @param {DateUnit} unit - The unit to add (e.g. 'day', 'month')
+     * @returns {DateTick} A new DateTick with the result
+     * @memberof DateTick
+     */
+    add(amount: number, unit: DateUnit): DateTick;
+    /**
+     * Formats the date as a calendar-style relative label such as "Today at 7:23 PM".
+     *
+     * @param {DateInput} [reference] - The date to compare against (defaults to now)
+     * @param {CalendarDisplayFormats} [formats] - Token patterns or callbacks for each calendar bucket
+     * @returns {string} The calendar-style label
+     * @memberof DateTick
+     */
+    calendar(reference?: DateInput, formats?: CalendarDisplayFormats): string;
+    /**
+     * Returns localized month-grid data for rendering a calendar UI.
+     *
+     * The grid is padded with adjacent-month dates so every week has seven cells,
+     * and the weekday order follows the configured `weekStartsOn`.
+     *
+     * @returns {CalendarMonth} Calendar data for the wrapped date's month
+     * @memberof DateTick
+     */
+    calendarMonth(options?: CalendarMonthOptions): CalendarMonth;
+    /**
+     * Returns a new DateTick with the exact same instant, locale and timezone
+     *
+     * @returns {DateTick} The cloned instance
+     * @memberof DateTick
+     */
+    clone(): DateTick;
+    /**
+     * Gets or sets the day of the month (in the configured timezone)
+     *
+     * @param {number} [value] - The day of the month to set
+     * @returns {number | DateTick} The day of the month, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    date(): number;
+    date(value: number): DateTick;
+    /** Day.js-style plural alias of {@link DateTick.date} (day of the month). */
+    dates(): number;
+    dates(value: number): DateTick;
+    /**
+     * Gets or sets the day of the week (0 = Sunday … 6 = Saturday, in the configured timezone)
+     *
+     * @param {number} [value] - The day of the week to set
+     * @returns {number | DateTick} The day of the week, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    day(): number;
+    day(value: number): DateTick;
+    /**
+     * Gets or sets the day of the year (1-based, in the configured timezone).
+     *
+     * Setting beyond the number of days in the year rolls over into the following year(s),
+     * the same way a native `Date` rolls over an out-of-range day-of-month.
+     *
+     * @param {number} [value] - The day of the year to set
+     * @returns {number | DateTick} The day of the year, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    dayOfYear(): number;
+    dayOfYear(value: number): DateTick;
+    /** Day.js-style plural alias of {@link DateTick.day} (day of the week). */
+    days(): number;
+    days(value: number): DateTick;
+    /**
+     * Gets the number of days in the wrapped date's month (in the configured timezone)
+     *
+     * @returns {number} The number of days in the month
+     * @memberof DateTick
+     */
+    daysInMonth(): number;
+    /**
+     * Gets the difference between the wrapped date and another date.
+     *
+     * @param {DateInput} date - The date to compare against
+     * @param {DateUnit} [unit='millisecond'] - The unit of measurement
+     * @param {boolean} [precise=false] - When true, returns a floating-point value instead of truncating.
+     * For `month`/`quarter`/`year` the fractional part reflects progress through the current calendar unit.
+     * @returns {number} The difference (positive when the wrapped date is later)
+     * @memberof DateTick
+     */
+    diff(date: DateInput, unit?: DateUnit, precise?: boolean): number;
+    /**
+     * Calendar-boundary difference in the configured timezone.
+     *
+     * Unlike {@link DateTick.diff}, this counts calendar units rather than elapsed duration.
+     * For example, Friday 23:00 to Saturday 01:00 is one calendar day apart even though
+     * only two hours elapsed.
+     *
+     * @param {DateInput} date - The date to compare against
+     * @param {CalendarDiffUnit} [unit='day'] - Calendar unit to compare
+     * @returns {number} The calendar difference, positive when this instance is later
+     * @memberof DateTick
+     */
+    diffCalendar(date: DateInput, unit?: CalendarDiffUnit): number;
+    /**
+     * Returns a new DateTick set to the end of the given unit (one millisecond before the next unit starts)
+     *
+     * @param {DateUnit} unit - The unit to snap to (e.g. 'month', 'day')
+     * @returns {DateTick} A new DateTick at the end of the unit
+     * @memberof DateTick
+     */
+    endOf(unit: DateUnit): DateTick;
+    /**
+     * Formats a date using Intl.DateTimeFormat or a preset (in the configured timezone)
+     *
+     * @param {Intl.DateTimeFormatOptions | DateFormatPreset} [format] - Format options or preset
+     * @returns {string} The formatted date string
+     * @memberof DateTick
+     */
+    format(format?: Intl.DateTimeFormatOptions | DateFormatPreset): string;
+    /**
+     * Formats the date using a token pattern, resolved in the configured timezone.
+     *
+     * Core tokens: `YYYY` `YY` `MMMM` `MMM` `MM` `M` `DD` `D` `dddd` `ddd` `dd` `d` `HH` `H` `hh` `h`
+     * `mm` `m` `ss` `s` `SSS` `A` `a` `Z` `ZZ`. Advanced: `Do` `Q` `k` `kk` `X` `x` `w` `ww` `wo` `W` `WW` `Wo`.
+     * Localized (resolved to the configured locale's field order and separators): `L` `LL` `LLL` `LLLL`
+     * `l` `ll` `lll` `llll` `LT` `LTS`. Wrap literal text in `[square brackets]`.
+     *
+     * @param {string} pattern - The token pattern (e.g. 'DD/MM/YYYY HH:mm')
+     * @returns {string} The formatted string
+     * @example date.formatPattern('DD/MM/YYYY') // '25/06/2026'
+     * @memberof DateTick
+     */
+    formatPattern(pattern: string): string;
+    /**
+     * Formats the date relative to another date, Day.js-style.
+     *
+     * @param {DateInput} date - The date to compare from
+     * @param {boolean} [withoutSuffix=false] - When true, omit "ago" / "in"
+     * @returns {string} The relative-time label
+     * @memberof DateTick
+     */
+    from(date: DateInput, withoutSuffix?: boolean): string;
+    /**
+     * Formats the date relative to now, Day.js-style.
+     *
+     * @param {boolean} [withoutSuffix=false] - When true, omit "ago" / "in"
+     * @returns {string} The relative-time label
+     * @memberof DateTick
+     */
+    fromNow(withoutSuffix?: boolean): string;
+    /**
+     * Gets a specific unit (or derived value) from the wrapped date
+     *
+     * @param {DateGettableUnit} unit - The unit to get (e.g. 'year', 'isoWeek')
+     * @returns {number} The value of the unit
+     * @memberof DateTick
+     */
+    get(unit: DateGettableUnit): number;
+    /**
+     * Gets or sets the hour (in the configured timezone)
+     *
+     * @param {number} [value] - The hour to set
+     * @returns {number | DateTick} The hour, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    hour(): number;
+    hour(value: number): DateTick;
+    /** Day.js-style plural alias of {@link DateTick.hour}. */
+    hours(): number;
+    hours(value: number): DateTick;
+    /**
+     * Checks if the wrapped date is strictly after another date
+     *
+     * @param {DateInput} date - The date to compare against
+     * @returns {boolean} True if the wrapped date is later
+     * @memberof DateTick
+     */
+    isAfter(date: DateInput): boolean;
+    /**
+     * Checks if the wrapped date is strictly before another date
+     *
+     * @param {DateInput} date - The date to compare against
+     * @returns {boolean} True if the wrapped date is earlier
+     * @memberof DateTick
+     */
+    isBefore(date: DateInput): boolean;
+    /**
+     * Checks if the wrapped date falls between two dates.
+     *
+     * @param {DateInput} start - The lower bound
+     * @param {DateInput} end - The upper bound
+     * @param {boolean | Inclusivity} [inclusivity=false] - `false`/`'()'` excludes both bounds,
+     * `true`/`'[]'` includes both, or use `'(]'`/`'[)'` to control each side independently
+     * @returns {boolean} True if the wrapped date is between start and end
+     * @memberof DateTick
+     */
+    isBetween(start: DateInput, end: DateInput, inclusivity?: boolean | Inclusivity): boolean;
+    /**
+     * Checks if the wrapped date's year is a leap year (in the configured timezone)
+     *
+     * @returns {boolean} True if the year is a leap year
+     * @memberof DateTick
+     */
+    isLeapYear(): boolean;
+    /**
+     * Checks if the wrapped date is the same as another date, optionally truncated to a unit
+     *
+     * @param {DateInput} date - The date to compare against
+     * @param {DateUnit} [unit] - When provided, compares after snapping both dates to the start of this unit
+     * @returns {boolean} True if the dates are the same
+     * @memberof DateTick
+     */
+    isSame(date: DateInput, unit?: DateUnit): boolean;
+    /**
+     * Checks if the wrapped date is the same as or after another date, optionally truncated to a unit
+     *
+     * @param {DateInput} date - The date to compare against
+     * @param {DateUnit} [unit] - When provided, compares after snapping both dates to the start of this unit
+     * @returns {boolean} True if the wrapped date is the same as or later than the other
+     * @memberof DateTick
+     */
+    isSameOrAfter(date: DateInput, unit?: DateUnit): boolean;
+    /**
+     * Checks if the wrapped date is the same as or before another date, optionally truncated to a unit
+     *
+     * @param {DateInput} date - The date to compare against
+     * @param {DateUnit} [unit] - When provided, compares after snapping both dates to the start of this unit
+     * @returns {boolean} True if the wrapped date is the same as or earlier than the other
+     * @memberof DateTick
+     */
+    isSameOrBefore(date: DateInput, unit?: DateUnit): boolean;
+    /**
+     * Checks if the wrapped date is today in the configured timezone.
+     *
+     * @returns {boolean} True if the date is today
+     * @memberof DateTick
+     */
+    isToday(): boolean;
+    /**
+     * Checks if the wrapped date is tomorrow in the configured timezone.
+     *
+     * @returns {boolean} True if the date is tomorrow
+     * @memberof DateTick
+     */
+    isTomorrow(): boolean;
+    /**
+     * Checks whether the wrapped date itself is a valid date
+     *
+     * @returns {boolean} True if valid, false otherwise
+     * @memberof DateTick
+     */
+    isValid(): boolean;
+    /**
+     * Checks if the wrapped date is yesterday in the configured timezone.
+     *
+     * @returns {boolean} True if the date is yesterday
+     * @memberof DateTick
+     */
+    isYesterday(): boolean;
+    /**
+     * Gets the ISO day of the week (1-7, Monday-Sunday, in the configured timezone)
+     *
+     * @returns {number} The ISO day
+     * @memberof DateTick
+     */
+    isoDay(): number;
+    /**
+     * Gets the ISO week number (in the configured timezone)
+     *
+     * @returns {number} The ISO week number
+     * @memberof DateTick
+     */
+    isoWeek(): number;
+    /**
+     * Gets the ISO week year (in the configured timezone)
+     *
+     * @returns {number} The ISO week year
+     * @memberof DateTick
+     */
+    isoWeekYear(): number;
+    /**
+     * Gets the number of ISO weeks in the year (in the configured timezone)
+     *
+     * @returns {number} The number of ISO weeks
+     * @memberof DateTick
+     */
+    isoWeeksInYear(): number;
+    /**
+     * Returns a new DateTick in the runtime's local timezone, keeping the same instant.
+     *
+     * @returns {DateTick} The local-timezone instance
+     * @memberof DateTick
+     */
+    local(): DateTick;
+    /**
+     * Gets the configured locale
+     *
+     * @returns {string} The BCP 47 locale
+     * @memberof DateTick
+     */
+    locale(): string;
+    /**
+     * Returns locale metadata (month/weekday names, first day of week, meridiems, ordinal), resolved
+     * through `Intl` — the Day.js `localeData()` equivalent.
+     *
+     * @returns {LocaleData} The locale metadata
+     * @example datetick('2026-06-25', { locale: 'fr' }).localeData().months()[0] // 'janvier'
+     * @memberof DateTick
+     */
+    localeData(): LocaleData;
+    /**
+     * Gets or sets the milliseconds
+     *
+     * @param {number} [value] - The milliseconds to set
+     * @returns {number | DateTick} The milliseconds, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    millisecond(): number;
+    millisecond(value: number): DateTick;
+    /** Day.js-style plural alias of {@link DateTick.millisecond}. */
+    milliseconds(): number;
+    milliseconds(value: number): DateTick;
+    /**
+     * Gets or sets the minutes (in the configured timezone)
+     *
+     * @param {number} [value] - The minutes to set
+     * @returns {number | DateTick} The minutes, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    minute(): number;
+    minute(value: number): DateTick;
+    /** Day.js-style plural alias of {@link DateTick.minute}. */
+    minutes(): number;
+    minutes(value: number): DateTick;
+    /**
+     * Gets or sets the month (0-11, in the configured timezone)
+     *
+     * @param {number} [value] - The month to set
+     * @returns {number | DateTick} The month, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    month(): number;
+    month(value: number): DateTick;
+    /** Day.js-style plural alias of {@link DateTick.month}. */
+    months(): number;
+    months(value: number): DateTick;
+    /**
+     * Gets the day of the month with its ordinal suffix (e.g. '1st', '22nd', '31st'). English by default,
+     * or the factory's `ordinal` override when one is configured.
+     *
+     * @returns {string} The ordinal day-of-month
+     * @memberof DateTick
+     */
+    ordinal(): string;
+    /**
+     * Gets or sets the quarter of the year (1-4, in the configured timezone).
+     *
+     * Setting preserves the current month's offset within its quarter (e.g. the 2nd month of
+     * the quarter stays the 2nd month) while moving to the target quarter.
+     *
+     * @param {number} [value] - The quarter (1-4) to set
+     * @returns {number | DateTick} The quarter, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    quarter(): number;
+    quarter(value: number): DateTick;
+    /**
+     * Gets or sets the seconds (in the configured timezone)
+     *
+     * @param {number} [value] - The seconds to set
+     * @returns {number | DateTick} The seconds, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    second(): number;
+    second(value: number): DateTick;
+    /** Day.js-style plural alias of {@link DateTick.second}. */
+    seconds(): number;
+    seconds(value: number): DateTick;
+    /**
+     * Sets a specific unit on the wrapped date
+     *
+     * @param {DateUnit} unit - The unit to set (e.g. 'year', 'month')
+     * @param {number} value - The value to set
+     * @returns {DateTick} A new DateTick with the result
+     * @memberof DateTick
+     */
+    set(unit: DateUnit, value: number): DateTick;
+    /**
+     * Returns a new DateTick set to the start of the given unit (in the configured timezone)
+     *
+     * @param {DateUnit} unit - The unit to snap to (e.g. 'month', 'day')
+     * @returns {DateTick} A new DateTick at the start of the unit
+     * @memberof DateTick
+     */
+    startOf(unit: DateUnit): DateTick;
+    /**
+     * Subtracts a specified amount of time from the wrapped date (chainable, immutable)
+     *
+     * @param {number} amount - The amount to subtract
+     * @param {DateUnit} unit - The unit to subtract (e.g. 'day', 'month')
+     * @returns {DateTick} A new DateTick with the result
+     * @memberof DateTick
+     */
+    subtract(amount: number, unit: DateUnit): DateTick;
+    /**
+     * Returns a human-readable relative time string (e.g. '3 minutes ago')
+     *
+     * @param {Intl.RelativeTimeFormatOptions} [options] - Intl options
+     * @param {RelativeTimeThresholds} [thresholds] - Override the unit step-up cutoffs
+     * @returns {string} The relative time string
+     * @memberof DateTick
+     */
+    timeAgo(options?: Intl.RelativeTimeFormatOptions, thresholds?: RelativeTimeThresholds): string;
+    /**
+     * Returns a dependency-free live relative-time stream.
+     *
+     * Subscribers receive the current `timeAgo()` label immediately, then again whenever it is
+     * expected to change. The refresh rate adapts from every second to every hour as the target
+     * time moves farther away.
+     *
+     * @param {Intl.RelativeTimeFormatOptions} [options] - Intl options
+     * @param {RelativeTimeThresholds} [thresholds] - Override the unit step-up cutoffs
+     * @returns {TimeAgoLive} A live relative-time subscription handle
+     * @memberof DateTick
+     */
+    timeAgoLive(options?: Intl.RelativeTimeFormatOptions, thresholds?: RelativeTimeThresholds): TimeAgoLive;
+    /**
+     * Subscribes to live relative-time labels and returns an unsubscribe function.
+     *
+     * @param {TimeAgoListener} listener - Receives each formatted relative-time label
+     * @param {Intl.RelativeTimeFormatOptions} [options] - Intl options
+     * @param {RelativeTimeThresholds} [thresholds] - Override the unit step-up cutoffs
+     * @returns {() => void} Function that stops the live updates
+     * @memberof DateTick
+     */
+    timeAgoSubscribe(listener: TimeAgoListener, options?: Intl.RelativeTimeFormatOptions, thresholds?: RelativeTimeThresholds): () => void;
+    /**
+     * Gets the configured IANA timezone
+     *
+     * @returns {string} The timezone
+     * @memberof DateTick
+     */
+    timezone(): string;
+    /**
+     * Formats another date relative to this one, Day.js-style.
+     *
+     * @param {DateInput} date - The target date to compare to
+     * @param {boolean} [withoutSuffix=false] - When true, omit "ago" / "in"
+     * @returns {string} The relative-time label
+     * @memberof DateTick
+     */
+    to(date: DateInput, withoutSuffix?: boolean): string;
+    /**
+     * Converts the wrapped date to an array of zoned calendar parts.
+     *
+     * @returns {DateArray} [year, month, date, hour, minute, second, millisecond]
+     * @memberof DateTick
+     */
+    toArray(): Required<DateArray>;
+    /**
+     * Converts the wrapped date to a plain Date object (a fresh clone of the absolute instant)
+     *
+     * @returns {Date} The Date object
+     * @memberof DateTick
+     */
+    toDate(): Date;
+    /**
+     * Converts the wrapped date to an ISO 8601 string (UTC)
+     *
+     * @returns {string} The ISO 8601 string
+     * @memberof DateTick
+     */
+    toISOString(): string;
+    /**
+     * Enables `JSON.stringify` to serialize a DateTick as an ISO 8601 string
+     *
+     * @returns {string} The ISO 8601 string
+     * @memberof DateTick
+     */
+    toJSON(): string;
+    /**
+     * Formats now relative to this date, Day.js-style.
+     *
+     * @param {boolean} [withoutSuffix=false] - When true, omit "ago" / "in"
+     * @returns {string} The relative-time label
+     * @memberof DateTick
+     */
+    toNow(withoutSuffix?: boolean): string;
+    /**
+     * Converts the wrapped date to an object of zoned calendar parts.
+     *
+     * @returns {DatePartsObject} Zoned calendar parts
+     * @memberof DateTick
+     */
+    toObject(): DatePartsObject;
+    /**
+     * Converts the wrapped date to its default string representation
+     *
+     * @returns {string} The string representation
+     * @memberof DateTick
+     */
+    toString(): string;
+    /**
+     * Gets the Unix timestamp (seconds since epoch)
+     *
+     * @returns {number} The Unix timestamp in seconds
+     * @memberof DateTick
+     */
+    unix(): number;
+    /**
+     * Returns a new DateTick in UTC, keeping the same instant.
+     *
+     * @returns {DateTick} The UTC instance
+     * @memberof DateTick
+     */
+    utc(): DateTick;
+    /**
+     * Gets the configured timezone's UTC offset for this instant, in minutes.
+     *
+     * @returns {number} Offset minutes, positive east of UTC
+     * @memberof DateTick
+     */
+    utcOffset(): number;
+    /**
+     * Gets the timestamp in milliseconds since epoch. Enables direct numeric comparisons (e.g. `+datetick`)
+     *
+     * @returns {number} The timestamp in milliseconds
+     * @memberof DateTick
+     */
+    valueOf(): number;
+    /**
+     * Gets the week number of the year (in the configured timezone)
+     *
+     * @returns {number} The week number
+     * @memberof DateTick
+     */
+    week(): number;
+    /**
+     * Gets the configured first day of the week (0 = Sunday … 6 = Saturday)
+     *
+     * @returns {number} The first day of the week
+     * @memberof DateTick
+     */
+    weekStart(): number;
+    /**
+     * Gets the week year, for ISO week calculations (in the configured timezone)
+     *
+     * @returns {number} The week year
+     * @memberof DateTick
+     */
+    weekYear(): number;
+    /**
+     * Gets or sets the day of the week relative to the configured first day of the week
+     * (0 = first day of the week … 6 = last day), in the configured timezone.
+     *
+     * Unlike {@link DateTick.day}, which is always Sunday-based, this respects `weekStartsOn`.
+     *
+     * @param {number} [value] - The relative day of the week to set
+     * @returns {number | DateTick} The relative day of the week, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    weekday(): number;
+    weekday(value: number): DateTick;
+    /** Day.js-style plural getter alias of {@link DateTick.week} (weeks have no setter). */
+    weeks(): number;
+    /**
+     * Gets the number of weeks in the year (in the configured timezone)
+     *
+     * @returns {number} The number of weeks
+     * @memberof DateTick
+     */
+    weeksInYear(): number;
+    /**
+     * Returns a new DateTick instance with the given date, keeping the current locale and timezone
+     *
+     * @param {Date | string} date - The date to wrap
+     * @returns {DateTick} The new DateTick
+     * @memberof DateTick
+     */
+    withDate(date: DateInput): DateTick;
+    /**
+     * Returns a new DateTick instance with the given locale, keeping the current instant and timezone
+     *
+     * @param {string} locale - The BCP 47 locale
+     * @returns {DateTick} The new DateTick
+     * @memberof DateTick
+     */
+    withLocale(locale: string): DateTick;
+    /**
+     * Returns a new DateTick instance with the given timezone, keeping the same absolute instant
+     * (the wall-clock components will be re-interpreted in the new zone)
+     *
+     * @param {string} timezone - The IANA timezone
+     * @returns {DateTick} The new DateTick
+     * @memberof DateTick
+     */
+    withTimezone(timezone: string): DateTick;
+    /**
+     * Returns a new DateTick instance with the given first-day-of-week, keeping everything else
+     *
+     * @param {number} weekStartsOn - First day of the week (0 = Sunday … 6 = Saturday)
+     * @returns {DateTick} The new DateTick
+     * @memberof DateTick
+     */
+    withWeekStart(weekStartsOn: number): DateTick;
+    /**
+     * Gets or sets the year (in the configured timezone)
+     *
+     * @param {number} [value] - The year to set
+     * @returns {number | DateTick} The year, or a new DateTick when setting
+     * @memberof DateTick
+     */
+    year(): number;
+    year(value: number): DateTick;
+    /** Day.js-style plural alias of {@link DateTick.year}. */
+    years(): number;
+    years(value: number): DateTick;
+    /**
+     * Adds calendar months (used for month/quarter/year), clamping the day to the last valid day.
+     */
+    private addMonths;
+    private calendarDayNumber;
+    /**
+     * Returns a preset Intl.DateTimeFormatOptions for a given format string.
+     */
+    private getPreset;
+    /**
+     * The Thursday of this instant's ISO week, as a UTC date built from the zoned calendar date so the
+     * math is offset-free. Shared by {@link DateTick.isoWeek} and {@link DateTick.weekYear}.
+     */
+    private isoThursday;
+    /**
+     * Creates an adaptive live relative-time stream.
+     */
+    private liveRelativeTime;
+    /**
+     * Formats the timezone's current offset from UTC as ±HH:mm (with colon) or ±HHmm (without).
+     */
+    private offsetString;
+    /**
+     * Applies the configured ordinal override, falling back to the English suffix.
+     */
+    private ordinalFor;
+    /**
+     * Reads the wrapped instant's wall-clock components in the configured timezone.
+     */
+    private parts;
+    /**
+     * Floating-point calendar-unit difference (used by `diff` when `precise` is true).
+     *
+     * Computes the whole-unit count, then interpolates the fractional remainder between the
+     * instant `whole` units away from `other` and the next unit boundary in the direction of `this`.
+     */
+    private preciseCalendarDiff;
+    /**
+     * Returns a new DateTick built from the current zoned components with the given overrides applied,
+     * then converted back to an absolute instant in the configured timezone.
+     */
+    private rebuild;
+    /**
+     * Normalizes a DateInput (Date, string, or DateTick) to a plain Date
+     */
+    private toComparable;
+    /**
+     * Validates a date and throws an error if invalid
+     */
+    private validateDate;
+    /**
+     * Number of weeks in this instant's year, per the given week-numbering function: Dec 31 usually
+     * carries the highest week number, unless it rolls into week 1 of the next year (then Dec 24 does).
+     * Shared by {@link DateTick.weeksInYear} and {@link DateTick.isoWeeksInYear}.
+     */
+    private weeksInYearBy;
+    /**
+     * Whole calendar-month difference (in units of `unitMonths` months), truncated toward zero.
+     */
+    private wholeMonthDiff;
+}
+
+/**
+ * Options accepted by the {@link datetick} factory and {@link DateTickFactory.withDefaults}.
+ */
+interface DateTickOptions {
+    /** BCP 47 locale used for formatting (default 'en'). */
+    locale?: string;
+    /** IANA timezone all calendar operations resolve through (default: the runtime timezone). */
+    timezone?: string;
+    /** First day of the week, 0 = Sunday … 6 = Saturday (default 0). */
+    weekStartsOn?: number;
+    /** Overrides the English ordinal used by `ordinal()` and the `Do`/`wo`/`Wo` tokens. */
+    ordinal?: OrdinalFn;
+}
+/**
+ * The callable factory plus its attached static helpers.
+ */
+interface DateTickFactory {
+    /**
+     * Creates a {@link DateTick} from a date input.
+     *
+     * @param date - A Date, ISO/parsable string, DateTick, date parts object, or date parts array (defaults to now)
+     * @param options - locale / timezone / weekStartsOn overrides (merged over this factory's defaults)
+     */
+    (date?: DateInput, options?: DateTickOptions): DateTick;
+    /** Creates a {@link Duration}, using this factory's default locale unless overridden. */
+    duration(value: number | string | DurationInput, unit?: DateUnit, locale?: string): Duration;
+    /** See {@link DateTick.guessTimezone}. */
+    guessTimezone: typeof DateTick.guessTimezone;
+    /** Parses a string into a DateTick, using this factory's default locale/timezone unless overridden. */
+    parse(input: string, pattern: string, locale?: string, timezone?: string): DateTick;
+    /** See {@link DateTick.min}. */
+    min: typeof DateTick.min;
+    /** See {@link DateTick.max}. */
+    max: typeof DateTick.max;
+    /** See {@link DateTick.isValid}. */
+    isValid: typeof DateTick.isValid;
+    /** See {@link DateTick.isDateTick}. */
+    isDateTick: typeof DateTick.isDateTick;
+    /** See {@link Duration.isDuration}. */
+    isDuration: typeof Duration.isDuration;
+    /** Shorthand for `datetick(date, { ...options, timezone: 'UTC' })`. */
+    utc(date?: DateInput, options?: Omit<DateTickOptions, 'timezone'>): DateTick;
+    /** Creates a DateTick from a Unix timestamp in seconds. */
+    unix(seconds: number, options?: DateTickOptions): DateTick;
+    /**
+     * Returns a new, independent factory pre-bound to the given defaults, merged over this
+     * factory's own defaults. Does not mutate this factory or any global state — every part of
+     * an app that wants the same defaults imports the same scoped factory instance.
+     *
+     * @example
+     * const frDateTick = datetick.withDefaults({ locale: 'fr', timezone: 'Europe/Paris' });
+     * frDateTick('2026-06-25').format('long'); // French, Paris
+     * datetick('2026-06-25').format('long'); // unaffected, still 'en' / runtime timezone
+     */
+    withDefaults(defaults: DateTickOptions): DateTickFactory;
+}
+/**
+ * The quickest way to create a {@link DateTick}.
+ *
+ * @example
+ * datetick('2026-06-25T19:23Z', { timezone: 'Asia/Tokyo' }).formatPattern('DD/MM/YYYY HH:mm');
+ * datetick.duration(90, 'minute').humanize(); // '2 hours'
+ * datetick.utc('2026-06-25').startOf('week');
+ */
+declare const datetick: DateTickFactory;
+
+export { DateTick, Duration, datetick, datetick as default };
+export type { CalendarDate, CalendarDiffUnit, CalendarDisplayFormats, CalendarMonth, CalendarMonthOptions, CalendarWeekday, DateArray, DateFormatPreset, DateGettableUnit, DateInput, DateObject, DatePartsObject, DateTickFactory, DateTickOptions, DateUnit, DurationInput, Inclusivity, LocaleData, OrdinalFn, RelativeTimeThresholds, TimeAgoListener, TimeAgoLive };