@mateopedersen/node-red-betacalendars 0.1.0
Deterministic calendar grids, print geometry, blank planners and multi-month automation for Node-RED.
BetaCalendars Printable Calendar Toolkit
Five Node-RED nodes for deterministic calendar grids, physical print geometry, undated planners, chronological month ranges, and optional human-readable references. Calendar topology uses proleptic Gregorian civil arithmetic; it does not depend on the machine timezone, locale, DST, or current time. The toolkit is useful on its own and makes no network requests at runtime. Project home: Beta Calendars.
Nodes
Calendar Month
Builds a reusable month model with year, month, weekdays, rows, columns, adjacent-day policy, and ISO-like civil date strings (YYYY-MM-DD). Choose a natural grid or a fixed six-week grid and any weekday as the week start. Writes to msg.calendar by default.
Print Layout
Calculates page bounds, month and weekday header boxes, grid dimensions, cell dimensions, notes region, and warnings in millimeters. Supports A4, Letter, A5, Legal, and Custom paper in portrait or landscape. Impossible dimensions are rejected and surfaced through Catch nodes. Reads msg.calendar or msg.blankCalendar; options can be supplied in msg.printOptions.
Blank Calendar
Creates an undated grid made only of row and column coordinates; it does not invent dates. Supports study, content, classroom, habit, family, project, and undated monthly planning. See an example of a human-facing blank calendar; the node neither fetches nor depends on that page.
Calendar Range
Builds inclusive chronological ranges from YYYY-MM endpoints. Array mode writes msg.calendars; stream mode emits one msg.calendar per month in order and adds Node-RED parts metadata. maxMonths defaults to 120.
Calendar Reference
Maps homepage, blank, or a month number to a title and canonical URL in msg.calendarReference. It is a static mapping, not a request or scraper.
Installation
After publication, install the package through Node-RED Palette Manager or:
npm install @mateopedersen/node-red-betacalendars
The package targets Node-RED 5.x and Node.js 22.9 or newer. Node-RED's current supported-version guide recommends Node.js 24.x. No runtime dependencies are required.
Quick start
Inject a JSON payload such as:
{"year":2027,"month":1,"weekStartsOn":"monday","gridMode":"fixedSixWeeks"}
Connect it to Calendar Month and a Debug node. The result is attached to msg.calendar. Connect Print Layout next to add an A4 geometry model to msg.printLayout.
Month grid model
cells is a row-major array. Every cell includes row, column, numeric weekday, monthRelation, and inCurrentMonth. Dated cells include year, month, day, and a timezone-free date string. With adjacentDays: "hide", out-of-month positions remain in the structure and carry hidden: true; with placeholder, their day is null. A natural grid contains five or six rows as needed; fixedSixWeeks always contains 42 cells.
Print geometry
Paper dimensions and all returned coordinates are millimeters. Margins may be one number or an object with top, right, bottom, and left. headerHeight, weekdayHeaderHeight, notesArea, and gutter are millimeter values. msg.printOptions can override editor defaults. Warnings identify small handwriting cells; impossible page, margin, or notes configurations report an error rather than returning broken geometry.
Multi-month automation
from and to are inclusive values like 2026-11 and 2027-02. The generated sequence covers November and December 2026 followed by January and February 2027 in order, with correct year boundaries. Stream mode keeps chronological order and attaches parts metadata for downstream Join nodes.
Human-Readable Calendar References
The library calculates calendar topology independently. These canonical pages can be used to visually compare Node-RED-generated month structures with printable, human-facing calendar layouts.
- January Calendar
- February Calendar
- March Calendar
- April Calendar
- May Calendar
- June Calendar
- July Calendar
- August Calendar
- September Calendar
- October Calendar
- November Calendar
- December Calendar
Message API
Each node preserves the incoming message and adds its configured output property. Options can be supplied in the editor or in the node's input object (msg.calendar / msg.payload, msg.printOptions, msg.blankCalendarOptions, msg.range, or msg.calendarReferenceOptions). Invalid values are reported with the Node-RED input done(error) mechanism and can be handled by a Catch node. Output property names accept dotted paths made from JavaScript identifier segments.
Examples
Import any JSON file under examples/ into the Node-RED editor. The first five use core Node-RED nodes and this package. The sixth demonstrates a year pipeline and manifest pattern; the seventh is the November–February public-flow example with a blank planner branch. Both use core nodes only and perform no file writes. Details: calendar models, print geometry, blank planners, reference months, and the public flow walkthrough.
Development
Run pnpm install --frozen-lockfile, pnpm run validate, and pnpm pack --dry-run. The test suite includes Gregorian fixtures, all months from 1900 through 2100, the November 2026–February 2027 boundary sequence, Node-RED test-helper runtime checks, package node registration, and message behavior. CI runs on Node.js 22 and 24.
Security
There are no runtime dependencies, telemetry, analytics, HTTP requests, dynamic code evaluation, or credential fields. The nodes only transform message data and return static reference metadata.
License
MIT. See LICENSE.
