@fitzzero/quickdraw-core 3.3.1 → 3.5.0

package/dist/{types-Cr8YC7Kg.d.ts → types-BJj94_XW.d.ts}

@@ -93,6 +93,16 @@ interface UseSubscriptionResult<TData> {
     subscribe: () => void;
     unsubscribe: () => void;
 }
+/**
+ * Options for the useRoomEvents hook.
+ */
+interface UseRoomEventsOptions {
+    /**
+     * Whether to listen for events (default: true).
+     * Set to false to temporarily disable all listeners.
+     */
+    enabled?: boolean;
+}
 /**
  * Options for the useServiceQuery hook.
  */
@@ -145,6 +155,22 @@ interface UseServiceQueryOptions<TResponse> {
      * Delay between retries in milliseconds
      */
     retryDelay?: number;
+    /**
+     * Socket event names that should trigger an automatic refetch.
+     * When any of these events fire on the socket, the query is refetched.
+     * Useful for keeping list queries in sync with real-time changes.
+     *
+     * Rapid-fire events within the same 100ms window are debounced into a single refetch.
+     *
+     * @example
+     * ```tsx
+     * // Refetch the task list when tasks are created, deleted, or change status
+     * useServiceQuery("taskService", "listTasks", { projectId }, {
+     *   invalidateOn: ["task:created", "task:deleted", "task:statusUpdate"],
+     * });
+     * ```
+     */
+    invalidateOn?: string[];
 }
 /**
  * Return type for the useServiceQuery hook.
@@ -259,4 +285,4 @@ interface QuickdrawSocketContextValue {
     subscriptionBatcher: SubscriptionBatcher;
 }
 
-export type { ClientServiceMethodMap as C, QuickdrawSocketContextValue as Q, SubscriptionDataMap as S, UseServiceOptions as U, QuickdrawProviderProps as a, UseServiceResult as b, UseServiceQueryOptions as c, UseServiceQueryResult as d, UseSubscriptionOptions as e, UseSubscriptionResult as f };
+export type { ClientServiceMethodMap as C, QuickdrawSocketContextValue as Q, SubscriptionDataMap as S, UseServiceOptions as U, QuickdrawProviderProps as a, UseServiceResult as b, UseServiceQueryOptions as c, UseServiceQueryResult as d, UseSubscriptionOptions as e, UseSubscriptionResult as f, UseRoomEventsOptions as g };

package/eslint-config/index.mjs

@@ -127,6 +127,7 @@ export const client = [
   ...nextVitals,
   ...base,
   {
+    plugins: { quickdraw: quickdrawPlugin },
     rules: {
       "react/react-in-jsx-scope": "off",
       "react/prop-types": "off",
@@ -144,6 +145,9 @@ export const client = [
       "@typescript-eslint/no-unsafe-argument": "warn",
       "@typescript-eslint/no-redundant-type-constituents": "off",
       "@typescript-eslint/no-unnecessary-type-arguments": "off",
+
+      "quickdraw/no-raw-socket-on": "warn",
+      "quickdraw/no-raw-socket-emit": "warn",
     },
   },
 ];

package/eslint-plugin-quickdraw/index.mjs

@@ -2,6 +2,8 @@ import noCrossServiceMutations from "./rules/no-cross-service-mutations.mjs"
 import requireZodSchema from "./rules/require-zod-schema.mjs"
 import noServiceMethodRecord from "./rules/no-service-method-record.mjs"
 import noUnsafePayloadCast from "./rules/no-unsafe-payload-cast.mjs"
+import noRawSocketOn from "./rules/no-raw-socket-on.mjs"
+import noRawSocketEmit from "./rules/no-raw-socket-emit.mjs"
 
 /** @type {import('eslint').ESLint.Plugin} */
 export default {
@@ -10,5 +12,7 @@ export default {
     "require-zod-schema": requireZodSchema,
     "no-service-method-record": noServiceMethodRecord,
     "no-unsafe-payload-cast": noUnsafePayloadCast,
+    "no-raw-socket-on": noRawSocketOn,
+    "no-raw-socket-emit": noRawSocketEmit,
   },
 }

package/eslint-plugin-quickdraw/rules/no-raw-socket-emit.mjs

@@ -0,0 +1,95 @@
+/**
+ * Allowed event name prefixes that are exempt from this rule.
+ * These are documented exceptions for protocols that don't map to BaseService.
+ */
+const DEFAULT_ALLOWED_PREFIXES = ["agentRunner:", "projectRunner:"]
+
+/**
+ * Allowed exact event names that are exempt from this rule.
+ */
+const DEFAULT_ALLOWED_EVENTS = new Set(["subscribe", "unsubscribe"])
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow raw socket.emit() in components. " +
+        "Use useService() for mutations, useServiceQuery() for reads, " +
+        "or useSubscription() for entity subscriptions.",
+    },
+    messages: {
+      noRawSocketEmit:
+        "Avoid raw socket.emit('{{ eventName }}'). " +
+        "Use useService() for mutations or useServiceQuery() for reads.",
+      noRawSocketEmitDynamic:
+        "Avoid raw socket.emit() with dynamic event names. " +
+        "Use useService() for mutations or useServiceQuery() for reads.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          allowedPrefixes: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Event name prefixes that are exempt from this rule " +
+              '(e.g. ["agentRunner:", "projectRunner:"])',
+          },
+          allowedEvents: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Exact event names that are exempt from this rule " +
+              '(e.g. ["subscribe", "unsubscribe"])',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const options = context.options[0] || {}
+    const allowedPrefixes = options.allowedPrefixes || DEFAULT_ALLOWED_PREFIXES
+    const allowedEvents = new Set(
+      options.allowedEvents || DEFAULT_ALLOWED_EVENTS
+    )
+
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "MemberExpression") return
+        if (callee.property.type !== "Identifier") return
+        if (callee.property.name !== "emit") return
+
+        const obj = callee.object
+        if (obj.type !== "Identifier" || obj.name !== "socket") return
+
+        const eventArg = node.arguments[0]
+        if (!eventArg) return
+
+        if (eventArg.type === "Literal" && typeof eventArg.value === "string") {
+          const eventName = eventArg.value
+
+          if (allowedEvents.has(eventName)) return
+          if (allowedPrefixes.some((prefix) => eventName.startsWith(prefix))) {
+            return
+          }
+
+          context.report({
+            node,
+            messageId: "noRawSocketEmit",
+            data: { eventName },
+          })
+        } else {
+          context.report({
+            node,
+            messageId: "noRawSocketEmitDynamic",
+          })
+        }
+      },
+    }
+  },
+}

package/eslint-plugin-quickdraw/rules/no-raw-socket-on.mjs

@@ -0,0 +1,79 @@
+/**
+ * Allowed event name prefixes that are exempt from this rule.
+ * These are documented exceptions for protocols that don't map to BaseService.
+ */
+const DEFAULT_ALLOWED_PREFIXES = ["agentRunner:", "projectRunner:"]
+
+/** @type {import('eslint').Rule.RuleModule} */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow raw socket.on() in components. " +
+        "Use useRoomEvents() for custom event listeners or useSubscription() for entity updates.",
+    },
+    messages: {
+      noRawSocketOn:
+        "Avoid raw socket.on('{{ eventName }}'). " +
+        "Use useRoomEvents({ '{{ eventName }}': handler }) for lifecycle-managed event listeners, " +
+        "or useSubscription() for entity data.",
+      noRawSocketOnDynamic:
+        "Avoid raw socket.on() with dynamic event names. " +
+        "Use useRoomEvents() for lifecycle-managed event listeners.",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          allowedPrefixes: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Event name prefixes that are exempt from this rule " +
+              '(e.g. ["agentRunner:", "projectRunner:"])',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    const options = context.options[0] || {}
+    const allowedPrefixes = options.allowedPrefixes || DEFAULT_ALLOWED_PREFIXES
+
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+        if (callee.type !== "MemberExpression") return
+        if (callee.property.type !== "Identifier") return
+        if (callee.property.name !== "on") return
+
+        const obj = callee.object
+        if (obj.type !== "Identifier" || obj.name !== "socket") return
+
+        const eventArg = node.arguments[0]
+        if (!eventArg) return
+
+        if (eventArg.type === "Literal" && typeof eventArg.value === "string") {
+          const eventName = eventArg.value
+
+          if (allowedPrefixes.some((prefix) => eventName.startsWith(prefix))) {
+            return
+          }
+
+          context.report({
+            node,
+            messageId: "noRawSocketOn",
+            data: { eventName },
+          })
+        } else {
+          context.report({
+            node,
+            messageId: "noRawSocketOnDynamic",
+          })
+        }
+      },
+    }
+  },
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitzzero/quickdraw-core",
-  "version": "3.3.1",
+  "version": "3.5.0",
   "description": "Fast fullstack patterns for real-time applications with Socket.io and TanStack Query",
   "type": "module",
   "main": "./dist/shared/index.js",