@bereasoftware/time-guard 2.5.1 → 2.5.3

package/dist/types/plugins/duration/types.d.ts

@@ -1,85 +0,0 @@
-/**
- * Duration Plugin Types
- */
-export type DurationUnit = 'years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds';
-export interface DurationInput {
-    years?: number;
-    months?: number;
-    weeks?: number;
-    days?: number;
-    hours?: number;
-    minutes?: number;
-    seconds?: number;
-    milliseconds?: number;
-}
-export interface DurationObject {
-    years: number;
-    months: number;
-    weeks: number;
-    days: number;
-    hours: number;
-    minutes: number;
-    seconds: number;
-    milliseconds: number;
-}
-/**
- * Duration class for ISO 8601 durations
- */
-export interface IDuration {
-    /**
-     * Get duration in specific unit
-     */
-    as(unit: DurationUnit): number;
-    /**
-     * Get duration as milliseconds
-     */
-    asMilliseconds(): number;
-    /**
-     * Get duration as seconds
-     */
-    asSeconds(): number;
-    /**
-     * Get duration as minutes
-     */
-    asMinutes(): number;
-    /**
-     * Get duration as hours
-     */
-    asHours(): number;
-    /**
-     * Get duration as days
-     */
-    asDays(): number;
-    /**
-     * Get duration as weeks
-     */
-    asWeeks(): number;
-    /**
-     * Get duration as months
-     */
-    asMonths(): number;
-    /**
-     * Get duration as years
-     */
-    asYears(): number;
-    /**
-     * Get all components
-     */
-    toObject(): DurationObject;
-    /**
-     * Get ISO 8601 string representation
-     */
-    toISO(): string;
-    /**
-     * Get human-readable string
-     */
-    humanize(): string;
-    /**
-     * Check if duration is negative
-     */
-    isNegative(): boolean;
-    /**
-     * Get absolute duration
-     */
-    abs(): IDuration;
-}

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

@@ -1,10 +0,0 @@
-/**
- * TimeGuard Plugins
- * Central export point for all plugins
- */
-export { PluginManager } from './manager';
-export { RelativeTimePlugin, default as relativeTimePlugin } from './relative-time';
-export { DurationPlugin, Duration, default as durationPlugin } from './duration';
-export { AdvancedFormatPlugin, default as advancedFormatPlugin } from './advanced-format';
-export type { RelativeTimeConfig, RelativeTimeFormats, RelativeTimeThreshold } from './relative-time/types';
-export type { IDuration, DurationInput, DurationObject, DurationUnit } from './duration/types';

package/dist/types/plugins/manager.d.ts

@@ -1,58 +0,0 @@
-import { ITimeGuardPlugin } from '../types';
-import { TimeGuard } from '../time-guard';
-/**
- * Plugin Manager - handles plugin registration and initialization
- * Uses Singleton pattern to ensure single instance across application
- */
-export declare class PluginManager {
-    private static instance;
-    private plugins;
-    /**
-     * Get singleton instance
-     */
-    static getInstance(): PluginManager;
-    /**
-     * Register a plugin
-     * @param plugin - The plugin to register
-     * @param timeGuardClass - Reference to TimeGuard class
-     * @param config - Optional plugin configuration
-     */
-    static use(plugin: ITimeGuardPlugin, timeGuardClass: typeof TimeGuard, config?: unknown): void;
-    /**
-     * Register multiple plugins at once
-     * @param plugins - Array of plugins to register
-     * @param timeGuardClass - Reference to TimeGuard class
-     * @param config - Optional plugin configuration
-     */
-    static useMultiple(plugins: ITimeGuardPlugin[], timeGuardClass: typeof TimeGuard, config?: unknown): void;
-    /**
-     * Get registered plugin by name
-     * @param name - Plugin name
-     * @returns Plugin instance or undefined
-     */
-    static getPlugin(name: string): ITimeGuardPlugin | undefined;
-    /**
-     * Check if plugin is registered
-     * @param name - Plugin name
-     * @returns True if plugin is registered
-     */
-    static hasPlugin(name: string): boolean;
-    /**
-     * Get all registered plugins
-     * @returns Array of registered plugin names
-     */
-    static listPlugins(): string[];
-    /**
-     * Unregister a plugin
-     * @param name - Plugin name
-     */
-    static unuse(name: string): boolean;
-    /**
-     * Clear all plugins
-     */
-    static clear(): void;
-    /**
-     * Internal register method
-     */
-    private register;
-}

package/dist/types/plugins/relative-time/index.d.ts

@@ -1,39 +0,0 @@
-import { ITimeGuardPlugin } from '../../types';
-import { TimeGuard } from '../../time-guard';
-import { RelativeTimeConfig, RelativeTimeFormats } from './types';
-export declare class RelativeTimePlugin implements ITimeGuardPlugin {
-    name: string;
-    version: string;
-    private config;
-    private formats;
-    constructor(config?: RelativeTimeConfig);
-    /**
-     * Install plugin into TimeGuard
-     */
-    install(TimeGuardClass: typeof TimeGuard): void;
-    /**
-     * Format relative time
-     */
-    private formatRelativeTime;
-    /**
-     * Get relative time string based on milliseconds
-     */
-    private getRelativeTimeString;
-    /**
-     * Get milliseconds per unit
-     */
-    private getUnitMilliseconds;
-    /**
-     * Set format strings
-     */
-    setFormats(formats: Partial<RelativeTimeFormats>): void;
-    /**
-     * Get current formats
-     */
-    getFormats(): RelativeTimeFormats;
-}
-/**
- * Create and export default instance
- */
-declare const _default: RelativeTimePlugin;
-export default _default;

package/dist/types/plugins/relative-time/types.d.ts

@@ -1,27 +0,0 @@
-/**
- * RelativeTime Plugin Types
- */
-export interface RelativeTimeConfig {
-    thresholds?: RelativeTimeThreshold[];
-    rounding?: (value: number) => number;
-}
-export interface RelativeTimeThreshold {
-    l: string;
-    r?: number;
-    d?: string;
-}
-export interface RelativeTimeFormats {
-    future: string;
-    past: string;
-    s: string;
-    m: string;
-    mm: string;
-    h: string;
-    hh: string;
-    d: string;
-    dd: string;
-    M: string;
-    MM: string;
-    y: string;
-    yy: string;
-}

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 {};

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

@@ -1,426 +0,0 @@
-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;
-    /**
-     * Pluralize a unit name (deprecated - use utility function)
-     */
-    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;
-    private formatterInstance;
-    private static readonly ZERO_DURATION;
-    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.
-     *
-     * @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;
-    valueOf(): number;
-    unix(): number;
-    toJSON(): string;
-    toString(): string;
-    locale(): string;
-    locale(locale: string): TimeGuard;
-    timezone(): string | null;
-    timezone(timezone: string): TimeGuard;
-    format(pattern: string | FormatPreset): string;
-    get(component: Unit): number;
-    add(units: Partial<Record<Unit, number>>): TimeGuard;
-    subtract(units: Partial<Record<Unit, number>>): TimeGuard;
-    /**
-     * 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;
-    isBetween(start: TimeGuard, end: TimeGuard, unit?: Unit, inclusivity?: '[)' | '()' | '[]' | '(]'): boolean;
-    clone(): TimeGuard;
-    startOf(unit: Unit): TimeGuard;
-    endOf(unit: Unit): TimeGuard;
-    set(values: Partial<Record<Unit, number>>): TimeGuard;
-    year(): number;
-    month(): number;
-    day(): number;
-    hour(): number;
-    minute(): number;
-    second(): number;
-    millisecond(): number;
-    dayOfWeek(): number;
-    dayOfYear(): number;
-    weekOfYear(): number;
-    daysInMonth(): number;
-    daysInYear(): number;
-    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
-     */
-    private generateUntilSteps;
-    /**
-     * Round to a specific unit with optional rounding mode
-     */
-    round(options?: IRoundOptions): TimeGuard;
-    /**
-     * Convert to PlainDate (removes time information)
-     */
-    toPlainDate(): {
-        year: number;
-        month: number;
-        day: number;
-        dayOfWeek: number;
-    };
-    /**
-     * Convert to PlainTime (removes date information)
-     */
-    toPlainTime(): {
-        hour: number;
-        minute: number;
-        second: number;
-        millisecond: number;
-    };
-    /**
-     * Create new TimeGuard with only date, keeping time from parameter
-     */
-    withDate(year: number, month: number, day: number): TimeGuard;
-    /**
-     * Create new TimeGuard with only time, keeping date
-     */
-    withTime(hour: number, minute?: number, second?: number, millisecond?: number): TimeGuard;
-    /**
-     * Get timezone offset in format ±HH:mm
-     */
-    getOffset(): string;
-    /**
-     * Get timezone offset in nanoseconds
-     */
-    getOffsetNanoseconds(): number;
-    /**
-     * Get timezone ID
-     */
-    getTimeZoneId(): string | null;
-    /**
-     * Start of the day in current timezone
-     */
-    startOfDay(): TimeGuard;
-    /**
-     * End of the day in current timezone
-     */
-    endOfDay(): TimeGuard;
-    /**
-     * 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, options?: IDurationOptions): DurationResult;
-    /**
-     * Get ISO 8601 duration string
-     * Example: P1Y2M3DT4H5M6S
-     */
-    toDurationString(other?: TimeGuard): string;
-    /**
-     * Check if this date is in the past
-     */
-    isPast(): boolean;
-    /**
-     * Check if this date is in the future
-     */
-    isFuture(): boolean;
-    /**
-     * Check if this date is today
-     */
-    isToday(): boolean;
-    /**
-     * Check if this date is tomorrow
-     */
-    isTomorrow(): boolean;
-    /**
-     * Check if this date is yesterday
-     */
-    isYesterday(): boolean;
-}
-export { PluginManager } from './plugins/manager';