ts-time-utils 0.0.1 → 1.0.0

package/README.md

@@ -8,7 +8,25 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 - **⚡ Fast** - Zero dependencies, pure JavaScript functions
 - **🔧 TypeScript** - Full type safety and IntelliSense support
 - **🌳 Tree-shakable** - Import individual functions to minimize bundle size
-- **📚 Comprehensive** - 12 utility categories with 70+ functions
+- **📚 Comprehensive** - 15 utility categories with 115+ functions
+
+### ⏱️ Duration utilities
+
+- Immutable Duration class with arithmetic operations
+- Create durations from various units and string formats
+- Add, subtract, multiply, divide durations
+- Compare durations and check relationships
+- Format to human-readable strings
+- Utility functions for arrays of durations
+
+### 💾 Serialization utilities
+
+- Safe JSON date serialization and deserialization
+- Multiple format support (ISO, epoch, object, custom)
+- Automatic date reviver and replacer functions
+- Timezone-aware serialization options
+- Cross-platform date interchange utilities
+- Validation for ISO strings and epoch timestamps
 
 ### 🎨 Format utilities
 
@@ -89,6 +107,16 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 - This/last/next week, month, quarter, year
 - Rolling windows and quarter helpers
 
+### 🌍 Locale utilities
+
+- Multi-language relative time formatting
+- Locale-specific date and time formatting
+- Support for 40+ locales with built-in configurations
+- Auto-detection of system/browser locale
+- Custom locale registration
+- Internationalization (i18n) support
+- **Locale conversions** - Convert between different locales and detect locale from text
+
 ### 🧱 Constants
 
 - Milliseconds & seconds per unit
@@ -122,10 +150,121 @@ import { createInterval, mergeIntervals } from "ts-time-utils/interval";
 import { formatInTimeZone } from "ts-time-utils/timezone";
 import { isWorkingTime, addWorkingHours } from "ts-time-utils/workingHours";
 import { today, lastNDays } from "ts-time-utils/rangePresets";
+import { Duration, createDuration } from "ts-time-utils/duration";
+import { serializeDate, parseJSONWithDates } from "ts-time-utils/serialize";
+import {
+  formatRelativeTime,
+  formatDateLocale,
+  detectLocale,
+} from "ts-time-utils/locale";
 ```
 
 ## 📖 Examples
 
+### Duration Utilities
+
+```ts
+import {
+  Duration,
+  createDuration,
+  formatDurationString,
+} from "ts-time-utils/duration";
+
+// Create durations
+const duration1 = Duration.fromHours(2.5); // 2.5 hours
+const duration2 = new Duration({ hours: 1, minutes: 30 }); // 1.5 hours
+const duration3 = Duration.fromString("1h 30m 45s"); // Parse from string
+const duration4 = Duration.between(startDate, endDate); // From date range
+
+// Arithmetic operations
+const sum = duration1.add(duration2); // 4 hours
+const diff = duration1.subtract(duration2); // 1 hour
+const doubled = duration1.multiply(2); // 5 hours
+const half = duration1.divide(2); // 1.25 hours
+
+// Comparisons
+duration1.equals(duration2); // false
+duration1.greaterThan(duration2); // true
+duration1.compareTo(duration2); // 1
+
+// Conversions and formatting
+duration1.hours; // 2.5
+duration1.minutes; // 150
+duration1.toString(); // "2h 30m"
+formatDurationString(duration1, { long: true }); // "2 hours, 30 minutes"
+
+// Utility functions with arrays
+const durations = [duration1, duration2, duration3];
+const max = maxDuration(...durations);
+const total = sumDurations(...durations);
+const average = averageDuration(...durations);
+```
+
+### Serialization Utilities
+
+```ts
+import {
+  serializeDate,
+  deserializeDate,
+  parseJSONWithDates,
+  stringifyWithDates,
+  toEpochTimestamp,
+  fromEpochTimestamp,
+  toDateObject,
+  fromDateObject,
+} from "ts-time-utils/serialize";
+
+// Serialize dates in different formats
+const date = new Date("2025-09-14T12:30:45.123Z");
+
+const isoString = serializeDate(date, { format: "iso" }); // "2025-09-14T12:30:45.123Z"
+const epochMs = serializeDate(date, { format: "epoch" }); // 1757853045123
+const dateObj = serializeDate(date, { format: "object" }); // {year: 2025, month: 9, ...}
+const custom = serializeDate(date, {
+  format: "custom",
+  customFormat: "YYYY-MM-DD HH:mm:ss",
+}); // "2025-09-14 12:30:45"
+
+// Deserialize from various formats
+const fromISO = deserializeDate("2025-09-14T12:30:45.123Z");
+const fromEpoch = deserializeDate(1757853045123);
+const fromObj = deserializeDate({
+  year: 2025,
+  month: 9,
+  day: 14,
+  hour: 12,
+  minute: 30,
+  second: 45,
+  millisecond: 123,
+});
+
+// Safe JSON handling with automatic date conversion
+const data = {
+  name: "User",
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  metadata: "other data",
+};
+
+// Stringify with automatic date serialization
+const jsonString = stringifyWithDates(data, ["createdAt", "updatedAt"], {
+  format: "epoch",
+});
+// {"name":"User","createdAt":1757853045123,"updatedAt":1757853045123,"metadata":"other data"}
+
+// Parse with automatic date restoration
+const parsed = parseJSONWithDates(jsonString, ["createdAt", "updatedAt"]);
+// parsed.createdAt and parsed.updatedAt are Date objects
+
+// Epoch timestamp utilities
+const timestamp = toEpochTimestamp(date, "seconds"); // 1757853045
+const restoredDate = fromEpochTimestamp(timestamp, "seconds");
+
+// Date object utilities (UTC-based)
+const dateObject = toDateObject(date, true); // includes timezone
+const reconstructed = fromDateObject(dateObject);
+```
+
 ### Format Utilities
 
 ```ts
@@ -289,8 +428,198 @@ const week = thisWeek();
 const quarter = quarterRange();
 ```
 
+### Locale Utilities
+
+```ts
+import {
+  formatRelativeTime,
+  formatDateLocale,
+  formatTimeLocale,
+  formatDateTimeLocale,
+  registerLocale,
+  getLocaleConfig,
+  detectLocale,
+  getSupportedLocales,
+} from "ts-time-utils/locale";
+
+// Relative time formatting in multiple languages
+const pastDate = new Date(Date.now() - 2 * 60 * 60 * 1000); // 2 hours ago
+formatRelativeTime(pastDate, { locale: "en" }); // "2 hours ago"
+formatRelativeTime(pastDate, { locale: "es" }); // "hace 2 horas"
+formatRelativeTime(pastDate, { locale: "fr" }); // "il y a 2 heures"
+formatRelativeTime(pastDate, { locale: "de" }); // "vor 2 Stunden"
+formatRelativeTime(pastDate, { locale: "nl" }); // "2 uur geleden"
+formatRelativeTime(pastDate, { locale: "it" }); // "2 ore fa"
+formatRelativeTime(pastDate, { locale: "zh" }); // "2小时前"
+formatRelativeTime(pastDate, { locale: "ja" }); // "2時間前"
+formatRelativeTime(pastDate, { locale: "fa" }); // "2 ساعت پیش"
+
+// Future dates
+const futureDate = new Date(Date.now() + 3 * 24 * 60 * 60 * 1000);
+formatRelativeTime(futureDate, { locale: "en" }); // "in 3 days"
+formatRelativeTime(futureDate, { locale: "es" }); // "en 3 días"
+formatRelativeTime(futureDate, { locale: "nl" }); // "over 3 dagen"
+formatRelativeTime(futureDate, { locale: "it" }); // "tra 3 giorni"
+formatRelativeTime(futureDate, { locale: "fa" }); // "3 روز دیگر"
+
+// Relative time options
+formatRelativeTime(pastDate, {
+  locale: "en",
+  maxUnit: "days", // Don't use units larger than days
+  minUnit: "minutes", // Don't use units smaller than minutes
+  precision: 1, // Show 1 decimal place: "2.0 hours ago"
+  short: true, // Use abbreviated format: "2h ago"
+  numeric: "auto", // Use words when appropriate: "yesterday"
+});
+
+// Date formatting
+const date = new Date("2024-01-15T14:30:45Z");
+formatDateLocale(date, "en", "medium"); // "Jan 15, 2024"
+formatDateLocale(date, "es", "medium"); // "15 ene 2024"
+formatDateLocale(date, "fr", "long"); // "15 janvier 2024"
+formatDateLocale(date, "de", "short"); // "15.1.2024"
+
+// Time formatting
+formatTimeLocale(date, "en", "short"); // "2:30 PM"
+formatTimeLocale(date, "de", "medium"); // "14:30:45"
+formatTimeLocale(date, "fr", "long"); // "14:30:45 UTC"
+
+// Combined date and time
+formatDateTimeLocale(date, "en"); // "Jan 15, 2024 2:30:45 PM"
+
+// Auto-detect locale from browser/system
+const userLocale = detectLocale(); // e.g., 'en-US' or 'fr-FR'
+formatRelativeTime(pastDate, { locale: userLocale });
+
+// Get supported locales
+const locales = getSupportedLocales();
+// ['en', 'es', 'fr', 'de', 'zh', 'ja', ...]
+
+// Register custom locale
+registerLocale("custom", {
+  locale: "custom",
+  dateFormats: {
+    short: "M/d/yyyy",
+    medium: "MMM d, yyyy",
+    long: "MMMM d, yyyy",
+    full: "EEEE, MMMM d, yyyy",
+  },
+  timeFormats: {
+    short: "h:mm a",
+    medium: "h:mm:ss a",
+    long: "h:mm:ss a z",
+    full: "h:mm:ss a zzzz",
+  },
+  relativeTime: {
+    future: "in {0}",
+    past: "{0} ago",
+    units: {
+      second: "sec",
+      seconds: "secs",
+      minute: "min",
+      minutes: "mins",
+      hour: "hr",
+      hours: "hrs",
+      day: "day",
+      days: "days",
+      week: "wk",
+      weeks: "wks",
+      month: "mo",
+      months: "mos",
+      year: "yr",
+      years: "yrs",
+    },
+  },
+  calendar: {
+    weekStartsOn: 0, // Sunday
+    monthNames: ["Jan", "Feb", "Mar" /* ... */],
+    monthNamesShort: ["J", "F", "M" /* ... */],
+    dayNames: ["Sun", "Mon", "Tue" /* ... */],
+    dayNamesShort: ["S", "M", "T" /* ... */],
+  },
+  numbers: {
+    decimal: ".",
+    thousands: ",",
+  },
+});
+
+// Locale Conversion Utilities
+import {
+  convertRelativeTime,
+  detectLocaleFromRelativeTime,
+  convertFormatPattern,
+  convertFormattedDate,
+  convertRelativeTimeArray,
+  compareLocaleFormats,
+} from "ts-time-utils/locale";
+
+// Convert relative time between locales
+convertRelativeTime("2 hours ago", "en", "es"); // "hace 2 horas"
+convertRelativeTime("hace 3 días", "es", "fr"); // "il y a 3 jours"
+convertRelativeTime("2h ago", "en", "de"); // "vor 2h"
+convertRelativeTime("2 hours ago", "en", "nl"); // "2 uur geleden"
+convertRelativeTime("2 hours ago", "en", "it"); // "2 ore fa"
+convertRelativeTime("2 hours ago", "en", "fa"); // "2 ساعت پیش"
+convertRelativeTime("2 ساعت پیش", "fa", "en"); // "2 hours ago"
+
+// Detect locale from formatted text
+detectLocaleFromRelativeTime("2 hours ago"); // "en"
+detectLocaleFromRelativeTime("hace 2 horas"); // "es"
+detectLocaleFromRelativeTime("il y a 2 heures"); // "fr"
+detectLocaleFromRelativeTime("2 uur geleden"); // "nl"
+detectLocaleFromRelativeTime("2 ore fa"); // "it"
+detectLocaleFromRelativeTime("2 ساعت پیش"); // "fa"
+detectLocaleFromRelativeTime("vor 2 Stunden"); // "de"
+
+// Convert date format patterns between locales
+convertFormatPattern("M/d/yyyy", "en", "de"); // "dd.MM.yyyy"
+convertFormatPattern("MMM d, yyyy", "en", "fr", "long"); // "d MMMM yyyy"
+
+// Convert formatted dates between locales
+convertFormattedDate("Jan 15, 2024", "en", "es"); // "15 ene 2024"
+convertFormattedDate("15. Januar 2024", "de", "en"); // "Jan 15, 2024"
+
+// Bulk conversion of relative time arrays
+const englishTimes = ["2 hours ago", "in 3 days", "1 week ago"];
+convertRelativeTimeArray(englishTimes, "en", "es");
+// ["hace 2 horas", "en 3 días", "hace 1 semana"]
+
+// Compare format differences between locales
+const comparison = compareLocaleFormats("en", "de");
+console.log(comparison.dateFormats.short);
+// { locale1: "M/d/yyyy", locale2: "dd.MM.yyyy" }
+console.log(comparison.weekStartsOn);
+// { locale1: 0, locale2: 1 } // Sunday vs Monday
+```
+
 ## 📊 API Reference
 
+### Duration Functions
+
+- `Duration` class - Immutable duration with full arithmetic support
+- `createDuration(input)` - Create duration from number, object, or string
+- `Duration.fromHours/Minutes/Seconds/Days/Weeks(n)` - Create from specific units
+- `Duration.fromString(str)` - Parse from string like "1h 30m 45s"
+- `Duration.between(start, end)` - Create from date range
+- `duration.add/subtract/multiply/divide()` - Arithmetic operations
+- `duration.equals/greaterThan/lessThan()` - Comparison methods
+- `formatDurationString(duration, options?)` - Format to readable string
+- `maxDuration/minDuration(...durations)` - Find extremes
+- `sumDurations/averageDuration(...durations)` - Aggregate operations
+
+### Serialization Functions
+
+- `serializeDate(date, options?)` - Serialize date to various formats (ISO, epoch, object, custom)
+- `deserializeDate(serialized, options?)` - Deserialize from string, number, or object
+- `parseJSONWithDates(jsonString, dateKeys?, options?)` - Parse JSON with automatic date conversion
+- `stringifyWithDates(obj, dateKeys?, options?)` - Stringify JSON with automatic date serialization
+- `createDateReviver/createDateReplacer(dateKeys?, options?)` - Create JSON reviver/replacer functions
+- `toEpochTimestamp/fromEpochTimestamp(input, precision?)` - Convert to/from epoch timestamps
+- `toDateObject/fromDateObject(input)` - Convert to/from safe object representation
+- `isValidISODateString/isValidEpochTimestamp(input)` - Validation utilities
+- `cloneDate(date)` - Safe date cloning
+- `datesEqual(date1, date2, precision?)` - Compare dates with precision control
+
 ### Format Functions
 
 - `formatDuration(ms, options?)` - Format milliseconds to readable duration
@@ -319,6 +648,41 @@ const quarter = quarterRange();
 - `isValidTimeString(time)` - Validate HH:MM time format
 - `isValidISOString(dateString)` - Validate ISO 8601 date string
 
+### Locale Functions
+
+- `formatRelativeTime(date, options?)` - Format relative time with locale support
+  - Options: `locale`, `maxUnit`, `minUnit`, `precision`, `short`, `numeric`, `style`
+  - Supports 30+ locales: en, es, fr, de, it, pt, nl, sv, da, no, fi, pl, cs, sk, hu, ro, bg, hr, sl, et, lv, lt, ru, uk, tr, ar, he, hi, th, ko, zh, ja
+- `formatDateLocale(date, locale?, style?)` - Format date in locale-specific format
+  - Styles: 'short', 'medium', 'long', 'full'
+- `formatTimeLocale(date, locale?, style?)` - Format time in locale-specific format
+- `formatDateTimeLocale(date, locale?, dateStyle?, timeStyle?)` - Format both date and time
+- `registerLocale(locale, config)` - Register a custom locale configuration
+- `getLocaleConfig(locale)` - Get configuration for a specific locale
+- `detectLocale(fallback?)` - Auto-detect system/browser locale
+- `getSupportedLocales()` - Get array of all supported locale codes
+- `getMonthNames(locale?, short?)` - Get localized month names
+- `getDayNames(locale?, short?)` - Get localized day names
+- `getBestMatchingLocale(preferences, fallback?)` - Find best matching locale from preferences
+
+#### Locale Conversion Functions
+
+- `convertRelativeTime(text, fromLocale, toLocale)` - Convert relative time between locales
+  - Example: `convertRelativeTime("2 hours ago", "en", "es")` → `"hace 2 horas"`
+  - Example: `convertRelativeTime("2 hours ago", "en", "nl")` → `"2 uur geleden"`
+  - Example: `convertRelativeTime("2 hours ago", "en", "it")` → `"2 ore fa"`
+  - Example: `convertRelativeTime("2 hours ago", "en", "fa")` → `"2 ساعت پیش"`
+- `detectLocaleFromRelativeTime(text)` - Detect locale from relative time string
+  - Returns most likely locale or null if detection fails
+- `convertFormatPattern(pattern, fromLocale, toLocale, style?)` - Convert date format patterns
+  - Maps common patterns between locales or uses target locale's style
+- `convertFormattedDate(formattedDate, fromLocale, toLocale, targetStyle?)` - Convert formatted dates
+  - Parses date in source locale and reformats in target locale
+- `convertRelativeTimeArray(array, fromLocale, toLocale)` - Bulk convert relative time arrays
+  - Returns array with same length, null for unparseable strings
+- `compareLocaleFormats(locale1, locale2)` - Compare format differences between locales
+  - Returns object with dateFormats, timeFormats, and weekStartsOn comparisons
+
 ## 🛠️ Development
 
 ```bash

package/dist/age.d.ts

@@ -1,14 +1,5 @@
 import { TimeUnit } from './constants.js';
-/**
- * Age calculation result
- */
-export interface AgeResult {
-    years: number;
-    months: number;
-    days: number;
-    totalDays: number;
-    totalMonths: number;
-}
+import type { AgeResult } from './types.js';
 /**
  * Calculate detailed age from birth date
  * @param birthDate - date of birth

package/dist/age.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"age.d.ts","sourceRoot":"","sources":["../src/age.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,SAAS,CAyBzF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,IAAI,EACf,IAAI,EAAE,QAAQ,EACd,aAAa,GAAE,IAAiB,GAC/B,MAAM,CAsBR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,IAAI,EACf,aAAa,GAAE,IAAiB,GAC/B,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAQlD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,IAAI,CAYvF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,MAAM,CAG9F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,OAAO,CAQrF"}
+{"version":3,"file":"age.d.ts","sourceRoot":"","sources":["../src/age.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,SAAS,CAyBzF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,IAAI,EACf,IAAI,EAAE,QAAQ,EACd,aAAa,GAAE,IAAiB,GAC/B,MAAM,CAsBR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,IAAI,EACf,aAAa,GAAE,IAAiB,GAC/B,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAQlD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,IAAI,CAYvF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,MAAM,CAG9F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,OAAO,CAQrF"}

package/dist/constants.d.ts

@@ -1,6 +1,7 @@
 /**
- * Time constants for millisecond conversions
+ * Constants for time conversions and utility types
  */
+export type { TimeUnit, FormatOptions } from './types.js';
 export declare const MILLISECONDS_PER_SECOND = 1000;
 export declare const MILLISECONDS_PER_MINUTE: number;
 export declare const MILLISECONDS_PER_HOUR: number;
@@ -8,28 +9,8 @@ export declare const MILLISECONDS_PER_DAY: number;
 export declare const MILLISECONDS_PER_WEEK: number;
 export declare const MILLISECONDS_PER_MONTH: number;
 export declare const MILLISECONDS_PER_YEAR: number;
-/**
- * Second-based constants
- */
 export declare const SECONDS_PER_MINUTE = 60;
 export declare const SECONDS_PER_HOUR: number;
 export declare const SECONDS_PER_DAY: number;
 export declare const SECONDS_PER_WEEK: number;
-/**
- * Common time units
- */
-export type TimeUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years';
-/**
- * Formatting options
- */
-export interface FormatOptions {
-    /** Include milliseconds in output */
-    includeMs?: boolean;
-    /** Use short format (e.g., "1h" vs "1 hour") */
-    short?: boolean;
-    /** Maximum number of units to show */
-    maxUnits?: number;
-    /** Round to nearest unit instead of floor */
-    round?: boolean;
-}
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,eAAO,MAAM,uBAAuB,QAA+B,CAAC;AACpE,eAAO,MAAM,qBAAqB,QAA+B,CAAC;AAClE,eAAO,MAAM,oBAAoB,QAA6B,CAAC;AAC/D,eAAO,MAAM,qBAAqB,QAA2B,CAAC;AAC9D,eAAO,MAAM,sBAAsB,QAA4B,CAAC;AAChE,eAAO,MAAM,qBAAqB,QAA6B,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,gBAAgB,QAA0B,CAAC;AACxD,eAAO,MAAM,eAAe,QAAwB,CAAC;AACrD,eAAO,MAAM,gBAAgB,QAAsB,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG1D,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,eAAO,MAAM,uBAAuB,QAAY,CAAC;AACjD,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AACpD,eAAO,MAAM,oBAAoB,QAAsB,CAAC;AACxD,eAAO,MAAM,qBAAqB,QAA0B,CAAC;AAC7D,eAAO,MAAM,sBAAsB,QAA2B,CAAC;AAC/D,eAAO,MAAM,qBAAqB,QAA4B,CAAC;AAG/D,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,gBAAgB,QAAU,CAAC;AACxC,eAAO,MAAM,eAAe,QAAe,CAAC;AAC5C,eAAO,MAAM,gBAAgB,QAAmB,CAAC"}

package/dist/constants.js

@@ -1,17 +1,16 @@
 /**
- * Time constants for millisecond conversions
+ * Constants for time conversions and utility types
  */
+// Milliseconds per unit
 export const MILLISECONDS_PER_SECOND = 1000;
-export const MILLISECONDS_PER_MINUTE = 60 * MILLISECONDS_PER_SECOND;
-export const MILLISECONDS_PER_HOUR = 60 * MILLISECONDS_PER_MINUTE;
-export const MILLISECONDS_PER_DAY = 24 * MILLISECONDS_PER_HOUR;
-export const MILLISECONDS_PER_WEEK = 7 * MILLISECONDS_PER_DAY;
-export const MILLISECONDS_PER_MONTH = 30 * MILLISECONDS_PER_DAY; // Approximate
-export const MILLISECONDS_PER_YEAR = 365 * MILLISECONDS_PER_DAY; // Approximate
-/**
- * Second-based constants
- */
+export const MILLISECONDS_PER_MINUTE = 60 * 1000;
+export const MILLISECONDS_PER_HOUR = 60 * 60 * 1000;
+export const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+export const MILLISECONDS_PER_WEEK = 7 * 24 * 60 * 60 * 1000;
+export const MILLISECONDS_PER_MONTH = 30 * 24 * 60 * 60 * 1000; // Approximate
+export const MILLISECONDS_PER_YEAR = 365 * 24 * 60 * 60 * 1000; // Approximate
+// Seconds per unit  
 export const SECONDS_PER_MINUTE = 60;
-export const SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE;
-export const SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR;
-export const SECONDS_PER_WEEK = 7 * SECONDS_PER_DAY;
+export const SECONDS_PER_HOUR = 60 * 60;
+export const SECONDS_PER_DAY = 24 * 60 * 60;
+export const SECONDS_PER_WEEK = 7 * 24 * 60 * 60;

package/dist/duration.d.ts

@@ -0,0 +1,171 @@
+import type { DurationInput, DurationComparison } from './types.js';
+/**
+ * Represents a duration of time with arithmetic and conversion capabilities
+ */
+export declare class Duration {
+    private readonly _milliseconds;
+    constructor(input: number | DurationInput | string);
+    /**
+     * Create Duration from milliseconds
+     */
+    static fromMilliseconds(ms: number): Duration;
+    /**
+     * Create Duration from seconds
+     */
+    static fromSeconds(seconds: number): Duration;
+    /**
+     * Create Duration from minutes
+     */
+    static fromMinutes(minutes: number): Duration;
+    /**
+     * Create Duration from hours
+     */
+    static fromHours(hours: number): Duration;
+    /**
+     * Create Duration from days
+     */
+    static fromDays(days: number): Duration;
+    /**
+     * Create Duration from weeks
+     */
+    static fromWeeks(weeks: number): Duration;
+    /**
+     * Create Duration from a string (e.g., "1h 30m", "2.5 hours", "90 seconds")
+     */
+    static fromString(str: string): Duration;
+    /**
+     * Create Duration between two dates
+     */
+    static between(start: Date, end: Date): Duration;
+    /**
+     * Get duration in milliseconds
+     */
+    get milliseconds(): number;
+    /**
+     * Get duration in seconds
+     */
+    get seconds(): number;
+    /**
+     * Get duration in minutes
+     */
+    get minutes(): number;
+    /**
+     * Get duration in hours
+     */
+    get hours(): number;
+    /**
+     * Get duration in days
+     */
+    get days(): number;
+    /**
+     * Get duration in weeks
+     */
+    get weeks(): number;
+    /**
+     * Add another duration
+     */
+    add(other: Duration | number | DurationInput): Duration;
+    /**
+     * Subtract another duration
+     */
+    subtract(other: Duration | number | DurationInput): Duration;
+    /**
+     * Multiply duration by a factor
+     */
+    multiply(factor: number): Duration;
+    /**
+     * Divide duration by a factor
+     */
+    divide(factor: number): Duration;
+    /**
+     * Get absolute duration (always positive)
+     */
+    abs(): Duration;
+    /**
+     * Negate duration
+     */
+    negate(): Duration;
+    /**
+     * Check if duration equals another
+     */
+    equals(other: Duration | number): boolean;
+    /**
+     * Check if duration is greater than another
+     */
+    greaterThan(other: Duration | number): boolean;
+    /**
+     * Check if duration is less than another
+     */
+    lessThan(other: Duration | number): boolean;
+    /**
+     * Compare with another duration (-1, 0, 1)
+     */
+    compareTo(other: Duration): DurationComparison;
+    /**
+     * Check if duration is zero
+     */
+    isZero(): boolean;
+    /**
+     * Check if duration is positive
+     */
+    isPositive(): boolean;
+    /**
+     * Check if duration is negative
+     */
+    isNegative(): boolean;
+    /**
+     * Convert to human-readable string
+     */
+    toString(): string;
+    /**
+     * Convert to detailed object representation
+     */
+    toObject(): Required<DurationInput>;
+    /**
+     * Convert to JSON representation
+     */
+    toJSON(): number;
+    /**
+     * Create Duration from JSON
+     */
+    static fromJSON(ms: number): Duration;
+    private calculateMilliseconds;
+    private parseString;
+    private normalizeToDuration;
+}
+/**
+ * Create a new Duration instance
+ */
+export declare function createDuration(input: number | DurationInput | string): Duration;
+/**
+ * Check if a value is a valid duration
+ */
+export declare function isValidDuration(value: any): value is Duration;
+/**
+ * Parse duration from various formats
+ */
+export declare function parseDurationString(input: string | number | DurationInput): Duration;
+/**
+ * Format duration to human-readable string
+ */
+export declare function formatDurationString(duration: Duration | number, options?: {
+    long?: boolean;
+    precision?: number;
+}): string;
+/**
+ * Get the maximum duration from an array
+ */
+export declare function maxDuration(...durations: Duration[]): Duration | null;
+/**
+ * Get the minimum duration from an array
+ */
+export declare function minDuration(...durations: Duration[]): Duration | null;
+/**
+ * Sum multiple durations
+ */
+export declare function sumDurations(...durations: Duration[]): Duration;
+/**
+ * Get average duration from an array
+ */
+export declare function averageDuration(...durations: Duration[]): Duration | null;
+//# sourceMappingURL=duration.d.ts.map

package/dist/duration.d.ts.map

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