🕐 Visiting hours

A simple library that allows you to provide visiting hours and extract information from it based on a provided Date.

This library was built to run continuously and for that reason optimized for lookup speed.

Features

Some of the features and characteristics of this library.

• 0 Dependencies 🦄
• Live mode, returns same reference when in cache (useful with mobx)
• 3.9 kB (minified + gzipped)
• Timezone support (specify zone in config or luxon instance or DateInputInterface in method calls.)
• Multiple ranges on days (allows for lunch breaks! 🥪)
• Check if provided Date falls within visiting hours
• Allows special dates to be provided (holidays and such)
• Works past-midnight
• Works with leap years (even for special dates)
• Check if open at all on provided Date's day, and if so at what time
• Extensive test coverage

This library is optimized to perform well when called frequently for many venues.

Usage

I prefer code over lengthy explanations so, take a gander:

import { VisitingHours, Utils, Timezone } from 'visiting-hours';
import { DateTime } from 'luxon';

const hours = new VisitingHours({
  // Optional. Requires IANA tz identifiers.
  // zone: 'America/New_York',

  live: false, // Set to true to optimize for frequent lookups.
  regular: {
    sunday: { isOpen: false },
    monday: {
      hours: [
        { open: '08:00', close: '12:00' },

        // Had a really nice lunch break
        { open: '13:30', close: '20:00' },

        // Past midnight
        { open: '23:30', close: '03:30' },
      ],
      isOpen: true
    },
    friday: {
      hours: [
        { open: '08:00', close: '18:00' }
      ],
      isOpen: true
    },
  },
  special: [
    // This venue is down with Christmas.
    { date: '25/12', isOpen: false }
  ]
});

// Monday, July 13th of 2020 at 11:15, result: true
hours.isOpen(new Date(2020, 6, 13, 11, 15)).open;

// Monday, July 13th of 2020 at 12:35, result: false
hours.isOpen(new Date(2020, 6, 13, 12, 35)).open;

// Tuesday, July 14th of 2020 at 02:15, result: true
hours.isOpen(new Date(2020, 6, 14, 2, 15)).open;

// Friday, July 17th of 2020 at 14:15, result: true
hours.isOpen(new Date(2020, 6, 17, 14, 15)).open;

// Friday, December 25th of 2020 at 14:15, result: false
hours.isOpen(new Date(2020, 11, 25, 14, 15)).open;

// You can use luxon objects, too.
hours.isOpen(DateTime.local()).open;

// Or use vanilla JS for timezone support
//  (requires IANA tz identifiers. Modern browsers will work.)
hours.isOpen(Utils.fromDate(new Date(2020, 6, 16, 15, 40), 'Europe/Amsterdam')).open;

// Small utility function to make range of hours
Utils.minuteInterval('08:01', '09:14', 15);  // ['08:15', '08:30', '08:45', '09:00']

// Get a Date representing a value in the future
Timezone.fromTimeString('02:00', 'Europe/Amsterdam', new Date());

Interfaces

Sometimes it's nice to know what's possible by taking a quick look at the README. This is one of those times!

VisitingHoursConfigInterface

| key | type | required | description | |---|---|---|---| | live | boolean | false | Will expect frequent lookups and optimize accordingly when set to true | | zone | string | false | IANA timezone identifier, will be applied to all Date arguments used on this instance.Examples: Europe/Amsterdam or America/New_York | | regular | RegularHoursInterface | false | Regular visiting hours for week days. | | special | HoursDayInterface[] | false | Override visiting hours, for example holidays.Example: { date: '25/12', isOpen: false } |

RegularHoursInterface

An interface where the key is the name of the week, and the value is an HoursDayInterface. Example:

Example:

{
  sunday: { isOpen: false },
  monday: {
    hours: [
      { close: '01:00', open: '11:15' }
    ],
    isOpen: true
  }
}

DateInputInterface

An object that contains all the info needed and allows you to use your own timezone changes or other magic.

| key | type | required | description | |---|---|---|---| | zoneName | number | false | The name of the timezone this instance is in. Required for live and zone. | | ts | number | true | The timestamp of the date object. | | offset | number | true | The timezone offset of the date object. | | month | number | true | The month of the date object. | | day | number | true | The day of the date object. | | weekday | number | true | The weekday of the date object. | | hour | number | true | The hour(s) of the date object. | | minute | number | true | The minute(s) of the date object. | | isInLeapYear | boolean | true | If this object's date falls in a leap year. |

HoursDayInterface

Holds opening hours for a week day or specific date (when it's an override).

| key | type | required | description | |---|---|---|---| | date | string | false | Used for special dates. Format: dd/mm | | isOpen | boolean | true | Used to specify if open on specified day/date. Note: will ignore provided hours when false. | | hours | HoursInterface[] | false | The hours for this day/date. |

HourMatchInterface

This is the shape you'll get back when calling .isOpen().

| key | type | description | |---|---|---| | open | boolean | If the provided date fall within visiting hours | | match | HourMatchSetInterface or null | Objects of the opening and closing hours matched or null. | | soonest | VisitingHour or null | If no match, the soonest match for the provided day or null when closed all day. |

VisitingHour

An instance with a few getters that represent an opening hour.

| key | type | description | |---|---|---| | hours | number | The hours of the matched time. | | minutes | number | The minutes of the matched time. | | military | string | The match in military notation. | | date | Date | Date instance of the matched time. | | formatted | string | Returns .toLocaleTimeString() on date |

HourMatchSetInterface

A set of open/close hours.

| key | type | description | |---|---|---| | open | VisitingHour | Open value of the matched visiting hours. | | close | VisitingHour | Close value of the matched visiting hours. |

Compatibility

Works in all modern browsers. Most features should work in IE (caches an timezones require Polyfills.),

React Native: Android

For android you have two options:

• jsc-android-buildscripts (recommended)
• Polyfills (include all required polyfills, there's a chart)

When using a polyfill you can prevent from adding to your bundle size on iOS and Web by using a polyfills.android.js file to only include them on android. Make sure to import the polyfills file in your App.js file.

License

MIT