README.md (2)

87-91: Add a timeout example for fetch options.

Fetch has no default timeout; show an AbortController pattern to prevent hangs when endpoints stall.

-    // you can pass standard fetch() options (e.g. headers)
+    // you can pass standard fetch() options (e.g. headers, signal for timeout)
+    // Example: 5s timeout
+    const ac = new AbortController();
+    setTimeout(() => ac.abort(), 5000);
     const headerWebEvents = await ical.async.fromURL(
         'http://lanyrd.com/topics/nodejs/nodejs.ics',
-        { headers: { 'User-Agent': 'API-Example / 1.0' } }
+        { headers: { 'User-Agent': 'API-Example/1.0' }, signal: ac.signal }
     );

---

196-196: Clarify Node 16 fallback with a safe CJS-friendly polyfill snippet.

Current note is great; add a one-liner that works from CommonJS without pinning node-fetch v2.

-Fetch the specified URL using the native fetch API (```options``` are passed to the underlying `fetch()` call) and call the function with the result (either an error or the data). Requires Node.js 18+ (or any environment that provides a global `fetch`).
+Fetch the specified URL using the native fetch API (```options``` are passed to the underlying `fetch()` call) and call the function with the result (either an error or the data). Requires Node.js 18+ (or any environment that provides a global `fetch`).
+
+For older Node 16 setups, you can polyfill:
+```js
+// At app startup
+global.fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));
+```

node-ical.js (1)

102-110: Timeouts and clearer missing‑fetch error.

• Add optional timeout via AbortController for reliability.
• Prefer explicit globalThis.fetch and a helpful error if fetch is unavailable.

-    fetch(url, fetchOptions)
+    if (typeof globalThis.fetch !== 'function') {
+      reject(new Error('Global fetch is not available. Requires Node.js >=18 or a fetch polyfill.'));
+      return;
+    }
+
+    // Optional timeout (ms) if provided by caller
+    let timeoutId;
+    if (typeof fetchOptions.timeout === 'number') {
+      const ac = new AbortController();
+      fetchOptions.signal = fetchOptions.signal ?? ac.signal;
+      timeoutId = setTimeout(() => ac.abort(new Error('fetch timeout')), fetchOptions.timeout);
+      delete fetchOptions.timeout; // not a standard fetch option
+    }
+
+    globalThis.fetch(url, fetchOptions)
       .then(response => {
         if (!response.ok) {
           // Mimic previous error style
           throw new Error(`${response.status} ${response.statusText}`);
         }
-        return response.text();
+        return response.text();
       })
       .then(data => {
+        if (timeoutId) clearTimeout(timeoutId);
         ical.parseICS(data, (error, ics) => {

node-ical.d.ts (1)

4-14: Broaden FetchOptions.headers to avoid TS friction without DOM libs.

Current union rejects Headers instances in TS projects. Widening keeps strong typing while avoiding DOM dependency.

 export interface FetchOptions {
   method?: string;
-  headers?: Record<string, string> | Array<[string, string]>;
-  body?: any;
-  // Allow any additional fields (e.g. agent for node, redirect etc.) without forcing DOM lib.
-  [key: string]: any;
+  // Accept common shapes without importing DOM types
+  headers?: Record<string, string> | Array<[string, string]> | Iterable<[string, string]> | unknown;
+  body?: unknown;
+  // Allow Node-specific fields like `agent`, plus custom ones (e.g., `timeout`)
+  [key: string]: unknown;
 }

package.json (1)

20-22: CI already runs Node ≥18; engines entry matches

.github/workflows/nodejs.yml matrix includes node-version: [18.x, 20.x, 22.x, 24.x] and uses actions/setup-node@v4. Optional: add engine-strict=true to .npmrc to fail installs on older Node.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

test/test-fromURL.js (4)

97-99: Use strict assertions; avoid coercion

Prefer assert.strictEqual to prevent accidental type coercion in tests.

-        assert.equal(ev.summary, 'Fetch Test Event');
+        assert.strictEqual(ev.summary, 'Fetch Test Event');
@@
-        assert.equal(data, null);
+        assert.strictEqual(data, null);
@@
-        assert.equal(ev.summary, 'Secured Event');
+        assert.strictEqual(ev.summary, 'Secured Event');
@@
-        assert.equal(ev.summary, 'Callback No Options');
+        assert.strictEqual(ev.summary, 'Callback No Options');
@@
-          assert.equal(data, null);
+          assert.strictEqual(data, null);
@@
-        assert.equal(ev.summary, 'Promise Event');
+        assert.strictEqual(ev.summary, 'Promise Event');
@@
-        assert.strictEqual(ok, true);
+        assert.strictEqual(ok, true);

Also applies to: 121-122, 151-156, 181-186, 204-208, 235-240, 261-264

---

105-109: Silence unused param warnings for consistency

A few route handlers still use an unused request param; standardize on _request like elsewhere.

-            '/missing.ics'(request, res) {
+            '/missing.ics'(_request, res) {
@@
-            '/plain-missing.ics'(request, res) {
+            '/plain-missing.ics'(_request, res) {
@@
-              '/missing.ics'(request, res) {
+              '/missing.ics'(_request, res) {

Also applies to: 167-170, 191-194

---

86-90: Call test callbacks before teardown to avoid edge‑case races

Minor ordering tweak: invoke this.callback(...) first, then done(); teardown may occasionally preempt callbacks on slow CI.

Example (apply similarly to all topics):

-            ical.fromURL(`${urlBase}/ok.ics`, {}, (error, data) => {
-              done();
-              this.callback(error, data);
-            });
+            ical.fromURL(`${urlBase}/ok.ics`, {}, (error, data) => {
+              this.callback(error, data);
+              done();
+            });

Also applies to: 111-115, 143-147, 174-177, 197-201, 224-231

---

27-45: Harden server teardown to reduce Windows CI flakiness

Disable keep‑alive and tighten header timeout to avoid lingering sockets; give the close a slightly longer grace period.

Apply:

   const server = http.createServer((req, res) => {
@@
   });
 
+  // Reduce flakiness on Windows/Node by avoiding keep-alive lingering
+  server.keepAliveTimeout = 0;
+  server.headersTimeout = 1000;
+
@@
-      setTimeout(() => server.close(), 10);
+      setTimeout(() => server.close(), 25);

Then re-run the Windows workflow to confirm stability.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro