Document async connection functions

Author: dgraham

README.md

@@ -26,6 +26,10 @@ const delegate = {
   },
   socketDidReceiveMessage(socket: Socket, message: string) {
     // Socket read data from the connection.
+  },
+  socketShouldRetry(socket: Socket, code: number): boolean {
+    // Socket reconnects unless server returns the policy violation code.
+    return code !== 1008
   }
 }
 
@@ -35,8 +39,65 @@ const policy = {
   maxDelay: 60000
 }
 
-const socket = new StableSocket('wss://live.example.com', delegate, policy)
+const url 'wss://live.example.com'
+const socket = new StableSocket(url , delegate, policy)
+socket.open()
+```
+
+### BufferedSocket
+
+Writing to a StableSocket while it is in the opening or closed states
+discards the message data. Use a BufferedSocket to buffer writes to be
+sent when it opens.
+
+```ts
+import {BufferedSocket, StableSocket} from '@github/stable-socket'
+const socket = new BufferedSocket(new StableSocket(url, delegate, policy))
 socket.open()
+socket.send('hello') // Will be sent when the socket is open.
+```
+
+### Asynchronous connections
+
+StableSocket and BufferedSocket are abstractions over a WebSocket that
+maintain an internal state machine, managing reconnects and preventing writes
+to closed sockets. However, sometimes we need direct access to an open WebSocket
+in async functions.
+
+#### connect
+
+Asynchronously connects to a web socket port or fails after a timeout. The
+socket is open, and writable with `send`, when its promise is fulfilled.
+Returns a Promise fulfilled with an open WebSocket or rejected with a
+connection failure.
+
+```ts
+import {connect} from '@github/stable-socket'
+
+try {
+  const socket = await connect('wss://live.example.com', 100)
+  socket.send('hi')
+} catch (e) {
+  console.log('Socket connection failed', e)
+}
+```
+
+#### connectWithRetry
+
+Asynchronously connects to a web socket port, retrying failed connections
+with exponential backoff. Returns a Promise fulfilled with an open WebSocket
+or rejected with a connection failure.
+
+```ts
+import {connectWithRetry} from '@github/stable-socket'
+
+try {
+  const policy = {timeout: 100, attempts: Infinity, maxDelay: 60000}
+  const socket = await connectWithRetry('wss://live.example.com', policy)
+  socket.send('hi')
+} catch (e) {
+  console.log('Socket connection failed', e)
+}
 ```
 
 ## Development

src/ws.ts

@@ -7,19 +7,6 @@ export type ConnectPolicy = {
   signal?: AbortSignal
 }
 
-// Asynchronously connects to a web socket port or fails after a timeout. The
-// socket is open, and writable with `send`, when its promise is fulfilled.
-//
-// Examples
-//
-//   try {
-//     const socket = await connect('wss://github.com', 100)
-//     socket.send('hi')
-//   } catch (e) {
-//     console.log('Socket connection failed', e)
-//   }
-//
-// Returns a Promise fulfilled with an open socket or rejected with a connection failure.
 export async function connect(url: string, ms: number, signal?: AbortSignal): Promise<WebSocket> {
   const socket = new WebSocket(url)
   const opened = whenOpen(socket)
@@ -41,18 +28,6 @@ async function shutdown(opened: Promise<WebSocket>) {
   }
 }
 
-// Asynchronously connects to a web socket port, retrying failed connections.
-//
-// Examples
-//
-//   try {
-//     const socket = await connectWithRetry('wss://github.com', 100, 3)
-//     socket.send('hi')
-//   } catch (e) {
-//     console.log('Socket connection failed', e)
-//   }
-//
-// Returns a Promise fulfilled with an open socket or rejected with a connection failure.
 export function connectWithRetry(url: string, policy: ConnectPolicy): Promise<WebSocket> {
   const fn = () => connect(url, policy.timeout, policy.signal)
   return retry(fn, policy.attempts, policy.maxDelay, policy.signal)