Registry / messaging / extra-native-websocket

extra-native-websocket

library0.5.2jsnpmunverified

extra-native-websocket (v0.5.2) is a lightweight, TypeScript-first library that wraps native WebSocket with a promise-based API, typed error handling, reconnection strategies, and state management. It extends an emitter pattern from @blackglory/structures, offering autoReconnect and exponential backoff without external dependencies. Requires Node >=22 and ESM-only. Differentiates from ws or isomorphic-ws by focusing on native WebSocket and providing extra utilities like autoReconnect and WebSocketError.

messaging

npm install extra-native-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EXTRA-NATIVE-WEBSO

extra-native-websocket

messagingjavascriptv0.5.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ExtraNativeWebSocket

✓ import { ExtraNativeWebSocket } from 'extra-native-websocket'

✗ const { ExtraNativeWebSocket } = require('extra-native-websocket')

ESM-only since v0.1.0; CommonJS require will fail.

autoReconnect

✓ import { autoReconnect } from 'extra-native-websocket'

Available as named export since v0.3.0.

WebSocketError

✓ import { WebSocketError } from 'extra-native-websocket'

✗ import { WebSocketError } from 'extra-error'

WebSocketError is re-exported from this package; do not import from extra-error directly.

BinaryType

✓ import { BinaryType } from 'extra-native-websocket'

TypeScript enum; use as type for setBinaryType.

State

✓ import { State } from 'extra-native-websocket'

TypeScript enum; returned by getState().

Creates an ExtraNativeWebSocket with reconnection, connects, sends and receives a message.

import { ExtraNativeWebSocket, autoReconnect } from 'extra-native-websocket'; const ws = new ExtraNativeWebSocket(() => new WebSocket('wss://echo.websocket.org')); const cleanup = autoReconnect(ws, 2000); // reconnect every 2 seconds ws.on('open', () => { console.log('connected'); ws.send('Hello'); }); ws.on('message', (event) => { console.log('Received:', event.data); cleanup(); // stop reconnecting after first message }); ws.connect().then(() => { console.log('Connection established'); }).catch((err) => { console.error('Connection failed:', err); });

Debug

Known issues

breakingConstructor expects a factory function, not a URL: new ExtraNativeWebSocket(() => new WebSocket(url))

fix

Wrap WebSocket creation in a lambda.

affects: >=0.1.0

gotchaconnect() returns Promise<void> but does not handle signal cancellation properly on React Native or non-standard environments

fix

Upgrade to 0.5.1+ or manually check AbortSignal in your own wrapper.

affects: <=0.5.0

deprecatedautoReonnectWithExponentialBackOff is misspelled (double 'n'), consider removing or deprecating in future

fix

Use autoReconnect with manual exponential backoff logic instead.

affects: <=0.5.2

gotchaRequires Node >=22; will throw SyntaxError on older versions due to ESM features

fix

Use Node 22+ or transpile with bundler.

affects: >=0.5.0

Errors

Common errors & fixes

TypeError: Class extends value undefined is not a constructor or null

Missing @blackglory/structures peer dependency

fix

Install @blackglory/structures: npm install @blackglory/structures

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Package is ESM-only; CommonJS require fails

fix

Use import or dynamic import() instead of require()

SyntaxError: Unexpected token '?'

Node.js version <22 does not support the ?? operator used in the source

fix

Upgrade Node to >=22 or use a bundler/transpiler

Upgrade

Version history

0.5.2latest on npm

Audit

Dependencies

@blackglory/structuresrequiredProvides the Emitter base class used by ExtraNativeWebSocket

extra-errorrequiredProvides CustomError for WebSocketError

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/BlackGlory/extra-native-websocket ↗

packageextra-native-websocket ↗

homepagehttps://github.com/BlackGlory/extra-native-websocket#readme ↗