@fitzzero/quickdraw-core 0.1.0 → 1.1.0

package/README.md

@@ -1,4 +1,4 @@
-# @quickdraw/core
+# @fitzzero/quickdraw-core
 
 Fast fullstack patterns for real-time applications with Socket.io and TanStack Query.
 
@@ -13,7 +13,7 @@ Fast fullstack patterns for real-time applications with Socket.io and TanStack Q
 ## Installation
 
 ```bash
-pnpm add @quickdraw/core
+pnpm add @fitzzero/quickdraw-core
 ```
 
 ## Quick Start
@@ -21,7 +21,7 @@ pnpm add @quickdraw/core
 ### Server Setup
 
 ```typescript
-import { createQuickdrawServer, BaseService } from '@quickdraw/core/server';
+import { createQuickdrawServer, BaseService } from '@fitzzero/quickdraw-core/server';
 import { PrismaClient } from '@prisma/client';
 
 const prisma = new PrismaClient();
@@ -62,7 +62,7 @@ const { io, httpServer } = createQuickdrawServer({
 
 ```tsx
 // app/layout.tsx
-import { QuickdrawProvider } from '@quickdraw/core/client';
+import { QuickdrawProvider } from '@fitzzero/quickdraw-core/client';
 
 export default function RootLayout({ children }) {
   return (
@@ -76,7 +76,7 @@ export default function RootLayout({ children }) {
 }
 
 // app/chat/page.tsx
-import { useService, useSubscription } from '@quickdraw/core/client';
+import { useService, useSubscription } from '@fitzzero/quickdraw-core/client';
 
 function ChatPage({ chatId }: { chatId: string }) {
   // Subscribe to real-time updates
@@ -103,7 +103,7 @@ function ChatPage({ chatId }: { chatId: string }) {
 ### Socket Inputs
 
 ```tsx
-import { SocketTextField } from '@quickdraw/core/client';
+import { SocketTextField } from '@fitzzero/quickdraw-core/client';
 
 function ChatTitleEditor({ chat, updateChat }) {
   return (
@@ -123,7 +123,7 @@ function ChatTitleEditor({ chat, updateChat }) {
 
 ```typescript
 // Shared types (both server and client)
-import { ServiceResponse, AccessLevel, ServiceMethodMap } from '@quickdraw/core';
+import { ServiceResponse, AccessLevel, ServiceMethodMap } from '@fitzzero/quickdraw-core';
 
 // Server
 import { 
@@ -134,10 +134,10 @@ import {
   verifyJWT,
   discordProvider,
   googleProvider,
-} from '@quickdraw/core/server';
+} from '@fitzzero/quickdraw-core/server';
 
 // Server testing
-import { createTestServer, connectAsUser, emitWithAck } from '@quickdraw/core/server/testing';
+import { createTestServer, connectAsUser, emitWithAck } from '@fitzzero/quickdraw-core/server/testing';
 
 // Client
 import {
@@ -150,10 +150,24 @@ import {
   SocketSelect,
   SocketSlider,
   SocketSwitch,
-} from '@quickdraw/core/client';
+} from '@fitzzero/quickdraw-core/client';
 
 // Client testing
-import { createMockSocket, createTestWrapper } from '@quickdraw/core/client/testing';
+import { createMockSocket, createTestWrapper } from '@fitzzero/quickdraw-core/client/testing';
+```
+
+## Local Development
+
+This package is developed alongside [quickdraw-chat](https://github.com/fitzzero/quickdraw-chat), a reference implementation.
+
+### Using pnpm link
+
+```bash
+# In quickdraw-chat, the package is linked:
+"@fitzzero/quickdraw-core": "link:../../../quickdraw"
+
+# Changes to quickdraw-core are instantly available after rebuild
+pnpm build  # or pnpm dev for watch mode
 ```
 
 ## Type Definitions
@@ -162,7 +176,7 @@ Define your service methods in a shared types file:
 
 ```typescript
 // shared/types.ts
-import type { ServiceMethodMap } from '@quickdraw/core';
+import type { ServiceMethodMap } from '@fitzzero/quickdraw-core';
 
 export type ChatServiceMethods = ServiceMethodMap<{
   createChat: {
@@ -221,38 +235,118 @@ export type ChatServiceMethods = ServiceMethodMap<{
 
 ## Access Control
 
-Quickdraw supports two levels of access control:
+Quickdraw provides flexible ACL with two complementary levels:
 
 ### Service-level ACL
 
-Stored in `user.serviceAccess` JSON field:
-```json
-{ "chatService": "Admin", "userService": "Read" }
+Blanket permissions across all entries in a service. Stored in `user.serviceAccess`:
+
+```typescript
+// User model must satisfy QuickdrawUser interface
+interface QuickdrawUser {
+  id: string;
+  serviceAccess?: Record<string, AccessLevel> | null;
+}
+
+// Example: Admin access to all chats
+user.serviceAccess = { chatService: "Admin", userService: "Read" };
 ```
 
 ### Entry-level ACL
 
-Stored in entity's `acl` JSON field (when `hasEntryACL: true`):
-```json
-[
-  { "userId": "user-1", "level": "Admin" },
-  { "userId": "user-2", "level": "Read" }
-]
+Per-entity permissions. Quickdraw supports two patterns:
+
+#### Pattern 1: JSON ACL (Simple)
+
+Store ACL directly on the entity. Best for:
+- Simple ownership models (owner + collaborators)
+- When you don't need to query "all entities user X can access" efficiently
+- Minimal schema complexity
+
+```typescript
+// Entity must satisfy ACLEntity interface
+interface ACLEntity {
+  id: string;
+  acl?: ACL | null;  // ACL = Array<{ userId: string; level: AccessLevel }>
+}
+
+// Prisma schema
+model Document {
+  id    String @id @default(cuid())
+  acl   Json?  // Stores [{ userId: "...", level: "Read" }]
+}
+
+// Service - uses default checkEntryACL (no override needed)
+class DocumentService extends BaseService<Document, ...> {
+  constructor(prisma: PrismaClient) {
+    super({ serviceName: "documentService", hasEntryACL: true });
+    this.setDelegate(prisma.document);
+  }
+}
+```
+
+#### Pattern 2: Membership Table (Complex)
+
+Separate table for memberships. Best for:
+- Querying "all entities user X can access" efficiently
+- Complex role hierarchies
+- Additional membership metadata (join date, invited by, etc.)
+
+```typescript
+// Prisma schema
+model Chat {
+  id      String       @id
+  members ChatMember[]
+}
+
+model ChatMember {
+  chatId String
+  userId String
+  level  String  // "Read" | "Moderate" | "Admin"
+  
+  @@unique([chatId, userId])
+}
+
+// Service - override checkEntryACL to use membership table
+class ChatService extends BaseService<Chat, ...> {
+  protected override async checkEntryACL(
+    userId: string,
+    chatId: string,
+    requiredLevel: AccessLevel
+  ): Promise<boolean> {
+    const member = await this.prisma.chatMember.findUnique({
+      where: { chatId_userId: { chatId, userId } },
+    });
+    if (!member) return false;
+    return this.isLevelSufficient(member.level as AccessLevel, requiredLevel);
+  }
+}
 ```
 
+### Access Check Order
+
+When a method is called, `ensureAccessForMethod` checks in this order:
+
+1. **Service-level**: `socket.serviceAccess[serviceName] >= requiredLevel` → Allow
+2. **Custom override**: `checkAccess()` returns true → Allow (use for self-access patterns)
+3. **Entry-level**: `checkEntryACL()` returns true → Allow (JSON ACL or membership table)
+4. **Deny** if none of the above
+
 ### Access Levels
 
-- **Public**: No authentication required
-- **Read**: Authenticated users (default for subscriptions)
-- **Moderate**: Edit access (update, moderate content)
-- **Admin**: Full access (delete, manage ACL)
+| Level | Value | Typical Use |
+|-------|-------|-------------|
+| Public | 0 | No authentication required |
+| Read | 1 | View data, subscribe to updates |
+| Moderate | 2 | Edit content, manage members |
+| Admin | 3 | Delete, manage ACL, full control |
 
 ## Testing
 
 ### Server Integration Tests
 
 ```typescript
-import { createTestServer, connectAsUser, emitWithAck } from '@quickdraw/core/server/testing';
+import { createTestServer, connectAsUser, emitWithAck } from '@fitzzero/quickdraw-core/server/testing';
 
 describe('ChatService', () => {
   let server;
@@ -278,7 +372,7 @@ describe('ChatService', () => {
 ### Client Component Tests
 
 ```typescript
-import { createTestWrapper, createMockSocket, mockSuccessEmit } from '@quickdraw/core/client/testing';
+import { createTestWrapper, createMockSocket, mockSuccessEmit } from '@fitzzero/quickdraw-core/client/testing';
 
 test('renders chat', () => {
   const mockSocket = createMockSocket();

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 UseSubscriptionOptions, d as UseSubscriptionResult } from '../types-CUExGF7F.js';
-export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-CUExGF7F.js';
+import { a as QuickdrawProviderProps, Q as QuickdrawSocketContextValue, U as UseServiceOptions, b as UseServiceResult, c as UseSubscriptionOptions, d as UseSubscriptionResult } from '../types-BADirRXn.js';
+export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-BADirRXn.js';
 import 'socket.io-client';
 import '@tanstack/react-query';
 import '../shared/index.js';
@@ -33,52 +33,44 @@ declare function QuickdrawProvider({ children, serverUrl, queryClient, authToken
 /**
  * Hook for invoking service methods via Socket.io with TanStack Query integration.
  *
- * @typeParam TServiceMethods - Map of service method definitions
- * @typeParam TService - Service name
- * @typeParam TMethod - Method name
+ * This hook supports two usage patterns:
  *
- * @example
+ * 1. **Simple usage** - Just pass service/method names with explicit payload/response types:
  * ```tsx
- * // Define your service methods type
- * type ChatServiceMethods = {
- *   createChat: { payload: { title: string }; response: { id: string } };
- *   updateTitle: { payload: { id: string; title: string }; response: { id: string; title: string } };
- * };
- *
- * // In your component
- * function CreateChatButton() {
- *   const createChat = useService<ChatServiceMethods, 'chatService', 'createChat'>(
- *     'chatService',
- *     'createChat',
- *     {
- *       onSuccess: (data) => {
- *         router.push(`/chat/${data.id}`);
- *       },
- *     }
- *   );
+ * const createChat = useService<{ title: string }, { id: string }>(
+ *   'chatService',
+ *   'createChat'
+ * );
+ * ```
  *
- *   return (
- *     <button
- *       onClick={() => createChat.mutate({ title: 'New Chat' })}
- *       disabled={createChat.isPending}
- *     >
- *       {createChat.isPending ? 'Creating...' : 'Create Chat'}
- *     </button>
- *   );
+ * 2. **Type-safe usage** - Pass a service methods map for full type inference:
+ * ```tsx
+ * // In your app, create a typed wrapper:
+ * function useTypedService<
+ *   TService extends keyof ServiceMethodsMap,
+ *   TMethod extends keyof ServiceMethodsMap[TService] & string,
+ * >(serviceName: TService, methodName: TMethod, options?: ...) {
+ *   type Methods = ServiceMethodsMap[TService];
+ *   type Payload = Methods[TMethod] extends { payload: infer P } ? P : never;
+ *   type Response = Methods[TMethod] extends { response: infer R } ? R : never;
+ *   return useService<Payload, Response>(serviceName, methodName, options);
  * }
  * ```
+ *
+ * @typeParam TPayload - The payload type for the method
+ * @typeParam TResponse - The response type for the method
  */
-declare function useService<TServiceMethods extends Record<string, Record<string, {
-    payload: unknown;
-    response: unknown;
-}>>, TService extends keyof TServiceMethods & string, TMethod extends keyof TServiceMethods[TService] & string>(serviceName: TService, methodName: TMethod, options?: UseServiceOptions<TServiceMethods[TService][TMethod]["response"]>): UseServiceResult<TServiceMethods[TService][TMethod]["payload"], TServiceMethods[TService][TMethod]["response"]>;
+declare function useService<TPayload = unknown, TResponse = unknown>(serviceName: string, methodName: string, options?: UseServiceOptions<TResponse>): UseServiceResult<TPayload, TResponse>;
 /**
  * Simplified hook for basic service method calls.
  * Use this when you don't need the full TanStack Query mutation features.
  *
  * @example
  * ```tsx
- * const { execute, loading, error, data } = useServiceMethod('chatService', 'createChat');
+ * const { execute, loading, error, data } = useServiceMethod<
+ *   { title: string },
+ *   { id: string }
+ * >('chatService', 'createChat');
  *
  * const handleCreate = async () => {
  *   const result = await execute({ title: 'New Chat' });
@@ -102,8 +94,9 @@ declare function useServiceMethod<TPayload = unknown, TResponse = unknown>(servi
  * Features:
  * - Automatic subscription management
  * - TanStack Query cache integration for optimistic updates
- * - Subscription deduplication across components
+ * - Subscription deduplication across components (via context-based registry)
  * - Automatic reconnection handling
+ * - HMR/Fast Refresh safe (no module-level state)
  *
  * @typeParam TData - The entity type
  *

package/dist/client/index.js

@@ -1,9 +1,47 @@
 import * as React from 'react';
 import { io } from 'socket.io-client';
-import { QueryClient, QueryClientProvider, useMutation, useQueryClient, useQuery } from '@tanstack/react-query';
+import { QueryClientProvider, useMutation, useQueryClient, useQuery, QueryClient } from '@tanstack/react-query';
 import { jsx } from 'react/jsx-runtime';
 
 // src/client/QuickdrawProvider.tsx
+function createSubscriptionRegistry() {
+  const subscriptions = /* @__PURE__ */ new Map();
+  return {
+    acquire(key) {
+      const existing = subscriptions.get(key);
+      if (existing) {
+        existing.refCount++;
+        return { isNew: false, entry: existing };
+      }
+      const entry = { refCount: 1 };
+      subscriptions.set(key, entry);
+      return { isNew: true, entry };
+    },
+    release(key) {
+      const entry = subscriptions.get(key);
+      if (!entry) return false;
+      entry.refCount--;
+      if (entry.refCount <= 0) {
+        entry.cleanup?.();
+        subscriptions.delete(key);
+        return true;
+      }
+      return false;
+    },
+    setCleanup(key, cleanup) {
+      const entry = subscriptions.get(key);
+      if (entry) {
+        entry.cleanup = cleanup;
+      }
+    },
+    clear() {
+      for (const entry of subscriptions.values()) {
+        entry.cleanup?.();
+      }
+      subscriptions.clear();
+    }
+  };
+}
 var QuickdrawSocketContext = React.createContext(null);
 function useQuickdrawSocket() {
   const context = React.useContext(QuickdrawSocketContext);
@@ -14,36 +52,44 @@ function useQuickdrawSocket() {
   }
   return context;
 }
-var defaultQueryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1e3 * 60 * 5,
-      // 5 minutes
-      retry: 1
-    },
-    mutations: {
-      retry: 0
+function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 1e3 * 60 * 5,
+        // 5 minutes
+        retry: 1
+      },
+      mutations: {
+        retry: 0
+      }
     }
-  }
-});
+  });
+}
 function QuickdrawProvider({
   children,
   serverUrl,
-  queryClient = defaultQueryClient,
+  queryClient,
   authToken,
   autoConnect = !!authToken
 }) {
+  const [defaultQueryClient] = React.useState(() => createQueryClient());
+  const actualQueryClient = queryClient ?? defaultQueryClient;
   const [socket, setSocket] = React.useState(null);
   const [isConnected, setIsConnected] = React.useState(false);
   const [userId, setUserId] = React.useState(null);
   const [serviceAccess, setServiceAccess] = React.useState({});
-  const authTokenRef = React.useRef(authToken);
-  React.useEffect(() => {
-    authTokenRef.current = authToken;
-  }, [authToken]);
+  const subscriptionRegistryRef = React.useRef(
+    createSubscriptionRegistry()
+  );
+  const prevAuthTokenRef = React.useRef(authToken);
+  const socketRef = React.useRef(null);
   const connect = React.useCallback(
     (token) => {
-      const authToUse = token ?? authTokenRef.current;
+      if (socketRef.current) return;
+      const authToUse = token;
+      subscriptionRegistryRef.current.clear();
+      subscriptionRegistryRef.current = createSubscriptionRegistry();
       const newSocket = io(serverUrl, {
         auth: authToUse ? { token: authToUse } : void 0,
         transports: ["websocket", "polling"],
@@ -54,6 +100,7 @@ function QuickdrawProvider({
       });
       newSocket.on("disconnect", () => {
         setIsConnected(false);
+        subscriptionRegistryRef.current.clear();
       });
       newSocket.on(
         "auth:info",
@@ -65,37 +112,46 @@ function QuickdrawProvider({
       newSocket.on("connect_error", (error) => {
         console.error("Socket connection error:", error.message);
       });
+      socketRef.current = newSocket;
       setSocket(newSocket);
     },
     [serverUrl]
   );
   const disconnect = React.useCallback(() => {
-    if (socket) {
-      socket.disconnect();
+    if (socketRef.current) {
+      subscriptionRegistryRef.current.clear();
+      socketRef.current.disconnect();
+      socketRef.current = null;
       setSocket(null);
       setIsConnected(false);
       setUserId(null);
       setServiceAccess({});
     }
-  }, [socket]);
+  }, []);
   React.useEffect(() => {
-    if (autoConnect && !socket) {
-      connect();
+    if (autoConnect && !socketRef.current) {
+      connect(authToken);
     }
     return () => {
-      if (socket) {
-        socket.disconnect();
+      if (socketRef.current) {
+        subscriptionRegistryRef.current.clear();
+        socketRef.current.disconnect();
+        socketRef.current = null;
       }
     };
-  }, [autoConnect]);
+  }, [autoConnect, authToken]);
   React.useEffect(() => {
-    if (socket && authToken !== authTokenRef.current) {
-      disconnect();
+    const prevToken = prevAuthTokenRef.current;
+    prevAuthTokenRef.current = authToken;
+    if (authToken !== prevToken) {
+      if (socketRef.current) {
+        disconnect();
+      }
       if (authToken) {
         connect(authToken);
       }
     }
-  }, [authToken, socket, disconnect, connect]);
+  }, [authToken, disconnect, connect]);
   const contextValue = React.useMemo(
     () => ({
       socket,
@@ -103,11 +159,12 @@ function QuickdrawProvider({
       userId,
       serviceAccess,
       connect,
-      disconnect
+      disconnect,
+      subscriptionRegistry: subscriptionRegistryRef.current
     }),
     [socket, isConnected, userId, serviceAccess, connect, disconnect]
   );
-  return /* @__PURE__ */ jsx(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsx(QuickdrawSocketContext.Provider, { value: contextValue, children }) });
+  return /* @__PURE__ */ jsx(QueryClientProvider, { client: actualQueryClient, children: /* @__PURE__ */ jsx(QuickdrawSocketContext.Provider, { value: contextValue, children }) });
 }
 function useService(serviceName, methodName, options) {
   const { socket, isConnected } = useQuickdrawSocket();
@@ -126,7 +183,7 @@ function useService(serviceName, methodName, options) {
         const eventName = `${serviceName}:${methodName}`;
         const timeout = setTimeout(() => {
           reject(new Error("Request timeout"));
-        }, 1e4);
+        }, options?.timeout ?? 1e4);
         socket.emit(
           eventName,
           payload,
@@ -190,7 +247,7 @@ function useServiceMethod(serviceName, methodName, options) {
           setLoading(false);
           optionsRef.current?.onError?.(errorMsg);
           resolve(null);
-        }, 1e4);
+        }, options?.timeout ?? 1e4);
         socket.emit(
           eventName,
           payload,
@@ -211,7 +268,7 @@ function useServiceMethod(serviceName, methodName, options) {
         );
       });
     },
-    [socket, isConnected, serviceName, methodName]
+    [socket, isConnected, serviceName, methodName, options?.timeout]
   );
   return {
     execute,
@@ -221,9 +278,8 @@ function useServiceMethod(serviceName, methodName, options) {
     isReady: !!socket && isConnected
   };
 }
-var activeSubscriptions = /* @__PURE__ */ new Map();
 function useSubscription(serviceName, entryId, options = {}) {
-  const { socket, isConnected } = useQuickdrawSocket();
+  const { socket, isConnected, subscriptionRegistry } = useQuickdrawSocket();
   const queryClient = useQueryClient();
   const [isSubscribed, setIsSubscribed] = React.useState(false);
   const [error, setError] = React.useState(null);
@@ -236,7 +292,10 @@ function useSubscription(serviceName, entryId, options = {}) {
     // Subscriptions should stay fresh via socket updates
   } = options;
   const subscriptionKey = entryId ? `${serviceName}:${entryId}` : null;
-  const queryKey = [serviceName, "subscription", entryId];
+  const queryKey = React.useMemo(
+    () => [serviceName, "subscription", entryId],
+    [serviceName, entryId]
+  );
   const onDataRef = React.useRef(onData);
   const onErrorRef = React.useRef(onError);
   React.useEffect(() => {
@@ -256,16 +315,11 @@ function useSubscription(serviceName, entryId, options = {}) {
     if (!socket || !isConnected || !subscriptionKey || !enabled || !entryId) {
       return;
     }
-    const existing = activeSubscriptions.get(subscriptionKey);
-    if (existing) {
-      existing.refCount++;
+    const { isNew } = subscriptionRegistry.acquire(subscriptionKey);
+    if (!isNew) {
       setIsSubscribed(true);
       return () => {
-        existing.refCount--;
-        if (existing.refCount === 0) {
-          existing.cleanup?.();
-          activeSubscriptions.delete(subscriptionKey);
-        }
+        subscriptionRegistry.release(subscriptionKey);
       };
     }
     const subscribeEvent = `${serviceName}:subscribe`;
@@ -307,19 +361,9 @@ function useSubscription(serviceName, entryId, options = {}) {
       socket.emit(`${serviceName}:unsubscribe`, { entryId });
       setIsSubscribed(false);
     };
-    activeSubscriptions.set(subscriptionKey, {
-      refCount: 1,
-      cleanup
-    });
+    subscriptionRegistry.setCleanup(subscriptionKey, cleanup);
     return () => {
-      const sub = activeSubscriptions.get(subscriptionKey);
-      if (sub) {
-        sub.refCount--;
-        if (sub.refCount === 0) {
-          sub.cleanup?.();
-          activeSubscriptions.delete(subscriptionKey);
-        }
-      }
+      subscriptionRegistry.release(subscriptionKey);
     };
   }, [
     socket,
@@ -330,7 +374,8 @@ function useSubscription(serviceName, entryId, options = {}) {
     serviceName,
     requiredLevel,
     queryClient,
-    queryKey
+    queryKey,
+    subscriptionRegistry
   ]);
   const subscribe = React.useCallback(() => {
     if (!socket || !isConnected || !entryId) return;