@rbxts/tether 1.0.8 → 1.0.10

package/README.md

@@ -1,6 +1,9 @@
 # Tether
 A message-based networking solution for Roblox with automatic binary serialization.
 
+> [!CAUTION]
+> Depends on `rbxts-transformer-flamework`!
+
 ## Usage
 
 ### In `shared/messaging.ts`
@@ -29,7 +32,7 @@ export interface MessageData {
 ```ts
 import { Message, messaging } from "shared/messaging";
 
-messaging.onServerMessage(Message.TEST, (player, data) => {
+messaging.onServerMessage(Message.Test, (player, data) => {
   print(player, "sent data:", data);
 });
 ```
@@ -38,27 +41,49 @@ messaging.onServerMessage(Message.TEST, (player, data) => {
 ```ts
 import { Message, messaging } from "shared/messaging";
 
-messaging.emitServer(Message.TEST, {
+messaging.emitServer(Message.Test, {
   foo: "bar",
   n: 69
 });
 ```
 
 ## Middleware
+Drop or delay requests
 
 ### Creating middleware
+
+#### Client, Global
+```ts
+import type { ClientGlobalMiddleware } from "@rbxts/tether";
+
+export function logClient(): ClientGlobalMiddleware {
+  return (player, data) => print(`[LOG]: Sent message to player ${player} with data:`, data);
+}
+```
+
+#### Server, Global
 ```ts
-import { type Middleware, DropRequest } from "@rbxts/tether";
+import type { ServerGlobalMiddleware } from "@rbxts/tether";
+
+export function logServer(): ServerGlobalMiddleware {
+  return data => print(`[LOG]: Sent message to server with data:`, data);
+}
+```
 
-export function rateLimit(interval: number): Middleware {
+#### Shared
+```ts
+import { type SharedMiddleware, DropRequest } from "@rbxts/tether";
+
+export function rateLimit(interval: number): SharedMiddleware<MessageData> {
   let lastRequest = 0;
 
-  return () => {
-    if (os.clock() - lastRequest < interval)
-      return DropRequest;
+  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();
-  };
+      lastRequest = os.clock();
+    };
 }
 ```
 
@@ -72,11 +97,11 @@ 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)]) 
-  // automatically validates that data sent through the remote
-  // matches the data associated with the message at runtime
+  // automatically validates that the data sent through the remote matches
+  // the data associated with the message at runtime using type guards
   .useShared(Message.Test, [BuiltinMiddlewares.validateClient()])
-  // rate limit every server remote (global)
-  .useServerGlobal([BuiltinMiddlewares.rateLimit(1)]);
+  .useClientGlobal([logClient()]);
+  .useServerGlobal([logServer()]);
 
 export const enum Message {
   Test

package/out/builtin-middlewares.d.ts

@@ -3,27 +3,30 @@ import { type SharedMiddleware, type ServerMiddleware, type ClientMiddleware } f
 type Guard<T> = (value: unknown) => value is T;
 export declare namespace BuiltinMiddlewares {
     /**
-     * Creates a universal middleware that will drop any message that occurs within the given interval of the previous message.
-     * @param interval The interval in seconds that the middleware should wait before allowing a new request.
-     * @returns A middleware that will drop any message that occurs within the given interval.
+     * Creates a shared per-message middleware that will drop any message that occurs within the given interval of the previous message
+     *
+     * @param interval The interval in seconds that the middleware should wait before allowing a new request
+     * @returns A middleware that will drop any message that occurs within the given interval
      */
     function rateLimit(interval: number): SharedMiddleware;
     /**
-     * Creates a server middleware that validates the data with the given guard (or a generated guard if none was provided).
-     * If the guard fails, the middleware will drop the message.
+     * Creates a server middleware that validates the data with the given guard (or a generated guard if none was provided)
      *
-     * @param guard The guard to use to validate the data.
-     * @returns A server middleware that validates the data with the given guard.
-     * @macro
+     * If the guard fails, the middleware will drop the message
+     *
+     * @param guard The guard to use to validate the data
+     * @returns A server middleware that validates the data with the given guard
+     * @metadata macro
      */
     function validateServer<T>(guard?: Guard<T> | Modding.Generic<T, "guard">): ServerMiddleware<T>;
     /**
-     * Creates a server middleware that validates the data with the given guard (or a generated guard if none was provided).
-     * If the guard fails, the middleware will drop the message.
+     * Creates a client middleware that validates the data with the given guard (or a generated guard if none was provided)
+     *
+     * If the guard fails, the middleware will drop the message
      *
      * @param guard The guard to use to validate the data.
-     * @returns A server middleware that validates the data with the given guard.
-     * @macro
+     * @returns A client middleware that validates the data with the given guard.
+     * @metadata macro
      */
     function validateClient<T>(guard?: Guard<T> | Modding.Generic<T, "guard">): ClientMiddleware<T>;
 }

package/out/builtin-middlewares.luau

@@ -1,38 +1,47 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
 local DropRequest = TS.import(script, script.Parent, "middleware").DropRequest
-local noOp = function() end
+local noOp = function()
+	return function() end
+end
 local validationGuardGenerationFailed = function(context)
 	return `[@rbxts/tether]: Failed to generate guard for validate{context}<T> builtin middleware - skipping validation`
 end
+local guardFailed = function(message)
+	return `[@rbxts/tether]: Type validation failed for message '{tostring(message)}' - check your sent data`
+end
 local BuiltinMiddlewares = {}
 do
 	local _container = BuiltinMiddlewares
 	--[[
 		*
-		     * Creates a universal middleware that will drop any message that occurs within the given interval of the previous message.
-		     * @param interval The interval in seconds that the middleware should wait before allowing a new request.
-		     * @returns A middleware that will drop any message that occurs within the given interval.
+		     * Creates a shared per-message middleware that will drop any message that occurs within the given interval of the previous message
+		     *
+		     * @param interval The interval in seconds that the middleware should wait before allowing a new request
+		     * @returns A middleware that will drop any message that occurs within the given interval
 		     
 	]]
 	local function rateLimit(interval)
 		local lastRequest = 0
 		return function()
-			if os.clock() - lastRequest < interval then
-				return DropRequest
+			return function()
+				if os.clock() - lastRequest < interval then
+					return DropRequest
+				end
+				lastRequest = os.clock()
 			end
-			lastRequest = os.clock()
 		end
 	end
 	_container.rateLimit = rateLimit
 	--[[
 		*
-		     * Creates a server middleware that validates the data with the given guard (or a generated guard if none was provided).
-		     * If the guard fails, the middleware will drop the message.
+		     * Creates a server middleware that validates the data with the given guard (or a generated guard if none was provided)
 		     *
-		     * @param guard The guard to use to validate the data.
-		     * @returns A server middleware that validates the data with the given guard.
-		     * @macro
+		     * If the guard fails, the middleware will drop the message
+		     *
+		     * @param guard The guard to use to validate the data
+		     * @returns A server middleware that validates the data with the given guard
+		     * @metadata macro
 		     
 	]]
 	local function validateServer(guard)
@@ -40,22 +49,26 @@ do
 			warn(validationGuardGenerationFailed("Server"))
 			return noOp
 		end
-		return function(data)
-			if guard(data) then
-				return nil
+		return function(message)
+			return function(data)
+				if guard(data) then
+					return nil
+				end
+				warn(guardFailed(message))
+				return DropRequest
 			end
-			return DropRequest
 		end
 	end
 	_container.validateServer = validateServer
 	--[[
 		*
-		     * Creates a server middleware that validates the data with the given guard (or a generated guard if none was provided).
-		     * If the guard fails, the middleware will drop the message.
+		     * Creates a client middleware that validates the data with the given guard (or a generated guard if none was provided)
+		     *
+		     * If the guard fails, the middleware will drop the message
 		     *
 		     * @param guard The guard to use to validate the data.
-		     * @returns A server middleware that validates the data with the given guard.
-		     * @macro
+		     * @returns A client middleware that validates the data with the given guard.
+		     * @metadata macro
 		     
 	]]
 	local function validateClient(guard)
@@ -63,11 +76,14 @@ do
 			warn(validationGuardGenerationFailed("Client"))
 			return noOp
 		end
-		return function(data)
-			if guard(data) then
-				return nil
+		return function(message)
+			return function(player, data)
+				if guard(data) then
+					return nil
+				end
+				warn(guardFailed(message))
+				return DropRequest
 			end
-			return DropRequest
 		end
 	end
 	_container.validateClient = validateClient

package/out/index.d.ts

@@ -1,3 +1,3 @@
 export { MessageEmitter } from "./message-emitter";
 export { BuiltinMiddlewares } from "./builtin-middlewares";
-export { DropRequest, type ClientMiddleware, type ServerMiddleware, type Middleware } from "./middleware";
+export { DropRequest, type ClientMiddleware, type ServerMiddleware, type SharedMiddleware, type Middleware, type ClientGlobalMiddleware, type ServerGlobalMiddleware, type SharedGlobalMiddleware, type GlobalMiddleware } from "./middleware";

package/out/message-emitter.d.ts

@@ -16,37 +16,37 @@ export declare class MessageEmitter<MessageData> extends Destroyable {
     }>): MessageEmitter<MessageData>;
     private constructor();
     /**.
-     * @returns A destructor function that disconnects the callback from the message.
+     * @returns A destructor function that disconnects the callback from the message
      */
     onServerMessage<Kind extends keyof MessageData>(message: Kind, callback: ServerMessageCallback<MessageData[Kind]>): () => void;
     /**.
-     * @returns A destructor function that disconnects the callback from the message.
+     * @returns A destructor function that disconnects the callback from the message
      */
     onClientMessage<Kind extends keyof MessageData>(message: Kind, callback: ClientMessageCallback<MessageData[Kind]>): () => void;
     private on;
     /**
-     * Emits a message to all connected clients.
+     * Emits a message to all connected clients
      *
-     * @param message - The message kind to be sent.
-     * @param data - The data associated with the message.
-     * @param unreliable - Optional flag indicating if the message should be sent unreliably.
+     * @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
      */
     emitServer<Kind extends keyof MessageData>(message: Kind, data?: MessageData[Kind], unreliable?: boolean): void;
     /**
-     * Emits a message to a specific client.
+     * Emits a message to a specific client
      *
-     * @param player - The player to whom the message is sent.
-     * @param message - The message kind to be sent.
-     * @param data - The data associated with the message.
-     * @param unreliable - Optional flag indicating if the message should be sent unreliably.
+     * @param player The player 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
      */
     emitClient<Kind extends keyof MessageData>(player: Player, message: Kind, data?: MessageData[Kind], unreliable?: boolean): void;
     /**
-     * Emits a message to all connected clients.
+     * Emits a message to all connected clients
      *
-     * @param message - The message kind to be sent.
-     * @param data - The data associated with the message.
-     * @param unreliable - Optional flag indicating if the message should be sent unreliably.
+     * @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
      */
     emitAllClients<Kind extends keyof MessageData>(message: Kind, data?: MessageData[Kind], unreliable?: boolean): void;
     private initialize;

package/out/message-emitter.luau

@@ -132,14 +132,14 @@ do
 		if unreliable == nil then
 			unreliable = false
 		end
-		for _, middleware in self.middleware:getServerGlobal() do
-			local result = middleware(data)
+		for _, globalMiddleware in self.middleware:getServerGlobal() do
+			local result = globalMiddleware(data)
 			if result == DropRequest then
 				return nil
 			end
 		end
 		for _, middleware in self.middleware:getServer(message) do
-			local result = middleware(data)
+			local result = middleware(message)(data)
 			if result == DropRequest then
 				return nil
 			end
@@ -151,14 +151,14 @@ do
 		if unreliable == nil then
 			unreliable = false
 		end
-		for _, middleware in self.middleware:getClientGlobal() do
-			local result = middleware(player, data)
+		for _, globalMiddleware in self.middleware:getClientGlobal() do
+			local result = globalMiddleware(player, data)
 			if result == DropRequest then
 				return nil
 			end
 		end
 		for _, middleware in self.middleware:getClient(message) do
-			local result = middleware(player, data)
+			local result = middleware(message)(player, data)
 			if result == DropRequest then
 				return nil
 			end
@@ -170,9 +170,9 @@ do
 		if unreliable == nil then
 			unreliable = false
 		end
-		for _, middleware in self.middleware:getClientGlobal() do
+		for _, globalMiddleware in self.middleware:getClientGlobal() do
 			for _1, player in Players:GetPlayers() do
-				local result = middleware(player, data)
+				local result = globalMiddleware(player, data)
 				if result == DropRequest then
 					return nil
 				end
@@ -180,7 +180,7 @@ do
 		end
 		for _, middleware in self.middleware:getClient(message) do
 			for _1, player in Players:GetPlayers() do
-				local result = middleware(player, data)
+				local result = middleware(message)(player, data)
 				if result == DropRequest then
 					return nil
 				end

package/out/middleware.d.ts

@@ -1,11 +1,16 @@
+import type { BaseMessage } from "./structs";
 type DropRequestSymbol = symbol & {
     _skip_middleware?: undefined;
 };
 export declare const DropRequest: DropRequestSymbol;
-export type ClientMiddleware<Data = unknown> = (player: Player, data: Readonly<Data> | undefined) => DropRequestSymbol | void;
-export type ServerMiddleware<Data = unknown> = (data: Readonly<Data> | undefined) => DropRequestSymbol | void;
-export type SharedMiddleware = () => DropRequestSymbol | void;
+export type ClientMiddleware<Data = unknown> = (message: BaseMessage) => (player: Player, data: Readonly<Data> | undefined) => DropRequestSymbol | void;
+export type ServerMiddleware<Data = unknown> = (message: BaseMessage) => (data: Readonly<Data> | undefined) => DropRequestSymbol | void;
+export type SharedMiddleware = (message: BaseMessage) => () => DropRequestSymbol | void;
 export type Middleware<Data = unknown> = ServerMiddleware<Data> & ClientMiddleware<Data>;
+export type ClientGlobalMiddleware<Data = unknown> = (player: Player, data: Readonly<Data> | undefined) => DropRequestSymbol | void;
+export type ServerGlobalMiddleware<Data = unknown> = (data: Readonly<Data> | undefined) => DropRequestSymbol | void;
+export type SharedGlobalMiddleware = () => DropRequestSymbol | void;
+export type GlobalMiddleware<Data = unknown> = ServerGlobalMiddleware<Data> & ClientGlobalMiddleware<Data>;
 export declare class MiddlewareProvider<MessageData> {
     private readonly clientGlobalMiddlewares;
     private readonly serverGlobalMiddlewares;
@@ -16,14 +21,14 @@ export declare class MiddlewareProvider<MessageData> {
     /** @hidden */
     getServer<Kind extends keyof MessageData>(message: Kind): ServerMiddleware<MessageData[Kind]>[];
     /** @hidden */
-    getClientGlobal<Data>(): ClientMiddleware<Data>[];
+    getClientGlobal<Data>(): ClientGlobalMiddleware<Data>[];
     /** @hidden */
-    getServerGlobal<Data>(): ServerMiddleware<Data>[];
+    getServerGlobal<Data>(): ServerGlobalMiddleware<Data>[];
     useClient<Kind extends keyof MessageData>(message: Kind, middlewares: ClientMiddleware<MessageData[Kind]> | readonly ClientMiddleware<MessageData[Kind]>[], order?: number): this;
     useServer<Kind extends keyof MessageData>(message: Kind, middlewares: ServerMiddleware<MessageData[Kind]> | readonly ServerMiddleware<MessageData[Kind]>[], order?: number): this;
     useShared<Kind extends keyof MessageData>(message: Kind, middlewares: SharedMiddleware | readonly SharedMiddleware[], order?: number): this;
-    useClientGlobal<Data>(middlewares: ClientMiddleware<Data> | readonly ClientMiddleware<Data>[], order?: number): this;
-    useServerGlobal<Data>(middlewares: ServerMiddleware<Data> | readonly ServerMiddleware<Data>[], order?: number): this;
-    useSharedGlobal(middlewares: SharedMiddleware | readonly SharedMiddleware[], order?: number): this;
+    useClientGlobal<Data>(middlewares: ClientGlobalMiddleware<Data> | readonly ClientGlobalMiddleware<Data>[], order?: number): this;
+    useServerGlobal<Data>(middlewares: ServerGlobalMiddleware<Data> | readonly ServerGlobalMiddleware<Data>[], order?: number): this;
+    useSharedGlobal(middlewares: SharedGlobalMiddleware | readonly SharedGlobalMiddleware[], order?: number): this;
 }
 export {};

package/out/middleware.luau

@@ -78,7 +78,7 @@ do
 	function MiddlewareProvider:useClientGlobal(middlewares, order)
 		local globalMiddleware = self:getClientGlobal()
 		local _middlewares = middlewares
-		if typeof(_middlewares) == "function" then
+		if type(_middlewares) == "function" then
 			local _condition = order
 			if _condition == nil then
 				_condition = #globalMiddleware - 1
@@ -95,7 +95,7 @@ do
 	function MiddlewareProvider:useServerGlobal(middlewares, order)
 		local globalMiddleware = self:getServerGlobal()
 		local _middlewares = middlewares
-		if typeof(_middlewares) == "function" then
+		if type(_middlewares) == "function" then
 			local _condition = order
 			if _condition == nil then
 				_condition = #globalMiddleware - 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/tether",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "main": "out/init.lua",
   "scripts": {
     "build": "rbxtsc",
@@ -32,13 +32,13 @@
   "devDependencies": {
     "@rbxts/compiler-types": "^3.0.0-types.0",
     "@rbxts/types": "^1.0.835",
-    "rbxts-transformer-flamework": "latest",
+    "rbxts-transformer-flamework": "^1.2.4",
     "roblox-ts": "^3.0.0",
     "typescript": "^5.5.3"
   },
   "dependencies": {
-    "@flamework/core": "^1.2.3",
-    "@flamework/networking": "^1.2.3",
+    "@flamework/core": "^1.2.4",
+    "@flamework/networking": "^1.2.4",
     "@rbxts/destroyable": "^1.0.1",
     "@rbxts/flamework-binary-serializer": "^0.6.0",
     "@rbxts/services": "^1.5.5"