Calendar Utilities

0.12.5 · active · verified Sun Apr 19

calendar-utils provides a set of utility functions designed to generate calendar views, abstracting away the complex date calculations required for displaying events across different time spans. It is currently at version 0.12.5, indicating a pre-1.0 release stage where API stability might be less guaranteed and breaking changes between minor versions are possible. The library is date library-agnostic, supporting popular options like `date-fns`, `luxon`, and `moment` through peer dependencies, allowing developers to choose their preferred date manipulation library. Its primary differentiator is its focus purely on view generation logic, making it a flexible backend for any calendar UI component, rather than a full-fledged UI solution itself. It ships with full TypeScript types, enhancing developer experience and type safety.

Common errors

```
Error: Cannot find module 'date-fns' (or 'luxon' or 'moment')
```
cause A required peer dependency for date manipulation (e.g., date-fns) is not installed in your project.

fix Install the missing date library: `npm install date-fns` or `npm install luxon` or `npm install moment`.
```
TypeError: getCalendarMonthView is not a function
```
cause This usually means you are attempting to use a CommonJS `require` statement on a library primarily designed for ESM, or using incorrect named/default import syntax.

fix Ensure you are using ESM `import { getCalendarMonthView } from 'calendar-utils';` and your project supports ESM.
```
Argument of type 'string' is not assignable to parameter of type 'Date'.
```
cause The `calendar-utils` functions expect native JavaScript `Date` objects (or objects compatible with the chosen date library's `Date` type) for date parameters, not strings.

fix Ensure all date inputs (e.g., `date`, `viewStart`, `viewEnd` arguments) are `new Date()` objects, or parsed by your chosen date library (e.g., `parseISO('2023-01-01')` from `date-fns`).

Warnings

breaking As a library in `0.x.x` versioning, `calendar-utils` may introduce breaking changes between minor versions (e.g., `0.11.0` to `0.12.0`) without adhering to strict semantic versioning. Always review the changelog when upgrading.
Fix: Always pin exact versions (e.g., `"calendar-utils": "0.12.5"`) or use caret ranges cautiously, and consult release notes for migration guides during upgrades.
gotcha The library relies on peer dependencies for date manipulation (e.g., `date-fns`, `luxon`, `moment`). You must install one of these explicitly in your project, along with any necessary adapters if the library requires it (though for `calendar-utils` the functions directly accept standard Date objects or compatible date library types).
Fix: Install your preferred date library: `npm install date-fns` or `npm install luxon` or `npm install moment`.
gotcha Incorrect configuration of `weekStartsOn` or `weekendDays` can lead to unexpected calendar layouts, especially when mixing `calendar-utils` with UI components that have their own default settings.
Fix: Ensure `weekStartsOn` (0 for Sunday, 1 for Monday) and `weekendDays` (array of day indexes, 0-6) are consistent across your `calendar-utils` configuration and any consuming UI library.

Install

npm install calendar-utils npm
yarn add calendar-utils yarn
pnpm add calendar-utils pnpm

Imports

getCalendarMonthView
wrong:
```
const { getCalendarMonthView } = require('calendar-utils');
```
correct:
```
import { getCalendarMonthView } from 'calendar-utils';
```
calendar-utils is primarily designed for ESM usage. While CommonJS might work via transpilation, direct require is not the idiomatic way.
getCalendarWeekView
wrong:
```
import getCalendarWeekView from 'calendar-utils';
```
correct:
```
import { getCalendarWeekView } from 'calendar-utils';
```
All primary view generation functions are named exports; there is no default export.
getCalendarDayView
wrong:
```
import * as calendarUtils from 'calendar-utils';
```
correct:
```
import { getCalendarDayView, getWeekViewHeader } from 'calendar-utils';
```
It's best practice to import only the specific functions you need to optimize bundle size.

Quickstart

This quickstart demonstrates how to generate a calendar month view using `getCalendarMonthView` with `date-fns` for date manipulation.

import { getCalendarMonthView } from 'calendar-utils';
import { startOfMonth, endOfMonth, eachDayOfInterval, format, addMonths } from 'date-fns';

interface CalendarDay {
  date: Date;
  isToday: boolean;
  isWeekend: boolean;
  events: string[];
}

const currentDate = new Date();
const monthStart = startOfMonth(currentDate);
const monthEnd = endOfMonth(currentDate);

const calendarMonthView = getCalendarMonthView({
  date: currentDate,
  events: [], // Your events array, e.g., [{ start: new Date(), end: new Date(), title: 'Meeting' }]
  weekStartsOn: 0, // Sunday
  excluded: [], // e.g., [6] for Saturday
  viewStart: monthStart,
  viewEnd: monthEnd,
  hourSegments: 2, // Not directly used by month view, but part of config
  dayStartHour: 0,
  dayEndHour: 23,
  weekendDays: [0, 6]
});

console.log(`Month View for ${format(currentDate, 'MMMM yyyy')}:`);
calendarMonthView.days.forEach(day => {
  console.log(`  ${format(day.date, 'yyyy-MM-dd')} (isCurrentMonth: ${day.inMonth}): ${day.events.length} events`);
});

// Example of getting a day outside the current month (for navigation)
const nextMonth = addMonths(currentDate, 1);
const nextMonthView = getCalendarMonthView({
  date: nextMonth,
  events: [],
  weekStartsOn: 0,
  excluded: [],
  viewStart: startOfMonth(nextMonth),
  viewEnd: endOfMonth(nextMonth),
  hourSegments: 2,
  dayStartHour: 0,
  dayEndHour: 23,
  weekendDays: [0, 6]
});

view raw JSON →