🗓️ Calendar Slots

Find availability for a user based on their calendar. Works with Google Calendar or any iCalendar URL.

💡 Usage

Install the package from npm:

npm install calendar-slots

Import and use:

import { findSlots } from "calendar-slots";

const today = new Date();
const tomorrow = new Date();
tomorrow.setDate(today.getDate() + 1);

const slots = await findSlots({
  slotDuration: 30, // Find 30 minute slots
  slots: 3, // Recommend 3 slots
  from: today, // Starting now
  to: tomorrow, // Until tomorrow
});

console.log(slots);
/* [
  { from: "Tue May 05 2020 12:00:00 GMT-0800 (PST)", to: "Tue May 05 2020 12:30:00 GMT-0800 (PST)" },
  { from: "Wed May 06 2020 09:30:00 GMT-0800 (PST)", to: "Wed May 06 2020 10:00:00 GMT-0800 (PST)" },
  { from: "Wed May 06 2020 14:30:00 GMT-0800 (PST)", to: "Wed May 06 2020 15:00:00 GMT-0800 (PST)" }
] */

Each Slot has two Date objects, start and end. The from and to properties accept native Date objects, moment objects, or other values that moment understands like date strings and UNIX timestamp numbers.

⚒️ Configuration

Key	Type	Description
`slotDuration`	number	Duration in minutes
`slots`	number	Number of slots to find
`from` (required)	Date or similar	Start time
`to` (required)	Date or similar	End time
`days`	number[]	Days of the week to use
`daily.timezone`	string	Timezone for time restrictions
`daily.from`	[number, number?, number?]	Start [hours, minutes, seconds]
`daily.to`	[number, number?, number?]	End [hours, minutes, seconds]
`strategies`	string	Recommendation strategies
`padding`	number	Time (min) between events
`slotFilter`	(slot: Slot) => boolean	Custom filter for available slots
`url`.	string	iCalendar URL
`calendarId`	string	Specific Google Calender ID
`auth`	Google API OAuth2 client	API client to use
`user.accessToken`	string	User’s access token
`user.refreshToken`	string	User’s refresh token
`log`	boolean	Whether to console.log steps
`logger`	(…args: any[]) => void	Custom function for logging

iCalendar

Any iCalendar-compliant URL is supported; all major calendar providers (Google Calendar, Apple Calendar, Microsoft Outlook, Yahoo! Calendar, etc.) support iCalendar URLs.

You can specify the url:

const slots = await findSlots({
  from: new Date(),
  to: nextWeek,
  url: "webcal://your-example-url.ics"
});

Authentication with Google Calendar

You can either specify auth, calendar, and user:

import { google } from "googleapis";
import { OAuth2Client } from "google-auth-library";
const oauth2Client = new google.auth.OAuth2(
  "Client ID",
  "Client Secret",
  "Redirect URL"
);
oauth2Client.setCredentials({
  access_token: "Access token",
  refresh_token: "Refresh token",
});
const calendar = google.calendar("v3");

const slots = await findSlots({
  from: new Date(),
  to: nextWeek,
  auth: oauth2Client,
  calendar: calendar,
});

Alternately, you can set the following environment variables and we’ll setup the authentication:

GOOGLE_CALENDAR_CLIENT_ID
GOOGLE_CALENDAR_CLIENT_SECRET
GOOGLE_CALENDAR_REDIRECT_URL
GOOGLE_CALENDAR_ACCESS
GOOGLE_CALENDAR_REFRESH

🗜️ Examples

Slots on specific days

You might want to skip weekends when finding slots. Add the days property with an array of numbers (0 for Sunday, 6 for Saturday):

/**
 * Find 3 slots, 30 minutes, from today until next week
 * but only between Monday and Friday
 */
const slots = await findSlots({
  slotDuration: 30,
  slots: 3,
  from: new Date(),
  to: nextWeek,
  days: [1, 2, 3, 4, 5],
});

Slots between specific times every day

You might want to find slots only between specific times of the day. Add the daily property:

/**
 * Find 3 slots, 30 minutes, from today until next week
 * but only between Monday and Friday
 * and only from 9:00 am to 5:30 pm, Pacific Time
 */
const slots = await findSlots({
  slotDuration: 30,
  slots: 3,
  from: new Date(),
  to: nextWeek,
  days: [1, 2, 3, 4, 5],
  daily: {
    timezone: "America/Los_Angeles",
    from: [9],
    to: [17, 30],
  },
});

Prefer morning slots

You may want to increase the probability of getting certain slots, using strategies.

/**
 * Find 3 slots, 30 minutes, from today until next week
 * but only between Monday and Friday
 * and prefer morning slots rather than later in the day
 */
const slots = await findSlots({
  slotDuration: 30,
  slots: 3,
  from: new Date(),
  to: nextWeek,
  days: [1, 2, 3, 4, 5],
  strategies: ["heavy-mornings"],
});

Available strategies are:

linear (default)
heavy-firsts (prefer beginning of all slots)
heavy-lasts (prefer ending of all slots)
heavy-centers (prefer middle of all slots)
heavy-mornings (prefer mornings)
heavy-afternoons (prefer afternoons)
heavy-evenings (prefer evenings)
heavy-mondays (prefer Mondays)
heavy-tuesdays (prefer Tuesdays)
heavy-wednesdays (prefer Wednesdays)
heavy-fridays (prefer Fridays)
heavy-saturday (prefer Saturday)
heavy-sundays (prefer Sundays)

There are no strategies for preference of light rather than heavy; however, this works: If you want light mornings, you can pass the strategies ["heavy-afternoons", "heavy-evenings"]. Similarly, if you want light Fridays, you can pass heavy- other days.

👩‍💻 Development

Build TypeScript:

npm run build

Run unit tests and view coverage:

npm run test-without-reporting