@smcv/opening-hours 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,420 @@
+type OpenState = "closed" | "open";
+declare const Days: {
+	readonly sunday: 0;
+	readonly monday: 1;
+	readonly tuesday: 2;
+	readonly wednesday: 3;
+	readonly thursday: 4;
+	readonly friday: 5;
+	readonly saturday: 6;
+};
+type Day = keyof typeof Days;
+type DateValue = Date | number | string;
+type TimeRangeString = string;
+type TimeRangeWithData<T extends Record<string, unknown> = Record<string, unknown>> = {
+	hours?: TimeRangeString;
+	time?: TimeRangeString;
+} & T;
+type TimeRangeInput<T extends Record<string, unknown> = Record<string, unknown>> = TimeRangeString | TimeRangeWithData<T>;
+type DayRange = `${Day}...${Day}`;
+type DateRange = `${string}...${string}`;
+type OpeningHoursConfig<T extends Record<string, unknown> = Record<string, unknown>> = Record<Day | DayRange, TimeRangeInput<T>[] | TimeRangeWithData<T>>;
+/**
+* Schema.org OpeningHoursSpecification interface
+* @see https://schema.org/OpeningHoursSpecification
+*/
+interface OpeningHoursSpecification {
+	"@type": "OpeningHoursSpecification";
+	dayOfWeek?: string | string[];
+	opens?: string;
+	closes?: string;
+	validFrom?: string;
+	validThrough?: string;
+}
+declare class Time {
+	private readonly hour;
+	private readonly minute;
+	constructor(hour: number, minute?: number);
+	/**
+	* Create a Time instance from a string.
+	* Supports formats like '09:00', '09:00:00', or '09:00:00-05:00'.
+	*/
+	static fromString(timeString: string): Time;
+	/**
+	* Create a Time instance from a Date object
+	*/
+	static fromDate(date: Date): Time;
+	/**
+	* Get the hour component
+	*/
+	getHour(): number;
+	/**
+	* Get the minute component
+	*/
+	getMinute(): number;
+	/**
+	* Format the time as a string
+	*/
+	format(format?: string): string;
+	/**
+	* Convert to string in H:i format
+	*/
+	toString(): string;
+	/**
+	* Check if this time is before another time
+	*/
+	isBefore(time: Time): boolean;
+	/**
+	* Check if this time is after another time
+	*/
+	isAfter(time: Time): boolean;
+	/**
+	* Check if this time is equal to another time
+	*/
+	isEqual(time: Time): boolean;
+	/**
+	* Add minutes to the time
+	*/
+	addMinutes(minutes: number): Time;
+	/**
+	* Get the time as minutes since midnight
+	*/
+	toMinutesSinceMidnight(): number;
+	/**
+	* Calculate difference in minutes between two times
+	*/
+	diffInMinutes(time: Time): number;
+	/**
+	* Create a date with this time
+	*/
+	toDate(baseDate?: Date): Date;
+}
+type TimeRangeData<T extends Record<string, unknown> = Record<string, unknown>> = T;
+declare class TimeRange<T extends Record<string, unknown> = Record<string, unknown>> {
+	private readonly start;
+	private readonly end;
+	private readonly data?;
+	constructor(start: Time, end: Time, data?: T);
+	/**
+	* Create a TimeRange from a string (e.g., '09:00-17:00')
+	*/
+	static fromString<T extends Record<string, unknown> = Record<string, unknown>>(rangeString: string, data?: T): TimeRange<T>;
+	/**
+	* Get the start time
+	*/
+	getStart(): Time;
+	/**
+	* Get the end time
+	*/
+	getEnd(): Time;
+	/**
+	* Get the associated data
+	*/
+	getData(): T | undefined;
+	/**
+	* Check if a specific time is contained in this range
+	*/
+	containsTime(time: Time, overflow?: boolean): boolean;
+	/**
+	* Check if the range spans overnight (end time is before start time)
+	*/
+	spansOvernight(): boolean;
+	/**
+	* Check if this range overlaps with another range
+	*/
+	overlaps(timeRange: TimeRange<T>, overflow?: boolean): boolean;
+	/**
+	* Get the duration of this range in minutes
+	*/
+	durationInMinutes(overflow?: boolean): number;
+	/**
+	* Convert to string representation
+	*/
+	toString(): string;
+}
+declare class OpeningHoursForDay<T extends Record<string, unknown> = Record<string, unknown>> {
+	private readonly timeRanges;
+	private readonly overflow;
+	private readonly displayOptions?;
+	private readonly data?;
+	constructor(timeRanges?: TimeRange<T>[], overflow?: boolean, displayOptions?: DisplayOptions, data?: T);
+	/**
+	* Check if open at the given time
+	*/
+	isOpenAt(time: Time): boolean;
+	/**
+	* Check if open at the given DateTime
+	*/
+	isOpenAtDateTime(dateTime: Date): boolean;
+	/**
+	* Check if the business is open during the day (has any time ranges)
+	*/
+	isOpenDuringDay(): boolean;
+	/**
+	* Get all time ranges
+	*/
+	getTimeRanges(): TimeRange<T>[];
+	/**
+	* Get the data associated with this day (e.g. a note on a closed exception)
+	*/
+	getData(): T | undefined;
+	/**
+	* Find the current open range at the given time
+	*/
+	getCurrentOpenRange(time: Time): TimeRange<T> | null;
+	/**
+	* Find the current open range at the given DateTime
+	*/
+	getCurrentOpenRangeAtDateTime(dateTime: Date): TimeRange<T> | null;
+	/**
+	* Check if this day has the same opening hours as another day
+	*/
+	equals(openingHoursForDay: OpeningHoursForDay<T>): boolean;
+	/**
+	* Format a time range for display
+	*/
+	protected formatTimeRange(timeRange: TimeRange<T>, options?: DisplayOptions): string;
+	/**
+	* Convert to string representation
+	*/
+	toString(options?: DisplayOptions): string;
+}
+type DayOfWeek = keyof typeof Days;
+interface OpeningHoursOptions<T extends Record<string, unknown> = Record<string, unknown>> extends Partial<OpeningHoursConfig<T>> {
+	overflow?: boolean;
+	exceptions?: Record<string, TimeRangeInput<T>[] | ((date: Date) => TimeRangeInput<T>[])>;
+	filters?: Array<(date: Date) => TimeRangeInput<T>[]>;
+	/**
+	* IANA timezone name representing the organization's local time
+	*/
+	timezone?: string;
+}
+interface DisplayOptions {
+	locale?: string;
+	weekday?: "narrow" | "short" | "long";
+	firstDayOfWeek?: "monday" | "sunday";
+	dayRangeSeparator?: string;
+	timeRangeSeparator?: string;
+	timeFormat?: string;
+	timeRangesSeparator?: string;
+	showTimezone?: boolean;
+	timeZoneName?: "short" | "long" | "shortOffset" | "longOffset" | "shortGeneric" | "longGeneric";
+	closedText?: string;
+}
+declare class OpeningHours<T extends Record<string, unknown> = Record<string, unknown>> {
+	private readonly config;
+	private readonly schedule;
+	private readonly exceptions;
+	private readonly filters;
+	private readonly timezone?;
+	private readonly overflow;
+	private readonly displayOptions?;
+	constructor(config: OpeningHoursOptions<T> & DisplayOptions);
+	private initializeSchedule;
+	private normalizeTimeRanges;
+	/**
+	* Check if a TimeRangeInput has no hours/time (metadata-only item)
+	*/
+	private isMetadataOnly;
+	/**
+	* Filter out metadata-only items, keeping only actual time ranges
+	*/
+	private filterActualRanges;
+	/**
+	* Extract data from a metadata-only item in a schedule (no hours/time)
+	*/
+	private extractDataFromSchedule;
+	/**
+	* Get the data for a specific date (from exceptions only)
+	*/
+	private getDataForDate;
+	/**
+	* Convert a TimeRangeInput to a TimeRange object
+	*/
+	private convertToTimeRange;
+	/**
+	* Get day name from a Date object
+	*/
+	private getDayName;
+	/**
+	* Format a date as YYYY-MM-DD
+	*/
+	private formatDate;
+	/**
+	* Get time ranges for a specific date
+	*/
+	private getTimeRangesForDate;
+	/**
+	* Create a static instance of OpeningHours
+	*/
+	static create<T extends Record<string, unknown> = Record<string, unknown>>(config: OpeningHoursOptions<T> & DisplayOptions): OpeningHours<T>;
+	/**
+	* Check if the business is open on a specific day
+	*/
+	isOpenOn(day: Day): boolean;
+	/**
+	* Check if the business is open at a specific date and time
+	*/
+	isOpenAt(dateTime: Date): boolean;
+	/**
+	* Check if the business is closed at a specific date and time
+	*/
+	isClosedAt(dateTime: Date): boolean;
+	/**
+	* Get opening hours for a specific day of the week
+	*/
+	forDay(day: Day): OpeningHoursForDay<T>;
+	/**
+	* Get opening hours for all days of the week
+	*/
+	forWeek(): Record<Day, OpeningHoursForDay<T>>;
+	/**
+	* Get opening hours for a specific date
+	*/
+	forDate(date: Date): OpeningHoursForDay<T>;
+	/**
+	* Get all exceptions
+	*/
+	getExceptions(): Record<string, OpeningHoursForDay<T>>;
+	/**
+	* Calculate the difference in open time between two dates (in hours)
+	*/
+	diffInOpenHours(startDate: Date, endDate: Date): number;
+	/**
+	* Calculate the difference in open time between two dates (in minutes)
+	*/
+	diffInOpenMinutes(startDate: Date, endDate: Date): number;
+	/**
+	* Calculate the open minutes within a timespan (all within the same day)
+	*/
+	private calculateOpenMinutesForTimespan;
+	/**
+	* Check if there are exceptions between two dates
+	*/
+	private hasExceptionBetween;
+	/**
+	* Calculate the difference in open time between two dates (in seconds)
+	*/
+	diffInOpenSeconds(startDate: Date, endDate: Date): number;
+	/**
+	* Calculate the difference in closed time between two dates (in hours)
+	*/
+	diffInClosedHours(startDate: Date, endDate: Date): number;
+	/**
+	* Calculate the difference in closed time between two dates (in minutes)
+	*/
+	diffInClosedMinutes(startDate: Date, endDate: Date): number;
+	/**
+	* Calculate the difference in closed time between two dates (in seconds)
+	*/
+	diffInClosedSeconds(startDate: Date, endDate: Date): number;
+	/**
+	* Get the current open range at a specific date and time
+	*/
+	currentOpenRange(dateTime: Date): TimeRange<T> | null;
+	/**
+	* Get the start of the current open range at a specific date and time
+	*/
+	currentOpenRangeStart(dateTime: Date): Date | null;
+	/**
+	* Get the end of the current open range at a specific date and time
+	*/
+	currentOpenRangeEnd(dateTime: Date): Date | null;
+	/**
+	* Find the next open range after a specific date and time
+	*/
+	private findNextOpenRange;
+	/**
+	* Find the previous open range before a specific date and time
+	*/
+	private findPreviousOpenRange;
+	/**
+	* Get the next open range after a specific date and time
+	*/
+	nextOpenRange(dateTime: Date): TimeRange<T> | null;
+	/**
+	* Get the start of the next open range after a specific date and time
+	*/
+	nextOpenRangeStart(dateTime: Date): Date | null;
+	/**
+	* Get the end of the next open range after a specific date and time
+	*/
+	nextOpenRangeEnd(dateTime: Date): Date | null;
+	/**
+	* Convenience alias for nextOpenRangeStart
+	*/
+	nextOpen(dateTime: Date): Date | null;
+	/**
+	* Get the next closing time after a specific date and time
+	*/
+	nextClose(dateTime: Date): Date | null;
+	/**
+	* Get the previous open range before a specific date and time
+	*/
+	previousOpenRange(dateTime: Date): TimeRange<T> | null;
+	/**
+	* Get the start of the previous open range before a specific date and time
+	*/
+	previousOpenRangeStart(dateTime: Date): Date | null;
+	/**
+	* Get the end of the previous open range before a specific date and time
+	*/
+	previousOpenRangeEnd(dateTime: Date): Date | null;
+	static from<T extends Record<string, unknown> = Record<string, unknown>>(config: OpeningHoursOptions<T> & DisplayOptions): OpeningHours<T>;
+	/**
+	* Create OpeningHours from structured data (schema.org format)
+	*/
+	static createFromStructuredData<T extends Record<string, unknown> = Record<string, unknown>>(inputData: unknown, displayOptions?: DisplayOptions): OpeningHours<T>;
+	/**
+	* Format a Time object as ISO-8601 time with timezone offset
+	*/
+	private formatISOTime;
+	/**
+	* Convert to structured data (schema.org format)
+	*/
+	asStructuredData(timezone?: string | null): OpeningHoursSpecification[];
+	/**
+	* Convert a date to the configured timezone.
+	* Returns a date object whose clock time reflects the target timezone
+	* but represents the same absolute instant.
+	*/
+	private toTimezone;
+	/**
+	* Convert a date interpreted in the configured timezone back to UTC.
+	*/
+	private fromTimezone;
+	/**
+	* Get a string representation of a day's schedule for comparison
+	*/
+	private getScheduleStringForDay;
+	/**
+	* Get time ranges for a specific day of the week
+	*/
+	private getTimeRangesForDayOfWeek;
+	/**
+	* Format a day range, e.g. "Mon...Fri" or "Sat"
+	*/
+	protected formatDayRange(days: DayOfWeek[], options?: DisplayOptions): string;
+	/**
+	* Format a time range for display (e.g. 9:00-17:00)
+	*/
+	protected formatTimeRange(timeRange: TimeRange<T>, options?: DisplayOptions): string;
+	/**
+	* Render opening hours as array where each array item corresponds to a line of output
+	* and contains day range followed by time ranges
+	*/
+	toArray(options?: DisplayOptions): string[][];
+	/**
+	* Format a day name using Intl.DateTimeFormat
+	*/
+	private formatDayName;
+	/**
+	* Get timezone abbreviation for display
+	*/
+	private getTimezoneName;
+	/**
+	* Render opening hours as multi-line string
+	*/
+	toString(options?: DisplayOptions): string;
+}
+export { TimeRangeWithData, TimeRangeString, TimeRangeInput, TimeRangeData, TimeRange, Time, OpeningHoursSpecification, OpeningHoursOptions, OpeningHoursForDay, OpeningHoursConfig, OpeningHours, OpenState, Days, DayRange, Day, DateValue, DateRange };