ts-time-utils 0.0.1 → 1.1.0

package/dist/serialize.js

@@ -0,0 +1,365 @@
+/**
+ * Safe JSON date serialization and deserialization utilities
+ */
+/**
+ * Safely serialize a date to JSON with various format options
+ */
+export function serializeDate(date, options = {}) {
+    const { format = 'iso', includeTimezone = false, useUTC = false, precision = 'milliseconds', customFormat } = options;
+    const dateObj = normalizeDate(date);
+    if (!dateObj) {
+        throw new Error('Invalid date provided for serialization');
+    }
+    const workingDate = useUTC ? new Date(dateObj.getTime()) : dateObj;
+    switch (format) {
+        case 'iso':
+            return workingDate.toISOString();
+        case 'epoch':
+            return toEpochTimestamp(workingDate, precision);
+        case 'object':
+            return toDateObject(workingDate, includeTimezone);
+        case 'custom':
+            if (!customFormat) {
+                throw new Error('Custom format string required when format is "custom"');
+            }
+            return formatCustom(workingDate, customFormat);
+        default:
+            return workingDate.toISOString();
+    }
+}
+/**
+ * Safely deserialize a date from various formats
+ */
+export function deserializeDate(serializedDate, options = {}) {
+    const { useUTC = false } = options;
+    try {
+        if (typeof serializedDate === 'string') {
+            return parseISOString(serializedDate, useUTC);
+        }
+        if (typeof serializedDate === 'number') {
+            if (isNaN(serializedDate)) {
+                return null;
+            }
+            return fromEpochTimestamp(serializedDate, options.precision || 'milliseconds');
+        }
+        if (typeof serializedDate === 'object' && serializedDate !== null) {
+            try {
+                return fromDateObject(serializedDate);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * Create a safe JSON reviver function for automatic date parsing
+ */
+export function createDateReviver(dateKeys = ['createdAt', 'updatedAt', 'date', 'timestamp'], options = {}) {
+    return (key, value) => {
+        if (dateKeys.includes(key) && (typeof value === 'string' || typeof value === 'number')) {
+            const parsed = deserializeDate(value, options);
+            return parsed || value; // Return original value if parsing fails
+        }
+        return value;
+    };
+}
+/**
+ * Create a safe JSON replacer function for automatic date serialization
+ */
+export function createDateReplacer(dateKeys = ['createdAt', 'updatedAt', 'date', 'timestamp'], options = {}) {
+    return (key, value) => {
+        if (dateKeys.includes(key)) {
+            if (value instanceof Date) {
+                return serializeDate(value, options);
+            }
+            // Handle case where Date was already converted to ISO string by JSON.stringify
+            if (typeof value === 'string' && isValidISODateString(value)) {
+                const date = parseISOString(value);
+                if (date) {
+                    return serializeDate(date, options);
+                }
+            }
+        }
+        return value;
+    };
+}
+/**
+ * Parse ISO string with better error handling
+ */
+export function parseISOString(isoString, useUTC = false) {
+    if (!isoString || typeof isoString !== 'string') {
+        return null;
+    }
+    // Handle various ISO formats
+    const cleanedString = isoString.trim();
+    // Check for valid ISO format
+    const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z?$/;
+    if (!isoRegex.test(cleanedString)) {
+        // Try to parse anyway, but be more forgiving
+        const relaxedRegex = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})?)?$/;
+        if (!relaxedRegex.test(cleanedString)) {
+            return null;
+        }
+    }
+    try {
+        const date = new Date(cleanedString);
+        if (isNaN(date.getTime())) {
+            return null;
+        }
+        return useUTC ? new Date(date.getTime() + (date.getTimezoneOffset() * 60000)) : date;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Convert date to epoch timestamp with specified precision
+ */
+export function toEpochTimestamp(date, precision = 'milliseconds') {
+    const dateObj = normalizeDate(date);
+    if (!dateObj) {
+        throw new Error('Invalid date provided for epoch conversion');
+    }
+    const ms = dateObj.getTime();
+    switch (precision) {
+        case 'seconds':
+            return Math.floor(ms / 1000);
+        case 'microseconds':
+            return ms * 1000; // JavaScript doesn't have true microsecond precision
+        case 'milliseconds':
+        default:
+            return ms;
+    }
+}
+/**
+ * Create date from epoch timestamp with specified precision
+ */
+export function fromEpochTimestamp(timestamp, precision = 'milliseconds') {
+    let ms;
+    switch (precision) {
+        case 'seconds':
+            ms = timestamp * 1000;
+            break;
+        case 'microseconds':
+            ms = timestamp / 1000;
+            break;
+        case 'milliseconds':
+        default:
+            ms = timestamp;
+            break;
+    }
+    return new Date(ms);
+}
+/**
+ * Create epoch timestamp with metadata
+ */
+export function createEpochTimestamp(date, precision = 'milliseconds', timezone) {
+    return {
+        timestamp: toEpochTimestamp(date, precision),
+        precision,
+        timezone
+    };
+}
+/**
+ * Convert date to safe object representation
+ */
+export function toDateObject(date, includeTimezone = false) {
+    const dateObj = normalizeDate(date);
+    if (!dateObj) {
+        throw new Error('Invalid date provided for object conversion');
+    }
+    const obj = {
+        year: dateObj.getUTCFullYear(),
+        month: dateObj.getUTCMonth() + 1, // Convert to 1-12
+        day: dateObj.getUTCDate(),
+        hour: dateObj.getUTCHours(),
+        minute: dateObj.getUTCMinutes(),
+        second: dateObj.getUTCSeconds(),
+        millisecond: dateObj.getUTCMilliseconds()
+    };
+    if (includeTimezone) {
+        // Get timezone offset in minutes and convert to string format
+        const offset = dateObj.getTimezoneOffset();
+        const hours = Math.floor(Math.abs(offset) / 60);
+        const minutes = Math.abs(offset) % 60;
+        const sign = offset <= 0 ? '+' : '-';
+        obj.timezone = `${sign}${hours.toString().padStart(2, '0')}:${minutes.toString().padStart(2, '0')}`;
+    }
+    return obj;
+}
+/**
+ * Create date from object representation
+ */
+export function fromDateObject(dateObj) {
+    // Validate required fields
+    if (!dateObj || typeof dateObj !== 'object') {
+        throw new Error('Invalid date object provided');
+    }
+    const { year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0 } = dateObj;
+    if (!year || !month || !day) {
+        throw new Error('Date object must include year, month, and day');
+    }
+    // Validate ranges
+    if (month < 1 || month > 12) {
+        throw new Error('Month must be between 1 and 12');
+    }
+    if (day < 1 || day > 31) {
+        throw new Error('Day must be between 1 and 31');
+    }
+    if (hour < 0 || hour > 23) {
+        throw new Error('Hour must be between 0 and 23');
+    }
+    if (minute < 0 || minute > 59) {
+        throw new Error('Minute must be between 0 and 59');
+    }
+    if (second < 0 || second > 59) {
+        throw new Error('Second must be between 0 and 59');
+    }
+    if (millisecond < 0 || millisecond > 999) {
+        throw new Error('Millisecond must be between 0 and 999');
+    }
+    return new Date(Date.UTC(year, month - 1, day, hour, minute, second, millisecond));
+}
+/**
+ * Check if a string is a valid ISO date string for serialization
+ */
+export function isValidISODateString(dateString) {
+    if (!dateString || typeof dateString !== 'string') {
+        return false;
+    }
+    const parsed = parseISOString(dateString);
+    return parsed !== null;
+}
+/**
+ * Check if a number is a valid epoch timestamp
+ */
+export function isValidEpochTimestamp(timestamp, precision = 'milliseconds') {
+    if (typeof timestamp !== 'number' || isNaN(timestamp)) {
+        return false;
+    }
+    // Check reasonable bounds for timestamps
+    const now = Date.now();
+    let min, max;
+    switch (precision) {
+        case 'seconds':
+            min = 0; // Jan 1, 1970
+            max = Math.floor(now / 1000) + (50 * 365 * 24 * 60 * 60); // 50 years from now
+            break;
+        case 'microseconds':
+            min = 0;
+            max = now * 1000 + (50 * 365 * 24 * 60 * 60 * 1000 * 1000); // 50 years from now
+            break;
+        case 'milliseconds':
+        default:
+            min = 0; // Jan 1, 1970
+            max = now + (50 * 365 * 24 * 60 * 60 * 1000); // 50 years from now
+            break;
+    }
+    return timestamp >= min && timestamp <= max;
+}
+/**
+ * Clone a date safely (avoids reference issues)
+ */
+export function cloneDate(date) {
+    const dateObj = normalizeDate(date);
+    return dateObj ? new Date(dateObj.getTime()) : null;
+}
+/**
+ * Compare two dates for equality (ignoring milliseconds if specified)
+ */
+export function datesEqual(date1, date2, precision = 'milliseconds') {
+    const d1 = normalizeDate(date1);
+    const d2 = normalizeDate(date2);
+    if (!d1 || !d2) {
+        return false;
+    }
+    let time1 = d1.getTime();
+    let time2 = d2.getTime();
+    switch (precision) {
+        case 'seconds':
+            time1 = Math.floor(time1 / 1000);
+            time2 = Math.floor(time2 / 1000);
+            break;
+        case 'minutes':
+            time1 = Math.floor(time1 / 60000);
+            time2 = Math.floor(time2 / 60000);
+            break;
+    }
+    return time1 === time2;
+}
+/**
+ * Get current timestamp in various formats
+ */
+export function now(format = 'date') {
+    const current = new Date();
+    switch (format) {
+        case 'iso':
+            return current.toISOString();
+        case 'epoch-ms':
+            return current.getTime();
+        case 'epoch-s':
+            return Math.floor(current.getTime() / 1000);
+        case 'date':
+        default:
+            return current;
+    }
+}
+/**
+ * Safely handle JSON parsing with date conversion
+ */
+export function parseJSONWithDates(jsonString, dateKeys, options) {
+    try {
+        return JSON.parse(jsonString, createDateReviver(dateKeys, options));
+    }
+    catch (error) {
+        throw new Error(`Failed to parse JSON: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Safely handle JSON stringification with date conversion
+ */
+export function stringifyWithDates(obj, dateKeys, options, space) {
+    try {
+        return JSON.stringify(obj, createDateReplacer(dateKeys, options), space);
+    }
+    catch (error) {
+        throw new Error(`Failed to stringify JSON: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+// Helper functions
+function normalizeDate(date) {
+    if (date instanceof Date) {
+        return isNaN(date.getTime()) ? null : date;
+    }
+    if (typeof date === 'string') {
+        const parsed = new Date(date);
+        return isNaN(parsed.getTime()) ? null : parsed;
+    }
+    if (typeof date === 'number') {
+        const parsed = new Date(date);
+        return isNaN(parsed.getTime()) ? null : parsed;
+    }
+    return null;
+}
+function formatCustom(date, format) {
+    // Simple custom formatter - can be extended
+    const formatMap = {
+        'YYYY': date.getUTCFullYear().toString(),
+        'MM': (date.getUTCMonth() + 1).toString().padStart(2, '0'),
+        'DD': date.getUTCDate().toString().padStart(2, '0'),
+        'HH': date.getUTCHours().toString().padStart(2, '0'),
+        'mm': date.getUTCMinutes().toString().padStart(2, '0'),
+        'ss': date.getUTCSeconds().toString().padStart(2, '0'),
+        'SSS': date.getUTCMilliseconds().toString().padStart(3, '0')
+    };
+    let result = format;
+    for (const [token, value] of Object.entries(formatMap)) {
+        result = result.replace(new RegExp(token, 'g'), value);
+    }
+    return result;
+}

package/dist/timezone.d.ts

@@ -1,11 +1,7 @@
 /**
- * Timezone utilities (rely on Intl API, fallbacks where possible)
+ * Timezone utilities using Intl API with fallbacks
  */
-export interface ZonedTime {
-    date: Date;
-    zone: string;
-    offsetMinutes: number;
-}
+import type { ZonedTime } from './types.js';
 /** Get offset (minutes) for a zone at a given date */
 export declare function getTimezoneOffset(zone: string, date?: Date): number | null;
 /** Format date/time in a zone */

package/dist/timezone.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../src/timezone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAgBtF;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,qBAA0B,GAAG,MAAM,CAG3G;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIvE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;CAAE,GAAG,IAAI,CAoB9J;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,UAK5B,CAAC;AAEF,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAKvG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAI7E"}
+{"version":3,"file":"timezone.d.ts","sourceRoot":"","sources":["../src/timezone.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,sDAAsD;AACtD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAgBtF;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,qBAA0B,GAAG,MAAM,CAG3G;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAIvE;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;CAAE,GAAG,IAAI,CAoB9J;AAED,yDAAyD;AACzD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOrD;AAED,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,UAK5B,CAAC;AAEF,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAKvG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAI7E"}

package/dist/timezone.js

@@ -1,5 +1,5 @@
 /**
- * Timezone utilities (rely on Intl API, fallbacks where possible)
+ * Timezone utilities using Intl API with fallbacks
  */
 /** Get offset (minutes) for a zone at a given date */
 export function getTimezoneOffset(zone, date = new Date()) {

package/dist/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Shared types and interfaces used across ts-time-utils modules
+ */
+/** Input that can be converted to a Date */
+export type DateInput = string | number | Date;
+/** A date range with start and end dates */
+export interface DateRange {
+    start: Date;
+    end: Date;
+}
+/** Options for parsing operations */
+export interface ParseOptions {
+    /** Whether to use strict parsing (reject ambiguous formats) */
+    strict?: boolean;
+    /** Timezone to use for parsing */
+    timezone?: string;
+    /** Default locale for parsing */
+    locale?: string;
+}
+/** Options for formatting operations */
+export interface FormatOptions {
+    /** Use short format (abbreviated units) */
+    short?: boolean;
+    /** Maximum number of units to display */
+    maxUnits?: number;
+    /** Round fractional units */
+    round?: boolean;
+    /** Include milliseconds in output */
+    includeMs?: boolean;
+    /** Locale for formatting */
+    locale?: string;
+}
+/** Time units supported across the library */
+export type TimeUnit = 'millisecond' | 'milliseconds' | 'ms' | 'second' | 'seconds' | 's' | 'minute' | 'minutes' | 'm' | 'hour' | 'hours' | 'h' | 'day' | 'days' | 'd' | 'week' | 'weeks' | 'w' | 'month' | 'months' | 'M' | 'year' | 'years' | 'y';
+/** Standardized error types */
+export declare class TimeUtilsError extends Error {
+    code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+export declare class ParseError extends TimeUtilsError {
+    input?: unknown | undefined;
+    constructor(message: string, input?: unknown | undefined);
+}
+export declare class ValidationError extends TimeUtilsError {
+    value?: unknown | undefined;
+    constructor(message: string, value?: unknown | undefined);
+}
+/** Common validation function type */
+export type DateValidator = (date: Date) => boolean;
+/** Common date transformation function type */
+export type DateTransformer = (date: Date) => Date;
+/** Options for working hours calculations */
+export interface WorkingHoursConfig {
+    /** Working days (0=Sunday, 1=Monday, etc.) */
+    workingDays: number[];
+    /** Working hours range */
+    hours: {
+        start: number;
+        end: number;
+    };
+    /** Break periods during working hours */
+    breaks?: {
+        start: number;
+        end: number;
+    }[];
+    /** Timezone for working hours calculation */
+    timezone?: string;
+}
+/** Result of age calculation */
+export interface AgeResult {
+    years: number;
+    months: number;
+    days: number;
+    totalDays: number;
+    totalMonths: number;
+}
+/** Timezone information */
+export interface ZonedTime {
+    date: Date;
+    zone: string;
+    offsetMinutes: number;
+}
+/** Interval between two points in time */
+export interface Interval {
+    start: Date;
+    end: Date;
+}
+/** Performance benchmarking result */
+export interface BenchmarkResult {
+    average: number;
+    min: number;
+    max: number;
+    total: number;
+    totalTime: number;
+    iterations: number;
+}
+/** Calendar event recurrence pattern */
+export interface RecurrencePattern {
+    frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
+    interval?: number;
+    byWeekDay?: number[];
+    byMonthDay?: number[];
+    byMonth?: number[];
+    count?: number;
+    until?: Date;
+}
+/** Recurrence frequency types */
+export type RecurrenceFrequency = 'daily' | 'weekly' | 'monthly' | 'yearly';
+/** Recurrence rule for repeating events (RRULE-inspired) */
+export interface RecurrenceRule {
+    /** Frequency of recurrence */
+    frequency: RecurrenceFrequency;
+    /** Start date for the recurrence */
+    startDate: DateInput;
+    /** Interval between occurrences (default: 1) */
+    interval?: number;
+    /** Days of week (0=Sunday, 6=Saturday) */
+    byWeekday?: number[];
+    /** Days of month (1-31) */
+    byMonthDay?: number[];
+    /** Months of year (1-12) */
+    byMonth?: number[];
+    /** Number of occurrences (alternative to until) */
+    count?: number;
+    /** End date for recurrence (alternative to count) */
+    until?: DateInput;
+}
+/** Locale-specific formatting options */
+export interface LocaleFormatOptions extends FormatOptions {
+    /** Calendar system to use */
+    calendar?: 'gregory' | 'islamic' | 'hebrew' | 'persian' | 'chinese';
+    /** Number system to use */
+    numberingSystem?: 'arab' | 'arabext' | 'bali' | 'beng' | 'latn';
+}
+/** Business calendar configuration */
+export interface BusinessConfig {
+    /** Fiscal year start month (1-12) */
+    fiscalYearStart?: number;
+    /** Custom holidays */
+    holidays?: Date[];
+    /** Trading days override */
+    tradingDays?: number[];
+    /** Country code for built-in holidays */
+    country?: string;
+}
+/** Duration unit types */
+export type DurationUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years';
+/** Duration input configuration */
+export interface DurationInput {
+    milliseconds?: number;
+    seconds?: number;
+    minutes?: number;
+    hours?: number;
+    days?: number;
+    weeks?: number;
+    months?: number;
+    years?: number;
+}
+/** Duration comparison result */
+export type DurationComparison = -1 | 0 | 1;
+/** Serialization format options */
+export interface SerializationOptions {
+    /** Include timezone information */
+    includeTimezone?: boolean;
+    /** Use UTC for serialization */
+    useUTC?: boolean;
+    /** Custom date format */
+    format?: 'iso' | 'epoch' | 'object' | 'custom';
+    /** Precision for epoch timestamps */
+    precision?: 'milliseconds' | 'seconds' | 'microseconds';
+    /** Custom format string when format is 'custom' */
+    customFormat?: string;
+}
+/** Date object representation for safe serialization */
+export interface DateObject {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+    timezone?: string;
+}
+/** Epoch timestamp with metadata */
+export interface EpochTimestamp {
+    timestamp: number;
+    precision: 'milliseconds' | 'seconds' | 'microseconds';
+    timezone?: string;
+}
+/** Supported locales for internationalization */
+export type SupportedLocale = 'en' | 'en-US' | 'en-GB' | 'en-CA' | 'en-AU' | 'es' | 'es-ES' | 'es-MX' | 'es-AR' | 'fr' | 'fr-FR' | 'fr-CA' | 'de' | 'de-DE' | 'de-AT' | 'de-CH' | 'it' | 'it-IT' | 'pt' | 'pt-PT' | 'pt-BR' | 'ru' | 'ru-RU' | 'zh' | 'zh-CN' | 'zh-TW' | 'ja' | 'ja-JP' | 'ko' | 'ko-KR' | 'ar' | 'ar-SA' | 'hi' | 'hi-IN' | 'tr' | 'tr-TR' | 'pl' | 'pl-PL' | 'nl' | 'nl-NL' | 'sv' | 'sv-SE' | 'da' | 'da-DK' | 'no' | 'no-NO' | 'fi' | 'fi-FI' | 'fa' | 'fa-IR';
+/** Relative time units for localization */
+export type RelativeTimeUnit = 'second' | 'seconds' | 'minute' | 'minutes' | 'hour' | 'hours' | 'day' | 'days' | 'week' | 'weeks' | 'month' | 'months' | 'year' | 'years';
+/** Locale-specific configuration */
+export interface LocaleConfig {
+    /** Locale identifier */
+    locale: SupportedLocale;
+    /** Date format patterns */
+    dateFormats?: {
+        short?: string;
+        medium?: string;
+        long?: string;
+        full?: string;
+    };
+    /** Time format patterns */
+    timeFormats?: {
+        short?: string;
+        medium?: string;
+        long?: string;
+        full?: string;
+    };
+    /** Relative time translations */
+    relativeTime?: {
+        future?: string;
+        past?: string;
+        units?: Partial<Record<RelativeTimeUnit, string>>;
+    };
+    /** Calendar-specific settings */
+    calendar?: {
+        weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+        monthNames?: string[];
+        monthNamesShort?: string[];
+        dayNames?: string[];
+        dayNamesShort?: string[];
+    };
+    /** Number formatting */
+    numbers?: {
+        decimal?: string;
+        thousands?: string;
+    };
+}
+/** Relative time formatting options */
+export interface RelativeTimeOptions {
+    /** Locale to use for formatting */
+    locale?: SupportedLocale;
+    /** Maximum unit to display (e.g., don't show years) */
+    maxUnit?: RelativeTimeUnit;
+    /** Minimum unit to display (e.g., don't show seconds) */
+    minUnit?: RelativeTimeUnit;
+    /** Number of decimal places for precise units */
+    precision?: number;
+    /** Use short forms (1h vs 1 hour) */
+    short?: boolean;
+    /** Use numeric format when possible */
+    numeric?: 'always' | 'auto';
+    /** Custom formatting style */
+    style?: 'long' | 'short' | 'narrow';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,25 @@
+/**
+ * Shared types and interfaces used across ts-time-utils modules
+ */
+/** Standardized error types */
+export class TimeUtilsError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'TimeUtilsError';
+    }
+}
+export class ParseError extends TimeUtilsError {
+    constructor(message, input) {
+        super(message, 'PARSE_ERROR');
+        this.input = input;
+        this.name = 'ParseError';
+    }
+}
+export class ValidationError extends TimeUtilsError {
+    constructor(message, value) {
+        super(message, 'VALIDATION_ERROR');
+        this.value = value;
+        this.name = 'ValidationError';
+    }
+}