🥮 mooncakes.io

signals

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

signals
reactive
alien-signals
ui
vnode
Download zip
Author
Version
0.6.5
License
MIT
Repository
Last updated
last month
Downloads
81K

#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 {
  fn 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