dsh-subscriptions 0.1.2 → 0.1.4

package/lib/client/usage-pace.js

@@ -23,13 +23,26 @@ export function resetCountdownParts(ms) {
     ];
     return parts.filter(part => part.count > 0).slice(0, 2);
 }
+/**
+ * Whether the reported percentage still describes the window now. Only a fresh
+ * reading may be compared with the current time (pace warnings); an old one
+ * keeps its absolute color. This does not decide whether the time cursor is
+ * drawn: where the window stands in time never depends on the reading.
+ */
 export function isUsageFresh(window, observation, now = Date.now()) {
     return validUsage(window.usedPercent) && observation.stale !== true
         && observation.observedAt !== undefined && Number.isFinite(observation.observedAt)
         && observation.observedAt <= now && now - observation.observedAt <= USAGE_FRESHNESS_MS
         && (window.resetsAt === undefined || Number.isFinite(window.resetsAt) && window.resetsAt > now);
 }
-/** Only explicit intervals or provider-verified fixed durations support linear pace. */
+/**
+ * How far through its window the clock is, from the window's own timing alone.
+ * It ignores the percentage and how recently it was read, so an unused,
+ * stale, aged or unobserved reading keeps its cursor whenever the timing
+ * places it. Returns undefined when the timing cannot: only an explicit
+ * interval or a provider-verified fixed duration supports linear pace, and no
+ * start is invented from a window's kind or label.
+ */
 export function elapsedPercent(window, now = Date.now()) {
     const end = window.resetsAt;
     if (end === undefined || !Number.isFinite(end) || end <= now)