@desolint/socket-shared

Contract types and the one constant @desolint/socket-server and @desolint/socket-client must agree on. Zero runtime dependencies — no socket.io, no React — so importing it into a browser bundle pulls in nothing.

Anything only one side reads lives in that side's package, not here.

Requirements

No runtime dependencies and no peer dependencies — this package is types plus one constant, so it imposes no version constraints of its own.

Install

You normally do not install this package directly. It is a pinned dependency of @desolint/socket-server and @desolint/socket-client, and both re-export everything it exposes — so installing either one gives you these types automatically.

Install it directly only if you consume the contract without either side (a shared types package of your own, for example):

npm install @desolint/socket-shared

It has no dependencies and no peer dependencies.

The contract

Backend and frontend are separate repos, so each project keeps a copy of the contract in both. All three type arguments are the project's, including the socket.data shape — there's no preset that fixes it:

export type AppContract = SocketContract<
  {ping: (n: number) => void}, // clientToServer
  {message: (text: string) => void}, // serverToClient
  {userId: string; tenantId: string} // socket.data
>;

Both packages take this as a type argument, giving checked event names and payloads on each side. Whatever the server's authenticate returns must match the third argument — that pairing is the only thing keeping socket.data honest, since nothing validates it at runtime.

There is deliberately no DesolContract / DesolSocketData. An earlier version shipped both, fixing socket.data to {userId, organizationId} for every project; multi-tenancy is a product model, not a transport concern.

AUTH_FAILED_MESSAGE

The reason this package exists rather than being folded into the other two.

The server throws it from authenticate; the client matches on it (via isAuthFailure) to stop reconnecting. Without a shared value, the client can't tell "server is down, keep retrying" from "this cookie will never be accepted" — and since the default is reconnectionAttempts: Infinity, the latter means hammering the server forever after logout.

It is a pinned regular dependency of both packages, so a consumer cannot resolve two different versions of it — see the root README's Versioning section.

API

Types — SocketContract, EventMap, ClientToServer, ServerToClient, SocketDataOf, EventPayload, ServerEvent, ServerPayload, ClientEvent, ClientPayload.

Values — AUTH_FAILED_MESSAGE, isAuthFailure({error}).

ServerEvent/ServerPayload type a server→client handler; ClientEvent/ClientPayload do the same for a client→server one (used for acknowledgements).

DEFAULT_CLIENT_OPTIONS moved to @desolint/socket-client — only the client reads it, so it was never something the two sides had to agree on.

Development

npm install        # install dependencies (from the repo root)
npm run build      # build all three packages
npm test           # type-check + jest
npm run lint       # eslint

This package is part of the package-socket-io workspaces monorepo — run the commands from the repository root, not this directory.

License

MIT © Desolint — see LICENSE.

Free to use, modify and redistribute, commercially or otherwise. Provided "as is", without warranty or liability of any kind.