scheduling-sdk

Scheduling SDK 📆

Brought to you by Recal - Your unified calendar API 🚀

A fast TypeScript Scheduling SDK for finding available time slots with exceptional developer experience!

Features

• 🎯 DX First: Intuitive APIs that feel intuitive to use
• 🔒 Full TypeScript Support: Complete type safety with excellent IntelliSense
• 📖 Extensive Documentation: In-depth guides, examples, and API references (With help by Claude)
• ⚡ Blazing Fast Performance: Optimized algorithms for handling large datasets
• 🔧 Flexible Configuration: Customizable slot duration, padding, splitting, and offset
• 📅 Weekly Availability Patterns: Define recurring weekly schedules with automatic break management
• 🏗️ Modular Architecture: Clean separation of concerns for maintainability and testing
• 🧪 98%+ Test Coverage: Comprehensive testing with edge case handling (Supported by the CODE's Automated Testing LU)

Note The SDK is fully written in TypeScript and uses Bun as the build and test tool. It requires TypeScript 5.0 or later as a peer dependency. While we use Bun for development, the compiled SDK is compatible with any JavaScript runtime, including Node.js, Deno, and modern browsers with ESM support.

Quick Start 💨

# Install the SDK
npm install scheduling-sdk
# or
bun add scheduling-sdk

Zero configuration required - start scheduling in seconds! 🚀

Core Concepts

• Busy Times: Periods when you're NOT available (meetings, appointments, breaks)
• Available Slots: Free time periods where new events can be scheduled
• Time Range: The window (start/end dates) to search for available slots
• Slot Options: Configuration for how slots are generated (duration, padding, etc.)

Basic Usage

Standard Scheduling

import { createScheduler } from 'scheduling-sdk'

// Initialize scheduler with busy times (existing meetings, appointments, etc.)
// Busy times are periods when you're NOT available
const scheduler = createScheduler([
    {
        start: new Date('2024-01-15T09:00:00Z'), // Meeting starts at 9:00 AM
        end: new Date('2024-01-15T10:00:00Z'), // Meeting ends at 10:00 AM
    },
])

// Find available time slots in a given time range
// This will return all free slots between 8:00 AM and 5:00 PM, excluding the busy time
const availableSlots = scheduler.findAvailableSlots(
    new Date('2024-01-15T08:00:00Z'), // Search from 8:00 AM
    new Date('2024-01-15T17:00:00Z'), // Search until 5:00 PM
    {
        slotDuration: 30, // Each available slot will be 30 minutes long
        padding: 15, // Add 15-minute buffer before and after busy times
        slotSplit: 15, // Generate overlapping slots every 15 minutes
        offset: 0, // No offset from hour boundaries
    }
)

// Result: availableSlots will contain time slots like:
// [
//   { start: "2024-01-15T08:00:00Z", end: "2024-01-15T08:30:00Z" },
//   { start: "2024-01-15T08:15:00Z", end: "2024-01-15T08:45:00Z" },
//   { start: "2024-01-15T10:15:00Z", end: "2024-01-15T10:45:00Z" }, // Note: starts at 10:15 due to 15-min padding
//   { start: "2024-01-15T10:30:00Z", end: "2024-01-15T11:00:00Z" },
//   ...
// ]

Managing Busy Times

import { createScheduler } from 'scheduling-sdk'

const scheduler = createScheduler()

// Add a single busy time (e.g., a new meeting)
scheduler.addBusyTime({
    start: new Date('2024-01-15T14:00:00Z'), // 2:00 PM
    end: new Date('2024-01-15T15:00:00Z'), // 3:00 PM
})

// Add multiple busy times at once (e.g., imported from calendar)
scheduler.addBusyTimes([
    {
        start: new Date('2024-01-15T10:00:00Z'), // Morning standup
        end: new Date('2024-01-15T11:00:00Z'),
    },
    {
        start: new Date('2024-01-15T16:00:00Z'), // Client call
        end: new Date('2024-01-15T17:00:00Z'),
    },
])

// Clear all busy times (e.g., starting fresh)
scheduler.clearBusyTimes()

// Get current busy times (returns a sorted array)
const currentBusyTimes = scheduler.getBusyTimes()
// Returns: [
//   { start: "2024-01-15T10:00:00Z", end: "2024-01-15T11:00:00Z" },
//   { start: "2024-01-15T14:00:00Z", end: "2024-01-15T15:00:00Z" },
//   ...
// ]

Weekly Availability Scheduling

Business hours made easy ;)

import { AvailabilityScheduler } from 'scheduling-sdk'

// Define when you're generally available (business hours)
// This creates recurring weekly patterns
const availability = {
    schedules: [
        // Monday-Friday: 9 AM to 12 PM (morning hours)
        { days: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'], start: '09:00', end: '12:00' },
        // Monday-Friday: 1 PM to 5 PM (afternoon hours, after lunch)
        { days: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'], start: '13:00', end: '17:00' },
        // Saturday: 10 AM to 2 PM
        { days: ['saturday'], start: '10:00', end: '14:00' },
    ],
}

const scheduler = new AvailabilityScheduler(availability)

// Add busy times within your available hours (meetings, appointments, etc.)
scheduler.addBusyTimes([
    {
        start: new Date('2024-01-15T14:00:00Z'), // Monday 2 PM meeting
        end: new Date('2024-01-15T15:00:00Z'),
    },
    {
        start: new Date('2024-01-16T10:00:00Z'), // Tuesday 10 AM appointment
        end: new Date('2024-01-16T11:00:00Z'),
    },
])

// Find available slots only within your defined business hours
// This respects both your availability schedule AND busy times
const slots = scheduler.findAvailableSlots(
    new Date('2024-01-15T08:00:00Z'), // Monday 8 AM
    new Date('2024-01-15T18:00:00Z'), // Monday 6 PM
    {
        slotDuration: 60, // 1-hour slots
    }
)
// Result: Only returns slots during business hours (9-12, 1-5) excluding busy times
// [
//   { start: "2024-01-15T09:00:00Z", end: "2024-01-15T10:00:00Z" },
//   { start: "2024-01-15T13:00:00Z", end: "2024-01-15T14:00:00Z" },
//   { start: "2024-01-15T15:00:00Z", end: "2024-01-15T16:00:00Z" },
//   { start: "2024-01-15T16:00:00Z", end: "2024-01-15T17:00:00Z" },
//   ...
// ]

Documentation 📚

• 📖 Getting Started - Installation and basic usage
• 📋 API Reference - Complete API documentation
• 🧠 Core Concepts - Understanding scheduling concepts
• ⏰ Availability API - Weekly availability patterns and scheduling
• 💡 Examples - Practical usage examples
• ⚡ Performance Guide - Optimization and benchmarks
• 🤝 Contributing - Development and contribution guidelines

Development 💻

# Install dependencies
bun install

# Run in development mode
bun run dev

# Build for production
bun run build

# Run tests
bun test

# Type checking
bun run typecheck

Architecture 🏗️

The SDK is built with a modular architecture:

src/
├── types/              # TypeScript type definitions
├── helpers/            # Utility functions organized by domain
│   ├── time/           # Date/time calculations and alignments
│   ├── busy-time/      # Busy time operations (padding, merging, overlap)
│   ├── slot/           # Slot generation and filtering
│   └── availability/   # Weekly availability conversion
├── validators/         # Input validation functions
├── core/              # Main Scheduler class
├── availability/      # AvailabilityScheduler class
└── utils/             # Shared constants and utilities

Performance ⚡

Optimized for speed with target performance:

• < 1ms for 100 busy times
• < 10ms for 1000 busy times
• < 100ms for 10000 busy times

See Performance Guide for detailed benchmarks.

License

MIT

Contributing 🤝

Please read our Contributing Guide for development setup and contribution guidelines.

Credits 👨‍💻

Engineering by @tkoehlerlg