@fitzzero/quickdraw-core 3.9.0 → 4.0.0

package/README.md

@@ -5,6 +5,7 @@ Fast fullstack patterns for real-time applications with Socket.io and TanStack Q
 ## Features
 
 - **Server Core**: BaseService class with typed CRUD, ACL-based access control, and real-time subscriptions
+- **Collections**: declare a scope-keyed list once, get live add/update/remove deltas, pagination, and reconnect healing — no hand-wired events
 - **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
@@ -110,6 +111,88 @@ function ChatPage({ chatId }: { chatId: string }) {
 }
 ```
 
+### Collections (Live Lists)
+
+Entity subscriptions cover single rows; **collections** cover lists. A
+collection is "rows of this service, grouped by a scope id derived from the
+row" — declare it once and the framework handles emission (multi-node-safe),
+pagination, and reconnect correctness. No more `task:created` /
+`task:deleted` mirror events, `invalidateOn` refetches, or hand-rolled
+merge-by-id state.
+
+**Server** — declare next to your methods; the CRUD trio emits deltas
+automatically (scope moves and predicate entry/exit included):
+
+```typescript
+type MessageCollections = { byChat: { item: MessageDTO } };
+
+class MessageService extends BaseService<
+  Message,
+  Prisma.MessageCreateInput,
+  Prisma.MessageUpdateInput,
+  MessageServiceMethods,
+  Record<string, unknown>, // channels
+  MessageDTO, // TDto — wire shape
+  MessageCollections // TCollections
+> {
+  constructor(prisma: PrismaClient) {
+    super({ serviceName: "messageService" });
+    this.setDelegate(prisma.message);
+
+    this.defineCollection("byChat", {
+      resolveScopeId: (message) => message.chatId,
+      checkScopeAccess: (userId, chatId) => this.isChatMember(userId, chatId),
+      // Server-ordered first page + reconnect re-snapshot. Omit `ids` for
+      // unbounded histories like this one; return it for bounded scopes so
+      // reconnecting clients prune rows deleted while offline.
+      snapshot: async (chatId, { cursor, limit }) => this.getMessagePage(chatId, cursor, limit),
+      toItem: (message) => this.toDto(message),
+    });
+  }
+}
+```
+
+**Client** — one hook per list; live deltas, `loadMore` paging, and
+re-snapshot-on-reconnect are built in:
+
+```tsx
+import { useCollection } from "@fitzzero/quickdraw-core/client";
+
+function ChatWindow({ chatId }: { chatId: string }) {
+  const {
+    items: messages,
+    isLoading,
+    hasMore,
+    loadMore,
+  } = useCollection<MessageDTO>("messageService", "byChat", chatId, {
+    compare: (a, b) => a.createdAt.localeCompare(b.createdAt),
+  });
+
+  return <MessageList messages={messages} onScrollTop={hasMore ? loadMore : undefined} />;
+}
+```
+
+Scopes don't have to be parent entities — `resolveScopeId` may return a
+`string[]` to fan out (e.g. a chat appearing in every member's `myChats`
+collection, scope = user id), or `null` to exclude a row (predicate
+filtering). For hand-rolled write paths, one-line choke points keep deltas
+flowing: `emitCollectionUpsert` / `emitCollectionRemove` /
+`emitCollectionMove` / `emitCollectionReset`, plus `kickFromCollection` for
+adapter-safe ACL revocation.
+
+ACL is deliberately simple: items are **scope-visible** — anyone who passes
+`checkScopeAccess` sees every item in full (strip sensitive fields in
+`toItem`/`snapshot`). If visibility varies per user within a scope, that's
+not a collection — use separate scopes or entity subscriptions.
+
+When to use which:
+
+| Hook              | Use for                                                       |
+| ----------------- | ------------------------------------------------------------- |
+| `useSubscription` | One entity, field-tiered (detail panels)                      |
+| `useCollection`   | Live lists of a scope (boards, feeds, chat histories)         |
+| `useServiceQuery` | Genuinely query-shaped reads (search, cross-scope aggregates) |
+
 ### Socket Inputs
 
 ```tsx
@@ -131,54 +214,71 @@ 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:
+For genuinely custom, ephemeral events (typing indicators, presence pulses —
+things that aren't rows), broadcast with `emitToRoom` and listen with
+`useRoomEvents`:
 
 ```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[]>([]);
+function ChatView({ chatId }: { chatId: string }) {
+  const { data: chat } = useSubscription("chatService", chatId);
+  const [typing, setTyping] = useState<string | null>(null);
 
   // 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)),
+    "chat:typing": ({ userName }: { userName: string }) => setTyping(userName),
+    "chat:typingStop": () => setTyping(null),
   });
 
-  return <Board tasks={tasks} />;
+  return <Chat chat={chat} typing={typing} />;
+}
+```
+
+Event names and payloads can be typed end-to-end by augmenting
+`QuickdrawEventMap` from the package root — `emitToRoom` and `useRoomEvents`
+then check payloads and autocomplete names (and degrade to
+`string`/`unknown` if you never augment it):
+
+```typescript
+declare module "@fitzzero/quickdraw-core" {
+  interface QuickdrawEventMap {
+    "chat:typing": { userName: string };
+    "chat:typingStop": Record<string, never>;
+  }
 }
 ```
 
+Don't hand-emit row lifecycle events (`task:created`, `task:deleted`, …) —
+that's what collections automate; the shipped
+`quickdraw/no-manual-collection-events` lint rule flags them.
+
 ### Auto-Invalidating Queries
 
-For list queries that should refresh when related events fire, use `invalidateOn`:
+For genuinely query-shaped reads (search results, cross-scope aggregates)
+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(
+function SearchResults({ query }: { query: string }) {
+  const { data: results } = useServiceQuery(
     "taskService",
-    "listTasks",
-    { projectId },
+    "searchTasks",
+    { query },
     {
-      invalidateOn: ["task:created", "task:deleted", "task:statusUpdate"],
+      invalidateOn: ["task:statusUpdate"],
+      refetchInterval: 60_000, // optional periodic refresh
     },
   );
 
-  return (
-    <ul>
-      {tasks?.map((t) => (
-        <li key={t.id}>{t.title}</li>
-      ))}
-    </ul>
-  );
+  return <Results items={results} />;
 }
 ```
 
-Rapid-fire events within 100ms are debounced into a single refetch.
+Rapid-fire events within 100ms are debounced into a single refetch. For
+plain scope lists, prefer `useCollection` — it replaces the
+`invalidateOn` + refetch cycle with true deltas.
 
 ### Channels (High-Frequency Traffic)
 
@@ -285,17 +385,89 @@ When to use which:
 | ACL            | full async check incl. DB | in-memory only           |
 | Rate limit     | global limiter            | per-channel token bucket |
 
+## Splitting Large Services
+
+Real services grow past what one file should hold. The proven pattern —
+battle-tested in the framework's largest consumer without import cycles — is
+an abstract `*ServiceCore` plus method modules wired by a thin concrete
+subclass:
+
+```typescript
+// services/task/service-core.ts — state, ACL overrides, helpers. No methods.
+export abstract class TaskServiceCore extends BaseService<
+  Task,
+  Prisma.TaskCreateInput,
+  Prisma.TaskUpdateInput,
+  TaskServiceMethods,
+  TaskChannels,
+  TaskDTO,
+  TaskCollections
+> {
+  constructor(protected readonly prisma: PrismaClient) {
+    super({ serviceName: "taskService" });
+    this.setDelegate(prisma.task);
+  }
+
+  public buildCardDTO(taskId: string): Promise<TaskCardDTO> {
+    /* ... */
+  }
+}
+
+// services/task/methods/create-task.ts — one module per method (or cluster).
+// defineMethod is public precisely so modules can register on the instance.
+export function registerCreateTask(service: TaskService): void {
+  service.defineMethod(
+    "createTask",
+    "Read",
+    async (payload, ctx) => {
+      // ...
+    },
+    { schema: createTaskSchema },
+  );
+}
+
+// services/task/index.ts — the concrete subclass wires the modules.
+export class TaskService extends TaskServiceCore {
+  constructor(prisma: PrismaClient) {
+    super(prisma);
+    registerCreateTask(this);
+    registerUpdateTask(this);
+    // ...
+    this.verifyAllMethods(["createTask", "updateTask" /* ... */]);
+  }
+}
+```
+
+Core → modules → concrete class is a DAG: the core never imports the modules,
+the modules never import each other. `verifyAllMethods` catches a forgotten
+`register*` call at boot. The public choke points (`emitUpdate`,
+`emitCollectionUpsert`, `emitToRoom`, `isLevelSufficient`, …) exist so method
+modules outside the class stay fully capable.
+
 ## Package Exports
 
 ```typescript
 // Shared types (both server and client)
-import { ServiceResponse, AccessLevel, ServiceMethodMap } from "@fitzzero/quickdraw-core";
+import {
+  ServiceResponse,
+  AccessLevel,
+  ServiceMethodMap,
+  // Room helpers + typed events (4.0)
+  serviceRoom,
+  collectionRoom,
+  userRoom,
+  type QuickdrawEventMap,
+  type CollectionDelta,
+} from "@fitzzero/quickdraw-core";
 
 // Server
 import {
   BaseService,
+  BaseRpcService, // 4.0: method-only services, no delegate/CRUD
   ServiceRegistry,
   createQuickdrawServer,
+  type CollectionDefinition, // 4.0
+  type QuickdrawIdentity, // 4.0: structured authenticate result
   createJWT,
   verifyJWT,
   discordProvider,
@@ -340,7 +512,9 @@ import {
   useService,
   useServiceQuery,
   useSubscription,
+  useCollection, // 4.0: live scope-keyed lists
   useRoomEvents,
+  ServiceCallError, // 4.0: hook errors carry the server code
   SocketCheckbox,
   SocketTextField,
   SocketSelect,
@@ -436,6 +610,7 @@ export type ChatServiceMethods = ServiceMethodMap<{
 │                                                                 │
 │  useService() ──────────────────────────────────────────────┐   │
 │  useSubscription() ─────────────────────────────────────────┤   │
+│  useCollection() ───────────────────────────────────────────┤   │
 │  SocketTextField, SocketCheckbox, ... ──────────────────────┤   │
 │                                                             │   │
 └─────────────────────────────────────────────────────────────│───┘
@@ -450,10 +625,11 @@ export type ChatServiceMethods = ServiceMethodMap<{
 │      ├── Auto-discovers public methods                          │
 │      └── Wires methods to Socket.io events                      │
 │                                                                 │
-│  BaseService<Entity, CreateInput, UpdateInput, ServiceMethods>  │
+│  BaseService<Entity, Create, Update, Methods, …, Dto, Colls>    │
 │  ├── defineMethod() - Type-safe method definition               │
+│  ├── defineCollection() - Live lists with automatic deltas      │
 │  ├── subscribe() / unsubscribe() - Real-time subscriptions      │
-│  ├── create() / update() / delete() - CRUD with auto-emit       │
+│  ├── create() / update() / delete() - CRUD, auto-emit + hooks   │
 │  └── checkAccess() - ACL enforcement                            │
 │                                                                 │
 │  Auth Utilities                                                 │

package/dist/client/index.d.ts

@@ -1,9 +1,9 @@
 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, g as UseRoomEventsOptions, h as UseChannelSendResult } from '../types-DUHPIy_5.js';
-export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-DUHPIy_5.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 UseCollectionOptions, h as UseCollectionResult, i as QuickdrawRoomEventHandlers, j as UseRoomEventsOptions, k as UseChannelSendResult } from '../types-CX5LuC_8.js';
+export { C as ClientServiceMethodMap, S as SubscriptionDataMap } from '../types-CX5LuC_8.js';
+import { CollectionSnapshotResponse, CollectionDelta } from '../shared/index.js';
 import 'socket.io-client';
 import '@tanstack/react-query';
-import '../shared/index.js';
 import 'zod';
 
 /**
@@ -28,7 +28,7 @@ declare function useQuickdrawSocket(): QuickdrawSocketContextValue;
  * }
  * ```
  */
-declare function QuickdrawProvider({ children, serverUrl, queryClient, authToken, autoConnect, withCredentials, socketPath, }: QuickdrawProviderProps): React.ReactElement;
+declare function QuickdrawProvider({ children, serverUrl, queryClient, authToken, autoConnect, withCredentials, socketPath, reconnectBehavior, }: QuickdrawProviderProps): React.ReactElement;
 
 /**
  * Hook for invoking service methods via Socket.io with TanStack Query integration.
@@ -171,6 +171,37 @@ declare function useSubscription<TData extends {
     id: string;
 }>(serviceName: string, entryId: string | null, options?: UseSubscriptionOptions<TData>): UseSubscriptionResult<TData>;
 
+/**
+ * Hook for subscribing to a server-declared collection: a scope-keyed,
+ * live-updating list (`defineCollection` server-side).
+ *
+ * The initial snapshot arrives via `{service}:collection:subscribe`;
+ * `added`/`updated`/`removed` deltas stream to the scope room and merge
+ * id-keyed with per-item last-writer-wins; `reset` deltas trigger a
+ * debounced re-snapshot. Reconnects re-snapshot automatically (the same
+ * registry cycle entity subscriptions use), pruning rows deleted while
+ * offline when the server provides membership `ids`.
+ *
+ * Subscriptions are deduped across components by scope; pagination reuses
+ * the subscribe event with a cursor via `loadMore`.
+ *
+ * @example
+ * ```tsx
+ * function ChatWindow({ chatId }: { chatId: string }) {
+ *   const { items: messages, loadMore, hasMore } = useCollection<MessageDTO>(
+ *     "messageService",
+ *     "byChat",
+ *     chatId,
+ *     { compare: (a, b) => a.createdAt.localeCompare(b.createdAt) },
+ *   );
+ *   // messages update live; loadMore() pages in older history
+ * }
+ * ```
+ */
+declare function useCollection<TItem extends {
+    id: string;
+}>(serviceName: string, collection: string, scopeId: string | null, options?: UseCollectionOptions<TItem>): UseCollectionResult<TItem>;
+
 /**
  * Hook for listening to custom socket events with managed lifecycle.
  *
@@ -178,6 +209,11 @@ declare function useSubscription<TData extends {
  * and connection-awareness. Each component gets its own listeners (no dedup needed).
  * Room scoping is handled server-side via `emitToRoom`.
  *
+ * Event names and payloads are typed via the augmentable `QuickdrawEventMap`
+ * (from the package root): augmented names get payload checking and
+ * autocomplete; unlisted names still work, untyped — nothing breaks if the
+ * map stays empty.
+ *
  * Pair with `useSubscription` to ensure the socket is in the correct room:
  * `useSubscription` manages room membership, `useRoomEvents` manages event listeners.
  *
@@ -205,7 +241,7 @@ declare function useSubscription<TData extends {
  * }
  * ```
  */
-declare function useRoomEvents(handlers: Record<string, (data: never) => void>, options?: UseRoomEventsOptions): void;
+declare function useRoomEvents(handlers: QuickdrawRoomEventHandlers, options?: UseRoomEventsOptions): void;
 
 /**
  * Hook for sending fire-and-forget channel messages (the high-frequency
@@ -237,6 +273,96 @@ declare function useRoomEvents(handlers: Record<string, (data: never) => void>,
  */
 declare function useChannelSend<TPayload = unknown>(serviceName: string, channelName: string): UseChannelSendResult<TPayload>;
 
+/**
+ * Pure merge logic for collection subscriptions — the correctness heart of
+ * `useCollection`, kept free of React/socket dependencies so every rule is
+ * unit-testable.
+ *
+ * Invariants:
+ * - Everything is id-keyed; live deltas and paged history compose.
+ * - Per-item last-writer-wins by `rev` (epoch ms). A delta older than what
+ *   the cache holds for that id is ignored; snapshot/page items only
+ *   overwrite cached items whose rev predates the response's rev.
+ * - Removals leave a tombstone rev in `revById` so a stale `added` cannot
+ *   resurrect a deleted row; snapshots garbage-collect stale tombstones.
+ */
+interface CollectionCacheEntry<TItem extends {
+    id: string;
+}> {
+    byId: Record<string, TItem>;
+    /** Insertion/server order; render order applies `compare` on top. */
+    order: string[];
+    /** Last-known rev per id — includes tombstones for removed ids. */
+    revById: Record<string, number>;
+    nextCursor: string | null;
+    totalCount: number | null;
+    /** Rev of the last cursor-less snapshot applied. */
+    snapshotRev: number;
+}
+interface ApplyDeltaOptions {
+    /** Where `added` lands when the id is new. Default "end". */
+    insertPosition?: "start" | "end";
+}
+interface ApplyDeltaResult<TItem extends {
+    id: string;
+}> {
+    entry: CollectionCacheEntry<TItem>;
+    /** True when the delta was a `reset` — caller schedules a re-snapshot. */
+    resetRequested: boolean;
+}
+declare function createEmptyEntry<TItem extends {
+    id: string;
+}>(): CollectionCacheEntry<TItem>;
+/**
+ * Apply a cursor-less snapshot (initial load or re-snapshot).
+ *
+ * - When `ids` is present it is the authoritative membership: cached items
+ *   absent from it are pruned — unless a live delta newer than the snapshot
+ *   put them there (`revById[id] > snapshot.rev`), in which case the live
+ *   push wins.
+ * - Page items upsert unless the cache holds a newer rev for that id.
+ * - Order: page order first (fresh server order), then surviving previously
+ *   known ids in their prior relative order (paged-in history stays).
+ * - Tombstones older than the snapshot rev are garbage-collected; newer
+ *   ones keep suppressing their id (the removal happened after the
+ *   snapshot query ran).
+ */
+declare function applySnapshot<TItem extends {
+    id: string;
+}>(prev: CollectionCacheEntry<TItem> | null | undefined, snapshot: CollectionSnapshotResponse<TItem>): CollectionCacheEntry<TItem>;
+/**
+ * Apply a cursored page (loadMore): upsert-only, never prune. Unseen ids
+ * append at the end in page order; existing ids keep their position (and
+ * their item, when the cache holds a newer rev).
+ */
+declare function applyPage<TItem extends {
+    id: string;
+}>(prev: CollectionCacheEntry<TItem> | null | undefined, page: CollectionSnapshotResponse<TItem>): CollectionCacheEntry<TItem>;
+/**
+ * Apply a live delta. Returns the previous entry object unchanged when the
+ * delta is stale (rev LWW) so referential equality can skip re-renders.
+ */
+declare function applyDelta<TItem extends {
+    id: string;
+}>(prev: CollectionCacheEntry<TItem> | null | undefined, delta: CollectionDelta<TItem>, options?: ApplyDeltaOptions): ApplyDeltaResult<TItem>;
+/**
+ * Apply a batch of buffered deltas in arrival order (used when deltas
+ * raced an in-flight snapshot). `resetRequested` is true if any was a reset.
+ */
+declare function applyDeltas<TItem extends {
+    id: string;
+}>(prev: CollectionCacheEntry<TItem> | null | undefined, deltas: CollectionDelta<TItem>[], options?: ApplyDeltaOptions): ApplyDeltaResult<TItem>;
+
+/**
+ * Error thrown by client hooks when a service call acks with
+ * `{ success: false }`. Carries the server's optional numeric code
+ * (e.g. 401, 403, 429) so callers can branch without string matching.
+ */
+declare class ServiceCallError extends Error {
+    readonly code?: number;
+    constructor(message: string, code?: number);
+}
+
 type CommitMode = "change" | "blur" | "debounce";
 interface UseSocketInputOptions<TEntry, TAllowedUpdate, TKey extends keyof TAllowedUpdate> {
     /**
@@ -547,4 +673,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, UseChannelSendResult, 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, useChannelSend, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };
+export { type BreadcrumbItem, type CollectionCacheEntry, type CommitMode, type JWTPayload, type NavItem, QuickdrawProvider, QuickdrawProviderProps, QuickdrawRoomEventHandlers, QuickdrawSocketContextValue, ServiceCallError, SocketCheckbox, type SocketCheckboxProps, SocketSelect, type SocketSelectProps, SocketSlider, type SocketSliderProps, SocketSwitch, type SocketSwitchProps, SocketTextField, type SocketTextFieldProps, UseChannelSendResult, UseCollectionOptions, UseCollectionResult, UseRoomEventsOptions, UseServiceOptions, UseServiceQueryOptions, UseServiceQueryResult, UseServiceResult, type UseSocketInputOptions, type UseSocketInputResult, UseSubscriptionOptions, UseSubscriptionResult, applyDelta, applyDeltas, applyPage, applySnapshot, buildBreadcrumbs, clearAuthToken, createEmptyEntry, findNavItemByHref, findParentNavItem, formatCurrency, formatDate, formatDateTime, formatNumber, formatPercent, getAuthToken, getOAuthUrl, logout, logoutAllDevices, parseJWTPayload, routeRequiresAuth, setAuthToken, truncate, useChannelSend, useCollection, useQuickdrawSocket, useRoomEvents, useService, useServiceMethod, useServiceQuery, useSocketInput, useSubscription };