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.
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 ==.
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.