# openinghours.js

> Given an opening hours structure as defined by [schema.org/OpeningHoursSpecification](https://schema.org/OpeningHoursSpecification), and as used by [Google](https://developers.google.com/search/docs/data-types/local-business#business_hours), this can tell

Latest version **0.1.1** (published 2020-02-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install openinghours.js
pnpm add openinghours.js
yarn add openinghours.js
bun add openinghours.js
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2020-02-14 |
| First published | 2019-11-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 285.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | elsdoerfer |

## Links

- npm: https://www.npmjs.com/package/openinghours.js
- npm.io page: https://npm.io/package/openinghours.js

## Dependencies (1)

- [luxon](https://npm.io/package/luxon.md) ^1.21.3

## Recent versions

- 0.1.1 (latest) — 2020-02-14
- 0.1.0 — 2019-12-27
- 0.0.2 — 2019-11-04
- 0.0.1 — 2019-11-04

## README

# openinghours.js

Given an opening hours structure as defined by [schema.org/OpeningHoursSpecification](https://schema.org/OpeningHoursSpecification),
and as used by [Google](https://developers.google.com/search/docs/data-types/local-business#business_hours), this can
tell you if at a particular point in time the entity is open, and when it will close, or the reverse.

This is still a work on progress and might fail to return the right result in edge cases, but seems to handle most 
common cases, and comes with a test suite.


## Install

```bash
$ yarn add openinghours.js
$ npm install --save openinghours.js
```

# Documentation

## The data structure

Define your opening hours using this data structure:

```javascript
const rules = [
  // This applies to every day
  {
    opens: '08:00',
    closes: '18:00'
  },
  {
    // This applies to any monday or tuesday.
    dayOfWeek: ['monday', 'tuesday'],
    // 00:00 - 00:00 means closed the whole day.
    opens: '00:00',
    closes: '00:00',
  },
  {
    // This applies to any sunday in December 2019
    dayOfWeek: ['sunday'],
    validFrom: '2019-12-01',
    validThrough: '2019-12-21',
    // 00:00 - 23:59 means open the whole day.
    opens: '00:00',
    closes: '23:59',
  },
];
```

## The main query function

Query the state at a given point in time:

```javascript
import {getCurrentState} from 'openinghours.js';

getCurrentState(
  rules,
  {
    date: new Date()
  }
);
```

The return value is an object such as: 

```javascript
const result = {
  isOpen: true,
  closesAt: new Date("2019-12-05T14:00:00.000Z")
}
```

```javascript
const result = {
  isOpen: false,
  opensAt: new Date("2019-12-05T14:00:00.000Z")
}
```

## A note on timezones

The library fully supports timezones.

To declare which timezone the open/close time rules refer to, you can pass a `rulesTimezone` option:

```javascript
getCurrentState(
  [
    {
      opens: '08:00',
      closes: '18:00'
    }
  ],
  {
    date: new Date("2019-12-05T07:30:00"),
    rulesTimezone: 'Europe/Berlin'
  }
);
```

If you run the above on a GMT machine (so the time queried will be 07:30 GMT) while Europe/Berlin is `GMT+1`, then
the result will be "is open", because the shop opened at 7am in GMT time (and at 8am in Europe/Berlin time).

*It is strongly recommended that you pass this option*, as the results you get will otherwise depend on the host 
machine timezone you run the query on: If not given, we assume ``06:00`` means 6am in the local timezone. If your
code runs in a browser on a visitor's machine in `America/New_York` at 6am New York time, we'll assume the entity
is just opening, which will not be true if it is situated in a different timezone.

For the date you want to query, you can pass a `luxon.DateTime` object instead of a native `Date`:

```javascript
import {getCurrentState} from 'openinghours.js';
import {DateTime} from 'luxon';

getCurrentState(
  rules,
  {
    date: DateTime.fromObject({ hour: 10, minute: 26, second: 6, year: 2019, month: 5, day: 25, zone: 'America/New_York' }),
    rulesTimezone: 'Europe/Berlin'
  }
);
```


# Other libraries

I could not find another library dealing with opening hours that does the following:

- Supports the data structure behind the [schema.org specification](https://schema.org/OpeningHoursSpecification).
- Can calculate when a business will next open or close.

---
_Source: https://npm.io/package/openinghours.js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._