{"id":47540,"library":"extra-native-websocket","title":"extra-native-websocket","description":"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.","status":"active","version":"0.5.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/BlackGlory/extra-native-websocket","tags":["javascript","typescript"],"install":[{"cmd":"npm install extra-native-websocket","lang":"bash","label":"npm"},{"cmd":"yarn add extra-native-websocket","lang":"bash","label":"yarn"},{"cmd":"pnpm add extra-native-websocket","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the Emitter base class used by ExtraNativeWebSocket","package":"@blackglory/structures","optional":false},{"reason":"Provides CustomError for WebSocketError","package":"extra-error","optional":false}],"imports":[{"note":"ESM-only since v0.1.0; CommonJS require will fail.","wrong":"const { ExtraNativeWebSocket } = require('extra-native-websocket')","symbol":"ExtraNativeWebSocket","correct":"import { ExtraNativeWebSocket } from 'extra-native-websocket'"},{"note":"Available as named export since v0.3.0.","wrong":"","symbol":"autoReconnect","correct":"import { autoReconnect } from 'extra-native-websocket'"},{"note":"WebSocketError is re-exported from this package; do not import from extra-error directly.","wrong":"import { WebSocketError } from 'extra-error'","symbol":"WebSocketError","correct":"import { WebSocketError } from 'extra-native-websocket'"},{"note":"TypeScript enum; use as type for setBinaryType.","wrong":"","symbol":"BinaryType","correct":"import { BinaryType } from 'extra-native-websocket'"},{"note":"TypeScript enum; returned by getState().","wrong":"","symbol":"State","correct":"import { State } from 'extra-native-websocket'"}],"quickstart":{"code":"import { ExtraNativeWebSocket, autoReconnect } from 'extra-native-websocket';\n\nconst ws = new ExtraNativeWebSocket(() => new WebSocket('wss://echo.websocket.org'));\n\nconst cleanup = autoReconnect(ws, 2000); // reconnect every 2 seconds\n\nws.on('open', () => {\n  console.log('connected');\n  ws.send('Hello');\n});\n\nws.on('message', (event) => {\n  console.log('Received:', event.data);\n  cleanup(); // stop reconnecting after first message\n});\n\nws.connect().then(() => {\n  console.log('Connection established');\n}).catch((err) => {\n  console.error('Connection failed:', err);\n});","lang":"typescript","description":"Creates an ExtraNativeWebSocket with reconnection, connects, sends and receives a message."},"warnings":[{"fix":"Wrap WebSocket creation in a lambda.","message":"Constructor expects a factory function, not a URL: new ExtraNativeWebSocket(() => new WebSocket(url))","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Upgrade to 0.5.1+ or manually check AbortSignal in your own wrapper.","message":"connect() returns Promise<void> but does not handle signal cancellation properly on React Native or non-standard environments","severity":"gotcha","affected_versions":"<=0.5.0"},{"fix":"Use autoReconnect with manual exponential backoff logic instead.","message":"autoReonnectWithExponentialBackOff is misspelled (double 'n'), consider removing or deprecating in future","severity":"deprecated","affected_versions":"<=0.5.2"},{"fix":"Use Node 22+ or transpile with bundler.","message":"Requires Node >=22; will throw SyntaxError on older versions due to ESM features","severity":"gotcha","affected_versions":">=0.5.0"}],"env_vars":null,"search_vec":"'22':52 'api':26 'autoreconnect':43,74 'backoff':46 'base':25 'blackglory/structures':41 'depend':49 'differenti':57 'emitt':38 'error':28 'esm':55 'esm-on':54 'exponenti':45 'extend':36 'extern':48 'extra':2,6,71 'extra-native-websocket':1,5 'first':15 'focus':65 'handl':29 'isomorph':62 'isomorphic-w':61 'javascript':77 'librari':16 'lightweight':12 'like':73 'manag':34 'nativ':3,7,19,67 'node':51 'offer':42 'pattern':39 'promis':24 'promise-bas':23 'provid':70 'reconnect':30 'requir':50 'state':33 'strategi':31 'type':27 'typescript':14,78 'typescript-first':13 'util':72 'v0.5.2':9 'websocket':4,8,20,68 'websocketerror':76 'without':47 'wrap':18 'ws':59,63","created_at":"2026-06-07T16:52:01.780477+00:00","updated_at":"2026-06-07T16:52:01.780477+00:00","problems":[{"fix":"Install @blackglory/structures: npm install @blackglory/structures","cause":"Missing @blackglory/structures peer dependency","error":"TypeError: Class extends value undefined is not a constructor or null"},{"fix":"Use import or dynamic import() instead of require()","cause":"Package is ESM-only; CommonJS require fails","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Upgrade Node to >=22 or use a bundler/transpiler","cause":"Node.js version <22 does not support the ?? operator used in the source","error":"SyntaxError: Unexpected token '?'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/BlackGlory/extra-native-websocket#readme","github":"ssh://git@github.com/BlackGlory/extra-native-websocket","docs":null,"changelog":null,"pypi":null,"npm":"extra-native-websocket","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}