@emeryld/rrroutes-client 2.2.18 → 2.3.0

package/README.md

@@ -61,10 +61,10 @@ export function Users() {
 ### 1) Configure the client
 
 ```ts
-import { QueryClient } from '@tanstack/react-query';
-import { createRouteClient, defaultFetcher } from '@emeryld/rrroutes-client';
+import { QueryClient } from '@tanstack/react-query'
+import { createRouteClient, defaultFetcher } from '@emeryld/rrroutes-client'
 
-const queryClient = new QueryClient();
+const queryClient = new QueryClient()
 
 const client = createRouteClient({
   baseUrl: 'https://api.example.com',
@@ -74,7 +74,7 @@ const client = createRouteClient({
     return defaultFetcher({
       ...req,
       headers: { ...req.headers, Authorization: `Bearer ${getToken()}` },
-    });
+    })
   },
   cursorParam: 'cursor', // optional; default is "cursor"
   getNextCursor: (page) => page?.links?.next ?? page?.nextCursor, // optional override
@@ -84,28 +84,28 @@ const client = createRouteClient({
     invalidate: true,
     verbose: true, // include params/query/output in debug events
   },
-});
+})
 ```
 
 ### 2) Build endpoints from your registry
 
 ```ts
-import { registry } from '../routes';
+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)
@@ -130,8 +130,8 @@ function Profile({ userId }: { userId: string }) {
 - 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
+const auditStatus = client.build(registry.byKey['GET /v1/audit'])
+await auditStatus.fetch({}, { includeExternal: true }) // body matches the leaf's bodySchema
 ```
 
 ### 4) Use infinite feeds
@@ -193,13 +193,13 @@ export function RenameForm({ userId }: { userId: string }) {
 ### 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
+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`).
@@ -207,18 +207,18 @@ getUser.setData((prev) => (prev ? { ...prev, status: 'online' } : prev), {
 ### 7) Router helper (build by name instead of leaf)
 
 ```ts
-import { buildRouter } from '@emeryld/rrroutes-client';
-import { registry } from '../routes';
+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;
+} as const
 
-const buildRoute = buildRouter(client, routes);
+const buildRoute = buildRouter(client, routes)
 
-const listUsers = buildRoute('listUsers');                         // builds from routes.listUsers
-const updateUser = buildRoute('updateUser', {}, { name: 'profile' }); // debug name filtering
+const listUsers = buildRoute('listUsers') // builds from routes.listUsers
+const updateUser = buildRoute('updateUser', {}, { name: 'profile' }) // debug name filtering
 ```
 
 ### 8) File uploads (FormData)
@@ -226,12 +226,14 @@ const updateUser = buildRoute('updateUser', {}, { name: 'profile' }); // debug n
 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']);
+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
@@ -251,9 +253,13 @@ const client = createRouteClient({
     only: ['profile', 'feed'],
     logger: (e) => console.info('[rrroutes-client]', e),
   },
-});
+})
 
-const profile = client.build(registry.byKey['GET /v1/me'], {}, { name: 'profile' });
+const profile = client.build(
+  registry.byKey['GET /v1/me'],
+  {},
+  { name: 'profile' },
+)
 ```
 
 Set `environment: 'production'` to silence all debug output regardless of the `debug` option.
@@ -267,33 +273,41 @@ The package also ships a typed Socket.IO client, React provider hooks, and a hel
 ### Define events + config
 
 ```ts
-import { z } from 'zod';
-import { defineSocketEvents } from '@emeryld/rrroutes-contract';
+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() }),
+    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() }) },
+    'chat:message': {
+      message: z.object({
+        roomId: z.string(),
+        text: z.string(),
+        userId: z.string(),
+      }),
+    },
   },
-);
+)
 ```
 
 ### Vanilla SocketClient
 
 ```ts
-import { io } from 'socket.io-client';
-import { SocketClient } from '@emeryld/rrroutes-client';
-import { events, config } from './socketContract';
+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 socket = io('https://socket.example.com', { transports: ['websocket'] })
 
 const client = new SocketClient(events, {
   socket,
@@ -303,26 +317,30 @@ const client = new SocketClient(events, {
       clientEcho: { sentAt: new Date().toISOString() },
     }),
     'sys:pong': async ({ payload }) => {
-      console.log('pong latency', payload.sinceMs);
+      console.log('pong latency', payload.sinceMs)
     },
     'sys:room_join': async ({ rooms }) => {
-      console.log('joining rooms', rooms);
-      return true; // allow join
+      console.log('joining rooms', rooms)
+      return true // allow join
     },
     'sys:room_leave': async ({ rooms }) => {
-      console.log('leaving rooms', rooms);
-      return true;
+      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' });
+  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()`.

package/dist/index.cjs

@@ -46,15 +46,17 @@ module.exports = __toCommonJS(index_exports);
 
 // src/routesV3.client.fetch.ts
 var HttpError = class extends Error {
-  constructor(args) {
-    const { res, url, body } = args;
-    super(`[${res.status}] ${res.statusText}${body ? ` - ${body}` : ""}`);
-    this.message = `${this.message}`;
+  constructor({
+    res,
+    url,
+    body: { message }
+  }) {
+    super(`[${res.status}] ${res.statusText}${message ? ` - ${message}` : ""}`);
     this.name = "HttpError";
     this.status = res.status;
     this.statusText = res.statusText;
     this.url = url;
-    this.body = body;
+    this.body = { message };
     this.headers = res.headers ? Object.fromEntries(res.headers.entries()) : {};
   }
 };
@@ -70,7 +72,7 @@ var defaultFetcher = async (req) => {
     headers,
     body: isFormData ? req.body : req.body == null ? void 0 : JSON.stringify(req.body)
   });
-  const text = await res.text();
+  const text = await res.json();
   if (!res.ok) {
     throw new HttpError({
       res,
@@ -80,7 +82,7 @@ var defaultFetcher = async (req) => {
   }
   try {
     return {
-      data: JSON.parse(text),
+      data: text,
       headers: res.headers ? Object.fromEntries(res.headers.entries()) : {},
       status: res.status
     };
@@ -777,7 +779,8 @@ function safeDescribeHookValue(value) {
     return value;
   }
   if (valueType === "bigint" || valueType === "symbol") return String(value);
-  if (valueType === "function") return `[function ${value.name || "anonymous"}]`;
+  if (valueType === "function")
+    return `[function ${value.name || "anonymous"}]`;
   if (Array.isArray(value)) return `[array length=${value.length}]`;
   if (isProbablySocket(value)) {
     return describeSocketLike(value);
@@ -789,7 +792,8 @@ function safeDescribeHookValue(value) {
   return `[${ctorName} keys=${keyPreview}${suffix}]`;
 }
 function summarizeEvents(events) {
-  if (!events || typeof events !== "object") return safeDescribeHookValue(events);
+  if (!events || typeof events !== "object")
+    return safeDescribeHookValue(events);
   const keys = Object.keys(events);
   if (!keys.length) return "[events empty]";
   const preview = keys.slice(0, 4).join(",");
@@ -797,7 +801,8 @@ function summarizeEvents(events) {
   return `[events count=${keys.length} keys=${preview}${suffix}]`;
 }
 function summarizeBaseOptions(options) {
-  if (!options || typeof options !== "object") return safeDescribeHookValue(options);
+  if (!options || typeof options !== "object")
+    return safeDescribeHookValue(options);
   const obj = options;
   const keys = Object.keys(obj);
   if (!keys.length) return "[baseOptions empty]";
@@ -861,8 +866,17 @@ function buildSocketProvider(args) {
   };
 }
 function SocketProvider(props) {
-  const { events, baseOptions, children, fallback, providerDebug, destroyLeaveMeta } = props;
-  const [resolvedSocket, setResolvedSocket] = React.useState(null);
+  const {
+    events,
+    baseOptions,
+    children,
+    fallback,
+    providerDebug,
+    destroyLeaveMeta
+  } = props;
+  const [resolvedSocket, setResolvedSocket] = React.useState(
+    null
+  );
   const socket = "socket" in props ? props.socket ?? null : resolvedSocket;
   const providerDebugRef = React.useRef();
   providerDebugRef.current = providerDebug;
@@ -884,18 +898,28 @@ function SocketProvider(props) {
     if (!resolvedSocket) {
       Promise.resolve(props.getSocket()).then((s) => {
         if (cancelled) {
-          dbg(providerDebugRef.current, { type: "resolve", phase: "cancelled" });
+          dbg(providerDebugRef.current, {
+            type: "resolve",
+            phase: "cancelled"
+          });
           return;
         }
         if (!s) {
-          dbg(providerDebugRef.current, { type: "resolve", phase: "socketMissing" });
+          dbg(providerDebugRef.current, {
+            type: "resolve",
+            phase: "socketMissing"
+          });
           return;
         }
         setResolvedSocket(s);
         dbg(providerDebugRef.current, { type: "resolve", phase: "ok" });
       }).catch((err) => {
         if (cancelled) return;
-        dbg(providerDebugRef.current, { type: "resolve", phase: "error", err: String(err) });
+        dbg(providerDebugRef.current, {
+          type: "resolve",
+          phase: "error",
+          err: String(err)
+        });
       });
     }
     return () => {
@@ -914,11 +938,19 @@ function SocketProvider(props) {
   });
   const client = React.useMemo(() => {
     if (!socket) {
-      dbg(providerDebugRef.current, { type: "client", phase: "init", missing: true });
+      dbg(providerDebugRef.current, {
+        type: "client",
+        phase: "init",
+        missing: true
+      });
       return null;
     }
     const c = new SocketClient(events, { ...baseOptions, socket });
-    dbg(providerDebugRef.current, { type: "client", phase: "init", missing: false });
+    dbg(providerDebugRef.current, {
+      type: "client",
+      phase: "init",
+      missing: false
+    });
     return c;
   }, [events, baseOptions, socket]);
   const destroyLeaveMetaRef = React.useRef(destroyLeaveMeta);
@@ -932,7 +964,10 @@ function SocketProvider(props) {
       providerDebug: providerDebugRef.current,
       snapshot: {
         hasClient: !!client,
-        destroyLeaveMeta: summarizeMeta(destroyLeaveMetaRef.current, "destroyLeaveMeta")
+        destroyLeaveMeta: summarizeMeta(
+          destroyLeaveMetaRef.current,
+          "destroyLeaveMeta"
+        )
       }
     });
     return () => {
@@ -947,22 +982,32 @@ function SocketProvider(props) {
 }
 function useSocketClient() {
   const ctx = React.useContext(SocketCtx);
-  if (!ctx) throw new Error("SocketClient not found. Wrap with <SocketProvider>.");
+  if (!ctx)
+    throw new Error("SocketClient not found. Wrap with <SocketProvider>.");
   return ctx;
 }
 function useSocketConnection(args) {
-  const { event, rooms, onMessage, onCleanup, autoJoin = true, autoLeave = true } = args;
+  const {
+    event,
+    rooms,
+    onMessage,
+    onCleanup,
+    autoJoin = true,
+    autoLeave = true
+  } = args;
   const client = useSocketClient();
   const normalizedRooms = React.useMemo(
     () => rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms],
     [rooms]
   );
   React.useEffect(() => {
-    if (autoJoin && normalizedRooms.length > 0) client.joinRooms(normalizedRooms, args.joinMeta);
+    if (autoJoin && normalizedRooms.length > 0)
+      client.joinRooms(normalizedRooms, args.joinMeta);
     const unsubscribe = client.on(event, onMessage);
     return () => {
       unsubscribe();
-      if (autoLeave && normalizedRooms.length > 0) client.leaveRooms(normalizedRooms, args.leaveMeta);
+      if (autoLeave && normalizedRooms.length > 0)
+        client.leaveRooms(normalizedRooms, args.leaveMeta);
       if (onCleanup) onCleanup();
     };
   }, [client, event, onMessage, autoJoin, autoLeave, ...normalizedRooms]);
@@ -1084,13 +1129,16 @@ function buildSocketedRoute(options) {
       );
       const unsubscribes = entries.map(
         ([ev, fn]) => client.on(ev, (payload, meta) => {
-          built.setData((prev) => {
-            const next = fn(prev, payload, meta);
-            setRoomState(
-              roomsFromData(next, toRooms)
-            );
-            return next;
-          }, ...useArgs);
+          built.setData(
+            (prev) => {
+              const next = fn(prev, payload, meta);
+              setRoomState(
+                roomsFromData(next, toRooms)
+              );
+              return next;
+            },
+            ...useArgs
+          );
         })
       );
       return () => unsubscribes.forEach((u) => u?.());