1.0.0 • Published 19h ago

@talosjs/socket-client

Licence

MIT

Version

1.0.0

Deps

Size

17 kB

Vulns

Weekly

Summary Dependency Versions

@talosjs/socket-client

WebSocket client for real-time bidirectional communication with automatic reconnection, event handling, and typed message serialization.

Features

Socket Class - WebSocket client with typed send and receive operations via the Socket class

Message Queuing - Automatically queues messages sent before the connection is open and flushes them on connect

Typed Events - Register handlers for onMessage, onOpen, onClose, and onError with typed responses

JSON Serialization - Automatic JSON serialization for outgoing messages and deserialization for incoming responses

Protocol Auto-Detection - Automatically converts HTTP/HTTPS URLs to WS/WSS WebSocket protocols

Generic Type Parameters - Parameterize Socket<SendData, Response> for type-safe request and response data

ISocket Interface - Standard interface defining the WebSocket client contract

Locale Support - Request data type includes optional language/locale information

Installation

bun add @talosjs/socket-client

Usage

Basic Connection

import { Socket } from '@talosjs/socket-client';

const socket = new Socket('wss://api.example.com/ws/chat');

socket.onOpen(() => {
  console.log('Connected');
});

socket.onMessage((response) => {
  console.log('Received:', response);
});

socket.onClose((event) => {
  console.log('Disconnected:', event.code, event.reason);
});

socket.onError((event) => {
  console.error('Error:', event);
});

Sending Messages

import { Socket } from '@talosjs/socket-client';

const socket = new Socket('wss://api.example.com/ws/messages');

// Messages are queued if the connection is not yet open
socket.send({
  payload: { message: 'Hello, world!' },
  queries: { room: 'general' }
});

Typed Socket

import { Socket, type RequestDataType } from '@talosjs/socket-client';

interface ChatRequest extends RequestDataType {
  payload: { message: string; type: 'text' | 'image' };
}

interface ChatResponse {
  event: string;
  data: { messageId: string; timestamp: string };
}

const socket = new Socket<ChatRequest, ChatResponse>(
  'wss://api.example.com/ws/chat'
);

socket.onMessage((response) => {
  // response is typed as ResponseDataType<ChatResponse>
  console.log(response.data.event);
});

socket.send({
  payload: { message: 'Hello!', type: 'text' }
});

Closing a Connection

import { Socket } from '@talosjs/socket-client';

const socket = new Socket('wss://api.example.com/ws');

// Close with a status code and reason
socket.close(1000, 'User disconnected');

url: string - WebSocket URL (supports ws://, wss://, http://, https://, or bare hostnames)

Methods:

Method	Returns	Description
`send(data)`	`void`	Send typed data as JSON (queued if not yet connected)
`close(code?, reason?)`	`void`	Close the WebSocket connection
`onMessage(handler)`	`void`	Register a handler for incoming messages
`onOpen(handler)`	`void`	Register a handler for connection open
`onClose(handler)`	`void`	Register a handler for connection close
`onError(handler)`	`void`	Register a handler for errors

type RequestDataType = {
  payload?: Record<string, unknown>;
  queries?: Record<string, boolean | number | bigint | string>;
  lang?: LocaleInfoType;
};

Clone the repository
Install dependencies: bun install
Run tests: bun run test
Build the project: bun run build