vide/docs/api/reactivity-utility.md

Reactivity: Utility

cleanup()

Queues a callback to run when a scope is reran or destroyed.

• Type

  function cleanup(v: Function | Disconnectable | Destroyable | thread)
  
  type Function = () -> ()
  type Destroyable = { destroy: () -> () }
  type Disconnectable = { disconnect: () -> () }
  

• Example

  local count = source(0)
  
  local destroy = root(function()
      effect(function()
          count()
  
          cleanup(function()
              print "cleaned"
          end)
      end)
  end
  
  -- nothing printed yet
  count(1) -- prints "cleaned"
  count(2) -- prints "cleaned"
  destroy() -- prints "cleaned"
  

untrack() STABLE

Runs a function in a new stable scope.

• Type

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

• Details

  Can be used inside a reactive scope to read from sources you do not want tracked by the reactive scope.

• Example

  local a = source(0)
  local b = source(0)
  
  local sum = derive(function()
      return a() + untrack(b)
  end)
  
  print(sum()) -- 0
  b(1) -- untracked so reactive scope created by derive() does not rerun
  print(sum()) -- 0
  a(1) -- reactive scope created by derive() reruns
  print(sum()) -- 2
  

read()

Utility used to read a value that is either a primitive or a source.

• Type

  function read<T>(value: T | () -> T): T
  

batch()

Runs a function where any source updates made within the function do not trigger effects until after the function ends.

• Type

  function batch(fn: () -> ())
  

• Details

  Improves performance when an effect depends on multiple sources, and those sources need to be updated.

• Example

  local a = source(0)
  local b = source(0)
  
  effect(function()
      print(a() + b())
  end)
  
  -- prints "0"
  
  batch(function()
      a(1) -- no print
      b(2) -- no print
  end)
  
  -- prints "3"
  

context() STABLE

Creates a new context.

• Type

  function context<T>(default: T): Context<T>
  
  type Context<T> =
      () -> T -- get
      & <U>(T, () -> U) -> U -- set
  

• Details

  Calling context() returns a new context function. Call this function with no arguments to get the context value. If no context is set, the default value is returned, or an error is thrown if no default was given. Call this function with a value and a function to create a new context with the given value.

  The new context is run under a stable scope.

• Example

  local theme = context()
  
  local function Button()
      print(theme())
  end
  
  root(function()
      theme("light", function()
           Button() -- prints "light"
  
          theme("dark", function()
              Button() -- prints "dark"
          end)
      end)
  end)