sonic-ws 1.3.0 → 1.3.1

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/index.js

@@ -1,19 +1,9 @@
-"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.
  */
+"use strict";
+
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WrapEnum = exports.DefineEnum = exports.UnFlattenData = exports.FlattenData = exports.CreateEnumPacket = exports.CreateObjPacket = exports.CreatePacket = exports.PacketType = exports.SonicWSServer = exports.SonicWSConnection = exports.SonicWS = void 0;
 var ClientNode_1 = require("./ws/client/node/ClientNode");

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,15 @@
-"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.
  */
+"use strict";
+
 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.VERSION = 20;
+
 exports.SERVER_SUFFIX = "SWS";
-/** Server data suffix in array */
+
 exports.SERVER_SUFFIX_NUMS = (0, StringUtil_1.processCharCodes)(exports.SERVER_SUFFIX);

package/dist/ws/Connection.d.ts

@@ -1,48 +1,35 @@
-import { ConnectionMiddleware, MiddlewareHolder } from "./PacketProcessor";
 /**
- * Holds shared connection values. Lets helper functions work on client and server.
+ * Copyright 2026 Lily (liwybloc)
+ * Licensed under the Apache License, Version 2.0.
  */
-export interface Connection extends MiddlewareHolder<ConnectionMiddleware> {
-    /**
-     * List of timers.
-     * For internal use only.
-     */
+import { ConnectionMiddleware, MiddlewareHolder } from "./PacketProcessor";
+import { BatchHelper } from "./util/packets/BatchHelper";
+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]>;
-    /**
-     * Sets a timeout that will automatically end when the socket closes
-     * @param call The function to call
-     * @param time The time between now and the call (ms)
-     * @param callOnClose If the callback should be fired anyways when the socket closes
-     * @returns The timeout id to be used with socket.clearInterval(id)
-     */
-    setTimeout(call: () => void, time: number, callOnClose: boolean): number;
-    /**
-     * Sets an interval that will automatically end when the socket closes
-     * @param call The function to call
-     * @param time The time between calls (ms)
-     * @returns The interval id to be used with socket.clearInterval(id)
-     */
-    setInterval(call: () => void, time: number): number;
-    /**
-     * Clears a timeout/interval
-     * @param id The timeout id
-     */
-    clearTimeout(index: number): void;
-    /**
-     * Clears an interval
-     *
-     * Delegates to `clearTimeout`
-     * @param id The interval id
-     */
-    clearInterval(index: number): void;
-    /**
-     * Sends raw uint8array data through the connection
-     */
+    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;
-    /**
-     * Closes the connection
-     */
-    close(code?: number, reason?: string): 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,22 +1,88 @@
-"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.
  */
+"use strict";
+
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CloseCodes = void 0;
+exports.CloseCodes = exports.Connection = void 0;
 exports.getClosureCause = getClosureCause;
+const PacketProcessor_1 = require("./PacketProcessor");
+const BatchHelper_1 = require("./util/packets/BatchHelper");
+class Connection extends PacketProcessor_1.MiddlewareHolder {
+    listeners;
+    name;
+    closed = false;
+    socket;
+    _timers = {};
+    batcher;
+    _on;
+    _off;
+    
+    id;
+    constructor(socket, id, name, addListener, removeListener) {
+        super();
+        this.id = id;
+        this.listeners = {};
+        this.name = name;
+        this.socket = socket;
+        this.batcher = new BatchHelper_1.BatchHelper();
+        this._on = addListener;
+        this._off = removeListener;
+        this._on("close", () => {
+            this.callMiddleware('onStatusChange', WebSocket.CLOSED);
+            this.closed = true;
+            for (const [id, callback, shouldCall] of Object.values(this._timers)) {
+                this.clearTimeout(id);
+                if (shouldCall)
+                    callback(true);
+            }
+        });
+        this._on('open', () => this.callMiddleware('onStatusChange', WebSocket.OPEN));
+    }
+    setTimeout(call, time, callOnClose = false) {
+        const timeout = setTimeout(() => {
+            call();
+            this.clearTimeout(timeout);
+        }, time);
+        this._timers[timeout] = [timeout, call, callOnClose];
+        return timeout;
+    }
+    setInterval(call, time, callOnClose = false) {
+        const interval = setInterval(call, time);
+        this._timers[interval] = [interval, call, callOnClose];
+        return interval;
+    }
+    clearTimeout(id) {
+        clearTimeout(id);
+        delete this._timers[id];
+    }
+    clearInterval(id) {
+        this.clearTimeout(id);
+    }
+    raw_send(data) {
+        this.socket.send(data);
+    }
+    raw_onmessage(listener) {
+        this._on("message", listener);
+    }
+    close(code = 1000, reason) {
+        this.closed = true;
+        this.socket.close(code, reason?.toString());
+    }
+    isClosed() {
+        return this.closed || this.socket.readyState == WebSocket.CLOSED;
+    }
+    async setName(name) {
+        if (await this.callMiddleware("onNameChange", name))
+            return;
+        this.name = name;
+    }
+    getName() {
+        return this.name;
+    }
+}
+exports.Connection = Connection;
 var CloseCodes;
 (function (CloseCodes) {
     CloseCodes[CloseCodes["RATELIMIT"] = 4000] = "RATELIMIT";

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,42 @@
-"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.
  */
+"use strict";
+
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiddlewareHolder = void 0;
+class MiddlewareHolder {
+    middlewares = [];
+    addMiddleware(middleware) {
+        this.middlewares.push(middleware);
+        const m = middleware;
+        try {
+            if (typeof m.init === 'function')
+                m.init(this);
+        }
+        catch (e) {
+            console.warn('Middleware init threw an error:', e);
+        }
+    }
+    async callMiddleware(method, ...values) {
+        let cancelled = false;
+        for (const middleware of this.middlewares) {
+            const fn = middleware[method];
+            if (!fn)
+                continue;
+            try {
+                if (await fn(...values)) {
+                    cancelled = true;
+                }
+            }
+            catch (e) {
+                console.warn(`Middleware ${String(method)} threw an error:`, e);
+            }
+        }
+        return cancelled;
+    }
+}
+exports.MiddlewareHolder = MiddlewareHolder;
 ;
 ;

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;
 }