ts-time-utils 1.0.0 → 2.0.0

package/dist/fiscal.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview Fiscal year and accounting period utilities
+ * Supports configurable fiscal year start months for business calculations
+ */
+/**
+ * Fiscal year configuration
+ */
+export interface FiscalConfig {
+    /** Month when fiscal year starts (1-12, default: 1 for January) */
+    startMonth: number;
+}
+/**
+ * Get the fiscal year for a given date
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns The fiscal year number
+ * @example
+ * // Calendar year (Jan start)
+ * getFiscalYear(new Date('2024-03-15')) // 2024
+ *
+ * // April fiscal year (UK/India style)
+ * getFiscalYear(new Date('2024-03-15'), { startMonth: 4 }) // 2023
+ * getFiscalYear(new Date('2024-04-15'), { startMonth: 4 }) // 2024
+ *
+ * // July fiscal year (Australia style)
+ * getFiscalYear(new Date('2024-06-15'), { startMonth: 7 }) // 2023
+ * getFiscalYear(new Date('2024-07-15'), { startMonth: 7 }) // 2024
+ */
+export declare function getFiscalYear(date: Date, config?: Partial<FiscalConfig>): number;
+/**
+ * Get the fiscal quarter for a given date (1-4)
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns The fiscal quarter (1-4)
+ * @example
+ * // Calendar year quarters
+ * getFiscalQuarter(new Date('2024-01-15')) // 1
+ * getFiscalQuarter(new Date('2024-04-15')) // 2
+ *
+ * // April fiscal year
+ * getFiscalQuarter(new Date('2024-04-15'), { startMonth: 4 }) // 1
+ * getFiscalQuarter(new Date('2024-07-15'), { startMonth: 4 }) // 2
+ */
+export declare function getFiscalQuarter(date: Date, config?: Partial<FiscalConfig>): number;
+/**
+ * Get the start date of a fiscal year
+ * @param fiscalYear - The fiscal year
+ * @param config - Fiscal year configuration
+ * @returns Start date of the fiscal year
+ * @example
+ * getFiscalYearStart(2024) // 2024-01-01
+ * getFiscalYearStart(2024, { startMonth: 4 }) // 2024-04-01 (FY2024 starts Apr 2024)
+ * getFiscalYearStart(2024, { startMonth: 7 }) // 2024-07-01 (FY2024 starts Jul 2024)
+ */
+export declare function getFiscalYearStart(fiscalYear: number, config?: Partial<FiscalConfig>): Date;
+/**
+ * Get the end date of a fiscal year
+ * @param fiscalYear - The fiscal year
+ * @param config - Fiscal year configuration
+ * @returns End date of the fiscal year (last day, 23:59:59.999)
+ * @example
+ * getFiscalYearEnd(2024) // 2024-12-31
+ * getFiscalYearEnd(2024, { startMonth: 4 }) // 2025-03-31 (FY2024 ends Mar 2025)
+ * getFiscalYearEnd(2024, { startMonth: 7 }) // 2025-06-30 (FY2024 ends Jun 2025)
+ */
+export declare function getFiscalYearEnd(fiscalYear: number, config?: Partial<FiscalConfig>): Date;
+/**
+ * Get the start date of a fiscal quarter
+ * @param fiscalYear - The fiscal year
+ * @param quarter - The quarter (1-4)
+ * @param config - Fiscal year configuration
+ * @returns Start date of the fiscal quarter
+ * @example
+ * getFiscalQuarterStart(2024, 1) // 2024-01-01
+ * getFiscalQuarterStart(2024, 2) // 2024-04-01
+ * getFiscalQuarterStart(2024, 1, { startMonth: 4 }) // 2023-04-01
+ * getFiscalQuarterStart(2024, 2, { startMonth: 4 }) // 2023-07-01
+ */
+export declare function getFiscalQuarterStart(fiscalYear: number, quarter: number, config?: Partial<FiscalConfig>): Date;
+/**
+ * Get the end date of a fiscal quarter
+ * @param fiscalYear - The fiscal year
+ * @param quarter - The quarter (1-4)
+ * @param config - Fiscal year configuration
+ * @returns End date of the fiscal quarter (last day, 23:59:59.999)
+ * @example
+ * getFiscalQuarterEnd(2024, 1) // 2024-03-31
+ * getFiscalQuarterEnd(2024, 2) // 2024-06-30
+ * getFiscalQuarterEnd(2024, 1, { startMonth: 4 }) // 2023-06-30
+ */
+export declare function getFiscalQuarterEnd(fiscalYear: number, quarter: number, config?: Partial<FiscalConfig>): Date;
+/**
+ * Check if two dates are in the same fiscal year
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @param config - Fiscal year configuration
+ * @returns True if both dates are in the same fiscal year
+ */
+export declare function isSameFiscalYear(date1: Date, date2: Date, config?: Partial<FiscalConfig>): boolean;
+/**
+ * Check if two dates are in the same fiscal quarter
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @param config - Fiscal year configuration
+ * @returns True if both dates are in the same fiscal year and quarter
+ */
+export declare function isSameFiscalQuarter(date1: Date, date2: Date, config?: Partial<FiscalConfig>): boolean;
+/**
+ * Get the fiscal month (1-12) within the fiscal year
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns The fiscal month (1-12, where 1 is the first month of fiscal year)
+ * @example
+ * getFiscalMonth(new Date('2024-01-15')) // 1
+ * getFiscalMonth(new Date('2024-04-15'), { startMonth: 4 }) // 1
+ * getFiscalMonth(new Date('2024-03-15'), { startMonth: 4 }) // 12
+ */
+export declare function getFiscalMonth(date: Date, config?: Partial<FiscalConfig>): number;
+/**
+ * Get the number of days remaining in the fiscal year
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns Number of days remaining in the fiscal year
+ */
+export declare function getDaysRemainingInFiscalYear(date: Date, config?: Partial<FiscalConfig>): number;
+/**
+ * Get the number of days elapsed in the fiscal year
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns Number of days elapsed in the fiscal year (including the given date)
+ */
+export declare function getDaysElapsedInFiscalYear(date: Date, config?: Partial<FiscalConfig>): number;
+/**
+ * Get fiscal year progress as a percentage
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns Percentage of fiscal year completed (0-100)
+ */
+export declare function getFiscalYearProgress(date: Date, config?: Partial<FiscalConfig>): number;
+/**
+ * Get the fiscal week number (1-53) within the fiscal year
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns The fiscal week number
+ */
+export declare function getFiscalWeek(date: Date, config?: Partial<FiscalConfig>): number;
+/**
+ * Common fiscal year configurations
+ */
+export declare const FISCAL_PRESETS: {
+    /** Calendar year (January start) - Default */
+    readonly CALENDAR: FiscalConfig;
+    /** UK/India government fiscal year (April start) */
+    readonly UK_INDIA: FiscalConfig;
+    /** Australian fiscal year (July start) */
+    readonly AUSTRALIA: FiscalConfig;
+    /** US federal government fiscal year (October start) */
+    readonly US_FEDERAL: FiscalConfig;
+};
+/**
+ * Format fiscal year as string (e.g., "FY2024" or "FY2023/24")
+ * @param fiscalYear - The fiscal year
+ * @param config - Fiscal year configuration
+ * @param format - Format style: 'short' (FY2024) or 'long' (FY2023/24)
+ * @returns Formatted fiscal year string
+ */
+export declare function formatFiscalYear(fiscalYear: number, config?: Partial<FiscalConfig>, format?: 'short' | 'long'): string;
+/**
+ * Format fiscal quarter as string (e.g., "Q1 FY2024")
+ * @param fiscalYear - The fiscal year
+ * @param quarter - The quarter (1-4)
+ * @param config - Fiscal year configuration
+ * @returns Formatted fiscal quarter string
+ */
+export declare function formatFiscalQuarter(fiscalYear: number, quarter: number, config?: Partial<FiscalConfig>): string;
+/**
+ * Get fiscal period info for a date
+ * @param date - The date to analyze
+ * @param config - Fiscal year configuration
+ * @returns Object with fiscal period information
+ */
+export declare function getFiscalPeriodInfo(date: Date, config?: Partial<FiscalConfig>): {
+    fiscalYear: number;
+    fiscalQuarter: number;
+    fiscalMonth: number;
+    fiscalWeek: number;
+    daysElapsed: number;
+    daysRemaining: number;
+    progress: number;
+    quarterStart: Date;
+    quarterEnd: Date;
+    yearStart: Date;
+    yearEnd: Date;
+};
+//# sourceMappingURL=fiscal.d.ts.map

package/dist/fiscal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiscal.d.ts","sourceRoot":"","sources":["../src/fiscal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,MAAM,CAYR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,MAAM,CAWR;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,IAAI,CAIN;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,IAAI,CAeN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,IAAI,CAaN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,IAAI,CAoBN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,IAAI,EACX,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,OAAO,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,IAAI,EACX,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,OAAO,CAKT;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,MAAM,CAUR;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,MAAM,CAWR;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,MAAM,CAGR;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;IACzB,8CAA8C;uBACf,YAAY;IAC3C,oDAAoD;uBACrB,YAAY;IAC3C,0CAA0C;wBACV,YAAY;IAC5C,wDAAwD;yBACtB,YAAY;CACtC,CAAC;AAEX;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,EAClC,MAAM,GAAE,OAAO,GAAG,MAAgB,GACjC,MAAM,CAWR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GACjC;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,IAAI,CAAC;IACnB,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;CACf,CAiBA"}

package/dist/fiscal.js

@@ -0,0 +1,295 @@
+/**
+ * @fileoverview Fiscal year and accounting period utilities
+ * Supports configurable fiscal year start months for business calculations
+ */
+const DEFAULT_CONFIG = {
+    startMonth: 1, // January (calendar year)
+};
+/**
+ * Get the fiscal year for a given date
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns The fiscal year number
+ * @example
+ * // Calendar year (Jan start)
+ * getFiscalYear(new Date('2024-03-15')) // 2024
+ *
+ * // April fiscal year (UK/India style)
+ * getFiscalYear(new Date('2024-03-15'), { startMonth: 4 }) // 2023
+ * getFiscalYear(new Date('2024-04-15'), { startMonth: 4 }) // 2024
+ *
+ * // July fiscal year (Australia style)
+ * getFiscalYear(new Date('2024-06-15'), { startMonth: 7 }) // 2023
+ * getFiscalYear(new Date('2024-07-15'), { startMonth: 7 }) // 2024
+ */
+export function getFiscalYear(date, config = {}) {
+    const { startMonth } = { ...DEFAULT_CONFIG, ...config };
+    const month = date.getMonth() + 1; // 1-12
+    const year = date.getFullYear();
+    if (startMonth === 1) {
+        return year;
+    }
+    // Fiscal year is named by when it starts
+    // If current month is before fiscal year start, we're still in the fiscal year that started last calendar year
+    return month < startMonth ? year - 1 : year;
+}
+/**
+ * Get the fiscal quarter for a given date (1-4)
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns The fiscal quarter (1-4)
+ * @example
+ * // Calendar year quarters
+ * getFiscalQuarter(new Date('2024-01-15')) // 1
+ * getFiscalQuarter(new Date('2024-04-15')) // 2
+ *
+ * // April fiscal year
+ * getFiscalQuarter(new Date('2024-04-15'), { startMonth: 4 }) // 1
+ * getFiscalQuarter(new Date('2024-07-15'), { startMonth: 4 }) // 2
+ */
+export function getFiscalQuarter(date, config = {}) {
+    const { startMonth } = { ...DEFAULT_CONFIG, ...config };
+    const month = date.getMonth() + 1; // 1-12
+    // Calculate months since fiscal year start
+    let monthsIntoFiscalYear = month - startMonth;
+    if (monthsIntoFiscalYear < 0) {
+        monthsIntoFiscalYear += 12;
+    }
+    return Math.floor(monthsIntoFiscalYear / 3) + 1;
+}
+/**
+ * Get the start date of a fiscal year
+ * @param fiscalYear - The fiscal year
+ * @param config - Fiscal year configuration
+ * @returns Start date of the fiscal year
+ * @example
+ * getFiscalYearStart(2024) // 2024-01-01
+ * getFiscalYearStart(2024, { startMonth: 4 }) // 2024-04-01 (FY2024 starts Apr 2024)
+ * getFiscalYearStart(2024, { startMonth: 7 }) // 2024-07-01 (FY2024 starts Jul 2024)
+ */
+export function getFiscalYearStart(fiscalYear, config = {}) {
+    const { startMonth } = { ...DEFAULT_CONFIG, ...config };
+    // Fiscal year N starts in the startMonth of calendar year N
+    return new Date(fiscalYear, startMonth - 1, 1);
+}
+/**
+ * Get the end date of a fiscal year
+ * @param fiscalYear - The fiscal year
+ * @param config - Fiscal year configuration
+ * @returns End date of the fiscal year (last day, 23:59:59.999)
+ * @example
+ * getFiscalYearEnd(2024) // 2024-12-31
+ * getFiscalYearEnd(2024, { startMonth: 4 }) // 2025-03-31 (FY2024 ends Mar 2025)
+ * getFiscalYearEnd(2024, { startMonth: 7 }) // 2025-06-30 (FY2024 ends Jun 2025)
+ */
+export function getFiscalYearEnd(fiscalYear, config = {}) {
+    const { startMonth } = { ...DEFAULT_CONFIG, ...config };
+    if (startMonth === 1) {
+        return new Date(fiscalYear, 11, 31, 23, 59, 59, 999);
+    }
+    // FY ends the day before the next FY starts
+    // FY N ends in (startMonth - 1) of year (N + 1)
+    const endMonth = startMonth - 1; // Month before start month (0-indexed: 0=Jan...11=Dec)
+    const endYear = fiscalYear + 1;
+    // Get last day of the end month
+    const lastDay = new Date(endYear, endMonth, 0).getDate();
+    return new Date(endYear, endMonth - 1, lastDay, 23, 59, 59, 999);
+}
+/**
+ * Get the start date of a fiscal quarter
+ * @param fiscalYear - The fiscal year
+ * @param quarter - The quarter (1-4)
+ * @param config - Fiscal year configuration
+ * @returns Start date of the fiscal quarter
+ * @example
+ * getFiscalQuarterStart(2024, 1) // 2024-01-01
+ * getFiscalQuarterStart(2024, 2) // 2024-04-01
+ * getFiscalQuarterStart(2024, 1, { startMonth: 4 }) // 2023-04-01
+ * getFiscalQuarterStart(2024, 2, { startMonth: 4 }) // 2023-07-01
+ */
+export function getFiscalQuarterStart(fiscalYear, quarter, config = {}) {
+    if (quarter < 1 || quarter > 4) {
+        throw new Error('Quarter must be between 1 and 4');
+    }
+    const { startMonth } = { ...DEFAULT_CONFIG, ...config };
+    const fyStart = getFiscalYearStart(fiscalYear, config);
+    // Add (quarter - 1) * 3 months to fiscal year start
+    const monthsToAdd = (quarter - 1) * 3;
+    const resultMonth = fyStart.getMonth() + monthsToAdd;
+    return new Date(fyStart.getFullYear(), resultMonth, 1);
+}
+/**
+ * Get the end date of a fiscal quarter
+ * @param fiscalYear - The fiscal year
+ * @param quarter - The quarter (1-4)
+ * @param config - Fiscal year configuration
+ * @returns End date of the fiscal quarter (last day, 23:59:59.999)
+ * @example
+ * getFiscalQuarterEnd(2024, 1) // 2024-03-31
+ * getFiscalQuarterEnd(2024, 2) // 2024-06-30
+ * getFiscalQuarterEnd(2024, 1, { startMonth: 4 }) // 2023-06-30
+ */
+export function getFiscalQuarterEnd(fiscalYear, quarter, config = {}) {
+    if (quarter < 1 || quarter > 4) {
+        throw new Error('Quarter must be between 1 and 4');
+    }
+    const quarterStart = getFiscalQuarterStart(fiscalYear, quarter, config);
+    // End of quarter is last day of the third month
+    const endMonth = quarterStart.getMonth() + 3;
+    const lastDay = new Date(quarterStart.getFullYear(), endMonth, 0).getDate();
+    return new Date(quarterStart.getFullYear(), endMonth - 1, lastDay, 23, 59, 59, 999);
+}
+/**
+ * Check if two dates are in the same fiscal year
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @param config - Fiscal year configuration
+ * @returns True if both dates are in the same fiscal year
+ */
+export function isSameFiscalYear(date1, date2, config = {}) {
+    return getFiscalYear(date1, config) === getFiscalYear(date2, config);
+}
+/**
+ * Check if two dates are in the same fiscal quarter
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @param config - Fiscal year configuration
+ * @returns True if both dates are in the same fiscal year and quarter
+ */
+export function isSameFiscalQuarter(date1, date2, config = {}) {
+    return (getFiscalYear(date1, config) === getFiscalYear(date2, config) &&
+        getFiscalQuarter(date1, config) === getFiscalQuarter(date2, config));
+}
+/**
+ * Get the fiscal month (1-12) within the fiscal year
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns The fiscal month (1-12, where 1 is the first month of fiscal year)
+ * @example
+ * getFiscalMonth(new Date('2024-01-15')) // 1
+ * getFiscalMonth(new Date('2024-04-15'), { startMonth: 4 }) // 1
+ * getFiscalMonth(new Date('2024-03-15'), { startMonth: 4 }) // 12
+ */
+export function getFiscalMonth(date, config = {}) {
+    const { startMonth } = { ...DEFAULT_CONFIG, ...config };
+    const month = date.getMonth() + 1; // 1-12
+    let fiscalMonth = month - startMonth + 1;
+    if (fiscalMonth <= 0) {
+        fiscalMonth += 12;
+    }
+    return fiscalMonth;
+}
+/**
+ * Get the number of days remaining in the fiscal year
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns Number of days remaining in the fiscal year
+ */
+export function getDaysRemainingInFiscalYear(date, config = {}) {
+    const fiscalYear = getFiscalYear(date, config);
+    const fyEnd = getFiscalYearEnd(fiscalYear, config);
+    const startOfDay = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    const diffMs = fyEnd.getTime() - startOfDay.getTime();
+    return Math.ceil(diffMs / (1000 * 60 * 60 * 24));
+}
+/**
+ * Get the number of days elapsed in the fiscal year
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns Number of days elapsed in the fiscal year (including the given date)
+ */
+export function getDaysElapsedInFiscalYear(date, config = {}) {
+    const fiscalYear = getFiscalYear(date, config);
+    const fyStart = getFiscalYearStart(fiscalYear, config);
+    const startOfDay = new Date(date.getFullYear(), date.getMonth(), date.getDate());
+    const diffMs = startOfDay.getTime() - fyStart.getTime();
+    return Math.floor(diffMs / (1000 * 60 * 60 * 24)) + 1;
+}
+/**
+ * Get fiscal year progress as a percentage
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns Percentage of fiscal year completed (0-100)
+ */
+export function getFiscalYearProgress(date, config = {}) {
+    const fiscalYear = getFiscalYear(date, config);
+    const fyStart = getFiscalYearStart(fiscalYear, config);
+    const fyEnd = getFiscalYearEnd(fiscalYear, config);
+    const totalDays = Math.ceil((fyEnd.getTime() - fyStart.getTime()) / (1000 * 60 * 60 * 24));
+    const elapsed = getDaysElapsedInFiscalYear(date, config);
+    return Math.min(100, Math.round((elapsed / totalDays) * 10000) / 100);
+}
+/**
+ * Get the fiscal week number (1-53) within the fiscal year
+ * @param date - The date to check
+ * @param config - Fiscal year configuration
+ * @returns The fiscal week number
+ */
+export function getFiscalWeek(date, config = {}) {
+    const elapsed = getDaysElapsedInFiscalYear(date, config);
+    return Math.ceil(elapsed / 7);
+}
+/**
+ * Common fiscal year configurations
+ */
+export const FISCAL_PRESETS = {
+    /** Calendar year (January start) - Default */
+    CALENDAR: { startMonth: 1 },
+    /** UK/India government fiscal year (April start) */
+    UK_INDIA: { startMonth: 4 },
+    /** Australian fiscal year (July start) */
+    AUSTRALIA: { startMonth: 7 },
+    /** US federal government fiscal year (October start) */
+    US_FEDERAL: { startMonth: 10 },
+};
+/**
+ * Format fiscal year as string (e.g., "FY2024" or "FY2023/24")
+ * @param fiscalYear - The fiscal year
+ * @param config - Fiscal year configuration
+ * @param format - Format style: 'short' (FY2024) or 'long' (FY2023/24)
+ * @returns Formatted fiscal year string
+ */
+export function formatFiscalYear(fiscalYear, config = {}, format = 'short') {
+    const { startMonth } = { ...DEFAULT_CONFIG, ...config };
+    if (format === 'short' || startMonth === 1) {
+        return `FY${fiscalYear}`;
+    }
+    // For non-calendar fiscal years, show both years
+    const calendarYearStart = fiscalYear - 1;
+    const shortEndYear = fiscalYear.toString().slice(-2);
+    return `FY${calendarYearStart}/${shortEndYear}`;
+}
+/**
+ * Format fiscal quarter as string (e.g., "Q1 FY2024")
+ * @param fiscalYear - The fiscal year
+ * @param quarter - The quarter (1-4)
+ * @param config - Fiscal year configuration
+ * @returns Formatted fiscal quarter string
+ */
+export function formatFiscalQuarter(fiscalYear, quarter, config = {}) {
+    const fyString = formatFiscalYear(fiscalYear, config, 'short');
+    return `Q${quarter} ${fyString}`;
+}
+/**
+ * Get fiscal period info for a date
+ * @param date - The date to analyze
+ * @param config - Fiscal year configuration
+ * @returns Object with fiscal period information
+ */
+export function getFiscalPeriodInfo(date, config = {}) {
+    const fiscalYear = getFiscalYear(date, config);
+    const fiscalQuarter = getFiscalQuarter(date, config);
+    return {
+        fiscalYear,
+        fiscalQuarter,
+        fiscalMonth: getFiscalMonth(date, config),
+        fiscalWeek: getFiscalWeek(date, config),
+        daysElapsed: getDaysElapsedInFiscalYear(date, config),
+        daysRemaining: getDaysRemainingInFiscalYear(date, config),
+        progress: getFiscalYearProgress(date, config),
+        quarterStart: getFiscalQuarterStart(fiscalYear, fiscalQuarter, config),
+        quarterEnd: getFiscalQuarterEnd(fiscalYear, fiscalQuarter, config),
+        yearStart: getFiscalYearStart(fiscalYear, config),
+        yearEnd: getFiscalYearEnd(fiscalYear, config),
+    };
+}

package/dist/format.d.ts

@@ -22,4 +22,69 @@ export declare function formatTime(date: Date, format?: '12h' | '24h' | 'iso'):
  * @param duration - duration string (e.g., "1h 30m", "2d", "45s")
  */
 export declare function parseDuration(duration: string): number;
+/**
+ * Format a date using a pattern string
+ * @param date - date to format
+ * @param pattern - format pattern (e.g., "YYYY-MM-DD", "MMM D, YYYY")
+ *
+ * Supported tokens:
+ * - YYYY: 4-digit year
+ * - YY: 2-digit year
+ * - MMMM: Full month name (January)
+ * - MMM: Short month name (Jan)
+ * - MM: Month with leading zero (01-12)
+ * - M: Month (1-12)
+ * - DDDD: Full day name (Monday)
+ * - DDD: Short day name (Mon)
+ * - DD: Day with leading zero (01-31)
+ * - D: Day (1-31)
+ * - HH: Hours 24h with leading zero (00-23)
+ * - H: Hours 24h (0-23)
+ * - hh: Hours 12h with leading zero (01-12)
+ * - h: Hours 12h (1-12)
+ * - mm: Minutes with leading zero (00-59)
+ * - ss: Seconds with leading zero (00-59)
+ * - SSS: Milliseconds (000-999)
+ * - A: AM/PM
+ * - a: am/pm
+ */
+export declare function formatDate(date: Date, pattern: string): string;
+/**
+ * Format a relative time string (e.g., "in 2 days", "3 hours ago")
+ * @param date - target date
+ * @param baseDate - base date (default: now)
+ */
+export declare function formatRelativeTime(date: Date, baseDate?: Date): string;
+/**
+ * Format a date range (e.g., "Jan 5 - Jan 10, 2025")
+ * @param start - start date
+ * @param end - end date
+ * @param options - formatting options
+ */
+export declare function formatDateRange(start: Date, end: Date, options?: {
+    separator?: string;
+    includeTime?: boolean;
+    format?: 'short' | 'medium' | 'long';
+}): string;
+/**
+ * Format a number as an ordinal (1st, 2nd, 3rd, etc.)
+ * @param n - number to format
+ */
+export declare function formatOrdinal(n: number): string;
+/**
+ * Format a day of month as an ordinal (1st, 2nd, 3rd, etc.)
+ * @param date - date to format
+ */
+export declare function formatDayOrdinal(date: Date): string;
+/**
+ * Format a duration in a compact form (e.g., "02:30:45")
+ * @param ms - milliseconds
+ * @param showHours - always show hours even if 0
+ */
+export declare function formatDurationCompact(ms: number, showHours?: boolean): string;
+/**
+ * Format a date/time for display in a calendar
+ * @param date - date to format
+ */
+export declare function formatCalendarDate(date: Date): string;
 //# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,aAAa,EACd,MAAM,gBAAgB,CAAC;AAGxB;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA2E9E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA+CvE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,GAAE,KAAK,GAAG,KAAK,GAAG,KAAa,GAAG,MAAM,CAcpF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyDtD"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,aAAa,EACd,MAAM,gBAAgB,CAAC;AAGxB;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA2E9E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA+CvE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,GAAE,KAAK,GAAG,KAAK,GAAG,KAAa,GAAG,MAAM,CAcpF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyDtD;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA4C9D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAE,IAAiB,GAAG,MAAM,CAuClF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,IAAI,EACX,GAAG,EAAE,IAAI,EACT,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;CACjC,GACL,MAAM,CA6BR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,OAAc,GAAG,MAAM,CAYnF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAwBrD"}