NW.js Notification API floods users with alerts — where should throttling live?

Answer

Throttle the burst of events in the Node context before they reach the window context. Collapse or coalesce the events there, then send a single, already‑summarised Notification payload to the DOM. Use the tray icon for steady‑state status and a small in‑app history panel for missed alerts. An in‑app quiet‑hours toggle is useful, but it only suppresses the notifications your code sends; it cannot override the OS’s own Do‑Not‑Disturb setting.

Why Node‑side throttling is preferable

• The Notification constructor in NW.js (Chromium‑based) has no built‑in rate limiting, grouping, or channels. Any collapsing logic must live in app code.
• Coalescing in Node prevents the window from creating dozens of Notification objects, which is more efficient and keeps the DOM side simple.
• Events in Node are already in a single thread; a burst window or debounce can be implemented with a single timer and counter.
• When the window later receives the collapsed payload, it only has to render one notification (or a summary), regardless of how many underlying events triggered.

Typical burst‑window pattern

Show the first event immediately, then buffer subsequent events for a few seconds. When the buffer times out, emit a single summary notification such as "12 files changed". This pattern keeps the user from seeing a flood of identical pop‑ups while still conveying the volume of activity.

// Node side – collapse before sending to the window
let pending = 0, timer = null;
function onWatcherChange(file) {
  if (!timer) {
    // First event – send immediately
    sendToWindow({ type: 'notify', body: file });
  }
  pending++;
  clearTimeout(timer);
  timer = setTimeout(() => {
    if (pending > 1) {
      sendToWindow({ type: 'notify', body: `${pending} files changed` });
    }
    pending = 0;
    timer = null;
  }, 4000); // 4‑second burst window
}

Replace sendToWindow with your chosen IPC mechanism (e.g., window.postMessage, a shared nw.Window.open channel, or a local server). The window simply renders whatever it receives.

Tray icon and passive status

• A nw.Tray icon is ideal for showing a lightweight status (e.g., a counter of pending syncs or a simple "idle" icon).
• Because the tray tooltip disappears when the cursor leaves, it should not be the sole record of events. Add a tiny in‑app history panel that users can open from the tray menu. This mirrors the behaviour of mature sync clients and IDEs.
• Reserve desktop notifications for events that require user action (sync failures, conflicts, or urgent alerts).

Quiet‑hours toggle

Implementing an in‑app quiet‑hours setting is worthwhile because:

• It suppresses the notifications your code sends, giving users control over noise.
• It works independently of the OS’s Do‑Not‑Disturb state, which NW.js cannot reliably detect across platforms.
• Document the distinction clearly in the settings UI: "This setting only affects the notifications generated by this app; it does not alter the system Do‑Not‑Disturb behaviour.”

Verification steps

1. Log the raw event count in Node before throttling and the number of notifications sent to the window after throttling.
2. Simulate a burst of file‑watcher events and visually confirm that only the first and one summary notification appear.
3. Record nw.process.versions on startup to note the Chromium version; repeat tests after any NW.js upgrade.
4. Enable the OS’s Do‑Not‑Disturb mode on each target platform and verify that your quiet‑hours toggle still behaves as documented.

Missing diagnostic detail

If you need to differentiate between event types (e.g., watcher hits vs. sync failures), you might want separate burst windows per severity. Let us know if that is a requirement, and we can adjust the throttling strategy accordingly.