@bereasoftware/time-guard 2.5.0 → 2.5.2

package/dist/types/adapters/temporal.adapter.d.ts

@@ -1,4 +1,4 @@
-import { Temporal } from '../../../node_modules/@js-temporal/polyfill/dist/index.cjs';
+import { Temporal } from '@js-temporal/polyfill';
 type TemporalPlainDateTime = Temporal.PlainDateTime;
 type TemporalZonedDateTime = Temporal.ZonedDateTime;
 /**

package/dist/types/formatters/date.formatter.d.ts

@@ -1,5 +1,5 @@
 import { IDateFormatter, FormatPreset } from '../types';
-import { Temporal } from '../../../node_modules/@js-temporal/polyfill/dist/index.cjs';
+import { Temporal } from '@js-temporal/polyfill';
 /**
  * Date Formatter implementation
  */

package/dist/types/plugins/advanced-format/index.d.ts

@@ -7,38 +7,6 @@ export declare class AdvancedFormatPlugin implements ITimeGuardPlugin {
      * Install plugin into TimeGuard
      */
     install(TimeGuardClass: typeof TimeGuard): void;
-    /**
-     * Get ordinal suffix (1st, 2nd, 3rd, etc.)
-     */
-    private getOrdinal;
-    /**
-     * Pad number with leading zeros
-     */
-    private padNumber;
-    /**
-     * Get ISO week number
-     */
-    private getISOWeek;
-    /**
-     * Get week of year (locale-based)
-     */
-    private getWeekOfYear;
-    /**
-     * Get ISO week year
-     */
-    private getISOWeekYear;
-    /**
-     * Get week year
-     */
-    private getWeekYear;
-    /**
-     * Get timezone offset short form
-     */
-    private getTimezoneOffset;
-    /**
-     * Get timezone offset long form
-     */
-    private getTimezoneOffsetLong;
 }
 /**
  * Create and export default instance

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

@@ -1,14 +1,12 @@
-import { ITimeGuard, ITimeGuardConfig, Unit, FormatPreset, IRoundOptions, IDurationOptions, IDiffResult, IDiffOptions, DurationParts, IDurationExplanation } from './types';
+import { ITimeGuard, ITimeGuardConfig, Unit, FormatPreset, IRoundOptions, IDurationOptions, IDiffResult, IDiffOptions, DurationParts, IDurationExplanation, IFormattableDuration } 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)
+ * - 'exact': Returns precise time differences
+ * - 'calendar': Returns calendar-aware breakdown
  */
-declare class DiffResult implements IDiffResult {
+declare class DiffResult implements IDiffResult, IFormattableDuration {
     private _value;
     private _tg1;
     private _tg2;
@@ -16,46 +14,19 @@ declare class DiffResult implements IDiffResult {
     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 {
+export declare class DurationResult implements DurationParts, IFormattableDuration {
     years: number;
     months: number;
     weeks: number;
@@ -83,78 +54,16 @@ export declare class DurationResult implements DurationParts {
         }>;
         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;
-    /**
-     * Pluralize a unit name (deprecated - use utility function)
-     */
     private pluralizeUnit;
 }
 /**
@@ -162,58 +71,23 @@ export declare class DurationResult implements DurationParts {
  */
 /**
  * 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
+ *   .toDuration().humanize()        // "2 months and 5 days"
+ *   .inMonths()                     // 2.1355 (precise decimal)
  */
 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 {
@@ -224,48 +98,23 @@ export declare class TimeGuard implements ITimeGuard {
     private static isLeapYearValue;
     private static toDurationParts;
     constructor(input?: unknown, config?: ITimeGuardConfig);
-    /**
-     * Static factory methods
-     */
     static now(config?: ITimeGuardConfig): TimeGuard;
     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.
+     * Calculate duration between two dates - always returns positive duration
      *
      * @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
+     * TimeGuard.between(start, end).humanize() // "2 months and 5 days"
+     * TimeGuard.between(end, start).humanize() // "2 months and 5 days" (still positive)
      */
     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
+     * TimeGuard.range("2024-01-15", "2024-03-20").humanize() // "2 months and 5 days"
      */
     static range(start: unknown, end: unknown): TimeRange;
     toTemporal(): any;
@@ -293,14 +142,9 @@ export declare class TimeGuard implements ITimeGuard {
      *
      * @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
+     * tg1.diff(tg2).as('day') // 65
+     * // Calendar mode
+     * tg1.diff(tg2, { mode: 'calendar' }).format('en') // "2 months and 5 days"
      */
     diff(other: TimeGuard): DiffResult;
     diff(other: TimeGuard, unit: Unit): number;

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

@@ -101,6 +101,14 @@ export interface DurationParts {
     seconds: number;
     milliseconds: number;
 }
+/**
+ * Base interface for formattable duration-like objects
+ * Common functionality shared by DiffResult and DurationResult
+ */
+export interface IFormattableDuration {
+    toString(): string;
+    toJSON(): Record<string, number> | number;
+}
 /**
  * Options for humanize() method
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bereasoftware/time-guard",
   "private": false,
-  "version": "2.5.0",
+  "version": "2.5.2",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/time-guard.cjs",
@@ -120,7 +120,6 @@
     "@js-temporal/polyfill": "^0.5.1"
   },
   "devDependencies": {
-    "@js-temporal/polyfill": "^0.5.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.6",

package/dist/types/locales/locales-data.d.ts

@@ -1,17 +0,0 @@
-import { ILocale } from '../types';
-/**
- * Locale data record for all supported languages
- */
-export declare const LOCALES_DATA: Record<string, ILocale>;
-/**
- * Dynamically register all locales
- */
-export declare function registerAllLocales(localeMap: Map<string, ILocale> | Record<string, ILocale>): void;
-/**
- * Get all available locales
- */
-export declare function getAvailableLocales(): string[];
-/**
- * Total locales count
- */
-export declare const LOCALES_COUNT: number;

package/dist/types/polyfill-loader.d.ts

@@ -1,6 +0,0 @@
-/**
- * Polyfill Loader - Automatically loads Temporal API polyfill if needed
- * No user installation required - polyfill is included in time-guard
- * Compatible with both ESM and CJS environments (SSR / Nest / Nuxt / Node.js)
- */
-export {};