sonic-ws 1.3.0 → 1.3.2

package/README.md

@@ -1,6 +1,19 @@
 # sonic-ws
 
-## INFO
+### WebSockets that handle correctness, security, and performance for you
+
+- No race conditions
+- No invalid packets
+- No accidental DoS
+- No cleanup bugs
+- No boilerplate
+- Many built-in security features
+- Lower bandwidth cost
+- Works much better on mobile
+- More readable than every other socket library
+
+<details>
+<summary>DETAILED INFO</summary>
 
 SonicWS is an ultra-lightweight, high-performance WebSocket library focused on maximum bandwidth efficiency, speed, and security.
 
@@ -44,83 +57,76 @@ Developer Experience:
 - Almost every case has a pre-made wire optimization and boilerplate removal.
 
 Whether you're making a real-time game, a dashboard, a distributed system, or anything else, SonicWS gets you safe, structured packets; fast.
+</details>
 
 ## SAMPLES
 
-### Importing:
-Node (Client & Server):
+### Node (Client & Server)
 ```js
-import { PacketType, SonicWS, SonicWSServer, CreatePacket, CreateObjPacket } from "sonic-ws";
+import { SonicWS, SonicWSServer, CreatePacket, PacketType } from "sonic-ws";
 ```
+
 Browser (Client):
 ```html
-<script src="https://cdn.jsdelivr.net/gh/liwybloc/sonic-ws/release/SonicWS_bundle.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/liwybloc/sonic-ws/release/SonicWS_bundle"></script>
 ```
 *This will always give the latest release build. I will add branches for each release if this project actually goes anywhere.
 
-### Server:
+### Simple Example: Clicker Server
+
+#### Server
 ```js
 const wss = new SonicWSServer({
     clientPackets: [
-        CreatePacket({tag: "pong", type: PacketType.UVARINT, dataMax: 1})
+        CreatePacket({ tag: "click", type: PacketType.NONE }),
+        CreatePacket({ tag: "token", type: PacketType.STRINGS }),
     ],
     serverPackets: [
-        CreatePacket({tag: "ping", type: PacketType.UVARINT, dataMax: 1}),
-        CreateObjPacket({tag: "data", types: [PacketType.UBYTES, PacketTypes.STRINGS], dataMaxes: [2, 3]})
+        CreatePacket({ tag: "pointsInfo", type: PacketType.UVARINT }),
+        CreatePacket({ tag: "notification", type: PacketType.STRINGS }),
     ],
-    websocketOptions: { port: 1234 }
+    websocketOptions: { port: 1234 },
 });
 
-wss.on_connect((socket) => {
+wss.requireHandshake("token");
 
-    console.log("Socket connection:", socket.id);
+wss.on_connect(ws => {
+    console.log("Client connected:", ws.id);
 
-    socket.on("pong", (num) => {
-        console.log("Ponged!", num);
-        socket.send("data", [Math.floor(Math.random() * 26), Math.floor(Math.random() * 256)], ["hello", "from", "server"]);
-    });
+    let clicks = 0;
 
-    socket.setInterval(() => {
-        socket.send("ping", Date.now());
-    }, 10000);
+    ws.on("token", token => {
+        if(!isValidToken(token)) // No listeners will ever trigger after this, unlike base websocket
+            return socket.close();
+    })
 
-});
+    // auto validation, no boilerplate. always passed the token check
+    ws.on("click", () => {
+        ws.send("pointsInfo", ++clicks);
+    });
 
-wss.on_ready(() => {
-    console.log("Server ready!");
+    ws.setInterval(() => ws.send("notification", "Keep going!"), 5000); // auto cleanup on close
 });
+
+wss.on_ready(() => console.log("Server ready!"));
 ```
 
-### Client:
+#### Client
 ```js
 const ws = new SonicWS("ws://localhost:1234");
 
-ws.on_ready(() => {
-    console.log("Connected to server");
-});
+ws.on_ready(() => console.log("Connected to server"));
 
-ws.on("ping", (num) => {
-    console.log("Pinged!", num);
-    ws.send("pong", Date.now());
-})
-ws.on("data", (i, s) => {
-    console.log("data: ", i);
-    console.log("message: " + s.join(" "));
-});
+ws.on("pointsInfo", clicks => console.log("Total Clicks: ", clicks));
 
-ws.on_close((event) => {
-    console.log("closed client: " + event.code);
+ws.on("notification", msg => console.log("Notification:", msg));
+
+button.addEventListener("click", () => {
+    ws.send("click");
 });
+
 ```
 
 ## KNOWN ISSUES
 
-Some weird error messages when invalid inputs are in like CreatePacket() and stuff
-
 ## PLANNED FEATURES
-
-Better error handling
-
-Some middleware support
-
-Debug menus for client/server

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Copyright 2026 Lily (liwybloc)
+ * Licensed under the Apache License, Version 2.0.
+ */
 export { SonicWS } from './ws/client/node/ClientNode';
 export { SonicWSConnection } from './ws/server/SonicWSConnection';
 export { SonicWSServer } from './ws/server/SonicWSServer';

package/dist/version.d.ts

@@ -1,5 +1,9 @@
+/**
+ * Copyright 2026 Lily (liwybloc)
+ * Licensed under the Apache License, Version 2.0.
+ */
 /** Current protocol version */
-export declare const VERSION = 19;
+export declare const VERSION = 20;
 /** Server data suffix */
 export declare const SERVER_SUFFIX = "SWS";
 /** Server data suffix in array */

package/dist/version.js

@@ -1,25 +1,6 @@
-"use strict";
-/*
+/**
  * Copyright 2026 Lily (liwybloc)
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * Licensed under the Apache License, Version 2.0.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SERVER_SUFFIX_NUMS = exports.SERVER_SUFFIX = exports.VERSION = void 0;
-const StringUtil_1 = require("./ws/util/StringUtil");
-/** Current protocol version */
-exports.VERSION = 19;
-/** Server data suffix */
-exports.SERVER_SUFFIX = "SWS";
-/** Server data suffix in array */
-exports.SERVER_SUFFIX_NUMS = (0, StringUtil_1.processCharCodes)(exports.SERVER_SUFFIX);
+
+Object.defineProperty(exports,"__esModule",{value:!0}),exports.SERVER_SUFFIX_NUMS=exports.SERVER_SUFFIX=exports.VERSION=void 0;const e=require("./ws/util/StringUtil");exports.VERSION=20,exports.SERVER_SUFFIX="SWS",exports.SERVER_SUFFIX_NUMS=(0,e.processCharCodes)(exports.SERVER_SUFFIX);

package/dist/ws/Connection.d.ts

@@ -1,8 +1,13 @@
-import { ConnectionMiddleware, MiddlewareHolder } from "./PacketProcessor";
+/**
+ * Copyright 2026 Lily (liwybloc)
+ * Licensed under the Apache License, Version 2.0.
+ */
+import { ConnectionMiddleware, IMiddlewareHolder, MiddlewareHolder } from "./PacketProcessor";
+import { BatchHelper } from "./util/packets/BatchHelper";
 /**
  * Holds shared connection values. Lets helper functions work on client and server.
  */
-export interface Connection extends MiddlewareHolder<ConnectionMiddleware> {
+export interface IConnection<T> extends IMiddlewareHolder<ConnectionMiddleware> {
     /**
      * List of timers.
      * For internal use only.
@@ -39,10 +44,55 @@ export interface Connection extends MiddlewareHolder<ConnectionMiddleware> {
      * Sends raw uint8array data through the connection
      */
     raw_send(data: Uint8Array): void;
+    /**
+     * Listens for all messages rawly
+     * @param listener Callback for when data is received
+     */
+    raw_onmessage(listener: (data: T) => void): void;
     /**
      * Closes the connection
      */
     close(code?: number, reason?: string): void;
+    /**
+     * Checks if the connection is closed
+     * @returns If it's closed or not
+     */
+    isClosed(): boolean;
+    /**
+     * Sets the name of this connection for the debug menu; good for setting e.g. usernames on games
+     */
+    setName(name: string): Promise<void>;
+    /**
+     * @returns Name of the socket, defaults to Socket [ID] or LocalSocket unless set with setName()
+     */
+    getName(): string;
+}
+export declare abstract class Connection<T extends {
+    readyState: number;
+    send: (u: Uint8Array) => void;
+    close: (c: number, d: string | undefined) => void;
+}, K> extends MiddlewareHolder<ConnectionMiddleware> implements IConnection<K> {
+    protected listeners: Record<string, Array<(...data: any[]) => void>>;
+    private name;
+    protected closed: boolean;
+    socket: T;
+    _timers: Record<number, [number, (closed: boolean) => void, boolean]>;
+    protected batcher: BatchHelper;
+    _on: Function;
+    _off: Function;
+    /** The index of the connection; unique for all connected, not unique after disconnection. */
+    id: number;
+    constructor(socket: T, id: number, name: string, addListener: Function, removeListener: Function);
+    setTimeout(call: () => void, time: number, callOnClose?: boolean): number;
+    setInterval(call: () => void, time: number, callOnClose?: boolean): number;
+    clearTimeout(id: number): void;
+    clearInterval(id: number): void;
+    raw_send(data: Uint8Array): void;
+    raw_onmessage(listener: (data: K) => void): void;
+    close(code?: number, reason?: string | Buffer): void;
+    isClosed(): boolean;
+    setName(name: string): Promise<void>;
+    getName(): string;
 }
 export declare enum CloseCodes {
     RATELIMIT = 4000,

package/dist/ws/Connection.js

@@ -1,50 +1,6 @@
-"use strict";
-/*
+/**
  * Copyright 2026 Lily (liwybloc)
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * Licensed under the Apache License, Version 2.0.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CloseCodes = void 0;
-exports.getClosureCause = getClosureCause;
-var CloseCodes;
-(function (CloseCodes) {
-    CloseCodes[CloseCodes["RATELIMIT"] = 4000] = "RATELIMIT";
-    CloseCodes[CloseCodes["SMALL"] = 4001] = "SMALL";
-    CloseCodes[CloseCodes["INVALID_KEY"] = 4002] = "INVALID_KEY";
-    CloseCodes[CloseCodes["INVALID_PACKET"] = 4003] = "INVALID_PACKET";
-    CloseCodes[CloseCodes["INVALID_DATA"] = 4004] = "INVALID_DATA";
-    CloseCodes[CloseCodes["REPEATED_HANDSHAKE"] = 4005] = "REPEATED_HANDSHAKE";
-    CloseCodes[CloseCodes["DISABLED_PACKET"] = 4006] = "DISABLED_PACKET";
-    CloseCodes[CloseCodes["MIDDLEWARE"] = 4007] = "MIDDLEWARE";
-    CloseCodes[CloseCodes["MANUAL_SHUTDOWN"] = 4008] = "MANUAL_SHUTDOWN";
-})(CloseCodes || (exports.CloseCodes = CloseCodes = {}));
-function getClosureCause(id) {
-    if (id >= 4000) {
-        return CloseCodes[id] ?? 'UNKNOWN';
-    }
-    switch (id) {
-        case 1000:
-            return 'NORMAL_CLOSURE';
-        case 1001:
-            return 'GOING_AWAY';
-        case 1002:
-            return 'PROTOCOL_ERROR';
-        case 1003:
-            return 'UNSUPPORTED_DATA';
-        case 1006:
-            return 'ABNORMAL_CLOSURE';
-        default:
-            return 'UNKNOWN';
-    }
-}
+
+Object.defineProperty(exports,"__esModule",{value:!0}),exports.CloseCodes=exports.Connection=void 0,exports.getClosureCause=function(e){if(e>=4e3)return r[e]??"UNKNOWN";switch(e){case 1e3:return"NORMAL_CLOSURE";case 1001:return"GOING_AWAY";case 1002:return"PROTOCOL_ERROR";case 1003:return"UNSUPPORTED_DATA";case 1006:return"ABNORMAL_CLOSURE";default:return"UNKNOWN"}};const e=require("./PacketProcessor"),t=require("./util/packets/BatchHelper");class s extends e.MiddlewareHolder{listeners;name;closed=!1;socket;_timers={};batcher;_on;_off;id;constructor(e,s,r,o,i){super(),this.id=s,this.listeners={},this.name=r,this.socket=e,this.batcher=new t.BatchHelper,this._on=o,this._off=i,this._on("close",()=>{this.callMiddleware("onStatusChange",WebSocket.CLOSED),this.closed=!0;for(const[e,t,s]of Object.values(this._timers))this.clearTimeout(e),s&&t(!0)}),this._on("open",()=>this.callMiddleware("onStatusChange",WebSocket.OPEN))}setTimeout(e,t,s=!1){const r=setTimeout(()=>{e(),this.clearTimeout(r)},t);return this._timers[r]=[r,e,s],r}setInterval(e,t,s=!1){const r=setInterval(e,t);return this._timers[r]=[r,e,s],r}clearTimeout(e){clearTimeout(e),delete this._timers[e]}clearInterval(e){this.clearTimeout(e)}raw_send(e){this.socket.send(e)}raw_onmessage(e){this._on("message",e)}close(e=1e3,t){this.closed=!0,this.socket.close(e,t?.toString())}isClosed(){return this.closed||this.socket.readyState==WebSocket.CLOSED}async setName(e){await this.callMiddleware("onNameChange",e)||(this.name=e)}getName(){return this.name}}var r;exports.Connection=s,function(e){e[e.RATELIMIT=4e3]="RATELIMIT",e[e.SMALL=4001]="SMALL",e[e.INVALID_KEY=4002]="INVALID_KEY",e[e.INVALID_PACKET=4003]="INVALID_PACKET",e[e.INVALID_DATA=4004]="INVALID_DATA",e[e.REPEATED_HANDSHAKE=4005]="REPEATED_HANDSHAKE",e[e.DISABLED_PACKET=4006]="DISABLED_PACKET",e[e.MIDDLEWARE=4007]="MIDDLEWARE",e[e.MANUAL_SHUTDOWN=4008]="MANUAL_SHUTDOWN"}(r||(exports.CloseCodes=r={}));

package/dist/ws/PacketProcessor.d.ts

@@ -1,4 +1,7 @@
-import { Connection } from "./Connection";
+/**
+ * Copyright 2026 Lily (liwybloc)
+ * Licensed under the Apache License, Version 2.0.
+ */
 import { SonicWSConnection } from "./server/SonicWSConnection";
 /**
  * A basic middleware interface; extended by other middleware types
@@ -8,12 +11,12 @@ export interface BasicMiddleware {
      * Called when the middleware is initialized
      * @param conn The connection instance
      */
-    init?(conn: Connection): void;
+    init?(conn: IMiddlewareHolder<BasicMiddleware>): void;
 }
 export type FuncKeys<T> = {
     [K in keyof T]: NonNullable<T[K]> extends (...args: any[]) => any ? K : never;
 }[keyof T];
-export interface MiddlewareHolder<T extends BasicMiddleware> {
+export interface IMiddlewareHolder<T extends BasicMiddleware> {
     /**
      * Adds middleware which can interact with packets and other events
      */
@@ -25,6 +28,11 @@ export interface MiddlewareHolder<T extends BasicMiddleware> {
      */
     callMiddleware<K extends FuncKeys<T> & keyof T>(method: K, ...values: Parameters<NonNullable<Extract<T[K], (...args: any[]) => any>>>): Promise<boolean>;
 }
+export declare class MiddlewareHolder<T extends BasicMiddleware> implements IMiddlewareHolder<T> {
+    private middlewares;
+    addMiddleware(middleware: T): void;
+    callMiddleware<K extends FuncKeys<T> & keyof T>(method: K, ...values: Parameters<NonNullable<Extract<T[K], (...args: any[]) => any>>>): Promise<boolean>;
+}
 /**
  * A connection middleware interface, used in SonicWSConnection and ClientCore
  */

package/dist/ws/PacketProcessor.js

@@ -1,19 +1,6 @@
-"use strict";
-/*
+/**
  * Copyright 2026 Lily (liwybloc)
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * Licensed under the Apache License, Version 2.0.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-;
-;
+
+Object.defineProperty(exports,"__esModule",{value:!0}),exports.MiddlewareHolder=void 0;exports.MiddlewareHolder=class{middlewares=[];addMiddleware(e){this.middlewares.push(e);const r=e;try{"function"==typeof r.init&&r.init(this)}catch(e){console.warn("Middleware init threw an error:",e)}}async callMiddleware(e,...r){let t=!1;for(const d of this.middlewares){const i=d[e];if(i)try{await i(...r)&&(t=!0)}catch(r){console.warn(`Middleware ${String(e)} threw an error:`,r)}}return t}};

package/dist/ws/client/core/ClientCore.d.ts

@@ -1,52 +1,40 @@
-import { PacketHolder } from '../../util/packets/PacketHolder';
-import { Connection } from '../../Connection';
-import { AsyncPQ, ConnectionMiddleware, ClientPQ, PacketQueue, FuncKeys } from '../../PacketProcessor';
-export declare abstract class SonicWSCore implements Connection {
-    /** Raw 'ws' library connection / webjs WebSocket class */
-    socket: WebSocket;
-    protected listeners: {
-        message: Array<(data: Uint8Array) => void>;
-        send: Array<(data: Uint8Array) => void>;
-        close: Array<(event: CloseEvent) => void>;
-        event: {
-            [key: number]: Array<(...data: any[]) => void>;
-        };
-    };
+/**
+ * Copyright 2026 Lily (liwybloc)
+ * Licensed under the Apache License, Version 2.0.
+ */
+import { PacketHolder } from "../../util/packets/PacketHolder";
+import { Connection } from "../../Connection";
+import { AsyncPQ, ClientPQ, PacketQueue } from "../../PacketProcessor";
+export declare abstract class SonicWSCore<T extends {
+    readyState: number;
+    send: (u: Uint8Array<ArrayBufferLike>) => void;
+    close: (c: number, d: string | undefined) => void;
+}, K> extends Connection<T, K> {
     protected preListen: {
         [key: string]: Array<(data: any[]) => void>;
     } | null;
-    protected clientPackets: PacketHolder;
-    protected serverPackets: PacketHolder;
+    clientPackets: PacketHolder;
+    serverPackets: PacketHolder;
     private pastKeys;
     private readyListeners;
-    private batcher;
     private bufferHandler;
-    id: number;
     _timers: Record<number, [number, (closed: boolean) => void, boolean]>;
     private asyncData;
     private asyncMap;
-    constructor(ws: WebSocket, bufferHandler: (val: MessageEvent) => Promise<Uint8Array>);
+    constructor(ws: T, bufferHandler: (val: K) => Promise<Uint8Array>, on: Function, off: Function);
     private reading;
     private readQueue;
     private serverKeyHandler;
     private invalidPacket;
     private listenLock;
     private packetQueue;
-    listenPacket(data: string | [any[], boolean], code: number, packetQueue: PacketQueue<ClientPQ>, isAsync: boolean, asyncData: AsyncPQ<ClientPQ>): Promise<void>;
+    listenPacket(data: string | [any[], boolean], tag: string, packetQueue: PacketQueue<ClientPQ>, isAsync: boolean, asyncData: AsyncPQ<ClientPQ>): Promise<void>;
     private isAsync;
     private enqueuePacket;
     private triggerNextPacket;
-    private middlewares;
-    addMiddleware(middleware: ConnectionMiddleware): void;
-    callMiddleware<K extends FuncKeys<ConnectionMiddleware> & keyof ConnectionMiddleware>(method: K, ...values: Parameters<NonNullable<Extract<ConnectionMiddleware[K], (...args: any[]) => any>>>): Promise<boolean>;
     private dataHandler;
     private messageHandler;
-    protected listen(key: string, listener: (data: any[]) => void): void;
-    /**
-     * Listens for all messages rawly
-     * @param listener Callback for when data is received
-     */
-    raw_onmessage(listener: (data: Uint8Array) => void): void;
+    protected listen(tag: string, listener: (data: any[]) => void): void;
     /**
      * Listens for all sent messages rawly
      * @param listener Callback for when data is received
@@ -75,10 +63,4 @@ export declare abstract class SonicWSCore implements Connection {
      * @param listener The callback with the values
      */
     on(tag: string, listener: (value: any[]) => void): void;
-    raw_send(data: Uint8Array): void;
-    setTimeout(call: () => void, time: number, callOnClose?: boolean): number;
-    setInterval(call: () => void, time: number, callOnClose?: boolean): number;
-    clearTimeout(id: number): void;
-    clearInterval(id: number): void;
-    close(code?: number, reason?: string): void;
 }