ts-time-utils 3.0.4 → 4.0.1

package/dist/esm/locale.d.ts

@@ -91,4 +91,57 @@ export declare function compareLocaleFormats(locale1: SupportedLocale, locale2:
         locale2: number;
     };
 };
+/**
+ * Get week information for a locale
+ * @param locale - locale code
+ * @returns Object with firstDay, weekend days, and minimalDays
+ */
+export declare function getWeekInfo(locale: SupportedLocale): {
+    firstDay: number;
+    weekend: number[];
+    minimalDays: number;
+};
+/**
+ * Get the day the week starts on for a locale
+ * @param locale - locale code
+ * @returns 0-6 (0 = Sunday, 1 = Monday, etc.)
+ */
+export declare function getLocaleWeekStartsOn(locale: SupportedLocale): number;
+/**
+ * Get the weekend days for a locale
+ * @param locale - locale code
+ * @returns Array of day numbers (0 = Sunday, 6 = Saturday)
+ */
+export declare function getLocaleWeekendDays(locale: SupportedLocale): number[];
+/**
+ * Thin wrapper around Intl.DateTimeFormat
+ * @param date - date to format
+ * @param options - Intl.DateTimeFormatOptions
+ * @param locale - locale string (defaults to system locale)
+ */
+export declare function intlFormat(date: Date, options?: Intl.DateTimeFormatOptions, locale?: string): string;
+/**
+ * Format only the date part in ISO format (YYYY-MM-DD)
+ * @param date - date to format
+ */
+export declare function formatISODate(date: Date): string;
+/**
+ * Format only the time part in ISO format (HH:mm:ss)
+ * @param date - date to format
+ * @param includeMs - include milliseconds
+ */
+export declare function formatISOTime(date: Date, includeMs?: boolean): string;
+/**
+ * Format distance between two dates without approximation words like "about" or "almost"
+ * Returns exact values like "5 days" instead of "about 5 days"
+ * @param date - the date
+ * @param baseDate - the base date to compare against (defaults to now)
+ * @param options - formatting options
+ */
+export declare function formatDistanceStrict(date: Date, baseDate?: Date, options?: {
+    locale?: SupportedLocale;
+    unit?: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
+    roundingMethod?: 'floor' | 'ceil' | 'round';
+    addSuffix?: boolean;
+}): string;
 //# sourceMappingURL=locale.d.ts.map

package/dist/esm/locale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/locale.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/locale.ts"],"names":[],"mappings":"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"}

package/dist/esm/locale.js

@@ -1085,3 +1085,144 @@ function tryParseWithPattern(dateString, pattern, config) {
     const isoDate = new Date(dateString);
     return isNaN(isoDate.getTime()) ? null : isoDate;
 }
+// ========================================
+// WEEK INFO UTILITIES
+// ========================================
+/**
+ * Get week information for a locale
+ * @param locale - locale code
+ * @returns Object with firstDay, weekend days, and minimalDays
+ */
+export function getWeekInfo(locale) {
+    const config = getLocaleConfig(locale);
+    const firstDay = config.calendar?.weekStartsOn ?? 0;
+    // Most locales use Saturday-Sunday weekend
+    // Some Middle Eastern locales use Friday-Saturday
+    const middleEasternLocales = ['ar', 'fa', 'he', 'ur'];
+    const baseLang = locale.split('-')[0];
+    const weekend = middleEasternLocales.includes(baseLang) ? [5, 6] : [6, 0];
+    // Minimal days in first week (ISO = 4, US = 1)
+    const minimalDays = firstDay === 1 ? 4 : 1;
+    return { firstDay, weekend, minimalDays };
+}
+/**
+ * Get the day the week starts on for a locale
+ * @param locale - locale code
+ * @returns 0-6 (0 = Sunday, 1 = Monday, etc.)
+ */
+export function getLocaleWeekStartsOn(locale) {
+    const config = getLocaleConfig(locale);
+    return config.calendar?.weekStartsOn ?? 0;
+}
+/**
+ * Get the weekend days for a locale
+ * @param locale - locale code
+ * @returns Array of day numbers (0 = Sunday, 6 = Saturday)
+ */
+export function getLocaleWeekendDays(locale) {
+    const middleEasternLocales = ['ar', 'fa', 'he', 'ur'];
+    const baseLang = locale.split('-')[0];
+    return middleEasternLocales.includes(baseLang) ? [5, 6] : [6, 0];
+}
+/**
+ * Thin wrapper around Intl.DateTimeFormat
+ * @param date - date to format
+ * @param options - Intl.DateTimeFormatOptions
+ * @param locale - locale string (defaults to system locale)
+ */
+export function intlFormat(date, options, locale) {
+    return new Intl.DateTimeFormat(locale, options).format(date);
+}
+/**
+ * Format only the date part in ISO format (YYYY-MM-DD)
+ * @param date - date to format
+ */
+export function formatISODate(date) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Format only the time part in ISO format (HH:mm:ss)
+ * @param date - date to format
+ * @param includeMs - include milliseconds
+ */
+export function formatISOTime(date, includeMs = false) {
+    const hours = String(date.getHours()).padStart(2, '0');
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    const seconds = String(date.getSeconds()).padStart(2, '0');
+    if (includeMs) {
+        const ms = String(date.getMilliseconds()).padStart(3, '0');
+        return `${hours}:${minutes}:${seconds}.${ms}`;
+    }
+    return `${hours}:${minutes}:${seconds}`;
+}
+/**
+ * Format distance between two dates without approximation words like "about" or "almost"
+ * Returns exact values like "5 days" instead of "about 5 days"
+ * @param date - the date
+ * @param baseDate - the base date to compare against (defaults to now)
+ * @param options - formatting options
+ */
+export function formatDistanceStrict(date, baseDate = new Date(), options = {}) {
+    const { locale = 'en', unit, roundingMethod = 'round', addSuffix = false } = options;
+    const config = getLocaleConfig(locale);
+    const diffMs = date.getTime() - baseDate.getTime();
+    const absDiffMs = Math.abs(diffMs);
+    const isPast = diffMs < 0;
+    const roundFn = roundingMethod === 'floor' ? Math.floor
+        : roundingMethod === 'ceil' ? Math.ceil
+            : Math.round;
+    // Unit definitions in ms
+    const units = {
+        second: 1000,
+        minute: 60 * 1000,
+        hour: 60 * 60 * 1000,
+        day: 24 * 60 * 60 * 1000,
+        week: 7 * 24 * 60 * 60 * 1000,
+        month: 30.44 * 24 * 60 * 60 * 1000,
+        year: 365.25 * 24 * 60 * 60 * 1000
+    };
+    let selectedUnit = unit;
+    let value;
+    if (selectedUnit) {
+        value = roundFn(absDiffMs / units[selectedUnit]);
+    }
+    else {
+        // Auto-select unit based on duration
+        if (absDiffMs < units.minute) {
+            selectedUnit = 'second';
+        }
+        else if (absDiffMs < units.hour) {
+            selectedUnit = 'minute';
+        }
+        else if (absDiffMs < units.day) {
+            selectedUnit = 'hour';
+        }
+        else if (absDiffMs < units.week) {
+            selectedUnit = 'day';
+        }
+        else if (absDiffMs < units.month) {
+            selectedUnit = 'week';
+        }
+        else if (absDiffMs < units.year) {
+            selectedUnit = 'month';
+        }
+        else {
+            selectedUnit = 'year';
+        }
+        value = roundFn(absDiffMs / units[selectedUnit]);
+    }
+    // Get unit text
+    const unitKey = (value === 1 ? selectedUnit : selectedUnit + 's');
+    const unitText = config.relativeTime?.units?.[unitKey] || unitKey;
+    const result = `${value} ${unitText}`;
+    if (addSuffix) {
+        const template = isPast
+            ? (config.relativeTime?.past || '{0} ago')
+            : (config.relativeTime?.future || 'in {0}');
+        return template.replace('{0}', result);
+    }
+    return result;
+}

package/dist/esm/precision.d.ts

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview High-precision time utilities
+ * Handles nanoseconds, BigInt timestamps, sub-millisecond operations
+ */
+/**
+ * Nanosecond precision timestamp
+ * Uses BigInt for precision beyond milliseconds
+ */
+export interface NanosecondTimestamp {
+    readonly milliseconds: number;
+    readonly nanoseconds: number;
+    readonly totalNanoseconds: bigint;
+}
+/**
+ * High-resolution duration with nanosecond precision
+ */
+export interface HighResDuration {
+    readonly seconds: number;
+    readonly nanoseconds: number;
+}
+/**
+ * Create a nanosecond timestamp from components
+ */
+export declare function createNanosecondTimestamp(milliseconds: number, nanoseconds?: number): NanosecondTimestamp;
+/**
+ * Create a nanosecond timestamp from BigInt
+ */
+export declare function fromNanoseconds(totalNs: bigint): NanosecondTimestamp;
+/**
+ * Create a nanosecond timestamp from a Date
+ */
+export declare function dateToNanoseconds(date: Date): NanosecondTimestamp;
+/**
+ * Convert nanosecond timestamp to Date (loses sub-millisecond precision)
+ */
+export declare function nanosecondsToDate(timestamp: NanosecondTimestamp): Date;
+/**
+ * Add two nanosecond timestamps
+ */
+export declare function addNanoseconds(a: NanosecondTimestamp, b: NanosecondTimestamp): NanosecondTimestamp;
+/**
+ * Subtract nanosecond timestamps
+ */
+export declare function subtractNanoseconds(a: NanosecondTimestamp, b: NanosecondTimestamp): NanosecondTimestamp;
+/**
+ * Compare nanosecond timestamps
+ * @returns -1 if a < b, 0 if equal, 1 if a > b
+ */
+export declare function compareNanoseconds(a: NanosecondTimestamp, b: NanosecondTimestamp): -1 | 0 | 1;
+/**
+ * Get current time with nanosecond precision (if available)
+ * Falls back to millisecond precision if performance.now() not available
+ */
+export declare function nowNanoseconds(): NanosecondTimestamp;
+/**
+ * Format nanosecond timestamp to ISO string with sub-millisecond precision
+ */
+export declare function formatNanoseconds(timestamp: NanosecondTimestamp): string;
+/**
+ * Parse ISO string with nanosecond precision
+ */
+export declare function parseNanoseconds(isoString: string): NanosecondTimestamp | null;
+/**
+ * Create a high-resolution duration
+ */
+export declare function createHighResDuration(seconds: number, nanoseconds?: number): HighResDuration;
+/**
+ * Add two high-resolution durations
+ */
+export declare function addHighResDuration(a: HighResDuration, b: HighResDuration): HighResDuration;
+/**
+ * Subtract high-resolution durations
+ */
+export declare function subtractHighResDuration(a: HighResDuration, b: HighResDuration): HighResDuration;
+/**
+ * Convert high-resolution duration to milliseconds
+ */
+export declare function highResDurationToMs(duration: HighResDuration): number;
+/**
+ * Convert milliseconds to high-resolution duration
+ */
+export declare function msToHighResDuration(ms: number): HighResDuration;
+/**
+ * Convert Unix epoch milliseconds to BigInt
+ */
+export declare function toBigIntMs(date: Date): bigint;
+/**
+ * Convert BigInt milliseconds to Date
+ */
+export declare function fromBigIntMs(ms: bigint): Date;
+/**
+ * Convert Unix epoch seconds to BigInt
+ */
+export declare function toBigIntSeconds(date: Date): bigint;
+/**
+ * Convert BigInt seconds to Date
+ */
+export declare function fromBigIntSeconds(seconds: bigint): Date;
+/**
+ * Add milliseconds (as BigInt) to a date
+ */
+export declare function addBigIntMs(date: Date, ms: bigint): Date;
+/**
+ * Subtract milliseconds (as BigInt) from a date
+ */
+export declare function subtractBigIntMs(date: Date, ms: bigint): Date;
+/**
+ * Calculate difference between dates in BigInt milliseconds
+ */
+export declare function diffBigIntMs(a: Date, b: Date): bigint;
+/**
+ * DST transition info
+ */
+export interface DSTTransition {
+    /** Transition date/time (UTC) */
+    readonly utc: Date;
+    /** Transition date/time (local) */
+    readonly local: Date;
+    /** Whether transitioning to DST */
+    readonly toDST: boolean;
+    /** Offset before transition (minutes) */
+    readonly offsetBefore: number;
+    /** Offset after transition (minutes) */
+    readonly offsetAfter: number;
+    /** Gap or overlap duration (minutes) */
+    readonly adjustmentMinutes: number;
+}
+/**
+ * Check if a date falls in a DST transition gap (skipped time)
+ * @param date - Date to check
+ * @param timeZone - IANA timezone (optional, uses local if not provided)
+ */
+export declare function isInDSTGap(date: Date, timeZone?: string): boolean;
+/**
+ * Check if a date falls in a DST overlap (ambiguous time)
+ * @param date - Date to check
+ * @param timeZone - IANA timezone (optional, uses local if not provided)
+ */
+export declare function isInDSTOverlap(date: Date, timeZone?: string): boolean;
+/**
+ * Find DST transitions in a year for local timezone
+ */
+export declare function getDSTTransitionsInYear(year: number): DSTTransition[];
+/**
+ * Resolve ambiguous time in DST overlap
+ * @param date - Potentially ambiguous date
+ * @param prefer - Prefer 'earlier' or 'later' interpretation
+ */
+export declare function resolveAmbiguousTime(date: Date, prefer?: 'earlier' | 'later'): Date;
+/**
+ * Validated Date wrapper that guarantees a valid date
+ */
+export declare class ValidDate {
+    private readonly _date;
+    private constructor();
+    /**
+     * Create a ValidDate, throws if invalid
+     */
+    static from(date: Date): ValidDate;
+    /**
+     * Create a ValidDate, returns null if invalid
+     */
+    static tryFrom(date: Date): ValidDate | null;
+    /**
+     * Create from timestamp, throws if invalid
+     */
+    static fromTimestamp(ms: number): ValidDate;
+    /**
+     * Create from ISO string, throws if invalid
+     */
+    static fromISO(isoString: string): ValidDate;
+    /**
+     * Get the underlying Date object
+     */
+    get value(): Date;
+    /**
+     * Get timestamp
+     */
+    get time(): number;
+    /**
+     * Format to ISO string
+     */
+    toISOString(): string;
+    /**
+     * Format to locale string
+     */
+    toLocaleString(locale?: string, options?: Intl.DateTimeFormatOptions): string;
+}
+/**
+ * Ensure a date is valid, with fallback
+ */
+export declare function ensureValidDate(date: Date, fallback?: Date): Date;
+/**
+ * Parse date with validation
+ */
+export declare function parseValidDate(input: string | number | Date): Date | null;
+/**
+ * Assert date is valid, throws if not
+ */
+export declare function assertValidDate(date: Date, message?: string): asserts date is Date & {
+    getTime(): number;
+};
+/**
+ * Known leap seconds (added at end of these dates, 23:59:60 UTC)
+ * List from https://www.ietf.org/timezones/data/leap-seconds.list
+ */
+export declare const LEAP_SECONDS: readonly Date[];
+/**
+ * Get number of leap seconds between two dates
+ */
+export declare function leapSecondsBetween(start: Date, end: Date): number;
+/**
+ * Check if a date is near a leap second (within 1 second)
+ */
+export declare function isNearLeapSecond(date: Date): boolean;
+/**
+ * Convert TAI (International Atomic Time) to UTC
+ * TAI = UTC + accumulated leap seconds + 10 (initial offset)
+ */
+export declare function taiToUtc(taiMs: number): Date;
+/**
+ * Convert UTC to TAI
+ */
+export declare function utcToTai(date: Date): number;
+//# sourceMappingURL=precision.d.ts.map

package/dist/esm/precision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precision.d.ts","sourceRoot":"","sources":["../../src/precision.ts"],"names":[],"mappings":"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"}