archive-gh-me/node-postgres
1
0
Fork 0
mirror of https://github.com/brianc/node-postgres.git synced 2025-12-08 20:16:25 +00:00
Code Issues Projects Releases Wiki Activity

Clarify usage and update readme (#3114)

Browse Source 
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 <brian.m.carlson@gmail.com>
This commit is contained in:
Brendan Irvine-Broque 2024-06-04 11:49:30 -05:00 committed by GitHub
parent 7fcf941a33
commit 5c846ca06e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 24 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
packages/pg-cloudflare/README.md
View File

@ -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)