itty-sockets 0.8.1 → 0.9.0

package/README.md

@@ -14,125 +14,63 @@
 [![Issues](https://img.shields.io/github/issues/kwhitley/itty-sockets?style=flat-square)](https://github.com/kwhitley/itty-sockets/issues)
 [![Discord](https://img.shields.io/discord/832353585802903572?label=Discord&logo=Discord&style=flat-square&logoColor=fff)](https://discord.gg/53vyrZAu9u)
 
-### [Documentation](https://itty.dev/itty-sockets)  |   [Discord](https://discord.gg/53vyrZAu9u)
+### [Full Documentation](https://itty.ws/docs)  |   [Discord](https://discord.gg/53vyrZAu9u)
 
 ---
 
-### Say goodbye to WebSocket boilerplate.
+# Zero-Config WebSockets.
 
-Your own wrapper is bigger, I promise.
+No accounts, no API keys, nothing to deploy. Just connect and start sending.
 
-Or [optionally] go a step further and use the integrated [itty.ws](https://itty.ws) connection to send messages (zero-config, zero-tracking, 100% free).
+**~466 bytes** min+gzip • **$0/month** • **Free forever**
 
-## Features ✨
-1. **DX perks** - JSON-in/out, queued messages, easy-reconnect, chainable everything
-1. **Works with *any* JSON-based WebSocket server** - it's just a raw WebSocket wrapper, after all
-1. **Powerful routing** - easily handle your own message formats
-1. **Type-safe message handling** - so your app knows what to expect
-1. **No socket server needed** - Use [itty.ws](https://itty.ws) public channels to get started even faster
-1. **Tiny** - under 500 bytes total
+## Features
+- **Zero Configuration** - No accounts, no API keys, no server. Pick a channel name and you're live.
+- **Zero Cost** - No tiers. No credit card. Built for the community.
+- **Private by Default** - No logging, no tracking, no storage. Messages are relayed and forgotten.
+- **Send Anything** - Strings, objects, arrays — anything JSON-serializable.
+- **Access Control** - [Reserve a namespace](https://ittysockets.com/reservations) to control who can join or send on your channels.
+- **Use Anywhere** - No vendor lock. This client works with *any* WebSocket server.  Want to host your own?  No problem.
+- **Tiny Client** - Only 466 bytes gzipped.
 
-## Basic Example
+## Quick Start
 ```ts
-import { connect } from 'itty-sockets'
-
-// connect to the channel
-const channel = connect('wss://example.com')
-
-channel
-  // log all messages
-  .on('message', e => console.log(e.message))
-
-  // send some messages
-  .send('hey!')
-  .send({ foo: 'bar' })
-```
-
-## Optional use with `itty.ws` public, privacy-first server
-`itty-sockets` has been designed to work with the public [itty.ws](https://itty.ws) service for even easier integrations.  With this path, it's possible to add realtime features without hosting a backend server at all.  We recommend using this for testing, prototyping, or simple projects. As your needs expand, you can always replace [itty.ws](https://itty.ws) with your own server(s) - nothing in the client changes.
-
-Using [itty.ws](https://itty.ws) channels provides a few features to the client (fully typed by passing the `UseItty` generic to `connect`):
+import { connect } from 'itty-sockets' // ~466 bytes
 
-1. `connect<UseItty>('my-channel')` - connect to a channel and go
-1. adds `uid`, `alias`, and `date` to all messages
-1. adds `join` and `leave` events to announce user changes
-1. allows private messaging (by uid)
-
-## Installation
-
-**Option 1: Import**
-```bash
-npm install itty-sockets
+connect('my-channel')
+  .on('message', ({ message }) => console.log(message))
+  .send('hello world')   // strings
+  .send([1, 2, 3])       // arrays
+  .send({ foo: 'bar' })  // objects
 ```
 
+## Chat Example
 ```ts
 import { connect } from 'itty-sockets'
-```
 
-**Option 2: Just copy this snippet:**
-<!-- BEGIN SNIPPET -->
-```ts
-let connect=(e,s={})=>{let a,t,n=[],p={},o=()=>(a||(a=new WebSocket((/^wss?:/.test(e)?e:"wss://itty.ws/c/"+e)+"?"+new URLSearchParams(s)),a.onmessage=(e,s=JSON.parse(e.data),a=s?.message,t={...null==a?.[0]&&a,...s})=>[t.type,s.type?0:"message","*"].map(e=>p[e]?.map(e=>e(t))),a.onopen=()=>(n.splice(0).map(e=>a.send(e)),p.open?.map(e=>e(t)),t&&a?.close()),a.onclose=()=>(t=a=null,p.close?.map(e=>e(t)))),l),l={open:o,send:(e,s)=>(e=(s?`${s}`:"")+JSON.stringify(e),1&a?.readyState?a.send(e):n.push(e),o()),on:(e,s)=>((p[e?.[0]?e:"*"]??=[]).push(e?.[0]?s:a=>e?.(a)&&s(a)),o()),remove:(e,s)=>(p[e]=p[e]?.filter(e=>e!=s),l),close:()=>(1&a?.readyState?a.close():t=1,l),push:(e,s)=>(t=1,l.send(e,s))};return l};
-```
-<!-- END SNIPPET -->
-*Note: This will lose TypeScript support.*
+// two users, same channel
+const alice = connect('chat-room', { as: 'Alice' })
+const bob   = connect('chat-room', { as: 'Bob' })
 
-## Example 2 - Receiving basic messages
-Assume the following simple client
-```ts
-import { connect } from 'itty-sockets'
+alice.on('message', ({ message, alias }) =>
+  console.log(`${alias}: ${message}`)
+)
 
-connect('wss://example.com')
-
-  // listen for every message
-  .on('message', console.log)
-
-  // and just { type: 'chat' }
-  .on('chat',
-    ({ user, text }) => console.log(`${user} says: ${text}`)
-  )
-```
-
-Now let's assume the following 2 messages are sent:
-```json
-// message 1
-{
-  "type": "chat",
-  "user": "Kevin",
-  "text": "Hey!"
-}
+bob.send('hey Alice!')
+// → "Bob: hey Alice!"
 ```
 
-```json
-// message 2
-{
-  "date": 1754659171196,
-  "items": [1, 2, 3],
-}
-```
-
-This will output the following to the console:
-```js
-// message 1
-{ type: "chat", user: "Kevin", text: "Hey!" }
-"Kevin says: Hey!"
-
-// message 2
-{ date: 1754659171196, items: [1, 2, 3] }
-```
-
-## Example 3 - Reconnection
-Using `itty-sockets`, you can safely fire `.open()` on the connection at any time, even if already connected.  All listeners will continue to work perfectly once reconnected.
-
-```ts
-const channel = connect('wss://example.com')
-                  .on('message', console.log)
-                  .on('open', () => console.log('connected'))
-                  .on('close', () => console.log('disconnected'))
-
-// we'll just reconnect every second - this is safe!
-setInterval(channel.open, 1000)
-```
+## API at a Glance
 
-## See the [full documentation](https://itty.dev/itty-sockets) to continue your journey!
+| Method | Description |
+|---|---|
+| `connect(channel, options?)` | Connect to a channel (or raw `wss://` URL) |
+| `.on(type, listener)` | Listen for events (`'message'`, `'join'`, `'leave'`, `'open'`, `'close'`, `'error'`, custom types, or `'*'`) |
+| `.on(filterFn, listener)` | Listen with a custom filter function |
+| `.send(message, uid?)` | Send a message (optionally to a specific user) |
+| `.push(message, uid?)` | Send a message and disconnect |
+| `.open()` | (Re)connect — safe to call anytime, listeners are preserved |
+| `.close()` | Disconnect |
+| `.remove(type, listener)` | Remove a listener |
 
+## See the [full documentation](https://itty.ws/docs) for more!

package/connect.d.ts

@@ -15,11 +15,17 @@ export type MessageEvent<T = any> = {
 } & EventBase;
 export type JoinEvent = {
     type: 'join';
-    users: number;
+    total: number;
+    self?: boolean;
+    users?: {
+        uid: string;
+        alias?: string;
+        self?: boolean;
+    }[];
 } & EventBase;
 export type LeaveEvent = {
     type: 'leave';
-    users: number;
+    total: number;
 } & EventBase;
 export type ErrorEvent = {
     type: 'error';
@@ -30,6 +36,7 @@ export type IttySocketOptions = {
     alias?: string;
     echo?: true;
     announce?: true;
+    list?: true;
 };
 type EventUnion<Events> = {
     [K in Exclude<keyof Events & string, 'message'>]: {
@@ -49,7 +56,7 @@ export type IttySocket<Base = object, Events extends Record<string, any> = Empty
     close: () => IttySocket<Base, Events>;
     send: SendFn<Base, Events>;
     push: SendFn<Base, Events>;
-    remove(type: string, listener: () => any): IttySocket<Base, Events>;
+    remove(type: string, listener: (...args: any[]) => any): IttySocket<Base, Events>;
     on(type: 'open', listener: () => any): IttySocket<Base, Events>;
     on(type: 'close', listener: () => any): IttySocket<Base, Events>;
     on<K extends keyof Events & string>(type: K, listener: (event: Base & Events[K] & {
@@ -63,8 +70,7 @@ export type IttySocket<Base = object, Events extends Record<string, any> = Empty
     on(type: 'join', listener: (event: JoinEvent) => any): IttySocket<Base, Events>;
     on(type: 'leave', listener: (event: LeaveEvent) => any): IttySocket<Base, Events>;
     on(type: 'error', listener: (event: ErrorEvent) => any): IttySocket<Base, Events>;
-} : object) & {
-    on<T = Record<string, any>>(type: string, listener: (event: Base & T & {
+    on<T = Record<string, any>, K extends string = string>(type: K extends 'open' | 'close' | 'message' | 'join' | 'leave' | 'error' | keyof Events ? never : K, listener: (event: Base & T & {
         type: string;
         message: T;
     }) => any): IttySocket<Base, Events>;
@@ -72,6 +78,15 @@ export type IttySocket<Base = object, Events extends Record<string, any> = Empty
         type: string;
         message: T;
     }) => any): IttySocket<Base, Events>;
-};
+} : {
+    on<T = Record<string, any>, K extends string = string>(type: K extends 'open' | 'close' | 'message' | keyof Events ? never : K, listener: (event: Base & T & {
+        type: string;
+        message: T;
+    }) => any): IttySocket<Base, Events>;
+    on<T = Record<string, any>>(type: (event?: any) => any, listener: (event: Base & T & {
+        type: string;
+        message: T;
+    }) => any): IttySocket<Base, Events>;
+});
 export declare let connect: IttySocketConnect;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itty-sockets",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "WebSockets : simplified and minified.",
   "type": "module",
   "exports": {