Clarify usage and update readme (#3114)

refs Ethan-Arrowood/socket#17

@petebacondarwin @brianc — publishing `pg-cloudflare` as a separate package seems to be really helpful to people. Ex:

https://github.com/sidorares/node-mysql2/pull/2289/files#diff-e56fabfb5e90fd8f6265cfbe84f3701a85261d884e198bf61de34958cee4864aR12

Added some docs to clarify usage, and cross link to the Node.js implementation of the Socket API.

Co-authored-by: Brian Carlson <[email protected]>

packages/pg-cloudflare/README.md

@@ -1,13 +1,35 @@
 # pg-cloudflare
 
-A socket implementation that can run on Cloudflare Workers using native TCP connections.
+`pg-cloudflare` makes it easier to take an existing package that relies on `tls` and `net`, and make it work in environments where only `connect()` is supported, such as Cloudflare Workers.
 
-## install
+`pg-cloudflare` wraps `connect()`, the [TCP Socket API](https://github.com/wintercg/proposal-sockets-api) proposed within WinterCG, and implemented in [Cloudflare Workers](https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/), and exposes an interface with methods similar to what the `net` and `tls` modules in Node.js expose. (ex: `net.connect(path[, options][, callback])`). This minimizes the number of changes needed in order to make an existing package work across JavaScript runtimes.
+
+## Installation
 
 ```
 npm i --save-dev pg-cloudflare
 ```
 
+## How to use conditionally, in non-Node.js environments
+
+As implemented in `pg` [here](https://github.com/brianc/node-postgres/commit/07553428e9c0eacf761a5d4541a3300ff7859578#diff-34588ad868ebcb232660aba7ee6a99d1e02f4bc93f73497d2688c3f074e60533R5-R13), a typical use case might look as follows, where in a Node.js environment the `net` module is used, while in a non-Node.js environment, where `net` is unavailable, `pg-cloudflare` is used instead, providing an equivalent interface:
+
+```js
+module.exports.getStream = function getStream(ssl = false) {
+  const net = require('net')
+  if (typeof net.Socket === 'function') {
+    return net.Socket()
+  }
+  const { CloudflareSocket } = require('pg-cloudflare')
+  return new CloudflareSocket(ssl);
+}
+```
+
+## Node.js implementation of the Socket API proposal
+
+If you're looking for a way to rely on `connect()` as the interface you use to interact with raw sockets, but need this interface to be availble in a Node.js environment, [`@arrowood.dev/socket`](https://github.com/Ethan-Arrowood/socket) provides a Node.js implementation of the Socket API.
+
+
 ### license
 
 The MIT License (MIT)