@emeryld/rrroutes-client 2.0.8 → 2.0.10

package/dist/index.cjs

@@ -488,30 +488,33 @@ function buildSocketProvider(args) {
 }
 function SocketProvider(props) {
   const { events, baseOptions, children, fallback, providerDebug } = props;
-  const [socket, setSocket] = React.useState(
-    "socket" in props ? props.socket : null
-  );
+  const [resolvedSocket, setResolvedSocket] = React.useState(null);
+  const socket = "socket" in props ? props.socket ?? null : resolvedSocket;
   React.useEffect(() => {
+    if (!("getSocket" in props)) return;
     let cancelled = false;
     dbg(providerDebug, { type: "resolve", phase: "start" });
-    if (!socket && "getSocket" in props) {
+    if (!resolvedSocket) {
       Promise.resolve(props.getSocket()).then((s) => {
         if (cancelled) {
           dbg(providerDebug, { type: "resolve", phase: "cancelled" });
+          return;
+        }
+        if (!s) {
+          dbg(providerDebug, { type: "resolve", phase: "missing" });
+          return;
         }
-        setSocket(s);
+        setResolvedSocket(s);
         dbg(providerDebug, { type: "resolve", phase: "ok" });
       }).catch((err) => {
-        dbg(providerDebug, { type: "resolve", phase: "error", err: String(err) });
         if (cancelled) return;
+        dbg(providerDebug, { type: "resolve", phase: "error", err: String(err) });
       });
-    } else {
-      dbg(providerDebug, { type: "resolve", phase: "missing" });
     }
     return () => {
       cancelled = true;
     };
-  }, [socket]);
+  }, [resolvedSocket]);
   const client = React.useMemo(() => {
     if (!socket) {
       dbg(providerDebug, { type: "client", phase: "missing" });
@@ -567,78 +570,165 @@ var SocketClient = class {
     this.roomCounts = /* @__PURE__ */ new Map();
     this.handlerMap = /* @__PURE__ */ new Map();
     this.events = events;
-    this.socket = opts.socket;
-    this.roomJoinEvent = opts.roomJoinEvent ?? "room:join";
-    this.roomLeaveEvent = opts.roomLeaveEvent ?? "room:leave";
+    this.socket = opts.socket ?? null;
     this.environment = opts.environment ?? "development";
     this.debug = opts.debug ?? {};
-    const hb = opts.heartbeat;
+    this.sysEvents = opts.sys ?? {};
+    const hb = opts.heartbeat ?? {};
     this.hb = {
-      pingEvent: hb.pingEvent ?? "sys:ping",
-      pongEvent: hb.pongEvent ?? "sys:pong",
       intervalMs: hb.intervalMs ?? 15e3,
       timeoutMs: hb.timeoutMs ?? 7500,
-      pingSchema: hb.pingSchema,
-      makePingPayload: hb.makePingPayload,
-      pongSchema: hb.pongSchema,
       onPong: hb.onPong
     };
     this.onConnect = () => {
-      this.dbg({
-        type: "connection",
-        phase: "connect",
-        id: this.socket.id ?? ""
-      });
-      this.startHeartbeat();
+      const sys = this.getSysEvent("sys:connect");
+      const defaultHandler = () => {
+        this.dbg({
+          type: "connection",
+          phase: "connect",
+          id: this.socket?.id ?? ""
+        });
+        this.startHeartbeat();
+      };
+      if (sys?.sysHandler) {
+        sys.sysHandler({
+          name: "sys:connect",
+          phase: "connect",
+          socket: this.socket,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
+      }
     };
     this.onReconnect = (attempt) => {
-      this.dbg({
-        type: "connection",
-        phase: "reconnect",
-        attempt
-      });
+      const sys = this.getSysEvent("sys:reconnect");
+      const defaultHandler = () => {
+        this.dbg({
+          type: "connection",
+          phase: "reconnect",
+          attempt
+        });
+      };
+      if (sys?.sysHandler) {
+        sys.sysHandler({
+          name: "sys:reconnect",
+          phase: "reconnect",
+          attempt,
+          socket: this.socket,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
+      }
     };
     this.onDisconnect = (reason) => {
-      this.dbg({
-        type: "connection",
-        phase: "disconnect",
-        reason: String(reason)
-      });
-      this.stopHeartbeat();
+      const sys = this.getSysEvent("sys:disconnect");
+      const defaultHandler = () => {
+        this.dbg({
+          type: "connection",
+          phase: "disconnect",
+          reason: String(reason)
+        });
+        this.stopHeartbeat();
+      };
+      if (sys?.sysHandler) {
+        sys.sysHandler({
+          name: "sys:disconnect",
+          phase: "disconnect",
+          reason: String(reason),
+          socket: this.socket,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
+      }
     };
     this.onConnectError = (err) => {
-      this.dbg({
-        type: "connection",
-        phase: "connect_error",
-        err: String(err)
-      });
+      const sys = this.getSysEvent("sys:connect_error");
+      const defaultHandler = () => {
+        this.dbg({
+          type: "connection",
+          phase: "connect_error",
+          err: String(err)
+        });
+      };
+      if (sys?.sysHandler) {
+        sys.sysHandler({
+          name: "sys:connect_error",
+          phase: "connect_error",
+          error: err,
+          socket: this.socket,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
+      }
     };
     this.onPong = (raw) => {
+      const sys = this.getSysEvent("sys:pong");
+      const schema = sys?.message;
+      let validated = raw;
+      if (schema) {
+        const ok = schema.safeParse(raw);
+        if (!ok.success) return;
+        validated = ok.data;
+      }
       const receivedAt = Date.now();
-      const clientSentIso = raw?.clientEcho?.__clientSentAt;
+      const clientSentIso = validated?.clientEcho?.__clientSentAt;
       let latencyMs;
       if (clientSentIso) {
         const sent = Date.parse(clientSentIso);
         if (!Number.isNaN(sent)) latencyMs = Math.max(0, receivedAt - sent);
       }
-      if (this.hb.pongSchema) {
-        const ok = this.hb.pongSchema.safeParse(raw);
-        if (!ok.success) return;
+      const latency = latencyMs ?? validated?.sinceMs ?? 0;
+      const defaultHandler = () => {
+        this.dbg({
+          type: "heartbeat",
+          action: "pong_recv",
+          latencyMs: latency,
+          payload: validated
+        });
+        if (this.hb.onPong) {
+          this.hb.onPong({
+            latencyMs: latency,
+            payload: validated,
+            socket: this.socket
+          });
+        }
+      };
+      if (sys?.sysHandler) {
+        sys.sysHandler({
+          name: "sys:pong",
+          socket: this.socket,
+          raw: validated,
+          latencyMs: latency,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
       }
-      const latency = latencyMs ?? raw?.sinceMs ?? 0;
-      this.dbg({
-        type: "heartbeat",
-        action: "pong_recv",
-        latencyMs: latency,
-        payload: raw
-      });
-      this.hb.onPong?.({ latencyMs: latency, payload: raw, socket: this.socket });
     };
-    this.socket.on("connect", this.onConnect);
-    this.socket.on("reconnect", this.onReconnect);
-    this.socket.on("disconnect", this.onDisconnect);
-    this.socket.on("connect_error", this.onConnectError);
-    this.socket.on(this.hb.pongEvent, this.onPong);
+    if (this.socket) {
+      this.socket.on("connect", this.onConnect);
+      this.socket.on("reconnect", this.onReconnect);
+      this.socket.on("disconnect", this.onDisconnect);
+      this.socket.on("connect_error", this.onConnectError);
+      this.socket.on("sys:pong", this.onPong);
+    }
+  }
+  getSysEvent(name) {
+    return this.sysEvents[name];
   }
   dbg(e) {
     const d = this.debug;
@@ -664,31 +754,73 @@ var SocketClient = class {
   toArray(rooms) {
     return rooms == null ? [] : Array.isArray(rooms) ? rooms : [rooms];
   }
+  /**
+   * Public: start the heartbeat loop manually.
+   *
+   * This is called by the default 'sys:connect' handler, but you can also
+   * call it yourself from any sysHandler to change when heartbeats start.
+   */
   startHeartbeat() {
     this.stopHeartbeat();
+    if (!this.socket) return;
+    const socket = this.socket;
     const tick = () => {
-      const basePayload = this.hb.makePingPayload({ socket: this.socket }) ?? {};
-      const candidate = { ...basePayload, __clientSentAt: (/* @__PURE__ */ new Date()).toISOString() };
-      const check = this.hb.pingSchema.safeParse(candidate);
-      if (!check.success) {
-        if (this.environment === "development")
-          console.warn("[socket] ping schema validation failed", check.error.issues);
-        return;
-      }
-      const timer = setTimeout(() => {
-      }, this.hb.timeoutMs);
-      this.socket.timeout(this.hb.timeoutMs).emit(this.hb.pingEvent, { payload: check.data }, () => {
-        clearTimeout(timer);
-      });
-      this.dbg({
-        type: "heartbeat",
-        action: "ping_emit",
-        payload: check.data
+      if (!socket) return;
+      const sysPing = this.getSysEvent("sys:ping");
+      const schema = sysPing?.message;
+      const buildDefaultPayload = () => ({
+        clientEcho: { __clientSentAt: (/* @__PURE__ */ new Date()).toISOString() }
       });
+      const send = (payload) => {
+        let dataToSend = payload;
+        if (schema) {
+          const check = schema.safeParse(payload);
+          if (!check.success) {
+            if (this.environment === "development") {
+              console.warn("[socket] ping schema validation failed", check.error.issues);
+            }
+            return;
+          }
+          dataToSend = check.data;
+        }
+        const timer = setTimeout(() => {
+        }, this.hb.timeoutMs);
+        socket.timeout(this.hb.timeoutMs).emit("sys:ping", dataToSend, () => {
+          clearTimeout(timer);
+        });
+        this.dbg({
+          type: "heartbeat",
+          action: "ping_emit",
+          payload: dataToSend
+        });
+      };
+      const defaultHandler = () => {
+        const payload = buildDefaultPayload();
+        send(payload);
+      };
+      if (sysPing?.sysHandler) {
+        sysPing.sysHandler({
+          name: "sys:ping",
+          socket,
+          buildDefaultPayload,
+          send,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
+      }
     };
     this.hbTimer = setInterval(tick, this.hb.intervalMs);
     tick();
   }
+  /**
+   * Public: stop the heartbeat loop.
+   *
+   * This is called by the default 'sys:disconnect' handler, but you can also
+   * call it yourself from any sysHandler to fully control heartbeat lifecycle.
+   */
   stopHeartbeat() {
     if (this.hbTimer) {
       clearInterval(this.hbTimer);
@@ -699,6 +831,12 @@ var SocketClient = class {
     const schema = this.events[event].message;
     const parsed = schema.safeParse(payload);
     if (!parsed.success) throw new Error(`Invalid payload for "${event}": ${parsed.error.message}`);
+    if (!this.socket) {
+      if (this.environment === "development") {
+        console.warn(`[socket] emit("${String(event)}") skipped because socket is null`);
+      }
+      return;
+    }
     if (onAck) {
       this.socket.timeout(timeoutMs ?? this.hb.timeoutMs).emit(String(event), parsed.data, (ack) => {
         try {
@@ -723,9 +861,25 @@ var SocketClient = class {
       this.roomCounts.set(r, next);
       if (next === 1) toJoin.push(r);
     }
-    if (toJoin.length > 0) {
-      this.socket.emit(this.roomJoinEvent, { rooms: toJoin });
-      this.dbg({ type: "room", action: "join", rooms: toJoin });
+    if (toJoin.length > 0 && this.socket) {
+      const socket = this.socket;
+      const sys = this.getSysEvent("sys:room_join");
+      const defaultHandler = () => {
+        socket.emit("sys:room_join", { rooms: toJoin });
+        this.dbg({ type: "room", action: "join", rooms: toJoin });
+      };
+      if (sys?.sysHandler) {
+        sys.sysHandler({
+          name: "sys:room_join",
+          rooms: toJoin,
+          socket,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
+      }
     }
   }
   leaveRooms(rooms) {
@@ -738,14 +892,38 @@ var SocketClient = class {
       if (next === 0) this.roomCounts.delete(r);
       else this.roomCounts.set(r, next);
     }
-    if (toLeave.length > 0) {
-      this.socket.emit(this.roomLeaveEvent, { rooms: toLeave });
-      this.dbg({ type: "room", action: "leave", rooms: toLeave });
+    if (toLeave.length > 0 && this.socket) {
+      const socket = this.socket;
+      const sys = this.getSysEvent("sys:room_leave");
+      const defaultHandler = () => {
+        socket.emit("sys:room_leave", { rooms: toLeave });
+        this.dbg({ type: "room", action: "leave", rooms: toLeave });
+      };
+      if (sys?.sysHandler) {
+        sys.sysHandler({
+          name: "sys:room_leave",
+          rooms: toLeave,
+          socket,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
+      }
     }
   }
   on(event, handler) {
     const schema = this.events[event].message;
     this.dbg({ type: "register", action: "register", event });
+    if (!this.socket) {
+      if (this.environment === "development") {
+        console.warn(`[socket] on("${String(event)}") skipped because socket is null`);
+      }
+      return () => {
+      };
+    }
+    const socket = this.socket;
     const wrapped = (envelopeOrRaw, maybeAck) => {
       const maybeEnvelope = envelopeOrRaw;
       const rawData = maybeEnvelope?.data ?? maybeEnvelope;
@@ -764,9 +942,9 @@ var SocketClient = class {
         ctx: {
           receivedAt,
           latencyMs: sentAt ? Math.max(0, receivedAt.getTime() - sentAt.getTime()) : void 0,
-          nsp: this.socket.nsp,
-          socketId: this.socket.id,
-          socket: this.socket,
+          nsp: socket.nsp,
+          socketId: socket.id,
+          socket,
           reply: typeof maybeAck === "function" ? (d) => {
             try {
               maybeAck(d);
@@ -792,8 +970,8 @@ var SocketClient = class {
         console.warn(`[socket] ${String(event)}:error`, e);
       }
     };
-    this.socket.on(String(event), wrapped);
-    this.socket.on(`${String(event)}:error`, errorWrapped);
+    socket.on(String(event), wrapped);
+    socket.on(`${String(event)}:error`, errorWrapped);
     let set = this.handlerMap.get(String(event));
     if (!set) {
       set = /* @__PURE__ */ new Set();
@@ -802,8 +980,8 @@ var SocketClient = class {
     const entry = { orig: handler, wrapped, errorWrapped };
     set.add(entry);
     return () => {
-      this.socket.off(String(event), wrapped);
-      this.socket.off(`${String(event)}:error`, errorWrapped);
+      socket.off(String(event), wrapped);
+      socket.off(`${String(event)}:error`, errorWrapped);
       const s = this.handlerMap.get(String(event));
       if (s) {
         s.delete(entry);
@@ -818,32 +996,52 @@ var SocketClient = class {
    */
   destroy() {
     this.stopHeartbeat();
-    this.socket.off("connect", this.onConnect);
-    this.socket.off("reconnect", this.onReconnect);
-    this.socket.off("disconnect", this.onDisconnect);
-    this.socket.off("connect_error", this.onConnectError);
-    this.socket.off(this.hb.pongEvent, this.onPong);
-    for (const [event, set] of this.handlerMap.entries()) {
-      for (const entry of set) {
-        this.socket.off(String(event), entry.wrapped);
-        this.socket.off(`${String(event)}:error`, entry.errorWrapped);
+    const socket = this.socket;
+    if (socket) {
+      socket.off("connect", this.onConnect);
+      socket.off("reconnect", this.onReconnect);
+      socket.off("disconnect", this.onDisconnect);
+      socket.off("connect_error", this.onConnectError);
+      socket.off("sys:pong", this.onPong);
+      for (const [event, set] of this.handlerMap.entries()) {
+        for (const entry of set) {
+          socket.off(String(event), entry.wrapped);
+          socket.off(`${String(event)}:error`, entry.errorWrapped);
+        }
       }
     }
     this.handlerMap.clear();
     const toLeave = Array.from(this.roomCounts.entries()).filter(([, count]) => count > 0).map(([room]) => room);
-    if (toLeave.length > 0) {
-      this.socket.emit(this.roomLeaveEvent, { rooms: toLeave });
-      this.dbg({ type: "room", action: "leave", rooms: toLeave });
+    if (toLeave.length > 0 && socket) {
+      const sys = this.getSysEvent("sys:room_leave");
+      const defaultHandler = () => {
+        socket.emit("sys:room_leave", { rooms: toLeave });
+        this.dbg({ type: "room", action: "leave", rooms: toLeave });
+      };
+      if (sys?.sysHandler) {
+        sys.sysHandler({
+          name: "sys:room_leave",
+          rooms: toLeave,
+          socket,
+          next: defaultHandler,
+          startHeartbeat: () => this.startHeartbeat(),
+          stopHeartbeat: () => this.stopHeartbeat()
+        });
+      } else {
+        defaultHandler();
+      }
     }
     this.roomCounts.clear();
   }
   /** Pass-throughs. Managing connection is the caller’s responsibility. */
   disconnect() {
+    if (!this.socket) return;
     this.stopHeartbeat();
     this.socket.disconnect();
     this.dbg({ type: "connection", phase: "disconnect", reason: "client_disconnect" });
   }
   connect() {
+    if (!this.socket) return;
     this.socket.connect();
     this.dbg({ type: "connection", phase: "connect", id: this.socket.id ?? "" });
   }