timeslottr

Generate time slots with ease.
Zero dependencies. TypeScript-first. Works everywhere.

Live Demo | API

Key features

• Fast: Written in TypeScript with efficient code that only uses the memory you need.
• Zero dependencies: No external packages, keeping the library small and secure.
• Works everywhere: Runs in Node.js, edge runtimes, and modern browsers.
• Timezone support: Handles different date and time formats in any timezone.
• Flexible scheduling: Add buffers, exclude time ranges, customize intervals, and control slot alignment.
• Comprehensive Test Coverage: 90%+ test coverage.
• Built-in metadata: Each slot includes useful information like index, duration, and custom labels.
• Rich utilities: Merge overlapping slots, find gaps in schedules, check containment, and serialize to/from JSON.

Installation

npm install timeslottr

Quick start

import { generateTimeslots } from 'timeslottr';

const slots = generateTimeslots({
  day: '2024-01-01',
  timezone: 'America/New_York',
  range: { start: '09:00', end: '17:30' },
  slotDurationMinutes: 45,
  slotIntervalMinutes: 30,
  bufferBeforeMinutes: 15,
  excludedWindows: [
    { start: '12:00', end: '13:00' } // lunch break
  ],
  minimumSlotDurationMinutes: 20,
  alignment: 'start',
  labelFormatter: ({ start }) => start.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' })
});

console.log(slots.map((slot) => ({
  start: slot.start.toISOString(),
  end: slot.end.toISOString(),
  label: slot.metadata?.label
})));

Multi-day scheduling

To generate slots across a range of dates (e.g., "9am to 5pm" for every day from Jan 1st to Jan 7th), use generateDailyTimeslots. This helper applies your configuration to each day within the specified period.

import { generateDailyTimeslots } from 'timeslottr';

const slots = generateDailyTimeslots(
  // The outer window (e.g. a full week)
  { start: '2024-01-01', end: '2024-01-08' },
  {
    // The daily schedule (applied to each day in the window)
    range: { start: '09:00', end: '17:00' },
    slotDurationMinutes: 60,
    timezone: 'America/New_York',
    // ... other config options (buffers, exclusions, etc.)
  }
);

Per-weekday schedules

You can define different time ranges for each day of the week by passing a Map<Weekday, TimeslotRangeInput> as the range. Days not included in the map are skipped. Set a weekday to null to explicitly exclude it.

import { generateDailyTimeslots, Weekday } from 'timeslottr';
import type { WeekdayTimeslotRangeInput } from 'timeslottr';

const weekdayRanges: WeekdayTimeslotRangeInput = new Map([
  [Weekday.MON, { start: '09:00', end: '17:00' }],
  [Weekday.TUE, { start: '09:00', end: '17:00' }],
  [Weekday.WED, { start: '09:00', end: '12:00' }], // half day
  [Weekday.THU, { start: '09:00', end: '17:00' }],
  [Weekday.FRI, { start: '10:00', end: '16:00' }], // late start, early finish
  // SAT and SUN omitted — no slots generated on weekends
]);

const slots = generateDailyTimeslots(
  { start: '2024-01-01', end: '2024-01-14' },
  {
    range: weekdayRanges,
    slotDurationMinutes: 60,
    timezone: 'America/New_York',
  }
);

Configuration

Option	Type	Description
range	{ start, end } or Map<Weekday, { start, end } | null>	Required boundaries for the generation window. Each boundary accepts a Date, an ISO-like string, a time-only string ("09:00"), or { date, time }. Time-only inputs need a day default or an inline date. For generateDailyTimeslots, you can pass a Map keyed by Weekday to define per-weekday schedules; omitted days produce no slots.
day	string | Date	Default calendar day when range/excludedWindows use time-only strings.
slotDurationMinutes	number	Length of each primary slot. Must be positive.
slotIntervalMinutes	number	Step between slot starts. Defaults to slotDurationMinutes, enabling overlaps or gaps when customised.
bufferBeforeMinutes / bufferAfterMinutes	number	Trim the usable window by applying leading/trailing buffers.
excludedWindows	TimeslotRangeInput[]	Sub-ranges to omit (breaks, blackout periods). Overlapping windows are merged.
timezone	string	IANA time zone used when interpreting date-only or time-only inputs (America/New_York, UTC, …).
alignment	'start' | 'end' | 'center'	Controls how leftover time is handled. start truncates at the end, end aligns slots backwards from the range end, center distributes leftover time evenly.
minimumSlotDurationMinutes	number	Minimum allowable length for partial edge slots. Defaults to slotDurationMinutes.
includeEdge	boolean	Include truncated edge slots when their duration is above the minimum. Defaults to true.
maxSlots	number	Hard limit on the number of generated slots.
labelFormatter	({ start, end }, index, durationMinutes) => string	Optional metadata helper for injecting labels or display text.

Each generated Timeslot contains immutable Date instances and optional metadata:

{
  start: Date;
  end: Date;
  metadata?: {
    index: number;
    durationMinutes: number;
    label?: string;
  };
}

Utilities

Creating and validating slots

import { createTimeslot } from 'timeslottr';

const slot = createTimeslot(
  new Date('2024-01-01T09:00:00Z'),
  new Date('2024-01-01T10:00:00Z')
);
// Throws TypeError for invalid dates, RangeError if end <= start

Checking for overlaps

import { overlaps } from 'timeslottr';

overlaps(slotA, slotB); // true if the two slots intersect

Checking if a time falls within a slot

import { contains } from 'timeslottr';

contains(slot, new Date('2024-01-01T09:30:00Z')); // true
contains(slot, new Date('2024-01-01T10:00:00Z')); // false (end is exclusive)

Merging overlapping slots

import { mergeSlots } from 'timeslottr';

const merged = mergeSlots([slotA, slotB, slotC]);
// Sorts by start time, merges any overlapping or adjacent slots

Finding gaps (free time)

import { findGaps } from 'timeslottr';

const free = findGaps(bookedSlots, {
  start: new Date('2024-01-01T09:00:00Z'),
  end: new Date('2024-01-01T17:00:00Z')
});
// Returns unbooked time slots within the range

JSON serialization

Date objects don't survive JSON.stringify → JSON.parse round-trips. Use the built-in helpers:

import { timeslotToJSON, timeslotFromJSON } from 'timeslottr';

const json = timeslotToJSON(slot);
// { start: "2024-01-01T09:00:00.000Z", end: "2024-01-01T10:00:00.000Z", metadata: { ... } }

const restored = timeslotFromJSON(json);
// Timeslot with proper Date instances — validates dates and start < end

Multi-day scheduling

generateDailyTimeslots applies your configuration to each day within a date range. The range can be a single TimeslotRangeInput (same schedule every day) or a Map<Weekday, TimeslotRangeInput | null> for per-weekday schedules:

import { generateDailyTimeslots, Weekday } from 'timeslottr';

// Same schedule every day
const slots = generateDailyTimeslots(
  { start: '2024-01-01', end: '2024-01-08' },
  {
    range: { start: '09:00', end: '17:00' },
    slotDurationMinutes: 60,
    timezone: 'America/New_York',
    maxDays: 365, // optional safety limit (default: 10,000)
  }
);

// Different schedule per weekday
const weekdaySlots = generateDailyTimeslots(
  { start: '2024-01-01', end: '2024-01-08' },
  {
    range: new Map([
      [Weekday.MON, { start: '09:00', end: '17:00' }],
      [Weekday.WED, { start: '09:00', end: '12:00' }],
      [Weekday.FRI, { start: '10:00', end: '16:00' }],
    ]),
    slotDurationMinutes: 60,
    timezone: 'America/New_York',
  }
);

The Weekday enum values are: SUN (0), MON (1), TUE (2), WED (3), THU (4), FRI (5), SAT (6).

Development

# Install dependencies
npm install

# Run tests
npm test

# Generate production build
npm run build

The build pipeline uses tsup to emit dual ESM/CJS bundles in dist/ with type definitions. Tests are written with Vitest.