socketio-hub

Core SDK for creating typed Socket.IO clients with a small event bus for framework wrappers.

import { createSocketHub } from "@lachong-university/socketio-hub";

type ServerEvents = {
  "message:new": { roomId: string; text: string };
};

type ClientEvents = {
  "message:send": { roomId: string; text: string };
};

const hub = createSocketHub<ServerEvents, ClientEvents>({
  url: "https://realtime.example.com",
  namespace: "/chat",
  auth: async () => ({ token: "access-token" }),
  reconnect: true,
  timeout: 10000,
  debug: false,
});

await hub.connect();

hub.on("message:new", (payload) => {
  console.log(payload.roomId, payload.text);
});

await hub.emit("message:send", {
  roomId: "general",
  text: "Hello realtime",
});

API

• connect() creates and connects the Socket.IO client.
• disconnect() closes the active socket.
• emit(event, payload) sends typed events to the server.
• on(event, handler), once(event, handler), and off(event, handler) manage SDK listeners.
• listen(listener) subscribes to every SDK event, including lifecycle events such as hub:connected, hub:disconnected, hub:state, and hub:error.
• cleanup() removes Socket.IO listeners, disconnects, and clears the local event bus.

Browser Script

Build the package to generate browser-ready files:

pnpm --filter @lachong-university/socketio-hub build

Then include the global bundle directly in any web page or upload it to your CDN/S3 bucket:

<script src="https://cdn.example.com/socketio-hub.global.min.js"></script>
<script>
  const hub = SocketIOHub.createSocketHub({
    url: "https://realtime.example.com",
    namespace: "/chat",
    auth: { token: "access-token" },
  });

  hub.on("message:new", function (payload) {
    console.log(payload);
  });

  hub.connect();
</script>

The browser bundle exposes every public export on window.SocketIOHub.

You can also open examples/browser.html after building to verify the script-tag flow locally.

For module scripts, import the browser ESM bundle directly:

<script type="module">
  import { createSocketHub } from "https://cdn.example.com/socketio-hub.esm.min.js";

  const hub = createSocketHub({
    url: "https://realtime.example.com",
    namespace: "/chat",
    auth: { token: "access-token" },
  });

  await hub.connect();
</script>