@checkstack/queue-common 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # @checkstack/queue-common
 
+## 0.2.0
+
+### Minor Changes
+
+- 180be38: # Queue Lag Warning
+
+  Added a queue lag warning system that displays alerts when pending jobs exceed configurable thresholds.
+
+  ## Features
+
+  - **Backend Stats API**: New `getStats`, `getLagStatus`, and `updateLagThresholds` RPC endpoints
+  - **Signal-based Updates**: `QUEUE_LAG_CHANGED` signal for real-time frontend updates
+  - **Aggregated Stats**: `QueueManager.getAggregatedStats()` sums stats across all queues
+  - **Configurable Thresholds**: Warning (default 100) and Critical (default 500) thresholds stored in config
+  - **Dashboard Integration**: Queue lag alert displayed on main Dashboard (access-gated)
+  - **Queue Settings Page**: Lag alert and Performance Tuning guidance card with concurrency tips
+
+  ## UI Changes
+
+  - Queue lag alert banner appears on Dashboard and Queue Settings when pending jobs exceed thresholds
+  - New "Performance Tuning" card with concurrency settings guidance and bottleneck indicators
+
+- 7a23261: ## TanStack Query Integration
+
+  Migrated all frontend components to use `usePluginClient` hook with TanStack Query integration, replacing the legacy `forPlugin()` pattern.
+
+  ### New Features
+
+  - **`usePluginClient` hook**: Provides type-safe access to plugin APIs with `.useQuery()` and `.useMutation()` methods
+  - **Automatic request deduplication**: Multiple components requesting the same data share a single network request
+  - **Built-in caching**: Configurable stale time and cache duration per query
+  - **Loading/error states**: TanStack Query provides `isLoading`, `error`, `isRefetching` states automatically
+  - **Background refetching**: Stale data is automatically refreshed when components mount
+
+  ### Contract Changes
+
+  All RPC contracts now require `operationType: "query"` or `operationType: "mutation"` metadata:
+
+  ```typescript
+  const getItems = proc()
+    .meta({ operationType: "query", access: [access.read] })
+    .output(z.array(itemSchema))
+    .query();
+
+  const createItem = proc()
+    .meta({ operationType: "mutation", access: [access.manage] })
+    .input(createItemSchema)
+    .output(itemSchema)
+    .mutation();
+  ```
+
+  ### Migration
+
+  ```typescript
+  // Before (forPlugin pattern)
+  const api = useApi(myPluginApiRef);
+  const [items, setItems] = useState<Item[]>([]);
+  useEffect(() => {
+    api.getItems().then(setItems);
+  }, [api]);
+
+  // After (usePluginClient pattern)
+  const client = usePluginClient(MyPluginApi);
+  const { data: items, isLoading } = client.getItems.useQuery({});
+  ```
+
+  ### Bug Fixes
+
+  - Fixed `rpc.test.ts` test setup for middleware type inference
+  - Fixed `SearchDialog` to use `setQuery` instead of deprecated `search` method
+  - Fixed null→undefined warnings in notification and queue frontends
+
+### Patch Changes
+
+- Updated dependencies [7a23261]
+  - @checkstack/common@0.3.0
+  - @checkstack/signal-common@0.1.1
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/queue-common",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -14,6 +14,7 @@
   },
   "dependencies": {
     "@checkstack/common": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
     "@orpc/contract": "^1.13.2",
     "zod": "^4.0.0"
   },

package/src/index.ts

@@ -3,3 +3,4 @@ export * from "./access";
 export { queueContract, QueueApi, type QueueContract } from "./rpc-contract";
 export * from "./plugin-metadata";
 export { queueRoutes } from "./routes";
+export * from "./signals";

package/src/rpc-contract.ts

@@ -1,8 +1,4 @@
-import { oc } from "@orpc/contract";
-import {
-  createClientDefinition,
-  type ProcedureMetadata,
-} from "@checkstack/common";
+import { createClientDefinition, proc } from "@checkstack/common";
 import { z } from "zod";
 import { queueAccess } from "./access";
 import { pluginMetadata } from "./plugin-metadata";
@@ -10,36 +6,57 @@ import {
   QueuePluginDtoSchema,
   QueueConfigurationDtoSchema,
   UpdateQueueConfigurationSchema,
+  QueueStatsDtoSchema,
+  QueueLagStatusSchema,
+  QueueLagThresholdsSchema,
 } from "./schemas";
 
-// Base builder with metadata support
-const _base = oc.$meta<ProcedureMetadata>({});
-
 // Queue RPC Contract with access metadata
 export const queueContract = {
   // Queue plugin queries - Read access
-  getPlugins: _base
-    .meta({
-      userType: "authenticated",
-      access: [queueAccess.settings.read],
-    })
-    .output(z.array(QueuePluginDtoSchema)),
-
-  getConfiguration: _base
-    .meta({
-      userType: "authenticated",
-      access: [queueAccess.settings.read],
-    })
-    .output(QueueConfigurationDtoSchema),
+  getPlugins: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [queueAccess.settings.read],
+  }).output(z.array(QueuePluginDtoSchema)),
+
+  getConfiguration: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [queueAccess.settings.read],
+  }).output(QueueConfigurationDtoSchema),
 
   // Queue configuration updates - Manage access
-  updateConfiguration: _base
-    .meta({
-      userType: "authenticated",
-      access: [queueAccess.settings.manage],
-    })
+  updateConfiguration: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [queueAccess.settings.manage],
+  })
     .input(UpdateQueueConfigurationSchema)
     .output(QueueConfigurationDtoSchema),
+
+  // Queue statistics - Read access
+  getStats: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [queueAccess.settings.read],
+  }).output(QueueStatsDtoSchema),
+
+  // Queue lag status (includes thresholds) - Read access
+  getLagStatus: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [queueAccess.settings.read],
+  }).output(QueueLagStatusSchema),
+
+  // Update lag thresholds - Manage access
+  updateLagThresholds: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [queueAccess.settings.manage],
+  })
+    .input(QueueLagThresholdsSchema)
+    .output(QueueLagThresholdsSchema),
 };
 
 // Export contract type

package/src/schemas.ts

@@ -36,3 +36,50 @@ export const UpdateQueueConfigurationSchema = z.object({
 export type UpdateQueueConfiguration = z.infer<
   typeof UpdateQueueConfigurationSchema
 >;
+
+/**
+ * Queue statistics DTO
+ */
+export const QueueStatsDtoSchema = z.object({
+  pending: z.number(),
+  processing: z.number(),
+  completed: z.number(),
+  failed: z.number(),
+});
+
+export type QueueStatsDto = z.infer<typeof QueueStatsDtoSchema>;
+
+/**
+ * Lag severity levels
+ */
+export const LagSeveritySchema = z.enum(["none", "warning", "critical"]);
+export type LagSeverity = z.infer<typeof LagSeveritySchema>;
+
+/**
+ * Queue lag thresholds configuration
+ */
+export const QueueLagThresholdsSchema = z.object({
+  warningThreshold: z
+    .number()
+    .min(1)
+    .default(100)
+    .describe("Pending job count to trigger warning"),
+  criticalThreshold: z
+    .number()
+    .min(1)
+    .default(500)
+    .describe("Pending job count to trigger critical alert"),
+});
+
+export type QueueLagThresholds = z.infer<typeof QueueLagThresholdsSchema>;
+
+/**
+ * Queue lag status response
+ */
+export const QueueLagStatusSchema = z.object({
+  pending: z.number(),
+  severity: LagSeveritySchema,
+  thresholds: QueueLagThresholdsSchema,
+});
+
+export type QueueLagStatus = z.infer<typeof QueueLagStatusSchema>;

package/src/signals.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { createSignal } from "@checkstack/signal-common";
+import { LagSeveritySchema } from "./schemas";
+
+/**
+ * Signal broadcast when queue lag status changes.
+ * Frontend listens to update lag warning UI in real-time.
+ */
+export const QUEUE_LAG_CHANGED = createSignal(
+  "queue.lag.changed",
+  z.object({
+    pending: z.number(),
+    severity: LagSeveritySchema,
+  })
+);