TableUtils.ttslua

-- This module operates on tables that contain only positive consecutive integer keys starting at 1 (i.e. a plain array), as well as tables which contain no
-- array component. Behavior is undefined for tables that contain a key for [1] as well as non-consecutive integer or non-integer keys.

---@class ge_tts__TableUtils
local TableUtils = {}

--- Returns true if `tab` contains an entry at index 1. That being the case, this module will assume `tab` only contains sequential positive integer keys.
---@overload fun<V>(tab: V[]): true
---@overload fun<V>(tab: table<boolean, V>): false
---@overload fun<V>(tab: table<string, V>): false
---@overload fun<V>(tab: table<table, V>): false
---@overload fun<V>(tab: table<userdata, V>): false
---@param tab table
---@return boolean
function TableUtils.isArray(tab)
    return tab[1] ~= nil or type(tab[0]) == 'number'
end

---@overload fun<V, MappedV>(tab: V[], func: fun(value: V, key: number): MappedV): MappedV[]
---@generic K, V, MappedV
---@param tab table<K, V>
---@param func fun(value: V, key: K): MappedV
---@return table<K, MappedV>
function TableUtils.map(tab, func)
    ---@type table<K, MappedV>
    local mapped = {}

    if TableUtils.isArray(tab) then
        for i, v in ipairs(--[[---@type V[] ]] tab) do
            mapped[--[[---@type K]] i] = func(v, --[[---@type K]] i)
        end
    else
        for k, v in pairs(tab) do
            mapped[k] = func(v, k)
        end
    end

    return mapped
end

---@generic K, V
---@param tab table<K, V>
---@return table<V, K>
function TableUtils.invert(tab)
    ---@type table<V, K>
    local inverted = {}

    for k, v in pairs(tab) do
        inverted[v] = k
    end

    return inverted
end

---@generic K, V, RemappedK
---@param tab table<K, V>
---@param func fun(value: V, key: K): RemappedK
---@return table<RemappedK, V>
function TableUtils.remap(tab, func)
    local remapped = {}

    for k, v in pairs(tab) do
        remapped[func(v, k)] = v
    end

    return remapped
end

---@overload fun<V>(arr: V[], func: fun(value: V, index: number): boolean): V[]
---@generic K, V
---@param tab table<K, V>
---@param func fun(value: V, key: K): any
---@return table<K, V>
function TableUtils.select(tab, func)
    ---@type table<K, V>
    local selected = {}

    if TableUtils.isArray(tab) then
        local arr = tab
        for i, v in ipairs(--[[---@type V[] ]] arr) do
            if func(v, --[[---@type K]] i) then
                table.insert(--[[---@type V[] ]] selected, v)
            end
        end
    else
        for k, v in pairs(tab) do
            if func(v, k) then
                selected[k] = v
            end
        end
    end

    return selected
end

---@overload fun<V>(arr: V[], func: fun(value: V, index: number): boolean): V[]
---@generic K, V
---@param tab table<K, V>
---@param func fun(value: V, key: K): boolean
---@return table<K, V>
function TableUtils.reject(tab, func)
    return TableUtils.select(tab, function(v, k) return not func(v, k) end)
end

---@overload fun<R, K, V: R>(tab: table<K, V>, func: fun(memo: R, value: V, key: K): R): R
---@generic K, V, R
---@param tab table<K, V>
---@param initial R
---@param func fun(memo: R, value: V, key: K): R
---@return R
function TableUtils.reduce(tab, initial, func)
    local memo = func and initial or next(tab)
    local reducer = func or initial

    ---@type K
    local initialK

    if not func then
        initialK = --[[---@type K]] memo
    end

    for k, v in next, tab, initialK do
        memo = reducer(memo, v, k)
    end

    return memo
end

---@generic K, V
---@param tab table<K, V>
---@param value any
---@return nil | K
function TableUtils.find(tab, value)
    if TableUtils.isArray(tab) then
        for i, v in ipairs(--[[---@type any[] ]] tab) do
            if v == value then
                return --[[---@type K]] i
            end
        end
    else
        for k, v in pairs(tab) do
            if v == value then
                return k
            end
        end
    end

    return nil
end

---@generic K, V
---@param tab table<K, V>
---@param func fun(value: V, key: K): boolean
---@return nil | V, nil | K
function TableUtils.detect(tab, func)
    if TableUtils.isArray(tab) then
        for i, v in ipairs(--[[---@type V[] ]] tab) do
            if func(v, --[[---@type K]] i) then
                return v, --[[---@type K]] i
            end
        end
    else
        for k, v in pairs(tab) do
            if func(v, k) then
                return v, k
            end
        end
    end

    return nil, nil
end

---@overload fun<T>(tab: T): T
---@generic T
---@param tab T
---@param recursive boolean
---@return T
function TableUtils.copy(tab, recursive)
    ---@type table
    local copied = {}

    for k, v in pairs(--[[---@type table]] tab) do
        copied[k] = (recursive and type(v) == 'table' and
            TableUtils.copy(--[[---@type table]] v, true)
        ) or v
    end

    return --[[---@type T]] copied
end

---@generic K, V
---@param tab table
---@vararg table
function TableUtils.inject(tab, ...)
    local otherTables = { ... }

    for _, t in ipairs(otherTables) do
        if TableUtils.isArray(tab) then
            for _, v in ipairs(--[[---@type any[] ]] t) do
                table.insert(--[[---@type any[] ]] tab, v)
            end
        else
            for k, v in pairs(t) do
                tab[k] = v
            end
        end
    end
end

---@overload fun<T>(...: T): T
---@vararg table
---@return table
function TableUtils.merge(...)
    local merged = {}
    TableUtils.inject(merged, ...)
    return merged
end

---@generic V
---@param tab V[][]
---@return V[]
function TableUtils.flatten(tab)
    ---@type V[]
    local flattened = {}

    for _, subTable in ipairs(tab) do
        for _, v in ipairs(subTable) do
            table.insert(flattened, v)
        end
    end

    return flattened
end

---@generic K, V
---@param tab table<K, V>
---@return K[]
function TableUtils.keys(tab)
    ---@type K[]
    local keys = {}

    for k, _ in pairs(tab) do
        table.insert(keys, k)
    end

    return keys
end

---@generic K, V
---@param tab table<K, V>
---@return V[]
function TableUtils.values(tab)
    ---@type V[]
    local values = {}

    for _, v in pairs(tab) do
        table.insert(values, v)
    end

    return values
end

---@param tab table
---@return number
function TableUtils.count(tab)
    local count = 0

    for _, _ in pairs(tab) do
        count = count + 1
    end

    return count
end

---@generic V
---@param arr V[]
---@return V[]
function TableUtils.reverse(arr)
    local reversed = {}

    if TableUtils.isArray(arr) then
        for i = #arr, 1, -1 do
            table.insert(reversed, arr[i])
        end
    end

    return reversed
end

---@overload fun<T>(arr: V[], start: number): V[]
---@generic V
---@param arr V[]
---@param start number
---@param finish number
---@return V[]
function TableUtils.range(arr, start, finish)
    local range = {}

    if TableUtils.isArray(arr) then
        finish = finish and math.min(finish, #arr) or #arr

        for i = start, finish do
            table.insert(range, arr[i])
        end
    end

    return range
end

---@generic V
---@param arr V[]
---@return V[]
function TableUtils.unique(arr)
    local unique = {}

    for _, value in ipairs(arr) do
        if not TableUtils.find(unique, value) then
            table.insert(unique, value)
        end
    end

    return unique
end

local TYPE_STRINGIFIERS = {
    ['nil'] = function(_) return 'nil' end,
    boolean = function(v) return tostring(v) end,
    number = function(v) return tostring(v) end,
    string = function(v) return "'" .. v .. "'" end,
    userdata = function(_) return 'userdata' end,
    ['function'] = function(_) return 'function' end,
    thread = function(_) return 'thread' end,
    table = function(v) return tostring(v) end,
}

---@overload fun(tab: table): string
---@overload fun(tab: table, recursive: boolean): string
---@param tab table
---@param recursive boolean
---@param depth number
---@return string
function TableUtils.dump(tab, recursive, depth)
    depth = depth or 1

    local indentation = string.rep('  ', depth)
    local str = '{'

    ---@type table<any, boolean>
    local ordered_keys = {}

    for i, v in ipairs(--[[---@type any[] ]] tab) do
        ordered_keys[i] = true
        str = str .. '\n' .. indentation .. '[' .. i .. '] = '

        if recursive and type(v) == 'table' then
            str = str .. TableUtils.dump(v, true, depth + 1) .. ','
        else
            local a = TYPE_STRINGIFIERS['nil']
            str = str .. TYPE_STRINGIFIERS[type(v)](v) .. ','
        end
    end

    for k, v in pairs(tab) do
        if not ordered_keys[k] then
            str = str .. '\n' .. indentation .. '[' .. TYPE_STRINGIFIERS[type(k)](k) .. '] = '

            if recursive and type(v) == 'table' then
                str = str .. TableUtils.dump(v, true, depth + 1) .. ','
            else
                str = str .. TYPE_STRINGIFIERS[type(v)](v) .. ','
            end
        end
    end

    str = str .. '\n' .. string.rep('  ', depth - 1) .. '}'

    return str
end

return TableUtils