slot-range-helper v1.0.0

Date-Range Utils

A utility library for managing date ranges, generating time slots, and scheduling. This library provides functions for working with date ranges, slotting systems, and checking the availability of time slots, making it perfect for use in booking systems, scheduling applications, or any system requiring time-based range manipulation.

Installation

You can install the package via npm:

npm install date-range-utils


Features
Create Date Ranges: Create date ranges with custom start and end times.
Generate Time Slots: Generate time slots within a specified range.
Slot Availability Check: Check if a particular time slot is available.
Book Slots: Book a time slot and add it to the list of booked slots.
Timezone Support: Work with specific time zones when creating and manipulating date ranges.

Usage
1. Creating Date Ranges
To create a date range with a specific start and end time:

const { createRange } = require('date-range-utils');

// Create a range from 8 AM to 6 PM on December 1st, 2024, in UTC timezone
const range = createRange("2024-12-01T08:00:00", "2024-12-01T18:00:00", "UTC");

console.log(range);
// Output: { start: Moment object (2024-12-01T08:00:00Z), end: Moment object (2024-12-01T18:00:00Z) }


2. Generating Time Slots
Generate time slots within a date range with a specified duration (e.g., hourly or by minutes):

const { generateSlots } = require('date-range-utils');

// Create a range and generate hourly slots
const range = createRange("2024-12-01T08:00:00", "2024-12-01T18:00:00", "UTC");
const slots = generateSlots(range, "hour", 1);

console.log(slots);
// Output: An array of time slots, each with a start and end time.


3. Checking Slot Availability
Check if a slot is available by comparing it with booked slots:

const { isSlotAvailable } = require('date-range-utils');

const range = createRange("2024-12-01T08:00:00", "2024-12-01T10:00:00", "UTC");
const bookedSlots = [
    createRange("2024-12-01T09:00:00", "2024-12-01T10:00:00", "UTC")
];

const availability = isSlotAvailable(range, bookedSlots);
console.log(availability); // Output: false, since the slot is already booked

4. Booking a Slot
Book a time slot if it's available:
 


const { bookSlot } = require('date-range-utils');

const range = createRange("2024-12-01T08:00:00", "2024-12-01T10:00:00", "UTC");
let bookedSlots = [];

const booked = bookSlot(range, bookedSlots);
console.log(booked); // Output: true, slot successfully booked

const alreadyBooked = bookSlot(range, bookedSlots);
console.log(alreadyBooked); // Output: false, slot is already booked


API Reference
createRange(start: string, end: string, timezone: string) => DateRange
start: The start time in ISO format (e.g., "2024-12-01T08:00:00").
end: The end time in ISO format (e.g., "2024-12-01T18:00:00").
timezone: The timezone in which to create the date range (e.g., "UTC", "Asia/Karachi").
Returns a DateRange object with start and end as moment objects.

generateSlots(range: DateRange, slotDuration: moment.unitOfTime.DurationConstructor, interval: number) => DateRange[]
range: The date range object to generate slots for.
slotDuration: The unit of time for the slot duration (e.g., "hour", "minute").
interval: The interval in the specified slot duration unit (e.g., 1 for 1-hour slots).
Returns an array of date range objects representing the available time slots.

isSlotAvailable(slot: DateRange, bookedSlots: DateRange[]) => boolean
slot: The date range object representing the slot to check.
bookedSlots: An array of DateRange objects representing the currently booked slots.
Returns true if the slot is available, otherwise false.

bookSlot(slot: DateRange, bookedSlots: DateRange[]) => boolean
slot: The date range object representing the slot to book.
bookedSlots: An array of DateRange objects representing the currently booked slots.
Returns true if the slot was successfully booked, otherwise false.

Contributing
We welcome contributions! If you'd like to improve this package, feel free to fork it, make your changes, and submit a pull request. Please make sure to test your changes and follow the existing code style.


License
MIT License. See the LICENSE file for details.