chronos-ts/dist/utils/index.d.ts

A comprehensive TypeScript library for date and time manipulation, inspired by Carbon PHP. Features immutable API, intervals, periods, timezones, and i18n support.

/**
 * 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;