Roblox.lua: Pseudo-Event API

--[[
    THE GOAL: Recreate the Roblox Event API that is used on their API instances (such as Part.Touched) in order to be applied in custom pseudo-API's (normally through a moduleScript);
    This API attempts to accurately use the same syntax and properties of the original API.
--]]

local Event = { -- recreate the RBXScriptSignal instance to be applied on custom gui objects
    new = function()
        local signalAPI = {
            FunctionConnectionQueue = {}, -- internal usage by the module to manage connected functions
            WaitLink = {WaitCount = 0, CanFlush = false, Args = nil}, -- internal usage by the module to manage yielding threads

            Connect = function(event, f) -- adds a function to the queue that is fired when the event happens
                local ScriptConnection = {Connected = true, Listener = f, Disconnect = function(connection)  -- recreates the RBXScriptConnection instance
                    connection.Connected = false
                end}
                table.insert(event.FunctionConnectionQueue, ScriptConnection)
                return ScriptConnection
            end,

            Wait = function(event) -- yields the script until the event is fired
                event.WaitLink.WaitCount = event.WaitLink.WaitCount + 1
                repeat
                    wait()
                until event.WaitLink.CanFlush

                event.WaitLink.WaitCount = event.WaitLink.WaitCount - 1
                return unpack(event.WaitLink.Args)
            end,

            Fire = function(event, ...)  -- internal usage by the module that makes the magic happen
                local packedArgs = {...}
                for i = #(event.FunctionConnectionQueue), 1 do
                    -- flush all :Wait() calls
                    event.WaitLink.Args = packedArgs
                    event.WaitLink.CanFlush = true
                    coroutine.resume(coroutine.create(function()
                        repeat
                            wait()
                        until event.WaitLink.WaitCount == 0  -- revoke the flush permission when all :Wait() calls have been returned

                        event.WaitLink.CanFlush = false
                    end))

                    -- RBXScriptSignal fires functions in reverse order they were connected, so do I
                    local connection = event.FunctionConnectionQueue[i]
                    if connection.Connected then
                        coroutine.resume(coroutine.create(function()
                            connection.Listener(unpack(packedArgs))
                        end))
                    end
                end
            end
        }
        return signalAPI
    end
}


--[[
    USAGE:
    Any dictionary can be deemed as a pseudo-API;
    To attach a word to an event, just set that value as Event.new();
    You can fire events using :Fire(), and connect events through :Connect() and/or :Wait() - last one is untested!
    :Connect() will return a Connection that you can disconnect through :Disconnect()
]]--

-- Sample code:

local pseudoApi = {
    Noobify = function(api, noob)
        -- inserts code here
        api.Noobified:Fire(noob)
    end,
    Noobified = Event.new()
}

local x
x = pseudoApi.Noobified:Connect(function(nub)
    print("OOF!!", nub)
    x:Disconnect()
end)

pseudoApi:Noobify("davness")
pseudoApi:Noobify("theonewhoisreadingthis")


--[[
OUTPUT:
OOF!! davness
]]--