Skip to content

Resources

Resources are the main way to connect Starbeam to external input data.

If you're used to using effects to connect external inputs in other frameworks, resources serve a similar purpose. The primary difference is that resources expose reactive data, just like FormulaFn.

The author of a resource sets up an imperative subscription, defines the cleanup logic for the subscription, and returns a function that computes the current value of the resource.

As the resource modifies its internal cells, the value of the resource is always up to date with the result of the computation.

tsx
import { Cell, Resource } from "@starbeam/core";
 
const Stopwatch = Resource((resource) => {
const start = Cell(new Date());
 
resource.on.setup(() => {
const interval = setInterval(() => {
start.set(new Date());
}, 1000);
 
return () => {
clearInterval(interval);
};
});
 
return () => start.current;
});
tsx
import { Cell, Resource } from "@starbeam/core";
 
const Stopwatch = Resource((resource) => {
const start = Cell(new Date());
 
resource.on.setup(() => {
const interval = setInterval(() => {
start.set(new Date());
}, 1000);
 
return () => {
clearInterval(interval);
};
});
 
return () => start.current;
});

Resources are defined in terms of Starbeam APIs, and then wired into applications through renderers.

For example, you could use the stopwatch in the above example in React by using the useResource hook from @starbeam/react.

tsx
import { useResource } from "@starbeam/react";
 
function TickingClock() {
const now = useResource(() => Stopwatch);
 
return <p>{now.toLocaleTimeString()}</p>;
}
tsx
import { useResource } from "@starbeam/react";
 
function TickingClock() {
const now = useResource(() => Stopwatch);
 
return <p>{now.toLocaleTimeString()}</p>;
}

Resource

T

The type of value that the resource represents.

Constructor Function

function Resource(blueprint, description?): ResourceBlueprint;

The Resource function returns a ResourceBlueprint, which is an unlinked resource. You call create() on the blueprint with an owner to instantiate the resource and link its lifetime to the specified owner object.

blueprint(create: ResourceBuilder) => () => T

A function that sets up a resource and returns a function that computes the current value of the resource.

description?string

A description of the resource.

optional

returnsResourceBlueprint

Properties

current

readonly current: T;

The current value of the resource.

ResourceBlueprint

bolt Methods

create

create(options): Resource;
options{ owner: object }

the owner to link the resource to.

returnsResource

A resource that computes the given value.

ResourceBuilder

bolt Methods

on.setup

on.setup(setup, description?): Unsubscribe;
setup() => () => void

A reactive setup function.

description?string

A description of the setup logic.

optional

returnsUnsubscribe

An unsubscribe function that can be used to stop the setup function from being called again.

Released under the MIT license