Starbeam

Starbeam is a library for building reactive data systems that integrate natively
with UI frameworks such as React, Vue, Svelte or Ember.

It interoperates natively with React state management patterns, Svelte stores,
the Vue composition API, and Ember’s auto-tracking system.

Starbeam Reactivity

Starbeam’s reactivity is based on a very simple, but powerful, idea:

• You mark your mutable state as reactive. Individual pieces of mutable state are called data cells.
• You use normal functions (or getters) to compute values based on your mutable state.
• You can turn a function into a formula cell to automatically cache it, and it will only recompute when the data cells it uses change.
• You use resources to compute values that require structured cleanup.

We call this collection of values the data universe. The data universe is always internally coherent. Once you mutate your state, you can call any function that depends on the mutable state, and that function will see an up-to-date version of the state.

Formulas, too, are always up to date. If you change a data cell that a formula depends on, and ask the formula for its current value, the formula will always produce a value that is up to date. You never need to worry about stale data.

The data universe becomes reactive when you plug it into your UI framework. Once you plug it into your UI framework, any changes to the data universe will be reflected in your UI automatically.

📝 Collectively, data cells and formula cells are called cells.

Data Cells and Formulas

Making It Universal

Plugging it into your UI

React

import { use } from "@starbeam/react";
import { InchCounter } from "#shared";

export function MeasureInches() {
  const inches = use(InchCounter);

  return (
    <>
      <button onClick={inches.increment}>Increment Inches</button>
      <div>{inches.description}</div>
    </>
  );
}

Svelte

Vue

<script>
import { InchCounter } from "#shared";

export default {
  setup() {
    const inches = InchCounter();

    return {
      inches,
    };
  },
};
script>

<template>
  <button v-on: click="inches.increment">Increment Inchesbutton>
  <div>{{ inches.description }}div>
template>

Resources

So what is a resource? A resource is a reactive value, just like our InchCounter above, that requires some cleanup. When you use a resource, you link it to an owner object, and when the owner object is cleaned up, the resource will be cleaned up as well. In practice, most of the time, the owner object is a component in your UI framework.

The RemoteData Resource

In this example, we’ll create a RemoteData resource that will fetch data from a remote server.

Note: We do not call this the fetch resource, because a resource represents a value not a task with a starting and stopping point. Because of this, the resource is linked, 1:1, to the owner object.

Inside of the RemoteData function, we use the Resource function to create a new resource. The Resource constructor takes a function, which we call the “resource constructor”. The resource constructor returns a cell that represents its current value. When code uses the resource, its value will be the current value of the reactive value.

A resource constructor is called once, when the resource is first used. A resource constructor:

• creates internal cells to manage its state
• connects to any stateful external objects it needs to manage, such as a network connection
• describes how to disconnect from those external objects when the resource is cleaned up
• returns a cell that represents the resource’s current value

💡 A resource can use mutable state internally, and it can interact with the imperative world, but it exposes the messy outside world as a cell that can be used in the data universe like any other cell, including in other formulas and even other resources.

Using it in React

Now that we’ve defined our data universe, we want to plug it into React to create a reactive system.

import { use } from "@starbeam/react";

function UserCard({ username }: { username: string }) {
  // when `username` changes, we clean up the old `RemoteData` resource and create a new one.
  const user = use(
    () => RemoteData(`https://api.github.com/users/${username}`),
    [username]
  );

  if (user.type === "loading") {
    return <div>Loading...</div>;
  } else if (user.type === "error") {
    return <div>Error: {user.error.message}</div>;
  } else {
    return <div>{user.data.name}</div>;
  }
}

In principle, we could turn RemoteData into a React hook that abstracts the dependencies for once and for all. The useRemoteData hook would take a URL, and whenever the URL changes, it would clean up the old resource and create a new one.

import { use } from "@starbeam/react";

function useRemoteData<T>(url: string) {
  return use(() => RemoteData(url), [url]);
}

And now we can use it in our app:

;
} else if (user.type === “error”) {
return

;
} else {
return

;
}
}”>

import { useRemoteData } from "#hooks/remote-data";

function UserCard({ username }: { username: string }) {
  const user = useRemoteData(`https://api.github.com/users/${username}`);

  if (user.type === "loading") {
    return <div>Loading...</div>;
  } else if (user.type === "error") {
    return <div>Error: {user.error.message}</div>;
  } else {
    return <div>{user.data.name}</div>;
  }
}