calendarize

1.1.1 · active · verified Sun Apr 19

calendarize is a minimalist (202B) JavaScript utility designed to generate structured calendar views for a given month. Currently at version 1.1.1, it provides an array of arrays representing weeks, where each inner array contains 7 numbers corresponding to days of the month, with `0` indicating days outside the current month. The library is highly flexible, providing no date labels or internationalization (i18n) directly, which allows developers complete control over localization and rendering. It ships as ES Module, CommonJS, and UMD, making it suitable for various environments. Its main differentiator is its tiny footprint and unopinionated output, focusing solely on the grid structure rather than presentation, and it has a steady, albeit slow, release cadence driven by community contributions for minor enhancements.

Common errors

```
Calendar view shows incorrect days for the month, or the first day of the week is not what I expected.
```
cause This often occurs due to Node.js timezone issues when parsing date strings, or misunderstanding how the `offset` parameter (which defines the starting day of the week) influences the output.

fix To prevent timezone-related errors, always provide a `Date` object with explicit timezone control (e.g., `new Date('YYYY-MM-DDT00:00:00Z')`). For the week start, verify the `offset` value: `0` for Sunday (default), `1` for Monday, etc., to match your desired calendar layout. Ensure `calendarize` is `v1.1.0` or higher to use `offset`.
```
When rendering, some days appear as '0' or cause 'Cannot read properties of undefined' when attempting to format them.
```
cause The `calendarize` output uses `0` to represent days that fall outside the current month's view. Directly rendering or attempting to format `0` as a valid date without a check will lead to unexpected display or errors.

fix When iterating through the `Week` arrays, add a conditional check: `if (day === 0) { /* render empty */ } else { /* render day */ }`. This prevents processing `0` as a real date and allows for correct visual representation of empty cells.

Warnings

gotcha When passing `string` or `number` values for the `date` parameter, Node.js may apply an incorrect timezone during conversion to a `Date` object, leading to unexpected calendar views (e.g., month off by a day).
Fix: Always pass a `Date` object initialized with the desired timezone, e.g., `new Date('YYYY-MM-DDTHH:MM:SSZ')` or use robust date parsing libraries (like `date-fns` or `luxon`) to create a `Date` object before passing it to `calendarize`.
gotcha The output array contains `0` values for days that fall outside the current month's view. Developers must explicitly handle these `0`s when rendering the calendar, for instance, by displaying empty cells or styling them differently.
Fix: When iterating through the `Week` arrays, add a conditional check for `day === 0` to render an empty cell or specific placeholder (e.g., `''` or `null`) instead of attempting to process `0` as a valid date number.
gotcha The library explicitly does not provide day-of-week labels (e.g., 'Sun', 'Mon') or internationalization (i18n) support. This design choice requires developers to implement their own labeling and localization logic.
Fix: Integrate with an i18n library or manually create arrays for day labels (`['Sun', 'Mon', ...]`) and month names, mapping them to the `calendarize` output based on the `offset` parameter and locale expectations.
breaking The `offset` parameter, which controls the starting day of the week, was introduced in version `1.1.0`. Using it in versions prior to `1.1.0` will result in an error or the parameter being ignored, as it was not part of the API.
Fix: Ensure your project's `calendarize` dependency is at version `1.1.0` or higher to utilize the `offset` parameter. Update your `package.json` to specify `"calendarize": ">=1.1.0"` or run `npm install calendarize@latest`.

Install

npm install calendarize npm
yarn add calendarize yarn
pnpm add calendarize pnpm

Imports

calendarize
wrong:
```
import { calendarize } from 'calendarize';
```
correct:
```
import calendarize from 'calendarize';
```
This is a default export. For TypeScript, the type of `calendarize` is inferred or can be explicitly imported if needed.
calendarize
```
const calendarize = require('calendarize');
```
CommonJS usage for Node.js environments.

Quickstart

Demonstrates generating a calendar view for a given date, including how to specify a different start day for the week using the `offset` parameter.

import calendarize from 'calendarize';

// Example 1: Calendar view for a specific date instance
// Week = [Sun, Mon, Tue, Wed, Thu, Fri, Sat]
const dateInstanceView = calendarize(new Date('2024-07-20'));
console.log('July 2024 (Sunday start):', dateInstanceView);
/*
Output:
[
  [ 0,  1,  2,  3,  4,  5,  6],
  [ 7,  8,  9, 10, 11, 12, 13],
  [14, 15, 16, 17, 18, 19, 20],
  [21, 22, 23, 24, 25, 26, 27],
  [28, 29, 30, 31,  0,  0,  0]
]
*/

// Example 2: Calendar view for a date string with Monday as the start of the week
// Week = [Mon, Tue, Wed, Thu, Fri, Sat, Sun]
const mondayStartView = calendarize('Aug 01, 2024', 1);
console.log('August 2024 (Monday start):', mondayStartView);
/*
Output:
[
  [ 0,  0,  0,  1,  2,  3,  4],
  [ 5,  6,  7,  8,  9, 10, 11],
  [12, 13, 14, 15, 16, 17, 18],
  [19, 20, 21, 22, 23, 24, 25],
  [26, 27, 28, 29, 30, 31,  0]
]
*/

view raw JSON →