itty-sockets 0.5.2 → 0.5.4

package/README.md

@@ -16,43 +16,46 @@
 
 ---
 
-Tiny realtime messaging client in under 500 bytes.  **No backend needed.**
+# WebSockets : simplified and minified.
 
-## What does this solve?
-
-Itty Sockets simplifies sending/receiving realtime data.
+Zero-config.  Pick a channel and go.
+```ts
+// CLIENT 1 (listens for messages)
+connect('unique-channel-name')
+  // listen for all messages
+  .on('message', e => console.log(e.message))
 
-By pairing an ultra-tiny client (this) with the public **[ittysockets.io](https://ittysockets.io)** backend, you
-can focus on sending/receiving messages, instead of building a transport layer.
+  // or just our custom messages
+  .on('my-chat-message', ({ user, text }) => console.log(user, 'says:', text))
+```
 
-The idea is simple:
+```ts
+// CLIENT 2 (sends messages)
+const channel = connect('unique-channel-name')
+  .send({ foo: 'bar' })
+  .send({ type: 'my-chat-message', user: 'Halsey', text: 'Meow!' })
 
-1. One or more parties connect to a channel (by name).
-2. They send/receive messages (this can be anything) in the channel.
-3. That's it!
 
-# Example
-```ts
-import { connect } from 'itty-sockets'
+channel.send('what else can this do?')
+```
 
-// connect to a channel
-const foo = connect('my-secret-room-name')
 
-foo
-  // we can listen for messages
-  .on('message', e => console.log(e.message))
+## Or simply use `connect` as a tiny WebSocket client that brings the following:
 
-  // and/or send some
-  .send('Hello World!')     // "Hello World!"
-  .send([1, 2, 3])          // [1, 2, 3]
-  .send({ foo: 'bar' })     // { foo: "bar" }
-```
+- JSON parsing/stringifying
+- message queing - sending automatically connects and queue is flushed on open
+- easy reconnection (listeners keep working)
+- custom listeners/filters
+- chainable syntax (it's just handy)
 
-### Important Considerations
+```ts
+const ws = connect('wss://somewhere.else')
+             .on('message', console.log) // log all messages
+             .send({ foo: 'bar' }) // send immediately, no waiting
 
-1. **There is no history/replay/storage.**  It's a live stream only.
-2. **We don't authenticate.**  [ittysockets.io](https://ittysockets.io) leverages security through obfuscation (a near-infinite number of channel names).  Choose a more unique channel for more privacy.  Need more?  Consider encrypting/decrypting your payloads before transmission (this is easy).
-3. **There are no guarantees of delivery.**  While [ittysockets.io](https://ittysockets.io) is *extremely* stable, it's a free public service that is provided without any guarantees of delivery or uptime.  Manage risk accordingly.
+// optional - reconnect every second (no effect if open)
+setInterval(ws.open, 1000)
+```
 
 <br />
 
@@ -66,7 +69,7 @@ import { connect } from 'itty-sockets'
 ...or simply paste this into your environment/console:
 <!-- BEGIN SNIPPET -->
 ```ts
-let connect=(e,s={})=>{let o,t=0,n=[],a={},r=()=>(o||(o=new WebSocket((/^wss?:/.test(e)?e:"wss://ittysockets.io/c/"+e)+"?"+new URLSearchParams(s)),o.onclose=()=>{t=0,o=null;for(let e of a.close??[])e()},o.onopen=()=>{for(;n.length;)o?.send(n.shift());for(let e of a.open??[])e();t&&o?.close()},o.onmessage=(e,s=JSON.parse(e.data))=>{for(let e of a[s.type??"message"]??[])e({...s,date:new Date(s.date)})}),l);const l=new Proxy(r,{get:(e,s)=>({close:()=>(1==o?.readyState?o.close():t=1,l),open:r,send:(e,s)=>(e=JSON.stringify(e),e=s?"@@"+s+"@@"+e:e,1==o?.readyState?(o.send(e),l):(n.push(e),r())),push:(e,s)=>(t=1,l.send(e,s)),on:(e,s)=>((a[e]??=[]).push(s),r()),remove:(e,s,o=a[e],t=o?.indexOf(s)??-1)=>(~t&&o?.splice(t,1),r())}[s])});return l};
+let connect=(e,s={})=>{let t,a=0,n=[],p=[],o={},l=()=>(t||(t=new WebSocket((/^wss?:/.test(e)?e:"wss://ittysockets.io/c/"+e)+"?"+new URLSearchParams(s)),t.onmessage=(e,s=JSON.parse(e.data),t=s?.message,a={...null==t?.[0]&&t,...s,...s.date&&{date:new Date(s.date)}})=>{o[s?.type??t?.type]?.map(e=>e(a)),s?.type||o.message?.map(e=>e(a)),p.map(([e,s])=>e(a)&&s(a))},t.onopen=()=>(n.splice(0).map(e=>t?.send(e)),o.open?.map(e=>e()),a&&t?.close()),t.onclose=()=>(a=0,t=null,o.close?.map(e=>e()))),c),c=new Proxy(l,{get:(e,s)=>({open:l,close:()=>(1==t?.readyState?t.close():a=1,c),push:(e,s)=>(a=1,c.send(e,s)),send:(e,s)=>(e=JSON.stringify(e),e=s?"@@"+s+"@@"+e:e,1==t?.readyState?(t.send(e),c):(n.push(e),l())),on:(e,s)=>(s&&(e?.[0]?(o[e]??=[]).push(s):p.push([e,s])),l()),remove:(e,s,t=o[e],a=t?.indexOf(s)??-1)=>(~a&&t?.splice(a,1),l())}[s])});return c};
 ```
 <!-- END SNIPPET -->
 
@@ -81,17 +84,17 @@ To start, simply connect to a channel based on a unique name (this can be anythi
 import { connect } from 'itty-sockets'
 
 // basic connection
-const channel = connect('my-channels/my-super-secret-channel')
+const channel = connect('my-super-secret-channel')
 
 // with options
-const channel = connect('my-channels/my-super-secret-channel', {
-                  as: 'Kevin',
-                  announce: true,
-                  echo: true
+const channel = connect('my-super-secret-channel', {
+                  alias: 'Kevin', // optional non-unique identifier, visible in messages
+                  announce: true, // shares your uid/alias with the channel on joining
+                  echo: true      // echos your own messages back to you (for testing)
                 })
 
-// an external server
-const channel = connect('wss://somewhere.else/entirely')
+// or any external JSON WebSocket server
+const channel = connect('wss://somewhere.else.entirely')
 ```
 
 #### Connection Options

package/connect.cjs

@@ -0,0 +1 @@
+"use strict";exports.connect=(e,s={})=>{let t,a=0,n=[],p=[],o={},c=()=>(t||(t=new WebSocket((/^wss?:/.test(e)?e:"wss://ittysockets.io/c/"+e)+"?"+new URLSearchParams(s)),t.onmessage=(e,s=JSON.parse(e.data),t=s?.message,a={...null==t?.[0]&&t,...s,...s.date&&{date:new Date(s.date)}})=>{o[s?.type??t?.type]?.map(e=>e(a)),s?.type||o.message?.map(e=>e(a)),p.map(([e,s])=>e(a)&&s(a))},t.onopen=()=>(n.splice(0).map(e=>t?.send(e)),o.open?.map(e=>e()),a&&t?.close()),t.onclose=()=>(a=0,t=null,o.close?.map(e=>e()))),l),l=new Proxy(c,{get:(e,s)=>({open:c,close:()=>(1==t?.readyState?t.close():a=1,l),push:(e,s)=>(a=1,l.send(e,s)),send:(e,s)=>(e=JSON.stringify(e),e=s?"@@"+s+"@@"+e:e,1==t?.readyState?(t.send(e),l):(n.push(e),c())),on:(e,s)=>(s&&(e?.[0]?(o[e]??=[]).push(s):p.push([e,s])),c()),remove:(e,s,t=o[e],a=t?.indexOf(s)??-1)=>(~a&&t?.splice(a,1),c())}[s])});return l};

package/connect.d.ts

@@ -12,7 +12,7 @@ type OptionalUserDetails = {
 };
 export type MessageEvent<MessageType = any> = {
     message: MessageType;
-} & Date & UserDetails;
+} & Date & UserDetails & MessageType;
 export type JoinEvent = {
     type: 'join';
     users: number;
@@ -32,11 +32,16 @@ export type IttySocket = {
     connected: boolean;
     send: SendMessage;
     push: SendMessage;
-    on<MessageFormat = any>(type: 'message', listener: (event: MessageEvent<MessageFormat>) => any): IttySocket;
     on(type: 'join', listener: (event: JoinEvent) => any): IttySocket;
     on(type: 'leave', listener: (event: LeaveEvent) => any): IttySocket;
     on(type: 'error', listener: (event: ErrorEvent) => any): IttySocket;
-    on(type: Exclude<IttySocketEvent, 'message'>, listener: () => any): IttySocket;
+    on<MessageFormat = any>(type: 'message', listener: (event: MessageEvent<MessageFormat>) => any): IttySocket;
+    on<MessageFormat = any>(type: string, listener: (event: MessageEvent<MessageFormat & {
+        type: string;
+    }>) => any): IttySocket;
+    on<MessageFormat = any>(type: (event?: any) => any, listener: (event: MessageEvent<MessageFormat & {
+        type: string;
+    }>) => any): IttySocket;
     remove(type: IttySocketEvent, listener: () => any): IttySocket;
 };
 export type IttySocketOptions = {
@@ -45,5 +50,5 @@ export type IttySocketOptions = {
     echo?: true;
     announce?: true;
 };
-export declare const connect: (channelId: string, options?: IttySocketOptions) => IttySocket;
+export declare let connect: (channelId: string, options?: IttySocketOptions) => IttySocket;
 export {};

package/connect.mjs

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

package/package.json

@@ -1,39 +1,27 @@
 {
   "name": "itty-sockets",
-  "version": "0.5.2",
-  "description": "Tiny realtime messaging client in under 450 bytes.  No backend needed.",
+  "version": "0.5.4",
+  "description": "WebSockets : simplified and minified.",
   "type": "module",
   "exports": {
     ".": {
-      "import": "./index.mjs",
-      "require": "./index.js",
-      "types": "./index.d.ts"
-    },
-    "./connect": {
       "import": "./connect.mjs",
-      "require": "./connect.js",
-      "types": "./connect.d.ts"
+      "types": "./connect.d.ts",
+      "require": "./connect.cjs"
     }
   },
   "scripts": {
-    "dev": "bun test --watch",
-    "lint": "bun eslint src",
-    "verify": "echo 'verifying module...' && bun run build && bun test",
-    "prerelease": "bun run verify",
-    "prerelease:next": "bun run verify",
-    "prebuild": "rimraf dist && mkdir dist",
-    "build": "rollup -c && bun readme-inject.mjs",
-    "release": "release --tag --push --patch --src=dist",
-    "release:next": "release --tag --push --type=next --src=dist"
+    "dev": "bun test --watch --coverage",
+    "test": "bun test --coverage",
+    "lint": "itty lint",
+    "build": "itty lint && itty build --snippet=connect --hybrid",
+    "release": "itty release --prepare --tag --push",
+    "release:next": "itty release --prepare --tag --push --type=next"
   },
   "keywords": [
     "websockets",
     "realtime",
-    "public",
-    "messages",
-    "tiny",
-    "free",
-    "p2p"
+    "client"
   ],
   "repository": {
     "type": "git",
@@ -45,18 +33,7 @@
     "url": "https://github.com/kwhitley/itty-sockets/issues"
   },
   "devDependencies": {
-    "@rollup/plugin-terser": "^0.4.4",
-    "@rollup/plugin-typescript": "^11.1.6",
     "@types/bun": "^1.2.3",
-    "@typescript-eslint/eslint-plugin": "^8.18.0",
-    "@typescript-eslint/parser": "^8.18.0",
-    "eslint": "^9.17.0",
-    "globby": "^14.1.0",
-    "rimraf": "^6.0.1",
-    "rollup": "^4.28.1",
-    "rollup-plugin-bundle-size": "^1.0.3",
-    "rollup-plugin-copy": "^3.5.0",
-    "typescript": "^5.7.2",
-    "yarn-release": "^1.10.6"
+    "itty-packager": "^1.6.7"
   }
 }

package/connect.js

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

package/index.d.ts

@@ -1 +0,0 @@
-export * from './connect';

package/index.js

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

package/index.mjs

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