@phoenix344/opening-hours

OpeningHours

A plain typescript/ES6+ opening hours library with no external dependencies.

Features

• [x] Support after midnight hours (i.e. 22:00 - 03:00)
• [x] Intl.DateTimeFormat support (for timezone and internationalization)
• [x] Starting the week on any day (default: Sunday)
• [x] Merge overlapping times for maintainance
• [x] Cut a timespan out of the opening hours (i.e. business hours between 8 AM till 6 PM, pause between 12 and 1 PM)
• [x] Provide functions to get the current open state
• [x] Provide functions to get an indicator for open/close soon
• [ ] Special opening hours for a given timespan in days
• [ ] Alternative text for special opening hours
• [ ] Schema.org import/export

Examples

Initialize your class:

import { OpeningHours, WeekDays } from '@phoenix344/opening-hours';

const oh = new OpeningHours({
    // Predefine a date makes only sense to test the current day
    //currentDate: new Date(2020, 8, 15),
    text: {
        weekDays: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
        closed: 'geschlossen',
        timespanSeparator: ' bis '
    }
});

Insert opening hours entries:

oh.add(WeekDays.Monday, '08:00', '12:30');
oh.add(WeekDays.Monday, '13:00', '16:00');

oh.add(WeekDays.Tuesday, '08:00', '12:30');
oh.add(WeekDays.Tuesday, '13:00', '16:00');

oh.add(WeekDays.Wednesday, '08:00', '14:00');

oh.add(WeekDays.Thursday, '08:00', '12:30');
oh.add(WeekDays.Thursday, '13:00', '16:00');

oh.add(WeekDays.Friday, '08:00', '12:30');
oh.add(WeekDays.Friday, '13:00', '16:00');

oh.add(WeekDays.Saturday, '10:00', '14:00');

Alternatively you can add a saved JSON output from toJSON():

oh.load([
    { "day": 1, "from": "0800", "until": "1230" },
    { "day": 1, "from": "1300", "until": "1600" },
    { "day": 2, "from": "0800", "until": "1230" },
    { "day": 2, "from": "1300", "until": "1600" },
    { "day": 3, "from": "0800", "until": "1400" },
    { "day": 4, "from": "0800", "until": "1230" },
    { "day": 4, "from": "1300", "until": "1600" },
    { "day": 5, "from": "0800", "until": "1230" },
    { "day": 5, "from": "1300", "until": "1600" },
    { "day": 6, "from": "1000", "until": "1400" }
]);

To display it as plain text use the toString() method:

oh.toString();

The current day will be highlighted in brackets [...]

Mo 08:00 bis 12:30, 13:00 bis 16:00
[Di 08:00 bis 12:30, 13:00 bis 16:00]
Mi 08:00 bis 14:00
Do 08:00 bis 12:30, 13:00 bis 16:00
Fr 08:00 bis 12:30, 13:00 bis 16:00
Sa 10:00 bis 14:00

To use the data to customize your UI you can also use the toLocaleJSON method:

oh.toLocaleJSON();

The output looks like this (the current day is active: true):

[
    {
        "active": false,
        "day": "Mo",
        "times": [
            { "from": "08:30", "until": "12:30" },
            { "from": "13:00", "until": "16:00" }
        ]
    },
    {
        "active": true,
        "day": "Di",
        "times": [
            { "from": "08:30", "until": "12:30" },
            { "from": "13:00", "until": "16:00" }
        ]
    },
    {
        "active": false,
        "day": "Mi",
        "times": [
            { "from": "08:30", "until": "14:00" },
        ]
    },
    {
        "active": false,
        "day": "Do",
        "times": [
            { "from": "08:30", "until": "12:30" },
            { "from": "13:00", "until": "16:00" }
        ]
    },
    {
        "active": false,
        "day": "Fr",
        "times": [
            { "from": "08:30", "until": "12:30" },
            { "from": "13:00", "until": "16:00" }
        ]
    },
    {
        "active": false,
        "day": "Sa",
        "times": [
            { "from": "10:00", "until": "14:00" }
        ]
    },
]

To export and save the opening hours, use the toJSON method:

oh.toJSON();

[
    { "day": 1, "from": "0800", "until": "1230" },
    { "day": 1, "from": "1300", "until": "1600" },
    { "day": 2, "from": "0800", "until": "1230" },
    { "day": 2, "from": "1300", "until": "1600" },
    { "day": 3, "from": "0800", "until": "1400" },
    { "day": 4, "from": "0800", "until": "1230" },
    { "day": 4, "from": "1300", "until": "1600" },
    { "day": 5, "from": "0800", "until": "1230" },
    { "day": 5, "from": "1300", "until": "1600" },
    { "day": 6, "from": "1000", "until": "1400" }
]

Different language formats:

oh.toString({ locales: 'zh-CN' });

The output looks like this:

[tue 上午08:00 - 下午12:30, 下午01:00 - 下午04:00]
wed 上午08:00 - 下午02:00
thu 上午08:00 - 下午12:30, 下午01:00 - 下午04:00
fri 上午08:00 - 下午12:30, 下午01:00 - 下午04:00
sat 上午10:00 - 下午02:00
sun closed
mon 上午08:00 - 下午12:30, 下午01:00 - 下午04:00

Documentation

OpeningHoursOptions

Interface for every available class option.

Property	Default	Description
weekStart	WeekDays.Monday	The start of the week can vary in different countries. The default is sunday, but you can set it to any week day.
currentDate	new Date()	This is the indicator to highlight the opening hours of the current day.
currentDayOnTop	false	Orders the output list, so the current day is always on top.
locales	"de-DE"	The language tag that represents how the time will be formatted. In case of internationalization it should be defined by the client (i.e. from navigator.language)
dateTimeFormatOptions	{ timeZone: "Europe/Berlin", hour: "2-digit", minute: "2-digit" }	The DateTimeFormat configures the time at GMT-2 and only displays hours and minutes in 2-digit format. Should be defined by the business owner to avoid confusion with local and remote timezones.
text	OpeningHoursTranslation	An object of translations for display behavior

OpeningHoursTranslation

Interface for the output text. In case of internationalization you can add your translations here

Property	Default	Description
weekDays	["sun", "mon", "tue", "wed", "thu", "fri", "sat"]	The human readable week days ordered by 0 = Sunday until 6 = Saturday. This will be used in the toString() and toLocaleJSON() output.
timespanSeparator	" - "	Fills the space between the from and until time in the toString() method.
closed	"closed"	Fills the empty value of a day with the closed message in toString() method.

OpeningHours

Method	Parameters	Return	Description
constructor	(optional) options?: OpeningHoursOptions		Initializes the class instance
getState	(optional) now?: Date	OpenState.Open or OpenState.Closed	Returns if the subject business is currently open or closed
isOpenSoon	(optional) now?: Date (optional) expireSeconds?: number	boolean	Informs whether the business will be open soon. expireSeconds = 1800 (30min)
isClosedSoon	(optional) now?: Date (optional) expireSeconds?: number	boolean	Informs whether the business will be closed soon. expireSeconds = 1800 (30min)
add	day: WeekDays `from: string	number	Date<br>until: string
load	`json: Array<{ day: WeekDays, from: string	number	Date, until: string
toString	(optional) options?: OpeningHoursOptions	Example: "mon 08:00 - 12:30, 13:00 - 16:00"	Creates a string output that represents the opening hours
toLocaleJSON	(optional) options?: OpeningHoursOptions	Example: [{day: string, active: boolean, times: [{day: 1, from: "08:00", until: "12:30"}, {from: "13:00", until: "16:00"}]}]	Creates an output format that can easily be used to format it in the UI.
toJSON		Example: [{day: 1, from: "0800", until: "1230"}, {day: 1, from: "1300", until: "1600"}]	Creates an object output for JSON and can be reimported into load(json)