@emeryld/rrroutes-client 2.2.10 → 2.2.12

package/README.md

@@ -1,6 +1,13 @@
+<!--
+Summary:
+- Added comprehensive usage for `createRouteClient`, built endpoints (GET/feeds/mutations), cache helpers, invalidation, debug modes, custom fetchers, and React Query integration.
+- Added new sections for router helpers, infinite/feeds, FormData uploads, and socket utilities (SocketClient, provider hooks, socketed routes).
+- Removed the sparse README and outdated publishing script focus; future additions should cover server-side Socket.IO envelope expectations and testing recipes for hooks.
+-->
+
 # @emeryld/rrroutes-client
 
-React Query helpers that sit on top of an RRRoutes contract. This package consumes finalized leaves from `@emeryld/rrroutes-contract` and produces typed fetch helpers (`useEndpoint`, `useInfinite`, `useMutation`, cache key utilities, etc.).
+Typed React Query + Socket.IO helpers that sit on top of RRRoutes contracts. Build endpoints directly from finalized leaves, get strongly-typed hooks/fetchers, ready-to-use cache keys, debug logging, and optional socket utilities (client + React provider + socketed routes).
 
 ## Installation
 
@@ -10,63 +17,429 @@ pnpm add @emeryld/rrroutes-client @tanstack/react-query
 npm install @emeryld/rrroutes-client @tanstack/react-query
 ```
 
-The client already depends on `@emeryld/rrroutes-contract` and `zod`. You only need to provide React Query as a peer dependency.
+`@emeryld/rrroutes-contract` and `zod` come along as dependencies; you supply React Query.
 
-## Usage
+## Quick start (typed GET with React Query)
 
 ```ts
-import { createRouteClient } from '@emeryld/rrroutes-client';
 import { QueryClient } from '@tanstack/react-query';
-import { registry } from '../routes';
+import { createRouteClient } from '@emeryld/rrroutes-client';
+import { registry } from '../routes'; // from @emeryld/rrroutes-contract + finalize(...)
 
 const routeClient = createRouteClient({
-  queryClient: new QueryClient(),
-  baseUrl: '/api',
+  baseUrl: '/api',                   // prepended to all paths
+  queryClient: new QueryClient(),    // shared React Query instance
 });
 
-const listUsers = routeClient.build(registry.byKey['GET /v1/users']);
+const listUsers = routeClient.build(registry.byKey['GET /v1/users'], {
+  staleTime: 60_000,
+  onReceive: (data) => console.log('fresh users', data),
+});
 
-function Users() {
+export function Users() {
   const { data, isLoading } = listUsers.useEndpoint({ query: { search: 'emery' } });
   if (isLoading) return <p>Loading…</p>;
-  return <pre>{JSON.stringify(data)}</pre>;
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
 }
 ```
 
-`createRouteClient` passes your `QueryClient` instance directly into every `useQuery`, `useInfiniteQuery`, and `useMutation` call. That means you can skip wrapping your app with `QueryClientProvider` if you prefer manual wiring (though it's still supported if you need context for devtools or hydration).
+## How it works
+
+- `createRouteClient` wires your `QueryClient`, base URL, optional custom fetcher, and debug settings.
+- `build(leaf, options?, meta?)` returns a helper that exposes:
+  - `useEndpoint(args?)` — React hook for GET/feeds/mutations (typed params/query/body/output).
+  - `fetch(...)` — direct fetcher (no cache). Mutations require the body as the last argument.
+  - `getQueryKeys(...)` — deterministic cache key used by React Query + invalidation.
+  - `invalidate(...)` — invalidate this exact endpoint instance.
+  - `setData(updater, args?)` — mutate cache (infinite-aware).
+- For feed endpoints (`cfg.feed === true`), cursors are handled automatically; cache keys omit the cursor so pages merge correctly.
 
-### Debug logging
+---
 
-You can opt into verbose logging by passing `debug` when constructing the client:
+## Detailed usage
+
+### 1) Configure the client
 
 ```ts
-const routeClient = createRouteClient({
+import { QueryClient } from '@tanstack/react-query';
+import { createRouteClient, defaultFetcher } from '@emeryld/rrroutes-client';
+
+const queryClient = new QueryClient();
+
+const client = createRouteClient({
+  baseUrl: 'https://api.example.com',
+  queryClient,
+  fetcher: async (req) => {
+    // Attach auth headers, reuse defaultFetcher for JSON parsing + error handling
+    return defaultFetcher({
+      ...req,
+      headers: { ...req.headers, Authorization: `Bearer ${getToken()}` },
+    });
+  },
+  cursorParam: 'cursor', // optional; default is "cursor"
+  getNextCursor: (page) => page?.links?.next ?? page?.nextCursor, // optional override
+  environment: process.env.NODE_ENV, // disables debug when "production"
+  debug: {
+    fetch: true,
+    invalidate: true,
+    verbose: true, // include params/query/output in debug events
+  },
+});
+```
+
+### 2) Build endpoints from your registry
+
+```ts
+import { registry } from '../routes';
+
+// Plain GET
+const getUser = client.build(registry.byKey['GET /v1/users/:userId'], {
+  staleTime: 30_000,
+});
+
+// Infinite/feed GET (cfg.feed === true)
+const listFeed = client.build(registry.byKey['GET /v1/posts'], {
+  getNextPageParam: (last) => last.nextCursor, // React Query option override
+});
+
+// Mutation
+const updateUser = client.build(registry.byKey['PATCH /v1/users/:userId'], {
+  onSuccess: () => client.invalidate(['get', 'v1', 'users']), // prefix invalidate
+});
+```
+
+### 3) Use GET hooks (with params/query/body)
+
+```ts
+type User = Awaited<ReturnType<typeof getUser.fetch>>; // fully typed output
+
+function Profile({ userId }: { userId: string }) {
+  const result = getUser.useEndpoint({ params: { userId } });
+  if (result.isLoading) return <p>Loading…</p>;
+  if (result.error) return <p>Failed: {String(result.error)}</p>;
+
+  // Register a listener for push-based updates (e.g., sockets) against this hook
+  result.onReceive((freshUser) => {
+    console.log('pushed update', freshUser);
+  });
+
+  return <div>{result.data.name}</div>;
+}
+```
+
+- For GET leaves that define a `bodySchema`, pass the body after the args tuple:
+
+```ts
+const auditStatus = client.build(registry.byKey['GET /v1/audit']);
+await auditStatus.fetch({}, { includeExternal: true }); // body matches the leaf's bodySchema
+```
+
+### 4) Use infinite feeds
+
+```ts
+function PostFeed() {
+  const feed = listFeed.useEndpoint({ query: { cursor: undefined, limit: 20 } });
+
+  return (
+    <>
+      {(feed.data?.pages ?? []).map((page) =>
+        page.items.map((post) => <article key={post.id}>{post.title}</article>),
+      )}
+      <button
+        disabled={!feed.hasNextPage || feed.isFetchingNextPage}
+        onClick={() => feed.fetchNextPage()}
+      >
+        Load more
+      </button>
+    </>
+  );
+}
+```
+
+- Cursor params are stripped from cache keys automatically so pages share the same base key.
+
+### 5) Use mutations (with optimistic cache helpers)
+
+```ts
+async function rename(userId: string, name: string) {
+  // Direct fetch (server action / non-React usage)
+  await updateUser.fetch({ params: { userId } }, { name });
+}
+
+export function RenameForm({ userId }: { userId: string }) {
+  const mutation = updateUser.useEndpoint({ params: { userId } });
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    const name = new FormData(e.currentTarget).get('name') as string;
+
+    // Optimistically update cache for both the detail and list
+    updateUser.setData((prev) => (prev ? { ...prev, name } : prev), { params: { userId } });
+    client.invalidate(['get', 'v1', 'users']);
+
+    await mutation.mutateAsync({ name });
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <input name="name" defaultValue="" />
+      <button disabled={mutation.isLoading}>Save</button>
+      {mutation.error && <p>Error: {String(mutation.error)}</p>}
+    </form>
+  );
+}
+```
+
+### 6) Cache keys, invalidation, and manual cache writes
+
+```ts
+const keys = getUser.getQueryKeys({ params: { userId: 'u_1' } }); // ['get','v1','users','u_1', {}]
+await getUser.invalidate({ params: { userId: 'u_1' } });          // invalidate exact detail
+await client.invalidate(['get', 'v1', 'users']);                  // invalidate any users endpoints
+
+getUser.setData((prev) => (prev ? { ...prev, status: 'online' } : prev), {
+  params: { userId: 'u_1' },
+});
+```
+
+`setData` respects feeds (updates `InfiniteData` shape when `cfg.feed === true`).
+
+### 7) Router helper (build by name instead of leaf)
+
+```ts
+import { buildRouter } from '@emeryld/rrroutes-client';
+import { registry } from '../routes';
+
+const routes = {
+  listUsers: registry.byKey['GET /v1/users'],
+  updateUser: registry.byKey['PATCH /v1/users/:userId'],
+} as const;
+
+const buildRoute = buildRouter(client, routes);
+
+const listUsers = buildRoute('listUsers');                         // builds from routes.listUsers
+const updateUser = buildRoute('updateUser', {}, { name: 'profile' }); // debug name filtering
+```
+
+### 8) File uploads (FormData)
+
+If a leaf has `bodyFiles` set in its contract, the client automatically converts the body to `FormData`:
+
+```ts
+const uploadAvatar = client.build(registry.byKey['PUT /v1/users/:userId/avatar']);
+
+await uploadAvatar.fetch(
+  { params: { userId: 'u_1' } },
+  { avatar: new File([blob], 'avatar.png', { type: 'image/png' }) },
+);
+```
+
+### 9) Debug logging
+
+```ts
+const client = createRouteClient({
   baseUrl: '/api',
-  queryClient: new QueryClient(),
-  debug: process.env.NODE_ENV !== 'production',
-  // or customize the logger:
-  // debug: {
-  //   enabled: true,
-  //   logger: (event) => console.info('[rrroutes-client]', event),
-  // },
+  queryClient,
+  debug: {
+    build: true,
+    fetch: true,
+    invalidate: true,
+    setData: true,
+    useEndpoint: true,
+    verbose: true,
+    // Limit to specific endpoints by name (third arg to build)
+    only: ['profile', 'feed'],
+    logger: (e) => console.info('[rrroutes-client]', e),
+  },
 });
+
+const profile = client.build(registry.byKey['GET /v1/me'], {}, { name: 'profile' });
 ```
 
-Events cover fetch lifecycles (`start`/`success`/`error`), cache updates, and invalidations so you can trace how RRRoutes interacts with React Query.
+Set `environment: 'production'` to silence all debug output regardless of the `debug` option.
 
-## Scripts
+---
 
-```sh
-pnpm install
-pnpm --filter @emeryld/rrroutes-client build
-pnpm --filter @emeryld/rrroutes-client test
+## Socket utilities (optional)
+
+The package also ships a typed Socket.IO client, React provider hooks, and a helper to merge socket events into React Query caches.
+
+### Define events + config
+
+```ts
+import { z } from 'zod';
+import { defineSocketEvents } from '@emeryld/rrroutes-contract';
+
+const { events, config } = defineSocketEvents(
+  {
+    joinMetaMessage: z.object({ source: z.string().optional() }),
+    leaveMetaMessage: z.object({ source: z.string().optional() }),
+    pingPayload: z.object({ clientEcho: z.object({ sentAt: z.string() }).optional() }),
+    pongPayload: z.object({
+      clientEcho: z.object({ sentAt: z.string() }).optional(),
+      sinceMs: z.number().optional(),
+    }),
+  },
+  {
+    'chat:message': { message: z.object({ roomId: z.string(), text: z.string(), userId: z.string() }) },
+  },
+);
 ```
 
-## Publishing
+### Vanilla SocketClient
 
-```sh
-cd packages/client
-npm publish --access public
+```ts
+import { io } from 'socket.io-client';
+import { SocketClient } from '@emeryld/rrroutes-client';
+import { events, config } from './socketContract';
+
+const socket = io('https://socket.example.com', { transports: ['websocket'] });
+
+const client = new SocketClient(events, {
+  socket,
+  config,
+  sys: {
+    'sys:ping': async () => ({
+      clientEcho: { sentAt: new Date().toISOString() },
+    }),
+    'sys:pong': async ({ payload }) => {
+      console.log('pong latency', payload.sinceMs);
+    },
+    'sys:room_join': async ({ rooms }) => {
+      console.log('joining rooms', rooms);
+      return true; // allow join
+    },
+    'sys:room_leave': async ({ rooms }) => {
+      console.log('leaving rooms', rooms);
+      return true;
+    },
+  },
+  heartbeat: { intervalMs: 15_000, timeoutMs: 7_500 },
+  debug: { receive: true, emit: true, verbose: true, logger: console.log },
+});
+
+client.on('chat:message', (payload, { ctx }) => {
+  console.log('socket message', payload.text, 'latency', ctx.latencyMs);
+});
+
+void client.emit('chat:message', { roomId: 'general', text: 'hi', userId: 'u_1' });
+```
+
+Key methods: `emit`, `on`, `joinRooms` / `leaveRooms`, `startHeartbeat` / `stopHeartbeat`, `connect` / `disconnect`, `stats()`, `destroy()`.
+
+### React provider + hooks
+
+```ts
+import { buildSocketProvider } from '@emeryld/rrroutes-client';
+import { io } from 'socket.io-client';
+import { events, config } from './socketContract';
+
+const { SocketProvider, useSocketClient, useSocketConnection } = buildSocketProvider({
+  events,
+  options: {
+    config,
+    sys: {
+      'sys:ping': async () => ({ clientEcho: { sentAt: new Date().toISOString() } }),
+      'sys:pong': async () => {},
+      'sys:room_join': async () => true,
+      'sys:room_leave': async () => true,
+    },
+    heartbeat: { intervalMs: 10_000 },
+    debug: { receive: true, hook: true, logger: console.log },
+  },
+});
+
+function App({ children }: { children: React.ReactNode }) {
+  return (
+    <SocketProvider
+      getSocket={() => io('https://socket.example.com')}
+      destroyLeaveMeta={{ source: 'app:unmount' }}
+      fallback={<p>Connecting…</p>}
+    >
+      {children}
+    </SocketProvider>
+  );
+}
+
+function RoomMessages({ roomId }: { roomId: string }) {
+  const client = useSocketClient<typeof events, typeof config>();
+
+  useSocketConnection({
+    event: 'chat:message',
+    rooms: roomId,
+    joinMeta: { source: 'room-hydration' },
+    leaveMeta: { source: 'room-hydration' },
+    onMessage: (payload) => console.log('message for room', payload.text),
+  });
+
+  return (
+    <button onClick={() => client.emit('chat:message', { roomId, text: 'ping', userId: 'me' })}>
+      Send
+    </button>
+  );
+}
+```
+
+### Socket + React Query: `buildSocketedRoute`
+
+Automatically join rooms based on fetched data and patch the cache when socket messages arrive.
+
+```ts
+import { buildSocketedRoute } from '@emeryld/rrroutes-client';
+import { useSocketClient } from './socketProvider';
+
+const listRooms = client.build(registry.byKey['GET /v1/rooms'], { staleTime: 120_000 });
+
+const useSocketedRooms = buildSocketedRoute({
+  built: listRooms,
+  event: 'chat:message',
+  toRooms: (page) => page.items.map((r) => r.id), // derive rooms from data (feeds supported)
+  joinMeta: { source: 'rooms:list' },
+  leaveMeta: { source: 'rooms:list' },
+  useSocketClient,
+  applyMessage: (prev, payload) => {
+    if (!prev) return prev;
+    // Example: bump unread count in cache
+    const apply = (items: any[]) =>
+      items.map((room) =>
+        room.id === payload.roomId ? { ...room, unread: (room.unread ?? 0) + 1 } : room,
+      );
+    return 'pages' in prev
+      ? { ...prev, pages: prev.pages.map((p) => ({ ...p, items: apply(p.items) })) }
+      : { ...prev, items: apply(prev.items) };
+  },
+});
+
+function RoomList() {
+  const { data, rooms } = useSocketedRooms();
+  return (
+    <>
+      <p>Subscribed rooms: {rooms.join(', ')}</p>
+      <ul>{data?.items.map((r) => <li key={r.id}>{r.name}</li>)}</ul>
+    </>
+  );
+}
 ```
 
-Always bump `packages/client/package.json` before publishing so consumers can pick up the new release.
+---
+
+## Edge cases & notes
+
+- Mutation `fetch` requires a body argument; GET `fetch` only requires a body when the leaf defines one.
+- Path and query params are validated with the contract schemas before fetch; missing params throw synchronously.
+- Query objects that contain arrays/objects are JSON-stringified in the URL query string.
+- Feed cache keys omit the cursor so `invalidate(['get','v1','posts'])` clears all pages.
+- `setData` runs your updater against the current cache value; return `undefined` to leave the cache untouched.
+- When `environment` is `'production'`, debug logs are disabled even if `debug` is set.
+
+---
+
+## Scripts (monorepo)
+
+Run from the repo root:
+
+```sh
+pnpm --filter @emeryld/rrroutes-client build
+pnpm --filter @emeryld/rrroutes-client typecheck
+pnpm --filter @emeryld/rrroutes-client test
+```

package/dist/index.cjs

@@ -71,8 +71,17 @@ var defaultFetcher = async (req) => {
 // src/routesV3.client.index.ts
 var import_react = require("react");
 var import_react_query = require("@tanstack/react-query");
+var import_zod = require("zod");
 var import_rrroutes_contract = require("@emeryld/rrroutes-contract");
 var toUpper = (m) => m.toUpperCase();
+var defaultFeedQuerySchema = import_zod.z.object({
+  cursor: import_zod.z.string().optional(),
+  limit: import_zod.z.coerce.number().min(1).max(100).default(20)
+});
+var defaultFeedOutputSchema = import_zod.z.object({
+  items: import_zod.z.array(import_zod.z.unknown()),
+  nextCursor: import_zod.z.string().optional()
+});
 function zParse(value, schema) {
   return schema ? schema.parse(value) : value;
 }
@@ -174,6 +183,37 @@ function extractArgs(args) {
 function toArgsTuple(args) {
   return typeof args === "undefined" ? [] : [args];
 }
+function augmentFeedQuerySchema(schema) {
+  if (!schema) return defaultFeedQuerySchema;
+  if (schema instanceof import_zod.z.ZodObject) {
+    const shape = schema.shape ? schema.shape : schema._def?.shape?.();
+    return schema.extend({
+      ...shape ?? {},
+      cursor: defaultFeedQuerySchema.shape.cursor,
+      limit: defaultFeedQuerySchema.shape.limit
+    });
+  }
+  return import_zod.z.intersection(schema, defaultFeedQuerySchema);
+}
+function augmentFeedOutputSchema(schema) {
+  if (!schema) return defaultFeedOutputSchema;
+  if (schema instanceof import_zod.z.ZodObject) {
+    const shape = schema.shape ? schema.shape : schema._def?.shape?.();
+    const hasItems = Boolean(shape?.items);
+    if (hasItems) return schema.extend({ nextCursor: import_zod.z.string().optional() });
+    return import_zod.z.object({
+      items: import_zod.z.array(schema),
+      nextCursor: import_zod.z.string().optional()
+    });
+  }
+  if (schema instanceof import_zod.z.ZodArray) {
+    return import_zod.z.object({
+      items: schema,
+      nextCursor: import_zod.z.string().optional()
+    });
+  }
+  return defaultFeedOutputSchema;
+}
 function buildUrl(leaf, baseUrl, params, query) {
   const normalizedParams = zParse(params, leaf.cfg.paramsSchema);
   const normalizedQuery = zParse(query, leaf.cfg.querySchema);
@@ -202,8 +242,13 @@ function createRouteClient(opts) {
   function buildInternal(leaf, rqOpts, meta) {
     const isGet = leaf.method === "get";
     const isFeed = !!leaf.cfg.feed;
+    const leafCfg = isFeed ? {
+      ...leaf.cfg,
+      querySchema: augmentFeedQuerySchema(leaf.cfg.querySchema),
+      outputSchema: augmentFeedOutputSchema(leaf.cfg.outputSchema)
+    } : leaf.cfg;
     const method = toUpper(leaf.method);
-    const expectsArgs = Boolean(leaf.cfg.paramsSchema || leaf.cfg.querySchema);
+    const expectsArgs = Boolean(leafCfg.paramsSchema || leafCfg.querySchema);
     const leafLabel = `${leaf.method.toUpperCase()} ${String(leaf.path)}`;
     const debugName = meta?.name;
     const emit = (event) => emitDebug(event, debugName);
@@ -247,13 +292,18 @@ function createRouteClient(opts) {
       const a = extractArgs(tuple);
       const params = a?.params;
       const query = options?.queryOverride ?? a?.query;
-      const { url, normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
+      const { url, normalizedQuery, normalizedParams } = buildUrl(
+        { ...leaf, cfg: leafCfg },
+        baseUrl,
+        params,
+        query
+      );
       let payload;
-      const acceptsBody = Boolean(leaf.cfg.bodySchema);
+      const acceptsBody = Boolean(leafCfg.bodySchema);
       const requiresBody = options?.requireBody ?? (!isGet && acceptsBody);
       if (typeof options?.body !== "undefined") {
-        const normalizedBody = zParse(options.body, leaf.cfg.bodySchema);
-        const isMultipart = Array.isArray(leaf.cfg.bodyFiles) && leaf.cfg.bodyFiles.length > 0;
+        const normalizedBody = zParse(options.body, leafCfg.bodySchema);
+        const isMultipart = Array.isArray(leafCfg.bodyFiles) && leafCfg.bodyFiles.length > 0;
         payload = isMultipart ? toFormData(normalizedBody) : normalizedBody;
       } else if (requiresBody) {
         throw new Error("Body is required when invoking a mutation fetch.");
@@ -277,7 +327,7 @@ function createRouteClient(opts) {
         const out = await fetcher(
           payload === void 0 ? { url, method } : { url, method, body: payload }
         );
-        const parsed = zParse(out, leaf.cfg.outputSchema);
+        const parsed = zParse(out, leafCfg.outputSchema);
         emit(
           decorateDebugEvent(
             {
@@ -313,7 +363,7 @@ function createRouteClient(opts) {
       }
     };
     const fetchGet = (...tupleWithBody) => {
-      const acceptsBody = Boolean(leaf.cfg.bodySchema);
+      const acceptsBody = Boolean(leafCfg.bodySchema);
       const tupleLength = tupleWithBody.length;
       const maybeBodyIndex = expectsArgs ? 1 : 0;
       const hasBodyCandidate = acceptsBody && tupleLength > maybeBodyIndex;
@@ -346,7 +396,12 @@ function createRouteClient(opts) {
           },
           []
         );
-        const { normalizedQuery, normalizedParams } = buildUrl(leaf, baseUrl, params, query);
+        const { normalizedQuery, normalizedParams } = buildUrl(
+          { ...leaf, cfg: leafCfg },
+          baseUrl,
+          params,
+          query
+        );
         const queryResult = (0, import_react_query.useInfiniteQuery)({
           ...buildOptions,
           queryKey: getQueryKeys(...tuple),
@@ -400,7 +455,7 @@ function createRouteClient(opts) {
           },
           []
         );
-        buildUrl(leaf, baseUrl, params, query);
+        buildUrl({ ...leaf, cfg: leafCfg }, baseUrl, params, query);
         const queryResult = (0, import_react_query.useQuery)({
           ...buildOptions,
           queryKey: getQueryKeys(...tuple),
@@ -488,9 +543,9 @@ function toFormData(body) {
 }
 
 // src/sockets/socket.client.sys.ts
-var import_zod = require("zod");
-var roomValueSchema = import_zod.z.union([import_zod.z.array(import_zod.z.string()), import_zod.z.string()]);
-var buildRoomPayloadSchema = (metaSchema) => import_zod.z.object({
+var import_zod2 = require("zod");
+var roomValueSchema = import_zod2.z.union([import_zod2.z.array(import_zod2.z.string()), import_zod2.z.string()]);
+var buildRoomPayloadSchema = (metaSchema) => import_zod2.z.object({
   rooms: roomValueSchema,
   meta: metaSchema
 });