Socket
Book a DemoInstallSign in
Socket
Book a DemoInstallSign in

socked

Package Overview
Dependencies
Maintainers
1
Versions
7
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

socked

Lightweight WebSocket client & server wrapper with reconnects, events, acks, and dev tools.

npmnpm
Version
1.0.5
Version published
Weekly downloads
9
125%
Maintainers
1
Weekly downloads
 
Created
Source

🧩 socked

A lightweight JavaScript utility for WebSocket-based client-server communication with:

  • ✅ Event-based messaging
  • 🔁 Reconnect with backoff strategy
  • 🧠 Acknowledged emits (emit + response)
  • 🔄 One-time listeners
  • 🫀 Ping/pong heartbeat (server-initiated)
  • 🧪 Debug logging & connection status API

Features

  • Event-driven API for both client and server
  • Automatic reconnect with backoff
  • Acknowledged emits (emit + response)
  • One-time listeners (once)
  • Server-initiated ping/pong heartbeat
  • Debug logging and connection status

Tutorial

Prerequisites

  • Node.js (v14 or newer)
  • A web browser
  • A code editor (e.g., VS Code)

1. 📦 Install the Package

Initialize a new Node.js project:

npm init -y
npm install socked

Or clone this repo and use the files in src/.

1.1. 📥 Importing in Your Project

If installed from npm:

For Node.js (server):

import { createServer } from 'socked';

For Browser (with a bundler):

import { createClient } from 'socked';

If using in the browser without a bundler (via CDN):

<script type="module">
  import { createClient } from 'https://cdn.jsdelivr.net/npm/socked/+esm';
  // ...your code...
</script>

2. 🛠️ Setup Server

Create the file: examples/server.js

import { createServer } from '../src/server.js';

const wss = createServer({ port: 3000 });

wss.onClient((client) => {
  console.log('Client connected');

  client.onEvent('join', (data) => {
    console.log('Join:', data);
    client.emit('welcome', { message: `Welcome to ${data.room}` });
  });
});

Run the server:

node examples/server.js

3. 🌐 Setup Client (Browser)

Create the file: examples/client.html

<!DOCTYPE html>
<html>
<head>
  <title>socked Client</title>
</head>
<body>
  <h1>socked Client</h1>
  <script type="module">
    import { createClient } from '../src/client.js';

    const socket = createClient('ws://localhost:3000', {
      reconnect: true
    });

    socket.on('connect', () => {
      console.log('Connected to server');
      socket.emit('join', { room: 'main' });
    });

    socket.on('welcome', (data) => {
      console.log('Server says:', data.message);
      document.body.innerHTML += `<p>${data.message}</p>`;
    });

    socket.on('disconnect', () => {
      console.log('Disconnected. Will retry...');
    });
  </script>
</body>
</html>

Open the file in your browser (e.g., with Live Server in VS Code).

4. 🧪 Advanced Features

🔁 Emit with Acknowledgment

Client:

socket.emitWithAck('saveData', { name: 'Test' })
  .then(response => console.log('✅ Ack:', response))
  .catch(err => console.error('❌ Timeout or Error:', err));

Server:

client.onEvent('saveData', (data) => {
  console.log('Saving data:', data);
  client.emit(`saveData_ack_${data._ackId}`, { success: true });
});

🧠 One-time Listeners

socket.once('config', (cfg) => {
  console.log('Loaded config:', cfg);
});

💓 Ping/Pong (Auto)

Handled internally: the server sends pings and expects pong responses to keep the connection alive.

🛠️ Get Connection Status

console.log('Connection Status:', socket.getStatus()); // "connected" or "disconnected"

🧼 Clean Up Listeners

socket.off('eventName'); // remove all listeners for that event

API Reference

See src/client.js and src/server.js for full API details.

License

MIT

Contributions welcome!
Create an issue or open a PR on GitHub.

Keywords

websocket
realtime
socket
client-server
websocket-wrapper
ws

FAQs

Package last updated on 10 Jun 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

Malicious fezbox npm Package Steals Browser Passwords from Cookies via Innovative QR Code Steganographic Technique

Research

Malicious fezbox npm Package Steals Browser Passwords from Cookies via Innovative QR Code Steganographic Technique

A malicious package uses a QR code as steganography in an innovative technique.

By Olivia Brown  -  Sep 22, 2025