From 39a3a338e7c2df870fe833a7fcb3d84ceab12806 Mon Sep 17 00:00:00 2001
From: protocol_1903 <67478786+protocol-1903@users.noreply.github.com>
Date: Mon, 25 May 2026 16:04:23 -0700
Subject: [PATCH] more annotations

---
 lib/autorecipes.lua |   3 ++
 lib/color.lua       |   2 +
 lib/table.lua       | 128 ++++++++++++++++++++++++++++----------------
 3 files changed, 87 insertions(+), 46 deletions(-)

diff --git a/lib/autorecipes.lua b/lib/autorecipes.lua
index 642ce5e..50950fb 100644
--- a/lib/autorecipes.lua
+++ b/lib/autorecipes.lua
@@ -57,6 +57,9 @@ numbers: sets amount to this value no matter what it was before
 ]] --
 --if you use the icon part its set to want a size 64 icon right now. if you want to use the size 32 ones ill need to add icon size in because i cant detect the icons size in the code
 
+---@generic V
+---@param tbl V[]
+---@return V[]
 local function ensure_contiguous(tbl)
     if not tbl or type(tbl) ~= "table" then return tbl end
     local contiguous_table = {}
diff --git a/lib/color.lua b/lib/color.lua
index b02345b..6302859 100644
--- a/lib/color.lua
+++ b/lib/color.lua
@@ -1,3 +1,4 @@
+---@type Color[]
 py.tints = {
     [0] = {r = 0.5,   g = 0.5,   b = 0.5,   a = 1.0},
     {r = 1.0,   g = 1.0,   b = 0.0,   a = 1.0},
@@ -6,6 +7,7 @@ py.tints = {
     {r = 1.0,   g = 0.0,   b = 1.0,   a = 1.0}
 }
 
+---@type Color[]
 py.light_tints = {}
 for i, tint in pairs(py.tints) do
     py.light_tints[i] = {}
diff --git a/lib/table.lua b/lib/table.lua
index 0388f81..20b9c29 100644
--- a/lib/table.lua
+++ b/lib/table.lua
@@ -1,10 +1,12 @@
 -- Adds new functions to the builtin table class.
 
 ---Returns a new table with the results of calling a provided function on every element in the table.
----@param tbl table
----@param f fun(v: any, k: any, ...: any): any
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@param f fun(v: V, k: K, ...: any): any
 ---@param ... any
----@return table
+---@return table<K,V>
 table.map = function(tbl, f, ...)
     local result = {}
     for k, v in pairs(tbl) do result[k] = f(v, k, ...) end
@@ -12,8 +14,10 @@ table.map = function(tbl, f, ...)
 end
 
 -- Sums every key up in a table
----@param tbl table
----@param f (fun(v: any, k: number, ...: any): number|nil)
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@param f (fun(v: V, k: K, ...: any): number|nil)
 ---@param ... any
 ---@return number
 table.sum = function(tbl, f, ...)
@@ -26,10 +30,12 @@ table.sum = function(tbl, f, ...)
 end
 
 ---Returns a new table with all elements that pass the test implemented by the provided function.
----@param tbl table
----@param f fun(v: any, k: any, ...: any): boolean
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@param f fun(v: V, k: K, ...: any): boolean
 ---@param ... any
----@return table
+---@return table<K,V>
 table.filter = function(tbl, f, ...)
     local result = {}
     local is_array = #tbl > 0
@@ -42,36 +48,41 @@ table.filter = function(tbl, f, ...)
 end
 
 ---Returns the first element that satisfies the predicate.
----@param tbl table
----@param f fun(v: any, k: any, ...: any): any
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@param f V|fun(v: V, k: K, ...: any): any
 ---@param ... any
----@return any, any
----@overload fun(tbl: table, v: any): any, any
+---@return V?,K?
+---@overload fun(tbl: table<K,V>, v: V): V, K
 table.find = function(tbl, f, ...)
     if type(f) == "function" then
         for k, v in pairs(tbl) do if f(v, k, ...) then return v, k end end
     else
         for k, v in pairs(tbl) do if v == f then return v, k end end
     end
-    return nil
 end
 
 ---Returns true if any element in the table passes the test implemented by the provided function.
----@param tbl table
----@param f fun(v: any, k: any, ...: any): any
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@param f fun(v: V, k: K, ...: any): any
 ---@param ... any
 ---@return boolean
----@overload fun(tbl: table, v: any): boolean
+---@overload fun(tbl: table<K,V>, v: V): boolean
 table.any = function(tbl, f, ...)
     return table.find(tbl, f, ...) ~= nil
 end
 
 ---Returns true if all elements in the table pass the test implemented by the provided function.
----@param tbl table
----@param f any|fun(v: any, k: any, ...: any): any
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@param f any|fun(v: V, k: K, ...: any): any
 ---@param ... any
 ---@return boolean
----@overload fun(tbl: table, v: any): boolean
+---@overload fun(tbl: table<K,V>, v: V): boolean
 table.all = function(tbl, f, ...)
     if type(f) == "function" then
         for k, v in pairs(tbl) do if not f(v, k, ...) then return false end end
@@ -89,8 +100,10 @@ table.is_empty = function(tbl)
 end
 
 ---Returns an array of the table's keys.
----@param tbl table
----@return any[]
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@return K[]
 table.keys = function(tbl)
     local keys = {}
     for k, _ in pairs(tbl) do keys[#keys + 1] = k end
@@ -98,8 +111,10 @@ table.keys = function(tbl)
 end
 
 ---Returns an array of the table's values.
----@param tbl table
----@return any[]
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@return V[]
 table.values = function(tbl)
     local values = {}
     for _, v in pairs(tbl) do table.insert(values, v) end
@@ -107,16 +122,20 @@ table.values = function(tbl)
 end
 
 ---Returns the first element of the table.
----@param tbl table
----@return any
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@return V
 table.first = function(tbl)
     local _, v = next(tbl)
     return v
 end
 
 ---Returns the last element of the table.
----@param tbl table
----@return any
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@return V
 table.last = function(tbl)
     local result
     for _, v in pairs(tbl) do result = v end
@@ -124,8 +143,9 @@ table.last = function(tbl)
 end
 
 ---Returns the last element of the array.
----@param tbl any[]
----@return any
+---@generic V
+---@param tbl V[]
+---@return V?
 table.array_last = function(tbl)
     local size = #tbl
     if size == 0 then return nil end
@@ -133,8 +153,10 @@ table.array_last = function(tbl)
 end
 
 ---Returns a new table with keys and values swapped.
----@param tbl table
----@return table
+---@generic V
+---@generic K
+---@param tbl table<K,V>
+---@return table<V,K>
 table.invert = function(tbl)
     local result = {}
     for k, v in pairs(tbl) do result[v] = k end
@@ -142,8 +164,10 @@ table.invert = function(tbl)
 end
 
 ---Returns a new table by merging the provided tables. If a key exists in multiple tables, the value from the last table is used.
----@param ... table
----@return table
+---@generic V
+---@generic K
+---@param ... table<K,V>
+---@return table<K,V>
 table.merge = function(...)
     local result = {}
     for _, tbl in pairs {...} do
@@ -153,8 +177,10 @@ table.merge = function(...)
 end
 
 ---Returns a new array by merging the provided tables. The values are appended in the order they are provided.
----@param ... table
----@return any[]
+---@generic V
+---@generic K
+---@param ... table<K,V>
+---@return V[]
 table.array_combine = function(...)
     local result = {}
     for _, tbl in pairs {...} do
@@ -164,8 +190,9 @@ table.array_combine = function(...)
 end
 
 ---Reverses an array in-place and returns it.
----@param tbl any[]
----@return any[]
+---@generic V
+---@param tbl V[]
+---@return V[]
 table.reverse = function(tbl)
     for i = 1, #tbl / 2 do
         tbl[i], tbl[#tbl - i + 1] = tbl[#tbl - i + 1], tbl[i]
@@ -173,6 +200,11 @@ table.reverse = function(tbl)
     return tbl
 end
 
+---Returns all the keys of a table in a random order
+---@generic V
+---@generic K
+---@param t table<K,V>
+---@return K[]
 local function shuffle(t)
     local keys = {}
     local n = 0
@@ -189,9 +221,12 @@ local function shuffle(t)
 
     return keys
 end
+
 ---Like normal pairs(), but in deterministic randomized order
----@param t table
----@return fun():any, any
+---@generic V
+---@generic K
+---@param t table<K,V>
+---@return fun():K, V
 function py.shuffled_pairs(t)
     local shuffled_keys = shuffle(t)
     local i = 0
@@ -205,8 +240,9 @@ function py.shuffled_pairs(t)
 end
 
 ---Returns a new array with duplicates removed.
----@param tbl any[]
----@return any[]
+---@generic V
+---@param tbl V[]
+---@return V[]
 table.dedupe = function(tbl)
     local seen = {}
     local result = {}
@@ -219,15 +255,15 @@ table.dedupe = function(tbl)
     return result
 end
 
--- Extends an array out
--- @param tbl any[]
--- @param tbl2 any[]
+---Extends an array out
+---@generic V
+---@param tbl V[]
+---@param tbl2 V[]
+---@return V[]
 table.extend = function(tbl, tbl2)
     tbl = table.deepcopy(tbl)
-    
     for _, v in pairs(tbl2) do
         table.insert(tbl, v)
     end
-
     return tbl
 end