noctcore-dates/no-local-calendar-time
noctcore-dates/no-local-calendar-time
- Package
- dates v0.1.0
- Preset
- none opt-in
- Severity
- off
- Autofix
- No
- Suggestions
- No
- Options
- Optional
- Type info
- Not needed
A calendar day is read in one agreed zone, never in whatever zone the machine is in.
A due date, a birthday or a leave day is a calendar day, not an instant. Once it is stored as a
Date, every read has to use the same zone, and the Date API makes the machine’s zone the easy
default. The same row then shows 31 March on a laptop in Warsaw and 30 March on a CI runner in
UTC or a browser in New York, and the test suite passes on whichever machine wrote it:
// rule options: {"allowIn":["**/src/lib/calendar.ts"]}export function leaveLabel(day: Date): string { return `${day.getDate()}.${day.getMonth() + 1}.${day.getFullYear()}`;}// rule options: {"allowIn":["**/src/lib/calendar.ts"]}import { formatDay } from '../lib/calendar';
export function leaveLabel(day: Date): string { return formatDay(day);}The calendar module answers the question once, in the zone the product agreed on (with
Intl.DateTimeFormat and a timeZone, or the UTC accessors for a day stored as midnight UTC),
and is the one file in allowIn.
What it flags
Section titled “What it flags”Three shapes by default, and a fourth through checks:
localAccessor:getFullYear,getMonth,getDate,getDay,getHours,getMinutesand their setters (setFullYeartosetMinutes), on any receiver, includingd?.getDate()andd['getDate']().dateOnlyParse:new Date('2026-03-31')andDate.parse('2026-03-31'). A date-only string parses as midnight UTC, so a local accessor or formatter reads it as 30 March anywhere west of UTC.isoDaySlice:toISOString().slice(0, 10),.substring(0, 10),.substr(0, 10)and.split('T')[0]. That is the UTC day of the instant, so “today” is yesterday in Warsaw just after midnight.instantVsNow(opt-in):due.getTime() < Date.now()in either order with any ordering operator. For a day stored as midnight it says the day is over from its first minute, so a deadline is overdue on its own last day.
// rule options: {"allowIn":["**/src/lib/calendar.ts"]}export const today = new Date().toISOString().slice(0, 10);export const firstDay = new Date('2026-01-01');// rule options: {"checks":["instantVsNow"]}export const isOverdue = (task: { dueAt: Date }) => task.dueAt.getTime() < Date.now();What it does not flag
Section titled “What it does not flag”- Any file matched by
allowIn. - The UTC accessors (
getUTCDate()), whichcalendar-math-via-sharedcovers. - A full timestamp with its zone (
new Date('2026-03-31T08:00:00Z')), the year, month and day constructor, andtoISOString()kept whole or cut somewhere else. getTime()againstDate.now()unlessinstantVsNowis on, and with it, equality and arithmetic (Date.now() - start.getTime()).
// rule options: {"allowIn":["**/src/lib/calendar.ts"]}const WARSAW = new Intl.DateTimeFormat('pl-PL', { timeZone: 'Europe/Warsaw', dateStyle: 'short' });
export const formatDay = (day: Date): string => WARSAW.format(day);export const dayOfMonth = (day: Date): number => day.getDate();Options
Section titled “Options”| Option | Type | Default | Meaning |
|---|---|---|---|
allowIn |
string[] (globs) |
[] |
Files exempt from the rule (the calendar module and its tests), matched against the absolute path and the path relative to the working directory or workspace root, so src/calendar/** and **/calendar/** both work. |
checks |
string[] |
["localAccessor", "dateOnlyParse", "isoDaySlice"] |
The shapes to report. Add instantVsNow when every Date compared with the clock in scope is a calendar day. |
calendarModule |
string |
none | Import path of your calendar module, named in the message. |
'noctcore-dates/no-local-calendar-time': ['error', { allowIn: ['**/src/lib/calendar.ts'], calendarModule: '@acme/shared/calendar',}]To scope the rule to part of a repo, set files on the config block that enables it.
A codebase that stores every calendar day as a midnight-UTC key reads it with the UTC accessors,
creates it with new Date('2026-03-31') and formats it with toISOString().slice(0, 10), all
correctly. There, checks: ['localAccessor', 'instantVsNow'] keeps the two shapes that are wrong
for such a key and drops the two that are its convention.
When not to use it
Section titled “When not to use it”A codebase whose dates are all instants (log stamps, token expiries, getHours() for a greeting)
has no calendar days to protect. Scope the rule with files to the code that handles days, or
leave it off.