UpgradeJS (minimal WebSocket utilities)

1.1.0 · abandoned · verified Wed Apr 22

UpgradeJS is a lightweight, low-level Node.js library designed to facilitate direct handling of HTTP upgrade requests, primarily for establishing raw WebSocket connections. It provides utilities for writing WebSocket handshake headers, framing and unmasking WebSocket data. A key limitation of this library is its explicit restriction to WebSocket payloads not exceeding 125 bytes. The package version `1.1.0` is the latest, but the project appears to be unmaintained, with its documentation largely reflecting an earlier `1.0.0` release and no visible recent development or a current active GitHub repository. This library offers a barebones approach, requiring developers to manage many WebSocket protocol details themselves, differentiating it from more feature-rich WebSocket libraries like `ws` or `Socket.IO` that handle framing, fragmentation, and other complexities automatically.

Common errors

```
RangeError: Payload too large for single frame.
```
cause Attempting to send a WebSocket message with a payload exceeding 125 bytes using `upgrade.frameData()` or `upgrade.send()`.

fix Reduce the size of the message payload to 125 bytes or less. This library does not automatically handle WebSocket message fragmentation.
```
SyntaxError: Named export '...' not found. The requested module 'upgrade' does not provide an export named '...'
```
cause Attempting to use ES Module `import { someFunction } from 'upgrade'` syntax with a CommonJS-only module.

fix Change your import statement to `const upgrade = require('upgrade');` and access functions as properties (e.g., `upgrade.someFunction`).
```
TypeError: upgrade.writeHead is not a function (or similar for other methods)
```
cause Incorrectly importing the module (e.g., `const { writeHead } = require('upgrade')` or a failed ESM import) leading to the `upgrade` variable not holding the module object.

fix Ensure you are using the correct CommonJS import: `const upgrade = require('upgrade');` then access methods as `upgrade.methodName(args)`.

Warnings

breaking The `frameData` and `send` functions explicitly do not support payloads larger than 125 bytes. Sending larger data will result in a `RangeError`.
Fix: Ensure all WebSocket message payloads are 125 bytes or less. For larger payloads, consider a different WebSocket library or implement fragmentation manually.
gotcha The package appears to be unmaintained. The GitHub repository linked in the npm package is defunct, and there are no signs of active development. This means it may not be compatible with newer Node.js versions or handle modern WebSocket features.
Fix: Evaluate alternatives like `ws` or `uWS` for actively maintained and feature-rich WebSocket implementations. Use this library only for specific, constrained legacy requirements.
gotcha UpgradeJS is a CommonJS-only module. Attempting to use `import` statements will result in runtime errors in Node.js environments unless transpiled or configured for CJS interop.
Fix: Always use `const upgrade = require('upgrade')` to import the module. If using an ES Module project, consider a CommonJS wrapper or a different library.

Install

npm install upgrade npm
yarn add upgrade yarn
pnpm add upgrade pnpm

Imports

upgrade
wrong:
```
import upgrade from 'upgrade'
```
correct:
```
const upgrade = require('upgrade')
```
This library is CommonJS-only and does not support ES Modules. Use `require()` for all imports.
writeHead
wrong:
```
import { writeHead } from 'upgrade'
```
correct:
```
const upgrade = require('upgrade'); upgrade.writeHead(req, socket);
```
Functions are accessed as properties of the main `upgrade` module object, not as named exports.
getData
wrong:
```
import { getData } from 'upgrade'
```
correct:
```
const upgrade = require('upgrade'); const data = upgrade.getData(buff);
```
Functions are accessed as properties of the main `upgrade` module object, not as named exports.
send
wrong:
```
import { send } from 'upgrade'
```
correct:
```
const upgrade = require('upgrade'); upgrade.send('message', socket);
```
The `send` function (and `getSend`) are core utilities for sending framed WebSocket data.

Quickstart

Demonstrates a basic WebSocket server handling HTTP upgrades, receiving messages, and sending framed responses using UpgradeJS utilities.

const http = require('http');
const upgrade = require('upgrade');

const server = http.createServer();

server.on('upgrade', function (req, socket) {
    const send = upgrade.getSend(socket);
    upgrade.writeHead(req, socket);

    socket.on('data', function (buff) {
        const data = upgrade.getData(buff);
        console.log('Server received: ' + data);
        send('Echo: ' + data); // Echo back the received message
    });

    socket.on('close', () => console.log('Client disconnected.'));
    socket.on('error', (err) => console.error('Socket error:', err));

    send('Welcome to the Server!');
});

server.listen(8000, () => {
    console.log('WebSocket server listening on port 8000');
});

// To test, run this in a browser console:
// const socket = new WebSocket('ws://localhost:8000');
// socket.onopen = () => { console.log('Socket Open.'); socket.send('Hello Server!'); };
// socket.onmessage = (evt) => { console.log('Client received: ' + evt.data); };
// socket.onclose = () => { console.log('Socket Closed.'); };
// socket.onerror = (err) => { console.error('Socket Error:', err); };

view raw JSON →