From 78adf5f7737b10166c6f4903e6a5cdbbbb59934c Mon Sep 17 00:00:00 2001 From: Luigi Pinca Date: Tue, 6 Jul 2021 09:01:15 +0200 Subject: [PATCH] [major] Add an ES module wrapper Fixes #1886 --- .eslintrc.yaml | 3 +- README.md | 74 +++++++++++++++++++++++++------------------------- doc/ws.md | 8 +++--- package.json | 7 ++++- wrapper.mjs | 8 ++++++ 5 files changed, 57 insertions(+), 43 deletions(-) create mode 100644 wrapper.mjs diff --git a/.eslintrc.yaml b/.eslintrc.yaml index 45998d206..f3d983b9c 100644 --- a/.eslintrc.yaml +++ b/.eslintrc.yaml @@ -7,7 +7,8 @@ extends: - eslint:recommended - plugin:prettier/recommended parserOptions: - ecmaVersion: 9 + ecmaVersion: latest + sourceType: module rules: no-console: off no-var: error diff --git a/README.md b/README.md index fd75b6533..a2ee9254e 100644 --- a/README.md +++ b/README.md @@ -98,9 +98,9 @@ into the creation of [raw deflate/inflate streams][node-zlib-deflaterawdocs]. See [the docs][ws-server-options] for more options. ```js -const WebSocket = require('ws'); +import WebSocket, { WebSocketServer } from 'ws'; -const wss = new WebSocket.Server({ +const wss = new WebSocketServer({ port: 8080, perMessageDeflate: { zlibDeflateOptions: { @@ -129,7 +129,7 @@ server. To always disable the extension on the client set the `perMessageDeflate` option to `false`. ```js -const WebSocket = require('ws'); +import WebSocket from 'ws'; const ws = new WebSocket('ws://www.host.com/path', { perMessageDeflate: false @@ -141,7 +141,7 @@ const ws = new WebSocket('ws://www.host.com/path', { ### Sending and receiving text data ```js -const WebSocket = require('ws'); +import WebSocket from 'ws'; const ws = new WebSocket('ws://www.host.com/path'); @@ -157,7 +157,7 @@ ws.on('message', function incoming(message) { ### Sending binary data ```js -const WebSocket = require('ws'); +import WebSocket from 'ws'; const ws = new WebSocket('ws://www.host.com/path'); @@ -175,9 +175,9 @@ ws.on('open', function open() { ### Simple server ```js -const WebSocket = require('ws'); +import { WebSocketServer } from 'ws'; -const wss = new WebSocket.Server({ port: 8080 }); +const wss = new WebSocketServer({ port: 8080 }); wss.on('connection', function connection(ws) { ws.on('message', function incoming(message) { @@ -191,15 +191,15 @@ wss.on('connection', function connection(ws) { ### External HTTP/S server ```js -const fs = require('fs'); -const https = require('https'); -const WebSocket = require('ws'); +import { createServer } from 'https'; +import { readFileSync } from 'fs'; +import { WebSocketServer } from 'ws'; -const server = https.createServer({ - cert: fs.readFileSync('/path/to/cert.pem'), - key: fs.readFileSync('/path/to/key.pem') +const server = createServer({ + cert: readFileSync('/path/to/cert.pem'), + key: readFileSync('/path/to/key.pem') }); -const wss = new WebSocket.Server({ server }); +const wss = new WebSocketServer({ server }); wss.on('connection', function connection(ws) { ws.on('message', function incoming(message) { @@ -215,13 +215,13 @@ server.listen(8080); ### Multiple servers sharing a single HTTP/S server ```js -const http = require('http'); -const WebSocket = require('ws'); -const url = require('url'); +import { createServer } from 'http'; +import { parse } from 'url'; +import { WebSocketServer } from 'ws'; -const server = http.createServer(); -const wss1 = new WebSocket.Server({ noServer: true }); -const wss2 = new WebSocket.Server({ noServer: true }); +const server = createServer(); +const wss1 = new WebSocketServer({ noServer: true }); +const wss2 = new WebSocketServer({ noServer: true }); wss1.on('connection', function connection(ws) { // ... @@ -232,7 +232,7 @@ wss2.on('connection', function connection(ws) { }); server.on('upgrade', function upgrade(request, socket, head) { - const pathname = url.parse(request.url).pathname; + const { pathname } = parse(request.url); if (pathname === '/foo') { wss1.handleUpgrade(request, socket, head, function done(ws) { @@ -253,11 +253,11 @@ server.listen(8080); ### Client authentication ```js -const http = require('http'); -const WebSocket = require('ws'); +import WebSocket from 'ws'; +import { createServer } from 'http'; -const server = http.createServer(); -const wss = new WebSocket.Server({ noServer: true }); +const server = createServer(); +const wss = new WebSocketServer({ noServer: true }); wss.on('connection', function connection(ws, request, client) { ws.on('message', function message(msg) { @@ -291,9 +291,9 @@ A client WebSocket broadcasting to all connected WebSocket clients, including itself. ```js -const WebSocket = require('ws'); +import WebSocket, { WebSocketServer } from 'ws'; -const wss = new WebSocket.Server({ port: 8080 }); +const wss = new WebSocketServer({ port: 8080 }); wss.on('connection', function connection(ws) { ws.on('message', function incoming(data, isBinary) { @@ -310,9 +310,9 @@ A client WebSocket broadcasting to every other connected WebSocket clients, excluding itself. ```js -const WebSocket = require('ws'); +import WebSocket, { WebSocketServer } from 'ws'; -const wss = new WebSocket.Server({ port: 8080 }); +const wss = new WebSocketServer({ port: 8080 }); wss.on('connection', function connection(ws) { ws.on('message', function incoming(data, isBinary) { @@ -328,7 +328,7 @@ wss.on('connection', function connection(ws) { ### echo.websocket.org demo ```js -const WebSocket = require('ws'); +import WebSocket from 'ws'; const ws = new WebSocket('wss://echo.websocket.org/', { origin: 'https://websocket.org' @@ -355,13 +355,13 @@ ws.on('message', function incoming(data) { ### Use the Node.js streams API ```js -const WebSocket = require('ws'); +import WebSocket, { createWebSocketStream } from 'ws'; const ws = new WebSocket('wss://echo.websocket.org/', { origin: 'https://websocket.org' }); -const duplex = WebSocket.createWebSocketStream(ws, { encoding: 'utf8' }); +const duplex = createWebSocketStream(ws, { encoding: 'utf8' }); duplex.pipe(process.stdout); process.stdin.pipe(duplex); @@ -381,9 +381,9 @@ Otherwise, see the test cases. The remote IP address can be obtained from the raw socket. ```js -const WebSocket = require('ws'); +import { WebSocketServer } from 'ws'; -const wss = new WebSocket.Server({ port: 8080 }); +const wss = new WebSocketServer({ port: 8080 }); wss.on('connection', function connection(ws, req) { const ip = req.socket.remoteAddress; @@ -409,7 +409,7 @@ In these cases ping messages can be used as a means to verify that the remote endpoint is still responsive. ```js -const WebSocket = require('ws'); +import { WebSocketServer } from 'ws'; function noop() {} @@ -417,7 +417,7 @@ function heartbeat() { this.isAlive = true; } -const wss = new WebSocket.Server({ port: 8080 }); +const wss = new WebSocketServer({ port: 8080 }); wss.on('connection', function connection(ws) { ws.isAlive = true; @@ -446,7 +446,7 @@ without knowing it. You might want to add a ping listener on your clients to prevent that. A simple implementation would be: ```js -const WebSocket = require('ws'); +import WebSocket from 'ws'; function heartbeat() { clearTimeout(this.pingTimeout); diff --git a/doc/ws.md b/doc/ws.md index 275a9ea28..6e0c6ef9f 100644 --- a/doc/ws.md +++ b/doc/ws.md @@ -2,8 +2,8 @@ ## Table of Contents -- [Class: WebSocket.Server](#class-websocketserver) - - [new WebSocket.Server(options[, callback])](#new-websocketserveroptions-callback) +- [Class: WebSocketServer](#class-websocketserver) + - [new WebSocketServer(options[, callback])](#new-websocketserveroptions-callback) - [Event: 'close'](#event-close) - [Event: 'connection'](#event-connection) - [Event: 'error'](#event-error) @@ -57,11 +57,11 @@ - [WS_ERR_UNSUPPORTED_DATA_PAYLOAD_LENGTH](#ws_err_unsupported_data_payload_length) - [WS_ERR_UNSUPPORTED_MESSAGE_LENGTH](#ws_err_unsupported_message_length) -## Class: WebSocket.Server +## Class: WebSocketServer This class represents a WebSocket server. It extends the `EventEmitter`. -### new WebSocket.Server(options[, callback]) +### new WebSocketServer(options[, callback]) - `options` {Object} - `host` {String} The hostname where to bind the server. diff --git a/package.json b/package.json index 5318ff9e4..32e9b7b9e 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,10 @@ "author": "Einar Otto Stangvik (http://2x.io)", "license": "MIT", "main": "index.js", + "exports": { + "import": "./wrapper.mjs", + "require": "./index.js" + }, "browser": "browser.js", "engines": { "node": ">=10.0.0" @@ -23,7 +27,8 @@ "files": [ "browser.js", "index.js", - "lib/*.js" + "lib/*.js", + "wrapper.mjs" ], "scripts": { "test": "nyc --reporter=lcov --reporter=text mocha --throw-deprecation test/*.test.js", diff --git a/wrapper.mjs b/wrapper.mjs new file mode 100644 index 000000000..7245ad15d --- /dev/null +++ b/wrapper.mjs @@ -0,0 +1,8 @@ +import createWebSocketStream from './lib/stream.js'; +import Receiver from './lib/receiver.js'; +import Sender from './lib/sender.js'; +import WebSocket from './lib/websocket.js'; +import WebSocketServer from './lib/websocket-server.js'; + +export { createWebSocketStream, Receiver, Sender, WebSocket, WebSocketServer }; +export default WebSocket;