README.md

Slot Calculator

Calculate time slots for your users to choose from.

• Intersect availabilities of multiple users/resources.
• Full timezone support.
• Blazing fast (usage of ES6 Sets, Maps and efficient data structures).
• Works great with Luxon and V-Calendar.

Table of contents

• Documentation
• Demo
• Usage
  • Setup
  • Returned values
• Examples
  • Basic usage
  • With availabilities and unavailabilities
  • With multiple users
  • With timezones

Documentation

View the JS/TS reference. TypeScript language support in your IDE is sufficient to make use of this package's types and annotations.

Demo

Play with a live demo on CodeSandbox

Usage

Setup

npm install slot-calculator

import { getSlots } from "slot-calculator"

const { allSlots } = getSlots({
  from: "2022-01-01",
  to: "2022-01-02",
  duration: 60,
})

Returned values

• allSlots: An array of all generated slots. Only use this as a starting point for manipulating the output.
• availableSlots: An array of available slots. Only use this as a starting point for manipulating the output.
• allDates: An array of dates, including unavailable ones, between the from and to configuration variables. Use this to allow users to specify their own datetime, but within your chosen bounds.
• availableDates: An array of available dates. Use this to mark on a calendar which dates can be selected.
• allSlotsByDay: Once a user has selected a date, use this object to easily find all the slots for that day.
• availableSlotsByDay: Once a user has selected a date, use this object to easily find the available slots for that day.
• timeTaken: Worried that the number crunching is slowing down your app? Monitor this variable to see the time taken by slot calculator.

Examples

For these examples to work, use this setup code:

import { DateTime, Settings } from "luxon";

Settings.defaultZone = "UTC";
const dateTimeRef = DateTime.utc(2022, 1, 1);

Basic usage

getSlots({
  from: dateTimeRef.toISO(),
  to: dateTimeRef.plus({ hour: 2 }).toISO(),
  duration: 60,
});

With availabilities and unavailabilities

getSlots({
  from: dateTimeRef.toISO(),
  to: dateTimeRef.plus({ hour: 3 }).toISO(),
  availability: [
    {
      from: dateTimeRef.plus({ hour: 1 }).toISO(),
      to: dateTimeRef.plus({ hour: 2 }).toISO(),
    },
  ],
  unavailability: [
    {
      from: dateTimeRef.plus({ hour: 2 }).toISO(),
      to: dateTimeRef.plus({ hour: 3 }).toISO(),
    },
  ],
  duration: 60,
});

With multiple users

getSlots({
  from: dateTimeRef.toISO(),
  to: dateTimeRef.plus({ hour: 2 }).toISO(),
  availability: [
    {
      day: "Saturday",
      from: "00:00",
      to: "01:00",
      metadata: {
        user: "Alice",
      },
    },
    {
      from: dateTimeRef.plus({ hour: 1 }).toISO(),
      to: dateTimeRef.plus({ hour: 2 }).toISO(),
      metadata: {
        user: "Bob",
      },
    },
  ],
  duration: 60,
});

With timezones

getSlots({
  from: dateTimeRef.toISO(),
  to: dateTimeRef.plus({ hour: 2 }).toISO(),
  outputTimezone: "Europe/Paris",
  availability: [
    {
      day: "Saturday",
      from: "01:00",
      to: "02:00",
      timezone: "Europe/Paris",
    },
  ],
  duration: 60,
});