chronos-ts 1.0.3 → 2.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,428 @@
+/**
+ * Core type definitions for Chronos
+ * @module types
+ */
+/**
+ * All supported time units in the library
+ */
+export type TimeUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'decade' | 'century' | 'millennium';
+/**
+ * Plural forms of time units
+ */
+export type TimeUnitPlural = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'quarters' | 'years' | 'decades' | 'centuries' | 'millennia';
+/**
+ * Short forms of time units
+ */
+export type TimeUnitShort = 'ms' | 's' | 'm' | 'h' | 'd' | 'w' | 'M' | 'Q' | 'y';
+/**
+ * Combined time unit type accepting any form
+ */
+export type AnyTimeUnit = TimeUnit | TimeUnitPlural | TimeUnitShort;
+/**
+ * Days of the week (0 = Sunday, 6 = Saturday)
+ */
+export 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)
+ */
+export 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
+ */
+export type DateInput = string | number | Date | ChronosLike | null | undefined;
+/**
+ * Interface for Chronos-like objects
+ */
+export interface ChronosLike {
+    toDate(): Date;
+    valueOf(): number;
+}
+/**
+ * Object representing individual date/time components
+ */
+export interface DateTimeComponents {
+    year?: number;
+    month?: number;
+    day?: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+}
+/**
+ * Object for setting date/time parts
+ */
+export interface DateTimeSetter {
+    year?: number;
+    month?: number;
+    date?: number;
+    day?: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    millisecond?: number;
+}
+/**
+ * Duration object for intervals
+ */
+export interface Duration {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+/**
+ * ISO 8601 duration string pattern
+ */
+export type ISODuration = string;
+/**
+ * Valid timezone input types
+ */
+export type TimezoneInput = string | number | TimezoneInfo;
+/**
+ * Timezone offset information
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export interface FormatTokens {
+    [key: string]: ((date: Date) => string) | string;
+}
+/**
+ * Predefined format presets
+ */
+export type FormatPreset = 'date' | 'time' | 'datetime' | 'iso' | 'rfc2822' | 'rfc3339' | 'atom' | 'cookie' | 'rss' | 'w3c';
+/**
+ * Comparison operators
+ */
+export type CompareOperator = '<' | '<=' | '=' | '>=' | '>' | '!=';
+/**
+ * Comparison granularity options
+ */
+export type CompareGranularity = TimeUnit | 'default';
+/**
+ * Period options for iteration
+ */
+export 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
+ */
+export declare enum PeriodBoundary {
+    Open = "open",
+    Closed = "closed",
+    OpenStart = "openStart",
+    OpenEnd = "openEnd"
+}
+/**
+ * Locale configuration
+ */
+export 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
+ */
+export 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
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Extract numeric keys from an object type
+ */
+export type NumericKeys<T> = {
+    [K in keyof T]: T[K] extends number ? K : never;
+}[keyof T];
+/**
+ * Type guard result
+ */
+export type TypeGuard<T> = (value: unknown) => value is T;
+/**
+ * Chainable method return type
+ */
+export type Chainable<T> = T & {
+    clone(): T;
+};
+/**
+ * Options for human-readable difference output
+ */
+export 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
+ */
+export 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
+ */
+export interface ChronosSerializable {
+    timestamp: number;
+    timezone: string;
+    offset: number;
+}
+/**
+ * JSON representation
+ */
+export interface ChronosJSON {
+    iso: string;
+    timestamp: number;
+    timezone: string;
+}
+/**
+ * Represents a time range/span
+ */
+export interface TimeRange {
+    start: Date;
+    end: Date;
+}
+/**
+ * Business hours configuration
+ */
+export interface BusinessHours {
+    open: {
+        hour: number;
+        minute: number;
+    };
+    close: {
+        hour: number;
+        minute: number;
+    };
+    days: DayOfWeek[];
+    holidays?: Date[];
+}
+/**
+ * Calendar week representation
+ */
+export interface CalendarWeek {
+    weekNumber: number;
+    year: number;
+    days: Date[];
+}
+/**
+ * Calendar month representation
+ */
+export interface CalendarMonth {
+    year: number;
+    month: number;
+    weeks: CalendarWeek[];
+}
+export declare const MILLISECONDS_PER_SECOND = 1000;
+export declare const SECONDS_PER_MINUTE = 60;
+export declare const MINUTES_PER_HOUR = 60;
+export declare const HOURS_PER_DAY = 24;
+export declare const DAYS_PER_WEEK = 7;
+export declare const MONTHS_PER_YEAR = 12;
+export declare const DAYS_PER_YEAR = 365;
+export declare const DAYS_PER_LEAP_YEAR = 366;
+export declare const MILLISECONDS_PER_MINUTE: number;
+export declare const MILLISECONDS_PER_HOUR: number;
+export declare const MILLISECONDS_PER_DAY: number;
+export declare const MILLISECONDS_PER_WEEK: number;
+export declare const AVERAGE_DAYS_PER_MONTH = 30.436875;
+export declare const AVERAGE_DAYS_PER_YEAR = 365.2425;
+export declare const MILLISECONDS_PER_MONTH: number;
+export declare const MILLISECONDS_PER_YEAR: number;

package/dist/types/index.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Core type definitions for Chronos
+ * @module types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MILLISECONDS_PER_YEAR = exports.MILLISECONDS_PER_MONTH = exports.AVERAGE_DAYS_PER_YEAR = exports.AVERAGE_DAYS_PER_MONTH = exports.MILLISECONDS_PER_WEEK = exports.MILLISECONDS_PER_DAY = exports.MILLISECONDS_PER_HOUR = exports.MILLISECONDS_PER_MINUTE = exports.DAYS_PER_LEAP_YEAR = exports.DAYS_PER_YEAR = exports.MONTHS_PER_YEAR = exports.DAYS_PER_WEEK = exports.HOURS_PER_DAY = exports.MINUTES_PER_HOUR = exports.SECONDS_PER_MINUTE = exports.MILLISECONDS_PER_SECOND = exports.PeriodBoundary = exports.Month = exports.DayOfWeek = void 0;
+// ============================================================================
+// Day of Week Types
+// ============================================================================
+/**
+ * Days of the week (0 = Sunday, 6 = Saturday)
+ */
+var DayOfWeek;
+(function (DayOfWeek) {
+    DayOfWeek[DayOfWeek["Sunday"] = 0] = "Sunday";
+    DayOfWeek[DayOfWeek["Monday"] = 1] = "Monday";
+    DayOfWeek[DayOfWeek["Tuesday"] = 2] = "Tuesday";
+    DayOfWeek[DayOfWeek["Wednesday"] = 3] = "Wednesday";
+    DayOfWeek[DayOfWeek["Thursday"] = 4] = "Thursday";
+    DayOfWeek[DayOfWeek["Friday"] = 5] = "Friday";
+    DayOfWeek[DayOfWeek["Saturday"] = 6] = "Saturday";
+})(DayOfWeek || (exports.DayOfWeek = DayOfWeek = {}));
+/**
+ * Months of the year (1 = January, 12 = December)
+ */
+var Month;
+(function (Month) {
+    Month[Month["January"] = 1] = "January";
+    Month[Month["February"] = 2] = "February";
+    Month[Month["March"] = 3] = "March";
+    Month[Month["April"] = 4] = "April";
+    Month[Month["May"] = 5] = "May";
+    Month[Month["June"] = 6] = "June";
+    Month[Month["July"] = 7] = "July";
+    Month[Month["August"] = 8] = "August";
+    Month[Month["September"] = 9] = "September";
+    Month[Month["October"] = 10] = "October";
+    Month[Month["November"] = 11] = "November";
+    Month[Month["December"] = 12] = "December";
+})(Month || (exports.Month = Month = {}));
+/**
+ * Period boundary options
+ */
+var PeriodBoundary;
+(function (PeriodBoundary) {
+    PeriodBoundary["Open"] = "open";
+    PeriodBoundary["Closed"] = "closed";
+    PeriodBoundary["OpenStart"] = "openStart";
+    PeriodBoundary["OpenEnd"] = "openEnd";
+})(PeriodBoundary || (exports.PeriodBoundary = PeriodBoundary = {}));
+// ============================================================================
+// Constants
+// ============================================================================
+exports.MILLISECONDS_PER_SECOND = 1000;
+exports.SECONDS_PER_MINUTE = 60;
+exports.MINUTES_PER_HOUR = 60;
+exports.HOURS_PER_DAY = 24;
+exports.DAYS_PER_WEEK = 7;
+exports.MONTHS_PER_YEAR = 12;
+exports.DAYS_PER_YEAR = 365;
+exports.DAYS_PER_LEAP_YEAR = 366;
+exports.MILLISECONDS_PER_MINUTE = exports.MILLISECONDS_PER_SECOND * exports.SECONDS_PER_MINUTE;
+exports.MILLISECONDS_PER_HOUR = exports.MILLISECONDS_PER_MINUTE * exports.MINUTES_PER_HOUR;
+exports.MILLISECONDS_PER_DAY = exports.MILLISECONDS_PER_HOUR * exports.HOURS_PER_DAY;
+exports.MILLISECONDS_PER_WEEK = exports.MILLISECONDS_PER_DAY * exports.DAYS_PER_WEEK;
+// Average values for variable-length units
+exports.AVERAGE_DAYS_PER_MONTH = 30.436875;
+exports.AVERAGE_DAYS_PER_YEAR = 365.2425;
+exports.MILLISECONDS_PER_MONTH = exports.MILLISECONDS_PER_DAY * exports.AVERAGE_DAYS_PER_MONTH;
+exports.MILLISECONDS_PER_YEAR = exports.MILLISECONDS_PER_DAY * exports.AVERAGE_DAYS_PER_YEAR;

package/dist/utils/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Utility functions for Chronos
+ * @module utils
+ */
+import { AnyTimeUnit, TimeUnit, Duration, DateInput, ChronosLike, MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR } from '../types';
+export { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR, };
+/**
+ * Check if value is a Date object
+ */
+export declare function isDate(value: unknown): value is Date;
+/**
+ * Check if value is a valid date input
+ */
+export declare function isValidDateInput(value: unknown): value is DateInput;
+/**
+ * Check if value implements ChronosLike interface
+ */
+export declare function isChronosLike(value: unknown): value is ChronosLike;
+/**
+ * Check if value is a Duration object
+ */
+export declare function isDuration(value: unknown): value is Duration;
+/**
+ * Check if value is a valid ISO 8601 duration string
+ */
+export declare function isISODuration(value: unknown): value is string;
+/**
+ * Check if a year is a leap year
+ */
+export declare function isLeapYear(year: number): boolean;
+/**
+ * Normalize a time unit to its canonical form
+ */
+export declare function normalizeUnit(unit: AnyTimeUnit | string): TimeUnit;
+/**
+ * Get the plural form of a time unit
+ */
+export declare function pluralizeUnit(unit: TimeUnit, count: number): string;
+/**
+ * Get milliseconds for a given time unit
+ */
+export declare function getMillisecondsPerUnit(unit: TimeUnit): number;
+/**
+ * Get the number of days in a specific month
+ */
+export declare function getDaysInMonth(year: number, month: number): number;
+/**
+ * Get the number of days in a year
+ */
+export declare function getDaysInYear(year: number): number;
+/**
+ * Get the day of year (1-366)
+ */
+export declare function getDayOfYear(date: Date): number;
+/**
+ * Get the ISO week number (1-53)
+ */
+export declare function getISOWeek(date: Date): number;
+/**
+ * Get the ISO week year
+ */
+export declare function getISOWeekYear(date: Date): number;
+/**
+ * Get the quarter (1-4)
+ */
+export declare function getQuarter(date: Date): number;
+/**
+ * Get start of a time unit
+ */
+export declare function startOf(date: Date, unit: TimeUnit): Date;
+/**
+ * Get end of a time unit
+ */
+export 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
+ */
+export declare function addDuration(date: Date, duration: Duration): Date;
+/**
+ * Subtract a duration from a date
+ */
+export declare function subtractDuration(date: Date, duration: Duration): Date;
+/**
+ * Add a specific number of units to a date
+ */
+export declare function addUnits(date: Date, amount: number, unit: TimeUnit): Date;
+/**
+ * Calculate the difference between two dates in a specific unit
+ */
+export declare function diffInUnits(date1: Date, date2: Date, unit: TimeUnit): number;
+/**
+ * Parse an ISO 8601 duration string
+ */
+export declare function parseISODuration(duration: string): Duration;
+/**
+ * Convert a duration to ISO 8601 format
+ */
+export declare function durationToISO(duration: Duration): string;
+/**
+ * Compare two dates at a specific granularity
+ */
+export declare function compareAtGranularity(date1: Date, date2: Date, unit: TimeUnit): number;
+/**
+ * Check if two dates are the same at a specific granularity
+ */
+export declare function isSameAt(date1: Date, date2: Date, unit: TimeUnit): boolean;
+/**
+ * Create a deep clone of a date
+ */
+export declare function cloneDate(date: Date): Date;
+/**
+ * Check if a date is valid
+ */
+export declare function isValidDate(date: Date): boolean;
+/**
+ * Ensure a value is within bounds
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Get ordinal suffix for a number (1st, 2nd, 3rd, etc.)
+ */
+export declare function ordinalSuffix(n: number): string;
+/**
+ * Pad a number with leading zeros
+ */
+export declare function padStart(value: number | string, length: number, char?: string): string;