Get Cargo/Passenger (SimEntity) at Terminal waiting for a specific line

---@return table : details of the entity at terminal
function api_helper.getEntityAtTerminal(entity_id)
    local success, res = pcall(function()
        return api.engine.getComponent(entity_id, api.type.ComponentType.SIM_ENTITY_AT_TERMINAL)
    end)
    if success then
        return res
    else
        return nil
    end
end

---this functions samples the waiting cargo for each line and adds the information to the sampled line data
local function sampleWaitingCargo()
    log.debug("sampling: sampleWaitingCargo() starting")
    local finished = true
    local stopProcessing = false
    local processed_lines = 0
    local processed_items = 0

    for line_id, line_data in pairs(sampledLineData) do
        -- Check for marker
        if line_data.SAMPLE_WAITING_CARGO then
            local lineWaiting = 0
            local lineWaitingPeak = 0
            local stopsWithWaiting = 0
            local waitingEntitiesPerStop = {}
            local lineEntities = {}

            -- Start by setting the lineEntities as per already cached data
            if line_data.type == "PASSENGER" and lineSimPersonCache[line_id] then
                lineEntities = lineSimPersonCache[line_id]
            elseif line_data.type == "CARGO" and lineSimCargoCache[line_id] then
                lineEntities = lineSimCargoCache[line_id]
            end

            if #lineEntities > 0 then
                for _, value in pairs(lineEntities) do
                    local currentEntityId = value

                    -- Get the SIM_ENTITY_AT_TERMINAL unless already cached
                    if not simEntityAtTerminalCache[currentEntityId] then
                        local entity_at_terminal = api_helper.getEntityAtTerminal(currentEntityId)
                        if entity_at_terminal ~= nil then
                            simEntityAtTerminalCache[currentEntityId] = entity_at_terminal
                        else
                            simEntityAtTerminalCache[currentEntityId] = NO_ENTITY -- Set a value in case the entity is not at terminal (nil returned)
                        end

                        -- Check if we've processed too many items, then stop and restart next tick
                        processed_items = processed_items + 1
                        if processed_items >= MAX_ENTITIES_TO_PROCESS_PER_RUN then
                            finished = false
                            stopProcessing = true
                            log.debug("sampling: sampleWaitingCargo() processing limit reached, stopping")
                            break
                        end
                    end

                    -- Process the entity for the line, if it exists in the cache
                    if simEntityAtTerminalCache[currentEntityId] and simEntityAtTerminalCache[currentEntityId] ~= NO_ENTITY then
                        local currentEntity = simEntityAtTerminalCache[currentEntityId]

                        -- First check if the entity is waiting for this line, process it if so
                        if currentEntity.line == line_id then
                            -- If previous entry in the table created, then increase it, otherwise create and initialize it
                            if waitingEntitiesPerStop[currentEntity.lineStop0] then
                                waitingEntitiesPerStop[currentEntity.lineStop0] = waitingEntitiesPerStop[currentEntity.lineStop0] + 1
                            else
                                waitingEntitiesPerStop[currentEntity.lineStop0] = 1
                            end
                        end
                    end
                end

                -- If stop processing has been triggered, break this loop here
                if stopProcessing then
                    break
                end

                for _, value in pairs(waitingEntitiesPerStop) do
                    -- Count number of stops with anything waiting
                    if value > 0 then
                        stopsWithWaiting = stopsWithWaiting + 1
                    end

                    lineWaiting = lineWaiting + value
                    if value > lineWaitingPeak then
                        lineWaitingPeak = value
                    end
                end
            end

            -- Add sampled data to sampledLineData
            sampledLineData[line_id].waiting = lineWaiting
            sampledLineData[line_id].waiting_peak = lineWaitingPeak
            sampledLineData[line_id].stops_with_waiting = stopsWithWaiting

            -- Update markers
            sampledLineData[line_id].SAMPLE_WAITING_CARGO = nil
            sampledLineData[line_id].MERGE = true

            -- Update counters
            processed_lines = processed_lines + 1

            if processed_lines >= MAX_LINES_TO_PROCESS_PER_RUN then
                finished = false -- This state can't be completed (for sure) if we reached this, run it one more time
                log.debug("sampling: mergeLineData() processing limit reached, stopping")
                break
            end
        end
    end

    log.debug("sampling: sampleWaitingCargo() processed " .. processed_lines .. " lines and " .. processed_items .. " new items")
    return finished
end