🥮 mooncakes.io

signals

Fine-grained reactive signals for MoonBit (alien-signals inspired)

signals
reactive
alien-signals
ui
vnode
moon add mizchi/signals@0.6.5
Download zip
Author
Version
0.6.5
License
MIT
Repository
Last updated
last month
Downloads
76K
README

#mizchi/signals

Fine-grained reactive signals library for MoonBit. Inspired by alien-signals and Solid.js.

#What are Reactive Signals?

Reactive signals provide a way to manage state that automatically tracks dependencies and propagates changes. When a signal's value changes, all computations and effects that depend on it are automatically updated.

Key benefits:
  • Automatic dependency tracking: No need to manually specify what depends on what
  • Efficient updates: Only affected computations re-run when values change
  • Composable: Build complex reactive graphs from simple primitives

Use cases:
  • UI frameworks: Automatically update views when data changes
  • State management: Manage application state with predictable updates
  • Data pipelines: Create derived values that stay in sync with source data
  • Game development: React to game state changes efficiently
  • Real-time systems: Propagate sensor/input changes through a system

#Installation

moon add mizchi/signals

#API

#Signal

Holds a reactive value and notifies subscribers when it changes.

let count = signal(0)

// Get value (auto-tracked inside effects)
count.get()  // => 0

// Set value
count.set(5)

// Update with function
count.update(fn(n) { n + 1 })

// Get without tracking (doesn't create dependency)
count.peek()

#memo / computed

Creates a memoized value that recomputes only when dependencies change.

let a = signal(2)
let b = signal(3)

let sum = memo(fn() { a.get() + b.get() })
sum()  // => 5

a.set(10)
sum()  // => 13 (recomputed)
sum()  // => 13 (cached value)

computed is an alias for memo.

#render_effect

Creates a side effect that re-runs synchronously when signals change.

let count = signal(0)

let dispose = render_effect(fn() {
  println("count = " + count.get().to_string())
})

count.set(1)  // prints "count = 1"
count.set(2)  // prints "count = 2"

dispose()  // stop the effect

#effect

Similar to render_effect, but the initial execution is deferred via microtask queue (Solid.js createEffect style).

let count = signal(0)
let dispose = effect(fn() {
  println("deferred: " + count.get().to_string())
})
// Initial execution happens after current synchronous code completes

Note: effect uses queue_microtask, which is environment-specific. See "Environment-specific async behavior" below.

#batch

Batches multiple updates so effects run only once.

let a = signal(0)
let b = signal(0)

let _ = render_effect(fn() {
  println("sum = " + (a.get() + b.get()).to_string())
})

batch(fn() {
  a.set(1)
  b.set(2)
})
// Effect runs only once

#on_cleanup

Registers a cleanup function inside an effect. Called before the effect re-runs or when disposed.

let _ = render_effect(fn() {
  let id = set_interval(...)
  on_cleanup(fn() {
    clear_interval(id)
  })
})

#create_root

Creates a reactive scope root. Calling dispose stops all effects within.

create_root(fn(dispose) {
  let _ = render_effect(fn() { ... })
  let _ = render_effect(fn() { ... })

  // Stop all effects at once
  dispose()
})

#untracked

Runs a function with tracking disabled. Signal reads won't create dependencies.

let _ = render_effect(fn() {
  // This signal read won't create a dependency
  untracked(fn() {
    let _ = some_signal.get()
  })
})

#Environment-specific async behavior

This library uses queue_microtask for deferred effects (the effect function), but microtask scheduling is environment-specific.

  • JS target: Uses native queueMicrotask from browser/Node.js
  • Non-JS targets (wasm/native): Falls back to immediate execution

For production use requiring deferred execution, consider implementing environment-appropriate async handling. If synchronous behavior is sufficient, use render_effect instead.

#License

MIT

#
Snapshot

source
pub trait Snapshot {
  snapshot(Self) -> Self
}

Trait for signal records that can produce a snapshot

#
Computed

source
pub(all) struct Computed[T] {
  node : ReactiveNode
  value : T?
  getter : () -> T
}

Computed node - derives value from dependencies (internal)

#
Computed::get

source
fn[T] Computed::get(self : Computed[T]) -> T

Get the computed value Automatically tracks dependency if called inside an effect/computed

#
Computed::peek

source
fn[T] Computed::peek(self : Computed[T]) -> T?

Peek at current value without tracking

#
Context

source
pub struct Context[T] {
  id : Int
  default_value : () -> T
  providers : Array[(Int, () -> T)]
}

Context type with typed getter The current_getter is managed per-context and tracks the current value chain

#
CoreSignal

source
pub(all) struct CoreSignal[T] {
  node : ReactiveNode
  current_value : T
  pending_value : T
}

CoreSignal - internal reactive value container (use Signal for public API)

#
CoreSignal::clear_subscribers

source
fn[T] CoreSignal::clear_subscribers(self : CoreSignal[T]) -> Unit

Clear all subscribers

#
CoreSignal::get

source
fn[T] CoreSignal::get(self : CoreSignal[T]) -> T

Get the current value of a core signal Automatically tracks dependency if called inside an effect/computed

#
CoreSignal::peek

source
fn[T] CoreSignal::peek(self : CoreSignal[T]) -> T

Get value without tracking (peek) Returns the latest value (pending if dirty, otherwise current)

#
CoreSignal::set

source
fn[T] CoreSignal::set(self : CoreSignal[T], value : T) -> Unit

Set a new value for the core signal Notifies all subscribers if value changed

#
CoreSignal::subscriber_count

source
fn[T] CoreSignal::subscriber_count(self : CoreSignal[T]) -> Int

Get number of subscribers (for debugging)

#
CoreSignal::update

source
fn[T] CoreSignal::update(self : CoreSignal[T], f : (T) -> T) -> Unit

Update core signal value using a function

#
EffectNode

source
pub(all) struct EffectNode {
  node : ReactiveNode
  run_fn : () -> Unit
}

Effect node - runs side effects

#
Flags

source
pub(all) struct Flags {
  value : Int
}

Bitwise flag set

#
Flags::get_value

source
fn Flags::get_value(self : Flags) -> Int

#
Flags::has

source
fn Flags::has(self : Flags, flag : ReactiveFlags) -> Bool

#
Flags::has_any

source
fn Flags::has_any(self : Flags, flags : Array[ReactiveFlags]) -> Bool

#
Flags::new

source
fn Flags::new(initial : Int) -> Flags

#
Flags::set

source
fn Flags::set(self : Flags, flag : ReactiveFlags) -> Unit

#
Flags::set_value

source
fn Flags::set_value(self : Flags, v : Int) -> Unit

#
Flags::unset

source
fn Flags::unset(self : Flags, flag : ReactiveFlags) -> Unit

#
Lens

source
pub struct Lens[S, A] {
  get : (S) -> A
  set : (S, A) -> S
}

A lens focuses on a specific part of a larger structure

#
Lens::new

source
fn[S, A] Lens::new(get : (S) -> A, set : (S, A) -> S) -> Lens[S, A]

#
LensStore

source
pub struct LensStore[T] {
  source : Signal[T]
}

A store with lens-based field access Each focused lens creates a derived signal that only updates when that field changes

#
LensStore::focus

source
fn[T, A : Eq] LensStore::focus(self : LensStore[T], lens : Lens[T, A]) -> (Signal[A], (A) -> Unit)

Focus on a field using a lens, returns getter and setter functions The getter is memoized and only recomputes when the focused value changes Uses render_effect for synchronous updates

#
LensStore::new

source
fn[T] LensStore::new(initial : T) -> LensStore[T]

#
LensStore::snapshot

source
fn[T] LensStore::snapshot(self : LensStore[T]) -> T

Get the current snapshot of the entire store

#
LensStore::update

source
fn[T] LensStore::update(self : LensStore[T], f : (T) -> T) -> Unit

Update the entire store
pub(all) struct Link {
  version : Int
  dep : ReactiveNode
  sub : ReactiveNode
  prev_sub : Link?
  next_sub : Link?
  prev_dep : Link?
  next_dep : Link?
}

Double-linked list node connecting dependencies and subscribers

#
Owner

source
pub struct Owner {
  id : Int
  parent : Owner?
  children : Array[Owner]
  cleanups : Array[() -> Unit]
  disposers : Array[() -> Unit]
  disposed : Bool
}

Owner - manages lifecycle of reactive computations (Solid.js style)

#
Owner::dispose

source
fn Owner::dispose(self : Owner) -> Unit

Dispose this owner and all its children

#
Owner::new

source
fn Owner::new(parent : Owner?) -> Owner

Create a new Owner

#
ReactiveFlags

source
pub(all) enum ReactiveFlags {
  None
  Mutable
  Watching
  RecursedCheck
  Recursed
  Dirty
  Pending
}

Reactive flags for tracking node state

#
ReactiveFlags::to_int

source
fn ReactiveFlags::to_int(self : ReactiveFlags) -> Int

Convert flags to int for bitwise operations

#
ReactiveNode

source
pub(all) struct ReactiveNode {
  deps : Link?
  deps_tail : Link?
  subs : Link?
  subs_tail : Link?
  flags : Flags
  last_modified_cycle : Int
  effect_callback : () -> Unit?
}

Base reactive node - can be signal, computed, or effect

#
ReactiveNode::new

source
fn ReactiveNode::new(flags : Int) -> ReactiveNode

#
Signal

source
pub struct Signal[T] {
  inner : CoreSignal[T]
}

Signal type - holds a value and notifies subscribers on change. A reactive primitive that stores a value and automatically tracks dependencies.

#
Signal::clear_subscribers

source
fn[T] Signal::clear_subscribers(self : Signal[T]) -> Unit

Clear all subscribers (for cleanup)

#
Signal::get

source
fn[T] Signal::get(self : Signal[T]) -> T

Get the current value and track dependency if inside an effect. When called inside an effect or memo, automatically subscribes to changes.

#
Signal::new

source
fn[T] Signal::new(initial : T) -> Signal[T]

Create a new signal with initial value.

#
Signal::peek

source
fn[T] Signal::peek(self : Signal[T]) -> T

Get value without tracking (won't create dependency). Useful when you need to read a signal without subscribing to it.

#
Signal::set

source
fn[T] Signal::set(self : Signal[T], new_value : T) -> Unit

Set a new value and notify all subscribers.

#
Signal::subscriber_count

source
fn[T] Signal::subscriber_count(self : Signal[T]) -> Int

Get number of subscribers (for debugging)

#
Signal::update

source
fn[T] Signal::update(self : Signal[T], f : (T) -> T) -> Unit

Update the value using a function. Useful for updating based on current value.

#
SplitStore2

source
pub struct SplitStore2[A, B] {
  field1 : Signal[A]
  field2 : Signal[B]
}

A record where each field is an independent Signal This is the most performant approach - updates only affect specific fields

#
SplitStore2::new

source
fn[A, B] SplitStore2::new(v1 : A, v2 : B) -> SplitStore2[A, B]

#
SplitStore3

source
pub struct SplitStore3[A, B, C] {
  field1 : Signal[A]
  field2 : Signal[B]
  field3 : Signal[C]
}

3-field version

#
SplitStore3::new

source
fn[A, B, C] SplitStore3::new(v1 : A, v2 : B, v3 : C) -> SplitStore3[A, B, C]

#
all

source
fn all(signals : Array[Signal[Bool]]) -> (() -> Bool)

Create a signal that is true when all input signals are true.

#
any

source
fn any(signals : Array[Signal[Bool]]) -> (() -> Bool)

Create a signal that is true when any input signal is true.

#
batch

source
fn[T] batch(f : () -> T) -> T

Run a function in a batch - all signal updates are batched. Effects only run once after all updates complete.

#
batch_end

source
fn batch_end() -> Unit

End a batch update - run all pending effects

#
batch_start

source
fn batch_start() -> Unit

Start a batch update - effects won't run until batch ends

#
check_dirty

source
fn check_dirty(start_link : Link, sub : ReactiveNode, update_fn : (ReactiveNode) -> Bool) -> Bool

Check if any dependency is dirty and needs update

#
combine2

source
fn[A, B, R] combine2(a : Signal[A], b : Signal[B], f : (A, B) -> R) -> (() -> R)

Combine two signals into one. The getter recomputes when either signal changes.

#
combine3

source
fn[A, B, C, R] combine3(a : Signal[A], b : Signal[B], c : Signal[C], f : (A, B, C) -> R) -> (() -> R)

Combine three signals into one

#
combine4

source
fn[A, B, C, D, R] combine4(a : Signal[A], b : Signal[B], c : Signal[C], d : Signal[D], f : (A, B, C, D) -> R) -> (() -> R)

Combine four signals into one

#
computed

source
fn[T] computed(compute : () -> T) -> (() -> T)

Create a computed signal (alias for memo with Signal-like API). Same as memo, but named to be more familiar for those coming from other reactive frameworks.

#
core_signal

source
fn[T] core_signal(initial : T) -> CoreSignal[T]

Create a new core signal with initial value

#
create_context

source
fn[T] create_context(default_value : T) -> Context[T]

Create a new context with a default value Similar to Solid.js createContext

#
create_root

source
fn[T] create_root(f : (() -> Unit) -> T) -> T

Create a new reactive root scope. The function receives a dispose callback that cleans up all effects. Returns the result of the function.

#
create_root_with_dispose

source
fn[T] create_root_with_dispose(f : () -> T) -> (T, () -> Unit)

Create a reactive root and return both result and dispose function

#
effect

source
fn effect(fn_ : () -> Unit) -> (() -> Unit)

Create an effect that is deferred until after rendering completes. (Solid.js style createEffect - deferred execution via microtask) Returns a dispose function to stop the effect. Unlike render_effect, this runs asynchronously via microtask queue.

#
effect_once

source
fn effect_once(fn_ : () -> Unit) -> Unit

Create a one-time effect that disposes itself after first run. Useful for initialization logic that should only run once.

#
effect_when

source
fn effect_when(condition : () -> Bool, fn_ : () -> Unit) -> (() -> Unit)

Create an effect that only runs when condition is true. Uses render_effect for synchronous execution.

#
end_batch

source
fn end_batch() -> Unit

End a batch update

#
flatten

source
fn[T] flatten(outer : Signal[Signal[T]]) -> (() -> T)

Flatten a signal of signals. Unwraps nested Signal[Signal[T]] to a getter for T.

#
flush

source
fn flush() -> Unit

Flush the effect queue

#
get_active_sub

source
fn get_active_sub() -> ReactiveNode?

Get current active subscriber

#
get_batch_depth

source
fn get_batch_depth() -> Int

Get current batch depth

#
get_cycle

source
fn get_cycle() -> Int

Get current cycle

#
get_owner

source
fn get_owner() -> Owner?

Get the current owner (if any)

#
has_owner

source
fn has_owner() -> Bool

Check if currently inside an owner scope

#
inc_cycle

source
fn inc_cycle() -> Unit

Increment cycle

#
is_batching

source
fn is_batching() -> Bool

Check if we're currently inside a batch
fn link(dep : ReactiveNode, sub : ReactiveNode, version : Int) -> Unit

Create a link between dependency and subscriber

#
memo

source
fn[T] memo(compute : () -> T) -> (() -> T)

Create a memoized computation. Returns a getter function that caches the result and recomputes only when dependencies change.

#
new_effect_id

source
fn new_effect_id() -> Int

Generate a new unique effect ID
fn[T] on(sig : Signal[T], callback : (T) -> Unit) -> (() -> Unit)

Explicitly subscribe to a signal with a callback. Returns an unsubscribe function. Unlike effect(), this doesn't auto-track and only listens to this one signal. Callback is NOT called on initial subscription, only on subsequent changes.

#
on_cleanup

source
fn on_cleanup(cleanup : () -> Unit) -> Unit

Register a cleanup function to run when the current scope disposes. Works in:
  • Effects: cleanup runs before effect re-runs or when effect disposes
  • Components: cleanup runs when component unmounts (Solid.js style - can be called directly in component body)

#
on_immediate

source
fn[T] on_immediate(sig : Signal[T], callback : (T) -> Unit) -> (() -> Unit)

Subscribe and run immediately with current value. Like on, but also invokes the callback with the current value right away.

#
on_mount

source
fn on_mount(fn_ : () -> Unit) -> Unit

Run a function once after mount (Solid.js style onMount). The function runs without tracking dependencies. Cleanup registered via on_cleanup inside will run when owner is disposed.
fn[T] previous(sig : Signal[T]) -> (() -> T?)

Create a signal that holds the previous value of another signal. Returns a getter function for the previous value (None on first read).

#
previous_with_initial

source
fn[T] previous_with_initial(sig : Signal[T], initial : T) -> (() -> T)

Create a signal that holds the previous value with initial value. Unlike previous, this returns a plain T instead of T?.

#
propagate

source
fn propagate(start_link : Link) -> Unit

Propagate changes through the dependency graph (simplified version)

#
provide

source
fn[T, R] provide(ctx : Context[T], value : T, f : () -> R) -> R

Provide a context value for the current Owner and its descendants The value is associated with the current Owner and will be available to all effects and components created within this scope.

#
purge_deps

source
fn purge_deps(sub : ReactiveNode) -> Unit

Purge unused deps after deps_tail

#
queue_effect

source
fn queue_effect(eff : EffectNode) -> Unit

Queue an effect for execution

#
register_disposer

source
fn register_disposer(disposer : () -> Unit) -> Unit

Register a disposer with the current owner Called internally by effect() to register its dispose function

#
register_owner_cleanup

source
fn register_owner_cleanup(cleanup : () -> Unit) -> Unit

Register a cleanup with the current owner (alternative to onCleanup in effect)

#
render_effect

source
fn render_effect(fn_ : () -> Unit) -> (() -> Unit)

Create an effect that runs immediately and re-runs when dependencies change. (Solid.js style createRenderEffect - synchronous execution) Returns a dispose function to stop the effect. Supports on_cleanup() calls inside the effect.

#
run_with_cleanup_tracking

source
fn[T] run_with_cleanup_tracking(cleanups : Array[() -> Unit], f : () -> T) -> T

Run a function with cleanup tracking enabled

#
run_with_owner

source
fn[T] run_with_owner(owner : Owner, f : () -> T) -> T

Run a function with a specific owner as current

#
select

source
fn[T] select(items : Signal[Array[T]], index : Signal[Int]) -> (() -> T?)

Select from an array signal by index signal. Returns None if index is out of bounds.

#
set_active_sub

source
fn set_active_sub(sub : ReactiveNode?) -> ReactiveNode?

Set active subscriber, returns previous

#
set_current_cleanups

source
fn set_current_cleanups(cleanups : Array[() -> Unit]?) -> Array[() -> Unit]?

Set the current cleanup array (used internally by effect)

#
shallow_propagate

source
fn shallow_propagate(start_link : Link) -> Unit

Shallow propagate - mark direct subscribers as dirty

#
sig_filter

source
fn[T] sig_filter(sig : Signal[T], predicate : (T) -> Bool) -> Signal[T?]

Filter signal updates - only updates when predicate is true. Returns a signal that only updates when predicate passes.

#
sig_filter_map

source
fn[T, U] sig_filter_map(sig : Signal[T], f : (T) -> U?) -> Signal[U?]

Filter and map signal updates Uses render_effect for synchronous execution

#
sig_map

source
fn[T, U] sig_map(sig : Signal[T], f : (T) -> U) -> (() -> U)

Map a signal's value through a function. Returns a getter function (like memo) that recomputes when the signal changes.

#
signal

source
fn[T] signal(initial : T) -> Signal[T]

Convenience function to create a signal. Shorthand for Signal::new.

#
start_batch

source
fn start_batch() -> Unit

Start a batch update

#
switch_

source
fn[T] switch_(condition : Signal[Bool], on_true : Signal[T], on_false : Signal[T]) -> (() -> T)

Switch between signals based on a boolean signal. Returns value from on_true when condition is true, otherwise on_false.

#
to_getter

source
fn[T] to_getter(sig : Signal[T]) -> (() -> T)

Create a read-only getter for a signal
fn unlink(lnk : Link, sub : ReactiveNode) -> Link?

Unlink a dependency link, returns next dep link

#
untracked

source
fn[T] untracked(f : () -> T) -> T

Run a function without tracking (useful for avoiding circular deps). Signal reads inside this function won't create subscriptions.

#
use_context

source
fn[T] use_context(ctx : Context[T]) -> T

Use a context value - returns the current provided value or default Walks up the Owner chain to find the nearest provided value. Similar to Solid.js useContext

#
watch

source
fn[T : Eq] watch(source : () -> T, callback : (T, T) -> Unit) -> (() -> Unit)

Watch a computed expression and run callback when it changes. Returns a dispose function. The callback receives (newValue, oldValue).

#
watch_immediate

source
fn[T : Eq] watch_immediate(source : () -> T, callback : (T, T?) -> Unit) -> (() -> Unit)

Watch with immediate execution (runs callback on first value too). The callback receives (newValue, oldValue?) where oldValue is None on first run.

#
with_parent_owner

source
fn[T] with_parent_owner(captured_owner : Owner?, f : () -> T) -> T

Run a function with a captured parent owner context (if any) This is useful for rendering child components that need to inherit the parent's owner. If captured_owner is Some, runs with that owner as context. If captured_owner is None, runs directly without owner context.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io