@quenty/signal 2.4.0 → 3.0.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/signal@2.4.0...@quenty/signal@3.0.0) (2023-10-11)
+
+
+### Features
+
+* Use GoodSignal only as signal implementation ([4475cab](https://github.com/Quenty/NevermoreEngine/commit/4475cab448564a8cf8e51902e30f5c486bf49ac3))
+
+
+
+
+
 # [2.4.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/signal@2.3.0...@quenty/signal@2.4.0) (2023-05-26)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/signal",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "A simple signal implementation for Roblox",
   "keywords": [
     "Roblox",
@@ -29,5 +29,8 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "11058e90e51ea83d3dad6ae9abe59cc19c36b94b"
+  "dependencies": {
+    "@quenty/loader": "^7.0.0"
+  },
+  "gitHead": "fdeae46099587019ec5fc15317dc673aed379400"
 }

package/src/Shared/GoodSignal.lua

@@ -1,27 +1,47 @@
---------------------------------------------------------------------------------
---               Batched Yield-Safe Signal Implementation                     --
--- This is a Signal class which has effectively identical behavior to a       --
--- normal RBXScriptSignal, with the only difference being a couple extra      --
--- stack frames at the bottom of the stack trace when an error is thrown.     --
--- This implementation caches runner coroutines, so the ability to yield in   --
--- the signal handlers comes at minimal extra cost over a naive signal        --
--- implementation that either always or never spawns a thread.                --
---                                                                            --
--- API:                                                                       --
---   local Signal = require(THIS MODULE)                                      --
---   local sig = Signal.new()                                                 --
---   local connection = sig:Connect(function(arg1, arg2, ...) ... end)        --
---   sig:Fire(arg1, arg2, ...)                                                --
---   connection:Disconnect()                                                  --
---   sig:DisconnectAll()                                                      --
---   local arg1, arg2, ... = sig:Wait()                                       --
---                                                                            --
--- Licence:                                                                   --
---   Licenced under the MIT licence.                                          --
---                                                                            --
--- Authors:                                                                   --
---   stravant - July 31st, 2021 - Created the file.                           --
---------------------------------------------------------------------------------
+--[=[
+	Batched Yield-Safe Signal Implementation
+
+	Lua-side duplication of the [API of events on Roblox objects](https://create.roblox.com/docs/reference/engine/datatypes/RBXScriptSignal).
+
+	Signals are needed for to ensure that for local events objects are passed by
+	reference rather than by value where possible, as the BindableEvent objects
+	always pass signal arguments by value, meaning tables will be deep copied.
+	Roblox's deep copy method parses to a non-lua table compatable format.
+
+	This class is designed to work both in deferred mode and in regular mode.
+	It follows whatever mode is set.
+
+	```lua
+	local signal = Signal.new()
+
+	local arg = {}
+
+	signal:Connect(function(value)
+		assert(arg == value, "Tables are preserved when firing a Signal")
+	end)
+
+	signal:Fire(arg)
+	```
+
+	:::info
+	Why this over a direct [BindableEvent]? Well, in this case, the signal
+	prevents Roblox from trying to serialize and desialize each table reference
+	fired through the BindableEvent.
+	:::
+
+	This is a Signal class which has effectively identical behavior to a
+	normal RBXScriptSignal, with the only difference being a couple extra
+	stack frames at the bottom of the stack trace when an error is thrown
+	This implementation caches runner coroutines, so the ability to yield in
+	the signal handlers comes at minimal extra cost over a naive signal
+	implementation that either always or never spawns a thread.
+
+	Author notes:
+	stravant - July 31st, 2021 - Created the file.
+	Quenty - Auguest 21st, 2023 - Modified to fit Nevermore contract, with Moonwave docs
+
+	@class Signal
+]=]
 
 -- The currently idle thread to run the next handler on
 local freeRunnerThread = nil
@@ -100,14 +120,36 @@ setmetatable(Connection, {
 
 -- Signal class
 local Signal = {}
+Signal.ClassName = "Signal"
 Signal.__index = Signal
 
+--[=[
+	Constructs a new signal.
+	@return Signal<T>
+]=]
 function Signal.new()
 	return setmetatable({
 		_handlerListHead = false,
 	}, Signal)
 end
 
+--[=[
+	Returns whether a class is a signal
+
+	@param value any
+	@return boolean
+]=]
+function Signal.isSignal(value)
+	return type(value) == "table"
+		and getmetatable(value) == Signal
+end
+
+--[=[
+	Connect a new handler to the event. Returns a connection object that can be disconnected.
+
+	@param fn (... T) -> () -- Function handler called when `:Fire(...)` is called
+	@return RBXScriptConnection
+]=]
 function Signal:Connect(fn)
 	local connection = Connection.new(self, fn)
 	if self._handlerListHead then
@@ -119,16 +161,30 @@ function Signal:Connect(fn)
 	return connection
 end
 
--- Disconnect all handlers. Since we use a linked list it suffices to clear the
--- reference to the head handler.
+--[=[
+	Disconnects all connected events to the signal.
+
+	:::info
+	Disconnect all handlers. Since we use a linked list it suffices to clear the
+	reference to the head handler.
+	:::
+]=]
 function Signal:DisconnectAll()
 	self._handlerListHead = false
 end
 
--- Signal:Fire(...) implemented by running the handler functions on the
--- coRunnerThread, and any time the resulting thread yielded without returning
--- to us, that means that it yielded to the Roblox scheduler and has been taken
--- over by Roblox scheduling, meaning we have to make a new coroutine runner.
+--[=[
+	Fire the event with the given arguments. All handlers will be invoked. Handlers follow
+
+	::: info
+	Signal:Fire(...) is implemented by running the handler functions on the
+	coRunnerThread, and any time the resulting thread yielded without returning
+	to us, that means that it yielded to the Roblox scheduler and has been taken
+	over by Roblox scheduling, meaning we have to make a new coroutine runner.
+	:::
+
+	@param ... T -- Variable arguments to pass to handler
+]=]
 function Signal:Fire(...)
 	local item = self._handlerListHead
 	while item do
@@ -144,8 +200,17 @@ function Signal:Fire(...)
 	end
 end
 
--- Implement Signal:Wait() in terms of a temporary connection using
--- a Signal:Connect() which disconnects itself.
+--[=[
+	Wait for fire to be called, and return the arguments it was given.
+
+	::: info
+	Signal:Wait() is implemented in terms of a temporary connection using
+	a Signal:Connect() which disconnects itself.
+	:::
+
+	@yields
+	@return T
+]=]
 function Signal:Wait()
 	local waitingCoroutine = coroutine.running()
 	local cn;
@@ -156,8 +221,17 @@ function Signal:Wait()
 	return coroutine.yield()
 end
 
--- Implement Signal:Once() in terms of a connection which disconnects
--- itself before running the handler.
+--[=[
+	Connect a new, one-time handler to the event. Returns a connection object that can be disconnected.
+
+	::: info
+	-- Implement Signal:Once() in terms of a connection which disconnects
+	-- itself before running the handler.
+	:::
+
+	@param fn (... T) -> () -- One-time function handler called when `:Fire(...)` is called
+	@return RBXScriptConnection
+]=]
 function Signal:Once(fn)
 	local cn;
 	cn = self:Connect(function(...)
@@ -169,6 +243,12 @@ function Signal:Once(fn)
 	return cn
 end
 
+--[=[
+	Alias for [DisconnectAll]
+
+	@function Destroy
+	@within Signal
+]=]
 Signal.Destroy = Signal.DisconnectAll
 
 -- Make signal strict

package/src/Shared/Signal.lua

@@ -30,6 +30,14 @@
 	@class Signal
 ]=]
 
+local USE_GOOD_SIGNAL_ONLY = true
+
+if USE_GOOD_SIGNAL_ONLY then
+	local require = require(script.Parent.loader).load(script)
+
+	return require("GoodSignal")
+end
+
 local HttpService = game:GetService("HttpService")
 
 local ENABLE_TRACEBACK = false

package/src/node_modules.project.json

@@ -0,0 +1,7 @@
+{
+  "name": "node_modules",
+  "globIgnorePaths": [ "**/.package-lock.json" ],
+  "tree": {
+    "$path": { "optional": "../node_modules" }
+  }
+}