Philosophy

Zocket is built on a simple idea:

The core units of many modern apps are live, stateful actors.

Chats, agents, rooms, sessions, documents, matches, and workflows all have identity, behavior, changing state, and clients connected to them in realtime. Zocket exists to make those things first-class instead of forcing them through stateless APIs plus an ad hoc websocket layer.

That is the philosophical distinction behind the rest of the library. Zocket is not just “websocket infrastructure.” It is an application model for building products around live entities.

The Core Idea

Zocket is for building products around long-lived, stateful actors.

Not just sending messages over a socket, but modeling things like:

• chat threads
• AI agent sessions
• collaborative rooms
• support conversations
• multiplayer matches
• workflow runs

as entities with:

• identity
• state
• behavior
• subscriptions

In Zocket, the unit you build around is not an endpoint. It is an actor instance clients can talk to directly.

Build Around Actors, Not Endpoints

Traditional backend design starts with routes, handlers, and stateless requests.

Zocket starts with entities that live.

A chat thread, AI agent, room, document, or multiplayer match is not just a collection of API calls. It has ongoing state, methods that mutate that state, and connected clients that need to stay in sync.

So Zocket treats those things as first-class:

• you talk to an actor
• you invoke typed methods on it
• you subscribe to its state
• you keep logic attached to the entity that owns it

That makes the mental model closer to product building blocks than to “servers that happen to hold sockets.”

Why Zocket Exists

Modern realtime apps are rarely just about transport.

The hard part is expressing live application state in a way that feels natural to build, reason about, and evolve over time.

Without a stronger abstraction, teams usually end up stitching together three separate concerns:

• request handlers or RPC endpoints
• websocket plumbing
• client-side state management and sync logic

That can get a demo working, but it usually turns product concepts into glue code.

Zocket exists to make realtime systems feel like application development again:

• typed
• stateful
• composable
• direct

The Problems Zocket Cares About

1. The wire is usually stringly typed

With raw sockets or Socket.io-style APIs, server and client are connected by event names and payload conventions.

socket.emit("chat:message", { text: "hello" });

socket.on("chat:mesage", (data) => {
  console.log(data.txt);
});

That looks fine until you rename an event, change a payload, or misspell one side. Then the type system stops helping exactly where you need it most: at the boundary between server and client.

Zocket’s answer is to define the shape once on the server and infer the client API from that source of truth.

2. State sync is not a side concern

Most realtime apps are not just “fire an event and forget.” They have shared state:

• a room roster
• a game board
• a document tree
• a presence map
• a running score

With lower-level tools, keeping that state in sync becomes app code:

• invent a patch protocol
• decide what to rebroadcast
• track who is subscribed
• recover when the client reconnects

Zocket treats state sync as part of the core runtime instead of something every app reimplements.

3. Server logic needs a shape

The hardest part of realtime code is usually not transport. It is organization.

Once an app grows beyond a few messages, you need a clear answer to questions like:

• where does the state for this room live?
• which code owns mutations to that state?
• how do concurrent actions get serialized?
• where do connection lifecycle hooks belong?
• what is the unit we route, scale, and reason about?

Zocket’s answer is: make that unit explicit.

What Zocket Is Not

Zocket is not:

• a thin websocket transport layer
• a generic pub/sub utility
• a bag of event handlers with better autocomplete
• a product optimized primarily around raw connection management

Zocket is optimized around stateful actors that clients can talk to in realtime.

If you think in terms of rooms, agents, sessions, threads, documents, or matches, you are probably already thinking in Zocket’s model.

The Design Principles

Define once, infer everywhere

The server should be the source of truth for:

• method names
• input types
• return types
• event payloads
• state shape

The client and React layers should inherit that automatically.

Treat state as a product feature

State synchronization is not a helper utility in a realtime system. It is most of the product experience. So Zocket bakes it in instead of treating it like optional glue code.

Make the unit of coordination explicit

A realtime app is usually made from many isolated stateful things. The runtime should expose that directly instead of forcing everything into a global message handler.

Prefer local reasoning

The more logic you can keep attached to one room, one document, one agent, or one match, the easier it is to understand, test, and operate.

Why Not Just Combine REST, WebSockets, And Client State Yourself?

You can.

Zocket exists because that stack often turns one product concept into three separate technical systems:

• an API surface for mutations
• a websocket channel for updates
• a client-side state layer to stitch everything back together

Zocket compresses those into one abstraction:

• a direct client-to-actor model
• typed methods and state
• built-in subscriptions and sync
• less glue code between product ideas and implementation

If you want the deeper reasoning behind the core abstraction, continue to Why Actors.