@fitzzero/quickdraw-core 0.1.0

package/README.md

@@ -0,0 +1,300 @@
+# @quickdraw/core
+
+Fast fullstack patterns for real-time applications with Socket.io and TanStack Query.
+
+## Features
+
+- **Server Core**: BaseService class with typed CRUD, ACL-based access control, and real-time subscriptions
+- **Client Core**: TanStack Query integration with Socket.io for real-time state management
+- **Socket Inputs**: Pre-built form components that sync with server state
+- **Custom OAuth**: JWT-based authentication with Discord and Google providers
+- **Type Safety**: End-to-end TypeScript support with shared type definitions
+
+## Installation
+
+```bash
+pnpm add @quickdraw/core
+```
+
+## Quick Start
+
+### Server Setup
+
+```typescript
+import { createQuickdrawServer, BaseService } from '@quickdraw/core/server';
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+// Define your service
+class ChatService extends BaseService<Chat, Prisma.ChatCreateInput, Prisma.ChatUpdateInput, ChatServiceMethods> {
+  constructor() {
+    super({ serviceName: 'chatService', hasEntryACL: true });
+    this.setDelegate(prisma.chat);
+    
+    // Define public methods
+    this.createChat = this.defineMethod('createChat', 'Read', async (payload, ctx) => {
+      const chat = await this.create({ title: payload.title, ownerId: ctx.userId });
+      return { id: chat.id };
+    });
+  }
+  
+  createChat: ReturnType<typeof this.defineMethod<'createChat'>>;
+}
+
+// Start server
+const { io, httpServer } = createQuickdrawServer({
+  port: 4000,
+  cors: { origin: 'http://localhost:3000' },
+  services: {
+    chatService: new ChatService(),
+  },
+  auth: {
+    authenticate: async (socket, auth) => {
+      const payload = await verifyJWT(auth.token, process.env.JWT_SECRET);
+      return payload?.userId;
+    },
+  },
+});
+```
+
+### Client Setup
+
+```tsx
+// app/layout.tsx
+import { QuickdrawProvider } from '@quickdraw/core/client';
+
+export default function RootLayout({ children }) {
+  return (
+    <QuickdrawProvider
+      serverUrl="http://localhost:4000"
+      authToken={getAuthToken()}
+    >
+      {children}
+    </QuickdrawProvider>
+  );
+}
+
+// app/chat/page.tsx
+import { useService, useSubscription } from '@quickdraw/core/client';
+
+function ChatPage({ chatId }: { chatId: string }) {
+  // Subscribe to real-time updates
+  const { data: chat, isLoading } = useSubscription('chatService', chatId);
+  
+  // Mutation hook
+  const updateTitle = useService('chatService', 'updateTitle', {
+    onSuccess: () => console.log('Title updated!'),
+  });
+  
+  if (isLoading) return <div>Loading...</div>;
+  
+  return (
+    <div>
+      <h1>{chat?.title}</h1>
+      <button onClick={() => updateTitle.mutate({ id: chatId, title: 'New Title' })}>
+        Update Title
+      </button>
+    </div>
+  );
+}
+```
+
+### Socket Inputs
+
+```tsx
+import { SocketTextField } from '@quickdraw/core/client';
+
+function ChatTitleEditor({ chat, updateChat }) {
+  return (
+    <SocketTextField
+      state={chat}
+      update={(patch) => updateChat.mutateAsync({ id: chat.id, ...patch })}
+      property="title"
+      commitMode="debounce"
+      debounceMs={500}
+      placeholder="Chat title..."
+    />
+  );
+}
+```
+
+## Package Exports
+
+```typescript
+// Shared types (both server and client)
+import { ServiceResponse, AccessLevel, ServiceMethodMap } from '@quickdraw/core';
+
+// Server
+import { 
+  BaseService, 
+  ServiceRegistry, 
+  createQuickdrawServer,
+  createJWT,
+  verifyJWT,
+  discordProvider,
+  googleProvider,
+} from '@quickdraw/core/server';
+
+// Server testing
+import { createTestServer, connectAsUser, emitWithAck } from '@quickdraw/core/server/testing';
+
+// Client
+import {
+  QuickdrawProvider,
+  useQuickdrawSocket,
+  useService,
+  useSubscription,
+  SocketCheckbox,
+  SocketTextField,
+  SocketSelect,
+  SocketSlider,
+  SocketSwitch,
+} from '@quickdraw/core/client';
+
+// Client testing
+import { createMockSocket, createTestWrapper } from '@quickdraw/core/client/testing';
+```
+
+## Type Definitions
+
+Define your service methods in a shared types file:
+
+```typescript
+// shared/types.ts
+import type { ServiceMethodMap } from '@quickdraw/core';
+
+export type ChatServiceMethods = ServiceMethodMap<{
+  createChat: {
+    payload: { title: string };
+    response: { id: string };
+  };
+  updateTitle: {
+    payload: { id: string; title: string };
+    response: { id: string; title: string };
+  };
+  inviteUser: {
+    payload: { id: string; userId: string; level: 'Read' | 'Moderate' | 'Admin' };
+    response: { id: string };
+  };
+}>;
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Client (React)                          │
+├─────────────────────────────────────────────────────────────────┤
+│  QuickdrawProvider                                              │
+│  ├── TanStack QueryClient                                       │
+│  └── Socket.io Connection                                       │
+│                                                                 │
+│  useService() ──────────────────────────────────────────────┐   │
+│  useSubscription() ─────────────────────────────────────────┤   │
+│  SocketTextField, SocketCheckbox, ... ──────────────────────┤   │
+│                                                             │   │
+└─────────────────────────────────────────────────────────────│───┘
+                                                              │
+                        Socket.io Events                      │
+                                                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                         Server (Node.js)                        │
+├─────────────────────────────────────────────────────────────────┤
+│  createQuickdrawServer()                                        │
+│  └── ServiceRegistry                                            │
+│      ├── Auto-discovers public methods                          │
+│      └── Wires methods to Socket.io events                      │
+│                                                                 │
+│  BaseService<Entity, CreateInput, UpdateInput, ServiceMethods>  │
+│  ├── defineMethod() - Type-safe method definition               │
+│  ├── subscribe() / unsubscribe() - Real-time subscriptions      │
+│  ├── create() / update() / delete() - CRUD with auto-emit       │
+│  └── checkAccess() - ACL enforcement                            │
+│                                                                 │
+│  Auth Utilities                                                 │
+│  ├── createJWT() / verifyJWT()                                  │
+│  └── OAuth providers (Discord, Google)                          │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Access Control
+
+Quickdraw supports two levels of access control:
+
+### Service-level ACL
+
+Stored in `user.serviceAccess` JSON field:
+```json
+{ "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" }
+]
+```
+
+### Access Levels
+
+- **Public**: No authentication required
+- **Read**: Authenticated users (default for subscriptions)
+- **Moderate**: Edit access (update, moderate content)
+- **Admin**: Full access (delete, manage ACL)
+
+## Testing
+
+### Server Integration Tests
+
+```typescript
+import { createTestServer, connectAsUser, emitWithAck } from '@quickdraw/core/server/testing';
+
+describe('ChatService', () => {
+  let server;
+  
+  beforeAll(async () => {
+    server = await createTestServer({
+      services: { chatService: new ChatService() },
+      seedDb: async () => { /* seed test data */ },
+    });
+  });
+  
+  afterAll(() => server.stop());
+  
+  it('creates chat', async () => {
+    const client = await server.connectAs('user-id');
+    const chat = await client.emit('chatService:createChat', { title: 'Test' });
+    expect(chat.id).toBeDefined();
+    client.close();
+  });
+});
+```
+
+### Client Component Tests
+
+```typescript
+import { createTestWrapper, createMockSocket, mockSuccessEmit } from '@quickdraw/core/client/testing';
+
+test('renders chat', () => {
+  const mockSocket = createMockSocket();
+  mockSocket.emit.mockImplementation(mockSuccessEmit({ title: 'Test Chat' }));
+  
+  const wrapper = createTestWrapper({ socketContext: { socket: mockSocket } });
+  render(<ChatView chatId="123" />, { wrapper });
+  
+  expect(screen.getByText('Test Chat')).toBeInTheDocument();
+});
+```
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guide for details.
+
+## License
+
+MIT

package/dist/client/index.d.ts

@@ -0,0 +1,349 @@
+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 'socket.io-client';
+import '@tanstack/react-query';
+import '../shared/index.js';
+import 'zod';
+
+/**
+ * Hook to access the quickdraw socket context.
+ */
+declare function useQuickdrawSocket(): QuickdrawSocketContextValue;
+/**
+ * Provider component that sets up TanStack Query and Socket.io connection.
+ *
+ * @example
+ * ```tsx
+ * // In your app layout
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <QuickdrawProvider
+ *       serverUrl="http://localhost:4000"
+ *       authToken={token}
+ *     >
+ *       {children}
+ *     </QuickdrawProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function QuickdrawProvider({ children, serverUrl, queryClient, authToken, autoConnect, }: QuickdrawProviderProps): React.ReactElement;
+
+/**
+ * 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
+ *
+ * @example
+ * ```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}`);
+ *       },
+ *     }
+ *   );
+ *
+ *   return (
+ *     <button
+ *       onClick={() => createChat.mutate({ title: 'New Chat' })}
+ *       disabled={createChat.isPending}
+ *     >
+ *       {createChat.isPending ? 'Creating...' : 'Create Chat'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+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"]>;
+/**
+ * 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 handleCreate = async () => {
+ *   const result = await execute({ title: 'New Chat' });
+ *   if (result) {
+ *     router.push(`/chat/${result.id}`);
+ *   }
+ * };
+ * ```
+ */
+declare function useServiceMethod<TPayload = unknown, TResponse = unknown>(serviceName: string, methodName: string, options?: UseServiceOptions<TResponse>): {
+    execute: (payload: TPayload) => Promise<TResponse | null>;
+    loading: boolean;
+    error: string | null;
+    data: TResponse | null;
+    isReady: boolean;
+};
+
+/**
+ * Hook for subscribing to real-time entity updates with TanStack Query integration.
+ *
+ * Features:
+ * - Automatic subscription management
+ * - TanStack Query cache integration for optimistic updates
+ * - Subscription deduplication across components
+ * - Automatic reconnection handling
+ *
+ * @typeParam TData - The entity type
+ *
+ * @example
+ * ```tsx
+ * function ChatView({ chatId }: { chatId: string }) {
+ *   const { data: chat, isLoading, error } = useSubscription<Chat>(
+ *     'chatService',
+ *     chatId,
+ *     {
+ *       onData: (chat) => {
+ *         console.log('Chat updated:', chat.title);
+ *       },
+ *     }
+ *   );
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *   if (!chat) return <div>Chat not found</div>;
+ *
+ *   return <div>{chat.title}</div>;
+ * }
+ * ```
+ */
+declare function useSubscription<TData extends {
+    id: string;
+}>(serviceName: string, entryId: string | null, options?: UseSubscriptionOptions<TData>): UseSubscriptionResult<TData>;
+
+type CommitMode = "change" | "blur" | "debounce";
+interface UseSocketInputOptions<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> {
+    /**
+     * Current state of the entity
+     */
+    state: TEntry | null;
+    /**
+     * Property key to update
+     */
+    property: TKey;
+    /**
+     * Update function that sends the patch to the server
+     */
+    update: (patch: Partial<TAllowedUpdate>) => Promise<TEntry | undefined | null>;
+    /**
+     * When to commit changes to the server
+     * - "change": immediately on every change
+     * - "blur": when input loses focus
+     * - "debounce": after debounceMs of inactivity
+     */
+    commitMode: CommitMode;
+    /**
+     * Debounce delay in milliseconds (only used when commitMode is "debounce")
+     */
+    debounceMs?: number;
+    /**
+     * Format the value from state for display
+     */
+    format?: (value: unknown) => unknown;
+    /**
+     * Parse the display value back to the state format
+     */
+    parse?: (value: unknown) => unknown;
+    /**
+     * Callback on successful update
+     */
+    onSuccess?: (entry: TEntry | undefined | null) => void;
+    /**
+     * Callback on error
+     */
+    onError?: (error: string) => void;
+}
+interface UseSocketInputResult<T> {
+    /**
+     * Current local value (may differ from server while editing)
+     */
+    value: T;
+    /**
+     * Update the local value
+     */
+    onLocalChange: (newValue: T) => void;
+    /**
+     * Manually commit the current value to the server
+     */
+    commit: () => void;
+    /**
+     * Handle blur event (commits if commitMode is "blur")
+     */
+    onBlur: () => void;
+    /**
+     * Whether an update is currently in flight
+     */
+    inFlight: boolean;
+    /**
+     * Whether the local value differs from the server value
+     */
+    isDirty: boolean;
+}
+/**
+ * Hook for managing input state that syncs with the server.
+ * Handles optimistic updates, debouncing, and conflict resolution.
+ */
+declare function useSocketInput<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate>(options: UseSocketInputOptions<TEntry, TAllowedUpdate, TKey>): UseSocketInputResult<unknown>;
+
+interface SocketCheckboxProps<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "checked" | "onChange" | "type" | "onError" | "property"> {
+    state: TEntry | null;
+    update: (patch: Partial<TAllowedUpdate>) => Promise<TEntry | undefined | null>;
+    property: TKey;
+    commitMode?: CommitMode;
+    debounceMs?: number;
+    format?: (v: unknown) => unknown;
+    parse?: (v: unknown) => unknown;
+    onSuccess?: (entry: TEntry | undefined | null) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * A checkbox input that syncs its checked state with the server via socket.
+ *
+ * @example
+ * ```tsx
+ * <SocketCheckbox
+ *   state={chat}
+ *   update={(patch) => updateChat.mutateAsync({ id: chat.id, ...patch })}
+ *   property="isArchived"
+ *   commitMode="change"
+ * />
+ * ```
+ */
+declare function SocketCheckbox<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate>(props: SocketCheckboxProps<TEntry, TAllowedUpdate, TKey>): React.ReactElement;
+
+interface SocketTextFieldProps<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "onChange" | "onError" | "property"> {
+    state: TEntry | null;
+    update: (patch: Partial<TAllowedUpdate>) => Promise<TEntry | undefined | null>;
+    property: TKey;
+    commitMode?: CommitMode;
+    debounceMs?: number;
+    format?: (v: unknown) => unknown;
+    parse?: (v: unknown) => unknown;
+    onSuccess?: (entry: TEntry | undefined | null) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * A text input that syncs its value with the server via socket.
+ *
+ * @example
+ * ```tsx
+ * <SocketTextField
+ *   state={chat}
+ *   update={(patch) => updateChat.mutateAsync({ id: chat.id, ...patch })}
+ *   property="title"
+ *   commitMode="debounce"
+ *   debounceMs={500}
+ *   placeholder="Chat title..."
+ * />
+ * ```
+ */
+declare function SocketTextField<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate>(props: SocketTextFieldProps<TEntry, TAllowedUpdate, TKey>): React.ReactElement;
+
+interface SocketSelectProps<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, "value" | "onChange" | "onError" | "property"> {
+    state: TEntry | null;
+    update: (patch: Partial<TAllowedUpdate>) => Promise<TEntry | undefined | null>;
+    property: TKey;
+    children: React.ReactNode;
+    commitMode?: CommitMode;
+    debounceMs?: number;
+    format?: (v: unknown) => unknown;
+    parse?: (v: unknown) => unknown;
+    onSuccess?: (entry: TEntry | undefined | null) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * A select input that syncs its value with the server via socket.
+ *
+ * @example
+ * ```tsx
+ * <SocketSelect
+ *   state={chat}
+ *   update={(patch) => updateChat.mutateAsync({ id: chat.id, ...patch })}
+ *   property="status"
+ *   commitMode="change"
+ * >
+ *   <option value="active">Active</option>
+ *   <option value="archived">Archived</option>
+ * </SocketSelect>
+ * ```
+ */
+declare function SocketSelect<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate>(props: SocketSelectProps<TEntry, TAllowedUpdate, TKey>): React.ReactElement;
+
+interface SocketSliderProps<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "onChange" | "type" | "onError" | "property"> {
+    state: TEntry | null;
+    update: (patch: Partial<TAllowedUpdate>) => Promise<TEntry | undefined | null>;
+    property: TKey;
+    commitMode?: CommitMode;
+    debounceMs?: number;
+    format?: (v: unknown) => unknown;
+    parse?: (v: unknown) => unknown;
+    onSuccess?: (entry: TEntry | undefined | null) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * A range slider input that syncs its value with the server via socket.
+ *
+ * @example
+ * ```tsx
+ * <SocketSlider
+ *   state={settings}
+ *   update={(patch) => updateSettings.mutateAsync({ id: settings.id, ...patch })}
+ *   property="volume"
+ *   min={0}
+ *   max={100}
+ *   commitMode="debounce"
+ *   debounceMs={200}
+ * />
+ * ```
+ */
+declare function SocketSlider<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate>(props: SocketSliderProps<TEntry, TAllowedUpdate, TKey>): React.ReactElement;
+
+interface SocketSwitchProps<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "checked" | "onChange" | "type" | "onError" | "property"> {
+    state: TEntry | null;
+    update: (patch: Partial<TAllowedUpdate>) => Promise<TEntry | undefined | null>;
+    property: TKey;
+    commitMode?: CommitMode;
+    debounceMs?: number;
+    format?: (v: unknown) => unknown;
+    parse?: (v: unknown) => unknown;
+    onSuccess?: (entry: TEntry | undefined | null) => void;
+    onError?: (error: string) => void;
+}
+/**
+ * A switch/toggle input that syncs its state with the server via socket.
+ * Styled as a switch by default using CSS.
+ *
+ * @example
+ * ```tsx
+ * <SocketSwitch
+ *   state={settings}
+ *   update={(patch) => updateSettings.mutateAsync({ id: settings.id, ...patch })}
+ *   property="darkMode"
+ *   commitMode="change"
+ * />
+ * ```
+ */
+declare function SocketSwitch<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate>(props: SocketSwitchProps<TEntry, TAllowedUpdate, TKey>): React.ReactElement;
+
+export { type CommitMode, QuickdrawProvider, QuickdrawProviderProps, QuickdrawSocketContextValue, SocketCheckbox, type SocketCheckboxProps, SocketSelect, type SocketSelectProps, SocketSlider, type SocketSliderProps, SocketSwitch, type SocketSwitchProps, SocketTextField, type SocketTextFieldProps, UseServiceOptions, UseServiceResult, type UseSocketInputOptions, type UseSocketInputResult, UseSubscriptionOptions, UseSubscriptionResult, useQuickdrawSocket, useService, useServiceMethod, useSocketInput, useSubscription };