@mapvx/web-js 1.0.0

package/dist/es/utils/opening-hours-helper.d.ts

@@ -0,0 +1,395 @@
+import { type OpeningHours, type OpeningTime, type DaysOfTheWeek } from "../domain/models/openingHours";
+/**
+ * Helper class for opening hours.
+ */
+export declare class OpeningHoursHelper {
+    /**
+     * Gets the day of the week as a two-character string indicator.
+     *
+     * @param date The Date object to extract the day from.
+     * @returns A `DaysOfTheWeek` string representing the day of the week.
+     * @example
+     * ```typescript
+     * const date = new Date(2024, 0, 1); // Monday
+     * const day = OpeningHoursHelper.getDay(date);
+     * console.log(day); // "mo"
+     * ```
+     * @default Returns null if an error occurs or invalid date is provided.
+     */
+    static getDay(date: Date): DaysOfTheWeek | null;
+    /**
+     * Converts a 24-hour time format to 12-hour format with AM/PM.
+     *
+     * @param time24h The time string in 24-hour format (HH:mm).
+     * @returns Time formatted in 12-hour format with AM/PM.
+     * @example
+     * ```typescript
+     * const time12h = OpeningHoursHelper.convertSingleTimeTo12Hour("14:30");
+     * console.log(time12h); // "2:30 p.m."
+     *
+     * const morningTime = OpeningHoursHelper.convertSingleTimeTo12Hour("09:00");
+     * console.log(morningTime); // "9:00 a.m."
+     * ```
+     * @default Returns empty string "" if an error occurs or invalid time is provided.
+     */
+    static convertSingleTimeTo12Hour(time24h: string): string;
+    /**
+     * Formats an opening time schedule into a readable string.
+     *
+     * @param openingTime The opening time object containing open and close times.
+     * @returns Formatted time schedule string.
+     * @example
+     * ```typescript
+     * const schedule = { open: "09:00", close: "17:00" };
+     * const formatted = OpeningHoursHelper.formatTimeSchedule(schedule);
+     * console.log(formatted); // "9:00 a.m. - 5:00 p.m."
+     * ```
+     * @default Returns empty string "" if an error occurs or invalid opening time is provided.
+     */
+    static formatTimeSchedule(openingTime: OpeningTime): string;
+    /**
+     * Gets the day number (1-7) for a given day string.
+     *
+     * @param day The two-character day string (e.g., "mo", "tu").
+     * @returns The day number (1-7), or -1 if the day is invalid.
+     * @example
+     * ```typescript
+     * const dayNumber = OpeningHoursHelper.getDayNumber("mo");
+     * console.log(dayNumber); // 1
+     *
+     * const invalidDay = OpeningHoursHelper.getDayNumber("invalid");
+     * console.log(invalidDay); // -1
+     * ```
+     * @default Returns -1 if an error occurs or invalid day string is provided.
+     */
+    static getDayNumber(day: string): number;
+    /**
+     * Gets the full day name (localized) for a given day string.
+     *
+     * @param day The two-character day string (e.g., "mo", "tu").
+     * @returns The localized day name, or an empty string if the day is invalid.
+     * @example
+     * ```typescript
+     * const dayName = OpeningHoursHelper.getDayName("mo");
+     * console.log(dayName); // "Monday" (or localized equivalent)
+     *
+     * const invalidDay = OpeningHoursHelper.getDayName("invalid");
+     * console.log(invalidDay); // ""
+     * ```
+     * @default Returns empty string "" if an error occurs or invalid day string is provided.
+     */
+    static getDayName(day: string): string;
+    /**
+     * Sorts the opening hours object by day of the week.
+     *
+     * @param openingHours The opening hours object to sort.
+     * @returns A new object with the opening hours sorted by day of the week.
+     * @example
+     * ```typescript
+     * const unsortedHours = { fr: [...], mo: [...], we: [...] };
+     * const sortedHours = OpeningHoursHelper.sortDays(unsortedHours);
+     * console.log(Object.keys(sortedHours)); // ["mo", "we", "fr"]
+     * ```
+     * @default Returns the original openingHours object if an error occurs.
+     */
+    static sortDays(openingHours: OpeningHours): Record<string, OpeningTime[]>;
+    /**
+     * Checks if a store is open from the previous day (for overnight hours).
+     *
+     * @param openingHours The opening hours of the store.
+     * @param currentDate Optional date to check against. If not provided, uses the current date.
+     * @returns `true` if the store is open from the previous day, `false` otherwise.
+     * @example
+     * ```typescript
+     * const overnightHours = { mo: [{ open: "22:00", close: "06:00" }] };
+     * const isOpen = OpeningHoursHelper.isOpenFromPreviousDay(overnightHours);
+     * console.log(isOpen); // true if current time is between 22:00 and 06:00
+     * ```
+     * @default Returns `false` if an error occurs or invalid opening hours are provided.
+     */
+    static isOpenFromPreviousDay(openingHours: OpeningHours, currentDate?: Date): boolean;
+    /**
+     * Modifies the given Date object to represent the previous day.
+     *
+     * @param date The Date object to modify. This object will be mutated.
+     * @returns This function modifies the Date object in place and does not return a value.
+     * @example
+     * ```typescript
+     * const date = new Date(2024, 0, 15); // January 15, 2024
+     * OpeningHoursHelper.previousDate(date);
+     * console.log(date.getDate()); // 14
+     * ```
+     */
+    static previousDate(date: Date): void;
+    /**
+     * Modifies the given Date object to represent the next day.
+     *
+     * @param date The Date object to modify. This object will be mutated.
+     * @returns This function modifies the Date object in place and does not return a value.
+     * @example
+     * ```typescript
+     * const date = new Date(2024, 0, 15); // January 15, 2024
+     * OpeningHoursHelper.nextDate(date);
+     * console.log(date.getDate()); // 16
+     * ```
+     */
+    static nextDate(date: Date): void;
+    /**
+     * Checks if the current time is within the opening hours defined for the current day.
+     *
+     * @param openingHours An object containing the opening hours for each day of the week.
+     * @param currentDate Optional date to check against. If not provided, uses the current date.
+     * @returns `true` if the current time is within the opening hours, `false` otherwise.
+     * @example
+     * ```typescript
+     * const hours = { mo: [{ open: "09:00", close: "17:00" }] };
+     * const isOpen = OpeningHoursHelper.isWithinOpeningHours(hours);
+     * console.log(isOpen); // true if current time is between 09:00 and 17:00 on Monday
+     * ```
+     * @default Returns `false` if an error occurs or invalid opening hours are provided.
+     */
+    static isWithinOpeningHours(openingHours: OpeningHours, currentDate?: Date): boolean;
+    /**
+     * Checks if there are opening times defined for today.
+     *
+     * @param openingHours The opening hours of a store.
+     * @returns `true` if there are opening times for today, `false` otherwise.
+     * @example
+     * ```typescript
+     * const hours = { mo: [{ open: "09:00", close: "17:00" }] };
+     * const hasHours = OpeningHoursHelper.hasOpeningHoursToday(hours);
+     * console.log(hasHours); // true if today is Monday
+     * ```
+     * @default Returns `false` if an error occurs or invalid opening hours are provided.
+     */
+    static hasOpeningHoursToday(openingHours: OpeningHours): boolean;
+    /**
+     * Checks if a given string is a valid time in HH:mm format.
+     *
+     * @param time The string to validate.
+     * @returns `true` if the string is a valid time, `false` otherwise.
+     * @example
+     * ```typescript
+     * const isValid = OpeningHoursHelper.isValidTime("14:30");
+     * console.log(isValid); // true
+     *
+     * const isInvalid = OpeningHoursHelper.isValidTime("25:00");
+     * console.log(isInvalid); // false
+     * ```
+     * @default Returns `false` if an error occurs or invalid time format is provided.
+     */
+    static isValidTime(time: string): boolean;
+    /**
+     * Parses a time string (HH:mm) and combines it with a date to create a new Date object.
+     *
+     * @param time The time string in HH:mm format (e.g., "14:30").
+     * @param date An optional Date object to combine with the time. If not provided, the current date is used.
+     * @returns A new Date object representing the combined date and time.
+     * @example
+     * ```typescript
+     * const date = new Date(2024, 0, 15);
+     * const timeDate = OpeningHoursHelper.parseTimeAsDate("14:30", date);
+     * console.log(timeDate); // Date object for January 15, 2024 at 2:30 PM
+     * ```
+     * @default Returns current date if an error occurs or invalid time is provided.
+     */
+    static parseTimeAsDate(time: string, date?: Date): Date;
+    /**
+     * Flattens an array of OpeningTime objects into a single OpeningTime object,
+     * taking the earliest open time and the latest close time.
+     *
+     * @param openingTimes The array of OpeningTime objects to flatten.
+     * @returns A single OpeningTime object representing the flattened time range.
+     * @example
+     * ```typescript
+     * const times = [
+     *   { open: "09:00", close: "12:00" },
+     *   { open: "14:00", close: "18:00" }
+     * ];
+     * const flattened = OpeningHoursHelper.flattenOpeningTimes(times);
+     * console.log(flattened); // { open: "09:00", close: "18:00" }
+     * ```
+     * @default Returns `{ open: "00:00", close: "00:00" }` if an error occurs or invalid array is provided.
+     */
+    static flattenOpeningTimes(openingTimes: OpeningTime[]): OpeningTime;
+    /**
+     * Sorts a list of OpeningTime objects in place, based on the 'open' property.
+     *
+     * This method mutates the array and returns a reference to the same array.
+     *
+     * @param openingTimes The array of OpeningTime objects to sort. This array will be mutated.
+     * @returns The sorted array of OpeningTime objects (mutated in place).
+     * @example
+     * ```typescript
+     * const times = [
+     *   { open: "14:00", close: "18:00" },
+     *   { open: "09:00", close: "12:00" }
+     * ];
+     * const sorted = OpeningHoursHelper.sortOpeningTimesByOpen(times);
+     * console.log(sorted[0].open); // "09:00"
+     * ```
+     * @default Returns the original array if an error occurs.
+     */
+    static sortOpeningTimesByOpen(openingTimes: OpeningTime[]): OpeningTime[];
+    /**
+     * Formats the opening hours for the current day into a string representation.
+     *
+     * @param openingHours The opening hours for the store.
+     * @returns A string representing the opening hours for the current day, or an empty string if there are no opening hours for today.
+     * @example
+     * ```typescript
+     * const hours = { mo: [{ open: "09:00", close: "17:00" }] };
+     * const schedule = OpeningHoursHelper.formatCurrentDaySchedule(hours);
+     * console.log(schedule); // "9:00 a.m. - 5:00 p.m." (if today is Monday)
+     * ```
+     * @default Returns empty string "" if an error occurs or no opening hours for today.
+     */
+    static formatCurrentDaySchedule(openingHours: OpeningHours): string;
+    /**
+     * Formats the opening hours for the previous day into a string representation.
+     *
+     * @param openingHours The opening hours for the store.
+     * @returns A string representing the opening hours for the previous day, or an empty string if there are no opening hours for yesterday.
+     * @example
+     * ```typescript
+     * const hours = { su: [{ open: "10:00", close: "15:00" }] };
+     * const schedule = OpeningHoursHelper.formatPreviousDaySchedule(hours);
+     * console.log(schedule); // "10:00 a.m. - 3:00 p.m." (if yesterday was Sunday)
+     * ```
+     * @default Returns empty string "" if an error occurs or no opening hours for yesterday.
+     */
+    static formatPreviousDaySchedule(openingHours: OpeningHours): string;
+    /**
+     * Checks if the current time is within the specified opening hours.
+     *
+     * @param openHour The opening time in HH:mm format (e.g., "09:00").
+     * @param closeHour The closing time in HH:mm format (e.g., "18:00").
+     * @param currentHour The current time in HH:mm format (e.g., "14:30").
+     * @returns `true` if the current time is within the opening hours, `false` otherwise.
+     * @example
+     * ```typescript
+     * const isWithinHours = OpeningHoursHelper.isValidSchedule("09:00", "17:00", "14:30");
+     * console.log(isWithinHours); // true
+     *
+     * const isOutsideHours = OpeningHoursHelper.isValidSchedule("09:00", "17:00", "20:00");
+     * console.log(isOutsideHours); // false
+     * ```
+     * @default Returns `false` if an error occurs or invalid time format is provided.
+     */
+    static isValidSchedule(openHour: string, closeHour: string, currentHour: string): boolean;
+    /**
+     * Parses a time string (HH:mm) and creates a Date object for today with that time.
+     *
+     * @param time The time string in HH:mm format (e.g., "14:30").
+     * @param baseDate Optional base date to use. If not provided, uses the current date.
+     * @returns A Date object representing the date with the specified time.
+     * @example
+     * ```typescript
+     * const timeDate = OpeningHoursHelper.parseTimeToDate("14:30");
+     * console.log(timeDate); // Date object for today at 2:30 PM
+     * ```
+     * @default Returns current date if an error occurs or invalid time is provided.
+     */
+    static parseTimeToDate(time: string, baseDate?: Date): Date;
+    /**
+     * Converts an array of day abbreviations to a readable day range string.
+     *
+     * @param days An array of day abbreviations (e.g., ["Mo", "Tu", "We"]).
+     * @returns A string representing the day range (e.g., "Monday - Wednesday" for consecutive days, or just "Monday" for a single day).
+     * @example
+     * ```typescript
+     * const range = OpeningHoursHelper.getDaysRange(["Mo", "Tu", "We"]);
+     * console.log(range); // "Monday - Wednesday"
+     *
+     * const singleDay = OpeningHoursHelper.getDaysRange(["Mo"]);
+     * console.log(singleDay); // "Monday"
+     * ```
+     * @default Returns empty string "" if an error occurs or empty array is provided.
+     */
+    static getDaysRange(days: string[]): string;
+    /**
+     * Finds the next closest time from an array of time strings relative to the current date.
+     *
+     * @param times An array of time strings in HH:mm format (e.g., ["09:00", "14:30", "18:00"]).
+     * @param currentDate The current date and time to compare against.
+     * @returns The closest upcoming time string, or empty string if no times are provided.
+     * @example
+     * ```typescript
+     * const times = ["09:00", "12:00", "18:00"];
+     * const currentTime = new Date(); // Assume it's 10:30 AM
+     * const nextTime = OpeningHoursHelper.getNextClosestTime(times, currentTime);
+     * console.log(nextTime); // "12:00"
+     * ```
+     * @default Returns empty string "" if an error occurs or no times are provided.
+     */
+    static getNextClosestTime(times: string[], currentDate: Date): string;
+    /**
+     * Checks if a place is currently open based on its opening hours.
+     *
+     * @param openingHours An object containing the opening hours for each day of the week.
+     * @param currentDate Optional date to check against. If not provided, uses the current date.
+     * @returns `true` if the place is currently open, `false` otherwise.
+     * @example
+     * ```typescript
+     * const hours = { mo: [{ open: "09:00", close: "17:00" }] };
+     * const isOpen = OpeningHoursHelper.isPlaceOpen(hours);
+     * console.log(isOpen); // true if current time is between 09:00 and 17:00 on Monday
+     * ```
+     * @default Returns `false` if an error occurs or invalid opening hours are provided.
+     */
+    static isPlaceOpen(openingHours: OpeningHours, currentDate?: Date): boolean;
+    /**
+     * Gets the next schedule time (opening or closing) for a place in 12-hour format.
+     *
+     * @param openingHours An object containing the opening hours for each day of the week.
+     * @param currentDate Optional date to check against. If not provided, uses the current date.
+     * @returns The next schedule time in 12-hour format (e.g., "9:00 a.m." or "6:00 p.m.").
+     * @example
+     * ```typescript
+     * const hours = { mo: [{ open: "09:00", close: "17:00" }] };
+     * const nextSchedule = OpeningHoursHelper.getNextSchedule(hours);
+     * console.log(nextSchedule); // "9:00 a.m." if closed, "5:00 p.m." if open
+     * ```
+     * @default Returns "" if an error occurs or invalid opening hours are provided.
+     */
+    static getNextSchedule(openingHours: OpeningHours, currentDate?: Date): string;
+    /**
+     * Checks if a specific day has a schedule defined in the opening hours.
+     *
+     * @param openingHours An object containing the opening hours for each day of the week.
+     * @param currentDate Optional date to check against. If not provided, uses the current date.
+     * @returns `true` if the day has a schedule defined, `false` otherwise.
+     * @example
+     * ```typescript
+     * const hours = { mo: [{ open: "09:00", close: "17:00" }] };
+     * const hasSchedule = OpeningHoursHelper.checkDayHasSchedule(hours);
+     * console.log(hasSchedule); // true if today is Monday
+     * ```
+     * @default Returns `false` if an error occurs or invalid opening hours are provided.
+     */
+    static checkDayHasSchedule(openingHours: OpeningHours, currentDate?: Date): boolean;
+    /**
+     * Converts a time string (HH:mm) to total minutes since midnight.
+     *
+     * @param time The time string in HH:mm format (e.g., "14:30").
+     * @returns The total number of minutes since midnight (e.g., 870 for "14:30").
+     * @example
+     * ```typescript
+     * const minutes = OpeningHoursHelper.toMinutes("14:30");
+     * console.log(minutes); // 870
+     *
+     * const morningMinutes = OpeningHoursHelper.toMinutes("09:00");
+     * console.log(morningMinutes); // 540
+     * ```
+     * @default Returns 0 if an error occurs or invalid time format is provided.
+     */
+    static toMinutes(time: string): number;
+}
+/**
+ * Checks if an OpeningTime represents a 24-hour schedule (open all day).
+ *
+ * @param openingTime The OpeningTime to check.
+ * @returns `true` if the schedule represents 24 hours, `false` otherwise.
+ */
+export declare function is24Hours(openingTime: OpeningTime): boolean;
+//# sourceMappingURL=opening-hours-helper.d.ts.map

package/dist/es/utils/opening-hours-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"opening-hours-helper.d.ts","sourceRoot":"","sources":["../../../src/utils/opening-hours-helper.ts"],"names":[],"mappings":"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"}