PlaySocket Client

Why use PlaySocket?

Installation

npm install playsocketjs

Usage examples

import PlaySocket from 'playsocketjs';
// Create a new instance
const socket = new PlaySocket('unique-client-id', { // You can pass no ID to let the server pick one
 endpoint: 'wss://example.com/socket'
});
// Set up event handlers (optional)
socket.onEvent('status', status => console.log('Status:', status));
socket.onEvent('error', status => console.log('Error:', status));
const clientId = await socket.init(); // Initialize the socket

// Create a new room
const roomId = await socket.createRoom();
// Optionally, with initial storage
const roomId = await socket.createRoom({
 players: ["this-player"],
 latestPlayer: null,
});

await socket.joinRoom('room-id'); // Join an existing room

socket.destroy(); // To leave the room, destroy the instance

const reactiveVariable = useState(); // Or $state(), reactive(), depending on your framework
socket.onEvent('storageUpdated', storage => (reactiveVariable = storage)); // Assign on update

const currentState = socket.storage; // Synchronous, local access
socket.updateStorage('players', 'array-add-unique', { username: 'Player4', level: 2 }); // Special method to enable conflict-free additions for arrays
socket.updateStorage('latestPlayer', 'set', 'Player4'); // Regular synced storage update

socket.sendRequest('chosen-request-name', { fact: "You can build server-authoritative logic using this!" })

API reference

Constructor

new PlaySocket(id?: string, options: PlaySocketOptions)

Configuration options

Methods

Event types

Properties (Read-only)

PlaySocket Server

Installation

npm install playsocketjs ws

Usage examples

Standalone server

import PlaySocketServer from 'playsocketjs/server'; // Both ES Module & CommonJS Module syntax is supported
const server = new PlaySocketServer(); // Create and start the server (default path is /)
// Gracefully disconnect all clients and close the server (optional)
function shutdown() {
 server.stop();
 process.exit(0);
}
// Handle both SIGINT and SIGTERM
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);

Together with Express.js (or other Backend frameworks)

const express = require('express');
const http = require('http');
const PlaySocketServer = require('playsocketjs/server');
const app = express();
const httpServer = http.createServer(app);
// Create PlaySocket server with your HTTP server
const playSocketServer = new PlaySocketServer({
 server: httpServer,
 path: '/socket'
});
// Start the server
httpServer.listen(3000, () => {
 console.log('Server running on port 3000');
});
// Gracefully disconnect all clients and close the server (recommended)
function shutdown() {
 server.stop();
 process.exit(0);
}
// Handle both SIGINT and SIGTERM
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);

API reference

Constructor

new PlaySocket(options: PlaySocketServerOptions)

Configuration options

verifyClient callback

const server = new PlaySocketServer({
 server: httpServer,
 path: '/socket',
 verifyClient: (info, callback) => {
 // info.req - the HTTP request object, info.origin - the Origin header value
 const ip = info.req.headers['x-forwarded-for'] || info.req.socket.remoteAddress;
 if (isRateLimited(ip)) return callback(false, 429, 'Too Many Requests');
 callback(true);
 }
});

Methods

Event types

Properties (Read-only)

License