@checkstack/signal-common 0.1.10 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @checkstack/signal-common
 
+## 0.2.0
+
+### Minor Changes
+
+- 208ad71: Centralize realtime cache invalidation: signals now carry their owning `pluginId` end-to-end, and a single `SignalAutoInvalidator` mounted near the React Query client invalidates `[[pluginId]]` for every incoming signal automatically.
+
+  **Breaking change to `createSignal`** (`@checkstack/signal-common`): the factory now takes a single object argument with `pluginMetadata`, `event`, and `payloadSchema`. The signal id is constructed as `${pluginMetadata.pluginId}.${event}` and the resulting `Signal` carries a `pluginId` field. The `SignalMessage` wire envelope and `ServerToClientMessage` `signal` variant gained a `pluginId` field so the frontend can route invalidations without parsing the id.
+
+  ```ts
+  // Before
+  export const ANOMALY_STATE_CHANGED = createSignal(
+    "anomaly.state_changed",
+    z.object({ ... }),
+  );
+
+  // After
+  export const ANOMALY_STATE_CHANGED = createSignal({
+    pluginMetadata,
+    event: "state_changed",
+    payloadSchema: z.object({ ... }),
+  });
+  ```
+
+  **New plugin field**: `FrontendPlugin.foreignSignals?: Signal<unknown>[]` lets a plugin opt its `[[pluginId]]` cache into invalidation when another plugin's signal fires (e.g. `dependency-frontend` declares `[SYSTEM_STATUS_CHANGED]` because dependency payloads embed system status). Same-plugin signals must NOT be listed — they are always auto-invalidated.
+
+  **Removed boilerplate**: per-component `useSignal(X, () => refetch())` and `useSignal(X, () => queryClient.invalidateQueries(...))` calls have been removed across `incident-frontend`, `maintenance-frontend`, `healthcheck-frontend`, `slo-frontend`, `dependency-frontend`, `satellite-frontend`, `announcement-frontend`, `notification-frontend`, and `dashboard-frontend`. The `NotificationBell` unread count is now derived directly from the `getUnreadCount` query (auto-invalidated) instead of a local state mirror.
+
+  **User-visible bug fix**: the system detail page anomaly widget (`SystemAnomalyWidget`) now updates in real-time when anomalies change, with no per-widget signal subscription required. The dashboard status page also stays fresh on `ANOMALY_STATE_CHANGED`, `ANOMALY_BASELINE_UPDATED`, and `ANOMALY_TREND_DETECTED`.
+
+  UI-state consumers that legitimately need a `useSignal` (the dashboard activity terminal, the queue lag alert, and the rolling-preset date refresh in `useHealthCheckData`) keep their handlers; the auto-invalidator runs alongside them.
+
 ## 0.1.10
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/signal-common",
-  "version": "0.1.10",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -8,7 +8,7 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.6.5",
+    "@checkstack/common": "0.7.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/src/index.test.ts

@@ -1,162 +1,132 @@
 import { describe, it, expect } from "bun:test";
 import { createSignal, type Signal, type SignalMessage } from "../src/index";
 import { z } from "zod";
+import type { PluginMetadata } from "@checkstack/common";
+
+const testPlugin: PluginMetadata = { pluginId: "notification" };
+const otherPlugin: PluginMetadata = { pluginId: "system" };
 
 describe("createSignal", () => {
-  it("should create a signal with the given id and schema", () => {
+  it("constructs id as `${pluginId}.${event}` and stores pluginId", () => {
     const schema = z.object({ message: z.string() });
-    const signal = createSignal("test.signal", schema);
+    const signal = createSignal({
+      pluginMetadata: testPlugin,
+      event: "test",
+      payloadSchema: schema,
+    });
 
-    expect(signal.id).toBe("test.signal");
+    expect(signal.id).toBe("notification.test");
+    expect(signal.pluginId).toBe("notification");
     expect(signal.payloadSchema).toBe(schema);
   });
 
-  it("should create signals with different payload types", () => {
-    const stringSignal = createSignal("string.signal", z.string());
-    const numberSignal = createSignal("number.signal", z.number());
-    const objectSignal = createSignal(
-      "object.signal",
-      z.object({
-        id: z.string(),
-        count: z.number(),
-        active: z.boolean(),
-      })
-    );
-
-    expect(stringSignal.id).toBe("string.signal");
-    expect(numberSignal.id).toBe("number.signal");
-    expect(objectSignal.id).toBe("object.signal");
+  it("creates signals with different payload types and pluginIds", () => {
+    const stringSignal = createSignal({
+      pluginMetadata: testPlugin,
+      event: "string",
+      payloadSchema: z.string(),
+    });
+    const numberSignal = createSignal({
+      pluginMetadata: otherPlugin,
+      event: "number",
+      payloadSchema: z.number(),
+    });
+
+    expect(stringSignal.id).toBe("notification.string");
+    expect(stringSignal.pluginId).toBe("notification");
+    expect(numberSignal.id).toBe("system.number");
+    expect(numberSignal.pluginId).toBe("system");
   });
 
-  it("should validate payload against schema", () => {
-    const signal = createSignal(
-      "notification.received",
-      z.object({
+  it("validates payload against schema", () => {
+    const signal = createSignal({
+      pluginMetadata: testPlugin,
+      event: "received",
+      payloadSchema: z.object({
         id: z.string(),
         title: z.string(),
         importance: z.enum(["info", "warning", "critical"]),
-      })
-    );
+      }),
+    });
 
-    // Valid payload
-    const validPayload = {
+    const validResult = signal.payloadSchema.safeParse({
       id: "n-123",
-      title: "Test Notification",
+      title: "Test",
       importance: "info" as const,
-    };
-    const validResult = signal.payloadSchema.safeParse(validPayload);
+    });
     expect(validResult.success).toBe(true);
 
-    // Invalid payload - missing required field
-    const invalidPayload = {
+    const invalidResult = signal.payloadSchema.safeParse({
       id: "n-123",
       title: "Test",
-    };
-    const invalidResult = signal.payloadSchema.safeParse(invalidPayload);
+    });
     expect(invalidResult.success).toBe(false);
-
-    // Invalid payload - wrong enum value
-    const wrongEnumPayload = {
-      id: "n-123",
-      title: "Test",
-      importance: "urgent",
-    };
-    const wrongEnumResult = signal.payloadSchema.safeParse(wrongEnumPayload);
-    expect(wrongEnumResult.success).toBe(false);
   });
 
-  it("should support nested object schemas", () => {
-    const signal = createSignal(
-      "complex.signal",
-      z.object({
-        user: z.object({
-          id: z.string(),
-          name: z.string(),
-        }),
-        metadata: z.record(z.string(), z.string()),
-        tags: z.array(z.string()),
-      })
-    );
-
-    const payload = {
-      user: { id: "u-1", name: "Test User" },
-      metadata: { source: "api" },
-      tags: ["important", "system"],
-    };
-
-    const result = signal.payloadSchema.safeParse(payload);
-    expect(result.success).toBe(true);
-  });
-
-  it("should support optional fields in schema", () => {
-    const signal = createSignal(
-      "optional.signal",
-      z.object({
-        required: z.string(),
-        optional: z.string().optional(),
-      })
-    );
-
-    // With optional field
-    const withOptional = signal.payloadSchema.safeParse({
-      required: "value",
-      optional: "optional value",
+  it("supports multi-segment event names", () => {
+    const signal = createSignal({
+      pluginMetadata: { pluginId: "healthcheck" },
+      event: "system.status_changed",
+      payloadSchema: z.object({ systemId: z.string() }),
     });
-    expect(withOptional.success).toBe(true);
 
-    // Without optional field
-    const withoutOptional = signal.payloadSchema.safeParse({
-      required: "value",
-    });
-    expect(withoutOptional.success).toBe(true);
+    expect(signal.id).toBe("healthcheck.system.status_changed");
+    expect(signal.pluginId).toBe("healthcheck");
   });
 });
 
 describe("Signal type inference", () => {
-  it("should correctly infer payload type from schema", () => {
-    const signal = createSignal(
-      "typed.signal",
-      z.object({
-        count: z.number(),
-        name: z.string(),
-      })
-    );
-
-    // TypeScript should infer that payload is { count: number, name: string }
-    type InferredPayload = z.infer<typeof signal.payloadSchema>;
-
-    // This test ensures the types compile correctly
-    const payload: InferredPayload = { count: 42, name: "test" };
+  it("infers payload type from schema", () => {
+    const signal = createSignal({
+      pluginMetadata: testPlugin,
+      event: "typed",
+      payloadSchema: z.object({ count: z.number(), name: z.string() }),
+    });
+
+    type Inferred = z.infer<typeof signal.payloadSchema>;
+    const payload: Inferred = { count: 42, name: "test" };
     expect(payload.count).toBe(42);
-    expect(payload.name).toBe("test");
   });
 });
 
-describe("SignalMessage structure", () => {
-  it("should have correct message envelope structure", () => {
+describe("SignalMessage envelope", () => {
+  it("carries signalId, pluginId, payload, and timestamp", () => {
     const message: SignalMessage<{ text: string }> = {
-      signalId: "test.message",
+      signalId: "notification.test",
+      pluginId: "notification",
       payload: { text: "Hello" },
       timestamp: new Date().toISOString(),
     };
 
-    expect(message.signalId).toBe("test.message");
+    expect(message.signalId).toBe("notification.test");
+    expect(message.pluginId).toBe("notification");
     expect(message.payload.text).toBe("Hello");
     expect(typeof message.timestamp).toBe("string");
   });
 });
 
 describe("Signal ID conventions", () => {
-  it("should follow dot-notation naming convention", () => {
-    const signals = [
-      createSignal("notification.received", z.string()),
-      createSignal("notification.read", z.string()),
-      createSignal("system.maintenance.scheduled", z.string()),
-      createSignal("healthcheck.status.changed", z.string()),
+  it("follows dot-notation naming convention", () => {
+    const signals: Signal<unknown>[] = [
+      createSignal({
+        pluginMetadata: { pluginId: "notification" },
+        event: "received",
+        payloadSchema: z.string(),
+      }),
+      createSignal({
+        pluginMetadata: { pluginId: "notification" },
+        event: "read",
+        payloadSchema: z.string(),
+      }),
+      createSignal({
+        pluginMetadata: { pluginId: "system" },
+        event: "maintenance.scheduled",
+        payloadSchema: z.string(),
+      }),
     ];
 
     for (const signal of signals) {
-      expect(signal.id).toMatch(/^[a-z]+(\.[a-z]+)+$/);
+      expect(signal.id).toMatch(/^[a-z]+(\.[a-z_]+)+$/);
     }
   });
 });

package/src/index.ts

@@ -7,29 +7,44 @@ import type { AccessRule, PluginMetadata } from "@checkstack/common";
 
 /**
  * A Signal is a typed event that can be broadcast from backend to frontend.
- * Similar to the Hook pattern but for realtime WebSocket communication.
+ * The `pluginId` field lets the realtime layer auto-invalidate
+ * react-query caches keyed `[[pluginId]]` without per-consumer wiring.
  */
 export interface Signal<T = unknown> {
   id: string;
+  pluginId: string;
   payloadSchema: z.ZodType<T>;
 }
 
 /**
  * Factory function for creating type-safe signals.
  *
+ * The signal id is constructed as `${pluginMetadata.pluginId}.${event}`
+ * so the owning plugin is encoded into the wire format and the frontend
+ * can route invalidations to `[[pluginId]]` automatically.
+ *
  * @example
  * ```typescript
- * const NOTIFICATION_RECEIVED = createSignal(
- *   "notification.received",
- *   z.object({ id: z.string(), title: z.string() })
- * );
+ * import { pluginMetadata } from "./plugin-metadata";
+ *
+ * export const NOTIFICATION_RECEIVED = createSignal({
+ *   pluginMetadata,
+ *   event: "received",
+ *   payloadSchema: z.object({ id: z.string(), title: z.string() }),
+ * });
  * ```
  */
-export function createSignal<T>(
-  id: string,
-  payloadSchema: z.ZodType<T>
-): Signal<T> {
-  return { id, payloadSchema };
+export function createSignal<T>(props: {
+  pluginMetadata: PluginMetadata;
+  event: string;
+  payloadSchema: z.ZodType<T>;
+}): Signal<T> {
+  const { pluginMetadata, event, payloadSchema } = props;
+  return {
+    id: `${pluginMetadata.pluginId}.${event}`,
+    pluginId: pluginMetadata.pluginId,
+    payloadSchema,
+  };
 }
 
 // =============================================================================
@@ -38,9 +53,13 @@ export function createSignal<T>(
 
 /**
  * The message envelope sent over WebSocket containing a signal payload.
+ *
+ * `pluginId` is carried alongside `signalId` so the frontend can route
+ * cache invalidations to `[[pluginId]]` without parsing the id.
  */
 export interface SignalMessage<T = unknown> {
   signalId: string;
+  pluginId: string;
   payload: T;
   timestamp: string;
 }
@@ -71,7 +90,13 @@ export type ClientToServerMessage = { type: "ping" };
 export type ServerToClientMessage =
   | { type: "pong" }
   | { type: "connected"; userId: string }
-  | { type: "signal"; signalId: string; payload: unknown; timestamp: string }
+  | {
+      type: "signal";
+      signalId: string;
+      pluginId: string;
+      payload: unknown;
+      timestamp: string;
+    }
   | { type: "error"; message: string };
 
 // =============================================================================
@@ -156,24 +181,33 @@ export interface SignalService {
 // CORE PLUGIN LIFECYCLE SIGNALS
 // =============================================================================
 
+/**
+ * Synthetic metadata for framework-level signals that are not owned by any plugin.
+ * The "core" pluginId reserves a top-level namespace; no plugin may register itself
+ * with that id.
+ */
+const coreSignalsPluginMetadata: PluginMetadata = { pluginId: "core" };
+
 /**
  * Broadcast to all frontends when a plugin has been fully installed on the backend.
  * Frontends should dynamically load the plugin's UI assets.
  */
-export const PLUGIN_INSTALLED = createSignal(
-  "core.plugin.installed",
-  z.object({
+export const PLUGIN_INSTALLED = createSignal({
+  pluginMetadata: coreSignalsPluginMetadata,
+  event: "plugin.installed",
+  payloadSchema: z.object({
     pluginId: z.string(),
-  })
-);
+  }),
+});
 
 /**
  * Broadcast to all frontends when a plugin has been deregistered from the backend.
  * Frontends should remove the plugin's extensions and routes.
  */
-export const PLUGIN_DEREGISTERED = createSignal(
-  "core.plugin.deregistered",
-  z.object({
+export const PLUGIN_DEREGISTERED = createSignal({
+  pluginMetadata: coreSignalsPluginMetadata,
+  event: "plugin.deregistered",
+  payloadSchema: z.object({
     pluginId: z.string(),
-  })
-);
+  }),
+});