🗓️ Calendar Slots
Find availability for a user based on their calendar. Currently only for Google Calendar.
💡 Usage
Install the package from npm:
npm install calendar-slots
Import and use:
; ;;tomorrow.setDatetoday.getDate + 1; ; console.logslots;/* [ { 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 |
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 |
Authentication
You can either specify auth
, calendar
, and user
:
;;;oauth2Client.setCredentials;; ;
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 */;
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 */;
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 */;
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