{"id":"maneetoo/luau-signals","name":"luau-signals","scope":"maneetoo","platform":"roblox","description":"Luau Port of alien-signals 👾 the lightest signal library","version":"0.2.0","latest":"0.2.0","versions":["0.1.0","0.1.1","0.2.0"],"license":"MIT","licenseRating":"safe","licenseCaveats":[],"licenseVerified":true,"dependencies":{},"integrity":"1738f98275e573db8cf385a652710a2002c886be172883d975f793fed06b3206","likes":0,"downloads":0,"install":"forest install maneetoo/luau-signals","url":"https://forest.dev/p/roblox/maneetoo/luau-signals","files":"https://api.forest.dev/ai/package/roblox/maneetoo/luau-signals/files","readme":"<div align=\"center\">\r\n\r\n<img src=\".github/assets/logo.svg\" width=\"100\">\r\n\r\n# luau-signals\r\nLuau Port of [alien-signals](https://github.com/stackblitz/alien-signals) 👾 the lightest signal library\r\n\r\n[![Get On Wally](https://raw.githubusercontent.com/maneetoo/Roblox-OSS-Badges/2214a2aca82cbdd386b946d759d3348705d7555e/Badges/Community/Package/link-wally.svg)](https://wally.run/package/maneetoo/luau-signals)\r\n[![Get On Pesde](https://raw.githubusercontent.com/maneetoo/Roblox-OSS-Badges/2214a2aca82cbdd386b946d759d3348705d7555e/Badges/Community/Package/link-pesde.svg)](https://pesde.dev/packages/maneetoo/luau_signals)\r\n[![Documentation](https://raw.githubusercontent.com/maneetoo/Roblox-OSS-Badges/2214a2aca82cbdd386b946d759d3348705d7555e/Badges/Roblox-Styled/Original/link-documentation.svg)](https://maneetoo.github.io/luau-signals/)\r\n[![GitHub Releases](https://raw.githubusercontent.com/maneetoo/Roblox-OSS-Badges/2214a2aca82cbdd386b946d759d3348705d7555e/Badges/Community/GitHub/link-github-releases.svg)](https://github.com/maneetoo/luau-signals/releases)\r\n[![Roblox OSS Discord Server](https://raw.githubusercontent.com/maneetoo/Roblox-OSS-Badges/2214a2aca82cbdd386b946d759d3348705d7555e/Badges/Community/Discord/link-discord-roblox-oss.svg)](https://discord.gg/vtUJdtUK2J)\r\n[![Changelog](https://raw.githubusercontent.com/maneetoo/Roblox-OSS-Badges/2214a2aca82cbdd386b946d759d3348705d7555e/Badges/Roblox-Styled/Original/link-changelog.svg)](https://github.com/maneetoo/luau-signals/blob/main/CHANGELOG.md)\r\n[![My Works](https://raw.githubusercontent.com/maneetoo/Roblox-OSS-Badges/2214a2aca82cbdd386b946d759d3348705d7555e/Badges/Roblox-Styled/Original/link-my-works.svg)](https://github.com/maneetoo/)\r\n\r\n</div>\r\n\r\n## About\r\n\r\n[`luau-signals`](https://github.com/maneetoo/luau-signals) is a faithful Luau port of [`alien-signals`](https://github.com/stackblitz/alien-signals), a push-pull reactive signals library whose core algorithm has been adopted by [Vue 3.6](https://github.com/vuejs/core/tree/minor). It brings the same `signal` / `computed` / `effect` / `effectScope` primitives to [`Luau 🦭`](https://luau.org/) 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.\r\n\r\nThe port preserves the upstream constraints that make [`alien-signals`](https://github.com/stackblitz/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.\r\n\r\nWhat 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`](https://luau.org/types/basic-types/#builtin-types)-valued field does not exist in Luau; this also makes `signal(nil)` unambiguous. All flag operations go through [`bit32`](https://luau.org/library/#bit32-library) (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.\r\n\r\n## Getting Started\r\n\r\nPlease follow the documentation [here](https://maneetoo.github.io/luau-signals/)!\r\n\r\n## Benchmarks\r\n\r\nCurrently, `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.\r\n\r\n<details>\r\n\t<summary>Comparing with Vide</summary>\r\n\r\n| Scenario | `signals` | `vide` | Winner | Rupture |\r\n|:--|--:|--:|:--|--:|\r\n| `batch: 10 writes, batched` | 2.15 µs | 2.1 µs | ≈ equal | ~1.0× |\r\n| `batch: 10 writes, no batch` | **11.8 µs** | 14.7 µs | 🟢 signals | 1.24× |\r\n| `derive: 1 src → 50 derives → 1 effect` | **13.4 µs** | 20.6 µs | 🟢 signals | **1.54×** |\r\n| `derive: chain depth 10` | **2.48 µs** | 3.03 µs | 🟢 signals | 1.22× |\r\n| `derive: chain depth 10 → effect` | 2.8 µs | 2.9 µs | ≈ equal | ~1.0× |\r\n| `derive: chain depth 40` | **9.11 µs** | 11.6 µs | 🟢 signals | 1.27× |\r\n| `derive: cutoff (value unchanged)` | 560 ns | **381 ns** | 🔴 vide | **1.47×*** |\r\n| `derive: diamond → effect` | 1.22 µs | 1.28 µs | ≈ equal | ~1.0× |\r\n| `derive: unobserved (lazy vs eager)` | **141 ns** | 2.56 µs | 🟢 signals | **18.18×** |\r\n| `derive: write + read (depth 1)` | 452 ns | 437 ns | ≈ equal | ~1.0× |\r\n| `effect: create + dispose` | 1.14 µs | 1.11 µs | ≈ equal | ~1.0× |\r\n| `effect: dynamic deps (branch toggle)` | 708 ns | **515 ns** | 🔴 vide | **1.37×*** |\r\n| `effect: rerun with cleanup` | 502 ns | 502 ns | ≈ equal | ~1.0× |\r\n| `graph: 20 src + 20 derive` | **18.8 µs** | 21.9 µs | 🟢 signals | 1.17× |\r\n| `mixed: 30 src, 60 derive, 15 effects` | **2.73 µs** | 11 µs | 🟢 signals | **4.04×** |\r\n| `source: create` | 106 ns | **100 ns** | 🔴 vide | 1.06×* |\r\n| `source: read (untracked)` | **39 ns** | 59 ns | 🟢 signals | **1.52×** |\r\n| `source: write, no subscribers` | **53 ns** | 86 ns | 🟢 signals | **1.63×** |\r\n| `source: write, same value` | 40 ns | 41 ns | ≈ equal | ~1.0× |\r\n| `write → 1 effect` | 409 ns | **316 ns** | 🔴 vide | 1.30×* |\r\n| `write → 10 effects` | **2.26 µs** | 3.24 µs | 🟢 signals | **1.43×** |\r\n| `write → 100 effects` | **18.3 µs** | 24.4 µs | 🟢 signals | **1.33×** |\r\n\r\n`*` - 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.\r\n</details>\r\n\r\n<details>\r\n\t<summary>Comparing with Fluid (fork of Vide)</summary>\r\n\r\n| Scenario | `signals` | `fluid` | Winner | Rupture |\r\n|:--|--:|--:|:--|--:|\r\n| `batch: 10 writes, batched` | **2.15 µs** | 53.31 µs | 🟢 signals | **24.80×** |\r\n| `batch: 10 writes, no batch` | **11.81 µs** | 54.46 µs | 🟢 signals | **4.61×** |\r\n| `derive: 1 src → 50 derives → 1 effect` | **13.40 µs** | 574.68 µs | 🟢 signals | **42.89×** |\r\n| `derive: chain depth 10` | **2.48 µs** | 8.52 µs | 🟢 signals | **3.44×** |\r\n| `derive: chain depth 10 → effect` | **2.80 µs** | 11.26 µs | 🟢 signals | **4.02×** |\r\n| `derive: chain depth 40` | **9.11 µs** | 36.91 µs | 🟢 signals | **4.05×** |\r\n| `derive: cutoff (value unchanged)` | **560.2 ns** | 1.56 µs | 🟢 signals | **2.78×** |\r\n| `derive: diamond → effect` | **1.22 µs** | 4.54 µs | 🟢 signals | **3.72×** |\r\n| `derive: unobserved (lazy vs eager)` | **140.8 ns** | 294.8 ns | 🟢 signals | **2.09×** |\r\n| `derive: write + read (depth 1)` | **451.7 ns** | 1.27 µs | 🟢 signals | **2.81×** |\r\n| `effect: create + dispose` | **1.14 µs** | 2.37 µs | 🟢 signals | **2.08×** |\r\n| `effect: dynamic deps (branch toggle)` | **707.5 ns** | 1.77 µs | 🟢 signals | **2.50×** |\r\n| `effect: rerun with cleanup` | **501.8 ns** | 1.53 µs | 🟢 signals | **3.05×** |\r\n| `graph: 20 src + 20 derive` | **18.77 µs** | 43.14 µs | 🟢 signals | **2.30×** |\r\n| `mixed: 30 src, 60 derive, 15 effects` | **2.73 µs** | 13.03 µs | 🟢 signals | **4.77×** |\r\n| `source: create` | **105.8 ns** | 208.1 ns | 🟢 signals | **1.97×** |\r\n| `source: read (untracked)` | **38.8 ns** | 74.2 ns | 🟢 signals | **1.91×** |\r\n| `source: write, no subscribers` | **52.6 ns** | 137.6 ns | 🟢 signals | **2.62×** |\r\n| `source: write, same value (no-op)` | **40.1 ns** | 71.1 ns | 🟢 signals | **1.77×** |\r\n| `write → 1 effect` | **409.4 ns** | 1.24 µs | 🟢 signals | **3.03×** |\r\n| `write → 10 effects` | **2.26 µs** | 11.65 µs | 🟢 signals | **5.15×** |\r\n| `write → 100 effects` | **18.34 µs** | 115.79 µs | 🟢 signals | **6.31×** |\r\n</details>\r\n\r\n<details>\r\n\t<summary>Comparing with Flux (@kohltastrophe)</summary>\r\n\r\n| Scenario | `signals` | `flux` | Winner | Rupture |\r\n|:--|--:|--:|:--|--:|\r\n| `batch: 10 writes, batched` | 2.15 µs | **1.86 µs** | 🔴 flux | 1.16× |\r\n| `batch: 10 writes, no batch` | 11.81 µs | **10.42 µs** | 🔴 flux | 1.13× |\r\n| `derive: 1 src → 50 derives → 1 effect` | 13.40 µs | **12.48 µs** | 🔴 flux | 1.07× |\r\n| `derive: chain depth 10` | 2.48 µs | **2.27 µs** | 🔴 flux | 1.09× |\r\n| `derive: chain depth 10 → effect` | **2.80 µs** | 3.06 µs | 🟢 signals | 1.09× |\r\n| `derive: chain depth 40` | 9.11 µs | 8.75 µs | ≈ equal | ~1.0× |\r\n| `derive: cutoff (value unchanged)` | 560.2 ns | 544.1 ns | ≈ equal | ~1.0× |\r\n| `derive: diamond → effect` | 1.22 µs | **1.12 µs** | 🔴 flux | 1.09× |\r\n| `derive: unobserved (lazy vs eager)` | **140.8 ns** | 168.8 ns | 🟢 signals | 1.20× |\r\n| `derive: write + read (depth 1)` | 451.7 ns | **406.1 ns** | 🔴 flux | 1.11× |\r\n| `effect: create + dispose` | **1.14 µs** | 1.27 µs | 🟢 signals | 1.11× |\r\n| `effect: dynamic deps (branch toggle)` | **707.5 ns** | 922.9 ns | 🟢 signals | **1.30×** |\r\n| `effect: rerun with cleanup` | 501.8 ns | **471.0 ns** | 🔴 flux | 1.07× |\r\n| `graph: 20 src + 20 derive` | 18.77 µs | **17.58 µs** | 🔴 flux | 1.07× |\r\n| `mixed: 30 src, 60 derive, 15 effects` | **2.73 µs** | 2.87 µs | 🟢 signals | 1.05× |\r\n| `source: create` | 105.8 ns | 101.7 ns | ≈ equal | ~1.0× |\r\n| `source: read (untracked)` | **38.8 ns** | 41.3 ns | 🟢 signals | 1.06× |\r\n| `source: write, no subscribers` | 52.6 ns | 52.1 ns | ≈ equal | ~1.0× |\r\n| `source: write, same value (no-op)` | 40.1 ns | 41.2 ns | ≈ equal | ~1.0× |\r\n| `write → 1 effect` | **409.4 ns** | 455.2 ns | 🟢 signals | 1.11× |\r\n| `write → 10 effects` | **2.26 µs** | 2.38 µs | 🟢 signals | 1.05× |\r\n| `write → 100 effects` | **18.34 µs** | 19.49 µs | 🟢 signals | 1.06× |\r\n\r\n`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.\r\n</details>\r\n\r\n\r\n## Code Sample\r\n```luau\r\nconst luau_signals = require './luau-signals'\r\nconst signal, computed, effect, effectScope, startBatch, endBatch =\r\n    luau_signals.signal, luau_signals.computed, luau_signals.effect, luau_signals.effectScope, luau_signals.startBatch, luau_signals.endBatch\r\n\r\nconst price, qty = signal(100), signal(2)\r\nconst total = computed(function()\r\n    return price() * qty()\r\nend)\r\n\r\n-- effectScope — groups effects for collective disposal\r\nconst dispose = effectScope(function()\r\n    -- effect — reacts to changes\r\n    effect(function()\r\n        print(`Total: { total() }`)\r\n    end)\r\nend) -- Output: `Total: 200`\r\n\r\nprice(150) -- Output: `Total: 300`\r\n\r\n-- batch — multiple changes → a single effect restart\r\nstartBatch()\r\nprice(200)\r\nqty(5)\r\nendBatch() -- Output: `Total: 1000`\r\n\r\ndispose() -- Unsubscribing from the entire scope\r\nprice(999) -- Nothing is being output\r\n```\r\n\r\n## Attribution\r\n\r\nThe core algorithm is by [Johnson Chu](https://github.com/johnsoncodehk) ([alien-signals](https://github.com/stackblitz/alien-signals), MIT).\r\n\r\n[luau-signals](https://github.com/maneetoo/luau-signals) is licensed under [MIT License](https://github.com/maneetoo/luau-signals/blob/main/LICENSE)","readmeTruncated":false}