itty-sockets

Documentation  |   Discord

---

Tiny realtime messaging client in under 450 bytes. No backend needed.

Example (using ittysockets.io public channels)

import { connect } from 'itty-sockets' // ~422 bytes

// connect to a channel (optionally echo messages back to yourself)
const foo = connect('my-secret-room-name', { echo: true })

foo
  // we can listen for messages
  .on('message', e => console.log(e.message))

  // and/or send some
  .send('Hello World!')     // "Hello World!"
  .send([1, 2, 3])          // [1, 2, 3]
  .send({ foo: 'bar' })     // { foo: "bar" }

Features

• Simple and powerful API for sending and receiving messages & data.
• No backend service needed. Ours is fast and private.
• Full TypeScript support, including custom types for messages.
• Prevents WebSocket race conditions. Automatically connects when needed to send/listen.
• Chainable. Every method returns the channel again.
• Ultra-tiny. It's an itty library, after all.

What is itty-sockets?

itty-sockets is a tiny messaging client that simplifies data/message transmission between users/connections. It's powered by ittysockets.io, a free, fast, and private public service. The idea is simple:

1. Connect to a channel by name (creates a new channel if it doesn't exist).
2. Send/receive messages in the channel.
3. That's it!

This is an easy way to transmit messages between clients, but comes with limitations and considerations:

1. There is no history/replay. It's a live stream.
2. We don't authenticate. Itty Sockets leverages security merely through obfuscation (a near-infinite number of channel names). Use a secure channel name and/or encode your payloads if concerned about eavesdropping. Add your own authentication layer, if needed.
3. There are no guarantees of delivery. Itty Sockets is not a traditional messaging system. It's a public service that is provided without any guarantees of delivery, order, or persistence. Use it for real-time communication, not for mission-critical data.

Privacy Concerns

We do not store any messages or data There is intentionally no message logging or tracking of any kind. It's easier for us that way, and safer for you.

Browser Usage

For use in browser/DevTools scripting, copy and paste this snippet directly into your browser console, then use as normal:

let connect=(e,s={})=>{let o,t=[],n=[],a=0,r={},c=()=>(o||(o=new WebSocket(`wss://ittysockets.io/r/${e??""}?${new URLSearchParams(s)}`),o.onopen=()=>{for(;t.length;)o?.send(t.shift());r.open?.(),a&&o?.close()},o.onmessage=(e,s=JSON.parse(e.data))=>{for(let e of n)e({...s,date:new Date(s.date)})},o.onclose=()=>(a=0,o=null,r.close?.())),l);const l=new Proxy(c,{get:(e,s)=>({open:c,close:()=>(1==o?.readyState?o.close():a=1,l),send:(e,s)=>(e=JSON.stringify(e),e=s?`@@${s}@@${e}`:e,1==o?.readyState?o.send(e)??l:(t.push(e),c())),push:(e,s)=>(a=1,l.send(e,s)),on:(e,s)=>(r[e]=s,"message"==e?(n.push(s),c()):l)}[s])});return l};

afterwards:

// send a message on connect 'foo'
connect('foo').push('hello world!')

API

METHOD	DESCRIPTION	EXAMPLE
connect(id, options)	Creates a new channel connection	connect('foo')
.open()	Opens/re-opens the connection (manually, usually not needed)	channel.open()
.close()	Closes the connection	channel.close()
.send(message)	Sends a message to the channel	channel.send({ type: 'chat', text: 'hello' })
.push(message)	Sends a message and closes the connection	channel.push({ type: 'goodbye' })
.on<MessageType = any>('message', listener)	Adds a message listener (multiple allowed)	channel.on('message', event => console.log(event))
.on('open', listener)	Executes a listener on channel open (one allowed)	channel.on('open', () => console.log('channel opened'))
.on('close', listener)	Executes a listener on channel close (one allowed)	channel.on('close', () => console.log('channel closed'))

Available Options

OPTION	DESCRIPTION	DEFAULT	EXAMPLE
alias	An optional display name for the connection	undefined	{ alias: 'Kevin' }
echo	Whether to echo messages back to the sender	false	{ echo: true }

MessageEvent Format

type MessageEvent = {
  id: string      // unique message ID
  uid: string     // unique user ID
  alias: string?  // optional display name
  date: Date      // JavaScript Date object
  message: any    // the message payload
}