refactor: update XO and modernize codebase while adopting new rules (#520)

Author: KristjanESPERANTO

build/update-windows-zones.mjs

@@ -117,13 +117,13 @@ function mergeLegacyOverrides(zoneTable, oldMap) {
 
   const unresolved = [];
   let merged = 0;
-  for (const key of Object.keys(oldMap)) {
-    const iana = getFirstIanaFromLookup(zoneTable, oldMap[key]);
+  for (const [key, windowsId] of Object.entries(oldMap)) {
+    const iana = getFirstIanaFromLookup(zoneTable, windowsId);
     if (iana) {
       zoneTable[key] = {iana: [iana]};
       merged++;
     } else {
-      unresolved.push({label: key, windowsId: oldMap[key]});
+      unresolved.push({label: key, windowsId});
     }
   }
 
@@ -132,6 +132,7 @@ function mergeLegacyOverrides(zoneTable, oldMap) {
 
 function writeOutput(filePath, data) {
   // Deterministic, diff-friendly: one top-level key per line, minified values, sorted keys
+  // eslint-disable-next-line unicorn/require-array-sort-compare -- plain string keys; default lexicographic toSorted() is sufficient and clearer here
   const keys = Object.keys(data).toSorted();
   const lines = ['{'];
   for (const [idx, key] of keys.entries()) {

examples/example-rrule-dayjs.js

@@ -53,12 +53,12 @@ for (const event of events) {
     const title = instance.summary;
     const startDate = dayjs(instance.start);
     const endDate = dayjs(instance.end);
-    const duration = dayjs.duration(endDate.diff(startDate));
+    const eventDuration = dayjs.duration(endDate.diff(startDate));
 
     console.log(`title:${title}`);
     console.log(`startDate:${startDate.format('LLLL')}`);
     console.log(`endDate:${endDate.format('LLLL')}`);
-    console.log(`duration:${Math.floor(duration.asHours())}:${String(duration.minutes()).padStart(2, '0')} hours`);
+    console.log(`duration:${Math.floor(eventDuration.asHours())}:${String(eventDuration.minutes()).padStart(2, '0')} hours`);
     console.log();
   }
 }

ical.js

@@ -6,6 +6,7 @@ const Temporal = globalThis.Temporal || require('temporal-polyfill').Temporal;
 const windowsZones = require('../windowsZones.json');
 
 // Ensure polyfill is globally available for downstream modules
+// eslint-disable-next-line unicorn/no-global-object-property-assignment -- shared polyfill bootstrap keeps runtime behavior explicit
 globalThis.Temporal ??= Temporal;
 
 // Minimal alias map to emulate the subset of moment.tz.link behavior tests rely on
@@ -16,7 +17,7 @@ const aliasMap = new Map();
  * Collapses whitespace, trims the result, and lowercases the value for case-insensitive lookups.
  *
  * @param {string} label
- * @returns {string}
+ * @returns {string} Normalized label
  */
 function normalizeWindowsLabel(label) {
   return String(label)
@@ -30,7 +31,7 @@ function normalizeWindowsLabel(label) {
  * This lets us resolve the canonical IANA identifier without relying on fuzzy substring matching.
  *
  * @param {Record<string, {iana: string[]}>} source
- * @returns {Map<string, {iana: string[]}>}
+ * @returns {Map<string, {iana: string[]}>} Index map of normalized labels to data
  */
 function buildWindowsLabelIndex(source) {
   const index = new Map();
@@ -68,7 +69,7 @@ const windowsLabelIndex = buildWindowsLabelIndex(windowsZones);
  * Resolve a Windows/legacy timezone label to the canonical IANA identifier exported in windowsZones.json.
  *
  * @param {string} label
- * @returns {string|null}
+ * @returns {string|null} IANA zone or null if not found
  */
 function mapWindowsZone(label) {
   const exact = windowsZones[label];
@@ -106,7 +107,7 @@ const validIanaCache = new Map();
  * Convert textual UTC offsets ("+05:30", "UTC-4", "(UTC+02:00)") into signed minute counts.
  *
  * @param {string} offset
- * @returns {number|undefined}
+ * @returns {number|undefined} Total minutes or undefined if invalid
  */
 function offsetLabelToMinutes(offset) {
   if (!offset) {
@@ -118,7 +119,7 @@ function offsetLabelToMinutes(offset) {
     .replace(/^\(?(?:utc|gmt)\)?\s*/iv, '')
     .replace(/\)$/v, '')
     .trim();
-  const match = trimmed.match(/^([+\-])(\d{1,2})(?::?(\d{2}))?$/v);
+  const match = /^([+\-])(\d{1,2})(?::?(\d{2}))?$/v.exec(trimmed);
   if (!match) {
     return undefined;
   }
@@ -177,7 +178,7 @@ function minutesToEtcZone(totalMinutes) {
  * Interpret a TZID value (IANA, Windows display name, or offset label) and return structured metadata.
  *
  * @param {string} value
- * @returns {{original: string|undefined, iana: string|undefined, offset: string|undefined, offsetMinutes: number|undefined, etc: string|undefined}}
+ * @returns {{original: string|undefined, iana: string|undefined, offset: string|undefined, offsetMinutes: number|undefined, etc: string|undefined}} Resolved timezone metadata
  */
 function resolveTZID(value) {
   if (typeof value !== 'string' || value.length === 0) {
@@ -247,7 +248,7 @@ function resolveTZID(value) {
  *
  * @param {Date} date
  * @param {{iana?: string, offsetMinutes?: number}} tzInfo
- * @returns {string|undefined}
+ * @returns {string|undefined} Formatted wall-time string or undefined if invalid
  */
 function formatDateForRrule(date, tzInfo = {}) {
   if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
@@ -276,7 +277,7 @@ function formatDateForRrule(date, tzInfo = {}) {
  *
  * @param {Date} date
  * @param {string|undefined} tzid
- * @returns {Date|undefined}
+ * @returns {Date|undefined} Date with attached timezone metadata
  */
 function attachTz(date, tzid) {
   if (!date || !tzid) {
@@ -314,6 +315,8 @@ function guessLocalZone() {
  *
  * We depend on Node 20+, so `Intl.supportedValuesOf('timeZone')` is guaranteed
  * to exist and yields the canonical list without requiring extra guards.
+ *
+ * @returns {string[]} Array of IANA timezone names
  */
 function getZoneNames() {
   return Intl.supportedValuesOf('timeZone');
@@ -362,7 +365,7 @@ function parseDateTimeInZone(yyyymmddThhmmss, zone) {
   const s = String(yyyymmddThhmmss);
   // Support basic and extended forms
   // Try extended first: YYYY-MM-DDTHH:mm:ss
-  let m = s.match(/^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/v);
+  let m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/v.exec(s);
   let fields;
   if (m) {
     fields = {
@@ -375,7 +378,7 @@ function parseDateTimeInZone(yyyymmddThhmmss, zone) {
     };
   } else {
     // Basic form: YYYYMMDDTHHmmss or YYYYMMDDTHHmm
-    m = s.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})?$/v);
+    m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})?$/v.exec(s);
     if (m) {
       fields = {
         year: Number(m[1]),
@@ -413,10 +416,10 @@ function parseDateTimeInZone(yyyymmddThhmmss, zone) {
 function parseWithOffset(yyyymmddThhmmss, offset) {
   // Offset like +hh:mm, -hh:mm, +hhmm, -hhmm, optionally prefixed by UTC/GMT
   const s = String(yyyymmddThhmmss);
-  let m = s.match(/^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})?$/v);
+  let m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})?$/v.exec(s);
   // Some feeds emit extended ISO `YYYY-MM-DD[T ]HH:mm[:ss]` strings alongside numeric offsets.
   // Mirror parseDateTimeInZone by accepting that form too so we don't fall back to local Date semantics.
-  m ||= s.match(/^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/v);
+  m ||= /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})(?::(\d{2}))?$/v.exec(s);
 
   if (!m) {
     return undefined;
@@ -484,7 +487,7 @@ const vtimezoneIanaCache = new Map();
  *
  * @param {Array} blocks - Array of STANDARD or DAYLIGHT components (all same type)
  * @param {number} refYear - The event year to look up the rule for
- * @returns {Object|undefined}
+ * @returns {object | undefined} Applicable observance block or undefined
  */
 function pickApplicableBlock(blocks, refYear) {
   if (blocks.length === 0) {
@@ -527,10 +530,10 @@ function pickApplicableBlock(blocks, refYear) {
  *      No reliable representation is available; callers should fall back to
  *      floating/local time rather than returning a confidently wrong offset.
  *
- * @param {Object} vTimezone - Parsed VTIMEZONE object (from the node-ical parser stack)
+ * @param {object} vTimezone - Parsed VTIMEZONE object (from the node-ical parser stack)
  * @param {number} year - Reference year used to select the applicable observance block
  *   and to probe the IANA database (DST boundaries can change historically).
- * @returns {{ iana: string|undefined, offset: string|undefined }}
+ * @returns {{ iana: string|undefined, offset: string|undefined }} IANA zone and/or fixed offset
  */
 function resolveVTimezoneToIana(vTimezone, year) {
   if (!vTimezone || typeof vTimezone !== 'object') {
@@ -540,7 +543,7 @@ function resolveVTimezoneToIana(vTimezone, year) {
   // Reject unusable year values before they can corrupt the cache key or cause
   // Temporal.Instant.from() to throw on a malformed ISO string.
   const yearNumber = Number(year);
-  if (!Number.isFinite(yearNumber) || !Number.isInteger(yearNumber)) {
+  if (!Number.isFinite(yearNumber) || !Number.isSafeInteger(yearNumber)) {
     return {iana: undefined, offset: undefined};
   }
 
@@ -645,5 +648,5 @@ function isUtcTimezone(tz) {
   }
 
   const tzLower = tz.toLowerCase();
-  return tzLower === 'etc/utc' || tzLower === 'utc' || tzLower === 'etc/gmt';
+  return ['etc/utc', 'utc', 'etc/gmt'].includes(tzLower);
 }

lib/tz-utils.js

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+
 declare module 'node-ical' {
   /**
    * Compatibility wrapper returned by node-ical (RRULE results are Date-based).
@@ -45,7 +47,10 @@ declare module 'node-ical' {
      * Methods (Async)
      */
   export type NodeICalAsync = {
-    fromURL: ((url: string, callback: NodeIcalCallback) => void) & ((url: string, options: FetchOptions | NodeIcalCallback, callback?: NodeIcalCallback) => void) & ((url: string) => Promise<CalendarResponse>);
+    fromURL:
+      ((url: string, callback: NodeIcalCallback) => void)
+      & ((url: string, options: FetchOptions | NodeIcalCallback, callback?: NodeIcalCallback) => void)
+      & ((url: string) => Promise<CalendarResponse>);
 
     parseICS: ((body: string, callback: NodeIcalCallback) => void) & ((body: string) => Promise<CalendarResponse>);
 
@@ -161,11 +166,11 @@ declare module 'node-ical' {
 
   export type VTimeZone = TimeZoneProps & TimeZoneDictionary;
 
-  type TimeZoneProps = {
+  type TimeZoneProps = BaseComponent & {
     type: 'VTIMEZONE';
     tzid: string;
     tzurl?: string;
-  } & BaseComponent;
+  };
 
   type TimeZoneDictionary = Record<string, TimeZoneDef | undefined>;
 
@@ -180,7 +185,7 @@ declare module 'node-ical' {
   /**
    * https://www.kanzaki.com/docs/ical/valarm.html
    */
-  export type VAlarm = {
+  export type VAlarm = BaseComponent & {
     type: 'VALARM';
     action: 'AUDIO' | 'DISPLAY' | 'EMAIL' | 'PROCEDURE';
     trigger: Trigger;
@@ -209,7 +214,7 @@ declare module 'node-ical' {
      */
     attendee?: Attendee;
 
-  } & BaseComponent;
+  };
 
   /**
    * Common properties shared by calendar components (VEVENT, VTODO, VJOURNAL)
@@ -235,7 +240,7 @@ declare module 'node-ical' {
     exdate?: Record<string, DateWithTimeZone>;
   };
 
-  export type VEvent = CalendarComponentCommon & {
+  export type VEvent = CalendarComponentCommon & BaseComponent & {
     type: 'VEVENT';
     // RFC 5545 required fields (override optional from CalendarComponentCommon)
     uid: string;
@@ -267,7 +272,7 @@ declare module 'node-ical' {
      */
     recurrences?: Record<string, Omit<VEvent, 'recurrences'>>;
     alarms?: VAlarm[];
-  } & BaseComponent;
+  };
 
   /**
    * Todo status values as defined in RFC 5545
@@ -291,7 +296,7 @@ declare module 'node-ical' {
    *   console.log(`Completed: ${todo.completion}%`);
    * });
    */
-  export type VTodo = CalendarComponentCommon & {
+  export type VTodo = CalendarComponentCommon & BaseComponent & {
     type: 'VTODO';
     // RFC 5545 required fields (override optional from CalendarComponentCommon)
     uid: string;
@@ -315,7 +320,7 @@ declare module 'node-ical' {
      */
     recurrences?: Record<string, Omit<VTodo, 'recurrences'>>;
     alarms?: VAlarm[];
-  } & BaseComponent;
+  };
 
   /**
    * VJOURNAL component representing a journal entry or note.
@@ -328,7 +333,7 @@ declare module 'node-ical' {
    *   console.log(`Description: ${journal.description}`);
    * });
    */
-  export type VJournal = CalendarComponentCommon & {
+  export type VJournal = CalendarComponentCommon & BaseComponent & {
     type: 'VJOURNAL';
     // RFC 5545 required fields (override optional from CalendarComponentCommon)
     uid: string;
@@ -341,7 +346,7 @@ declare module 'node-ical' {
      * Uses dual-key approach (date and ISO timestamp).
      */
     recurrences?: Record<string, Omit<VJournal, 'recurrences'>>;
-  } & BaseComponent;
+  };
 
   /**
    * Free/busy time type as defined in RFC 5545
@@ -374,7 +379,7 @@ declare module 'node-ical' {
    *   });
    * }
    */
-  export type VFreebusy = {
+  export type VFreebusy = BaseComponent & {
     type: 'VFREEBUSY';
     method?: Method;
     uid?: string;
@@ -391,7 +396,7 @@ declare module 'node-ical' {
     freebusy?: FreebusyPeriod[];
     /** Attendee information */
     attendee?: Attendee[] | Attendee;
-  } & BaseComponent;
+  };
 
   /**
    * VCALENDAR component containing calendar-level metadata.