@bereasoftware/time-guard 2.1.0 → 2.2.0

package/dist/types/time-guard.d.ts

@@ -1,16 +1,225 @@
-import { ITimeGuard, ITimeGuardConfig, Unit, FormatPreset, IRoundOptions } from './types';
-type DurationParts = {
+import { ITimeGuard, ITimeGuardConfig, Unit, FormatPreset, IRoundOptions, IDurationOptions, IDiffResult, IDiffOptions, DurationParts, IDurationExplanation } from './types';
+/**
+ * Diff result object that allows chaining with .as()
+ * Example: tg1.diff(tg2).as('month')
+ * Also acts as a number value for backward compatibility
+ *
+ * Supports two modes:
+ * - 'exact': Returns precise time differences (e.g., 65 days)
+ * - 'calendar': Returns calendar-aware breakdown (e.g., 2 months 5 days)
+ */
+declare class DiffResult implements IDiffResult {
+    private _value;
+    private _tg1;
+    private _tg2;
+    private _mode;
+    private _breakdownData;
+    private _locale;
+    constructor(value: number, tg1: TimeGuard, tg2: TimeGuard, mode?: 'calendar' | 'exact', breakdownData?: DurationParts, locale?: string);
+    /**
+     * Convert the diff to a different unit
+     * Example: diff.as('month') returns the difference in months
+     */
+    as(unit: Unit): number;
+    /**
+     * Get breakdown in calendar mode (months, days, etc.)
+     * Returns null for 'exact' mode
+     */
+    breakdown(): DurationParts | null;
+    /**
+     * Format as human-readable string
+     * Example: "2 months and 5 days"
+     */
+    format(locale?: string): string;
+    /**
+     * Get the calculation mode used for this diff
+     */
+    getMode(): 'calendar' | 'exact';
+    /**
+     * Allow implicit numeric conversion for backward compatibility
+     */
+    valueOf(): number;
+    /**
+     * String representation
+     */
+    toString(): string;
+    /**
+     * JSON representation
+     */
+    toJSON(): number;
+}
+/**
+ * DurationResult class - Represents a duration breakdown with humanize support
+ * Example: start.until(end).humanize() → "2 months and 5 days"
+ *
+ * Public class available for type checking and extending
+ * Returned by until(), since(), and between() methods
+ */
+export declare class DurationResult implements DurationParts {
     years: number;
     months: number;
+    weeks: number;
     days: number;
     hours: number;
     minutes: number;
     seconds: number;
     milliseconds: number;
-};
+    private _locale;
+    private _startDate?;
+    private _endDate?;
+    private _steps;
+    private _mode;
+    private _leapYearFlags;
+    private _calculationTimeMs;
+    constructor(parts: DurationParts, locale?: string, metadata?: {
+        startDate?: string;
+        endDate?: string;
+        steps?: string[];
+        mode?: 'exact' | 'estimated';
+        leapYearFlags?: Array<{
+            year: number;
+            isLeap: boolean;
+            daysInFebruary: number;
+        }>;
+        calculationTimeMs?: number;
+    });
+    /**
+     * Convert duration to human-readable string
+     * Supports multiple humanization styles using Intl API
+     * @example
+     * duration.humanize() // "2 months" (Intl.RelativeTimeFormat style)
+     * duration.humanize({ fullBreakdown: true, locale: 'es' }) // "2 meses y 5 días"
+     */
+    humanize(options?: {
+        locale?: string;
+        fullBreakdown?: boolean;
+        numeric?: 'always' | 'auto';
+    }): string;
+    /**
+     * Get total duration in specified unit (date-fns style)
+     * Useful for business logic: payments, metrics, analytics
+     *
+     * Conversion factors:
+     * - 1 year = 365.25 days (accounting for leap years)
+     * - 1 month = 365.25/12 days = 30.4375 days
+     * - 1 week = 7 days
+     *
+     * @example
+     * duration.total('days')    // 65
+     * duration.total('months')  // 2.166... (65 / 30.4375)
+     * duration.total('hours')   // 1560 (65 * 24)
+     * duration.total('seconds') // 5616000 (65 * 24 * 60 * 60)
+     */
+    total(unit: Unit): number;
+    /**
+     * String representation
+     * Returns humanized format by default, or numeric if in exact mode
+     */
+    toString(): string;
+    /**
+     * JSON representation
+     * Returns the breakdown as object for serialization
+     */
+    toJSON(): Record<string, number>;
+    /**
+     * Explain the calculation - killer feature for debugging and education
+     * Returns detailed breakdown of how the duration was calculated
+     *
+     * Perfect for:
+     * - Debugging complex date calculations
+     * - Educational purposes (showing date math)
+     * - Auditing time-based business logic
+     * - Verification of calculation methodology
+     *
+     * @example
+     * start.until(end).explain()
+     * // {
+     * //   input: ['2024-01-15', '2024-03-20'],
+     * //   steps: [
+     * //     'Parsed dates: 2024-01-15 to 2024-03-20',
+     * //     '2024 is a leap year (366 days)',
+     * //     'February 2024 has 29 days',
+     * //     'Total calculated: 65 days'
+     * //   ],
+     * //   breakdown: { years: 0, months: 2, weeks: 0, days: 5, ... },
+     * //   mode: 'exact',
+     * //   explanation: 'Calculated 2024-01-15 to 2024-03-20...'
+     * // }
+     */
+    explain(): IDurationExplanation;
+    /**
+     * Generate explanation steps for the calculation
+     * Used when steps weren't provided during construction
+     */
+    private generateExplanationSteps;
+    /**
+     * Get the conjunction for a locale
+     */
+    private getConjunction;
+    /**
+     * Pluralize a unit name
+     */
+    private pluralizeUnit;
+}
 /**
  * TimeGuard implementation - Main facade class
  */
+/**
+ * TimeRange - Fluent API for date range operations
+ * Semantic naming that eliminates confusion about date order
+ *
+ * @example
+ * TimeGuard.range('2024-01-15', '2024-03-20')
+ *   .toDuration()        // Returns DurationResult
+ *   .humanize()          // "2 months and 5 days"
+ *
+ * TimeGuard.range('2024-01-15', '2024-03-20')
+ *   .inMonths()          // 2.1355 (precise decimal)
+ *
+ * These methods work regardless of date order
+ */
+export declare class TimeRange {
+    private _start;
+    private _end;
+    constructor(start: TimeGuard, end: TimeGuard);
+    /**
+     * Get the duration between the two dates
+     * @returns DurationResult with all duration properties and methods
+     * @example
+     * const duration = TimeGuard.range(start, end).toDuration();
+     * duration.humanize();  // "2 months and 5 days"
+     * duration.total('day'); // 65.875
+     */
+    toDuration(): DurationResult;
+    /**
+     * Get the range expressed in months (as decimal)
+     * Accounts for leap years and average month lengths
+     * @returns Number of months (can be decimal like 2.1355)
+     * @example
+     * TimeGuard.range('2024-01-15', '2024-03-20').inMonths(); // ~2.1355
+     */
+    inMonths(): number;
+    /**
+     * Get human-readable representation of the range
+     * Semantic naming that emphasizes what the range represents
+     * @returns String like "2 months and 5 days"
+     * @example
+     * TimeGuard.range(start, end).humanize(); // "2 months and 5 days"
+     * TimeGuard.range(start, end).humanize({ locale: 'es' }); // "2 meses y 5 días"
+     */
+    humanize(options?: {
+        locale?: string;
+        fullBreakdown?: boolean;
+        numeric?: 'always' | 'auto';
+    }): string;
+    /**
+     * Get duration in specific unit
+     * Chainable with other TimeRange methods
+     * @example
+     * TimeGuard.range(start, end).in('day'); // 65.875
+     */
+    in(unit: Unit): number;
+}
 export declare class TimeGuard implements ITimeGuard {
     private temporal;
     private config;
@@ -26,6 +235,43 @@ export declare class TimeGuard implements ITimeGuard {
     static from(input: unknown, config?: ITimeGuardConfig): TimeGuard;
     static fromTemporal(temporal: any, // Temporal.PlainDateTime | Temporal.ZonedDateTime
     config?: ITimeGuardConfig): TimeGuard;
+    /**
+     * Calculate duration between two dates - semantic API eliminating until/since confusion
+     *
+     * Always returns positive duration regardless of date order.
+     * Use .humanize() for user-friendly output.
+     *
+     * @example
+     * const start = TimeGuard.from("2024-01-15");
+     * const end = TimeGuard.from("2024-03-20");
+     *
+     * TimeGuard.between(start, end).humanize();
+     * // "2 months and 5 days"
+     *
+     * // Order doesn't matter - semantic clarity!
+     * TimeGuard.between(end, start).humanize();
+     * // "2 months and 5 days" (still positive)
+     *
+     * // Has all DurationParts properties
+     * TimeGuard.between(start, end).months; // 2
+     * TimeGuard.between(start, end).days;   // 5
+     */
+    static between(date1: TimeGuard, date2: TimeGuard): DurationResult;
+    /**
+     * Create a TimeRange for fluent duration calculations
+     * Marketing-friendly naming that emphasizes range semantics
+     *
+     * @example
+     * TimeGuard.range("2024-01-15", "2024-03-20")
+     *   .humanize() // "2 months and 5 days"
+     *
+     * TimeGuard.range("2024-01-15", "2024-03-20")
+     *   .inMonths() // 2.1355
+     *
+     * TimeGuard.range("2024-01-15", "2024-03-20")
+     *   .toDuration() // DurationResult object
+     */
+    static range(start: unknown, end: unknown): TimeRange;
     toTemporal(): any;
     toDate(): Date;
     toISOString(): string;
@@ -41,7 +287,28 @@ export declare class TimeGuard implements ITimeGuard {
     get(component: Unit): number;
     add(units: Partial<Record<Unit, number>>): TimeGuard;
     subtract(units: Partial<Record<Unit, number>>): TimeGuard;
-    diff(other: TimeGuard, unit?: Unit): number;
+    /**
+     * Calculate difference between two TimeGuard instances
+     *
+     * Supports multiple modes:
+     * 1. diff(other) - Returns DiffResult with fluent API (default: exact mode)
+     * 2. diff(other, unit) - Returns number (backward compatible)
+     * 3. diff(other, options) - Returns DiffResult with calendar or exact mode
+     *
+     * @example
+     * // Exact mode (default)
+     * tg1.diff(tg2).as('day') // Get as number: 65
+     *
+     * // Calendar mode - shows normalized breakdown
+     * tg1.diff(tg2, { mode: 'calendar' }).format('en')
+     * // Output: "2 months and 5 days"
+     *
+     * // With custom unit
+     * tg1.diff(tg2, { unit: 'hour' }).as('hour') // 1560
+     */
+    diff(other: TimeGuard): DiffResult;
+    diff(other: TimeGuard, unit: Unit): number;
+    diff(other: TimeGuard, options: IDiffOptions): DiffResult;
     isBefore(other: TimeGuard): boolean;
     isAfter(other: TimeGuard): boolean;
     isSame(other: TimeGuard, unit?: Unit): boolean;
@@ -65,8 +332,16 @@ export declare class TimeGuard implements ITimeGuard {
     inLeapYear(): boolean;
     /**
      * Calculate duration until another TimeGuard
+     * @returns Duration object with .humanize() and other methods
+     * @example
+     * start.until(end).humanize() // "2 months and 5 days"
+     * start.until(end).humanize({ fullBreakdown: true, locale: 'es' }) // "2 meses y 5 días"
+     */
+    until(other: TimeGuard, options?: IDurationOptions): DurationResult;
+    /**
+     * Generate explanation steps for until() calculation
      */
-    until(other: TimeGuard): DurationParts;
+    private generateUntilSteps;
     /**
      * Round to a specific unit with optional rounding mode
      */
@@ -120,8 +395,12 @@ export declare class TimeGuard implements ITimeGuard {
     /**
      * Calculate duration from another TimeGuard (inverse of until)
      * Returns negative values if other is before this
+     * @returns Duration object with .humanize() and other methods
+     * @example
+     * end.since(start).humanize() // "2 months and 5 days"
+     * end.since(start).humanize({ locale: 'es' }) // "2 meses y 5 días"
      */
-    since(other: TimeGuard): DurationParts;
+    since(other: TimeGuard, options?: IDurationOptions): DurationResult;
     /**
      * Get ISO 8601 duration string
      * Example: P1Y2M3DT4H5M6S

package/dist/types/types/index.d.ts

@@ -35,6 +35,230 @@ export interface IRoundOptions {
     roundingMode?: 'ceil' | 'floor' | 'expand' | 'trunc' | 'halfExpand' | 'halfFloor' | 'halfCeil' | 'halfTrunc';
     roundingIncrement?: number;
 }
+/**
+ * Duration options for normalizing time differences
+ */
+export interface IDurationOptions {
+    largestUnit?: 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
+    smallestUnit?: 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
+}
+/**
+ * Diff result object that allows chaining with .as()
+ * Example: tg1.diff(tg2).as('month')
+ */
+export interface IDiffResult {
+    as(unit: Unit): number;
+    /**
+     * Get breakdown in calendar mode (e.g., "2 months 5 days")
+     * Only available when mode is 'calendar'
+     */
+    breakdown(): DurationParts | null;
+    /**
+     * Format the difference as a human-readable string
+     * @param locale Locale code (e.g., 'en', 'es', 'fr')
+     * @example
+     * diff.format('en') // "2 months and 5 days"
+     * diff.format('es') // "2 meses y 5 días"
+     */
+    format(locale?: string): string;
+    /**
+     * Get the mode used for this diff calculation
+     */
+    getMode(): 'calendar' | 'exact';
+}
+/**
+ * Options for diff() method
+ */
+export interface IDiffOptions {
+    /**
+     * Calculation mode:
+     * - 'calendar': Returns months/days breakdown (e.g., 65 days → 2 months 5 days)
+     * - 'exact': Returns exact time units (e.g., 65 days)
+     * @default 'exact'
+     */
+    mode?: 'calendar' | 'exact';
+    /**
+     * Unit for diff when using 'exact' mode
+     * @default 'millisecond'
+     */
+    unit?: Unit;
+    /**
+     * Locale for formatting output text
+     * @default from TimeGuard instance config
+     */
+    locale?: string;
+}
+/**
+ * Duration parts breakdown
+ */
+export interface DurationParts {
+    years: number;
+    months: number;
+    weeks: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+}
+/**
+ * Options for humanize() method
+ */
+export interface IHumanizeOptions {
+    /**
+     * Locale code (e.g., 'en', 'es', 'fr')
+     * @default from TimeGuard instance config
+     */
+    locale?: string;
+    /**
+     * Show full breakdown (e.g., "2 months and 5 days")
+     * or just largest unit (e.g., "2 months")
+     * @default false (largest unit only with Intl.RelativeTimeFormat style)
+     */
+    fullBreakdown?: boolean;
+    /**
+     * Numeric format: 'always', 'auto'
+     * @default 'always'
+     */
+    numeric?: 'always' | 'auto';
+}
+/**
+ * Duration result with humanize and total methods
+ * Returned by until(), since(), and between()
+ * Rich object for business logic: payments, metrics, analytics
+ */
+export interface IDurationResult extends DurationParts {
+    /**
+     * Convert duration to human-readable string
+     * @example
+     * duration.humanize() // "2 months"
+     * duration.humanize({ fullBreakdown: true, locale: 'es' }) // "2 meses y 5 días"
+     */
+    humanize(options?: IHumanizeOptions): string;
+    /**
+     * Get total duration in specified unit (date-fns style)
+     * Perfect for business metrics: payments, analytics, calculations
+     *
+     * Conversion factors account for:
+     * - Leap years (1 year = 365.25 days)
+     * - Average month length (1 month = 30.4375 days)
+     *
+     * @example
+     * duration.total('days')    // 65
+     * duration.total('months')  // 2.166... (65 / 30.4375)
+     * duration.total('hours')   // 1560
+     * duration.total('seconds') // 5616000
+     *
+     * Use cases:
+     * - Billing calculations: `duration.total('days') * dailyRate`
+     * - Performance metrics: `duration.total('milliseconds')`
+     * - Report generation: `duration.total('months')`
+     */
+    total(unit: Unit): number;
+    /**
+     * String representation
+     * Returns humanized format for display
+     */
+    toString(): string;
+    /**
+     * JSON representation
+     * Returns breakdown as object for API responses
+     */
+    toJSON(): Record<string, number>;
+    /**
+     * Explain the calculation - killer feature for debugging and education
+     * Returns detailed breakdown of how the duration was calculated
+     *
+     * Perfect for:
+     * - Debugging complex date calculations
+     * - Educational purposes (showing date math)
+     * - Auditing time-based business logic
+     *
+     * @example
+     * duration.explain()
+     * // {
+     * //   input: ['2024-01-15', '2024-03-20'],
+     * //   steps: ['...step 1...', '...step 2...'],
+     * //   breakdown: { years: 0, months: 2, days: 5, ... },
+     * //   mode: 'exact',
+     * //   explanation: '...'
+     * // }
+     */
+    explain(): IDurationExplanation;
+}
+/**
+ * Duration explanation object for debugging and education
+ * Provides transparent insight into calculation methodology
+ * Perfect for: debugging, auditing, educational purposes
+ *
+ * @example
+ * duration.explain()
+ * // {
+ * //   input: ['2024-01-15', '2024-03-20'],
+ * //   steps: [
+ * //     'Parsed dates: 2024-01-15 (day 15 of 365) to 2024-03-20 (day 80 of 365)',
+ * //     '2024 is a leap year (366 days)',
+ * //     'February 2024 has 29 days',
+ * //     'Month 1: 31 - 15 = 16 days remaining',
+ * //     'Month 2: 29 days (full leap month)',
+ * //     'Month 3: 1 - 20 = 20 days',
+ * //     'Total: 16 + 29 + 20 = 65 days'
+ * //   ],
+ * //   breakdown: { years: 0, months: 2, weeks: 0, days: 5, ... },
+ * //   mode: 'exact',
+ * //   explanation: 'Calculated 2024-01-15 to 2024-03-20 including leap year adjustment'
+ * // }
+ */
+export interface IDurationExplanation {
+    /**
+     * Input dates as array of strings or formatted representations
+     */
+    input: string[];
+    /**
+     * Step-by-step calculation explanation
+     * Each step is human-readable and educational
+     * Useful for debugging complex date calculations
+     */
+    steps: string[];
+    /**
+     * Duration breakdown by component
+     * Same as the DurationResult properties
+     */
+    breakdown: DurationParts;
+    /**
+     * Calculation mode
+     * - 'exact': Uses Temporal API precise calculations
+     * - 'estimated': Fallback for edge cases
+     */
+    mode: 'exact' | 'estimated';
+    /**
+     * Human-readable explanation of the entire calculation
+     * Summarizes the approach and any special handling
+     */
+    explanation: string;
+    /**
+     * Locale used for explanation text
+     * Supports internationalization of step descriptions
+     */
+    locale: string;
+    /**
+     * Leap year flags if applicable
+     * Documents which years were leap years in the calculation
+     */
+    leapYearFlags?: {
+        year: number;
+        isLeap: boolean;
+        daysInFebruary: number;
+    }[];
+    /**
+     * Performance metadata
+     * For monitoring calculation complexity
+     */
+    metadata?: {
+        calculationTimeMs: number;
+        precision: 'nanosecond' | 'microsecond' | 'millisecond' | 'second' | 'day';
+    };
+}
 /**
  * Calendar system interface
  */
@@ -110,8 +334,10 @@ export interface ILocaleManager {
 export interface IDateArithmetic {
     add(units: Partial<Record<Unit, number>> | IDuration): TimeGuard;
     subtract(units: Partial<Record<Unit, number>> | IDuration): TimeGuard;
-    diff(other: TimeGuard, unit?: Unit): number;
-    until(other: TimeGuard, options?: IRoundOptions): IDuration;
+    diff(other: TimeGuard): IDiffResult;
+    diff(other: TimeGuard, unit: Unit): number;
+    until(other: TimeGuard, options?: IDurationOptions): IDurationResult;
+    since(other: TimeGuard, options?: IDurationOptions): IDurationResult;
     round(options: IRoundOptions): TimeGuard;
 }
 /**
@@ -250,7 +476,7 @@ export interface ITimeGuard extends IDateArithmetic, IDateQuery, IDateManipulati
     /**
      * Duration from another date (inverse of until)
      */
-    since(other: TimeGuard): IDuration;
+    since(other: TimeGuard, options?: IDurationOptions): IDurationResult;
     /**
      * ISO 8601 duration string (P1Y2M3DT4H5M6S)
      */
@@ -299,3 +525,54 @@ export interface ITimeGuardFactory {
 export declare class TimeGuard {
     constructor(input?: unknown, config?: ITimeGuardConfig);
 }
+/**
+ * Forward declaration for DurationResult class
+ * Implementation is in ./time-guard.ts, exported via ./index.ts
+ */
+export declare class DurationResult implements IDurationResult {
+    constructor(parts: DurationParts, locale?: string, metadata?: {
+        startDate?: string;
+        endDate?: string;
+        steps?: string[];
+        mode?: 'exact' | 'estimated';
+        leapYearFlags?: Array<{
+            year: number;
+            isLeap: boolean;
+            daysInFebruary: number;
+        }>;
+        calculationTimeMs?: number;
+    });
+    years: number;
+    months: number;
+    weeks: number;
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+    milliseconds: number;
+    humanize(options?: {
+        locale?: string;
+        fullBreakdown?: boolean;
+        numeric?: 'always' | 'auto';
+    }): string;
+    total(unit: Unit): number;
+    toString(): string;
+    toJSON(): Record<string, number>;
+    explain(): IDurationExplanation;
+}
+/**
+ * Forward declaration for TimeRange class
+ * Fluent API for date range operations with semantic naming
+ * Implementation is in ./time-guard.ts, exported via ./index.ts
+ */
+export declare class TimeRange {
+    constructor(start: TimeGuard, end: TimeGuard);
+    toDuration(): DurationResult;
+    inMonths(): number;
+    humanize(options?: {
+        locale?: string;
+        fullBreakdown?: boolean;
+        numeric?: 'always' | 'auto';
+    }): string;
+    in(unit: Unit): number;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bereasoftware/time-guard",
   "private": false,
-  "version": "2.1.0",
+  "version": "2.2.0",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/time-guard.cjs",