itty-sockets 0.1.0 → 0.2.0

package/README.md

@@ -20,45 +20,28 @@ Tiny messaging client in under 400 bytes.  No backend needed.
 
 ## Example (using ittysockets.io public channels)
 ```ts
-import { connect } from 'itty-sockets' // ~400 bytes
+import { connect } from 'itty-sockets' // ~340 bytes
 
-// create a channel instance
-const foo = connect('foo', { echo: true }) // echo messages back to sender
+// connect to a channel (optionally echo messages back to yourself)
+const foo = connect('my-secret-room-name', { echo: true })
 
-// listen for messages
-foo.listen(e => {
-  console.log(e.alias ?? e.uid, 'says', e.message, 'at', e.date)
-})
-
-// send some messages
 foo
-  .send('hello world!')
-  .send([1,2,3]) // no need to stringify
-  .send({ foo: 'bar' })
-
-// or connect, send, and close - all in one call
-foo.push('this will open, send, and close the connection')
-```
-
-## Example (other WebSocket servers)
-```ts
-import { ws } from 'itty-sockets' // ~340 bytes
-
-const foo = ws('wss://example.com', { json: true })
+  // we can listen for messages
+  .on('message', e => console.log(e.message))
 
-foo
-  .listen(console.log) // this will auto-parse JSON messages from the server
-  .send('hello world!')
-  .send([1,2,3])
-  .send({ foo: 'bar' })
+  // 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.
-- Prevents WebSocket race conditions.
 - 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?
@@ -82,11 +65,11 @@ There is intentionally no message logging or tracking of any kind.  It's easier
 
 ## Browser Usage
 
-If you want to send/receive messages from the browser (e.g. for sending information from one web page or tab to another), copy and paste this snippet directly into your browser console, then use as normal.
+For use in browser/DevTools scripting, copy and paste this snippet directly into your browser console, then use as normal:
 
 <!-- BEGIN SNIPPET -->
 ```ts
-let connect=(e,s={})=>{let t,n=[],o=[],a=0,r=()=>{t||(t=new WebSocket(`wss://ittysockets.io/r/${e??""}?${new URLSearchParams(s)}`),t.onopen=()=>{for(;n.length;)t?.send(n.shift());a&&t?.close()},t.onmessage=(e,s=JSON.parse(e.data))=>{for(let e of o)e({...s,date:new Date(s.date)})},t.onclose=()=>(a=0,t=null))};return new Proxy(r,{get:(e,s,l)=>({ws:t,send:(e,s)=>(e=JSON.stringify(e),e=s?`@@${s}@@${e}`:e,1==t?.readyState?t.send(e)??l:(n.push(e),r()??l)),push:(e,s)=>(a=1,l.send(e,s)),listen:(e,s)=>(o.push((t=>(!s||s(t))&&e(t))),r()??l),close:()=>(1==t?.readyState?t.close():a=1,l)}[s])})};
+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};
 ```
 <!-- END SNIPPET -->
 
@@ -100,11 +83,15 @@ connect('foo').push('hello world!')
 
 | METHOD | DESCRIPTION | EXAMPLE |
 | --- | --- | --- |
-| **connect(id, options)** | Creates a new connect | `connect('foo')` |
-| **send(message)** | Sends a message to the room | `room.send({ type: 'chat', text: 'hello' })` |
-| **push(message)** | Sends a message and closes the connection | `room.push({ type: 'goodbye' })` |
-| **listen(fn)** | Adds a message listener | `room.listen(msg => console.log(msg))` |
-| **close()** | Closes the connection | `room.close()` |
+| **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 room | `channel.send({ type: 'chat', text: 'hello' })` |
+| **.push(message)** | Sends a message and closes the connection | `channel.push({ type: 'goodbye' })` |
+| **.on('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
 
@@ -114,10 +101,12 @@ connect('foo').push('hello world!')
 | **echo** | Whether to echo messages back to the sender | `false` | `{ echo: true }` |
 
 
-## Message Format
+## MessageEvent Format
 ```ts
-type Message = {
+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
 }

package/connect.d.ts

@@ -1,16 +1,22 @@
-export type AllowedProperty = 'ws' | 'send' | 'push' | 'listen' | 'close';
+export type AllowedProperty = 'open' | 'close' | 'send' | 'push' | 'on';
 export type MessageEvent<MessageType = any> = {
     date: Date;
     uid?: string;
     alias?: string;
     message: MessageType;
 };
-export type SendMessage = <MessageFormat = any>(message: MessageFormat, recipient?: string) => Connection;
-export type Connection = {
-    ws?: WebSocket;
+export type SendMessage = <MessageFormat = any>(message: MessageFormat, recipient?: string) => IttySocket;
+export type IttySocket = {
+    open: () => IttySocket;
+    close: () => IttySocket;
+    connected: boolean;
     send: SendMessage;
     push: SendMessage;
-    listen: <MessageType = any>(listener: (event: MessageEvent<MessageType>) => any, when?: (event: MessageEvent<MessageType>) => any) => Connection;
-    close: () => Connection;
+    on: <T extends string, MessageType = any>(type: T, listener: T extends 'message' ? (event: MessageEvent<MessageType>) => any : () => any) => IttySocket;
 };
-export declare const connect: (id: string, options?: Record<string, any>) => Connection;
+export type IttySocketOptions = {
+    as?: string;
+    alias?: string;
+    echo?: boolean;
+};
+export declare const connect: (id: string, options?: IttySocketOptions) => IttySocket;

package/connect.js

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

package/connect.mjs

@@ -1 +1 @@
-const e=(e,s={})=>{let t,n=[],o=[],a=0,r=()=>{t||(t=new WebSocket(`wss://ittysockets.io/r/${e??""}?${new URLSearchParams(s)}`),t.onopen=()=>{for(;n.length;)t?.send(n.shift());a&&t?.close()},t.onmessage=(e,s=JSON.parse(e.data))=>{for(let e of o)e({...s,date:new Date(s.date)})},t.onclose=()=>(a=0,t=null))};return new Proxy(r,{get:(e,s,l)=>({ws:t,send:(e,s)=>(e=JSON.stringify(e),e=s?`@@${s}@@${e}`:e,1==t?.readyState?t.send(e)??l:(n.push(e),r()??l)),push:(e,s)=>(a=1,l.send(e,s)),listen:(e,s)=>(o.push((t=>(!s||s(t))&&e(t))),r()??l),close:()=>(1==t?.readyState?t.close():a=1,l)}[s])})};export{e as connect};
+const e=(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};export{e as connect};

package/connect.snippet.js

@@ -1 +1 @@
-let connect=(e,s={})=>{let t,n=[],o=[],a=0,r=()=>{t||(t=new WebSocket(`wss://ittysockets.io/r/${e??""}?${new URLSearchParams(s)}`),t.onopen=()=>{for(;n.length;)t?.send(n.shift());a&&t?.close()},t.onmessage=(e,s=JSON.parse(e.data))=>{for(let e of o)e({...s,date:new Date(s.date)})},t.onclose=()=>(a=0,t=null))};return new Proxy(r,{get:(e,s,l)=>({ws:t,send:(e,s)=>(e=JSON.stringify(e),e=s?`@@${s}@@${e}`:e,1==t?.readyState?t.send(e)??l:(n.push(e),r()??l)),push:(e,s)=>(a=1,l.send(e,s)),listen:(e,s)=>(o.push((t=>(!s||s(t))&&e(t))),r()??l),close:()=>(1==t?.readyState?t.close():a=1,l)}[s])})};
+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};

package/index.d.ts

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

package/index.js

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

package/index.mjs

@@ -1 +1 @@
-const e=(e,s={})=>{let t,n=[],o=[],a=0,r=()=>{t||(t=new WebSocket(`wss://ittysockets.io/r/${e??""}?${new URLSearchParams(s)}`),t.onopen=()=>{for(;n.length;)t?.send(n.shift());a&&t?.close()},t.onmessage=(e,s=JSON.parse(e.data))=>{for(let e of o)e({...s,date:new Date(s.date)})},t.onclose=()=>(a=0,t=null))};return new Proxy(r,{get:(e,s,l)=>({ws:t,send:(e,s)=>(e=JSON.stringify(e),e=s?`@@${s}@@${e}`:e,1==t?.readyState?t.send(e)??l:(n.push(e),r()??l)),push:(e,s)=>(a=1,l.send(e,s)),listen:(e,s)=>(o.push((t=>(!s||s(t))&&e(t))),r()??l),close:()=>(1==t?.readyState?t.close():a=1,l)}[s])})},s=(e,s={})=>{let t,n=[],o=[],a=0,r=()=>{t||(t=new WebSocket(e),t.onopen=()=>{for(;n.length;)t?.send(n.shift());a&&t?.close()},t.onmessage=(e,t=(s.json?JSON.parse(e.data):e.data))=>{for(let e of o)e(t)},t.onclose=()=>(a=0,t=null))};return new Proxy(r,{get:(e,l,d)=>({ws:t,send:e=>(e=s.json?JSON.stringify(e):e,1==t?.readyState?t.send(e)??d:(n.push(e),r()??d)),push:e=>(a=1,d.send(e)),listen:(e,s)=>(o.push((t=>(!s||s(t))&&e(t))),r()??d),close:()=>(1==t?.readyState?t.close():a=1,d)}[l])})};export{e as connect,s as ws};
+const e=(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};export{e as connect};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itty-sockets",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "An easier way to handle WebSockets, in an itty package.",
   "main": "./sockets.js",
   "module": "./sockets.mjs",
@@ -56,11 +56,6 @@
       "import": "./connect.mjs",
       "require": "./connect.js",
       "types": "./connect.d.ts"
-    },
-    "./ws": {
-      "import": "./ws.mjs",
-      "require": "./ws.js",
-      "types": "./ws.d.ts"
     }
   }
 }

package/ws.d.ts

@@ -1,13 +0,0 @@
-type SendMessage = <MessageFormat = any>(message: MessageFormat) => Connection;
-export type Connection = {
-    ws?: WebSocket | null;
-    send: SendMessage;
-    push: SendMessage;
-    listen: <MessageType = any>(listener: (message: MessageType) => any, when?: (message: MessageType) => any) => Connection;
-    close: () => Connection;
-};
-export type ConnectionOptions = {
-    json?: boolean;
-};
-export declare const ws: (url: string, options?: ConnectionOptions) => Connection;
-export {};

package/ws.js

@@ -1 +0,0 @@
-"use strict";exports.ws=(e,s={})=>{let t,n=[],o=[],r=0,a=()=>{t||(t=new WebSocket(e),t.onopen=()=>{for(;n.length;)t?.send(n.shift());r&&t?.close()},t.onmessage=(e,t=(s.json?JSON.parse(e.data):e.data))=>{for(let e of o)e(t)},t.onclose=()=>(r=0,t=null))};return new Proxy(a,{get:(e,l,d)=>({ws:t,send:e=>(e=s.json?JSON.stringify(e):e,1==t?.readyState?t.send(e)??d:(n.push(e),a()??d)),push:e=>(r=1,d.send(e)),listen:(e,s)=>(o.push((t=>(!s||s(t))&&e(t))),a()??d),close:()=>(1==t?.readyState?t.close():r=1,d)}[l])})};

package/ws.mjs

@@ -1 +0,0 @@
-const e=(e,s={})=>{let n,o=[],t=[],a=0,l=()=>{n||(n=new WebSocket(e),n.onopen=()=>{for(;o.length;)n?.send(o.shift());a&&n?.close()},n.onmessage=(e,n=(s.json?JSON.parse(e.data):e.data))=>{for(let e of t)e(n)},n.onclose=()=>(a=0,n=null))};return new Proxy(l,{get:(e,r,d)=>({ws:n,send:e=>(e=s.json?JSON.stringify(e):e,1==n?.readyState?n.send(e)??d:(o.push(e),l()??d)),push:e=>(a=1,d.send(e)),listen:(e,s)=>(t.push((n=>(!s||s(n))&&e(n))),l()??d),close:()=>(1==n?.readyState?n.close():a=1,d)}[r])})};export{e as ws};