ts-time-utils 3.0.4 → 4.1.0

package/README.md

@@ -1,6 +1,6 @@
 # ts-time-utils
 
-A comprehensive TypeScript utility library for time, dates, durations, and calendar operations. Zero dependencies, full tree-shaking support, 320+ functions across 26 categories.
+A comprehensive TypeScript utility library for time, dates, durations, and calendar operations. Zero dependencies, full tree-shaking support, 430+ functions across 32 categories.
 
 [![npm version](https://img.shields.io/npm/v/ts-time-utils.svg)](https://www.npmjs.com/package/ts-time-utils)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -12,7 +12,7 @@ A comprehensive TypeScript utility library for time, dates, durations, and calen
 - **Lightweight** — Import only what you need with tree-shaking support
 - **Zero dependencies** — Pure TypeScript, no external packages
 - **Type-safe** — Full TypeScript support with IntelliSense
-- **Comprehensive** — 320+ functions across 26 utility categories
+- **Comprehensive** — 430+ functions across 32 utility categories
 - **Fluent API** — Chain operations with the `chain()` API
 - **Extensible** — Plugin system for custom functionality
 
@@ -256,7 +256,7 @@ extractDatesFromText('Meeting tomorrow at 3pm');
 
 ### International Holidays
 
-Public holidays for 10 countries.
+Public holidays for 20 countries.
 
 ```ts
 import { getHolidays, isHoliday, getNextHoliday } from 'ts-time-utils/holidays';
@@ -266,7 +266,8 @@ getHolidays(2025, 'DE');      // German holidays
 isHoliday(date, 'CA');        // Is Canadian holiday?
 getNextHoliday(date, 'AU');   // Next Australian holiday
 
-// Supported: UK, NL, DE, CA, AU, IT, ES, CN, IN, US
+// Supported: UK, NL, DE, CA, AU, IT, ES, CN, IN, US,
+//            JP, FR, BR, MX, KR, SG, PL, SE, BE, CH
 ```
 
 ### Locale
@@ -381,6 +382,69 @@ thisWeek();     // Current week
 thisMonth();    // Current month
 ```
 
+### Non-Gregorian Calendars
+
+Convert dates between calendar systems using Intl.DateTimeFormat.
+
+```ts
+import { toHebrewDate, toIslamicDate, toJapaneseDate, getChineseZodiac } from 'ts-time-utils/calendars';
+
+toHebrewDate(new Date());        // { year: 5785, month: 4, day: 23, calendar: 'hebrew' }
+toIslamicDate(new Date());       // { year: 1446, month: 7, day: 1, calendar: 'islamic-umalqura' }
+toJapaneseDate(new Date());      // { year: 6, era: 'Reiwa', calendar: 'japanese' }
+getChineseZodiac(2024);          // 'Dragon'
+
+// Supported: Hebrew, Islamic, Buddhist, Japanese, Persian, Chinese
+```
+
+### Temporal API Compatibility
+
+Future-proof with Temporal-like objects that work with native Date.
+
+```ts
+import { toPlainDate, toPlainDateTime, toZonedDateTime, toInstant } from 'ts-time-utils/temporal';
+
+const date = toPlainDate(2024, 3, 25);
+date.add({ days: 7 });           // PlainDate
+date.until(otherDate);           // Duration
+date.dayOfWeek;                  // 1 (Monday, ISO)
+
+const zdt = toZonedDateTime(new Date(), 'America/New_York');
+zdt.hour;                        // Hour in that timezone
+zdt.toInstant();                 // Epoch-based Instant
+
+const instant = toInstant(Date.now());
+instant.toZonedDateTime('UTC');  // Convert to any timezone
+```
+
+### High-Precision Utilities
+
+Nanosecond timestamps, BigInt support, DST handling, and leap seconds.
+
+```ts
+import {
+  createNanosecondTimestamp, nowNanoseconds,
+  toBigIntMs, ValidDate, isInDSTGap, leapSecondsBetween
+} from 'ts-time-utils/precision';
+
+// Nanosecond precision
+const ts = createNanosecondTimestamp(Date.now(), 500000);
+ts.totalNanoseconds;             // BigInt
+
+// BigInt timestamps for large date ranges
+toBigIntMs(new Date());          // BigInt milliseconds
+
+// DST transition detection
+isInDSTGap(new Date('2024-03-10T02:30:00'));
+
+// Validated dates (never invalid)
+const valid = ValidDate.from(date);  // Throws if invalid
+const maybe = ValidDate.tryFrom(date);  // Returns null if invalid
+
+// Leap second awareness
+leapSecondsBetween(date1, date2);  // Number of leap seconds
+```
+
 ### Parse
 
 Date parsing from various formats.
@@ -394,6 +458,98 @@ parseTime('2:30 PM');  // { hour: 14, minute: 30 }
 autoDetectFormat('2025-09-14');  // 'YYYY-MM-DD'
 ```
 
+### Scheduling
+
+Appointment slots, availability, and booking conflict detection.
+
+```ts
+import {
+  generateSlots, getAvailableSlots, findNextAvailable,
+  hasConflict, findConflicts, mergeBookings
+} from 'ts-time-utils/scheduling';
+
+// Generate 30-min slots for a day
+const slots = generateSlots(new Date(), {
+  slotDuration: 30,
+  workingHours: { startTime: { hour: 9, minute: 0 }, endTime: { hour: 17, minute: 0 } }
+});
+
+// Find available slots (excluding existing bookings)
+const available = getAvailableSlots(new Date(), existingBookings, config);
+
+// Find next available slot of specific duration
+findNextAvailable(new Date(), bookings, 60, config);  // 60-min slot
+
+// Check for conflicts
+hasConflict(bookings, proposedSlot);  // true/false
+findConflicts(bookings, proposedSlot);  // Array of conflicting bookings
+
+// Merge adjacent bookings
+mergeBookings(bookings);
+```
+
+### Finance
+
+Market hours, trading days, and settlement date calculations.
+
+```ts
+import {
+  isMarketOpen, isTradingDay, getMarketHours,
+  getNextMarketOpen, addTradingDays, getSettlementDate,
+  eachTradingDay, getOptionsExpiration
+} from 'ts-time-utils/finance';
+
+// Check market status
+isMarketOpen(new Date(), 'NYSE');      // Is NYSE open right now?
+isTradingDay(new Date(), 'NASDAQ');    // Is today a trading day?
+getMarketHours('NYSE');                // { open: {hour:9,minute:30}, close: {hour:16,minute:0} }
+
+// Market timing
+getNextMarketOpen(new Date());         // Next market open time
+addTradingDays(new Date(), 5);         // 5 trading days from now
+
+// Settlement (T+2, etc.)
+getSettlementDate(tradeDate, 2);       // T+2 settlement date
+
+// Iterate trading days
+eachTradingDay(start, end);            // Array of trading days
+
+// Options expiration (3rd Friday)
+getOptionsExpiration(2025, 3);         // March 2025 expiration
+```
+
+### Healthcare
+
+Medication scheduling, shift patterns, and compliance windows.
+
+```ts
+import {
+  getMedicationTimes, getNextMedicationTime, parseMedicationFrequency,
+  generateShiftSchedule, getShiftForTime, isOnShift,
+  createOnCallRotation, getOnCallStaff,
+  getComplianceDeadline, timeUntilDeadline
+} from 'ts-time-utils/healthcare';
+
+// Medication times (BID = twice daily, TID = 3x daily, etc.)
+getMedicationTimes(new Date(), 'BID');   // [8am, 8pm] (default wake/sleep times)
+getMedicationTimes(new Date(), 'q6h');   // Every 6 hours
+getNextMedicationTime(now, 'TID');       // Next scheduled dose
+parseMedicationFrequency('twice daily'); // 'BID'
+
+// Shift scheduling
+generateShiftSchedule(start, end, { pattern: '12hr', startTime: { hour: 7, minute: 0 } });
+getShiftForTime(now, shiftConfig);       // Current shift
+isOnShift(now, shiftStart, config);      // Is within shift?
+
+// On-call rotations
+const rotation = createOnCallRotation(start, end, ['Dr. Smith', 'Dr. Jones'], 24);
+getOnCallStaff(now, rotation);           // Who's on call?
+
+// Compliance windows
+getComplianceDeadline(eventDate, 72);    // 72-hour window
+timeUntilDeadline(eventDate, deadline);  // Duration remaining
+```
+
 ---
 
 ## Plugin System
@@ -432,12 +588,15 @@ For complete API documentation, see the [Playground & Docs](https://ts-time-util
 | Module | Description |
 |--------|-------------|
 | `format` | Duration formatting, time ago, date patterns |
-| `calculate` | Date arithmetic, differences, period boundaries |
+| `calculate` | Date arithmetic, differences, rounding |
 | `validate` | Date validation, comparisons, type checks |
 | `duration` | Immutable Duration class with arithmetic |
 | `chain` | Fluent chainable API |
 | `timezone` | Timezone conversions, DST handling |
 | `calendar` | ISO weeks, quarters, holidays, grids |
+| `calendars` | Non-Gregorian calendars (Hebrew, Islamic, etc.) |
+| `temporal` | Temporal API compatibility layer |
+| `precision` | Nanoseconds, BigInt, DST, leap seconds |
 | `dateRange` | Range operations: overlap, gaps, merge |
 | `recurrence` | RRULE-inspired recurring patterns |
 | `cron` | Cron expression parsing and matching |
@@ -445,7 +604,7 @@ For complete API documentation, see the [Playground & Docs](https://ts-time-util
 | `compare` | Date sorting, grouping, statistics |
 | `iterate` | Date iteration and counting |
 | `naturalLanguage` | Natural language date parsing |
-| `holidays` | International holiday calculations |
+| `holidays` | International holidays (20 countries) |
 | `locale` | Multi-language formatting (40+ locales) |
 | `workingHours` | Business hours calculations |
 | `serialize` | JSON date serialization |
@@ -455,6 +614,9 @@ For complete API documentation, see the [Playground & Docs](https://ts-time-util
 | `interval` | Time interval operations |
 | `rangePresets` | Common date range presets |
 | `parse` | Date parsing from various formats |
+| `scheduling` | Appointment slots, availability, booking |
+| `finance` | Market hours, trading days, settlement |
+| `healthcare` | Medication schedules, shifts, on-call |
 | `plugins` | Plugin system for extensions |
 | `constants` | Time constants and types |
 
@@ -469,6 +631,24 @@ npm test         # Run tests
 npm run lint     # Lint code
 ```
 
+## Releasing
+
+Releases are automated via GitHub Actions with npm trusted publishing (OIDC).
+
+**To release a new version:**
+
+```bash
+git tag v4.0.1        # Create tag (use semantic versioning)
+git push --tags       # Push tag → triggers publish workflow
+```
+
+The workflow automatically:
+1. Sets `package.json` version from tag
+2. Runs lint, tests, and build
+3. Publishes to npm with provenance
+
+**Version format:** Tags must match `v*` pattern (e.g., `v4.0.0`, `v4.1.0-beta.1`)
+
 ## License
 
 MIT

package/dist/calculate.d.ts

@@ -51,4 +51,29 @@ export declare function isBetween(date: Date, start: Date, end: Date, inclusive?
  * @param endDate - end date
  */
 export declare function businessDaysBetween(startDate: Date, endDate: Date): number;
+/**
+ * Round a date to the nearest unit (rounds to closest)
+ * @param date - date to round
+ * @param unit - unit to round to
+ * @example
+ * roundToNearestUnit(new Date('2024-03-15T14:37:00'), 'hour') // 15:00
+ * roundToNearestUnit(new Date('2024-03-15T14:22:00'), 'hour') // 14:00
+ */
+export declare function roundToNearestUnit(date: Date, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month'): Date;
+/**
+ * Round a date up (ceiling) to the specified unit
+ * @param date - date to round
+ * @param unit - unit to round to
+ * @example
+ * ceilDate(new Date('2024-03-15T14:01:00'), 'hour') // 15:00
+ */
+export declare function ceilDate(date: Date, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month'): Date;
+/**
+ * Round a date down (floor) to the specified unit
+ * @param date - date to round
+ * @param unit - unit to round to
+ * @example
+ * floorDate(new Date('2024-03-15T14:59:00'), 'hour') // 14:00
+ */
+export declare function floorDate(date: Date, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month'): Date;
 //# sourceMappingURL=calculate.d.ts.map

package/dist/calculate.d.ts.map

@@ -1 +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,CAgDxE;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;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,GAAE,OAAc,GAAG,OAAO,CAShG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAa1E"}
+{"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,CAgDxE;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;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,GAAE,OAAc,GAAG,OAAO,CAShG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAa1E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAC5D,IAAI,CA2CN;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAC5D,IAAI,CA0BN;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAC5D,IAAI,CA8BN"}

package/dist/calculate.js

@@ -201,3 +201,128 @@ export function businessDaysBetween(startDate, endDate) {
     }
     return count;
 }
+/**
+ * Round a date to the nearest unit (rounds to closest)
+ * @param date - date to round
+ * @param unit - unit to round to
+ * @example
+ * roundToNearestUnit(new Date('2024-03-15T14:37:00'), 'hour') // 15:00
+ * roundToNearestUnit(new Date('2024-03-15T14:22:00'), 'hour') // 14:00
+ */
+export function roundToNearestUnit(date, unit) {
+    const d = new Date(date);
+    switch (unit) {
+        case 'second':
+            if (d.getMilliseconds() >= 500)
+                d.setSeconds(d.getSeconds() + 1);
+            d.setMilliseconds(0);
+            break;
+        case 'minute':
+            if (d.getSeconds() >= 30)
+                d.setMinutes(d.getMinutes() + 1);
+            d.setSeconds(0, 0);
+            break;
+        case 'hour':
+            if (d.getMinutes() >= 30)
+                d.setHours(d.getHours() + 1);
+            d.setMinutes(0, 0, 0);
+            break;
+        case 'day':
+            if (d.getHours() >= 12)
+                d.setDate(d.getDate() + 1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        case 'week': {
+            const dayOfWeek = d.getDay();
+            const daysFromMonday = dayOfWeek === 0 ? 6 : dayOfWeek - 1;
+            if (daysFromMonday >= 4) {
+                d.setDate(d.getDate() + (7 - daysFromMonday));
+            }
+            else {
+                d.setDate(d.getDate() - daysFromMonday);
+            }
+            d.setHours(0, 0, 0, 0);
+            break;
+        }
+        case 'month': {
+            const daysInMonth = new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate();
+            if (d.getDate() > daysInMonth / 2) {
+                d.setMonth(d.getMonth() + 1);
+            }
+            d.setDate(1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        }
+    }
+    return d;
+}
+/**
+ * Round a date up (ceiling) to the specified unit
+ * @param date - date to round
+ * @param unit - unit to round to
+ * @example
+ * ceilDate(new Date('2024-03-15T14:01:00'), 'hour') // 15:00
+ */
+export function ceilDate(date, unit) {
+    const floored = floorDate(date, unit);
+    if (floored.getTime() === date.getTime())
+        return new Date(date);
+    const d = new Date(floored);
+    switch (unit) {
+        case 'second':
+            d.setSeconds(d.getSeconds() + 1);
+            break;
+        case 'minute':
+            d.setMinutes(d.getMinutes() + 1);
+            break;
+        case 'hour':
+            d.setHours(d.getHours() + 1);
+            break;
+        case 'day':
+            d.setDate(d.getDate() + 1);
+            break;
+        case 'week':
+            d.setDate(d.getDate() + 7);
+            break;
+        case 'month':
+            d.setMonth(d.getMonth() + 1);
+            break;
+    }
+    return d;
+}
+/**
+ * Round a date down (floor) to the specified unit
+ * @param date - date to round
+ * @param unit - unit to round to
+ * @example
+ * floorDate(new Date('2024-03-15T14:59:00'), 'hour') // 14:00
+ */
+export function floorDate(date, unit) {
+    const d = new Date(date);
+    switch (unit) {
+        case 'second':
+            d.setMilliseconds(0);
+            break;
+        case 'minute':
+            d.setSeconds(0, 0);
+            break;
+        case 'hour':
+            d.setMinutes(0, 0, 0);
+            break;
+        case 'day':
+            d.setHours(0, 0, 0, 0);
+            break;
+        case 'week': {
+            const dayOfWeek = d.getDay();
+            const daysFromMonday = dayOfWeek === 0 ? 6 : dayOfWeek - 1;
+            d.setDate(d.getDate() - daysFromMonday);
+            d.setHours(0, 0, 0, 0);
+            break;
+        }
+        case 'month':
+            d.setDate(1);
+            d.setHours(0, 0, 0, 0);
+            break;
+    }
+    return d;
+}

package/dist/calendar.d.ts

@@ -182,4 +182,49 @@ export declare function getEndOfWeek(date: Date): Date;
  * @param month - month (0-11)
  */
 export declare function getWeeksInMonth(year: number, month: number): Date[][];
+/**
+ * Get the ISO week-numbering year (year the week belongs to)
+ * @param date - date to get week year for
+ * @returns The year the ISO week belongs to (may differ from calendar year)
+ * @example
+ * getWeekYear(new Date('2024-01-01')) // 2024
+ * getWeekYear(new Date('2020-12-31')) // 2020 (belongs to week 53 of 2020)
+ */
+export declare function getWeekYear(date: Date): number;
+/**
+ * Get the last day of the decade containing the date
+ * @param date - any date
+ * @returns December 31 of the last year of the decade
+ * @example
+ * lastDayOfDecade(new Date('2024-06-15')) // 2029-12-31
+ */
+export declare function lastDayOfDecade(date: Date): Date;
+/**
+ * Get the first day of the decade containing the date
+ * @param date - any date
+ * @returns January 1 of the first year of the decade
+ * @example
+ * firstDayOfDecade(new Date('2024-06-15')) // 2020-01-01
+ */
+export declare function firstDayOfDecade(date: Date): Date;
+/**
+ * Get the last day of the century containing the date
+ * @param date - any date
+ * @returns December 31 of the last year of the century
+ * @example
+ * lastDayOfCentury(new Date('2024-06-15')) // 2099-12-31
+ */
+export declare function lastDayOfCentury(date: Date): Date;
+/**
+ * Get the start of a quarter
+ * @param date - any date
+ * @returns First day of the quarter
+ */
+export declare function getStartOfQuarter(date: Date): Date;
+/**
+ * Get the end of a quarter
+ * @param date - any date
+ * @returns Last day of the quarter
+ */
+export declare function getEndOfQuarter(date: Date): Date;
 //# sourceMappingURL=calendar.d.ts.map

package/dist/calendar.d.ts.map

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

package/dist/calendar.js

@@ -376,3 +376,71 @@ export function getWeeksInMonth(year, month) {
     }
     return weeks;
 }
+/**
+ * Get the ISO week-numbering year (year the week belongs to)
+ * @param date - date to get week year for
+ * @returns The year the ISO week belongs to (may differ from calendar year)
+ * @example
+ * getWeekYear(new Date('2024-01-01')) // 2024
+ * getWeekYear(new Date('2020-12-31')) // 2020 (belongs to week 53 of 2020)
+ */
+export function getWeekYear(date) {
+    const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+    const dayNum = d.getUTCDay() || 7;
+    d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+    return d.getUTCFullYear();
+}
+/**
+ * Get the last day of the decade containing the date
+ * @param date - any date
+ * @returns December 31 of the last year of the decade
+ * @example
+ * lastDayOfDecade(new Date('2024-06-15')) // 2029-12-31
+ */
+export function lastDayOfDecade(date) {
+    const year = date.getFullYear();
+    const decadeEnd = Math.floor(year / 10) * 10 + 9;
+    return new Date(decadeEnd, 11, 31);
+}
+/**
+ * Get the first day of the decade containing the date
+ * @param date - any date
+ * @returns January 1 of the first year of the decade
+ * @example
+ * firstDayOfDecade(new Date('2024-06-15')) // 2020-01-01
+ */
+export function firstDayOfDecade(date) {
+    const year = date.getFullYear();
+    const decadeStart = Math.floor(year / 10) * 10;
+    return new Date(decadeStart, 0, 1);
+}
+/**
+ * Get the last day of the century containing the date
+ * @param date - any date
+ * @returns December 31 of the last year of the century
+ * @example
+ * lastDayOfCentury(new Date('2024-06-15')) // 2099-12-31
+ */
+export function lastDayOfCentury(date) {
+    const year = date.getFullYear();
+    const centuryEnd = Math.floor(year / 100) * 100 + 99;
+    return new Date(centuryEnd, 11, 31);
+}
+/**
+ * Get the start of a quarter
+ * @param date - any date
+ * @returns First day of the quarter
+ */
+export function getStartOfQuarter(date) {
+    const month = Math.floor(date.getMonth() / 3) * 3;
+    return new Date(date.getFullYear(), month, 1);
+}
+/**
+ * Get the end of a quarter
+ * @param date - any date
+ * @returns Last day of the quarter
+ */
+export function getEndOfQuarter(date) {
+    const month = Math.floor(date.getMonth() / 3) * 3 + 2;
+    return new Date(date.getFullYear(), month + 1, 0, 23, 59, 59, 999);
+}