Functions

In the previous section, we kept repeating that updates to cells take effect immediately. That will start to matter once we build functions that compute values based on the value of a cell.

Just Use Functions

In Starbeam, there is no special concept such as "derived state" or "computed property" that you use to compute a value from reactive values.

Instead, you use JavaScript's built-in mechanism for computing values based on other values: functions.

A Simple Function

tsx
import { Cell, Reactive } from "@starbeam/universal";
 
const name = Cell("John");
const location = Cell("New York");
 
function description(): string {
  return `${name.current} lives in ${location.current}`;
}

tsx
import { Cell, Reactive } from "@starbeam/universal";
 
const name = Cell("John");
const location = Cell("New York");
 
function description(): string {
  return `${name.current} lives in ${location.current}`;
}

tsx
import { Cell } from "@starbeam/universal";
 
const name = Cell("John");
const location = Cell("New York");
 
function description() {
  return `${name.current} lives in ${location.current}`;
}

tsx
import { Cell } from "@starbeam/universal";
 
const name = Cell("John");
const location = Cell("New York");
 
function description() {
  return `${name.current} lives in ${location.current}`;
}

Calling the Function

To get the computed value, you call the function.

tsx
description();
// "John lives in New York"
 
name.set("John Doe");
description();
// "John Doe lives in New York"
 
location.set("Los Angeles");
description(); // "John Doe lives in Los Angeles"

tsx
description();
// "John lives in New York"
 
name.set("John Doe");
description();
// "John Doe lives in New York"
 
location.set("Los Angeles");
description(); // "John Doe lives in Los Angeles"

Because updates to cells take effect immediately, calling a function immediately after updating a cell will always return an up-to-date result.

A Weird Feeling

You might be getting the feeling that you're being tricked and there's nothing reactive about what we're doing.

That's what we mean when we say that reactivity in Starbeam feels like normal JavaScript.

But don't worry! You'll soon see how these seemingly normal JavaScript functions can reactively update the DOM.

Passing Cells as Arguments

You can also pass cells into functions as arguments.

tsx
function description(name: Reactive<string>): string {
  return `${name.current} lives in ${location.current}`;
}

tsx
function description(name: Reactive<string>): string {
  return `${name.current} lives in ${location.current}`;
}

tsx
function description(name) {
  return `${name.current} lives in ${location.current}`;
}

tsx
function description(name) {
  return `${name.current} lives in ${location.current}`;
}

And then use the function as normal.

tsx
const name = Cell("John");
const location = Cell("New York");
 
description(name); //=> "John lives in New York"
 
name.set("John Doe");
description(name); //=> "John Doe lives in New York"
 
location.set("Los Angeles");
description(name); //=> "John Doe lives in Los Angeles"

tsx
const name = Cell("John");
const location = Cell("New York");
 
description(name); //=> "John lives in New York"
 
name.set("John Doe");
description(name); //=> "John Doe lives in New York"
 
location.set("Los Angeles");
description(name); //=> "John Doe lives in Los Angeles"

Optionally Reactive Arguments

You may want to write a function that is able to take a reactive value as an argument, but will also accept a normal value as well.

This is especially important when writing universal code (code that is intended to work across multiple frameworks).

Instead of reading the cell by accessing its current property, you can use the read function to read its value. If you call read with a non-reactive value, it will return the value you passed it.

Instead of taking a Reactive<T> as an argument, you can take an IntoReactive<T>.

tsx
function description(
  name: IntoReactive<string>,
  location: IntoReactive<string>,
): string {
  return `${read(name)} lives in ${read(location)}`;
}

tsx
function description(
  name: IntoReactive<string>,
  location: IntoReactive<string>,
): string {
  return `${read(name)} lives in ${read(location)}`;
}

tsx
function description(name, location) {
  return `${read(name)} lives in ${read(location)}`;
}

tsx
function description(name, location) {
  return `${read(name)} lives in ${read(location)}`;
}

When you pass a non-reactive value in, the function behaves as if you had passed in a reactive value that never changes.

tsx
const name = Cell("John");
const location = Cell("New York");
 
description(name, "New York"); //=> "John lives in New York"
description("John", location); //=> "John lives in New York"
 
name.set("John Doe");
description(name, location); //=> "John Doe lives in New York"
 
location.set("Los Angeles");
description(name, location); //=> "John Doe lives in Los Angeles"
 
description("John", location); //=> "John lives in Los Angeles"

tsx
const name = Cell("John");
const location = Cell("New York");
 
description(name, "New York"); //=> "John lives in New York"
description("John", location); //=> "John lives in New York"
 
name.set("John Doe");
description(name, location); //=> "John Doe lives in New York"
 
location.set("Los Angeles");
description(name, location); //=> "John Doe lives in Los Angeles"
 
description("John", location); //=> "John lives in Los Angeles"

What About Expensive Computations?

So far, we've seen that you can use normal functions to compute values.

When these functions are rendered using a Starbeam renderer, any changes to cells used by the function will result in rerendering.

You might be worried about the fact that the function is executed every time it's used, even if that happens multiple times in your app for the same render.

Key Point

In most cases, the cost of maintaining a cache of a computation is more expensive than the computation itself.

However, it is definitely possible to have a computation that is very expensive to compute, and is worth caching.

You can learn more about this in the Optimizing Expensive Computations guide.

Functions ​

A Simple Function ​

Calling the Function ​

Passing Cells as Arguments ​

What About Expensive Computations? ​