From 5c846ca06ee5f5b173b7f49aec862a863a29c348 Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Tue, 4 Jun 2024 11:49:30 -0500 Subject: [PATCH] Clarify usage and update readme (#3114) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit refs https://github.com/Ethan-Arrowood/socket/pull/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 --- packages/pg-cloudflare/README.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/packages/pg-cloudflare/README.md b/packages/pg-cloudflare/README.md index 8496faa4d..b2d6b9937 100644 --- a/packages/pg-cloudflare/README.md +++ b/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)