JOIN MY SPONSORS

Type Reference

All types are exported from itty-sockets and available for use in your own code.

IttyProtocol

The base type present on all events when connected to an itty-sockets channel. Includes the sender's uid, optional alias, and server date timestamp.

types.ts
type Timestamp = { date: number }
type UserDetails = { uid: string; alias?: string }

// base protocol — present on all itty-sockets events
type IttyProtocol = UserDetails & Timestamp

IttySocketOptions

Options passed to connect() when connecting to an itty-sockets channel.

types.ts
type IttySocketOptions = {
  as?: string       // display name (alias)
  alias?: string    // alias for `as`
  echo?: true       // receive your own messages
  announce?: true   // broadcast identity on join/leave
}

IttySocket

The socket instance returned by connect(). All methods are chainable. The Base generic is IttyProtocol for itty-sockets channels, or object for raw WebSocket connections. The Events generic is your event map (if provided).

types.ts
type IttySocket<Base, Events> = {
  open():  IttySocket
  close(): IttySocket
  send(message: T, uid?: string): IttySocket
  push(message: T, uid?: string): IttySocket
  remove(type: string, listener: Function): IttySocket
  on(type: string, listener: Function): IttySocket
  on(routeFn: Function, listener: Function): IttySocket
}

IttySocketConnect

The type of the connect function itself. Has two overloads — one for itty-sockets channels (string), one for raw WebSocket URLs (ws:// or wss://).

types.ts
interface IttySocketConnect {
  // itty-sockets channel (auto-detects itty protocol)
  <Events>(channel: string, options?: IttySocketOptions):
    IttySocket<IttyProtocol, Events>

  // raw WebSocket (no itty protocol)
  <Events>(url: 'ws://...' | 'wss://...', queryParams?: any):
    IttySocket<object, Events>
}

MessageEvent

The event shape received by .on('message', ...) and .on(customType, ...) listeners. The generic T is the message payload type.

types.ts
type MessageEvent<T = any> = {
  message: T
  uid?: string
  alias?: string
  date: number
}

JoinEvent

Received by .on('join', ...) listeners. Always includes users (total connected count). uid and alias are only present when the joiner connected with announce: true.

types.ts
type JoinEvent = {
  type: 'join'
  users: number
  uid?: string     // present with announce: true
  alias?: string   // present with announce: true
  date: number
}

LeaveEvent

Received by .on('leave', ...) listeners. Same shape as JoinEvent.

types.ts
type LeaveEvent = {
  type: 'leave'
  users: number
  uid?: string
  alias?: string
  date: number
}

ErrorEvent

Received by .on('error', ...) listeners. Fired on server errors such as rate limit exceeded or send permission denied.

types.ts
type ErrorEvent = {
  type: 'error'
  message: string
  date: number
}