@rbxts/tether 1.2.2 → 1.2.4

package/README.md

@@ -1,197 +1,197 @@
-# Tether
-A message-based networking solution for Roblox with automatic binary serialization and type validation.
-
-> [!CAUTION]
-> Depends on `rbxts-transformer-flamework`!
-
-## Usage
-
-### In `shared/messaging.ts`
-```ts
-import type { DataType } from "@rbxts/flamework-binary-serializer";
-import { MessageEmitter } from "@rbxts/tether";
-
-export const messaging = MessageEmitter.create<MessageData>();
-
-export const enum Message {
-  Test,
-  Packed
-}
-
-export interface MessageData {
-  [Message.Test]: {
-    readonly foo: string;
-    readonly n: DataType.u8;
-  };
-  [Message.Packed]: DataType.Packed<{
-    readonly boolean1: boolean;
-    readonly boolean2: boolean;
-    readonly boolean3: boolean;
-    readonly boolean4: boolean;
-    readonly boolean5: boolean;
-    readonly boolean6: boolean;
-    readonly boolean7: boolean;
-    readonly boolean8: boolean;
-  }>;
-}
-```
-
-> [!CAUTION]
-> Every single message kind must implement an interface for it's data (in the example that would be the object types in `MessageData`). Message serialization (as well as your message itself) will not work if you don't do this.
-
-### Server
-```ts
-import { Message, messaging } from "shared/messaging";
-
-messaging.server.on(Message.Test, (player, data) => print(player, "sent data:", data));
-```
-
-### Client
-```ts
-import { Message, messaging } from "shared/messaging";
-
-messaging.server.emit(Message.Test, {
-  foo: "bar",
-  n: 69
-});
-```
-
-## Simulated Remote Functions
-Tether does not directly use RemoteFunctions since it's based on the MessageEmitter structure. However I have created a small framework to simulate remote functions, as shown below.
-
-For each function you will need two messages. One to invoke the function, and one to send the return value back (which is done automatically).
-
-### In `shared/messaging.ts`
-```ts
-import type { DataType } from "@rbxts/flamework-binary-serializer";
-import { MessageEmitter } from "@rbxts/tether";
-
-export const messaging = MessageEmitter.create<MessageData>();
-
-export const enum Message {
-  Increment,
-  IncrementReturn
-}
-
-export interface MessageData {
-  [Message.Increment]: DataType.u8;
-  [Message.IncrementReturn]: DataType.u8;
-}
-```
-
-### Server
-```ts
-import { Message, messaging } from "shared/messaging";
-
-messaging.server.setCallback(Message.Increment, Message.IncrementReturn, (_, n) => n + 1);
-```
-
-### Client
-```ts
-import { Message, messaging } from "shared/messaging";
-
-messaging.server
-  .invoke(Message.Increment, Message.IncrementReturn, 69)
-  .then(print); // 70 - incremented by the server
-
-// or use await style
-async function main(): Promise<void> {
-  const value = await messaging.server.invoke(Message.Increment, Message.IncrementReturn, 69);
-  print(value) // 70
-}
-
-main();
-```
-
-## Middleware
-Drop, delay, or modify requests
-
-### Creating middleware
-
-**Note:** These client/server middlewares can be implemented as shared middlewares. This is strictly an example.
-#### Client
-```ts
-import type { ClientMiddleware } from "@rbxts/tether";
-
-export function logClient(): ClientMiddleware {
-  return message => (player, ctx) => print(`[LOG]: Sent message '${message}' to player ${player} with data:`, ctx.data);
-}
-```
-
-#### Server
-```ts
-import type { ServerMiddleware } from "@rbxts/tether";
-
-export function logServer(): ServerMiddleware {
-  return message => ctx => print(`[LOG]: Sent message '${message}' to server with data:`, ctx.data);
-}
-```
-
-#### Shared
-```ts
-import { type SharedMiddleware, DropRequest } from "@rbxts/tether";
-
-export function rateLimit(interval: number): SharedMiddleware {
-  let lastRequest = 0;
-
-  return message => // message attempting to be sent
-    () => { // no data/player - it's a shared middleware
-      if (os.clock() - lastRequest < interval)
-        return DropRequest;
-
-      lastRequest = os.clock();
-    };
-}
-```
-
-#### Transforming data
-```ts
-import type { ServerMiddleware } from "@rbxts/tether";
-
-export function incrementNumberData(): ServerMiddleware<number> {
-  // sets the data to be used by the any subsequent middlewares as well as sent through the remote
-  return () => ({ data, updateData }) => updateData(data + 1);
-}
-```
-
-### Using middleware
-```ts
-import type { DataType } from "@rbxts/flamework-binary-serializer";
-import { MessageEmitter, BuiltinMiddlewares } from "@rbxts/tether";
-
-export const messaging = MessageEmitter.create<MessageData>();
-messaging.middleware
-  // only allows requests to the server every 5 seconds,
-  // drops any requests that occur within 5 seconds of each other
-  .useServer(Message.Test, BuiltinMiddlewares.rateLimit(5)) 
-  // will be just one byte!
-  .useShared(Message.Packed, () => ctx => print("Packed object size:", buffer.len(ctx.getRawData().buffer)));
-  // logs every message fired
-  .useServerGlobal(logServer())
-  .useClientGlobal(logClient())
-  .useSharedGlobal(BuiltinMiddlewares.debug()); // verbosely logs every packet sent
-  .useServer(Message.Test, incrementNumberData()) // error! - data for Message.Test is not a number 
-  .useServerGlobal(incrementNumberData()); // error! - global data type is always 'unknown', we cannot guarantee a number
-
-export const enum Message {
-  Test,
-  Packed
-}
-
-export interface MessageData {
-  [Message.Test]: {
-    readonly foo: string;
-    readonly n: DataType.u8;
-  };
-  [Message.Packed]: DataType.Packed<{
-    readonly boolean1: boolean;
-    readonly boolean2: boolean;
-    readonly boolean3: boolean;
-    readonly boolean4: boolean;
-    readonly boolean5: boolean;
-    readonly boolean6: boolean;
-    readonly boolean7: boolean;
-    readonly boolean8: boolean;
-  }>;
-}
+# Tether
+A message-based networking solution for Roblox with automatic binary serialization and type validation.
+
+> [!CAUTION]
+> Depends on `rbxts-transformer-flamework`!
+
+## Usage
+
+### In `shared/messaging.ts`
+```ts
+import type { DataType } from "@rbxts/flamework-binary-serializer";
+import { MessageEmitter } from "@rbxts/tether";
+
+export const messaging = MessageEmitter.create<MessageData>();
+
+export const enum Message {
+  Test,
+  Packed
+}
+
+export interface MessageData {
+  [Message.Test]: {
+    readonly foo: string;
+    readonly n: DataType.u8;
+  };
+  [Message.Packed]: DataType.Packed<{
+    readonly boolean1: boolean;
+    readonly boolean2: boolean;
+    readonly boolean3: boolean;
+    readonly boolean4: boolean;
+    readonly boolean5: boolean;
+    readonly boolean6: boolean;
+    readonly boolean7: boolean;
+    readonly boolean8: boolean;
+  }>;
+}
+```
+
+> [!CAUTION]
+> Every single message kind must implement an interface for it's data (in the example that would be the object types in `MessageData`). Message serialization (as well as your message itself) will not work if you don't do this.
+
+### Server
+```ts
+import { Message, messaging } from "shared/messaging";
+
+messaging.server.on(Message.Test, (player, data) => print(player, "sent data:", data));
+```
+
+### Client
+```ts
+import { Message, messaging } from "shared/messaging";
+
+messaging.server.emit(Message.Test, {
+  foo: "bar",
+  n: 69
+});
+```
+
+## Simulated Remote Functions
+Tether does not directly use RemoteFunctions since it's based on the MessageEmitter structure. However I have created a small framework to simulate remote functions, as shown below.
+
+For each function you will need two messages. One to invoke the function, and one to send the return value back (which is done automatically).
+
+### In `shared/messaging.ts`
+```ts
+import type { DataType } from "@rbxts/flamework-binary-serializer";
+import { MessageEmitter } from "@rbxts/tether";
+
+export const messaging = MessageEmitter.create<MessageData>();
+
+export const enum Message {
+  Increment,
+  IncrementReturn
+}
+
+export interface MessageData {
+  [Message.Increment]: DataType.u8;
+  [Message.IncrementReturn]: DataType.u8;
+}
+```
+
+### Server
+```ts
+import { Message, messaging } from "shared/messaging";
+
+messaging.server.setCallback(Message.Increment, Message.IncrementReturn, (_, n) => n + 1);
+```
+
+### Client
+```ts
+import { Message, messaging } from "shared/messaging";
+
+messaging.server
+  .invoke(Message.Increment, Message.IncrementReturn, 69)
+  .then(print); // 70 - incremented by the server
+
+// or use await style
+async function main(): Promise<void> {
+  const value = await messaging.server.invoke(Message.Increment, Message.IncrementReturn, 69);
+  print(value) // 70
+}
+
+main();
+```
+
+## Middleware
+Drop, delay, or modify requests
+
+### Creating middleware
+
+**Note:** These client/server middlewares can be implemented as shared middlewares. This is strictly an example.
+#### Client
+```ts
+import type { ClientMiddleware } from "@rbxts/tether";
+
+export function logClient(): ClientMiddleware {
+  return message => (player, ctx) => print(`[LOG]: Sent message '${message}' to player ${player} with data:`, ctx.data);
+}
+```
+
+#### Server
+```ts
+import type { ServerMiddleware } from "@rbxts/tether";
+
+export function logServer(): ServerMiddleware {
+  return message => ctx => print(`[LOG]: Sent message '${message}' to server with data:`, ctx.data);
+}
+```
+
+#### Shared
+```ts
+import { type SharedMiddleware, DropRequest } from "@rbxts/tether";
+
+export function rateLimit(interval: number): SharedMiddleware {
+  let lastRequest = 0;
+
+  return message => // message attempting to be sent
+    () => { // no data/player - it's a shared middleware
+      if (os.clock() - lastRequest < interval)
+        return DropRequest;
+
+      lastRequest = os.clock();
+    };
+}
+```
+
+#### Transforming data
+```ts
+import type { ServerMiddleware } from "@rbxts/tether";
+
+export function incrementNumberData(): ServerMiddleware<number> {
+  // sets the data to be used by the any subsequent middlewares as well as sent through the remote
+  return () => ({ data, updateData }) => updateData(data + 1);
+}
+```
+
+### Using middleware
+```ts
+import type { DataType } from "@rbxts/flamework-binary-serializer";
+import { MessageEmitter, BuiltinMiddlewares } from "@rbxts/tether";
+
+export const messaging = MessageEmitter.create<MessageData>();
+messaging.middleware
+  // only allows requests to the server every 5 seconds,
+  // drops any requests that occur within 5 seconds of each other
+  .useServer(Message.Test, BuiltinMiddlewares.rateLimit(5)) 
+  // will be just one byte!
+  .useShared(Message.Packed, () => ctx => print("Packed object size:", buffer.len(ctx.getRawData().buffer)));
+  // logs every message fired
+  .useServerGlobal(logServer())
+  .useClientGlobal(logClient())
+  .useSharedGlobal(BuiltinMiddlewares.debug()); // verbosely logs every packet sent
+  .useServer(Message.Test, incrementNumberData()) // error! - data for Message.Test is not a number 
+  .useServerGlobal(incrementNumberData()); // error! - global data type is always 'unknown', we cannot guarantee a number
+
+export const enum Message {
+  Test,
+  Packed
+}
+
+export interface MessageData {
+  [Message.Test]: {
+    readonly foo: string;
+    readonly n: DataType.u8;
+  };
+  [Message.Packed]: DataType.Packed<{
+    readonly boolean1: boolean;
+    readonly boolean2: boolean;
+    readonly boolean3: boolean;
+    readonly boolean4: boolean;
+    readonly boolean5: boolean;
+    readonly boolean6: boolean;
+    readonly boolean7: boolean;
+    readonly boolean8: boolean;
+  }>;
+}
 ```

package/out/message-emitter.d.ts

@@ -61,14 +61,23 @@ export declare class MessageEmitter<MessageData> extends Destroyable {
          */
         once: <Kind extends keyof MessageData>(message: Kind & BaseMessage, callback: ClientMessageCallback<MessageData[Kind]>) => () => void;
         /**
-         * Emits a message to a specific client
+         * Emits a message to a specific client or multiple clients
          *
-         * @param player The player to whom the message is sent
+         * @param player The player(s) to whom the message is sent
          * @param message The message kind to be sent
          * @param data The data associated with the message
          * @param unreliable Whether the message should be sent unreliably
          */
         emit: <Kind extends keyof MessageData>(player: Player | Player[], message: Kind & BaseMessage, data?: MessageData[Kind], unreliable?: boolean) => void;
+        /**
+         * Emits a message to all clients except the specified client(s)
+         *
+         * @param player The player(s) to whom the message is not sent
+         * @param message The message kind to be sent
+         * @param data The data associated with the message
+         * @param unreliable Whether the message should be sent unreliably
+         */
+        emitExcept: <Kind extends keyof MessageData>(player: Player | Player[], message: Kind & BaseMessage, data?: MessageData[Kind], unreliable?: boolean) => void;
         /**
          * Emits a message to all connected clients
          *
@@ -94,6 +103,7 @@ export declare class MessageEmitter<MessageData> extends Destroyable {
     };
     private validateData;
     private initialize;
+    private onRemoteFire;
     private readMessageFromPacket;
     private executeFunctions;
     private executeEventCallbacks;

package/out/message-emitter.luau

@@ -175,6 +175,36 @@ do
 					send(player, getPacket())
 				end)
 			end,
+			emitExcept = function(player, message, data, unreliable)
+				if unreliable == nil then
+					unreliable = false
+				end
+				local shouldSendTo = function(p)
+					local _player = player
+					local _result
+					if typeof(_player) == "Instance" then
+						_result = p ~= player
+					else
+						local _player_1 = player
+						local _p = p
+						_result = not (table.find(_player_1, _p) ~= nil)
+					end
+					return _result
+				end
+				local _client = self.client
+				local _exp = Players:GetPlayers()
+				-- ▼ ReadonlyArray.filter ▼
+				local _newValue = {}
+				local _length = 0
+				for _k, _v in _exp do
+					if shouldSendTo(_v, _k - 1, _exp) == true then
+						_length += 1
+						_newValue[_length] = _v
+					end
+				end
+				-- ▲ ReadonlyArray.filter ▲
+				_client.emit(_newValue, message, data, unreliable)
+			end,
 			emitAll = function(message, data, unreliable)
 				if unreliable == nil then
 					unreliable = false
@@ -342,19 +372,26 @@ do
 	function MessageEmitter:initialize()
 		if RunService:IsClient() then
 			self.janitor:Add(self.clientEvents.sendClientMessage:connect(function(serializedPacket)
-				local sentMessage = self:readMessageFromPacket(serializedPacket)
-				self:executeEventCallbacks(sentMessage, serializedPacket)
-				self:executeFunctions(sentMessage, serializedPacket)
+				return self:onRemoteFire(serializedPacket)
+			end))
+			self.janitor:Add(self.clientEvents.sendUnreliableClientMessage:connect(function(serializedPacket)
+				return self:onRemoteFire(serializedPacket)
 			end))
 		else
 			self.janitor:Add(self.serverEvents.sendServerMessage:connect(function(player, serializedPacket)
-				local sentMessage = self:readMessageFromPacket(serializedPacket)
-				self:executeEventCallbacks(sentMessage, serializedPacket, player)
-				self:executeFunctions(sentMessage, serializedPacket)
+				return self:onRemoteFire(serializedPacket, player)
+			end))
+			self.janitor:Add(self.serverEvents.sendUnreliableServerMessage:connect(function(player, serializedPacket)
+				return self:onRemoteFire(serializedPacket, player)
 			end))
 		end
 		return self
 	end
+	function MessageEmitter:onRemoteFire(serializedPacket, player)
+		local sentMessage = self:readMessageFromPacket(serializedPacket)
+		self:executeEventCallbacks(sentMessage, serializedPacket, player)
+		self:executeFunctions(sentMessage, serializedPacket)
+	end
 	function MessageEmitter:readMessageFromPacket(serializedPacket)
 		return buffer.readu8(serializedPacket.buffer, 0)
 	end

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/tether",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "main": "out/init.lua",
   "scripts": {
     "build": "rbxtsc",