Resources ​

Resources are created with an owner, and whenever the owner is cleaned up, the resource is also cleaned up. This is called ownership linking.

Typically, a component in your framework will own your resources. The framework renderer will make sure that when your component is unmounted, its associated resources are cleaned up.

A Very Simple Resource ​

To illustrate the concept, let's create a simple resource that represents the current time.

tsx
import { Cell, Resource } from "@starbeam/universal";
 
export const Now = Resource(({ on }) => {
  const now = Cell(Date.now());
 
  const timer = setInterval(() => {
    now.set(Date.now());
  });
 
  on.cleanup(() => {
    clearInterval(timer);
  });
 
  return now;
});

tsx
import { Cell, Resource } from "@starbeam/universal";
 
export const Now = Resource(({ on }) => {
  const now = Cell(Date.now());
 
  const timer = setInterval(() => {
    now.set(Date.now());
  });
 
  on.cleanup(() => {
    clearInterval(timer);
  });
 
  return now;
});

When you use the Now resource in a component in your framework, it will automatically get its lifetime linked to the component. In this case, that means that the interval will be cleaned up when the component is unmounted.

The Resource function creates a Resource Constructor. A resource constructor:

1. Sets up internal reactive state that changes over time.
2. Sets up the external process that needs to be cleaned up.
3. Registers the cleanup code that will run when the resource is cleaned up.
4. Returns a reactive value that represents the current state of the resource as a value.

In this case:

A Ticking Stopwatch ​

To see how lifetime linking works, here's a simple demo of a Stopwatch resource using the DEBUG_RENDERER.

The code instantiates the stopwatch using an owner it creates locally. When you press the "Finalize the Stopwatch" button, the owner is finalized, which will clean up the stopwatch.

import { LIFETIME } from "@starbeam/timeline";
import { DEBUG_RENDERER } from "@starbeam/universal";
import { Stopwatch } from "./stopwatch";

const button = document.querySelector(
  "#finalize"
) as HTMLButtonElement;
const output = document.querySelector(
  "#output"
) as HTMLParagraphElement;

// Instantiate the Stopwatch with an owner. We will
// later finalize the owner to clean up the resource.
// In this case, that will clear the interval and
// stop the watch from ticking.
const owner = {};
const stopwatch = Stopwatch.create(owner);

// Render the stopwatch into the DOM. The `render`
// callback will be called whenever the stopwatch's
// value changes.
//
// In this case, that will happen whenever the `time`
// cell in the resource is set.
DEBUG_RENDERER.render({
  render: () => stopwatch.current,
  debug: (now) => {
    output.innerHTML = `The current time is: ${now}`;
  },
});

button.addEventListener("click", () => {
  LIFETIME.finalize(owner);
});

A description of the Stopwatch resource:

The internals of the Stopwatch resource behave very similarly to the Now resource. The main difference is that the Stopwatch resource returns the time as a formatted string.

From the perspective of the code that uses the stopwatch, the return value is a normal reactive string.

Reusing the Now Resource in Stopwatch ​

You might be thinking that Stopwatch reimplements a whole bunch of Now, and you ought to be able to just use Now directly inside of Stopwatch.

You'd be right!

tsx
const Stopwatch = Resource(({ use }) => {
  const time = use(Now);
         
const time: Reactive<number>
 
  const formatter = new Intl.DateTimeFormat("en-US", {
    hour: "numeric",
    minute: "numeric",
    second: "numeric",
    hour12: false,
  });
 
  return Formula(() => formatter.format(time.current));
});

tsx
const Stopwatch = Resource(({ use }) => {
  const time = use(Now);
         
const time: Reactive<number>
 
  const formatter = new Intl.DateTimeFormat("en-US", {
    hour: "numeric",
    minute: "numeric",
    second: "numeric",
    hour12: false,
  });
 
  return Formula(() => formatter.format(time.current));
});

The Stopwatch resource instantiated a Now resource using its use method. That automatically links the Now instance to the owner of the Stopwatch, which means that when the component that instantiated the stopwatch is unmounted, the interval will be cleaned up.

Using a Resource to Represent an Open Channel ​

Resources can do more than represent data like a ticking clock. You can use a resource with any long-running process, as long as you can represent it meaningfully as a "current value".

Let's take a look at an example of a resource that receives messages on a channel, and returns a string representing the last message it received.

In this example, the channel name that we're subscribing to is dynamic, and we want to unsubscribe from the channel whenever the channel name changes, but not when we get a new message.

tsx
function ChannelResource(
  channelName: Reactive<string>,
): ResourceBlueprint<string> {
  return Resource(({ on }) => {
    const lastMessage = Cell(null as string | null);
 
    const channel = Channel.subscribe(channelName.read());
 
    channel.onMessage((message) => {
      lastMessage.set(message);
    });
 
    on.cleanup(() => {
      channel.unsubscribe();
    });
 
    return Formula(() => {
      const prefix = `[${channelName.read()}] `;
      if (lastMessage.current === null) {
        return `${prefix} No messages received yet`;
      } /*E1*/ else {
        return `${prefix} ${lastMessage.current}`;
      }
    });
  });
}

tsx
function ChannelResource(
  channelName: Reactive<string>,
): ResourceBlueprint<string> {
  return Resource(({ on }) => {
    const lastMessage = Cell(null as string | null);
 
    const channel = Channel.subscribe(channelName.read());
 
    channel.onMessage((message) => {
      lastMessage.set(message);
    });
 
    on.cleanup(() => {
      channel.unsubscribe();
    });
 
    return Formula(() => {
      const prefix = `[${channelName.read()}] `;
      if (lastMessage.current === null) {
        return `${prefix} No messages received yet`;
      } /*E1*/ else {
        return `${prefix} ${lastMessage.current}`;
      }
    });
  });
}

tsx
function ChannelResource(channelName) {
  return Resource(({ on }) => {
    const lastMessage = Cell(null);
 
    const channel = Channel.subscribe(channelName.read());
 
    channel.onMessage((message) => {
      lastMessage.set(message);
    });
 
    on.cleanup(() => {
      channel.unsubscribe();
    });
 
    return Formula(() => {
      const prefix = `[${channelName.read()}] `;
      if (lastMessage.current === null) {
        return `${prefix} No messages received yet`;
      } /*E1*/ else {
        return `${prefix} ${lastMessage.current}`;
      }
    });
  });
}

tsx
function ChannelResource(channelName) {
  return Resource(({ on }) => {
    const lastMessage = Cell(null);
 
    const channel = Channel.subscribe(channelName.read());
 
    channel.onMessage((message) => {
      lastMessage.set(message);
    });
 
    on.cleanup(() => {
      channel.unsubscribe();
    });
 
    return Formula(() => {
      const prefix = `[${channelName.read()}] `;
      if (lastMessage.current === null) {
        return `${prefix} No messages received yet`;
      } /*E1*/ else {
        return `${prefix} ${lastMessage.current}`;
      }
    });
  });
}

ChannelResource is a JavaScript function that takes the channel name as a reactive input and returns a resource constructor.

That resource constructor starts by subscribing to the current value of the channelName, and then telling starbeam to unsubscribe from the channel when the resource is cleaned up.

It then creates a cell that holds the last message it received on the channel, and returns a function that returns that message as a formatted string (or a helpful message if the channel hasn't received any messages yet).

At this point, let's take a look at the dependencies:

Our output depends on the channel name and the last message received on that channel. The lastMessage depends on the channel name as well, and whenever the channel name changes, the resource is cleaned up and the channel is unsubscribed.

If we receive a new message, the lastMessage cell is set to the new message. This invalidates lastMessage and therefore the output as well.

However, this does not invalidate the resource itself, so the channel subscription remains active.

On the other hand, if we change the channelName, that invalidates the ChannelResource itself.

As a result, the resource will be cleaned up and the channel unsubscribed. After that, the resource will be re-created from the new channelName, and the process will continue.