{"id":15468,"library":"mnth","title":"mnth: Calendar Month Generator","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/nextools/metarepo","tags":["javascript","date","month","calendar","typescript"],"install":[{"cmd":"npm install mnth","lang":"bash","label":"npm"},{"cmd":"yarn add mnth","lang":"bash","label":"yarn"},{"cmd":"pnpm add mnth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { getCalendarMonth } = require('mnth');","symbol":"getCalendarMonth","correct":"import { getCalendarMonth } from 'mnth';"},{"note":"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.","symbol":"Options","correct":"import type { Options } from 'mnth';"}],"quickstart":{"code":"import { getCalendarMonth } from 'mnth';\n\n// Get the calendar month for April 2018, with default options (Monday as first day of week)\nconst date = new Date('2018-04-01T12:00:00.000Z'); // Using UTC to avoid local timezone issues on initialization\nconst calendarMonth = getCalendarMonth(date);\n\nconsole.log('Calendar for April 2018 (default options):');\ncalendarMonth.forEach(week => {\n  console.log(week.map(day => day.toLocaleDateString('en-US', { day: '2-digit' })).join(', '));\n});\n\n// Example with custom options: Sunday as the first day of the week\nconst sundayFirstCalendar = getCalendarMonth(date, { firstDayOfWeek: 0 });\n\nconsole.log('\\nCalendar for April 2018 (Sunday as first day):');\nsundayFirstCalendar.forEach(week => {\n  console.log(week.map(day => day.toLocaleDateString('en-US', { day: '2-digit' })).join(', '));\n});\n\n/* Expected output structure (values depend on exact date/timezone):\nCalendar for April 2018 (default options):\n26, 27, 28, 29, 30, 31, 01\n02, 03, 04, 05, 06, 07, 08\n09, 10, 11, 12, 13, 14, 15\n16, 17, 18, 19, 20, 21, 22\n23, 24, 25, 26, 27, 28, 29\n30, 01, 02, 03, 04, 05, 06\n\nCalendar for April 2018 (Sunday as first day):\n25, 26, 27, 28, 29, 30, 31\n01, 02, 03, 04, 05, 06, 07\n08, 09, 10, 11, 12, 13, 14\n15, 16, 17, 18, 19, 20, 21\n22, 23, 24, 25, 26, 27, 28\n29, 30, 01, 02, 03, 04, 05\n*/","lang":"typescript","description":"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."},"warnings":[{"fix":"Always refer to the documentation for the `firstDayOfWeek` option: `0` for Sunday, `1` for Monday (default), `6` for Saturday.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"If immutability is crucial, clone `Date` objects from the `mnth` output before performing modifications (e.g., `new Date(day.getTime())`).","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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()`.","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.","error":"TypeError: Cannot destructure property 'getCalendarMonth' of 'mnth' as it is undefined."},{"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).","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.","error":"RangeError: Invalid Date"}],"ecosystem":"npm"}