Skip to content

getting-started.md

Latest commit

 

History

History
226 lines (174 loc) · 6.62 KB

getting-started.md

File metadata and controls

226 lines (174 loc) · 6.62 KB
Raw

Getting Started

Next: Core Concepts

Installation

npm install scheduling-sdk
# or
yarn add scheduling-sdk
# or
bun add scheduling-sdk

Key Concepts

Before diving in, let's clarify the main concepts:

  • Busy Time: A period when you're NOT available (existing meetings, appointments, breaks)
  • Available Slot: A time period when you CAN be scheduled (no conflicts with busy times)
  • Time Range: The window (start and end dates) where you want to find available slots
  • Padding: Extra buffer time added around busy times to prevent back-to-back scheduling

Quick Start

The Scheduling SDK provides a simple interface for finding available time slots while considering busy periods and various scheduling constraints.

Basic Example

import { Scheduler } from 'scheduling-sdk'

// Create a scheduler with busy times (periods when NOT available)
const scheduler = new Scheduler([
    {
        start: new Date('2024-01-15T09:00:00Z'),  // 9:00 AM meeting
        end: new Date('2024-01-15T10:00:00Z'),    // ends at 10:00 AM
    },
    {
        start: new Date('2024-01-15T14:00:00Z'),  // 2:00 PM appointment
        end: new Date('2024-01-15T15:30:00Z'),    // ends at 3:30 PM
    },
])

// Find available 30-minute slots
const availableSlots = scheduler.findAvailableSlots(
    new Date('2024-01-15T08:00:00Z'), // Start time
    new Date('2024-01-15T17:00:00Z'), // End time
    {
        slotDuration: 30, // 30-minute slots
        padding: 0, // No padding around busy times
        slotSplit: 30, // Non-overlapping slots
        offset: 0, // No offset from hour boundaries
    }
)

console.log(availableSlots)
// Output: Array of available time slots that avoid the busy periods:
// - 8:00-8:30, 8:30-9:00 (before first meeting)
// - 10:00-10:30, 10:30-11:00... up to 14:00 (between meetings)
// - 15:30-16:00, 16:00-16:30, 16:30-17:00 (after last appointment)

Step-by-Step Breakdown

  1. Import the SDK: Import the Scheduler class
  2. Create Scheduler: Initialize with existing busy times (optional)
  3. Define Options: Configure slot duration, padding, splitting, and offset
  4. Find Slots: Call findAvailableSlots with time range and options
  5. Use Results: Process the returned array of available time slots

Core Concepts

Time Slots

A time slot represents a potential booking period with a start and end time:

interface TimeSlot {
    start: Date
    end: Date
}

Busy Times

Busy times represent periods when you are NOT available for scheduling - think of them as blocked time on your calendar:

interface BusyTime {
    start: Date
    end: Date
}

Scheduling Options

Configure how slots are generated:

interface SchedulingOptions {
    // Required
    slotDuration: number // Duration of each slot in minutes

    // Optional
    slotSplit?: number // Interval between slot starts (default: same as duration)
    padding?: number   // Buffer time around busy periods in minutes
    offset?: number    // Offset from hour boundaries in minutes
    maxOverlaps?: number // Allow up to K overlapping busy intervals (K-overlaps)

    // Daily window filtering (timezone-aware)
    timezone?: string
    earliestTime?: string | number // 'HH:mm' or minutes since midnight
    latestTime?: string | number   // 'HH:mm' or minutes since midnight; supports '24:00' or 1440
}

Quick links:

Common Use Cases

1. Simple Appointment Booking

import { Scheduler } from 'scheduling-sdk'

const scheduler = new Scheduler()

// Add existing appointments
scheduler.addBusyTimes([
    { start: new Date('2024-01-15T10:00:00Z'), end: new Date('2024-01-15T11:00:00Z') },
    { start: new Date('2024-01-15T14:30:00Z'), end: new Date('2024-01-15T15:30:00Z') },
])

// Find 60-minute slots
const slots = scheduler.findAvailableSlots(new Date('2024-01-15T09:00:00Z'), new Date('2024-01-15T17:00:00Z'), {
    slotDuration: 60,
})

2. Meeting Room Scheduling with Padding

// Add 15-minute padding for room setup/cleanup
const slots = scheduler.findAvailableSlots(new Date('2024-01-15T09:00:00Z'), new Date('2024-01-15T17:00:00Z'), {
    slotDuration: 60,
    padding: 15, // 15 minutes buffer around busy times
})

3. Overlapping Time Slots

// Generate 60-minute slots every 30 minutes (overlapping)
const slots = scheduler.findAvailableSlots(new Date('2024-01-15T09:00:00Z'), new Date('2024-01-15T17:00:00Z'), {
    slotDuration: 60,
    slotSplit: 30, // New slot every 30 minutes
})

3b. Allowing Overlaps (K-overlaps)

// Allow up to 1 overlapping busy time (K = 1)
const kOverlapSlots = scheduler.findAvailableSlots(new Date('2024-01-15T09:00:00Z'), new Date('2024-01-15T17:00:00Z'), {
    slotDuration: 30,
    slotSplit: 15,
    maxOverlaps: 1,
})

4. Aligned Scheduling

// Align slots to quarter-hours (15-minute boundaries)
const slots = scheduler.findAvailableSlots(new Date('2024-01-15T09:00:00Z'), new Date('2024-01-15T17:00:00Z'), {
    slotDuration: 30,
    slotSplit: 15, // Align to 15-minute intervals
    offset: 0, // Start on the hour
})

Working with Multiple Schedulers

// Separate schedulers for different resources
const roomScheduler = new Scheduler()
const equipmentScheduler = new Scheduler()

// Add resource-specific busy times
roomScheduler.addBusyTimes([...roomBookings])
equipmentScheduler.addBusyTimes([...equipmentBookings])

// Find slots available for both
const roomSlots = roomScheduler.findAvailableSlots(start, end, options)
const equipmentSlots = equipmentScheduler.findAvailableSlots(start, end, options)

// Find intersection of available slots
const bothAvailable = findIntersection(roomSlots, equipmentSlots)

Error Handling

try {
    const slots = scheduler.findAvailableSlots(
        new Date('2024-01-15T17:00:00Z'), // End time
        new Date('2024-01-15T09:00:00Z'), // Start time (invalid!)
        { slotDuration: 30 }
    )
} catch (error) {
    console.error('Invalid time range:', error.message)
}

Next Steps