fs_util.lua

local flib_gui = require "__flib__/gui"
local flib_table = require "__flib__/table"

local M = {}

---Factorio runs the simulation at a fixed 60 ticks per second, so a per-tick
---rate becomes per-second by multiplying by this. Single source of truth for
---the conversion the accessor / solver layers lean on; re-exported as
---`accessor.second_per_tick` for the consumers that still read it there.
M.second_per_tick = 60

---Relative residual cutoff used to decide a material's net per-second flow is
---effectively zero against its gross throughput (see accessor.is_negligible /
---number_format.is_negligible). Lives here as a shared numeric epsilon next to
---is_nan / is_infinite; re-exported as `accessor.tolerance`.
M.tolerance = 10 ^ -7

---@type table<TimeScale, number>
M.scale_per_second = {
    second = 1,
    five_seconds = 5,
    minute = 60,
    ten_minutes = 10 * 60,
    hour = 60 * 60,
    ten_hours = 10 * 60 * 60,
    fifty_hours = 50 * 60 * 60,
    two_hundred_fifty_hours = 250 * 60 * 60,
    thousand_hours = 1000 * 60 * 60,
}

---comment
---@param value number
---@param scale TimeScale
---@return number
function M.to_scale(value, scale)
    return value * M.scale_per_second[scale]
end

---comment
---@param value number
---@param scale TimeScale
---@return number
function M.from_scale(value, scale)
    return value / M.scale_per_second[scale]
end

---Returns an index of first element that matches the condition.
---@generic K, V
---@param tbl table<K, V>
---@param fun fun(value: V, key: K): boolean
---@return K?
function M.find(tbl, fun)
    for key, value in pairs(tbl) do
        if fun(value, key) then
            return key
        end
    end
    return nil
end

---Returns a new table with each value transformed by `mapper`, same keys.
---Non-mutating (flib_table.map mutates its input in 0.17+ and returns a new
---table in 0.16.x; every caller here wants the latter, so this is a
---flib-version-independent replacement rather than a call to either).
---@generic K, V, N
---@param tbl table<K, V>
---@param mapper fun(value: V, key: K): N
---@return table<K, N>
function M.map(tbl, mapper)
    local output = {}
    for key, value in pairs(tbl) do
        output[key] = mapper(value, key)
    end
    return output
end

---Returns a compact array of the values for which `predicate(value, key)` is
---truthy (flib_table.filter's array_insert=true mode, which flib 0.17 dropped
---with no replacement). Callers can feed the result straight to code that
---expects an array; no separate to_list step needed.
---@generic K, V
---@param tbl table<K, V>
---@param predicate fun(value: V, key: K): boolean
---@return V[]
function M.filter(tbl, predicate)
    local output = {}
    for key, value in pairs(tbl) do
        if predicate(value, key) then
            output[#output + 1] = value
        end
    end
    return output
end

---Flattens a list of arrays into a single array (flib_table.array_merge in
---0.16.x, moved to flib_array.flatten in 0.17+ -- neither module is safe to
---depend on for this across both flib versions, so this is a plain-Lua copy
---of the same ~8-line algorithm both had).
---@generic V
---@param arrays V[][]
---@return V[]
function M.array_merge(arrays)
    local output = {}
    local i = 0
    for j = 1, #arrays do
        local arr = arrays[j]
        for k = 1, #arr do
            i = i + 1
            output[i] = arr[k]
        end
    end
    return output
end

---Returns a table containing arrays with elements grouped
---according to values returned by the callback function.
---@generic K, V, R
---@param tbl table<K, V>
---@param fun fun(value: V, key: K): R
---@return table<R, V[]>
function M.group_by(tbl, fun)
    local grouping = {}
    for key, value in pairs(tbl) do
        local group_key = fun(value, key)
        if not grouping[group_key] then
            grouping[group_key] = {}
        end
        table.insert(grouping[group_key], value)
    end
    return grouping
end

---Converts the table to list.
---@generic V
---@param tbl table<any, V>
---@return V[]
function M.to_list(tbl)
    local list = {}
    for _, value in pairs(tbl) do
        table.insert(list, value)
    end
    return list
end

---Sorts prototypes by standard method of factorio.
---@generic V
---@param list (V | { order: string, name: string })[]
---@return V[]
function M.sort_prototypes(list)
    table.sort(list, function(a, b)
        if a.order ~= b.order then
            return a.order < b.order
        else
            return a.name < b.name
        end
    end)
    return list
end

---comment
---@param value number
---@return boolean
function M.is_nan(value)
    return value ~= value
end

---comment
---@param value number
---@return boolean
function M.is_infinite(value)
    return value == math.huge or value == -math.huge
end

---Add a new child or children to the given GUI element.
---@param parent LuaGuiElement
---@param def fs.GuiElemDef
---@param append_tags table?
---@return table<string, LuaGuiElement> elems
---@return LuaGuiElement first
function M.add_gui(parent, def, append_tags)
    local res_elems, first = flib_gui.add(parent, def --[[@as flib.GuiElemDef]])
    first.tags = flib_table.shallow_merge{
        first.tags,
        append_tags,
    }
    M.dispatch_to_subtree(first, "on_added")
    return res_elems, first
end

M.add_handlers = flib_gui.add_handlers

---Collect necessary data and create an event.
---@param element LuaGuiElement
---@param event_name string?
---@param data table?
---@return EventDataTrait
function M.create_gui_event(element, event_name, data)
    local event = {
        element = element,
        mod_name = element.get_mod(),
        name = event_name or "",
        player_index = element.player_index,
        tick = game.tick,
    }
    event = flib_table.deep_merge { event, data }
    return event
end

---Dispatch an event to the element.
---@param element LuaGuiElement
---@param event_name string
---@param data table?
function M.dispatch(element, event_name, data)
    local event = M.create_gui_event(element, event_name, data)
    ---@diagnostic disable-next-line: param-type-mismatch
    flib_gui.dispatch(event)
end

---Dispatches an event to all lower elements on the root element.
---@param root_element LuaGuiElement
---@param event_name string
---@param append_data table?
function M.dispatch_to_subtree(root_element, event_name, append_data)
    local elements = {}
    for e in M.dfs_lower(root_element) do
        table.insert(elements, e)
    end

    for _, e in ipairs(elements) do
        if e.valid then
            local event = M.create_gui_event(e, event_name, append_data)
            ---@diagnostic disable-next-line: param-type-mismatch
            flib_gui.dispatch(event)
        end
    end
end

---Returns an element with matching name from upper elements.
---@param start_element LuaGuiElement
---@param name string
---@return LuaGuiElement?
function M.find_upper(start_element, name)
    for element in M.follow_upper(start_element) do
        if element.name == name then
            return element
        end
    end
    return nil
end

---Returns the first descendant (or `start_element` itself) with matching name,
---searched in depth-first order. `LuaGuiElement[name]` indexing only looks at
---direct children, so reach grandchildren and deeper through this helper.
---@param start_element LuaGuiElement
---@param name string
---@return LuaGuiElement?
function M.find_lower(start_element, name)
    for element in M.dfs_lower(start_element) do
        if element.name == name then
            return element
        end
    end
    return nil
end

---Iterate over all lower elements of the starting element in depth-first search.
---Note that if elements are added or deleted in progress of iteration, they will not be iterated correctly.
---@param start_element LuaGuiElement
---@return fun(): LuaGuiElement?
function M.dfs_lower(start_element)
    local element_stack = { start_element }
    local index_stack = { 0 }
    -- Cache each node's children array. LuaGuiElement.children allocates a fresh
    -- array on every read, so re-reading it once per traversal step (as a naive
    -- version does) makes visiting a node with C children O(C^2) -- a multi-second
    -- stall for a wide table (e.g. a recipe picker with thousands of slots). Fetch
    -- it once when the node is pushed and reuse it; traversal is then O(node count).
    local children_stack = { start_element.children }

    local function it()
        local tail = #element_stack
        if tail == 0 then
            return nil
        end

        local current = element_stack[tail]
        local children = children_stack[tail]

        local index = index_stack[tail]
        index_stack[tail] = index + 1

        if index == 0 then
            return current
        elseif index <= #children then
            local child = children[index]
            table.insert(element_stack, child)
            table.insert(index_stack, 0)
            table.insert(children_stack, child.children)
            return it()
        else
            table.remove(element_stack)
            table.remove(index_stack)
            table.remove(children_stack)
            return it()
        end
    end

    return it
end

---Iterates elements from the start element to the root element.
---@param start_element LuaGuiElement
---@return fun(): LuaGuiElement?
function M.follow_upper(start_element)
    local current = start_element

    function it()
        local ret = current
        if current then
            current = current.parent
        end
        return ret
    end

    return it
end

return M