Event Class, Brief explanation

--[[
    Simple Events, brief explanation on logic behind them

    About events :
    Event-driven programming is a method in programming to handle systems based on exection of given events,
    it allows us to avoid constantly checking if "x" changed but we rather tell it when it has, therefore greatly optimizing it.

    NOTES :
    Each callback invoked creates a new thread to allow yielding.

    Using coroutine.wrap function to make a method which yields the thread until the event has been fired is discouraged and not
    efficient to do. Unless the engine, library, whatever you're using allows you to do so more efficiently then feel free to.

    Making a WeakFire or WeakConnection methods which don't create a thread when triggered is an option though not advised.
    You can easily mess up and keep in mind it's cons as well as consider if it's even worth using..

--]]

local function EventDisconnect(Connection)
    --[[
    Using Callback index we fetch the connections call back and remove it from the list so it is't affected by fire method anymore.

    Important to use table.remove and not manually set value to nil in order to keep the array without any nil spots to avoid iteration problems.

    --]]

    local Event = Connection.Event
    Event.NumberOfCallbacks = Event.NumberOfCallbacks - 1

    table.remove(Event.Callbacks, Connection.CallbackIndex)
end

local function EventConnect(Event, Callback)
    --[[
    Increase "NumberOfCallbacks" variable to keep track on how many call backs are in the list which we later use to directly
    index the call back in list in order to disconnect.

    Callback function is cached in a list so when we fire the event we can simply loop through all of them and invoke each function connected.

    A table is returned in order to give an option to disconnect the connection and avoid memory leaks. (Table:Method(), self reference is passed for convenient indexing)

    --]]

    local NumberOfCallbacks = Event.NumberOfCallbacks + 1
    Event.NumberOfCallbacks = NumberOfCallbacks

    Event.Callbacks[NumberOfCallbacks] = Callback

    return {
        Event = Event,
        CallbackIndex = NumberOfCallbacks,

        Disconnect = EventDisconnect,
    }
end

local function EventFire(Event, ...)
    --[[
    Iterate through the list of call backs and invoke them.

    Each call back is executed in a seperate thread in case they have a yield in them which would error and unwanted yields between each call

    example :

    Event:Connect(function(...)
        print(...)
        wait(3)
    end

    for i = 1, 10 do
        Event:Fire("Hello")
    end;

    Each time the event is fired the callback will print the message "Hello" wait 3 seconds then continue to invoke the next one


    --]]

    local Callbacks = Event.Callbacks

    for Index = 1, Event.NumberOfCallbacks do
        coroutine.wrap(Callbacks[Index])(...)
    end
end

local EventClass = {}

function EventClass.new()
    return {
        --// Properties
        Callbacks = {},
        NumberOfCallbacks = 0,

        --// Methods
        Connect = EventConnect,
        Fire = EventFire,
    }
end