itty-sockets 0.6.0 → 0.7.0

package/.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: kwhitley
+open_collective: kevinrwhitley
+# patreon: # Replace with a single Patreon username
+# ko_fi: # Replace with a single Ko-fi username
+# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+# liberapay: # Replace with a single Liberapay username
+# issuehunt: # Replace with a single IssueHunt username
+# otechie: # Replace with a single Otechie username
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/.github/workflows/coverage.yml

@@ -0,0 +1,25 @@
+on: [push, pull_request]
+
+name: test
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2.0.1
+
+      - name: Clean workspace and run tests
+        run: |
+          git clean -xfd       # Remove all untracked files, including stale tests
+          bun install
+          bun test --coverage --coverage-reporter=text --coverage-reporter=lcov
+
+      - name: Coveralls
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/lint.yml

@@ -0,0 +1,19 @@
+name: lint
+
+on:
+  push:
+    branches: [v0.x]
+  pull_request:
+    branches: [v0.x]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: oven-sh/setup-bun@v2.0.1
+      - name: install dependencies
+        run: bun install
+      - name: lint
+        run: bun run lint

package/.github/workflows/verify.yml

@@ -0,0 +1,19 @@
+name: verify
+
+on:
+  push:
+    branches: [v0.x]
+  pull_request:
+    branches: [v0.x]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: oven-sh/setup-bun@v2.0.1
+      - name: Install dependencies
+        run: bun install
+      - name: Build
+        run: bun run build

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+## Changelog
+CAUTION: Pre v1.0.0, this should be considered an alpha release, with minor updates allowing for breaking changes to the interface.
+#### v0.7.0
+- added: .on('*', listener) to respond to *any* messages (e.g. normal, custom, join, leave, error, etc)
+#### v0.6.0
+- added: .on('custom-type', listener) support, keying off payload.type
+- added: .on(filterFunction, listener) support to route listeners based on custom payload rules
+- added: .on('message', listener) still works, catching *all* user-sent messages
+- added: full TypeScript generics support for .on and .send functions
+- added: for convenience, we now destructure the message payload into the top-level event (before the event props)
+- breaking: removed Date casting of event.date, now left as numeric timestamp
+#### v0.5.0
+- BREAKING: removed base (url) option - instead, simply pass a full wss:// path as the channelId to use an external compatible server.
+#### v0.4.0
+- added: base (url) option
+#### v0.3.1
+- fixes: module export
+- removes extra NPM files
+#### v0.3.0
+- breaking: every event has multiple listeners (previously only on('message') allowed multiple)
+- added: join/leave/error event types
+- added: .remove('event-name', listener) to remove listeners
+#### v0.2.3
+- fix type hinting on listeners
+- improve type hinting on send/push
+#### v0.2.0
+- alpha release 2
+#### v0.1.0
+- alpha release 1

package/README.md

@@ -18,32 +18,19 @@
 
 ---
 
-### The last WebSocket client you'll need : 512 bytes, all-in.
+### Say goodbye to WebSocket boilerplate.
+
+Your own wrapper is bigger, I promise.
+
+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).
 
 ## Features ✨
-1. **DX perks** - JSON-in/out, queued messages, easy-reconnect, chainable everything.
-1. **Works with any JSON-based WebSocket server**
-1. **Powerful Routing**
-   - Listen for all messages
-     ```ts
-     .on('message', data => console.log(data))
-     ```
-   - Only specific types
-     ```ts
-     // matches any data with { type: 'chat' }
-     .on('chat', ({ text }) => console.log(text))
-     ```
-   - or fully custom filters
-     ```ts
-     // matches only messages where data.value > 20
-     .on(
-       ({ value }) => value > 20), // filter function
-       ({ value }) => console.log(value),
-     )
-     ```
-1. **Type-safe message handling**
-1. **Tiny footprint** - 512 bytes, all-in.
-1. **Optional usage with free/public/zero-config [itty.ws](https://itty.ws) service**
+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
 
 ## Basic Example
 ```ts
@@ -85,7 +72,7 @@ import { connect } from 'itty-sockets'
 **Option 2: Just copy this snippet:**
 <!-- BEGIN SNIPPET -->
 ```ts
-let connect=(e,s={})=>{let p,a=0,n=[],t=[],o={},l=()=>(p||(p=new WebSocket((/^wss?:/.test(e)?e:"wss://itty.ws/c/"+e)+"?"+new URLSearchParams(s)),p.onmessage=(e,s=JSON.parse(e.data),p=s?.message,a={...null==p?.[0]&&p,...s})=>{o[s?.type??p?.type]?.map(e=>e(a)),s?.type||o.message?.map(e=>e(a)),t.map(([e,s])=>e(a)&&s(a))},p.onopen=()=>(n.splice(0).map(e=>p?.send(e)),o.open?.map(e=>e()),a&&p?.close()),p.onclose=()=>(a=0,p=null,o.close?.map(e=>e()))),m),m=new Proxy(l,{get:(e,s)=>({open:l,close:()=>(1==p?.readyState?p.close():a=1,m),push:(e,s)=>(a=1,m.send(e,s)),send:(e,s)=>(e=JSON.stringify(e),e=s?""+s+""+e:e,1==p?.readyState?(p.send(e),m):(n.push(e),l())),on:(e,s)=>(s&&(e?.[0]?(o[e]??=[]).push(s):t.push([e,s])),l()),remove:(e,s,p=o[e],a=p?.indexOf(s)??-1)=>(~a&&p?.splice(a,1),l())}[s])});return m};
+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.*
@@ -101,13 +88,14 @@ connect('wss://example.com')
   .on('message', console.log)
 
   // and just { type: 'chat' }
-  .on('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",
@@ -116,6 +104,7 @@ Now let's assume the following 2 messages are sent:
 ```
 
 ```json
+// message 2
 {
   "date": 1754659171196,
   "items": [1, 2, 3],
@@ -123,12 +112,13 @@ Now let's assume the following 2 messages are sent:
 ```
 
 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] }
-
-"Kevin says: Hey!"
 ```
 
 ## Example 3 - Reconnection

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "itty-sockets",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "WebSockets : simplified and minified.",
   "type": "module",
   "exports": {
     ".": {
       "import": "./connect.mjs",
       "types": "./connect.d.ts",
-      "require": "./connect.cjs"
+      "require": "./connect.js"
     }
   },
   "scripts": {

package/src/connect.spec.ts

@@ -0,0 +1,570 @@
+import { describe, afterAll, expect, it, mock } from 'bun:test'
+import { connect, type IttySocket, type UseItty } from './connect'
+
+type TestLeaf = (args: {
+  channel: IttySocket<UseItty>,
+  resolve: () => void,
+  spy: () => void,
+  getChannel: (options?: any) => IttySocket<UseItty>
+}) => void
+
+type TestTree = {
+  [key: string]: TestTree | TestLeaf
+}
+
+type ChatMessage = {
+  type: 'chat',
+  user: string,
+  text: string,
+}
+
+const EXPOSED_METHODS = ['send', 'push', 'on', 'remove', 'close', 'open']
+const OPEN_CHANNELS: IttySocket[] = []
+
+const tests: TestTree = {
+  'NAMED EXPORTS': {
+    'import { connect } from "itty-sockets"': {
+      'is a function': () => expect(typeof connect).toBe('function'),
+    },
+  },
+  'connect(id, options?)': {
+    'constructs correct WebSocket URL': () => {
+      const originalWebSocket = global.WebSocket
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      const mockFn = mock((url: string) => ({}))
+
+      // @ts-ignore
+      global.WebSocket = mockFn
+
+      connect('my-channel', { a: 'b', c: 'd' } as any).open()
+      expect(mockFn.mock.calls[0][0]).toBe('wss://itty.ws/c/my-channel?a=b&c=d')
+
+      connect('ws://custom.server/path').open()
+      expect(mockFn.mock.calls[1][0]).toBe('ws://custom.server/path?')
+
+      connect('ws://custom.server/path', { echo: true, alias: 'test-user' }).open()
+      expect(mockFn.mock.calls[2][0]).toBe('ws://custom.server/path?echo=true&alias=test-user')
+
+      global.WebSocket = originalWebSocket
+    },
+    'exposes chainable method': EXPOSED_METHODS.reduce((acc, method) => {
+        acc[`.${method}()`] = ({ channel }) => {
+          expect(typeof channel[method]).toBe('function')
+          expect(channel[method]()).toBe(channel)
+        }
+        return acc
+      }, {} as Record<string, TestLeaf>),
+    'OPTIONS': {
+      '{ echo: true }': {
+        'sends messages back to sender': async ({ getChannel, resolve }) =>
+          getChannel({ echo: true })
+            .on('message', msg => {
+              expect(msg.message).toBe('test')
+              resolve()
+            })
+            .send('test'),
+      },
+      '{ alias: string }': {
+        'sets alias for messages': async ({ getChannel, resolve }) =>
+          getChannel({ echo: true, alias: 'test-user' })
+            .on('message', msg => {
+              expect(msg.alias).toBe('test-user')
+              resolve()
+            })
+            .send('test'),
+        'sets alias for join events if { announce: true } is set': async ({ getChannel, resolve }) =>
+          getChannel({ echo: true, alias: 'test-user', announce: true })
+            .on('join', ({ alias }) => {
+              expect(alias).toBe('test-user')
+              resolve()
+            }),
+      },
+      '{ as: string }': {
+        'sets alias for messages': async ({ getChannel, resolve }) =>
+          getChannel({ echo: true, as: 'test-user' })
+            .on('message', msg => {
+              expect(msg.alias).toBe('test-user')
+              resolve()
+            })
+            .send('test')
+      },
+      '{ announce: true }': {
+        'announces self to channel upon joining/leaving': async ({ getChannel, resolve }) =>
+          getChannel({ announce: true, as: 'test-user' })
+            .on('join', ({ alias }) => {
+              expect(alias).toBe('test-user')
+              resolve()
+            })
+      },
+    },
+    'METHODS': {
+      '.open()': {
+        'opens the socket': async ({ channel, resolve }) =>
+          channel
+            .on('open', resolve)
+            .open(),
+        'calling multiple times is fine': async ({ channel, resolve }) =>
+          channel
+            .on('open', () => {
+              channel.open() // one more time for good measure
+              resolve()
+            })
+            .open(),
+      },
+      '.close()': {
+        'closes the socket': async ({ channel, resolve }) =>
+          channel
+            .on('close', resolve)
+            .on('open', channel.close),
+        'calling multiple times is fine': async ({ channel, resolve }) =>
+          channel
+            .on('close',resolve)
+            .on('open', () => {
+              channel.close()
+              channel.close()
+            }),
+      },
+      '.on(\'open\', listener)': {
+        'registers an event listener that is called when the socket is opened': async ({ channel, resolve }) =>
+          channel
+            .on('open', resolve)
+            .open(),
+        'allows multiple listeners': async ({ channel, resolve, spy }) =>
+          channel
+            .on('open', spy)
+            .on('open', () => {
+              expect(spy).toHaveBeenCalled()
+              resolve()
+            }),
+      },
+      '.on(\'close\', listener)': {
+        'registers an event listener that is called when the socket is closed': async ({ channel, resolve }) =>
+          channel
+            .on('close', resolve)
+            .on('open', channel.close),
+        'allows multiple listeners': async ({ channel, resolve, spy }) =>
+          channel
+            .on('close', spy)
+            .on('close', () => {
+              expect(spy).toHaveBeenCalled()
+              resolve()
+            })
+            .on('open', channel.close),
+      },
+      '.on(\'message\', listener)': {
+        'registers an event listener that is called when a message is received': async ({ getChannel, resolve }) => {
+          getChannel({ echo: true })
+            .on('message', e => {
+              expect(e.message).toBe('test')
+              resolve()
+            })
+            .send('test')
+        },
+        'allows multiple message listeners': async ({ getChannel, resolve, spy }) =>
+          getChannel({ echo: true })
+            .on('message', spy)
+            .on('message', (e) => {
+              expect(e.message).toBe('test')
+              expect(spy).toHaveBeenCalled()
+              resolve()
+            })
+            .send('test'),
+        'receives message props on base message object': async ({ getChannel, resolve }) =>
+          getChannel({ echo: true })
+            .on<{ foo: string }>('message', (e) => {
+              expect(e.foo).toBe('bar')
+              expect(e.message.foo).toBe('bar')
+              resolve()
+            })
+            .send({ foo: 'bar' }),
+        'message props do not override event base props': async ({ getChannel, resolve }, date = new Date()) =>
+          getChannel({ echo: true, alias: 'test-user' })
+            .on<{ foo: string }>('message', (e) => {
+              expect(e.foo).toBe('bar')
+              // confirm types are correct
+              expect(e.uid).toBeTypeOf('string')
+              expect(e.alias).toBeTypeOf('string')
+              expect(e.date).toBeTypeOf('number')
+              // confirm props are not overridden
+              expect(e.uid).not.toBe('foo')
+              expect(e.alias).not.toBe('bar')
+              expect(e.date).not.toBe(+date)
+              resolve()
+            })
+            .send({ foo: 'bar', uid: 'foo', alias: 'bar', date }),
+        'base props not polluted by string messages': async ({ getChannel, resolve, spy }) =>
+          getChannel({ echo: true })
+            .on('message', spy)
+            .on('message', (e) => {
+              expect(e[0]).toBeUndefined() // "h" if polluted
+              expect(spy).toHaveBeenCalled()
+              resolve()
+            })
+            .send('hello'),
+        'base props not polluted by array messages': async ({ getChannel, resolve, spy }) =>
+          getChannel({ echo: true })
+            .on('message', spy)
+            .on('message', (e) => {
+              expect(e[0]).toBeUndefined() // "1" if polluted
+              expect(spy).toHaveBeenCalled()
+              resolve()
+            })
+            .send([1, 2, 3]),
+        'base props not polluted by numeric messages': async ({ getChannel, resolve, spy }) =>
+          getChannel({ echo: true })
+            .on('message', spy)
+            .on('message', (e) => {
+              expect(e[0]).toBeUndefined() // "?" if polluted
+              expect(spy).toHaveBeenCalled()
+              resolve()
+            })
+            .send(13),
+      },
+      '.on(\'join\', listener)': {
+        'registers an event listener that is called when a user (or self) joins the channel': async ({ channel, resolve }) =>
+          channel
+            .on('join', e => {
+              expect(e.users).toBe(1)
+              resolve()
+            }),
+        'does NOT include user details when { announce: true } is not set': async ({ channel, resolve }) =>
+          channel
+            .on('join', e => {
+              expect(e.uid).toBeUndefined()
+              expect(e.alias).toBeUndefined()
+              resolve()
+            }),
+        'DOES include user details when { announce: true } is set': async ({ getChannel, resolve }) =>
+          getChannel({ announce: true, alias: 'test-user' })
+            .on('join', e => {
+              expect(e.uid).not.toBeUndefined()
+              expect(e.alias).toBe('test-user')
+              resolve()
+            })
+      },
+      '.on(\'error\', listener)': {
+        'registers an event listener that is called when an error occurs': async ({ channel, resolve }) =>
+          channel
+            .on('error', e => {
+              expect(e.message).toContain('non-existent-user')
+              resolve()
+            })
+            .send('test', 'non-existent-user')
+      },
+      '.on(\'leave\', listener)': {
+        'registers an event listener that is called when a user leaves the channel': async ({ channel, getChannel,resolve }) => {
+            channel
+              .on('leave', e => {
+                expect(e.users).toBe(1)
+                resolve()
+              })
+              .on('open', () => {
+                getChannel().push('test') // trigger a join + leave
+              })
+        },
+        'does NOT include user details when { announce: true } is not set': async ({ channel, getChannel, resolve }) => {
+          channel
+            .on('leave', e => {
+              expect(e.uid).toBeUndefined()
+              expect(e.alias).toBeUndefined()
+              resolve()
+            })
+            .on('open', () => {
+              getChannel().push('test') // trigger a join + leave
+            })
+        },
+        'DOES include user details when { announce: true } is set': async ({ getChannel, resolve }) => {
+          getChannel()
+            .on('leave', e => {
+              expect(e.uid).not.toBeUndefined()
+              expect(e.alias).toBe('test-user')
+              resolve()
+            })
+            .on('open', () => {
+              getChannel({ announce: true, alias: 'test-user' }).push('test') // trigger a join + leave
+            })
+        }
+      },
+      '.on(\'{custom-type}\', listener)': {
+        'catches when message.type matches the custom type': async ({ getChannel, resolve }) => {
+           getChannel()
+             .on<{ user: string, text: string }>('chat', (e) => {
+                const { user, text } = e
+                expect(user).toBe('test-user')
+                expect(text).toBe('test')
+                expect(e.type).toBe('chat') // currently giving a TS error (incorrect)
+                expect(e.uid).toBeTypeOf('string')
+                expect(e.date).toBeTypeOf('number')
+                expect(e.user).toBe(e.message.user)
+                resolve()
+              })
+              .on('open', () => {
+                getChannel().send({ type: 'chat', user: 'test-user', text: 'test' })
+              })
+        },
+        'will still trigger "message" listeners': async ({ getChannel, resolve, spy }) =>
+          getChannel({ echo: true })
+            .on('message', spy)
+            .on('chat', () => {
+              setTimeout(() => {
+                expect(spy).toHaveBeenCalled()
+                resolve()
+              }, 5)
+            })
+            .send({ type: 'chat', user: 'test-user', text: 'test' }),
+        'will include custom payloads at top level and under e.message': async ({ getChannel, resolve, spy }) =>
+          getChannel({ echo: true })
+            .on('message', spy)
+            .on<ChatMessage>('chat', (e) => {
+               expect(e.type).toBe('chat')
+               expect(e.user).toBe('test-user')
+               expect(e.text).toBe('test')
+               expect(e.message.type).toBe('chat')
+               expect(e.message.user).toBe('test-user')
+               expect(e.message.text).toBe('test')
+               resolve()
+            })
+            .send({ type: 'chat', user: 'test-user', text: 'test' })
+      },
+      '.on(\'*\', listener)': {
+        'catches both typed and untyped events': async ({ getChannel, resolve }) => {
+          const received: any[] = []
+          getChannel({ echo: true })
+            .on('*', (e) => {
+              received.push(e)
+              if (received.length === 2) {
+                expect(received[0].type).toBe('join')
+                expect(received[1].message).toBe('test')
+                resolve()
+              }
+            })
+            .send('test')
+        },
+      },
+      '.on(eventFilter, listener)': {
+        'can accept a filter function as type': async ({ getChannel, resolve, spy }) =>
+          getChannel({ echo: true })
+            .on('message', spy)
+            .on(e => e.type === 'chat', () => {
+              setTimeout(() => {
+                expect(spy).toHaveBeenCalled()
+                resolve()
+              }, 5)
+            })
+            .send({ type: 'chat', user: 'test-user', text: 'test' }),
+      },
+      '.remove(\'open\', listener)': {
+        'removes a listener (will not fire)': async ({ channel, resolve, spy }) =>
+          channel
+            .on('open', spy)
+            .on('open', () => {
+              expect(spy).not.toHaveBeenCalled()
+              resolve()
+            })
+            .remove('open', spy)
+      },
+      '.send(message, recipient?)': {
+        'delivers a message to the channel': async ({ channel, getChannel, resolve }) => {
+          channel
+            .on('message', e => {
+              expect(e.message).toBe('test')
+              resolve()
+            })
+            .on('open', () => {
+              getChannel().send('test')
+            })
+        },
+        'delivers a message to a recipient': async ({ channel, getChannel, resolve }) => {
+          channel
+            .on('join', ({ uid }) => {
+              channel.send('test', uid)
+            })
+
+          getChannel({ announce: true })
+            .on('message', (e) => {
+              expect(e.message).toBe('test')
+              resolve()
+            })
+        },
+        'private messages are ONLY delivered to the recipient': async ({ channel, getChannel, resolve, spy }) =>
+          channel
+            .on('join', ({ uid, alias }) => {
+              if (alias === 'test-user') {
+                channel.send('test', uid)
+              }
+            })
+            .on('open', () => {
+              getChannel()
+                .on('message', spy)
+                .on('open', () => {
+                  getChannel({ announce: true, alias: 'test-user' })
+                    .on('message', (e) => {
+                      expect(e.message).toBe('test')
+                      expect(spy).not.toHaveBeenCalled()
+                      resolve()
+                    })
+                })
+            }),
+        'will send an error if the recipient does not exist': async ({ channel, resolve }) =>
+          channel
+            .on('error', e => {
+              expect(e.message).toContain('non-existent-user')
+              resolve()
+            })
+            .send('test', 'non-existent-user'),
+      },
+      '.push(message, recipient?)': {
+        'sends a message to the channel': async ({ channel, getChannel, resolve }) => {
+          channel
+            .on('message', e => {
+              expect(e.message).toBe('test')
+              resolve()
+            })
+            .on('open', () => {
+              getChannel().push('test')
+            })
+        },
+        'closes after sending a message': async ({ channel, resolve }) =>
+          channel
+            .on('close', () => {
+              resolve()
+            })
+            .push('test')
+      },
+    },
+    'MISC BEHAVIOR': {
+      'messages are queued and delivered upon connection': async ({ getChannel, resolve }) => {
+        const messages = ['first', 'second', 'third']
+        const received: string[] = []
+
+        getChannel({ echo: true })
+          .on('message', e => {
+            received.push(e.message)
+
+            if (received.length === messages.length) {
+              expect(received).toEqual(messages)
+              resolve()
+            }
+          })
+          .send(messages[0])
+          .send(messages[1])
+          .send(messages[2])
+      },
+      'connection is opened when registering a listener': async ({ channel, resolve }) => channel.on('open', resolve),
+    },
+    'EVENT PAYLOADS': {
+      'join': {
+        'default': async ({ channel, resolve }) =>
+          channel
+            .on('join', e => {
+              expect(e.users).toBe(1)
+              expect(e.uid).toBeUndefined()
+              expect(e.alias).toBeUndefined()
+              expect(e.date).toBeTypeOf('number')
+              resolve()
+            }),
+        'with { announce: true }': async ({ getChannel, resolve }) =>
+          getChannel({ announce: true, as: 'test-user' })
+            .on('join', e => {
+              expect(e.users).toBe(1)
+              expect(e.uid).toBeTypeOf('string')
+              expect(e.alias).toBe('test-user')
+              expect(e.date).toBeTypeOf('number')
+              resolve()
+            })
+      },
+      'leave': {
+        'default': async ({ channel, getChannel, resolve }) => {
+          channel
+            .on('leave', e => {
+              expect(e.users).toBe(1)
+              expect(e.uid).toBeUndefined()
+              expect(e.alias).toBeUndefined()
+              expect(e.date).toBeTypeOf('number')
+              resolve()
+            })
+            .on('open', () => {
+              getChannel().push('test')
+            })
+        },
+        'with { announce: true }': async ({ getChannel, resolve }) => {
+          getChannel()
+            .on('leave', e => {
+              expect(e.users).toBe(1)
+              expect(e.uid).toBeTypeOf('string')
+              expect(e.alias).toBe('test-user')
+              expect(e.date).toBeTypeOf('number')
+              resolve()
+            })
+            .on('open', () => {
+              getChannel({ announce: true, as: 'test-user' }).push('test')
+            })
+        }
+      },
+      'message': {
+        'default': async ({ getChannel, resolve }) =>
+          getChannel({ echo: true })
+            .on('message', e => {
+              expect(e.message).toBe('test')
+              expect(e.uid).toBeTypeOf('string')
+              expect(e.alias).toBeUndefined()
+              expect(e.date).toBeTypeOf('number')
+              resolve()
+            })
+            .send('test'),
+        'with { alias: string } includes users alias in payload': async ({ getChannel, resolve }) =>
+          getChannel({ echo: true, alias: 'test-user' })
+            .on('message', e => {
+              expect(e.message).toBe('test')
+              expect(e.uid).toBeTypeOf('string')
+              expect(e.alias).toBe('test-user')
+              expect(e.date).toBeTypeOf('number')
+              resolve()
+            })
+            .send('test'),
+      },
+    }
+  }
+}
+
+// setup function for each test
+const setup = () => {
+  const id = 'itty:itty-sockets:test-' + Math.random().toString(36).slice(2)
+  const getChannel = (options = {}): IttySocket<UseItty> => {
+    const channel = connect(id, options)
+    OPEN_CHANNELS.push(channel)
+    return channel
+  }
+
+  return {
+    getChannel,
+    channel: getChannel(id) as IttySocket<UseItty>,
+    spy: mock(() => {}),
+  }
+}
+
+// recursive test runner
+const runTests = (tests: TestTree) => {
+  for (const [name, test] of Object.entries(tests)) {
+    if (typeof test === 'function') {
+      if (test.constructor.name === 'AsyncFunction') {
+        // @ts-ignore
+        it(name, () => new Promise(resolve => test({ ...setup(), resolve })))
+      } else {
+        // @ts-ignore
+        it(name, () => test({ ...setup() }))
+      }
+    } else {
+      describe(name, () => runTests(test))
+    }
+  }
+}
+
+// run the tests!
+runTests(tests)
+
+// close any open channels
+afterAll(() => {
+  console.log(`closing ${OPEN_CHANNELS.length} channels`)
+  OPEN_CHANNELS.forEach(channel => channel.close())
+})

package/src/connect.ts

@@ -0,0 +1,133 @@
+type IttySocketEvent<BaseFormat> = BaseFormat extends UseItty
+  ? 'open' | 'close' | 'message' | 'join' | 'leave'
+  : 'open' | 'close' | 'message'
+
+type Timestamp = { date: number }
+type UserDetails = { uid: string, alias?: string }
+type OptionalUserDetails = { uid?: string, alias?: string }
+
+export type UseItty<MessageType = any> = {
+  message: MessageType
+} & UserDetails & Timestamp
+
+export type MessageEvent<MessageType = any> = {
+  message: MessageType
+} & Timestamp & OptionalUserDetails
+
+export type JoinEvent = {
+  type: 'join'
+  users: number
+} & Timestamp & OptionalUserDetails
+
+export type LeaveEvent = {
+  type: 'leave'
+  users: number
+} & Timestamp & OptionalUserDetails
+
+export type ErrorEvent = {
+  type: 'error'
+  message: string
+} & Timestamp
+
+export type IttySocketOptions = {
+  as?: string,
+  alias?: string,
+  echo?: true,
+  announce?: true,
+}
+
+export interface IttySocketConnect {
+  <BaseFormat = object>(
+    ...args: BaseFormat extends UseItty
+      ? [channelID: string, options?: IttySocketOptions]
+      : [url: string, queryParams?: any]
+  ): IttySocket<BaseFormat>
+}
+
+type UseIttyEvents<BaseFormat> = {
+  on(type: 'join', listener: (event: JoinEvent) => any): IttySocket<BaseFormat>
+  on(type: 'leave', listener: (event: LeaveEvent) => any): IttySocket<BaseFormat>
+  on(type: 'error', listener: (event: ErrorEvent) => any): IttySocket<BaseFormat>
+}
+
+type SendMessage<BaseFormat> = BaseFormat extends UseItty
+  ? <MessageFormat = any>(message: MessageFormat, uid?: string) => IttySocket<BaseFormat>
+  : <MessageFormat = any>(message: MessageFormat) => IttySocket<BaseFormat>
+
+export type IttySocket<BaseFormat = object> = {
+  open: () => IttySocket<BaseFormat>
+  close: () => IttySocket<BaseFormat>
+  send: SendMessage<BaseFormat>
+  push: SendMessage<BaseFormat>
+  remove(type: IttySocketEvent<BaseFormat>, listener: () => any): IttySocket<BaseFormat>
+  remove(type: string, listener: () => any): IttySocket<BaseFormat>
+
+  // EVENTS
+  on(type: 'open', listener: () => any): IttySocket<BaseFormat>
+  on(type: 'close', listener: () => any): IttySocket<BaseFormat>
+  on<MessageFormat = BaseFormat>(type: 'message', listener: (event: BaseFormat & MessageFormat) => any): IttySocket<BaseFormat>
+  on<MessageFormat = BaseFormat>(type: string, listener: (event: BaseFormat & MessageFormat & { type: string }) => any): IttySocket<BaseFormat>
+  on<MessageFormat = BaseFormat>(type: (event?: any) => any, listener: (event: BaseFormat & MessageFormat & { type: string }) => any): IttySocket<BaseFormat>
+} & (BaseFormat extends UseItty ? UseIttyEvents<BaseFormat> : object)
+
+export let connect: IttySocketConnect = (channelId: string, options = {}) => {
+  let ws: WebSocket | null,
+      closeAfterSend: any,
+      queue: string[] = [],
+      events: Record<string, Array<(event?: any) => any>> = {}
+
+  let open = () => (
+    ws || (
+      // @ts-ignore - options will be cast as string regardless of what is passed
+      ws = new WebSocket((/^wss?:/.test(channelId) ? channelId : 'wss://itty.ws/c/' + channelId) + '?' + new URLSearchParams(options)),
+
+      ws.onmessage = (
+        event: any,
+        parsed = JSON.parse(event.data),
+        payload = parsed?.message,
+        eventPayload = {
+          ...(payload?.[0] == null && payload),
+          ...parsed,
+        },
+      ) =>
+        [eventPayload.type, parsed.type ? 0 : 'message', '*'].map(key =>
+          events[key]?.map(listener => listener(eventPayload))
+        ),
+
+      ws.onopen = () => (
+        queue.splice(0).map(m => ws!.send(m)),
+        events.open?.map(listener => listener(closeAfterSend)),
+        closeAfterSend && ws?.close()
+      ),
+
+      ws.onclose = () => (
+        closeAfterSend = ws = null,
+        events.close?.map(listener => listener(closeAfterSend))
+      )
+    ),
+    socket
+  )
+
+  let socket: any = {
+    open,
+    send: (message: any, recipient?: string) => (
+      message = (recipient ? `\x1F${recipient}\x1F` : '') + JSON.stringify(message),
+      // @ts-ignore
+      ws?.readyState & 1 ? ws!.send(message) : queue.push(message),
+      open()
+    ),
+    on: (type: any, listener: (e?: any) => any) => (
+      (events[type?.[0] ? type : '*'] ??= []).push(type?.[0] ? listener : (e: any) => type?.(e) && listener(e)),
+      open()
+    ),
+    remove: (type: any, listener: () => any) => (
+      events[type] = events[type]?.filter((l: any) => l != listener),
+      socket
+    ),
+    // @ts-ignore
+    close: () => (ws?.readyState & 1 ? ws!.close() : closeAfterSend = 1, socket),
+    push: (message: any, recipient?: string) => (closeAfterSend = 1, socket.send(message, recipient!)),
+  }
+
+  return socket
+}

package/src/connect.ts.backup

@@ -0,0 +1,183 @@
+type IttySocketEvent<BaseFormat> = BaseFormat extends UseItty
+  ? 'open' | 'close' | 'message' | 'join' | 'leave'
+  : 'open' | 'close' | 'message'
+
+type Timestamp = { date: number }
+type UserDetails = { uid: string, alias?: string }
+type OptionalUserDetails = { uid?: string, alias?: string }
+
+export type UseItty<MessageType = any> = {
+  message: MessageType
+} & UserDetails & Timestamp
+
+export type MessageEvent<MessageType = any> = {
+  message: MessageType
+} & Timestamp & OptionalUserDetails
+
+export type JoinEvent = {
+  type: 'join'
+  users: number
+} & Timestamp & OptionalUserDetails
+
+export type LeaveEvent = {
+  type: 'leave'
+  users: number
+} & Timestamp & OptionalUserDetails
+
+export type ErrorEvent = {
+  type: 'error'
+  message: string
+} & Timestamp
+
+export type IttySocketOptions = {
+  as?: string,
+  alias?: string,
+  echo?: true,
+  announce?: true,
+}
+
+export interface IttySocketConnect {
+  <BaseFormat = object>(
+    ...args: BaseFormat extends UseItty
+      ? [channelID: string, options?: IttySocketOptions]
+      : [url: string, queryParams?: any]
+  ): IttySocket<BaseFormat>
+}
+
+type UseIttyEvents<BaseFormat> = {
+  on(type: 'join', listener: (event: JoinEvent) => any): IttySocket<BaseFormat>
+  on(type: 'leave', listener: (event: LeaveEvent) => any): IttySocket<BaseFormat>
+  on(type: 'error', listener: (event: ErrorEvent) => any): IttySocket<BaseFormat>
+}
+
+type SendMessage<BaseFormat> = BaseFormat extends UseItty
+  ? <MessageFormat = any>(message: MessageFormat, uid?: string) => IttySocket<BaseFormat>
+  : <MessageFormat = any>(message: MessageFormat) => IttySocket<BaseFormat>
+
+export type IttySocket<BaseFormat = object> = {
+  open: () => IttySocket<BaseFormat>
+  close: () => IttySocket<BaseFormat>
+  send: SendMessage<BaseFormat>
+  push: SendMessage<BaseFormat>
+  remove(type: IttySocketEvent<BaseFormat>, listener: () => any): IttySocket<BaseFormat>
+  remove(type: string, listener: () => any): IttySocket<BaseFormat>
+
+  // EVENTS
+  on(type: 'open', listener: () => any): IttySocket<BaseFormat>
+  on(type: 'close', listener: () => any): IttySocket<BaseFormat>
+  on<MessageFormat = BaseFormat>(type: 'message', listener: (event: BaseFormat & MessageFormat) => any): IttySocket<BaseFormat>
+  on<MessageFormat = BaseFormat>(type: string, listener: (event: BaseFormat & MessageFormat & { type: string }) => any): IttySocket<BaseFormat>
+  on<MessageFormat = BaseFormat>(type: (event?: any) => any, listener: (event: BaseFormat & MessageFormat & { type: string }) => any): IttySocket<BaseFormat>
+} & (BaseFormat extends UseItty ? UseIttyEvents<BaseFormat> : object)
+
+export let connect: IttySocketConnect = (channelId: string, options = {}) => {
+  let ws: WebSocket | null,
+      closeAfterSend: any,
+      queue: string[] = [],
+      events: Record<string, Array<(event?: any) => any>> = {}
+
+  let open = () => {
+    if (ws) return socket
+
+    // @ts-ignore - options will be cast as string regardless of what is passed
+    ws = new WebSocket((channelId[3] < 'a' ? channelId : 'wss://itty.ws/c/' + channelId) + '?' + new URLSearchParams(options))
+
+    ws.onmessage = (
+      event: any,
+      parsed = JSON.parse(event.data),
+      payload = parsed?.message,
+      eventPayload = {
+        ...(payload?.[0] == null && payload),
+        ...parsed,
+      },
+    ) => (
+      events[eventPayload.type]?.map(listener => listener(eventPayload)),
+      parsed.type || events.message?.map(listener => listener(eventPayload)),
+      events['*']?.map(listener => listener(eventPayload))
+    )
+
+    ws.onopen = () => (
+      queue.splice(0).map(m => ws!.send(m)),
+      events.open?.map(listener => listener(closeAfterSend)),
+      closeAfterSend && ws?.close()
+    )
+
+    ws.onclose = () => (
+      closeAfterSend = ws = null,
+      events.close?.map(listener => listener(closeAfterSend))
+    )
+
+    return socket
+  }
+
+  let send = (message: any, recipient?: string) => (
+    message = (recipient ? `\x1F${recipient}\x1F` : '') + JSON.stringify(message),
+    ws?.readyState & 1 ? ws!.send(message) : queue.push(message),
+    open()
+  )
+
+  let socket: any = {
+    open,
+    send,
+    on: (type: any, listener: (e?: any) => any) => (
+      (events[type?.[0] ? type : '*'] ??= []).push(type?.[0] ? listener : (e: any) => type(e) && listener(e)),
+      open()
+    ),
+    remove: (type: any, listener: () => any) => (
+      events[type] = events[type]?.filter((l: any) => l != listener),
+      socket
+    ),
+    close: () => (ws?.readyState & 1 ? ws!.close() : closeAfterSend = 1, socket),
+    push: (message: any, recipient?: string) => (closeAfterSend = 1, send(message, recipient!)),
+  }
+
+  return socket
+}
+
+// type Chat = { type: 'chat', user: string, text: string }
+
+// connect<UseItty>('doo')
+//   .on<Chat>('message', e => {
+//     e
+//   })
+//   .on<Chat>('chat', (e) => {
+//     e.text
+//   })
+//   .on<Chat>(v => v.type === 'chat', e => {
+//     e.texts
+//   })
+//   // .send() // test for (message) vs (message, recipient) based on BaseFormat type
+//   .remove('leave',
+
+
+// GENERICS TESTING
+// connect('test')
+//   .on('message', (e) => e.message.name)
+//   .on('close', () => {})
+//   .send(123)
+//   .on<{ x: string }>('message', (e) => parseInt(e.message.x))
+//   .send<{ foo: string }>({ foo: 'bar' })
+//   .on('join', e => e.users + 4)
+//   .on('leave', e => e.users - 4)
+//   .on('error', e => e.message)
+//   .on('message', e => e.message.whatever)
+//   .on('message', e => e.whatever)
+//   .on<{ foo: string }>('message', e => e.message.foo)
+//   .on<{ foo: string }>('message', e => e.foo)
+//   .on<{ foo: string }>('chat', e => e.foo)
+//   .on<{ foo: string }>('chat', e => e.type)
+//   .send({ $type: 'chat', foo: 'bar' })
+//   .on('*', e => e.message)
+
+//   .on<{ age: number }>('message', (e) => e.message.name) // ERROR
+//   .on<{ x: number }>('message', (e) => parseInt(e.message.x)) // ERROR
+//   .send<string>(123) // ERROR
+//   .send<{ foo: string }>(123) // ERROR
+//   .send<{ foo: string }>({ foo: 'foo', bar: 123 }) // ERROR
+//   .on('join', e => e.message) // ERROR
+//   .on<{ foo: string }>('join', e => e.users) // ERROR
+//   .on('leave', e => e.message) // ERROR
+//   .on('error', e => e.foo) // ERROR
+//   .on<{ foo: string }>('message', e => e.message.whatever) // ERROR
+//   .on<{ foo: string }>('chat', e => e.bar) // ERROR
+

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": "src",
+    "declaration": true,
+    "sourceMap": false,
+    "esModuleInterop": true,
+    "inlineSourceMap": false,
+    "lib": ["esnext", "es2015", "dom"],
+    "listEmittedFiles": false,
+    "listFiles": false,
+    "noFallthroughCasesInSwitch": true,
+    "pretty": true,
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "strict": true,
+    "traceResolution": false,
+    "outDir": "",
+    "target": "esnext",
+    "module": "esnext"
+  },
+  "exclude": ["node_modules", "dist", "**/*.spec.ts"],
+  "include": ["src"]
+}

package/connect.d.ts

@@ -1,61 +0,0 @@
-type IttySocketEvent<BaseFormat> = BaseFormat extends UseItty ? 'open' | 'close' | 'message' | 'join' | 'leave' : 'open' | 'close' | 'message';
-type Date = {
-    date: Date;
-};
-type UserDetails = {
-    uid: string;
-    alias?: string;
-};
-type OptionalUserDetails = {
-    uid?: string;
-    alias?: string;
-};
-export type UseItty<MessageType = any> = {
-    message: MessageType;
-} & UserDetails & Date;
-export type JoinEvent = {
-    type: 'join';
-    users: number;
-} & Date & OptionalUserDetails;
-export type LeaveEvent = {
-    type: 'leave';
-    users: number;
-} & Date & OptionalUserDetails;
-export type ErrorEvent = {
-    type: 'error';
-    message: string;
-} & Date;
-export type IttySocketOptions = {
-    as?: string;
-    alias?: string;
-    echo?: true;
-    announce?: true;
-};
-export interface IttySocketConnect {
-    <BaseFormat = object>(...args: BaseFormat extends UseItty ? [channelID: string, options?: IttySocketOptions] : [url: string, queryParams?: any]): IttySocket<BaseFormat>;
-}
-type UseIttyEvents<BaseFormat> = {
-    on(type: 'join', listener: (event: JoinEvent) => any): IttySocket<BaseFormat>;
-    on(type: 'leave', listener: (event: LeaveEvent) => any): IttySocket<BaseFormat>;
-    on(type: 'error', listener: (event: ErrorEvent) => any): IttySocket<BaseFormat>;
-};
-type SendMessage<BaseFormat> = BaseFormat extends UseItty ? <MessageFormat = any>(message: MessageFormat, uid?: string) => IttySocket<BaseFormat> : <MessageFormat = any>(message: MessageFormat) => IttySocket<BaseFormat>;
-export type IttySocket<BaseFormat = object> = {
-    open: () => IttySocket<BaseFormat>;
-    close: () => IttySocket<BaseFormat>;
-    send: SendMessage<BaseFormat>;
-    push: SendMessage<BaseFormat>;
-    remove(type: IttySocketEvent<BaseFormat>, listener: () => any): IttySocket<BaseFormat>;
-    remove(type: string, listener: () => any): IttySocket<BaseFormat>;
-    on(type: 'open', listener: () => any): IttySocket<BaseFormat>;
-    on(type: 'close', listener: () => any): IttySocket<BaseFormat>;
-    on<MessageFormat = BaseFormat>(type: 'message', listener: (event: BaseFormat & MessageFormat) => any): IttySocket<BaseFormat>;
-    on<MessageFormat = BaseFormat>(type: string, listener: (event: BaseFormat & MessageFormat & {
-        type: string;
-    }) => any): IttySocket<BaseFormat>;
-    on<MessageFormat = BaseFormat>(type: (event?: any) => any, listener: (event: BaseFormat & MessageFormat & {
-        type: string;
-    }) => any): IttySocket<BaseFormat>;
-} & (BaseFormat extends UseItty ? UseIttyEvents<BaseFormat> : object);
-export declare let connect: IttySocketConnect;
-export {};

package/connect.js

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

package/connect.mjs

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