ts-time-utils 4.1.0 → 4.4.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, 430+ functions across 32 categories.
+A comprehensive TypeScript utility library for time, dates, durations, and calendar operations. Zero dependencies, full tree-shaking support, 430+ functions across 32 public modules.
 
 [![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,10 +12,16 @@ 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** — 430+ functions across 32 utility categories
+- **Comprehensive** — 430+ functions across 32 public modules
 - **Fluent API** — Chain operations with the `chain()` API
 - **Extensible** — Plugin system for custom functionality
 
+## When Not To Use This Library
+
+- You only need a single built-in `Date` helper or one `Intl` formatter.
+- You want the standardized Temporal API rather than a utility library.
+- You need a mutable Moment-style wrapper with implicit global locale state.
+
 ## Installation
 
 ```bash
@@ -47,6 +53,16 @@ import { differenceInUnits } from 'ts-time-utils/calculate';
 import { isValidDate } from 'ts-time-utils/validate';
 ```
 
+Every public module is also available as a subpath import such as
+`ts-time-utils/timezone`, `ts-time-utils/workingHours`, or
+`ts-time-utils/naturalLanguage`.
+
+### Module Selection
+
+- Use `ts-time-utils` when you need a few core utilities from different areas.
+- Use `ts-time-utils/format` or `ts-time-utils/calculate` when one module is enough.
+- Use dedicated subpaths like `ts-time-utils/chain`, `ts-time-utils/plugins`, `ts-time-utils/locale`, or `ts-time-utils/workingHours` for those feature areas.
+
 ---
 
 ## Utility Categories
@@ -125,18 +141,22 @@ chain(new Date())
   .format('YYYY-MM-DD');  // Next week Monday
 ```
 
+Plugin extensions are imported from `ts-time-utils/plugins`, and that module now loads the chain class directly. You can import `plugins` before or after `chain` without any hidden global setup.
+
 ### Timezone
 
 Timezone conversions, DST handling, and zone comparisons.
 
 ```ts
-import { formatInTimeZone, isDST, convertTimezone } from 'ts-time-utils/timezone';
+import { formatInTimeZone, isDST, convertBetweenZones } from 'ts-time-utils/timezone';
 
-formatInTimeZone(date, 'America/New_York');
+formatInTimeZone(new Date(), 'America/New_York');
 isDST(new Date('2025-07-14'), 'America/New_York');  // true
-convertTimezone(date, 'UTC', 'Asia/Tokyo');
+convertBetweenZones(new Date(), 'UTC', 'Asia/Tokyo');
 ```
 
+`isDST()` uses a yearly-offset heuristic rather than authoritative transition metadata.
+
 ### Calendar
 
 ISO weeks, quarters, holidays, and calendar grids.
@@ -191,12 +211,14 @@ recurrenceToString(weekly.rule);  // "Every week on Monday, Wednesday, Friday"
 Parse and match cron expressions.
 
 ```ts
-import { matchesCron, getNextCronDate, describeCron, CRON_PRESETS } from 'ts-time-utils/cron';
+import { parseCronExpression, matchesCron, getNextCronDate, describeCron } from 'ts-time-utils/cron';
+
+const date = new Date();
 
-matchesCron('0 9 * * 1-5', date);         // true if weekday 9am
+parseCronExpression('0 9 * * 1-5');       // minute/hour/day/month/day-of-week parts
+matchesCron(date, '0 9 * * 1-5');         // true if weekday 9am
 getNextCronDate('0 9 * * *');             // Next 9am
 describeCron('0 9 * * 1-5');              // "At 09:00 on Monday through Friday"
-CRON_PRESETS.DAILY;                       // "0 0 * * *"
 ```
 
 ### Fiscal Year
@@ -204,11 +226,13 @@ CRON_PRESETS.DAILY;                       // "0 0 * * *"
 Fiscal year utilities with configurable start month.
 
 ```ts
-import { getFiscalYear, getFiscalQuarter, FISCAL_PRESETS } from 'ts-time-utils/fiscal';
+import { getFiscalYear, getFiscalQuarter } from 'ts-time-utils/fiscal';
 
-getFiscalYear(date, FISCAL_PRESETS.UK_INDIA);     // April start
-getFiscalYear(date, FISCAL_PRESETS.AUSTRALIA);   // July start
-getFiscalYear(date, FISCAL_PRESETS.US_FEDERAL);  // October start
+const date = new Date();
+
+getFiscalYear(date, { startMonth: 4 });          // April start
+getFiscalYear(date, { startMonth: 7 });          // July start
+getFiscalYear(date, { startMonth: 10 });         // October start
 getFiscalQuarter(date, { startMonth: 4 });       // Q2 for UK fiscal
 ```
 
@@ -254,6 +278,8 @@ extractDatesFromText('Meeting tomorrow at 3pm');
 // [{ date: Date, text: 'tomorrow at 3pm', confidence: 0.9 }]
 ```
 
+`parseNaturalDate` accepts `referenceDate`, `defaultTime`, and `strict`. When `strict` is `true`, the parser only returns the library's recognized patterns and skips the permissive `Date` fallback.
+
 ### International Holidays
 
 Public holidays for 20 countries.
@@ -261,10 +287,12 @@ Public holidays for 20 countries.
 ```ts
 import { getHolidays, isHoliday, getNextHoliday } from 'ts-time-utils/holidays';
 
+const today = new Date();
+
 getHolidays(2025, 'UK');      // UK bank holidays
 getHolidays(2025, 'DE');      // German holidays
-isHoliday(date, 'CA');        // Is Canadian holiday?
-getNextHoliday(date, 'AU');   // Next Australian holiday
+isHoliday(today, 'CA');       // Is Canadian holiday?
+getNextHoliday(today, 'AU');   // Next Australian holiday
 
 // Supported: UK, NL, DE, CA, AU, IT, ES, CN, IN, US,
 //            JP, FR, BR, MX, KR, SG, PL, SE, BE, CH
@@ -277,6 +305,9 @@ Multi-language formatting with 40+ locales.
 ```ts
 import { formatRelativeTime, formatDateLocale, detectLocale } from 'ts-time-utils/locale';
 
+const pastDate = new Date(Date.now() - 2 * 60 * 60 * 1000);
+const date = new Date();
+
 formatRelativeTime(pastDate, { locale: 'es' });  // "hace 2 horas"
 formatRelativeTime(pastDate, { locale: 'de' });  // "vor 2 Stunden"
 formatDateLocale(date, 'fr', 'long');            // "15 janvier 2024"
@@ -285,14 +316,24 @@ detectLocale();                                   // Auto-detect system locale
 
 ### Working Hours
 
-Business hours calculations with break support.
+Business hours calculations with break support. These helpers use the
+`Date` values you pass in directly; if you need a different timezone's wall
+clock, adapt the instant first with a timezone helper such as
+`convertDateToZone()` or `reinterpretAsZone()`.
 
 ```ts
 import { isWorkingTime, addWorkingDays, workingDaysBetween } from 'ts-time-utils/workingHours';
 
-isWorkingTime(date, config);
-addWorkingDays(date, 5, config);
-workingDaysBetween(start, end, config);
+const config = {
+  workingDays: [1, 2, 3, 4, 5],
+  hours: { start: 9, end: 17 },
+  breaks: [{ start: 12, end: 13 }]
+};
+const now = new Date();
+
+isWorkingTime(now, config);
+addWorkingDays(now, 5, config);
+workingDaysBetween(now, new Date('2025-12-31'), config);
 ```
 
 ### Serialization
@@ -450,12 +491,12 @@ leapSecondsBetween(date1, date2);  // Number of leap seconds
 Date parsing from various formats.
 
 ```ts
-import { parseDate, parseTime, autoDetectFormat } from 'ts-time-utils/parse';
+import { parseDate, parseTime, guessDateFormat } from 'ts-time-utils/parse';
 
 parseDate('Dec 25, 2025');
 parseDate('25/12/2025', 'DD/MM/YYYY');
 parseTime('2:30 PM');  // { hour: 14, minute: 30 }
-autoDetectFormat('2025-09-14');  // 'YYYY-MM-DD'
+guessDateFormat('2025-09-14');  // 'YYYY-MM-DD'
 ```
 
 ### Scheduling
@@ -471,7 +512,10 @@ import {
 // 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 } }
+  workingHours: {
+    workingDays: [1, 2, 3, 4, 5],
+    hours: { start: 9, end: 17 }
+  }
 });
 
 // Find available slots (excluding existing bookings)
@@ -557,21 +601,20 @@ timeUntilDeadline(eventDate, deadline);  // Duration remaining
 Extend ChainedDate with custom functionality.
 
 ```ts
-import { chain, registerPlugin, createPlugin } from 'ts-time-utils/chain';
+import { chain, ChainedDate } from 'ts-time-utils/chain';
+import { extend } from 'ts-time-utils/plugins';
 
-const businessPlugin = createPlugin('business', {
-  addBusinessDays(days: number) {
+extend('business', {
+  addBusinessDays(this: ChainedDate, days: number) {
     // Implementation
     return this;
   },
-  isBusinessDay() {
+  isBusinessDay(this: ChainedDate) {
     const day = this.toDate().getDay();
     return day !== 0 && day !== 6;
   }
 });
 
-registerPlugin(businessPlugin);
-
 chain(new Date())
   .addBusinessDays(5)
   .isBusinessDay();  // true/false
@@ -628,6 +671,7 @@ For complete API documentation, see the [Playground & Docs](https://ts-time-util
 npm install      # Install dependencies
 npm run build    # Build both CJS and ESM
 npm test         # Run tests
+npm run test:package  # Verify built package exports after build
 npm run lint     # Lint code
 ```
 
@@ -638,16 +682,22 @@ 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
+git tag vX.Y.Z        # Create a semantic version tag for the release
+git push --tags       # Push tag -> triggers publish workflow
 ```
 
 The workflow automatically:
 1. Sets `package.json` version from tag
-2. Runs lint, tests, and build
+2. Runs `npm run release:verify`
 3. Publishes to npm with provenance
 
-**Version format:** Tags must match `v*` pattern (e.g., `v4.0.0`, `v4.1.0-beta.1`)
+**Version format:** Tags must match `v*` pattern (e.g., `v1.2.3`, `v1.2.3-beta.1`)
+
+Before tagging, run:
+
+```bash
+npm run release:verify
+```
 
 ## License
 

package/dist/{age.js → age.cjs}

@@ -1,9 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateAge = calculateAge;
+exports.getAgeInUnits = getAgeInUnits;
+exports.getLifeStage = getLifeStage;
+exports.getNextBirthday = getNextBirthday;
+exports.getDaysUntilBirthday = getDaysUntilBirthday;
+exports.isBirthday = isBirthday;
 /**
  * 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()) {
+function calculateAge(birthDate, referenceDate = new Date()) {
     const birth = new Date(birthDate);
     const reference = new Date(referenceDate);
     let years = reference.getFullYear() - birth.getFullYear();
@@ -30,7 +38,7 @@ export function calculateAge(birthDate, referenceDate = new Date()) {
  * @param unit - unit to return age in
  * @param referenceDate - date to calculate from (defaults to now)
  */
-export function getAgeInUnits(birthDate, unit, referenceDate = new Date()) {
+function getAgeInUnits(birthDate, unit, referenceDate = new Date()) {
     const diffMs = referenceDate.getTime() - birthDate.getTime();
     switch (unit) {
         case 'years':
@@ -57,7 +65,7 @@ export function getAgeInUnits(birthDate, unit, referenceDate = new Date()) {
  * @param birthDate - date of birth
  * @param referenceDate - date to calculate from (defaults to now)
  */
-export function getLifeStage(birthDate, referenceDate = new Date()) {
+function getLifeStage(birthDate, referenceDate = new Date()) {
     const ageInYears = getAgeInUnits(birthDate, 'years', referenceDate);
     if (ageInYears < 2)
         return 'infant';
@@ -74,7 +82,7 @@ export function getLifeStage(birthDate, referenceDate = new Date()) {
  * @param birthDate - date of birth
  * @param referenceDate - date to calculate from (defaults to now)
  */
-export function getNextBirthday(birthDate, referenceDate = new Date()) {
+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());
@@ -89,7 +97,7 @@ export function getNextBirthday(birthDate, referenceDate = new Date()) {
  * @param birthDate - date of birth
  * @param referenceDate - date to calculate from (defaults to now)
  */
-export function getDaysUntilBirthday(birthDate, referenceDate = new Date()) {
+function getDaysUntilBirthday(birthDate, referenceDate = new Date()) {
     const nextBirthday = getNextBirthday(birthDate, referenceDate);
     return Math.ceil((nextBirthday.getTime() - referenceDate.getTime()) / (1000 * 60 * 60 * 24));
 }
@@ -98,7 +106,7 @@ export function getDaysUntilBirthday(birthDate, referenceDate = new Date()) {
  * @param birthDate - date of birth
  * @param referenceDate - date to check (defaults to now)
  */
-export function isBirthday(birthDate, referenceDate = new Date()) {
+function isBirthday(birthDate, referenceDate = new Date()) {
     const birth = new Date(birthDate);
     const reference = new Date(referenceDate);
     return (birth.getMonth() === reference.getMonth() &&

package/dist/{calculate.js → calculate.cjs}

@@ -1,4 +1,16 @@
-import { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR } from './constants.js';
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.differenceInUnits = differenceInUnits;
+exports.addTime = addTime;
+exports.subtractTime = subtractTime;
+exports.startOf = startOf;
+exports.endOf = endOf;
+exports.isBetween = isBetween;
+exports.businessDaysBetween = businessDaysBetween;
+exports.roundToNearestUnit = roundToNearestUnit;
+exports.ceilDate = ceilDate;
+exports.floorDate = floorDate;
+const constants_js_1 = require("./constants.cjs");
 /**
  * Calculate difference between two dates in specified unit
  * @param date1 - first date
@@ -6,30 +18,30 @@ import { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR
  * @param unit - unit to return the difference in
  * @param precise - if true, returns decimal values; if false, returns integers
  */
-export function differenceInUnits(date1, date2, unit = 'milliseconds', precise = true) {
+function differenceInUnits(date1, date2, unit = 'milliseconds', precise = true) {
     const diffMs = Math.abs(date1.getTime() - date2.getTime());
     let result;
     switch (unit) {
         case 'years':
-            result = diffMs / MILLISECONDS_PER_YEAR;
+            result = diffMs / constants_js_1.MILLISECONDS_PER_YEAR;
             break;
         case 'months':
-            result = diffMs / MILLISECONDS_PER_MONTH;
+            result = diffMs / constants_js_1.MILLISECONDS_PER_MONTH;
             break;
         case 'weeks':
-            result = diffMs / MILLISECONDS_PER_WEEK;
+            result = diffMs / constants_js_1.MILLISECONDS_PER_WEEK;
             break;
         case 'days':
-            result = diffMs / MILLISECONDS_PER_DAY;
+            result = diffMs / constants_js_1.MILLISECONDS_PER_DAY;
             break;
         case 'hours':
-            result = diffMs / MILLISECONDS_PER_HOUR;
+            result = diffMs / constants_js_1.MILLISECONDS_PER_HOUR;
             break;
         case 'minutes':
-            result = diffMs / MILLISECONDS_PER_MINUTE;
+            result = diffMs / constants_js_1.MILLISECONDS_PER_MINUTE;
             break;
         case 'seconds':
-            result = diffMs / MILLISECONDS_PER_SECOND;
+            result = diffMs / constants_js_1.MILLISECONDS_PER_SECOND;
             break;
         case 'milliseconds':
         default:
@@ -44,7 +56,7 @@ export function differenceInUnits(date1, date2, unit = 'milliseconds', precise =
  * @param amount - amount to add
  * @param unit - unit of the amount
  */
-export function addTime(date, amount, unit) {
+function addTime(date, amount, unit) {
     const result = new Date(date);
     switch (unit) {
         case 'year':
@@ -97,7 +109,7 @@ export function addTime(date, amount, unit) {
  * @param amount - amount to subtract
  * @param unit - unit of the amount
  */
-export function subtractTime(date, amount, unit) {
+function subtractTime(date, amount, unit) {
     return addTime(date, -amount, unit);
 }
 /**
@@ -105,7 +117,7 @@ export function subtractTime(date, amount, unit) {
  * @param date - input date
  * @param unit - time unit to get the start of
  */
-export function startOf(date, unit) {
+function startOf(date, unit) {
     const result = new Date(date);
     switch (unit) {
         case 'minute':
@@ -137,7 +149,7 @@ export function startOf(date, unit) {
  * @param date - input date
  * @param unit - time unit to get the end of
  */
-export function endOf(date, unit) {
+function endOf(date, unit) {
     const result = new Date(date);
     switch (unit) {
         case 'minute':
@@ -175,7 +187,7 @@ export function endOf(date, unit) {
  * @param end - end date
  * @param inclusive - whether boundaries are inclusive (default: true)
  */
-export function isBetween(date, start, end, inclusive = true) {
+function isBetween(date, start, end, inclusive = true) {
     const time = date.getTime();
     const startTime = start.getTime();
     const endTime = end.getTime();
@@ -189,7 +201,7 @@ export function isBetween(date, start, end, inclusive = true) {
  * @param startDate - start date
  * @param endDate - end date
  */
-export function businessDaysBetween(startDate, endDate) {
+function businessDaysBetween(startDate, endDate) {
     let count = 0;
     const current = new Date(startDate);
     while (current <= endDate) {
@@ -209,7 +221,7 @@ export function businessDaysBetween(startDate, endDate) {
  * 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) {
+function roundToNearestUnit(date, unit) {
     const d = new Date(date);
     switch (unit) {
         case 'second':
@@ -263,7 +275,7 @@ export function roundToNearestUnit(date, unit) {
  * @example
  * ceilDate(new Date('2024-03-15T14:01:00'), 'hour') // 15:00
  */
-export function ceilDate(date, unit) {
+function ceilDate(date, unit) {
     const floored = floorDate(date, unit);
     if (floored.getTime() === date.getTime())
         return new Date(date);
@@ -297,7 +309,7 @@ export function ceilDate(date, unit) {
  * @example
  * floorDate(new Date('2024-03-15T14:59:00'), 'hour') // 14:00
  */
-export function floorDate(date, unit) {
+function floorDate(date, unit) {
     const d = new Date(date);
     switch (unit) {
         case 'second':