Reactivity API: Core ​

root() ​

Creates and runs a function in a new reactive scope.

• Type

  lua

  function root<T...>(fn: (destroy: () -> ()) -> T...): T...

  function root<T...>(fn: (destroy: () -> ()) -> T...): T...

• Details

  Returns the result of the given function.

  Creates a new root reactive scope, where creation and derivations of sources can be tracked and properly disposed of.

  A function to destroy the root is passed into the callback, which will run any cleanups and allow derived sources created to garbage collect.

source() ​

Creates a new source with the given value.

• Type

  lua

  function source<T>(value: T): (T?) -> T

  function source<T>(value: T): (T?) -> T

• Details

  Calling the returned source with no argument will return its stored value, calling with an argument will set a new value.

  Reading from the source from within a reactive scope will cause changes to that source to be tracked and anything depending on it to update.

  Sources can be created outside of reactive scopes.

• Example

  lua

  local count = source(0)
  
  count() -- 0
  
  count(count() + 1) -- 1

  local count = source(0)
  
  count() -- 0
  
  count(count() + 1) -- 1

effect() ​

Runs a side-effect in a new reactive scope on source update.

• Type

  lua

  function effect(callback: () -> ())

  function effect(callback: () -> ())

• Details

  Any time a source referenced in the callback is changed, the callback will be reran.

  The callback is ran to initially ran on first call to find dependent sources.

• Example

  lua

  local num = source(1)
  
  effect(function()
      print(num())
  end)
  
  -- prints 1
  
  num(num() + 1)
  
  -- prints 2

  local num = source(1)
  
  effect(function()
      print(num())
  end)
  
  -- prints 1
  
  num(num() + 1)
  
  -- prints 2

derive() ​

Derives a new source in a new reactive scope from existing sources.

• Type

  lua

  function derive<T>(source: () -> T): () -> T

  function derive<T>(source: () -> T): () -> T

• Details

  The derived source will have its value recalculated when any source source it derives from is updated.

  Anytime its value is recalculated it is also cached, subsequent calls will retun this cached value until it recalculates again.

  The callback is ran to initially ran on first call to find dependent sources.

• Example

  lua

  local count = source(0)
  local text = derive(function() return `count: {count()}` end)
  
  text() -- "count: 0"
  
  count(1)
  
  text() -- "count: 1"

  local count = source(0)
  local text = derive(function() return `count: {count()}` end)
  
  text() -- "count: 0"
  
  count(1)
  
  text() -- "count: 1"