ts-time-utils 3.0.4 → 4.0.1

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, 400+ functions across 29 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** — 400+ functions across 29 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.
@@ -432,12 +496,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 +512,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 |
@@ -469,6 +536,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);
+}

package/dist/calendars.d.ts

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Non-Gregorian calendar conversions using Intl.DateTimeFormat
+ * Supports Hebrew, Islamic, Buddhist, Japanese, Persian, and Chinese calendars
+ */
+export interface CalendarDate {
+    year: number;
+    month: number;
+    day: number;
+    era?: string;
+    calendar: string;
+}
+export interface HebrewDate extends CalendarDate {
+    calendar: 'hebrew';
+}
+export interface IslamicDate extends CalendarDate {
+    calendar: 'islamic' | 'islamic-umalqura' | 'islamic-civil';
+}
+export interface BuddhistDate extends CalendarDate {
+    calendar: 'buddhist';
+}
+export interface JapaneseDate extends CalendarDate {
+    calendar: 'japanese';
+    era: string;
+}
+export interface PersianDate extends CalendarDate {
+    calendar: 'persian';
+}
+export interface ChineseDate extends CalendarDate {
+    calendar: 'chinese';
+    cycleYear?: number;
+}
+export type CalendarType = 'hebrew' | 'islamic' | 'islamic-umalqura' | 'islamic-civil' | 'buddhist' | 'japanese' | 'persian' | 'chinese';
+/**
+ * Convert Gregorian date to Hebrew calendar
+ * @example toHebrewDate(new Date('2024-03-25')) // { year: 5784, month: 6, day: 15, calendar: 'hebrew' }
+ */
+export declare function toHebrewDate(date: Date): HebrewDate;
+/**
+ * Convert Gregorian date to Islamic calendar (default: islamic-umalqura)
+ * @param date - Date to convert
+ * @param variant - Islamic calendar variant: 'islamic', 'islamic-umalqura', 'islamic-civil'
+ * @example toIslamicDate(new Date('2024-03-25')) // { year: 1445, month: 9, day: 15, calendar: 'islamic-umalqura' }
+ */
+export declare function toIslamicDate(date: Date, variant?: 'islamic' | 'islamic-umalqura' | 'islamic-civil'): IslamicDate;
+/**
+ * Convert Gregorian date to Buddhist calendar (Thai Solar)
+ * Buddhist Era = Gregorian Year + 543
+ * @example toBuddhistDate(new Date('2024-03-25')) // { year: 2567, month: 3, day: 25, calendar: 'buddhist' }
+ */
+export declare function toBuddhistDate(date: Date): BuddhistDate;
+/**
+ * Convert Gregorian date to Japanese calendar with era
+ * @example toJapaneseDate(new Date('2024-03-25')) // { year: 6, month: 3, day: 25, era: 'Reiwa', calendar: 'japanese' }
+ */
+export declare function toJapaneseDate(date: Date): JapaneseDate;
+/**
+ * Convert Gregorian date to Persian (Jalali/Solar Hijri) calendar
+ * @example toPersianDate(new Date('2024-03-20')) // { year: 1403, month: 1, day: 1, calendar: 'persian' }
+ */
+export declare function toPersianDate(date: Date): PersianDate;
+/**
+ * Convert Gregorian date to Chinese lunar calendar
+ * @example toChineseDate(new Date('2024-02-10')) // { year: 4721, month: 1, day: 1, calendar: 'chinese' }
+ */
+export declare function toChineseDate(date: Date): ChineseDate;
+/**
+ * Format date in specified calendar system
+ * @param date - Date to format
+ * @param calendar - Calendar system to use
+ * @param locale - Locale for formatting (default: 'en')
+ * @param options - Additional Intl.DateTimeFormat options
+ */
+export declare function formatInCalendar(date: Date, calendar: CalendarType, locale?: string, options?: Intl.DateTimeFormatOptions): string;
+/**
+ * Get month names for a specific calendar system
+ * @param calendar - Calendar system
+ * @param locale - Locale for month names (default: 'en')
+ * @param format - Month name format: 'long', 'short', 'narrow'
+ */
+export declare function getCalendarMonthNames(calendar: CalendarType, locale?: string, format?: 'long' | 'short' | 'narrow'): string[];
+/**
+ * Get era name for Japanese calendar
+ * @param date - Date to get era for
+ * @param format - Era format: 'long', 'short', 'narrow'
+ */
+export declare function getJapaneseEra(date: Date, format?: 'long' | 'short' | 'narrow'): string;
+/**
+ * Get all Japanese era names with their start dates
+ */
+export declare function getJapaneseEras(): Array<{
+    name: string;
+    start: Date;
+}>;
+/**
+ * Check if a Hebrew year is a leap year (has 13 months)
+ * @param hebrewYear - Year in Hebrew calendar
+ */
+export declare function isHebrewLeapYear(hebrewYear: number): boolean;
+/**
+ * Get Hebrew month name
+ * @param month - Month number (1-13)
+ * @param isLeapYear - Whether the year is a leap year
+ */
+export declare function getHebrewMonthName(month: number, isLeapYear?: boolean): string;
+/**
+ * Get Islamic month name
+ * @param month - Month number (1-12)
+ */
+export declare function getIslamicMonthName(month: number): string;
+/**
+ * Get Persian month name
+ * @param month - Month number (1-12)
+ */
+export declare function getPersianMonthName(month: number): string;
+/**
+ * Check if a Persian year is a leap year
+ * Uses the 2820-year cycle algorithm
+ */
+export declare function isPersianLeapYear(persianYear: number): boolean;
+/**
+ * Get Chinese zodiac animal for a year
+ * @param gregorianYear - Gregorian year
+ */
+export declare function getChineseZodiac(gregorianYear: number): string;
+/**
+ * Get Chinese element for a year
+ * @param gregorianYear - Gregorian year
+ */
+export declare function getChineseElement(gregorianYear: number): string;
+/**
+ * Get full Chinese zodiac description (element + animal)
+ * @param gregorianYear - Gregorian year
+ */
+export declare function getChineseZodiacFull(gregorianYear: number): string;
+/**
+ * Convert calendar date to string representation
+ */
+export declare function calendarDateToString(calendarDate: CalendarDate): string;
+/**
+ * Compare two calendar dates
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+export declare function compareCalendarDates(a: CalendarDate, b: CalendarDate): number;
+/**
+ * Get current date in specified calendar
+ */
+export declare function today(calendar: CalendarType): CalendarDate;
+/**
+ * Check if two calendar dates are the same day
+ */
+export declare function isSameCalendarDay(a: CalendarDate, b: CalendarDate): boolean;
+/**
+ * Get supported calendar systems
+ */
+export declare function getSupportedCalendars(): CalendarType[];
+//# sourceMappingURL=calendars.d.ts.map

package/dist/calendars.d.ts.map

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