@bereasoftware/time-guard 2.5.3 → 2.5.4

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

@@ -0,0 +1,66 @@
+import { Temporal } from '@js-temporal/polyfill';
+type TemporalPlainDateTime = Temporal.PlainDateTime;
+type TemporalZonedDateTime = Temporal.ZonedDateTime;
+/**
+ * Adapter for Temporal date/time operations
+ */
+export declare class TemporalAdapter {
+    /**
+     * Parse various input formats to Temporal.PlainDateTime
+     */
+    static parseToPlainDateTime(input: unknown): TemporalPlainDateTime;
+    /**
+     * Convert JavaScript Date to Temporal.PlainDateTime
+     */
+    static fromDate(date: Date): TemporalPlainDateTime;
+    /**
+     * Convert Unix timestamp (milliseconds) to Temporal.PlainDateTime
+     */
+    static fromUnix(timestamp: number): TemporalPlainDateTime;
+    /**
+     * Parse ISO string to Temporal.PlainDateTime
+     */
+    static parseISOString(iso: string): TemporalPlainDateTime;
+    /**
+     * Create from object with date components
+     */
+    static fromObject(obj: Record<string, any>): TemporalPlainDateTime;
+    /**
+     * Convert Temporal.PlainDateTime to JavaScript Date
+     */
+    static toDate(temporal: TemporalPlainDateTime | TemporalZonedDateTime): Date;
+    /**
+     * Convert to Unix timestamp (milliseconds)
+     */
+    static toUnix(temporal: TemporalPlainDateTime | TemporalZonedDateTime): number;
+    /**
+     * Convert to ISO string
+     */
+    static toISOString(temporal: TemporalPlainDateTime | TemporalZonedDateTime): string;
+    /**
+     * Ensure we have a PlainDateTime
+     */
+    static toPlainDateTime(temporal: TemporalPlainDateTime | TemporalZonedDateTime): TemporalPlainDateTime;
+    /**
+     * Type guards
+     */
+    static isPlainDateTime(obj: unknown): obj is TemporalPlainDateTime;
+    static isZonedDateTime(obj: unknown): obj is TemporalZonedDateTime;
+    static isPlainDate(obj: unknown): obj is any;
+    static isPlainTime(obj: unknown): obj is any;
+    /**
+     * Get current time as PlainDateTime
+     */
+    static now(): TemporalPlainDateTime;
+    /**
+     * Get current time as ZonedDateTime with timezone
+     */
+    static nowInTimezone(timezone: string): TemporalZonedDateTime;
+    /**
+     * Compare two Temporal.PlainDateTime objects
+     * Returns: -1 if dt1 < dt2, 0 if equal, 1 if dt1 > dt2
+     * Uses ISO string comparison as fallback for polyfills that don't have Temporal.PlainDateTime.compare
+     */
+    static compare(dt1: TemporalPlainDateTime, dt2: TemporalPlainDateTime): number;
+}
+export {};

package/dist/types/calendars/calendar.manager.d.ts

@@ -0,0 +1,52 @@
+import { ICalendarSystem, ICalendarManager } from '../types';
+/**
+ * Gregorian Calendar System (ISO 8601 default)
+ */
+export declare class GregorianCalendar implements ICalendarSystem {
+    readonly id = "gregory";
+    readonly name = "Gregorian Calendar";
+    readonly locale = "en";
+    private monthNames;
+    private monthNamesShort;
+    private weekdayNames;
+    private weekdayNamesShort;
+    getMonthName(month: number, short?: boolean): string;
+    getWeekdayName(day: number, short?: boolean): string;
+    isLeapYear(year: number): boolean;
+    daysInMonth(year: number, month: number): number;
+    daysInYear(year: number): number;
+}
+/**
+ * Calendar Manager - Singleton for managing calendar systems
+ */
+export declare class CalendarManager implements ICalendarManager {
+    private static instance;
+    private calendars;
+    private defaultCalendar;
+    private constructor();
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): CalendarManager;
+    /**
+     * Register a new calendar system
+     */
+    register(calendar: ICalendarSystem): void;
+    /**
+     * Get calendar by ID
+     */
+    get(id: string): ICalendarSystem | undefined;
+    /**
+     * List all available calendars
+     */
+    list(): string[];
+    /**
+     * Set default calendar
+     */
+    setDefault(id: string): void;
+    /**
+     * Get default calendar
+     */
+    getDefault(): ICalendarSystem;
+}
+export declare const calendarManager: CalendarManager;

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

@@ -1 +1,81 @@
-export {}
+import { ICalendarSystem } from '../types';
+/**
+ * Islamic Calendar (Hijri)
+ * @experimental Uses simplified calculations. May not be accurate for all dates.
+ */
+export declare class IslamicCalendar implements ICalendarSystem {
+    readonly id = "islamic";
+    readonly name = "Islamic Calendar (Hijri)";
+    readonly locale = "ar";
+    private monthNames;
+    getMonthName(month: number): string;
+    getWeekdayName(day: number, short?: boolean): string;
+    isLeapYear(year: number): boolean;
+    daysInMonth(year: number, month: number): number;
+    daysInYear(year: number): number;
+}
+/**
+ * Hebrew Calendar
+ * @experimental Uses simplified calculations. May not be accurate for all dates.
+ */
+export declare class HebrewCalendar implements ICalendarSystem {
+    readonly id = "hebrew";
+    readonly name = "Hebrew Calendar";
+    readonly locale = "he";
+    private monthNames;
+    getMonthName(month: number): string;
+    getWeekdayName(day: number, short?: boolean): string;
+    isLeapYear(year: number): boolean;
+    daysInMonth(_year: number, month: number): number;
+    daysInYear(year: number): number;
+}
+/**
+ * Chinese Calendar
+ * @experimental Uses simplified calculations. May not be accurate for all dates.
+ */
+export declare class ChineseCalendar implements ICalendarSystem {
+    readonly id = "chinese";
+    readonly name = "Chinese Calendar";
+    readonly locale = "zh";
+    private monthNames;
+    private terrestrialBranches;
+    getMonthName(month: number): string;
+    getWeekdayName(day: number, short?: boolean): string;
+    isLeapYear(year: number): boolean;
+    daysInMonth(_year: number, month: number): number;
+    daysInYear(year: number): number;
+    /**
+     * Get zodiac sign for year
+     */
+    getZodiacSign(year: number): string;
+}
+/**
+ * Japanese Calendar
+ * @experimental Uses Gregorian rules post-1873. Historical dates may not be accurate.
+ */
+export declare class JapaneseCalendar implements ICalendarSystem {
+    readonly id = "japanese";
+    readonly name = "Japanese Calendar";
+    readonly locale = "ja";
+    private monthNames;
+    getMonthName(month: number): string;
+    getWeekdayName(day: number, short?: boolean): string;
+    isLeapYear(year: number): boolean;
+    daysInMonth(year: number, month: number): number;
+    daysInYear(year: number): number;
+}
+/**
+ * Buddhist Calendar
+ * @experimental Uses Gregorian rules with BE year offset (CE + 543).
+ */
+export declare class BuddhistCalendar implements ICalendarSystem {
+    readonly id = "buddhist";
+    readonly name = "Buddhist Calendar";
+    readonly locale = "th";
+    private monthNames;
+    getMonthName(month: number): string;
+    getWeekdayName(day: number): string;
+    isLeapYear(year: number): boolean;
+    daysInMonth(year: number, month: number): number;
+    daysInYear(year: number): number;
+}

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

@@ -0,0 +1,21 @@
+import { IDateFormatter, FormatPreset } from '../types';
+import { Temporal } from '@js-temporal/polyfill';
+/**
+ * Date Formatter implementation
+ */
+export declare class DateFormatter implements IDateFormatter {
+    private localeManager;
+    constructor();
+    /**
+     * Format date with pattern and locale
+     */
+    format(date: Temporal.PlainDateTime, pattern: string, locale?: string): string;
+    /**
+     * Get format pattern for preset
+     */
+    getPreset(preset: FormatPreset): string;
+    /**
+     * Format with preset
+     */
+    formatPreset(date: Temporal.PlainDateTime, preset: FormatPreset, locale?: string): string;
+}

package/dist/types/index.d.ts

@@ -1 +1,205 @@
-export {}
+import { ITimeGuard, ITimeGuardConfig, Unit, FormatPreset, IRoundOptions, IDurationOptions, IDiffResult, IDiffOptions, DurationParts, IDurationExplanation, IFormattableDuration } from './types';
+import { LocaleManager, EN_LOCALE, ES_LOCALE } from './locales/locale.manager';
+/**
+ * Diff result object that allows chaining with .as()
+ *
+ * Supports two modes:
+ * - 'exact': Returns precise time differences
+ * - 'calendar': Returns calendar-aware breakdown
+ */
+declare class DiffResult implements IDiffResult, IFormattableDuration {
+    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);
+    as(unit: Unit): number;
+    breakdown(): DurationParts | null;
+    format(locale?: string): string;
+    getMode(): 'calendar' | 'exact';
+    valueOf(): number;
+    toString(): string;
+    toJSON(): number;
+}
+/**
+ * DurationResult class - Represents a duration breakdown with humanize support
+ * Returned by until(), since(), and between() methods
+ */
+export declare class DurationResult implements DurationParts, IFormattableDuration {
+    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;
+    });
+    humanize(options?: {
+        locale?: string;
+        fullBreakdown?: boolean;
+        numeric?: 'always' | 'auto';
+    }): string;
+    total(unit: Unit): number;
+    toString(): string;
+    toJSON(): Record<string, number>;
+    explain(): IDurationExplanation;
+    private generateExplanationSteps;
+    private pluralizeUnit;
+}
+/**
+ * TimeRange - Fluent API for date range operations
+ *
+ * @example
+ * TimeGuard.range('2024-01-15', '2024-03-20')
+ *   .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);
+    toDuration(): DurationResult;
+    inMonths(): number;
+    humanize(options?: {
+        locale?: string;
+        fullBreakdown?: boolean;
+        numeric?: 'always' | 'auto';
+    }): string;
+    in(unit: Unit): number;
+}
+/**
+ * TimeGuard implementation - Main facade class
+ */
+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 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 - always returns positive duration
+     *
+     * @example
+     * 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
+     *
+     * @example
+     * TimeGuard.range("2024-01-15", "2024-03-20").humanize() // "2 months and 5 days"
+     */
+    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;
+    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;
+    until(other: TimeGuard, options?: IDurationOptions): DurationResult;
+    private generateUntilSteps;
+    round(options?: IRoundOptions): TimeGuard;
+    toPlainDate(): {
+        year: number;
+        month: number;
+        day: number;
+        dayOfWeek: number;
+    };
+    toPlainTime(): {
+        hour: number;
+        minute: number;
+        second: number;
+        millisecond: number;
+    };
+    withDate(year: number, month: number, day: number): TimeGuard;
+    withTime(hour: number, minute?: number, second?: number, millisecond?: number): TimeGuard;
+    getOffset(): string;
+    getOffsetNanoseconds(): number;
+    getTimeZoneId(): string | null;
+    startOfDay(): TimeGuard;
+    endOfDay(): TimeGuard;
+    since(other: TimeGuard, options?: IDurationOptions): DurationResult;
+    toDurationString(other?: TimeGuard): string;
+    isPast(): boolean;
+    isFuture(): boolean;
+    isToday(): boolean;
+    isTomorrow(): boolean;
+    isYesterday(): boolean;
+}
+export type { ITimeGuard, ITimeGuardConfig, ITimeGuardFactory, ITimeGuardPlugin, IDateParser, IDateFormatter, ILocaleManager, IDateArithmetic, IDateQuery, IDateManipulation, ITimezoneAdapter, ICalendarSystem, ICalendarManager, IRoundOptions, IDurationOptions, IDurationResult, IDurationExplanation, IHumanizeOptions, IDiffResult, IDiffOptions, DurationParts, Unit, FormatPreset, ILocale, } from './types';
+export { TemporalAdapter } from './adapters/temporal.adapter';
+export { LocaleManager, EN_LOCALE, ES_LOCALE };
+export { getAvailableLocales, LOCALES_COUNT, ALL_LOCALES, registerAllLocales } from './locales/index';
+export { DateFormatter } from './formatters/date.formatter';
+export { CalendarManager, GregorianCalendar, calendarManager, } from './calendars/calendar.manager';
+export { IslamicCalendar, HebrewCalendar, ChineseCalendar, JapaneseCalendar, BuddhistCalendar, } from './calendars/index';
+export * from './plugins/index';
+export { PluginManager } from './plugins/manager';
+export { RelativeTimePlugin, default as relativeTimePlugin } from './plugins/relative-time';
+export type { RelativeTimeConfig, RelativeTimeFormats, RelativeTimeThreshold } from './plugins/relative-time/types';
+export { DurationPlugin, Duration, default as durationPlugin } from './plugins/duration';
+export type { IDuration, DurationInput, DurationObject, DurationUnit } from './plugins/duration/types';
+export { AdvancedFormatPlugin, default as advancedFormatPlugin } from './plugins/advanced-format';
+export declare function timeGuard(input?: unknown, config?: ITimeGuardConfig): TimeGuard;
+export declare const version: string;

package/dist/types/locales/additional.locale.d.ts

@@ -0,0 +1,5 @@
+import { ILocale } from '../types';
+export declare const VI_LOCALE_DATA: ILocale;
+export declare const ID_LOCALE_DATA: ILocale;
+export declare const TH_LOCALE_DATA: ILocale;
+export declare const ADDITIONAL_LOCALES: Record<string, ILocale>;

package/dist/types/locales/asian.locale.d.ts

@@ -0,0 +1,9 @@
+import { ILocale } from '../types';
+export declare const JA_LOCALE_DATA: ILocale;
+export declare const ZH_CN_LOCALE_DATA: ILocale;
+export declare const ZH_TW_LOCALE_DATA: ILocale;
+export declare const KO_LOCALE_DATA: ILocale;
+export declare const TH_LOCALE_DATA: ILocale;
+export declare const VI_LOCALE_DATA: ILocale;
+export declare const ID_LOCALE_DATA: ILocale;
+export declare const ASIAN_LOCALES: Record<string, ILocale>;

package/dist/types/locales/english.locale.d.ts

@@ -0,0 +1,6 @@
+import { ILocale } from '../types';
+export declare const EN_LOCALE_DATA: ILocale;
+export declare const EN_AU_LOCALE_DATA: ILocale;
+export declare const EN_GB_LOCALE_DATA: ILocale;
+export declare const EN_CA_LOCALE_DATA: ILocale;
+export declare const ENGLISH_LOCALES: Record<string, ILocale>;

package/dist/types/locales/european.locale.d.ts

@@ -0,0 +1,9 @@
+import { ILocale } from '../types';
+export declare const DE_LOCALE_DATA: ILocale;
+export declare const NL_LOCALE_DATA: ILocale;
+export declare const EL_LOCALE_DATA: ILocale;
+export declare const HU_LOCALE_DATA: ILocale;
+export declare const EU_LOCALE_DATA: ILocale;
+export declare const CA_LOCALE_DATA: ILocale;
+export declare const TR_LOCALE_DATA: ILocale;
+export declare const EUROPEAN_LOCALES: Record<string, ILocale>;

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

@@ -1 +1,17 @@
-export {}
+import { ILocale } from '../types';
+/**
+ * Aggregated locale data from all modules
+ */
+export declare const ALL_LOCALES: Record<string, ILocale>;
+/**
+ * Register all locales into a locale map
+ */
+export declare function registerAllLocales(localeMap: Map<string, ILocale> | Record<string, ILocale>): void;
+/**
+ * Get all available locales
+ */
+export declare function getAvailableLocales(): string[];
+/**
+ * Total locales count (minimum 40 required)
+ */
+export declare const LOCALES_COUNT = 40;

package/dist/types/locales/locale.manager.d.ts

@@ -0,0 +1,42 @@
+import { ILocale, ILocaleManager } from '../types';
+/**
+ * English locale data
+ */
+export declare const EN_LOCALE: ILocale;
+/**
+ * Spanish locale data (sample for i18n support)
+ */
+export declare const ES_LOCALE: ILocale;
+/**
+ * Locale Manager - implements ILocaleManager
+ */
+export declare class LocaleManager implements ILocaleManager {
+    private static instance;
+    private locales;
+    private currentLocale;
+    /**
+     * Singleton pattern
+     */
+    static getInstance(): LocaleManager;
+    private constructor();
+    /**
+     * Set or register a locale
+     */
+    setLocale(locale: string, data?: ILocale): void;
+    /**
+     * Get locale information
+     */
+    getLocale(locale?: string): ILocale;
+    /**
+     * List all registered locales
+     */
+    listLocales(): string[];
+    /**
+     * Get current locale
+     */
+    getCurrentLocale(): string;
+    /**
+     * Load multiple locales
+     */
+    loadLocales(locales: Record<string, ILocale>): void;
+}

package/dist/types/locales/middle-eastern.locale.d.ts

@@ -0,0 +1,5 @@
+import { ILocale } from '../types';
+export declare const AR_LOCALE_DATA: ILocale;
+export declare const HE_LOCALE_DATA: ILocale;
+export declare const HI_LOCALE_DATA: ILocale;
+export declare const MIDDLE_EASTERN_LOCALES: Record<string, ILocale>;

package/dist/types/locales/nordic.locale.d.ts

@@ -0,0 +1,6 @@
+import { ILocale } from '../types';
+export declare const SV_LOCALE_DATA: ILocale;
+export declare const NB_LOCALE_DATA: ILocale;
+export declare const DA_LOCALE_DATA: ILocale;
+export declare const FI_LOCALE_DATA: ILocale;
+export declare const NORDIC_LOCALES: Record<string, ILocale>;

package/dist/types/locales/romance.locale.d.ts

@@ -0,0 +1,7 @@
+import { ILocale } from '../types';
+export declare const FR_LOCALE_DATA: ILocale;
+export declare const IT_LOCALE_DATA: ILocale;
+export declare const PT_LOCALE_DATA: ILocale;
+export declare const PT_BR_LOCALE_DATA: ILocale;
+export declare const RO_LOCALE_DATA: ILocale;
+export declare const ROMANCE_LOCALES: Record<string, ILocale>;

package/dist/types/locales/slavic.locale.d.ts

@@ -0,0 +1,6 @@
+import { ILocale } from '../types';
+export declare const RU_LOCALE_DATA: ILocale;
+export declare const PL_LOCALE_DATA: ILocale;
+export declare const CS_LOCALE_DATA: ILocale;
+export declare const SK_LOCALE_DATA: ILocale;
+export declare const SLAVIC_LOCALES: Record<string, ILocale>;

package/dist/types/locales/spanish.locale.d.ts

@@ -0,0 +1,5 @@
+import { ILocale } from '../types';
+export declare const ES_LOCALE_DATA: ILocale;
+export declare const ES_MX_LOCALE_DATA: ILocale;
+export declare const ES_US_LOCALE_DATA: ILocale;
+export declare const SPANISH_LOCALES: Record<string, ILocale>;

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

@@ -0,0 +1,15 @@
+import { ITimeGuardPlugin } from '../../types';
+import { TimeGuard } from '../../index';
+export declare class AdvancedFormatPlugin implements ITimeGuardPlugin {
+    name: string;
+    version: string;
+    /**
+     * Install plugin into TimeGuard
+     */
+    install(TimeGuardClass: typeof TimeGuard): void;
+}
+/**
+ * Create and export default instance
+ */
+declare const _default: AdvancedFormatPlugin;
+export default _default;

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

@@ -1 +1,6 @@
+export * from './advanced-format/index'
+export {}
+import BereasoftTimeGuard from './advanced-format/index'
+export default BereasoftTimeGuard
+export * from './advanced-format/index'
 export {}