@quenty/remoting 3.3.0 → 3.4.0-canary.241.a4e8214.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.4.0-canary.241.a4e8214.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/remoting@3.3.1...@quenty/remoting@3.4.0-canary.241.a4e8214.0) (2022-01-03)
+
+**Note:** Version bump only for package @quenty/remoting
+
+
+
+
+
+## [3.3.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/remoting@3.3.0...@quenty/remoting@3.3.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/remoting
+
+
+
+
+
 # [3.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/remoting@3.2.0...@quenty/remoting@3.3.0) (2021-12-18)
 
 **Note:** Version bump only for package @quenty/remoting

package/README.md

@@ -1,10 +1,10 @@
 ## Remoting
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -13,6 +13,8 @@
 
 Provides global remoting functionality for Roblox (GetRemoteEvent/GetRemoteFunction). This is extremely light-weight, but makes programming with global remotes a lot easier.
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/GetRemoteEvent">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/remoting --save

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/remoting",
-  "version": "3.3.0",
+  "version": "3.4.0-canary.241.a4e8214.0",
   "description": "Global remoting retrieval system for Roblox (RemoteFunctions/RemoteEvents)",
   "keywords": [
     "Roblox",
@@ -26,12 +26,12 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/loader": "^3.1.1",
-    "@quenty/promise": "^3.3.0",
-    "@quenty/table": "^2.1.0"
+    "@quenty/loader": "3.2.0-canary.241.a4e8214.0",
+    "@quenty/promise": "3.4.0-canary.241.a4e8214.0",
+    "@quenty/table": "2.1.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6eb398e9fb81191f0815885f807ab0cb3bb9bad1"
+  "gitHead": "a4e821471f35998d63f38a4f4a578e07b4e79035"
 }

package/src/Shared/GetRemoteEvent.lua

@@ -1,5 +1,41 @@
---- Provides getting remote events
--- @function GetRemoteEvent
+--[=[
+	Provides getting named global [RemoteEvent] resources.
+	@class GetRemoteEvent
+]=]
+
+--[=[
+	Retrieves a global remote event from the store. On the server, it constructs a new one,
+	and on the client, it waits for it to exist.
+
+	:::tip
+	Consider using [PromiseGetRemoteEvent] for a non-yielding version
+	:::
+
+	```lua
+	-- server.lua
+	local GetRemoteEvent = require("GetRemoteEvent")
+
+	local remoteEvent = GetRemoteEvent("testing")
+	remoteEvent.OnServerEvent:Connect(print)
+
+	-- client.lua
+	local GetRemoteEvent = require("GetRemoteEvent")
+
+	local remoteEvent = GetRemoteEvent("testing")
+	remoteEvent:FireServer("Hello") --> Hello (on the server)
+	```
+
+	:::info
+	If the game is not running, then a mock remote event will be created
+	for use in testing.
+	:::
+
+	@yields
+	@function GetRemoteEvent
+	@within GetRemoteEvent
+	@param name string
+	@return RemoteEvent
+]=]
 
 local require = require(script.Parent.loader).load(script)
 

package/src/Shared/GetRemoteFunction.lua

@@ -1,5 +1,44 @@
---- Provides getting remote events
--- @function GetRemoteFunction
+--[=[
+	Provides getting named global [RemoteFunction] resources.
+
+	@class GetRemoteFunction
+]=]
+
+--[=[
+	Retrieves a global remote function from the store. On the server, it constructs a new one,
+	and on the client, it waits for it to exist.
+
+	:::tip
+	Consider using [PromiseGetRemoteFunction] for a non-yielding version
+	:::
+
+	```lua
+	-- server.lua
+	local GetRemoteFunction = require("GetRemoteFunction")
+
+	local remoteFunction = GetRemoteFunction("testing")
+	remoteFunction.OnServerInvoke = function(_player, text)
+		return "HI " .. tostring(text)
+	end
+
+	-- client.lua
+	local GetRemoteFunction = require("GetRemoteFunction")
+
+	local remoteFunction = GetRemoteFunction("testing")
+	print(remoteFunction:InvokeServer("Bob")) --> HI Bob
+	```
+
+	:::info
+	If the game is not running, then a mock remote event will be created
+	for use in testing.
+	:::
+
+	@yields
+	@function GetRemoteFunction
+	@within GetRemoteFunction
+	@param name string
+	@return RemoteFunction
+]=]
 
 local require = require(script.Parent.loader).load(script)
 

package/src/Shared/PromiseGetRemoteEvent.lua

@@ -1,5 +1,7 @@
---- Retrieves a remote event as a promise
--- @module PromiseGetRemoteEvent
+--[=[
+	Retrieves a remote event as a promise
+	@class PromiseGetRemoteEvent
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -10,6 +12,14 @@ local GetRemoteEvent = require("GetRemoteEvent")
 local Promise = require("Promise")
 local ResourceConstants = require("ResourceConstants")
 
+--[=[
+	Like [GetRemoteEvent] but in promise form.
+
+	@function PromiseGetRemoteEvent
+	@within PromiseGetRemoteEvent
+	@param name string
+	@return Promise<RemoteEvent>
+]=]
 if not RunService:IsRunning() then
 	-- Handle testing
 	return function(name)

package/src/Shared/PromiseGetRemoteFunction.lua

@@ -1,5 +1,7 @@
---- Retrieves a remote function as a promise
--- @module PromiseGetRemoteFunction
+--[=[
+	Retrieves a remote function as a promise
+	@class PromiseGetRemoteFunction
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -10,6 +12,15 @@ local GetRemoteFunction = require("GetRemoteFunction")
 local Promise = require("Promise")
 local ResourceConstants = require("ResourceConstants")
 
+--[=[
+	Like [GetRemoteFunction] but in promise form.
+
+	@function PromiseGetRemoteFunction
+	@within PromiseGetRemoteFunction
+	@param name string
+	@return Promise<RemoteFunction>
+]=]
+
 if not RunService:IsRunning() then
 	-- Handle testing
 	return function(name)

package/src/Shared/PromiseRemoteEventMixin.lua

@@ -1,5 +1,7 @@
---- Intended for classes that extend BaseObject only
--- @module PromiseRemoteEventMixin
+--[=[
+	Intended for classes that extend BaseObject only
+	@class PromiseRemoteEventMixin
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -7,8 +9,37 @@ local promiseChild = require("promiseChild")
 
 local PromiseRemoteEventMixin = {}
 
+--[=[
+	Adds the remote function mixin to a class
+
+	```lua
+	local BaseObject = require("BaseObject")
+
+	local Bird = setmetatable({}, BaseObject)
+	Bird.ClassName = "Bird"
+	Bird.__index = Bird
+
+	require("PromiseRemoteEventMixin"):Add(Bird, "BirdRemoteEvent")
+
+	function Bird.new(inst)
+		local self = setmetatable(BaseObject.new(inst), Bird)
+
+		self:PromiseRemoteEvent():Then(function(remoteEvent)
+			self._maid:GiveTask(remoteEvent.OnClientEvent:Connect(function(...)
+				self:_handleRemoteEvent(...)
+			end)
+		end)
+
+		return self
+	end
+	```
+
+	@param class { _maid: Maid }
+	@param remoteEventName string
+]=]
 function PromiseRemoteEventMixin:Add(class, remoteEventName)
-	assert(remoteEventName, "Bad remoteEventName")
+	assert(type(class) == "table", "Bad class")
+	assert(type(remoteEventName) == "string", "Bad remoteEventName")
 	assert(not class.PromiseRemoteEventMixin, "Class already has PromiseRemoteEventMixin defined")
 	assert(not class._remoteEventName, "Class already has _remoteEventName defined")
 
@@ -16,7 +47,10 @@ function PromiseRemoteEventMixin:Add(class, remoteEventName)
 	class._remoteEventName = remoteEventName
 end
 
--- Initialize PromiseRemoteEventMixin
+--[=[
+	Returns a promise that returns a remote event
+	@return Promise<RemoteEvent>
+]=]
 function PromiseRemoteEventMixin:PromiseRemoteEvent()
 	return self._maid:GivePromise(promiseChild(self._obj, self._remoteEventName))
 end

package/src/Shared/PromiseRemoteFunctionMixin.lua

@@ -1,5 +1,7 @@
---- Intended for classes that extend BaseObject only
--- @module PromiseRemoteFunctionMixin
+--[=[
+	Intended for classes that extend BaseObject only
+	@class PromiseRemoteFunctionMixin
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -7,8 +9,37 @@ local promiseChild = require("promiseChild")
 
 local PromiseRemoteFunctionMixin = {}
 
+--[=[
+	Adds the remote function mixin to a class
+
+	```lua
+	local BaseObject = require("BaseObject")
+
+	local Bird = setmetatable({}, BaseObject)
+	Bird.ClassName = "Bird"
+	Bird.__index = Bird
+
+	require("PromiseRemoteFunctionMixin"):Add(Bird, "BirdRemoteFunction")
+
+	function Bird.new(inst)
+		local self = setmetatable(BaseObject.new(inst), Bird)
+
+		self:PromiseRemoteFunction():Then(function(remoteFunction)
+			task.spawn(function()
+				remoteFunction:InvokeServer() -- or whatever
+			end)
+		end)
+
+		return self
+	end
+	```
+
+	@param class { _maid: Maid }
+	@param remoteFunctionName string
+]=]
 function PromiseRemoteFunctionMixin:Add(class, remoteFunctionName)
-	assert(remoteFunctionName, "Bad remoteFunctionName")
+	assert(type(class) == "table", "Bad class")
+	assert(type(remoteFunctionName) == "string", "Bad remoteFunctionName")
 	assert(not class.PromiseRemoteFunctionMixin, "Class already has PromiseRemoteFunctionMixin defined")
 	assert(not class._remoteFunctionName, "Class already has _remoteFunctionName defined")
 
@@ -16,7 +47,10 @@ function PromiseRemoteFunctionMixin:Add(class, remoteFunctionName)
 	class._remoteFunctionName = remoteFunctionName
 end
 
--- Initialize PromiseRemoteFunctionMixin
+--[=[
+	Returns a promise that returns a remote function
+	@return Promise<RemoteFunction>
+]=]
 function PromiseRemoteFunctionMixin:PromiseRemoteFunction()
 	return self._maid:GivePromise(promiseChild(self._obj, self._remoteFunctionName))
 end

package/src/Shared/ResourceConstants.lua

@@ -1,5 +1,8 @@
---- Holds constants for resource retrieval
--- @module ResourceConstants
+--[=[
+	Holds constants for resource retrieval.
+	@class ResourceConstants
+	@private
+]=]
 
 local require = require(script.Parent.loader).load(script)