ts-time-utils 1.1.0 → 2.0.0

package/dist/calendar.d.ts

@@ -79,4 +79,107 @@ export declare function getFirstDayOfYear(year: number): Date;
  * @param year - year
  */
 export declare function getLastDayOfYear(year: number): Date;
+/**
+ * Get the nth occurrence of a day in a month (e.g., 2nd Monday)
+ * @param year - year
+ * @param month - month (0-11)
+ * @param dayOfWeek - day of week (0=Sunday, 6=Saturday)
+ * @param n - occurrence (1-5, or -1 for last)
+ */
+export declare function getNthDayOfMonth(year: number, month: number, dayOfWeek: number, n: number): Date | null;
+/**
+ * US Holiday type
+ */
+export interface USHoliday {
+    name: string;
+    date: Date;
+    type: 'federal' | 'observance';
+}
+/**
+ * Get New Year's Day
+ * @param year - year
+ */
+export declare function getNewYearsDay(year: number): Date;
+/**
+ * Get Martin Luther King Jr. Day (3rd Monday of January)
+ * @param year - year
+ */
+export declare function getMLKDay(year: number): Date | null;
+/**
+ * Get Presidents' Day (3rd Monday of February)
+ * @param year - year
+ */
+export declare function getPresidentsDay(year: number): Date | null;
+/**
+ * Get Memorial Day (last Monday of May)
+ * @param year - year
+ */
+export declare function getMemorialDay(year: number): Date | null;
+/**
+ * Get Independence Day (July 4th)
+ * @param year - year
+ */
+export declare function getIndependenceDay(year: number): Date;
+/**
+ * Get Labor Day (1st Monday of September)
+ * @param year - year
+ */
+export declare function getLaborDay(year: number): Date | null;
+/**
+ * Get Columbus Day (2nd Monday of October)
+ * @param year - year
+ */
+export declare function getColumbusDay(year: number): Date | null;
+/**
+ * Get Veterans Day (November 11th)
+ * @param year - year
+ */
+export declare function getVeteransDay(year: number): Date;
+/**
+ * Get Thanksgiving Day (4th Thursday of November)
+ * @param year - year
+ */
+export declare function getThanksgivingDay(year: number): Date | null;
+/**
+ * Get Christmas Day (December 25th)
+ * @param year - year
+ */
+export declare function getChristmasDay(year: number): Date;
+/**
+ * Get Good Friday (Friday before Easter)
+ * @param year - year
+ */
+export declare function getGoodFriday(year: number): Date;
+/**
+ * Get all US federal holidays for a year
+ * @param year - year
+ */
+export declare function getUSHolidays(year: number): USHoliday[];
+/**
+ * Check if a date is a US federal holiday
+ * @param date - date to check
+ */
+export declare function isUSHoliday(date: Date): boolean;
+/**
+ * Get the name of a US holiday for a given date
+ * @param date - date to check
+ * @returns holiday name or null if not a holiday
+ */
+export declare function getUSHolidayName(date: Date): string | null;
+/**
+ * Get the start of the week for a date (Monday)
+ * @param date - any date
+ */
+export declare function getStartOfWeek(date: Date): Date;
+/**
+ * Get the end of the week for a date (Sunday)
+ * @param date - any date
+ */
+export declare function getEndOfWeek(date: Date): Date;
+/**
+ * Get all weeks in a month as arrays of dates
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export declare function getWeeksInMonth(year: number, month: number): Date[][];
 //# sourceMappingURL=calendar.d.ts.map

package/dist/calendar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../src/calendar.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAMhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAKjD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAI/C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAUD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkB5C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAGvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAKtE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAEnD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEnD"}
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../src/calendar.ts"],"names":[],"mappings":"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"}

package/dist/calendar.js

@@ -152,3 +152,227 @@ export function getFirstDayOfYear(year) {
 export function getLastDayOfYear(year) {
     return new Date(year, 11, 31);
 }
+/**
+ * Get the nth occurrence of a day in a month (e.g., 2nd Monday)
+ * @param year - year
+ * @param month - month (0-11)
+ * @param dayOfWeek - day of week (0=Sunday, 6=Saturday)
+ * @param n - occurrence (1-5, or -1 for last)
+ */
+export function getNthDayOfMonth(year, month, dayOfWeek, n) {
+    if (n === 0 || n < -1 || n > 5)
+        return null;
+    const firstDay = new Date(year, month, 1);
+    const lastDay = new Date(year, month + 1, 0);
+    if (n === -1) {
+        // Last occurrence
+        let date = lastDay.getDate();
+        while (date > 0) {
+            const d = new Date(year, month, date);
+            if (d.getDay() === dayOfWeek)
+                return d;
+            date--;
+        }
+        return null;
+    }
+    // Find nth occurrence
+    let count = 0;
+    for (let date = 1; date <= lastDay.getDate(); date++) {
+        const d = new Date(year, month, date);
+        if (d.getDay() === dayOfWeek) {
+            count++;
+            if (count === n)
+                return d;
+        }
+    }
+    return null;
+}
+/**
+ * Get New Year's Day
+ * @param year - year
+ */
+export function getNewYearsDay(year) {
+    return new Date(year, 0, 1);
+}
+/**
+ * Get Martin Luther King Jr. Day (3rd Monday of January)
+ * @param year - year
+ */
+export function getMLKDay(year) {
+    return getNthDayOfMonth(year, 0, 1, 3);
+}
+/**
+ * Get Presidents' Day (3rd Monday of February)
+ * @param year - year
+ */
+export function getPresidentsDay(year) {
+    return getNthDayOfMonth(year, 1, 1, 3);
+}
+/**
+ * Get Memorial Day (last Monday of May)
+ * @param year - year
+ */
+export function getMemorialDay(year) {
+    return getNthDayOfMonth(year, 4, 1, -1);
+}
+/**
+ * Get Independence Day (July 4th)
+ * @param year - year
+ */
+export function getIndependenceDay(year) {
+    return new Date(year, 6, 4);
+}
+/**
+ * Get Labor Day (1st Monday of September)
+ * @param year - year
+ */
+export function getLaborDay(year) {
+    return getNthDayOfMonth(year, 8, 1, 1);
+}
+/**
+ * Get Columbus Day (2nd Monday of October)
+ * @param year - year
+ */
+export function getColumbusDay(year) {
+    return getNthDayOfMonth(year, 9, 1, 2);
+}
+/**
+ * Get Veterans Day (November 11th)
+ * @param year - year
+ */
+export function getVeteransDay(year) {
+    return new Date(year, 10, 11);
+}
+/**
+ * Get Thanksgiving Day (4th Thursday of November)
+ * @param year - year
+ */
+export function getThanksgivingDay(year) {
+    return getNthDayOfMonth(year, 10, 4, 4);
+}
+/**
+ * Get Christmas Day (December 25th)
+ * @param year - year
+ */
+export function getChristmasDay(year) {
+    return new Date(year, 11, 25);
+}
+/**
+ * Get Good Friday (Friday before Easter)
+ * @param year - year
+ */
+export function getGoodFriday(year) {
+    const easter = getEaster(year);
+    const goodFriday = new Date(easter);
+    goodFriday.setDate(easter.getDate() - 2);
+    return goodFriday;
+}
+/**
+ * Get all US federal holidays for a year
+ * @param year - year
+ */
+export function getUSHolidays(year) {
+    const holidays = [];
+    holidays.push({ name: "New Year's Day", date: getNewYearsDay(year), type: 'federal' });
+    const mlk = getMLKDay(year);
+    if (mlk)
+        holidays.push({ name: "Martin Luther King Jr. Day", date: mlk, type: 'federal' });
+    const presidents = getPresidentsDay(year);
+    if (presidents)
+        holidays.push({ name: "Presidents' Day", date: presidents, type: 'federal' });
+    const memorial = getMemorialDay(year);
+    if (memorial)
+        holidays.push({ name: "Memorial Day", date: memorial, type: 'federal' });
+    holidays.push({ name: "Independence Day", date: getIndependenceDay(year), type: 'federal' });
+    const labor = getLaborDay(year);
+    if (labor)
+        holidays.push({ name: "Labor Day", date: labor, type: 'federal' });
+    const columbus = getColumbusDay(year);
+    if (columbus)
+        holidays.push({ name: "Columbus Day", date: columbus, type: 'federal' });
+    holidays.push({ name: "Veterans Day", date: getVeteransDay(year), type: 'federal' });
+    const thanksgiving = getThanksgivingDay(year);
+    if (thanksgiving)
+        holidays.push({ name: "Thanksgiving Day", date: thanksgiving, type: 'federal' });
+    holidays.push({ name: "Christmas Day", date: getChristmasDay(year), type: 'federal' });
+    return holidays.sort((a, b) => a.date.getTime() - b.date.getTime());
+}
+/**
+ * Check if a date is a US federal holiday
+ * @param date - date to check
+ */
+export function isUSHoliday(date) {
+    const holidays = getUSHolidays(date.getFullYear());
+    return holidays.some(h => h.date.getFullYear() === date.getFullYear() &&
+        h.date.getMonth() === date.getMonth() &&
+        h.date.getDate() === date.getDate());
+}
+/**
+ * Get the name of a US holiday for a given date
+ * @param date - date to check
+ * @returns holiday name or null if not a holiday
+ */
+export function getUSHolidayName(date) {
+    const holidays = getUSHolidays(date.getFullYear());
+    const holiday = holidays.find(h => h.date.getFullYear() === date.getFullYear() &&
+        h.date.getMonth() === date.getMonth() &&
+        h.date.getDate() === date.getDate());
+    return holiday ? holiday.name : null;
+}
+/**
+ * Get the start of the week for a date (Monday)
+ * @param date - any date
+ */
+export function getStartOfWeek(date) {
+    const d = new Date(date);
+    const day = d.getDay();
+    const diff = d.getDate() - day + (day === 0 ? -6 : 1); // Adjust for Monday start
+    d.setDate(diff);
+    d.setHours(0, 0, 0, 0);
+    return d;
+}
+/**
+ * Get the end of the week for a date (Sunday)
+ * @param date - any date
+ */
+export function getEndOfWeek(date) {
+    const start = getStartOfWeek(date);
+    const end = new Date(start);
+    end.setDate(start.getDate() + 6);
+    end.setHours(23, 59, 59, 999);
+    return end;
+}
+/**
+ * Get all weeks in a month as arrays of dates
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export function getWeeksInMonth(year, month) {
+    const weeks = [];
+    const firstDay = new Date(year, month, 1);
+    const lastDay = new Date(year, month + 1, 0);
+    let currentWeek = [];
+    const startDayOfWeek = firstDay.getDay() || 7; // Convert Sunday from 0 to 7 for ISO
+    // Add days from previous month to fill the first week
+    for (let i = 1; i < startDayOfWeek; i++) {
+        const prevDate = new Date(year, month, 1 - (startDayOfWeek - i));
+        currentWeek.push(prevDate);
+    }
+    // Add days of the current month
+    for (let day = 1; day <= lastDay.getDate(); day++) {
+        currentWeek.push(new Date(year, month, day));
+        if (currentWeek.length === 7) {
+            weeks.push(currentWeek);
+            currentWeek = [];
+        }
+    }
+    // Add days from next month to fill the last week
+    if (currentWeek.length > 0) {
+        let nextDay = 1;
+        while (currentWeek.length < 7) {
+            currentWeek.push(new Date(year, month + 1, nextDay++));
+        }
+        weeks.push(currentWeek);
+    }
+    return weeks;
+}

package/dist/compare.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview Date comparison, sorting, and array manipulation utilities
+ */
+/**
+ * Compare two dates for sorting
+ * @param a - First date
+ * @param b - Second date
+ * @returns Negative if a < b, positive if a > b, 0 if equal
+ * @example
+ * [date3, date1, date2].sort(compareDates) // [date1, date2, date3]
+ */
+export declare function compareDates(a: Date, b: Date): number;
+/**
+ * Compare two dates in reverse order for sorting
+ * @param a - First date
+ * @param b - Second date
+ * @returns Positive if a < b, negative if a > b, 0 if equal
+ * @example
+ * [date1, date3, date2].sort(compareDatesDesc) // [date3, date2, date1]
+ */
+export declare function compareDatesDesc(a: Date, b: Date): number;
+/**
+ * Sort an array of dates
+ * @param dates - Array of dates to sort
+ * @param direction - Sort direction: 'asc' (oldest first) or 'desc' (newest first)
+ * @returns New sorted array (does not mutate original)
+ * @example
+ * sortDates([date3, date1, date2]) // [date1, date2, date3]
+ * sortDates([date1, date2, date3], 'desc') // [date3, date2, date1]
+ */
+export declare function sortDates(dates: Date[], direction?: 'asc' | 'desc'): Date[];
+/**
+ * Find the minimum (earliest) date in an array
+ * @param dates - Array of dates
+ * @returns The earliest date, or undefined if array is empty
+ * @example
+ * minDate([date2, date1, date3]) // date1
+ */
+export declare function minDate(dates: Date[]): Date | undefined;
+/**
+ * Find the maximum (latest) date in an array
+ * @param dates - Array of dates
+ * @returns The latest date, or undefined if array is empty
+ * @example
+ * maxDate([date1, date3, date2]) // date3
+ */
+export declare function maxDate(dates: Date[]): Date | undefined;
+/**
+ * Find the date range (min and max) in an array
+ * @param dates - Array of dates
+ * @returns Object with min and max dates, or undefined if array is empty
+ * @example
+ * dateRange([date2, date1, date3]) // { min: date1, max: date3 }
+ */
+export declare function dateExtent(dates: Date[]): {
+    min: Date;
+    max: Date;
+} | undefined;
+/**
+ * Remove duplicate dates from an array
+ * @param dates - Array of dates
+ * @param precision - Precision for comparison: 'ms' (exact), 'second', 'minute', 'hour', 'day'
+ * @returns New array with duplicates removed (preserves first occurrence)
+ * @example
+ * uniqueDates([date1, date1Copy, date2]) // [date1, date2]
+ */
+export declare function uniqueDates(dates: Date[], precision?: 'ms' | 'second' | 'minute' | 'hour' | 'day'): Date[];
+/**
+ * Find the closest date to a target from an array of candidates
+ * @param target - The target date
+ * @param candidates - Array of candidate dates
+ * @returns The closest date, or undefined if candidates is empty
+ * @example
+ * closestDate(targetDate, [date1, date2, date3]) // closest to target
+ */
+export declare function closestDate(target: Date, candidates: Date[]): Date | undefined;
+/**
+ * Find the closest future date to a target
+ * @param target - The target date
+ * @param candidates - Array of candidate dates
+ * @returns The closest future date, or undefined if none found
+ */
+export declare function closestFutureDate(target: Date, candidates: Date[]): Date | undefined;
+/**
+ * Find the closest past date to a target
+ * @param target - The target date
+ * @param candidates - Array of candidate dates
+ * @returns The closest past date, or undefined if none found
+ */
+export declare function closestPastDate(target: Date, candidates: Date[]): Date | undefined;
+/**
+ * Clamp a date to be within a range
+ * @param date - The date to clamp
+ * @param min - Minimum allowed date
+ * @param max - Maximum allowed date
+ * @returns The clamped date
+ * @example
+ * clampDate(earlyDate, minDate, maxDate) // returns minDate
+ * clampDate(lateDate, minDate, maxDate) // returns maxDate
+ * clampDate(middleDate, minDate, maxDate) // returns middleDate
+ */
+export declare function clampDate(date: Date, min: Date, max: Date): Date;
+/**
+ * Check if a date is within a range (inclusive)
+ * @param date - The date to check
+ * @param min - Start of range
+ * @param max - End of range
+ * @returns True if date is within range
+ */
+export declare function isDateInRange(date: Date, min: Date, max: Date): boolean;
+/**
+ * Filter dates to only those within a range
+ * @param dates - Array of dates
+ * @param min - Start of range
+ * @param max - End of range
+ * @returns New array with only dates in range
+ */
+export declare function filterDatesInRange(dates: Date[], min: Date, max: Date): Date[];
+/**
+ * Group dates by a key function
+ * @param dates - Array of dates
+ * @param keyFn - Function to generate group key from date
+ * @returns Map of key to array of dates
+ * @example
+ * groupDates(dates, d => d.getFullYear()) // Map { 2023 => [...], 2024 => [...] }
+ * groupDates(dates, d => d.toISOString().slice(0, 7)) // Group by month
+ */
+export declare function groupDates<K>(dates: Date[], keyFn: (date: Date) => K): Map<K, Date[]>;
+/**
+ * Group dates by year
+ * @param dates - Array of dates
+ * @returns Map of year to array of dates
+ */
+export declare function groupDatesByYear(dates: Date[]): Map<number, Date[]>;
+/**
+ * Group dates by month (YYYY-MM format)
+ * @param dates - Array of dates
+ * @returns Map of month key to array of dates
+ */
+export declare function groupDatesByMonth(dates: Date[]): Map<string, Date[]>;
+/**
+ * Group dates by day (YYYY-MM-DD format)
+ * @param dates - Array of dates
+ * @returns Map of day key to array of dates
+ */
+export declare function groupDatesByDay(dates: Date[]): Map<string, Date[]>;
+/**
+ * Group dates by day of week (0-6, Sunday-Saturday)
+ * @param dates - Array of dates
+ * @returns Map of day of week to array of dates
+ */
+export declare function groupDatesByDayOfWeek(dates: Date[]): Map<number, Date[]>;
+/**
+ * Calculate the median date from an array
+ * @param dates - Array of dates
+ * @returns The median date, or undefined if array is empty
+ */
+export declare function medianDate(dates: Date[]): Date | undefined;
+/**
+ * Calculate the average/mean date from an array
+ * @param dates - Array of dates
+ * @returns The average date, or undefined if array is empty
+ */
+export declare function averageDate(dates: Date[]): Date | undefined;
+/**
+ * Round a date to the nearest unit
+ * @param date - The date to round
+ * @param unit - Unit to round to
+ * @returns New rounded date
+ * @example
+ * roundDate(new Date('2024-03-15T14:37:00'), 'hour') // 2024-03-15T15:00:00
+ * roundDate(new Date('2024-03-15T14:22:00'), 'hour') // 2024-03-15T14:00:00
+ */
+export declare function roundDate(date: Date, unit: 'minute' | 'hour' | 'day'): Date;
+/**
+ * Snap a date to a grid interval
+ * @param date - The date to snap
+ * @param intervalMinutes - Interval in minutes (e.g., 15 for quarter-hour)
+ * @param mode - Snap mode: 'floor' (down), 'ceil' (up), or 'round' (nearest)
+ * @returns New snapped date
+ * @example
+ * snapDate(new Date('2024-03-15T14:37:00'), 15) // 2024-03-15T14:30:00
+ * snapDate(new Date('2024-03-15T14:37:00'), 15, 'ceil') // 2024-03-15T14:45:00
+ */
+export declare function snapDate(date: Date, intervalMinutes: number, mode?: 'floor' | 'ceil' | 'round'): Date;
+/**
+ * Check if dates are in chronological order
+ * @param dates - Array of dates
+ * @param strict - If true, requires strictly increasing (no duplicates)
+ * @returns True if dates are in order
+ */
+export declare function isChronological(dates: Date[], strict?: boolean): boolean;
+/**
+ * Get the span (duration) between min and max dates
+ * @param dates - Array of dates
+ * @returns Duration in milliseconds, or 0 if less than 2 dates
+ */
+export declare function dateSpan(dates: Date[]): number;
+/**
+ * Partition dates into buckets based on a predicate
+ * @param dates - Array of dates
+ * @param predicate - Function that returns true for dates in first partition
+ * @returns Tuple of [matching, non-matching] date arrays
+ */
+export declare function partitionDates(dates: Date[], predicate: (date: Date) => boolean): [Date[], Date[]];
+/**
+ * Get the nth date from an array (supports negative indices)
+ * @param dates - Array of dates (will be sorted)
+ * @param n - Index (0-based, negative counts from end)
+ * @returns The nth date, or undefined if out of bounds
+ * @example
+ * nthDate(dates, 0) // earliest
+ * nthDate(dates, -1) // latest
+ * nthDate(dates, 2) // third earliest
+ */
+export declare function nthDate(dates: Date[], n: number): Date | undefined;
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAErD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,IAAI,EAAE,EACb,SAAS,GAAE,KAAK,GAAG,MAAc,GAChC,IAAI,EAAE,CAIR;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CAY9E;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,IAAI,EAAE,EACb,SAAS,GAAE,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAY,GAC5D,IAAI,EAAE,CAaR;AAoBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,CAgB9E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,CAIpF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,CAIlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,CAIhE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGvE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,IAAI,EAAE,CAE9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,IAAI,EAAE,EACb,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,GACvB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAchB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAMpE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAElE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAExE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,CAc1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,GAAG,SAAS,CAK3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAC9B,IAAI,CAyBN;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,IAAI,EACV,eAAe,EAAE,MAAM,EACvB,IAAI,GAAE,OAAO,GAAG,MAAM,GAAG,OAAiB,GACzC,IAAI,CAkBN;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,GAAE,OAAe,GAAG,OAAO,CAU/E;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAI9C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,IAAI,EAAE,EACb,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,GACjC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAalB;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAQlE"}