{"id":10603,"library":"calendar-utils","title":"Calendar Utilities","description":"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.","status":"active","version":"0.12.5","language":"javascript","source_language":"en","source_url":"https://github.com/mattlewis92/calendar-utils","tags":["javascript","calendar","utilities","typescript"],"install":[{"cmd":"npm install calendar-utils","lang":"bash","label":"npm"},{"cmd":"yarn add calendar-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add calendar-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for date manipulation if chosen as the adapter. One of the peer dependencies must be installed and configured.","package":"date-fns","optional":false},{"reason":"Required for date manipulation if chosen as the adapter. One of the peer dependencies must be installed and configured.","package":"luxon","optional":false},{"reason":"Required for date manipulation if chosen as the adapter. One of the peer dependencies must be installed and configured.","package":"moment","optional":false}],"imports":[{"note":"calendar-utils is primarily designed for ESM usage. While CommonJS might work via transpilation, direct require is not the idiomatic way.","wrong":"const { getCalendarMonthView } = require('calendar-utils');","symbol":"getCalendarMonthView","correct":"import { getCalendarMonthView } from 'calendar-utils';"},{"note":"All primary view generation functions are named exports; there is no default export.","wrong":"import getCalendarWeekView from 'calendar-utils';","symbol":"getCalendarWeekView","correct":"import { getCalendarWeekView } from 'calendar-utils';"},{"note":"It's best practice to import only the specific functions you need to optimize bundle size.","wrong":"import * as calendarUtils from 'calendar-utils';","symbol":"getCalendarDayView","correct":"import { getCalendarDayView, getWeekViewHeader } from 'calendar-utils';"}],"quickstart":{"code":"import { getCalendarMonthView } from 'calendar-utils';\nimport { startOfMonth, endOfMonth, eachDayOfInterval, format, addMonths } from 'date-fns';\n\ninterface CalendarDay {\n  date: Date;\n  isToday: boolean;\n  isWeekend: boolean;\n  events: string[];\n}\n\nconst currentDate = new Date();\nconst monthStart = startOfMonth(currentDate);\nconst monthEnd = endOfMonth(currentDate);\n\nconst calendarMonthView = getCalendarMonthView({\n  date: currentDate,\n  events: [], // Your events array, e.g., [{ start: new Date(), end: new Date(), title: 'Meeting' }]\n  weekStartsOn: 0, // Sunday\n  excluded: [], // e.g., [6] for Saturday\n  viewStart: monthStart,\n  viewEnd: monthEnd,\n  hourSegments: 2, // Not directly used by month view, but part of config\n  dayStartHour: 0,\n  dayEndHour: 23,\n  weekendDays: [0, 6]\n});\n\nconsole.log(`Month View for ${format(currentDate, 'MMMM yyyy')}:`);\ncalendarMonthView.days.forEach(day => {\n  console.log(`  ${format(day.date, 'yyyy-MM-dd')} (isCurrentMonth: ${day.inMonth}): ${day.events.length} events`);\n});\n\n// Example of getting a day outside the current month (for navigation)\nconst nextMonth = addMonths(currentDate, 1);\nconst nextMonthView = getCalendarMonthView({\n  date: nextMonth,\n  events: [],\n  weekStartsOn: 0,\n  excluded: [],\n  viewStart: startOfMonth(nextMonth),\n  viewEnd: endOfMonth(nextMonth),\n  hourSegments: 2,\n  dayStartHour: 0,\n  dayEndHour: 23,\n  weekendDays: [0, 6]\n});","lang":"typescript","description":"This quickstart demonstrates how to generate a calendar month view using `getCalendarMonthView` with `date-fns` for date manipulation."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.0"},{"fix":"Install your preferred date library: `npm install date-fns` or `npm install luxon` or `npm install moment`.","message":"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).","severity":"gotcha","affected_versions":">=0.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install the missing date library: `npm install date-fns` or `npm install luxon` or `npm install moment`.","cause":"A required peer dependency for date manipulation (e.g., date-fns) is not installed in your project.","error":"Error: Cannot find module 'date-fns' (or 'luxon' or 'moment')"},{"fix":"Ensure you are using ESM `import { getCalendarMonthView } from 'calendar-utils';` and your project supports ESM.","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.","error":"TypeError: getCalendarMonthView is not a function"},{"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`).","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.","error":"Argument of type 'string' is not assignable to parameter of type 'Date'."}],"ecosystem":"npm"}