Business Hours # Business hours need a time zone, a calendar, and clear boundaries 22 October 20263 minute readBy [Brownsmith Dynamics](https://brownsmithdynamics.com/) Model weekly hours, holidays, exceptions, and overnight periods without relying on the server’s local clock. “Open until five” sounds precise until a customer, server, and business are in different time zones. The same schedule also has to answer more than whether the doors are open now: when do they next close, does an appointment cross a lunch break, and what happens when a holiday changes the usual hours? The Business Hours Engine from [Brownsmith Dynamics](https://brownsmithdynamics.com/) represents weekly periods, overnight shifts, date-specific overrides, and IANA time zones. It calculates against an explicitly supplied instant rather than reading the system clock, which makes the time context part of the application’s decision. ## Define the local schedule first Consider a consultation practice in Kolkata that takes appointments Monday through Friday, 9:00–12:00 and 13:00–17:00. Configure the time zone as Asia/Kolkata and define the two periods for each working weekday. Weekdays use Monday-through-Sunday numbering. A missing day or an empty list means closed; an empty weekly schedule is a valid always-closed calendar. Hours use zero-padded 24-hour time with minute precision. A close time earlier than the opening time describes an overnight shift, such as a Friday evening service that ends at 02:00 Saturday. The schedule can also include holidays and exceptions, where an exception replaces the entire local civil day. That lets an application express an early closing or a one-off closure explicitly. ## Ask questions in actual instants When a support page needs to show status, the library can tell whether the business is open and find the next opening or closing transition. For an appointment flow, validate that a proposed interval fits within effective operating hours. Because intervals use a half-open boundary, an appointment ending exactly at closing is allowed, while one starting at that moment falls outside the period. This is schedule validation, not appointment management. It does not reserve a slot or check staff availability, capacity, existing bookings, payment, lead time, or service-specific rules. Those belong to the booking system that calls it. Likewise, a result that no transition was found within the configured search horizon does not prove the schedule stays closed forever. ## Plan for exceptions and daylight changes Holiday and exception dates are interpreted in the business’s time zone, not the host computer’s local zone. You supply holiday dates or a synchronous local provider; the package does not include a holiday database or fetch one. That keeps the calendar source and observed-day policy under your application’s control. Daylight-saving changes create local times that repeat or do not occur. The engine offers a disambiguation policy, defaulting to compatible behavior, and can be configured to reject ambiguous or nonexistent boundaries when a human decision is preferable. Durations are elapsed milliseconds, so a nominal three-hour span on a clock may contain fewer or more elapsed hours on a transition day. For reliable results, pass an ISO date-time with an explicit offset or a Date/epoch instant, and keep runtime time-zone data current. ## Keep the schedule maintainable Store the schedule and its time-zone choice as business configuration, then make changes reviewable. Use conflict detection to identify overlapping effective periods, and write down the expected handling for overrides and overnight carry. This is especially helpful when holiday closures affect a shift that began the prior evening. Explore the [npm package page](https://www.npmjs.com/package/@brownsmithdynamics/business-hours) and the [source repository](https://github.com/apnatvar/plugins/tree/main/business-hours). ## More from the shelf [Compare sitemap releases to catch URL changes before launch](https://plugins.brownsmithdynamics.com/blogs/sitemap-diff/) [Validate invoice arithmetic before it reaches the next system](https://plugins.brownsmithdynamics.com/blogs/invoice-rules/) [All articles](https://plugins.brownsmithdynamics.com/blogs/) --- [HTML page](https://plugins.brownsmithdynamics.com/blogs/business-hours/) · [Developer documentation](https://plugins.brownsmithdynamics.com/developers/) · [Agent instructions](https://plugins.brownsmithdynamics.com/llms.txt)