@fitzzero/quickdraw-core 3.3.1 → 3.5.0

package/README.md

@@ -76,10 +76,10 @@ export default function RootLayout({ children }) {
 }
 
 // app/chat/page.tsx
-import { useService, useSubscription } from '@fitzzero/quickdraw-core/client';
+import { useService, useSubscription, useRoomEvents } from '@fitzzero/quickdraw-core/client';
 
 function ChatPage({ chatId }: { chatId: string }) {
-  // Subscribe to real-time updates
+  // Subscribe to real-time entity updates
   const { data: chat, isLoading } = useSubscription('chatService', chatId);
   
   // Mutation hook
@@ -87,6 +87,14 @@ function ChatPage({ chatId }: { chatId: string }) {
     onSuccess: () => console.log('Title updated!'),
   });
   
+  // Listen for custom events broadcast to the chat room
+  const [typing, setTyping] = useState(false);
+  useRoomEvents({
+    'chat:message': (msg) => appendMessage(msg),
+    'agent_typing_start': () => setTyping(true),
+    'agent_typing_stop': () => setTyping(false),
+  });
+  
   if (isLoading) return <div>Loading...</div>;
   
   return (
@@ -119,6 +127,46 @@ function ChatTitleEditor({ chat, updateChat }) {
 }
 ```
 
+### Custom Room Events
+
+When your server broadcasts custom events to subscription rooms via `emitToRoom`, use `useRoomEvents` on the client to listen with proper lifecycle management:
+
+```tsx
+import { useSubscription, useRoomEvents } from '@fitzzero/quickdraw-core/client';
+
+function ProjectBoard({ projectId }: { projectId: string }) {
+  const { data: project } = useSubscription('projectService', projectId);
+  const [tasks, setTasks] = useState<Task[]>([]);
+
+  // Lifecycle-managed event listeners — cleanup handled automatically
+  useRoomEvents({
+    'task:created': (task: Task) => setTasks(prev => [...prev, task]),
+    'task:deleted': ({ id }: { id: string }) => setTasks(prev => prev.filter(t => t.id !== id)),
+  });
+
+  return <Board tasks={tasks} />;
+}
+```
+
+### Auto-Invalidating Queries
+
+For list queries that should refresh when related events fire, use `invalidateOn`:
+
+```tsx
+import { useServiceQuery } from '@fitzzero/quickdraw-core/client';
+
+function TaskList({ projectId }: { projectId: string }) {
+  // Auto-refetches when tasks are created, deleted, or change status
+  const { data: tasks } = useServiceQuery('taskService', 'listTasks', { projectId }, {
+    invalidateOn: ['task:created', 'task:deleted', 'task:statusUpdate'],
+  });
+
+  return <ul>{tasks?.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+```
+
+Rapid-fire events within 100ms are debounced into a single refetch.
+
 ## Package Exports
 
 ```typescript
@@ -144,7 +192,9 @@ import {
   QuickdrawProvider,
   useQuickdrawSocket,
   useService,
+  useServiceQuery,
   useSubscription,
+  useRoomEvents,
   SocketCheckbox,
   SocketTextField,
   SocketSelect,

package/dist/client/index.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { a as QuickdrawProviderProps, Q as QuickdrawSocketContextValue, U as UseServiceOptions, b as UseServiceResult, c as UseServiceQueryOptions, d as UseServiceQueryResult, e as UseSubscriptionOptions, f as UseSubscriptionResult } from '../types-Cr8YC7Kg.js';
-export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-Cr8YC7Kg.js';
+import { a as QuickdrawProviderProps, Q as QuickdrawSocketContextValue, U as UseServiceOptions, b as UseServiceResult, c as UseServiceQueryOptions, d as UseServiceQueryResult, e as UseSubscriptionOptions, f as UseSubscriptionResult, g as UseRoomEventsOptions } from '../types-BJj94_XW.js';
+export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-BJj94_XW.js';
 import 'socket.io-client';
 import '@tanstack/react-query';
 import '../shared/index.js';
@@ -171,6 +171,42 @@ declare function useSubscription<TData extends {
     id: string;
 }>(serviceName: string, entryId: string | null, options?: UseSubscriptionOptions<TData>): UseSubscriptionResult<TData>;
 
+/**
+ * Hook for listening to custom socket events with managed lifecycle.
+ *
+ * Handles `socket.on`/`socket.off` cleanup, reconnection re-attachment,
+ * and connection-awareness. Each component gets its own listeners (no dedup needed).
+ * Room scoping is handled server-side via `emitToRoom`.
+ *
+ * Pair with `useSubscription` to ensure the socket is in the correct room:
+ * `useSubscription` manages room membership, `useRoomEvents` manages event listeners.
+ *
+ * @param handlers - Map of event names to handler functions. Event names should be
+ *   stable (don't change between renders). Handler functions can change freely.
+ * @param options - Optional configuration
+ *
+ * @example
+ * ```tsx
+ * function ChatView({ chatId }: { chatId: string }) {
+ *   const [messages, setMessages] = useState<Message[]>([]);
+ *   const [typing, setTyping] = useState(false);
+ *
+ *   // Subscribe to the chat room (manages room membership)
+ *   const { data: chat } = useSubscription('chatService', chatId);
+ *
+ *   // Listen for custom events broadcast to the chat room
+ *   useRoomEvents({
+ *     'chat:message': (msg: Message) => setMessages(prev => [...prev, msg]),
+ *     'agent_typing_start': () => setTyping(true),
+ *     'agent_typing_stop': () => setTyping(false),
+ *   });
+ *
+ *   return <div>{chat?.title}</div>;
+ * }
+ * ```
+ */
+declare function useRoomEvents(handlers: Record<string, (data: never) => void>, options?: UseRoomEventsOptions): void;
+
 type CommitMode = "change" | "blur" | "debounce";
 interface UseSocketInputOptions<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> {
     /**
@@ -481,4 +517,4 @@ declare function buildBreadcrumbs(pathname: string, navigation: NavItem[]): Brea
  */
 declare function routeRequiresAuth(pathname: string, navigation: NavItem[], userMenuItems?: NavItem[]): boolean;
 
-export { type BreadcrumbItem, type CommitMode, type JWTPayload, type NavItem, QuickdrawProvider, QuickdrawProviderProps, QuickdrawSocketContextValue, SocketCheckbox, type SocketCheckboxProps, SocketSelect, type SocketSelectProps, SocketSlider, type SocketSliderProps, SocketSwitch, type SocketSwitchProps, SocketTextField, type SocketTextFieldProps, UseServiceOptions, UseServiceQueryOptions, UseServiceQueryResult, UseServiceResult, type UseSocketInputOptions, type UseSocketInputResult, UseSubscriptionOptions, UseSubscriptionResult, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useQuickdrawSocket, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
+export { type BreadcrumbItem, type CommitMode, type JWTPayload, type NavItem, QuickdrawProvider, QuickdrawProviderProps, QuickdrawSocketContextValue, SocketCheckbox, type SocketCheckboxProps, SocketSelect, type SocketSelectProps, SocketSlider, type SocketSliderProps, SocketSwitch, type SocketSwitchProps, SocketTextField, type SocketTextFieldProps, UseRoomEventsOptions, UseServiceOptions, UseServiceQueryOptions, UseServiceQueryResult, UseServiceResult, type UseSocketInputOptions, type UseSocketInputResult, UseSubscriptionOptions, UseSubscriptionResult, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };

package/dist/client/index.js

@@ -386,7 +386,8 @@ function useServiceQuery(serviceName, methodName, payload, options) {
     skipCache = false,
     timeout = 1e4,
     retry = 1,
-    retryDelay
+    retryDelay,
+    invalidateOn
   } = options ?? {};
   const queryKey = React.useMemo(
     () => [serviceName, methodName, JSON.stringify(payload)],
@@ -420,6 +421,34 @@ function useServiceQuery(serviceName, methodName, payload, options) {
       queryClient.invalidateQueries({ queryKey });
     }
   }, [skipCache, enabled, queryClient, queryKey]);
+  const invalidateOnKey = invalidateOn?.join("\0");
+  const stableInvalidateOn = React.useMemo(
+    () => invalidateOn,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [invalidateOnKey]
+  );
+  React.useEffect(() => {
+    if (!socket || !isConnected || !stableInvalidateOn?.length || !enabled) {
+      return;
+    }
+    let debounceTimer = null;
+    const handleInvalidate = () => {
+      if (debounceTimer) return;
+      debounceTimer = setTimeout(() => {
+        debounceTimer = null;
+        queryClient.invalidateQueries({ queryKey });
+      }, 100);
+    };
+    for (const eventName of stableInvalidateOn) {
+      socket.on(eventName, handleInvalidate);
+    }
+    return () => {
+      if (debounceTimer) clearTimeout(debounceTimer);
+      for (const eventName of stableInvalidateOn) {
+        socket.off(eventName, handleInvalidate);
+      }
+    };
+  }, [socket, isConnected, stableInvalidateOn, enabled, queryClient, queryKey]);
   const query = useQuery({
     queryKey,
     queryFn,
@@ -607,6 +636,39 @@ function useSubscription(serviceName, entryId, options = {}) {
     unsubscribe
   };
 }
+function useRoomEvents(handlers, options) {
+  const { socket, isConnected } = useQuickdrawSocket();
+  const { enabled = true } = options ?? {};
+  const handlersRef = React.useRef(handlers);
+  React.useEffect(() => {
+    handlersRef.current = handlers;
+  }, [handlers]);
+  const eventNames = Object.keys(handlers);
+  const eventNamesKey = eventNames.join("\0");
+  const stableEventNames = React.useMemo(
+    () => eventNames,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [eventNamesKey]
+  );
+  React.useEffect(() => {
+    if (!socket || !isConnected || !enabled || stableEventNames.length === 0) {
+      return;
+    }
+    const wrappers = /* @__PURE__ */ new Map();
+    for (const eventName of stableEventNames) {
+      const wrapper = (...args) => {
+        handlersRef.current[eventName]?.(...args);
+      };
+      wrappers.set(eventName, wrapper);
+      socket.on(eventName, wrapper);
+    }
+    return () => {
+      for (const [eventName, wrapper] of wrappers) {
+        socket.off(eventName, wrapper);
+      }
+    };
+  }, [socket, isConnected, enabled, stableEventNames]);
+}
 function useSocketInput(options) {
   const {
     state,
@@ -1137,6 +1199,6 @@ function routeRequiresAuth(pathname, navigation, userMenuItems) {
   return false;
 }
 
-export { QuickdrawProvider, SocketCheckbox, SocketSelect, SocketSlider, SocketSwitch, SocketTextField, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useQuickdrawSocket, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
+export { QuickdrawProvider, SocketCheckbox, SocketSelect, SocketSlider, SocketSwitch, SocketTextField, buildBreadcrumbs, clearAuthToken, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map