Opening Hours

A TypeScript library for managing and querying business opening hours, heavily inspired by Spatie's Opening Hours PHP library.

Installation

npm install @smcv/opening-hours

Usage

Basic Usage

import { OpeningHours } from '@smcv/opening-hours';

const openingHours = OpeningHours.create({
    monday: ['09:00-12:00', '13:00-18:00'],
    tuesday: ['09:00-12:00', '13:00-18:00'],
    wednesday: ['09:00-12:00'],
    thursday: ['09:00-12:00', '13:00-18:00'],
    friday: ['09:00-12:00', '13:00-20:00'],
    saturday: ['09:00-12:00', '13:00-16:00'],
    sunday: [],
    exceptions: {
        '2025-12-25': [], // Closed on Christmas
        '2025-11-11': ['09:00-12:00'], // Different hours on this day
    },
});

// Check if open on a specific day
console.log(openingHours.isOpenOn('monday')); // true
console.log(openingHours.isOpenOn('sunday')); // false

// Check if open at a specific date and time
const dateTime = new Date('2025-11-05 15:00:00');
console.log(openingHours.isOpenAt(dateTime)); // false (Wednesday afternoon)

// Check if open on Christmas
const christmas = new Date('2025-12-25 10:00:00');
console.log(openingHours.isOpenAt(christmas)); // false (exception)

Get Opening Hours for a Day

const monday = openingHours.forDay('monday');
console.log(monday.toString()); // '09:00-12:00, 13:00-18:00'

// Get all time ranges as objects
const timeRanges = monday.getTimeRanges();
timeRanges.forEach(range => {
    console.log(`Open from ${range.getStart()} to ${range.getEnd()}`);
});

Get Opening Hours for a Specific Date

forDate() respects exceptions, unlike forDay() which only looks at the weekly schedule:

const christmas = openingHours.forDate(new Date('2025-12-25'));
console.log(christmas.toString()); // 'Closed'

const normalMonday = openingHours.forDate(new Date('2025-11-03'));
console.log(normalMonday.toString()); // '09:00-12:00, 13:00-18:00'

Get Opening Hours for the Week

const week = openingHours.forWeek();
Object.entries(week).forEach(([day, dayHours]) => {
    console.log(`${day}: ${dayHours.toString()}`);
});

Array and String Representation

// Get opening hours as an array
const hoursArray = openingHours.toArray();
console.log(hoursArray);
// Output: [['Mon...Fri', '9AM-5PM'], ['Sat', '9AM-1PM', '2PM-4PM'], ['Sun', 'Closed']]

// Get opening hours as a formatted string
const hoursString = openingHours.toString();
console.log(hoursString);
// Output:
// Mon...Fri 9AM-5PM
// Sat 9AM-1PM 2PM-4PM
// Sun Closed

Days with identical schedules are grouped (Mon...Fri). Each row begins with the day(s) followed by time slots, or Closed for days with no hours.

Display Options

Both toArray() and toString() accept a DisplayOptions object:

| Option | Type | Default | Description | |--------|------|---------|-------------| | locale | string | 'en-US' | BCP 47 locale for day names | | weekday | 'narrow' | 'short' | 'long' | 'short' | Day name format | | firstDayOfWeek | 'monday' | 'sunday' | 'monday' | First day of the week | | dayRangeSeparator | string | '...' | Separator between grouped days | | timeRangeSeparator | string | '-' | Separator within a time range | | timeRangesSeparator | string | ', ' | Separator between multiple time ranges | | timeFormat | string | auto | Format string (H:i, gA, etc.) | | closedText | string | 'Closed' | Text shown for closed days |

Internationalization

// French day names, full format
const frenchHours = openingHours.toString({ locale: 'fr', weekday: 'long' });
// lundi...vendredi 09:00-17:00
// samedi 09:00-13:00 14:00-18:00
// dimanche Fermé

// Spanish, abbreviated (default)
const spanishHours = openingHours.toString({ locale: 'es' });
// lun...vie 09:00-17:00
// sáb 09:00-13:00 14:00-18:00
// dom Cerrado

// Narrow (single-letter)
const narrow = openingHours.toString({ weekday: 'narrow' });

First Day of Week

// Sunday first (US convention)
const sundayFirst = openingHours.toString({ firstDayOfWeek: 'sunday' });
// Output:
// Sun Closed
// Mon...Fri 9AM-5PM
// Sat 9AM-1PM 2PM-4PM

Exceptions

// Get all exceptions
const exceptions = openingHours.getExceptions();
Object.entries(exceptions).forEach(([date, hours]) => {
    console.log(`${date}: ${hours.toString()}`);
});

Current Open Range

const now = new Date();
const range = openingHours.currentOpenRange(now);

if (range) {
    console.log(`Open since ${openingHours.currentOpenRangeStart(now)?.toLocaleTimeString()}`);
    console.log(`Closes at ${openingHours.currentOpenRangeEnd(now)?.toLocaleTimeString()}`);
} else {
    console.log('Currently closed');
}

Next and Previous Ranges

const now = new Date();

// Next opening window
const nextStart = openingHours.nextOpenRangeStart(now);
const nextEnd = openingHours.nextOpenRangeEnd(now);
console.log(`Next open: ${nextStart?.toLocaleString()} – ${nextEnd?.toLocaleString()}`);

// Next moment the business opens / closes
const nextOpen = openingHours.nextOpen(now);
const nextClose = openingHours.nextClose(now);

// Previous opening window
const prevStart = openingHours.previousOpenRangeStart(now);
const prevEnd = openingHours.previousOpenRangeEnd(now);

Time Differences

const start = new Date('2025-01-01 08:00:00');
const end = new Date('2025-01-05 18:00:00');

console.log(openingHours.diffInOpenHours(start, end));
console.log(openingHours.diffInOpenMinutes(start, end));
console.log(openingHours.diffInOpenSeconds(start, end));

console.log(openingHours.diffInClosedHours(start, end));
console.log(openingHours.diffInClosedMinutes(start, end));
console.log(openingHours.diffInClosedSeconds(start, end));

Day Ranges

const openingHours = OpeningHours.create({
    'monday...friday': ['09:00-17:00'],
    saturday: ['09:00-13:00'],
    sunday: [],
});

Overnight Ranges

const nightClub = OpeningHours.create({
    friday: ['22:00-04:00'],
    saturday: ['22:00-04:00'],
    overflow: true, // required for overnight ranges
});

const saturdayNight = new Date('2025-01-04 02:00:00'); // 2 AM Saturday
console.log(nightClub.isOpenAt(saturdayNight)); // true

Schema.org Integration

Create from schema.org structured data:

const hours = OpeningHours.createFromStructuredData([
    {
        '@type': 'OpeningHoursSpecification',
        opens: '09:00:00Z',
        closes: '17:00:00Z',
        dayOfWeek: [
            'https://schema.org/Monday',
            'https://schema.org/Friday',
        ],
    },
]);

Export to schema.org format:

const structured = openingHours.asStructuredData();
console.log(JSON.stringify(structured, null, 2));

// With timezone offset in the output
const structuredWithTz = openingHours.asStructuredData('America/New_York');

Advanced Usage

Custom Data in Time Ranges

Associate arbitrary data with each time range via generics:

type ShiftData = { shift: string };

const openingHours = OpeningHours.create<ShiftData>({
    monday: [
        { hours: '09:00-12:00', shift: 'morning' },
        { hours: '13:00-18:00', shift: 'afternoon' },
    ],
});

const ranges = openingHours.forDay('monday').getTimeRanges();
console.log(ranges[0]?.getData()?.shift); // 'morning'

Dynamic Exceptions

Use a function to compute exceptions at runtime:

const openingHours = OpeningHours.create({
    monday: ['09:00-17:00'],
    exceptions: {
        // First Monday of each month has different hours
        firstMondayFunc: (date: Date) => {
            if (date.getDay() === 1 && date.getDate() <= 7) {
                return ['10:00-15:00'];
            }
            return [];
        },
    },
});

Timezone Support

Specify the organization's local timezone so that isOpenAt and related methods evaluate dates in that timezone regardless of the caller's local time:

const openingHours = OpeningHours.create({
    monday: ['09:00-17:00'],
    timezone: 'America/New_York',
});

const dateTime = new Date('2025-01-15T12:30:00Z'); // UTC input
console.log(openingHours.isOpenAt(dateTime)); // evaluated in America/New_York

Valid values are IANA timezone identifiers: America/New_York, Europe/London, Asia/Tokyo, Australia/Sydney, etc.

Requirements

• Node.js 20.19+
• TypeScript 4.5+ (optional peer dependency)

License

MIT