maneetoo/luau_signals

Luau Port of alien-signals 👾 the lightest signal library

luau-signals

Luau Port of alien-signals 👾 the lightest signal library

Get On Wally Get On Pesde Documentation GitHub Releases Roblox OSS Discord Server Changelog My Works

About

luau-signals is a faithful Luau port of alien-signals, a push-pull reactive signals library whose core algorithm has been adopted by Vue 3.6. It brings the same signal / computed / effect / effectScope primitives to Luau 🦭 and Roblox, with the same lazy, glitch-free semantics: signals hold state, computed values are derived lazily, effects react to changes, and scopes let you dispose whole component trees at once.

The port preserves the upstream constraints that make alien-signals fast. Writes push flags through the graph while reads pull fresh values only when needed, so an unobserved computed chain is never touched. The hot path uses linked lists and plain arrays only — no Set, no Map, no dynamic fields — and propagate, checkDirty, and shallowPropagate are iterative rather than recursive. Each Link is seven flat fields with no hidden allocation.

What is specific to Luau is mostly adaptation. Signals, computed values, and effects are callable tables — the node is the API — so no closure or wrapper is allocated per node. Node kinds are identified by metatable identity instead of 'getter' in node checks, which cannot be ported literally because a nil-valued field does not exist in Luau; this also makes signal(nil) unambiguous. All flag operations go through bit32 (Luau has no native &, |, ~ for numbers), with masks precomputed and bit32.btest used for "any of these bits set". Every finally block from the original is reproduced with pcall plus a re-error, including state restoration on thrown errors, and the linked-list stack is replaced with a plain array plus a depth counter for cheaper push/pop and safe reentrancy.

Getting Started

Please follow the documentation here!

Benchmarks

Currently, Vide is the most popular and frequently chosen reactivity library for Luau, thanks to its speed and an API largely derived from Solid.js - which is why it was selected for comparison with luau-signals. Furthermore, unlike Fusion, Vide is currently being actively maintained and updated.

Comparing with Vide
ScenariosignalsvideWinnerRupture
batch: 10 writes, batched2.15 µs2.1 µs≈ equal~1.0×
batch: 10 writes, no batch11.8 µs14.7 µs🟢 signals1.24×
derive: 1 src → 50 derives → 1 effect13.4 µs20.6 µs🟢 signals1.54×
derive: chain depth 102.48 µs3.03 µs🟢 signals1.22×
derive: chain depth 10 → effect2.8 µs2.9 µs≈ equal~1.0×
derive: chain depth 409.11 µs11.6 µs🟢 signals1.27×
derive: cutoff (value unchanged)560 ns381 ns🔴 vide1.47×*
derive: diamond → effect1.22 µs1.28 µs≈ equal~1.0×
derive: unobserved (lazy vs eager)141 ns2.56 µs🟢 signals18.18×
derive: write + read (depth 1)452 ns437 ns≈ equal~1.0×
effect: create + dispose1.14 µs1.11 µs≈ equal~1.0×
effect: dynamic deps (branch toggle)708 ns515 ns🔴 vide1.37×*
effect: rerun with cleanup502 ns502 ns≈ equal~1.0×
graph: 20 src + 20 derive18.8 µs21.9 µs🟢 signals1.17×
mixed: 30 src, 60 derive, 15 effects2.73 µs11 µs🟢 signals4.04×
source: create106 ns100 ns🔴 vide1.06×*
source: read (untracked)39 ns59 ns🟢 signals1.52×
source: write, no subscribers53 ns86 ns🟢 signals1.63×
source: write, same value40 ns41 ns≈ equal~1.0×
write → 1 effect409 ns316 ns🔴 vide1.30×*
write → 10 effects2.26 µs3.24 µs🟢 signals1.43×
write → 100 effects18.3 µs24.4 µs🟢 signals1.33×

* - Scenarios where Vide excels - essentially its "natural habitat" - are those involving a single action (e.g. write operation resulting in one effect) or situations where nothing changes following an update. In such cases, its "eager" update model incurs lower computational overhead. For larger-scale tasks, luau-signals is a better choice.

Comparing with Fluid (fork of Vide)
ScenariosignalsfluidWinnerRupture
batch: 10 writes, batched2.15 µs53.31 µs🟢 signals24.80×
batch: 10 writes, no batch11.81 µs54.46 µs🟢 signals4.61×
derive: 1 src → 50 derives → 1 effect13.40 µs574.68 µs🟢 signals42.89×
derive: chain depth 102.48 µs8.52 µs🟢 signals3.44×
derive: chain depth 10 → effect2.80 µs11.26 µs🟢 signals4.02×
derive: chain depth 409.11 µs36.91 µs🟢 signals4.05×
derive: cutoff (value unchanged)560.2 ns1.56 µs🟢 signals2.78×
derive: diamond → effect1.22 µs4.54 µs🟢 signals3.72×
derive: unobserved (lazy vs eager)140.8 ns294.8 ns🟢 signals2.09×
derive: write + read (depth 1)451.7 ns1.27 µs🟢 signals2.81×
effect: create + dispose1.14 µs2.37 µs🟢 signals2.08×
effect: dynamic deps (branch toggle)707.5 ns1.77 µs🟢 signals2.50×
effect: rerun with cleanup501.8 ns1.53 µs🟢 signals3.05×
graph: 20 src + 20 derive18.77 µs43.14 µs🟢 signals2.30×
mixed: 30 src, 60 derive, 15 effects2.73 µs13.03 µs🟢 signals4.77×
source: create105.8 ns208.1 ns🟢 signals1.97×
source: read (untracked)38.8 ns74.2 ns🟢 signals1.91×
source: write, no subscribers52.6 ns137.6 ns🟢 signals2.62×
source: write, same value (no-op)40.1 ns71.1 ns🟢 signals1.77×
write → 1 effect409.4 ns1.24 µs🟢 signals3.03×
write → 10 effects2.26 µs11.65 µs🟢 signals5.15×
write → 100 effects18.34 µs115.79 µs🟢 signals6.31×
Comparing with Flux (@kohltastrophe)
ScenariosignalsfluxWinnerRupture
batch: 10 writes, batched2.15 µs1.86 µs🔴 flux1.16×
batch: 10 writes, no batch11.81 µs10.42 µs🔴 flux1.13×
derive: 1 src → 50 derives → 1 effect13.40 µs12.48 µs🔴 flux1.07×
derive: chain depth 102.48 µs2.27 µs🔴 flux1.09×
derive: chain depth 10 → effect2.80 µs3.06 µs🟢 signals1.09×
derive: chain depth 409.11 µs8.75 µs≈ equal~1.0×
derive: cutoff (value unchanged)560.2 ns544.1 ns≈ equal~1.0×
derive: diamond → effect1.22 µs1.12 µs🔴 flux1.09×
derive: unobserved (lazy vs eager)140.8 ns168.8 ns🟢 signals1.20×
derive: write + read (depth 1)451.7 ns406.1 ns🔴 flux1.11×
effect: create + dispose1.14 µs1.27 µs🟢 signals1.11×
effect: dynamic deps (branch toggle)707.5 ns922.9 ns🟢 signals1.30×
effect: rerun with cleanup501.8 ns471.0 ns🔴 flux1.07×
graph: 20 src + 20 derive18.77 µs17.58 µs🔴 flux1.07×
mixed: 30 src, 60 derive, 15 effects2.73 µs2.87 µs🟢 signals1.05×
source: create105.8 ns101.7 ns≈ equal~1.0×
source: read (untracked)38.8 ns41.3 ns🟢 signals1.06×
source: write, no subscribers52.6 ns52.1 ns≈ equal~1.0×
source: write, same value (no-op)40.1 ns41.2 ns≈ equal~1.0×
write → 1 effect409.4 ns455.2 ns🟢 signals1.11×
write → 10 effects2.26 µs2.38 µs🟢 signals1.05×
write → 100 effects18.34 µs19.49 µs🟢 signals1.06×

flux is close to signals — within 1.05–1.3× on every scenario, unlike fluid (2–43× slower). In this run signals is ahead in 9 scenarios, flux in 8, and 5 are within noise. The largest gaps are effect: dynamic deps (branch toggle) (1.30× in favour of signals) and batch: 10 writes, batched (1.16× in favour of flux). This suggests flux also uses a lazy push-pull model with similar overhead; the difference is likely in constant factors (getmetatable vs internal tags, closure handling, queue flush strategy) rather than architecture.

Code Sample

const luau_signals = require './luau-signals'
const signal, computed, effect, effectScope, startBatch, endBatch =
    luau_signals.signal, luau_signals.computed, luau_signals.effect, luau_signals.effectScope, luau_signals.startBatch, luau_signals.endBatch

const price, qty = signal(100), signal(2)
const total = computed(function()
    return price() * qty()
end)

-- effectScope — groups effects for collective disposal
const dispose = effectScope(function()
    -- effect — reacts to changes
    effect(function()
        print(`Total: { total() }`)
    end)
end) -- Output: `Total: 200`

price(150) -- Output: `Total: 300`

-- batch — multiple changes → a single effect restart
startBatch()
price(200)
qty(5)
endBatch() -- Output: `Total: 1000`

dispose() -- Unsubscribing from the entire scope
price(999) -- Nothing is being output

Attribution

The core algorithm is by Johnson Chu (alien-signals, MIT).

luau-signals is licensed under MIT License