@smcv/opening-hours 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Yuri Sementsov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# Opening Hours
+
+A TypeScript library for managing and querying business opening hours, heavily inspired by [Spatie's Opening Hours PHP library](https://github.com/spatie/opening-hours).
+
+## Installation
+
+```bash
+npm install @smcv/opening-hours
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+const week = openingHours.forWeek();
+Object.entries(week).forEach(([day, dayHours]) => {
+    console.log(`${day}: ${dayHours.toString()}`);
+});
+```
+
+### Array and String Representation
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+// Sunday first (US convention)
+const sundayFirst = openingHours.toString({ firstDayOfWeek: 'sunday' });
+// Output:
+// Sun Closed
+// Mon...Fri 9AM-5PM
+// Sat 9AM-1PM 2PM-4PM
+```
+
+### Exceptions
+
+```typescript
+// Get all exceptions
+const exceptions = openingHours.getExceptions();
+Object.entries(exceptions).forEach(([date, hours]) => {
+    console.log(`${date}: ${hours.toString()}`);
+});
+```
+
+### Current Open Range
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+const openingHours = OpeningHours.create({
+    'monday...friday': ['09:00-17:00'],
+    saturday: ['09:00-13:00'],
+    sunday: [],
+});
+```
+
+### Overnight Ranges
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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