@oneuptime/common 11.6.1 → 11.6.2

package/Tests/Utils/NetworkSite/SiteStatusRollupUtil.test.ts

@@ -0,0 +1,221 @@
+import SiteStatusRollupUtil, {
+  DeviceHealthState,
+  RollupStatusOption,
+} from "../../../Utils/NetworkSite/SiteStatusRollupUtil";
+
+/*
+ * MonitorStatus priority is HIGHER = WORSE (seeded: Operational 1,
+ * Degraded 2, Offline 3).
+ */
+const OPERATIONAL: RollupStatusOption = {
+  monitorStatusId: "status-operational",
+  priority: 1,
+};
+const DEGRADED: RollupStatusOption = {
+  monitorStatusId: "status-degraded",
+  priority: 2,
+};
+const OFFLINE: RollupStatusOption = {
+  monitorStatusId: "status-offline",
+  priority: 3,
+};
+
+const NOW: Date = new Date("2026-07-22T12:00:00Z");
+
+function minutesAgo(minutes: number): Date {
+  return new Date(NOW.getTime() - minutes * 60 * 1000);
+}
+
+function worst(
+  deviceStates: Array<DeviceHealthState>,
+  overrides?: {
+    operationalStatus?: RollupStatusOption | null;
+    offlineStatus?: RollupStatusOption | null;
+    freshnessWindowInMinutes?: number;
+  },
+): string | null {
+  return SiteStatusRollupUtil.worstStatus({
+    deviceStates,
+    operationalStatus:
+      overrides && "operationalStatus" in overrides
+        ? overrides.operationalStatus
+        : OPERATIONAL,
+    offlineStatus:
+      overrides && "offlineStatus" in overrides
+        ? overrides.offlineStatus
+        : OFFLINE,
+    now: NOW,
+    freshnessWindowInMinutes: overrides?.freshnessWindowInMinutes,
+  });
+}
+
+describe("SiteStatusRollupUtil.worstStatus", () => {
+  it("returns null for an empty device set (no-op)", () => {
+    expect(worst([])).toBeNull();
+  });
+
+  it("a single monitored device contributes its stamped status", () => {
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: DEGRADED.monitorStatusId,
+          monitorStatusPriority: DEGRADED.priority,
+        },
+      ]),
+    ).toBe(DEGRADED.monitorStatusId);
+  });
+
+  it("the worst (highest priority) stamped status wins", () => {
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: OPERATIONAL.monitorStatusId,
+          monitorStatusPriority: OPERATIONAL.priority,
+        },
+        {
+          currentMonitorStatusId: OFFLINE.monitorStatusId,
+          monitorStatusPriority: OFFLINE.priority,
+        },
+        {
+          currentMonitorStatusId: DEGRADED.monitorStatusId,
+          monitorStatusPriority: DEGRADED.priority,
+        },
+      ]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("a fresh unmonitored device maps to the operational equivalent", () => {
+    expect(worst([{ lastSeenAt: minutesAgo(5) }])).toBe(
+      OPERATIONAL.monitorStatusId,
+    );
+  });
+
+  it("a stale unmonitored device maps to the offline equivalent", () => {
+    expect(worst([{ lastSeenAt: minutesAgo(30) }])).toBe(
+      OFFLINE.monitorStatusId,
+    );
+  });
+
+  it("a never-seen unmonitored device maps to the offline equivalent", () => {
+    expect(worst([{}])).toBe(OFFLINE.monitorStatusId);
+    expect(worst([{ lastSeenAt: null }])).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("freshness boundary: exactly 15 minutes is still fresh, beyond is not", () => {
+    expect(worst([{ lastSeenAt: minutesAgo(15) }])).toBe(
+      OPERATIONAL.monitorStatusId,
+    );
+    expect(
+      worst([{ lastSeenAt: new Date(minutesAgo(15).getTime() - 1) }]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("mix: a stale unmonitored device outranks a monitored operational one", () => {
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: OPERATIONAL.monitorStatusId,
+          monitorStatusPriority: OPERATIONAL.priority,
+        },
+        { lastSeenAt: minutesAgo(60) },
+      ]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("mix: a monitored offline device outranks fresh unmonitored ones", () => {
+    expect(
+      worst([
+        { lastSeenAt: minutesAgo(1) },
+        {
+          currentMonitorStatusId: OFFLINE.monitorStatusId,
+          monitorStatusPriority: OFFLINE.priority,
+        },
+        { lastSeenAt: minutesAgo(2) },
+      ]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("a stamped status whose priority is unknown falls back to freshness", () => {
+    // The MonitorStatus row was deleted: treat the device by lastSeenAt.
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: "deleted-status",
+          monitorStatusPriority: undefined,
+          lastSeenAt: minutesAgo(1),
+        },
+      ]),
+    ).toBe(OPERATIONAL.monitorStatusId);
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: "deleted-status",
+          monitorStatusPriority: null,
+          lastSeenAt: minutesAgo(120),
+        },
+      ]),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("priority ties keep the first contributor (stable)", () => {
+    expect(
+      worst([
+        {
+          currentMonitorStatusId: "status-a",
+          monitorStatusPriority: 2,
+        },
+        {
+          currentMonitorStatusId: "status-b",
+          monitorStatusPriority: 2,
+        },
+      ]),
+    ).toBe("status-a");
+  });
+
+  it("returns null when only freshness fallbacks apply but the project has no flagged rows", () => {
+    expect(
+      worst([{ lastSeenAt: minutesAgo(1) }, { lastSeenAt: minutesAgo(60) }], {
+        operationalStatus: null,
+        offlineStatus: null,
+      }),
+    ).toBeNull();
+  });
+
+  it("skips devices without a usable fallback but keeps the rest", () => {
+    expect(
+      worst(
+        [
+          { lastSeenAt: minutesAgo(60) }, // offline equivalent missing -> skipped
+          {
+            currentMonitorStatusId: DEGRADED.monitorStatusId,
+            monitorStatusPriority: DEGRADED.priority,
+          },
+        ],
+        { offlineStatus: null },
+      ),
+    ).toBe(DEGRADED.monitorStatusId);
+  });
+
+  it("honors a custom freshness window", () => {
+    expect(
+      worst([{ lastSeenAt: minutesAgo(20) }], {
+        freshnessWindowInMinutes: 30,
+      }),
+    ).toBe(OPERATIONAL.monitorStatusId);
+    expect(
+      worst([{ lastSeenAt: minutesAgo(20) }], {
+        freshnessWindowInMinutes: 10,
+      }),
+    ).toBe(OFFLINE.monitorStatusId);
+  });
+
+  it("a lastSeenAt in the future counts as fresh, not an error", () => {
+    expect(worst([{ lastSeenAt: minutesAgo(-5) }])).toBe(
+      OPERATIONAL.monitorStatusId,
+    );
+  });
+
+  it("exposes the default freshness window as 15 minutes", () => {
+    expect(SiteStatusRollupUtil.DEFAULT_FRESHNESS_WINDOW_IN_MINUTES).toBe(15);
+  });
+});

package/Tests/Utils/NetworkSite/SiteUptimeUtil.test.ts

@@ -0,0 +1,283 @@
+import SiteUptimeUtil, {
+  SiteStatusTimelineRow,
+} from "../../../Utils/NetworkSite/SiteUptimeUtil";
+
+const WINDOW_START: Date = new Date("2026-07-22T00:00:00Z");
+const WINDOW_END: Date = new Date("2026-07-23T00:00:00Z"); // 24h window
+
+function hoursAfterStart(hours: number): Date {
+  return new Date(WINDOW_START.getTime() + hours * 60 * 60 * 1000);
+}
+
+function row(data: {
+  startsAt: Date;
+  endsAt: Date | null;
+  isOperationalState: boolean;
+  priority?: number;
+}): SiteStatusTimelineRow {
+  return {
+    monitorStatusId: data.isOperationalState ? "operational" : "down",
+    startsAt: data.startsAt,
+    endsAt: data.endsAt,
+    priority: data.priority ?? (data.isOperationalState ? 1 : 3),
+    isOperationalState: data.isOperationalState,
+  };
+}
+
+describe("SiteUptimeUtil.calculateUptimePercent", () => {
+  it("is 100 with no timeline rows", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent([], WINDOW_START, WINDOW_END),
+    ).toBe(100);
+  });
+
+  it("is 100 when every row is operational", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: WINDOW_START,
+            endsAt: null,
+            isOperationalState: true,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(100);
+  });
+
+  it("is 0 when a non-operational row covers the whole window", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: WINDOW_START,
+            endsAt: WINDOW_END,
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(0);
+  });
+
+  it("an open row (endsAt null) extends to the window end", () => {
+    // Down from hour 18 onwards -> 6h down of 24h -> 75% up.
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: hoursAfterStart(18),
+            endsAt: null,
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(75);
+  });
+
+  it("clamps rows that extend beyond both window edges", () => {
+    // Down row spans well beyond the window on both sides -> 0% up.
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: new Date("2026-07-20T00:00:00Z"),
+            endsAt: new Date("2026-07-25T00:00:00Z"),
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(0);
+  });
+
+  it("clamps a row that starts before the window", () => {
+    // Down until hour 6 -> 18h up of 24h -> 75%.
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: new Date("2026-07-21T12:00:00Z"),
+            endsAt: hoursAfterStart(6),
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(75);
+  });
+
+  it("ignores rows entirely outside the window", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: new Date("2026-07-20T00:00:00Z"),
+            endsAt: new Date("2026-07-21T00:00:00Z"),
+            isOperationalState: false,
+          }),
+          row({
+            startsAt: new Date("2026-07-24T00:00:00Z"),
+            endsAt: new Date("2026-07-25T00:00:00Z"),
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(100);
+  });
+
+  it("merges overlapping down rows so no second is counted twice", () => {
+    // [2h, 8h] and [6h, 12h] overlap -> merged 10h down -> ~58.33% up.
+    const percent: number = SiteUptimeUtil.calculateUptimePercent(
+      [
+        row({
+          startsAt: hoursAfterStart(2),
+          endsAt: hoursAfterStart(8),
+          isOperationalState: false,
+        }),
+        row({
+          startsAt: hoursAfterStart(6),
+          endsAt: hoursAfterStart(12),
+          isOperationalState: false,
+        }),
+      ],
+      WINDOW_START,
+      WINDOW_END,
+    );
+    expect(percent).toBeCloseTo(((24 - 10) / 24) * 100, 10);
+  });
+
+  it("merges a row contained inside another", () => {
+    const percent: number = SiteUptimeUtil.calculateUptimePercent(
+      [
+        row({
+          startsAt: hoursAfterStart(2),
+          endsAt: hoursAfterStart(12),
+          isOperationalState: false,
+        }),
+        row({
+          startsAt: hoursAfterStart(4),
+          endsAt: hoursAfterStart(6),
+          isOperationalState: false,
+        }),
+      ],
+      WINDOW_START,
+      WINDOW_END,
+    );
+    expect(percent).toBeCloseTo(((24 - 10) / 24) * 100, 10);
+  });
+
+  it("sums disjoint down rows", () => {
+    // 3h + 3h down -> 18h up -> 75%.
+    const percent: number = SiteUptimeUtil.calculateUptimePercent(
+      [
+        row({
+          startsAt: hoursAfterStart(1),
+          endsAt: hoursAfterStart(4),
+          isOperationalState: false,
+        }),
+        row({
+          startsAt: hoursAfterStart(10),
+          endsAt: hoursAfterStart(13),
+          isOperationalState: false,
+        }),
+      ],
+      WINDOW_START,
+      WINDOW_END,
+    );
+    expect(percent).toBe(75);
+  });
+
+  it("interleaves operational and non-operational rows correctly", () => {
+    // Operational rows never subtract, whatever they overlap.
+    const percent: number = SiteUptimeUtil.calculateUptimePercent(
+      [
+        row({
+          startsAt: WINDOW_START,
+          endsAt: hoursAfterStart(12),
+          isOperationalState: true,
+        }),
+        row({
+          startsAt: hoursAfterStart(12),
+          endsAt: hoursAfterStart(18),
+          isOperationalState: false,
+        }),
+        row({
+          startsAt: hoursAfterStart(18),
+          endsAt: null,
+          isOperationalState: true,
+        }),
+      ],
+      WINDOW_START,
+      WINDOW_END,
+    );
+    expect(percent).toBe(75);
+  });
+
+  it("a zero-length down row contributes nothing", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: hoursAfterStart(5),
+            endsAt: hoursAfterStart(5),
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(100);
+  });
+
+  it("returns 100 for a zero-length or inverted window", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent([], WINDOW_START, WINDOW_START),
+    ).toBe(100);
+    expect(
+      SiteUptimeUtil.calculateUptimePercent([], WINDOW_END, WINDOW_START),
+    ).toBe(100);
+  });
+
+  it("an open down row starting exactly at windowEnd contributes nothing", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: WINDOW_END,
+            endsAt: null,
+            isOperationalState: false,
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(100);
+  });
+
+  it("non-operational status of ANY priority counts as down (degraded too)", () => {
+    expect(
+      SiteUptimeUtil.calculateUptimePercent(
+        [
+          row({
+            startsAt: WINDOW_START,
+            endsAt: hoursAfterStart(6),
+            isOperationalState: false,
+            priority: 2, // degraded
+          }),
+        ],
+        WINDOW_START,
+        WINDOW_END,
+      ),
+    ).toBe(75);
+  });
+});

package/Tests/Utils/ObjectUtil.test.ts

@@ -0,0 +1,30 @@
+import ObjectUtil from "../../Utils/ObjectUtil";
+import { GlobalObject } from "../../Types/Object";
+
+describe("ObjectUtil.isEmpty", () => {
+  test("should return true for an object with no own keys", () => {
+    expect(ObjectUtil.isEmpty({} as GlobalObject)).toBe(true);
+  });
+
+  test("should return false when the object has keys", () => {
+    expect(ObjectUtil.isEmpty({ a: 1 } as unknown as GlobalObject)).toBe(false);
+  });
+
+  test("should return false when a key holds an undefined value", () => {
+    // The key still exists, so the object is not empty.
+    expect(
+      ObjectUtil.isEmpty({ a: undefined } as unknown as GlobalObject),
+    ).toBe(false);
+  });
+
+  test("should ignore inherited properties", () => {
+    const parent: GlobalObject = { inherited: true } as unknown as GlobalObject;
+    const child: GlobalObject = Object.create(parent) as GlobalObject;
+
+    expect(ObjectUtil.isEmpty(child)).toBe(true);
+  });
+
+  test("should treat an empty array as empty", () => {
+    expect(ObjectUtil.isEmpty([] as unknown as GlobalObject)).toBe(true);
+  });
+});

package/Tests/Utils/Slo/SloStatusColor.test.ts

@@ -0,0 +1,89 @@
+import { Gray500, Green, Red, Yellow } from "../../../Types/BrandColors";
+import Color from "../../../Types/Color";
+import SloStatus from "../../../Types/ServiceLevelObjective/SloStatus";
+import {
+  getSloStatusColor,
+  getSloStatusText,
+} from "../../../Utils/Slo/SloStatusColor";
+
+describe("SloStatusColor", () => {
+  describe("getSloStatusColor", () => {
+    it("colours a healthy SLO green", () => {
+      expect(getSloStatusColor(SloStatus.Healthy).toString()).toBe(
+        Green.toString(),
+      );
+    });
+
+    it("colours an at-risk SLO yellow", () => {
+      expect(getSloStatusColor(SloStatus.AtRisk).toString()).toBe(
+        Yellow.toString(),
+      );
+    });
+
+    it("colours an exhausted error budget red", () => {
+      expect(getSloStatusColor(SloStatus.BudgetExhausted).toString()).toBe(
+        Red.toString(),
+      );
+    });
+
+    it("colours a misconfigured SLO gray because there is nothing to measure", () => {
+      expect(getSloStatusColor(SloStatus.Misconfigured).toString()).toBe(
+        Gray500.toString(),
+      );
+    });
+
+    it("colours a paused SLO gray because it is deliberately not measured", () => {
+      expect(getSloStatusColor(SloStatus.Paused).toString()).toBe(
+        Gray500.toString(),
+      );
+    });
+
+    it("colours an unset status gray rather than claiming a health colour", () => {
+      expect(getSloStatusColor(undefined).toString()).toBe(Gray500.toString());
+      expect(getSloStatusColor(null).toString()).toBe(Gray500.toString());
+    });
+
+    it("colours an unrecognised persisted status gray", () => {
+      expect(getSloStatusColor("Something New" as SloStatus).toString()).toBe(
+        Gray500.toString(),
+      );
+    });
+
+    it("returns a colour for every member of the SloStatus enum", () => {
+      for (const status of Object.values(SloStatus)) {
+        const color: Color = getSloStatusColor(status);
+
+        expect(color).toBeInstanceOf(Color);
+        expect(color.toString()).toMatch(/^#[0-9a-fA-F]{6}$/);
+      }
+    });
+
+    it("only ever uses the four brand colours the SLO pages use", () => {
+      const allowed: Array<string> = [
+        Green.toString(),
+        Yellow.toString(),
+        Red.toString(),
+        Gray500.toString(),
+      ];
+
+      for (const status of Object.values(SloStatus)) {
+        expect(allowed).toContain(getSloStatusColor(status).toString());
+      }
+    });
+  });
+
+  describe("getSloStatusText", () => {
+    it.each(Object.values(SloStatus))(
+      "passes the %s status through unchanged",
+      (status: SloStatus) => {
+        expect(getSloStatusText(status)).toBe(status);
+      },
+    );
+
+    it("labels an unevaluated SLO Unknown rather than defaulting to Healthy", () => {
+      expect(getSloStatusText(undefined)).toBe("Unknown");
+      expect(getSloStatusText(null)).toBe("Unknown");
+      expect(getSloStatusText(undefined)).not.toBe(SloStatus.Healthy);
+    });
+  });
+});