Reference

Util Modules

Independent, requirable standalone from Packages/Util/, or via Thread.Signal/Thread.Trove/etc. after requiring Thread. None of them touch networking — general-purpose Lua/Roblox utilities, hand-written and inspired by (not copied from) RbxUtil, the collection Knit itself is built on.

Signal

A fast, pure-Luau event class, independent of BindableEvent. Use this for in-process pub/sub between your own modules (server-only or client-only — it never crosses the network) — faster than a Bindable, and unlike one, can carry any Lua value (functions, tables) as an argument.

local mySignal = Thread.Signal.new()
local connection = mySignal:Connect(function(msg) print(msg) end)
mySignal:Fire("hello")            -- "hello" printed
mySignal:Once(function() ... end)  -- fires at most once, then auto-disconnects
mySignal:Wait()                    -- yields the current thread until the next Fire
mySignal:GetConnections()          -- array of every active connection
connection.Connected               -- true, until :Disconnect()/:Destroy()
connection:Disconnect()            -- :Destroy() is an identical alias
mySignal:DisconnectAll()
mySignal:Destroy()                 -- disconnects everything, incl. any wrapped RBXScriptSignal
Thread.Signal.Wrap(someRBXScriptSignal)  -- adapts an engine signal to this same API
Thread.Signal.Is(mySignal)         -- true - checks if a value is one of these Signal objects

Internally this uses a pooled-coroutine linked-list design (the same well-known "GoodSignal" shape used across the Roblox ecosystem) so that firing a signal doesn't allocate a fresh coroutine per call.

Trove

A cleanup/janitor helper: track a bunch of "things that need cleaning up" and tear them all down with a single call, instead of manually writing out a dozen :Destroy()/:Disconnect() calls.

local trove = Thread.Trove.new()

trove:Add(someInstance)                               -- cleaned up via :Destroy()
trove:Connect(player.CharacterAdded, onCharacterAdded) -- trove:Add(signal:Connect(fn))
trove:Add(function() print("custom cleanup") end)      -- cleaned up by calling it
trove:Add(someTable, "Cleanup")                        -- via someTable:Cleanup() (custom method)
trove:Clone(somePart)                                  -- clones + tracks the clone
trove:Construct(SomeClass, arg1, arg2)                 -- SomeClass.new(arg1, arg2), tracked

trove:Remove(someInstance)  -- stop tracking it, without cleaning it up
trove:Clean()               -- clean up everything so far; trove stays reusable
trove:Destroy()              -- same as :Clean() — the trove is done

local sub = trove:Extend()  -- a nested Trove, auto-cleaned when the parent is
trove:AttachToInstance(someInstance) -- auto :Destroy() once someInstance leaves the game

Trove figures out the right cleanup method automatically based on the value's type (Destroy for Instances, Disconnect for connections, calling functions directly, task.cancel for threads) — pass an explicit method name as the second argument to :Add only when the default guess is wrong.

TableUtil

Table helper functions filling gaps in Lua's standard library. Except where noted, these return a new table rather than mutating the input.

TableUtil.Copy(tbl, deep?)             -- shallow by default; deep = true copies recursively
TableUtil.Sync(src, template)          -- two-way: src ends up with EXACTLY template's keys (extras removed!)
TableUtil.Reconcile(src, template)     -- one-way: adds missing keys, never removes (safe for save data)
TableUtil.Lock(tbl)                    -- deep table.freeze, mutates in place

TableUtil.SwapRemove(arrayTbl, i)             -- O(1) removal, doesn't preserve order
TableUtil.SwapRemoveFirstValue(arrayTbl, v)
TableUtil.Reverse(arrayTbl)
TableUtil.Shuffle(arrayTbl, rng?)

TableUtil.Map(tbl, function(value, key) return newValue end)
TableUtil.Filter(tbl, function(value, key) return keepIt end)
TableUtil.Reduce(tbl, function(acc, value, key) return newAcc end, initial)
TableUtil.Find(tbl, function(value, key) return matches end)  -- returns value, key or nil, nil
TableUtil.Every(tbl, fn)  -- true if fn(v,k) is true for ALL entries
TableUtil.Some(tbl, fn)   -- true if fn(v,k) is true for ANY entry
TableUtil.Keys(tbl)
TableUtil.Values(tbl)
TableUtil.IsEmpty(tbl)
TableUtil.Length(tbl)     -- counts ALL keys (unlike #tbl, works for dictionaries too)

Reconcile is the one you want for player save data: old saved tables automatically gain new fields your template added, without losing data your template doesn't know about. Sync is stricter (two-way) and is meant for things like config tables where extra/stale keys genuinely should be removed.

Filter gotcha
Map/Filter/Reduce/Find/Every/Some/Keys/Values all work over dictionaries by default. Filter specifically switches to array behavior (preserving order, compacting indices) whenever #tbl > 0 — if a table has both an array part and separate string keys, only the array part gets filtered. Keep arrays and dictionaries as separate tables if you need to filter both.

Option

A Rust-style Option<T>, for making "this might not have a value" explicit instead of silently passing nil around.

local result = Thread.Option.Wrap(dataStore:GetAsync(key)) -- Some(value) or None

result:Match({
    Some = function(v) print("Got", v) end,
    None = function() print("Nothing stored") end,
})

result:IsSome() / result:IsNone()
result:Unwrap()                 -- errors if None — use when you're SURE it's Some
result:Expect("custom error")   -- errors with your message if None
result:UnwrapOr(defaultValue)
result:UnwrapOrElse(function() return computeDefault() end)
result:Contains(value)          -- true if Some AND equal to value

result:And(otherOption)         -- otherOption if Some, else None
result:AndThen(function(v) return Thread.Option.Wrap(...) end)
result:Or(otherOption)          -- self if Some, else otherOption
result:OrElse(function() return Thread.Option.Wrap(...) end)

Thread.Option.Some(value)  -- errors if value is nil
Thread.Option.Is(obj)      -- true if obj is an Option
Thread.Option.None         -- the shared "no value" singleton itself, not a function call

Use Option where a stray nil could realistically slip through unnoticed (DataStore reads, optional config lookups). For an obvious, immediately-checked nil, plain Lua is clearer — don't wrap everything just because you can.

EnumList

Defines a custom enum with named, comparable, immutable members — Luau has no built-in way to do this yourself.

local Direction = Thread.EnumList.new("Direction", { "North", "South", "East", "West" })

print(Direction.North.Name)   --> "North"
print(Direction.North.Value)  --> 1 (position in the list, 1-indexed)

Direction:BelongsTo(Direction.North)  --> true
Direction:GetEnumItems()              --> array of all 4 items
Direction:GetName()                   --> "Direction"
Direction:FromName("South")           --> Direction.South
Direction:FromValue(1)                --> Direction.North

Use this instead of raw strings whenever you have a fixed, known set of named states (game phases, directions, item rarities) — a typo in a raw string ("Nort") fails silently; Direction.Nort fails immediately and loudly (nil-index).

Both the EnumList itself and every individual item are deep-frozen with table.freeze at creation time — you can't add members after the fact or mutate an item's fields, which is what makes == comparisons reliable.

MathUtil

Small numeric helpers Roblox's own math library doesn't already provide (math.clamp/math.round/math.sign/math.noise etc. cover the rest — this module doesn't duplicate them).

MathUtil.Lerp(0, 10, 0.5)                   --> 5
MathUtil.MapRange(0.5, 0, 1, 0, 100)        --> 50
MathUtil.FuzzyEquals(0.1 + 0.2, 0.3, 1e-9)  --> true

MapRange(value, inMin, inMax, outMin, outMax) rescales value from the inMin..inMax range into outMin..outMax — useful for things like mapping a joystick's -1..1 axis onto a 0..100 UI bar. FuzzyEquals is for comparing floats that accumulated rounding error and shouldn't be checked with ==.

Divide-by-zero
Passing inMin == inMax to MapRange divides by zero — Lua floats give you inf/nan back rather than an error, so it's on the caller to avoid that input.

TimerUtil

Debounce/throttle wrappers for rate-limiting how often a function runs.

local onClick = Thread.TimerUtil.Debounce(function()
    print("clicked")
end, 1)

button.MouseButton1Click:Connect(onClick) -- ignores clicks within 1s of the last one

Debounce(fn, seconds) runs fn immediately on the first call, then ignores every call for seconds afterward until the cooldown expires — the classic pattern for stopping a Touched event from firing twice. Throttle(fn, seconds) runs fn immediately too, but instead caps it to at most once per seconds. Both return a new wrapped function; they don't mutate fn.

No trailing call
Calls dropped during the cooldown/interval are simply discarded — neither function queues a trailing call to run once the window reopens.