ts-time-utils 0.0.1

package/README.md

@@ -0,0 +1,343 @@
+# ts-time-utils
+
+A lightweight TypeScript utility library for time formatting, calculations, and validation with full tree-shaking support.
+
+## 🚀 Features
+
+- **📦 Lightweight** - Import only what you need with tree-shaking support
+- **⚡ 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
+
+### 🎨 Format utilities
+
+- Format milliseconds to human-readable durations
+- Get human-friendly "time ago" strings
+- Parse duration strings back to milliseconds
+- Format time in 12h/24h/ISO formats
+
+### 🧮 Calculation utilities
+
+- Calculate difference between dates in any unit
+- Add/subtract time from dates
+- Get start/end of time periods
+- Business days calculations
+- Check if date is between two dates
+
+### ✅ Validation utilities
+
+- Validate dates and time strings
+- Check for leap years, weekends, past/future dates
+- Compare dates (same day, today, yesterday, etc.)
+
+### 🎂 Age utilities
+
+- Calculate precise age with years, months, and days
+- Get life stage classifications (infant, child, adult, etc.)
+- Birthday calculations and next birthday finder
+- Check if today is someone's birthday
+
+### 📅 Calendar utilities
+
+- ISO week numbers and week-based calculations
+- Quarter operations and fiscal year support
+- Holiday calculations (Easter, Thanksgiving, etc.)
+- Days in month/year calculations
+
+### 🔍 Parse utilities
+
+- Advanced date parsing from multiple formats
+- Relative date parsing ("tomorrow", "next week")
+- Custom format parsing with flexible patterns
+- Smart date interpretation
+
+### ⚡ Performance utilities
+
+- Async utilities (sleep, timeout, retry)
+- Performance measurement and benchmarking
+- Stopwatch for timing operations
+- Function utilities (debounce, throttle, memoize)
+
+### 📏 Interval utilities
+
+- Create and validate intervals
+- Overlap, intersection, merge, subtraction
+- Split by day and total coverage
+- Normalize and compute durations
+
+### 🌐 Timezone utilities
+
+- Validate IANA timezones
+- Get offsets and compare zones
+- Format in specific timezone
+- Convert absolute moment to zone components
+- Reinterpret wall-clock times
+
+### 🕘 Working hours utilities
+
+- Define working day patterns and breaks
+- Check working day/time
+- Compute working time between dates
+- Add working hours across days
+- Find next working time
+
+### 🎯 Range preset utilities
+
+- Today / yesterday / tomorrow
+- Last/next N days windows
+- This/last/next week, month, quarter, year
+- Rolling windows and quarter helpers
+
+### 🧱 Constants
+
+- Milliseconds & seconds per unit
+- Time unit and formatting option types
+
+## 📦 Installation
+
+```bash
+npm install ts-time-utils
+```
+
+## 🔧 Usage
+
+### Import everything (not recommended for production)
+
+```ts
+import { formatDuration, timeAgo, isValidDate } from "ts-time-utils";
+```
+
+### Import by category (better for tree-shaking)
+
+```ts
+import { formatDuration, timeAgo } from "ts-time-utils/format";
+import { differenceInUnits, addTime } from "ts-time-utils/calculate";
+import { isValidDate, isLeapYear } from "ts-time-utils/validate";
+import { calculateAge, getNextBirthday } from "ts-time-utils/age";
+import { getWeekNumber, getQuarter } from "ts-time-utils/calendar";
+import { parseDate, parseRelativeDate } from "ts-time-utils/parse";
+import { sleep, benchmark, Stopwatch } from "ts-time-utils/performance";
+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";
+```
+
+## 📖 Examples
+
+### Format Utilities
+
+```ts
+import { formatDuration, timeAgo, parseDuration } from "ts-time-utils/format";
+
+// Format durations
+formatDuration(65000); // "1 minute, 5 seconds"
+formatDuration(65000, { short: true }); // "1m 5s"
+formatDuration(90061000, { maxUnits: 2 }); // "1 day, 1 hour"
+
+// Time ago strings
+timeAgo(new Date(Date.now() - 60000)); // "1 minute ago"
+timeAgo(new Date(Date.now() + 60000)); // "in 1 minute"
+
+// Parse duration strings
+parseDuration("1h 30m"); // 5400000 (milliseconds)
+parseDuration("2 days 3 hours"); // 183600000
+```
+
+### Calculate Utilities
+
+```ts
+import { differenceInUnits, addTime, startOf } from "ts-time-utils/calculate";
+
+// Date calculations
+differenceInUnits(new Date("2025-09-01"), new Date("2025-09-11"), "days"); // 10
+
+addTime(new Date(), 5, "hours"); // 5 hours from now
+startOf(new Date(), "day"); // Start of today (00:00:00)
+```
+
+### Validation Utilities
+
+```ts
+import { isValidDate, isLeapYear, isWeekend } from "ts-time-utils/validate";
+
+// Validations
+isValidDate(new Date("2025-13-01")); // false
+isLeapYear(2024); // true
+isWeekend(new Date("2025-09-13")); // true (Saturday)
+```
+
+### Age Utilities
+
+```ts
+import {
+  calculateAge,
+  getLifeStage,
+  getNextBirthday,
+  isBirthday,
+} from "ts-time-utils/age";
+
+// Age calculations
+calculateAge(new Date("1990-05-15")); // { years: 34, months: 4, days: 2 }
+getLifeStage(25); // "adult"
+getNextBirthday(new Date("1990-05-15")); // Next May 15th
+isBirthday(new Date("1990-05-15"), new Date("2025-05-15")); // true
+```
+
+### Calendar Utilities
+
+```ts
+import {
+  getWeekNumber,
+  getQuarter,
+  getEaster,
+  getDaysInMonth,
+} from "ts-time-utils/calendar";
+
+// Calendar operations
+getWeekNumber(new Date("2025-01-15")); // 3
+getQuarter(new Date("2025-07-15")); // 3
+getEaster(2025); // Date object for Easter Sunday 2025
+getDaysInMonth(2, 2024); // 29 (leap year)
+```
+
+### Parse Utilities
+
+```ts
+import {
+  parseDate,
+  parseRelativeDate,
+  parseCustomFormat,
+} from "ts-time-utils/parse";
+
+// Advanced parsing
+parseDate("2025-02-30"); // null (invalid date)
+parseDate("Dec 25, 2025"); // Date object
+parseRelativeDate("tomorrow"); // Date for tomorrow
+parseCustomFormat("25/12/2025", "DD/MM/YYYY"); // Date object
+```
+
+### Performance Utilities
+
+```ts
+import {
+  sleep,
+  timeout,
+  benchmark,
+  Stopwatch,
+  debounce,
+} from "ts-time-utils/performance";
+
+// Async utilities
+await sleep(1000); // Wait 1 second
+await timeout(promise, 5000); // Timeout after 5 seconds
+
+// Performance measurement
+const result = await benchmark(() => heavyOperation(), 10); // Run 10 times
+const stopwatch = new Stopwatch();
+stopwatch.start();
+// ... operations
+console.log(stopwatch.getElapsed()); // Get elapsed time
+
+// Function utilities
+const debouncedFn = debounce(() => console.log("Called!"), 300);
+```
+
+### Interval Utilities
+
+```ts
+import {
+  createInterval,
+  intervalsOverlap,
+  mergeIntervals,
+} from "ts-time-utils/interval";
+
+const a = createInterval("2025-01-01", "2025-01-05");
+const b = createInterval("2025-01-04", "2025-01-10");
+intervalsOverlap(a!, b!); // true
+const merged = mergeIntervals([a!, b!]);
+```
+
+### Timezone Utilities
+
+```ts
+import { formatInTimeZone, getTimezoneOffset } from "ts-time-utils/timezone";
+formatInTimeZone(new Date(), "Europe/Paris", {
+  hour: "2-digit",
+  minute: "2-digit",
+});
+getTimezoneOffset("America/New_York"); // e.g. -300 (minutes)
+```
+
+### Working Hours Utilities
+
+```ts
+import { isWorkingTime, addWorkingHours } from "ts-time-utils/workingHours";
+
+isWorkingTime(new Date()); // depends on config
+addWorkingHours(new Date(), 10); // adds 10 working hours, skipping off-hours
+```
+
+### Range Preset Utilities
+
+```ts
+import { lastNDays, thisWeek, quarterRange } from "ts-time-utils/rangePresets";
+
+const last7 = lastNDays(7);
+const week = thisWeek();
+const quarter = quarterRange();
+```
+
+## 📊 API Reference
+
+### Format Functions
+
+- `formatDuration(ms, options?)` - Format milliseconds to readable duration
+- `timeAgo(date, options?)` - Get "time ago" string for past/future dates
+- `formatTime(date, format?)` - Format time as 12h/24h/ISO
+- `parseDuration(duration)` - Parse duration string to milliseconds
+
+### Calculate Functions
+
+- `differenceInUnits(date1, date2, unit?, precise?)` - Calculate difference between dates
+- `addTime(date, amount, unit)` - Add time to a date
+- `subtractTime(date, amount, unit)` - Subtract time from a date
+- `startOf(date, unit)` - Get start of time period
+- `endOf(date, unit)` - Get end of time period
+- `isBetween(date, start, end)` - Check if date is between two dates
+- `businessDaysBetween(start, end)` - Count business days between dates
+
+### Validation Functions
+
+- `isValidDate(date)` - Check if date is valid
+- `isLeapYear(year)` - Check if year is leap year
+- `isPast(date)` / `isFuture(date)` - Check if date is past/future
+- `isToday(date)` / `isYesterday(date)` / `isTomorrow(date)` - Date comparisons
+- `isSameDay(date1, date2)` - Check if dates are same day
+- `isWeekend(date)` / `isWeekday(date)` - Check day type
+- `isValidTimeString(time)` - Validate HH:MM time format
+- `isValidISOString(dateString)` - Validate ISO 8601 date string
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build (both CommonJS and ES modules)
+npm run build
+
+# Run tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Lint code
+npm run lint
+```
+
+## 📄 License
+
+MIT

package/dist/age.d.ts

@@ -0,0 +1,49 @@
+import { TimeUnit } from './constants.js';
+/**
+ * Age calculation result
+ */
+export interface AgeResult {
+    years: number;
+    months: number;
+    days: number;
+    totalDays: number;
+    totalMonths: number;
+}
+/**
+ * Calculate detailed age from birth date
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate age from (defaults to now)
+ */
+export declare function calculateAge(birthDate: Date, referenceDate?: Date): AgeResult;
+/**
+ * Get age in specific units
+ * @param birthDate - date of birth
+ * @param unit - unit to return age in
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export declare function getAgeInUnits(birthDate: Date, unit: TimeUnit, referenceDate?: Date): number;
+/**
+ * Determine life stage based on age
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export declare function getLifeStage(birthDate: Date, referenceDate?: Date): 'infant' | 'child' | 'teen' | 'adult' | 'senior';
+/**
+ * Get the next birthday date
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export declare function getNextBirthday(birthDate: Date, referenceDate?: Date): Date;
+/**
+ * Get days until next birthday
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export declare function getDaysUntilBirthday(birthDate: Date, referenceDate?: Date): number;
+/**
+ * Check if today is someone's birthday
+ * @param birthDate - date of birth
+ * @param referenceDate - date to check (defaults to now)
+ */
+export declare function isBirthday(birthDate: Date, referenceDate?: Date): boolean;
+//# sourceMappingURL=age.d.ts.map

package/dist/age.d.ts.map

@@ -0,0 +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"}

package/dist/age.js

@@ -0,0 +1,106 @@
+/**
+ * Calculate detailed age from birth date
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate age from (defaults to now)
+ */
+export function calculateAge(birthDate, referenceDate = new Date()) {
+    const birth = new Date(birthDate);
+    const reference = new Date(referenceDate);
+    let years = reference.getFullYear() - birth.getFullYear();
+    let months = reference.getMonth() - birth.getMonth();
+    let days = reference.getDate() - birth.getDate();
+    // Adjust for negative days
+    if (days < 0) {
+        months--;
+        const lastMonth = new Date(reference.getFullYear(), reference.getMonth(), 0);
+        days += lastMonth.getDate();
+    }
+    // Adjust for negative months
+    if (months < 0) {
+        years--;
+        months += 12;
+    }
+    const totalDays = Math.floor((reference.getTime() - birth.getTime()) / (1000 * 60 * 60 * 24));
+    const totalMonths = years * 12 + months;
+    return { years, months, days, totalDays, totalMonths };
+}
+/**
+ * Get age in specific units
+ * @param birthDate - date of birth
+ * @param unit - unit to return age in
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export function getAgeInUnits(birthDate, unit, referenceDate = new Date()) {
+    const diffMs = referenceDate.getTime() - birthDate.getTime();
+    switch (unit) {
+        case 'years':
+            return Math.floor(diffMs / (1000 * 60 * 60 * 24 * 365.25));
+        case 'months':
+            return Math.floor(diffMs / (1000 * 60 * 60 * 24 * 30.44));
+        case 'weeks':
+            return Math.floor(diffMs / (1000 * 60 * 60 * 24 * 7));
+        case 'days':
+            return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+        case 'hours':
+            return Math.floor(diffMs / (1000 * 60 * 60));
+        case 'minutes':
+            return Math.floor(diffMs / (1000 * 60));
+        case 'seconds':
+            return Math.floor(diffMs / 1000);
+        case 'milliseconds':
+        default:
+            return diffMs;
+    }
+}
+/**
+ * Determine life stage based on age
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export function getLifeStage(birthDate, referenceDate = new Date()) {
+    const ageInYears = getAgeInUnits(birthDate, 'years', referenceDate);
+    if (ageInYears < 2)
+        return 'infant';
+    if (ageInYears < 13)
+        return 'child';
+    if (ageInYears < 18)
+        return 'teen';
+    if (ageInYears < 65)
+        return 'adult';
+    return 'senior';
+}
+/**
+ * Get the next birthday date
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export function getNextBirthday(birthDate, referenceDate = new Date()) {
+    const birth = new Date(birthDate);
+    const reference = new Date(referenceDate);
+    const nextBirthday = new Date(reference.getFullYear(), birth.getMonth(), birth.getDate());
+    // If birthday has passed this year, get next year's birthday
+    if (nextBirthday <= reference) {
+        nextBirthday.setFullYear(reference.getFullYear() + 1);
+    }
+    return nextBirthday;
+}
+/**
+ * Get days until next birthday
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export function getDaysUntilBirthday(birthDate, referenceDate = new Date()) {
+    const nextBirthday = getNextBirthday(birthDate, referenceDate);
+    return Math.ceil((nextBirthday.getTime() - referenceDate.getTime()) / (1000 * 60 * 60 * 24));
+}
+/**
+ * Check if today is someone's birthday
+ * @param birthDate - date of birth
+ * @param referenceDate - date to check (defaults to now)
+ */
+export function isBirthday(birthDate, referenceDate = new Date()) {
+    const birth = new Date(birthDate);
+    const reference = new Date(referenceDate);
+    return (birth.getMonth() === reference.getMonth() &&
+        birth.getDate() === reference.getDate());
+}

package/dist/calculate.d.ts

@@ -0,0 +1,49 @@
+import { TimeUnit } from './constants.js';
+/**
+ * Calculate difference between two dates in specified unit
+ * @param date1 - first date
+ * @param date2 - second date
+ * @param unit - unit to return the difference in
+ * @param precise - if true, returns decimal values; if false, returns integers
+ */
+export declare function differenceInUnits(date1: Date, date2: Date, unit?: TimeUnit, precise?: boolean): number;
+/**
+ * Add time to a date
+ * @param date - base date
+ * @param amount - amount to add
+ * @param unit - unit of the amount
+ */
+export declare function addTime(date: Date, amount: number, unit: TimeUnit): Date;
+/**
+ * Subtract time from a date
+ * @param date - base date
+ * @param amount - amount to subtract
+ * @param unit - unit of the amount
+ */
+export declare function subtractTime(date: Date, amount: number, unit: TimeUnit): Date;
+/**
+ * Get the start of a time period for a given date
+ * @param date - input date
+ * @param unit - time unit to get the start of
+ */
+export declare function startOf(date: Date, unit: 'day' | 'week' | 'month' | 'year' | 'hour' | 'minute'): Date;
+/**
+ * Get the end of a time period for a given date
+ * @param date - input date
+ * @param unit - time unit to get the end of
+ */
+export declare function endOf(date: Date, unit: 'day' | 'week' | 'month' | 'year' | 'hour' | 'minute'): Date;
+/**
+ * Check if a date is between two other dates
+ * @param date - date to check
+ * @param start - start date (inclusive)
+ * @param end - end date (inclusive)
+ */
+export declare function isBetween(date: Date, start: Date, end: Date): boolean;
+/**
+ * Get the number of business days between two dates (excludes weekends)
+ * @param startDate - start date
+ * @param endDate - end date
+ */
+export declare function businessDaysBetween(startDate: Date, endDate: Date): number;
+//# sourceMappingURL=calculate.d.ts.map

package/dist/calculate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculate.d.ts","sourceRoot":"","sources":["../src/calculate.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,QAAQ,EACT,MAAM,gBAAgB,CAAC;AAExB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,IAAI,EACX,IAAI,GAAE,QAAyB,EAC/B,OAAO,GAAE,OAAc,GACtB,MAAM,CAkCR;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAmCxE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CA4BrG;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CA4BnG;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGrE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAa1E"}