Install

bash

npm install @tahanabavi/typesocket zod socket.io-client

zod and socket.io-client are peer dependencies — schemas only compare correctly when every package shares one zod instance.

Quick start

1. Declare the contract. This file is imported by the frontend and the backend:

// ws-contracts.ts
import { z } from 'zod'
import { defineSocketContracts } from '@tahanabavi/typesocket'

export const wsContracts = defineSocketContracts({
  chat: {
    sendMessage: {
      direction: 'client->server',
      request: z.object({ roomId: z.string(), text: z.string().min(1) }),
      ack: z.object({ id: z.string(), sentAt: z.number() }),
    },
    typing: {
      direction: 'client->server',
      request: z.object({ roomId: z.string(), isTyping: z.boolean() }),
    },
    message: {
      direction: 'server->client',
      payload: z.object({ id: z.string(), text: z.string(), user: z.string() }),
    },
  },
})

2. Use it. The client is generated from the contract — there is no event name to mistype and no payload shape to keep in sync:

import { createSocketClient } from '@tahanabavi/typesocket'
import { wsContracts } from './ws-contracts'

const client = createSocketClient({ url: 'http://localhost:3001' }, wsContracts)

// server -> client: listening. `m` is fully typed.
const off = client.modules.chat.message.on((m) => console.log(m.user, m.text))

// client -> server with an ack: returns a Promise of the *validated* ack.
const { id } = await client.modules.chat.sendMessage({
  roomId: 'r1',
  text: 'hi',
})

// client -> server without an ack: fire-and-forget, returns void.
client.modules.chat.typing({ roomId: 'r1', isTyping: true })

off() // unsubscribe

Whether an emit returns Promise<Ack> or void is decided by the contract: declare ack and awaiting is meaningful, omit it and the return type is void.