mnth: Calendar Month Generator

2.0.0 · active · verified Tue Apr 21

mnth is a lightweight, framework-agnostic utility library designed to simplify the generation of calendar-style month data. Its primary function, `getCalendarMonth`, takes a `Date` object and an optional configuration (e.g., `firstDayOfWeek`) to return a 2D array of `Date` objects, representing all days visible in a given month's calendar view, including leading and trailing days from adjacent months. Currently at version 2.0.0, the package provides a focused solution for UI components like datepickers and full calendars, distinguishing itself by providing raw `Date` objects for maximum flexibility rather than pre-formatted strings or complex component structures. It ships with TypeScript types, promoting strong type checking and improved developer experience. The library is part of the `nextools/metarepo` monorepo.

Common errors

```
TypeError: Cannot destructure property 'getCalendarMonth' of 'mnth' as it is undefined.
```
cause Attempting to use CommonJS `require` syntax on a package primarily designed for ES Modules without proper transpilation or configuration. `mnth` exports `getCalendarMonth` as a named ES Module export.

fix Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json` for Node.js) and use `import { getCalendarMonth } from 'mnth';`. If you must use CommonJS, you might need a bundler like Webpack or Rollup to transpile ESM to CJS, or explore dynamic `import()`.
```
RangeError: Invalid Date
```
cause The `Date` object passed to `getCalendarMonth` is invalid or represents an unparseable date. This can happen if the `Date` constructor received an invalid string or number.

fix Validate your input `Date` object before passing it to `getCalendarMonth`. Check if `isNaN(date.getTime())` is true, which indicates an invalid Date. Ensure date strings are in a consistent, parsable format (e.g., ISO 8601).

Warnings

gotcha The `firstDayOfWeek` option expects a number where `0` is Sunday, `1` is Monday, and so on, up to `6` for Saturday. Misinterpreting these values (e.g., assuming `1` is Sunday) can lead to incorrect calendar layouts.
Fix: Always refer to the documentation for the `firstDayOfWeek` option: `0` for Sunday, `1` for Monday (default), `6` for Saturday.
gotcha JavaScript `Date` objects are mutable. While `mnth` returns new `Date` objects in its 2D array, any subsequent modification to these `Date` instances in your application will affect the object directly. Be mindful of this when passing `Date` objects around or manipulating them after `getCalendarMonth` has returned.
Fix: If immutability is crucial, clone `Date` objects from the `mnth` output before performing modifications (e.g., `new Date(day.getTime())`).
gotcha Handling timezones with native JavaScript `Date` objects can be a source of common errors. `mnth` operates based on the `Date` object you provide, which will inherently have a timezone context (either UTC or local, depending on how it was created). Ensure your input `Date` objects and subsequent display logic align with your desired timezone handling to avoid unexpected shifts.
Fix: For consistent behavior, especially in applications serving users across different timezones, consider creating input `Date` objects in UTC (e.g., `new Date('YYYY-MM-DDTHH:MM:SSZ')`) and handle display-side timezone conversions explicitly, or use dedicated internationalization APIs.

Install

npm install mnth npm
yarn add mnth yarn
pnpm add mnth pnpm

Imports

getCalendarMonth
wrong:
```
const { getCalendarMonth } = require('mnth');
```
correct:
```
import { getCalendarMonth } from 'mnth';
```
mnth v2.0.0 is primarily designed for ES Modules. While CommonJS might work with transpilation, direct `require` is not the idiomatic or guaranteed approach. The package ships with TypeScript types for enhanced development.
Options
```
import type { Options } from 'mnth';
```
Importing types uses the `import type` syntax for clarity and to ensure they are stripped during compilation, though a regular `import` might also work depending on your TypeScript configuration.

Quickstart

This example demonstrates how to use `getCalendarMonth` to generate a 2D array of `Date` objects for a given month, showing both default and custom `firstDayOfWeek` options. It then formats and logs the day numbers for each week.

import { getCalendarMonth } from 'mnth';

// Get the calendar month for April 2018, with default options (Monday as first day of week)
const date = new Date('2018-04-01T12:00:00.000Z'); // Using UTC to avoid local timezone issues on initialization
const calendarMonth = getCalendarMonth(date);

console.log('Calendar for April 2018 (default options):');
calendarMonth.forEach(week => {
  console.log(week.map(day => day.toLocaleDateString('en-US', { day: '2-digit' })).join(', '));
});

// Example with custom options: Sunday as the first day of the week
const sundayFirstCalendar = getCalendarMonth(date, { firstDayOfWeek: 0 });

console.log('\nCalendar for April 2018 (Sunday as first day):');
sundayFirstCalendar.forEach(week => {
  console.log(week.map(day => day.toLocaleDateString('en-US', { day: '2-digit' })).join(', '));
});

/* Expected output structure (values depend on exact date/timezone):
Calendar for April 2018 (default options):
26, 27, 28, 29, 30, 31, 01
02, 03, 04, 05, 06, 07, 08
09, 10, 11, 12, 13, 14, 15
16, 17, 18, 19, 20, 21, 22
23, 24, 25, 26, 27, 28, 29
30, 01, 02, 03, 04, 05, 06

Calendar for April 2018 (Sunday as first day):
25, 26, 27, 28, 29, 30, 31
01, 02, 03, 04, 05, 06, 07
08, 09, 10, 11, 12, 13, 14
15, 16, 17, 18, 19, 20, 21
22, 23, 24, 25, 26, 27, 28
29, 30, 01, 02, 03, 04, 05
*/

view raw JSON →