@emeryld/rrroutes-client 2.0.9 → 2.0.10

package/dist/index.cjs

@@ -571,81 +571,165 @@ var SocketClient = class {
     this.handlerMap = /* @__PURE__ */ new Map();
     this.events = events;
     this.socket = opts.socket ?? null;
-    this.roomJoinEvent = opts.roomJoinEvent ?? "room:join";
-    this.roomLeaveEvent = opts.roomLeaveEvent ?? "room:leave";
     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 ?? ""
-        // CHANGED
-      });
-      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 });
     };
     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(this.hb.pongEvent, this.onPong);
+      this.socket.on("sys:pong", this.onPong);
     }
   }
+  getSysEvent(name) {
+    return this.sysEvents[name];
+  }
   dbg(e) {
     const d = this.debug;
     if (!d.logger) return;
@@ -670,33 +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 = () => {
-      if (!this.socket) return;
-      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);
@@ -738,8 +862,24 @@ var SocketClient = class {
       if (next === 1) toJoin.push(r);
     }
     if (toJoin.length > 0 && this.socket) {
-      this.socket.emit(this.roomJoinEvent, { rooms: toJoin });
-      this.dbg({ type: "room", action: "join", rooms: toJoin });
+      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) {
@@ -753,8 +893,24 @@ var SocketClient = class {
       else this.roomCounts.set(r, next);
     }
     if (toLeave.length > 0 && this.socket) {
-      this.socket.emit(this.roomLeaveEvent, { rooms: toLeave });
-      this.dbg({ type: "room", action: "leave", rooms: toLeave });
+      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) {
@@ -846,7 +1002,7 @@ var SocketClient = class {
       socket.off("reconnect", this.onReconnect);
       socket.off("disconnect", this.onDisconnect);
       socket.off("connect_error", this.onConnectError);
-      socket.off(this.hb.pongEvent, this.onPong);
+      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);
@@ -857,8 +1013,23 @@ var SocketClient = class {
     this.handlerMap.clear();
     const toLeave = Array.from(this.roomCounts.entries()).filter(([, count]) => count > 0).map(([room]) => room);
     if (toLeave.length > 0 && socket) {
-      socket.emit(this.roomLeaveEvent, { rooms: toLeave });
-      this.dbg({ type: "room", action: "leave", rooms: toLeave });
+      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();
   }