Announcing Starbeam: Universal Reactivity

Hi, everybody. Today I'm here to talk to you about Starbeam. Starbeam is a library for building reactive user interfaces based on the guiding principle that if you write your reactive code just like any other code, you can build a radically simpler, more reliable user interfaces with the JavaScript skills you already have.

Now, people have said a lot of similar things like that before, so I don't blame you for being skeptical and jaded. Before I get started, I want to be really clear about something. Starbeam is not the next hot new JavaScript framework. The demo I'm doing today uses Starbeam inside a React app, and we have similar examples in Svelte, Vue, and Ember. The people who work with me on Starbeam are pretty tired of the way that new front-end ideas are always packaged up with a whole new framework you need to migrate to. We think we can do better, and I hope that by the time I'm done here, I'll have piqued your interest.

Let's start by taking a look at what the app that we're going to be building looks like. Here's the finished app. So we have a form we can create some new users. I can write leah-silver-portland. I can append it. As you can see, once I have appended it, there is some information on the bottom about what happened. I can filter. I can write portland...here. And when I do that, you see that this changes to say two filtered out of five. I can delete items while I'm filtered. Everything works as you would expect. I can delete all the items. I can add people back in. Like that. And that's about it. That's basically what this app does.

Well, the very first thing I want to do is change to using the non-finished version of the demo. So let's start there.

Okay, great. And as you can see, there's some features here already, but nothing, there's no filters. There's nothing that made it very interesting. And more importantly, nothing works here.

Before we get started, let's take a look at the data that backs our component. Now it's a little bit of an involved JavaScript thing here, but the reason it's involved is less that Starbeam cares that you do anything interesting here and more that I want to show that even if you use pretty advanced fancy JavaScript features, everything still continues to work.

So let's take a look at the first piece of this, which is the table. So a table has an ID which starts at zero and that's what we can allocate IDs as we create new rows. We have a list of rows, which is a map from a string to a row. Now what's a row? Well, here we have an example of a person. So a person has a name, which is a string, a location, which is a string, and all a row is is that thing plus an ID added to it. So we're going to map from the ID to a row of a person, in this case, and that means it's going to be the person plus an ID. We're going to take a bunch of columns so that we have a way of reflectively creating headers. We're going to have a getter for rows. So what does the getter for rows do? It gets the values out of our map and splats it onto an array. This gives us an array back. How do we append a row? Well, we make a new ID as a string and then we make a new object that contains the ID and the columns that we specified, and then we set the string ID onto the map and give it the row as the value, return the row, pretty vanilla stuff. How do we delete an ID? Well, we delete it from the row. How do we clear rows? We clear the map. And then there's one additional feature here, which we're going to use to implement filtering, which is the query feature. So what is query? A query is another very simple object. A query has a table that backs it, and then it has a bunch of filters and an optional sort. What's a filter? It's a thing that takes a row and gives back a Boolean. What's a sort? It's a thing that takes two rows and gives you back a number, which is what the compare functions do. Okay, now what happens if you ask for a list of rows from a query? Well, the first thing that happens is that we get the rows from the table, and as a reminder, that does this splatting thing. Then, we loop through all the rows and we make sure that all the filters match the row. And then if we have a sort, we sort the filtered things by the sort, otherwise we just return the array. So basically it's a little object, wraps a table, has some filters, and gives us back new rows.

Okay. So, that's the table, that's the query. And then we have a little people class. So what is a people? Well, it has a table of person, it has a query of person. And then what happens, if you get the table it gives you back the table. If you get the rows for people, it gives you back the query's rows. And then there's two convenience methods for adding sorting and filtering.

Let's look at filter first. So you can filter based on text. What it does is it takes the existing query, it adds a filter to it that checks if the row's name includes text or the row's location includes text, and then it returns a new people object with the table and the query. Then, what does the sort method do? It takes a column, so that would be a name or location, and then it takes a locale. The reason it takes a locale is because we're going to want to use the Intel API to sort things so that we get the right behavior for different languages. And this looks like a lot of things are going on here, but really all that's going on is we're making a new collator for the locale that we passed in, and then we're giving query a sort, which is going to get the values out of the column. So let's say we're sorting by name, so we're going to get the name out, and then we're going to use the collator from intel.collator to compare, and it gives back a new people so that when we go to get the rows, it does the right thing.

Now, here's the most important thing. You didn't have to follow necessarily all of that, but the thing to note is that there's no reactive concepts in here. This is just an object. Locale is just a string. There's nothing about hooks. There's nothing about needing to run something multiple times. There's no special kind of objects that you need. There's no piping. There is one place that we've seen so far where we have a reactive object, which is right here, this reactive map. But other than that, all we've seen so far is just functions that work with that, ultimately that underlying map and produce new values. Okay, so that's basically how the data works under the hood. And now what we're going to do is we're going to go look at our app. So we replaced the app already with the unfinished data table, and now let's take a look at the component. So, the first thing that you're going to notice here is that we have this useStarBeam hook and useStarBeam basically wraps your entire component, and its job is just to get you into StarBeam mode so you can access and work with all of the reactive data. Now, inside of StarBeam, inside of a useStarBeam component, there's two sections. There's the top section, everything up until the point where you return this JSX chunk.

So the top part of a useStarBeam function runs exactly one time, and it's a good place to set up stuff like this table that you only want to set up one time or functions that you don't want to have changing under you. And the bottom part, this callback, this chunk of JSX, that's the thing that runs over and over so that React has JSX to reconcile. But the critical thing here is that StarBeam makes sure that it doesn't rerun if none of the dependencies, the reactive dependencies that are used inside of the callback run. And we'll see what that means in a minute. You can sort of think of it as a React.Memo on steroids.

So let's take a look at the actual implementation here. So we have a JSX. We have this form here. And you'll see if you run the form, you can see that the form doesn't really work. Right? Because if we look at what the append function does, it doesn't do anything. So we'll take a look at that form in a second.

Then we loop over all the columns on the table. And, just remember, the columns are just a field that's on the table. And we turn them into THs. And then we have one last TH here that gives you the ability to clear all the rows. And that's what happens if I clear all the rows. We'll talk about that in a second.

Then I loop through all the rows that I have. And for each one, I make a TR. I give it the key of the ID that we created. And then I give it TDs for the person and the name and the location. And then I have one final action here which allows me to delete the person.id. Now I just want to reiterate, when you click on, when you look at clear, that's just doing rows.clear. When I do Table.deletePersonId, that's just doing rows.deleteId. So even though these are callback functions that are happening inside of here, they're happening inside of JSX, you didn't have to do anything fancy here. They're working with StarBeam data. OK.

And then finally, we have this summary section over here. And the summary section has a data items attribute of the length. And that's basically so that when there's zero of them, there's some CSS that makes it look different. And then we have a TD, which prints out the total. And what is the total? Right now, it's very simple. It just says items, colon, Table.rows.length. OK, cool. Now, what I want to quickly look at here is, so we already have some interesting data here, right? If I reload and I start deleting things, you can see that there's already items 2 here.

You can see that the array got filtered and stuff like that, right? And so how did that happen? What exactly happened here? So notice that we don't have any kind of useState. We don't have any dependency arrays. We're not using React concepts really at all. So how does that work? So the way it works is that if we go back and look at our table, like I said, there's this little piece of reactive state here. And when you get the rows of the table, it gets this.rows.values. And StarBeam knows that when you do this.rows.values, that means that you are reading the iteration of the whole map. And that means that whenever anything changes the iteration of the whole map, that will invalidate the read of this.rows.values.

But the thing is, we don't actually use the table rows directly most of the time. What we mostly do is use it through other abstractions. And we'll see that's going to get more and more elaborate over time. And so the point is that it doesn't matter if we specifically use people.rows here, or if we use it through something else. The fact that we access the data that is inside of people.rows somehow. So people.rows, just as a reminder, is not actually directly... It's not the table, it goes to the query. And the query, as a reminder, goes to the filter, right? So there's actually a lot of steps in between what looks like, oh, it's just the rows, and that piece of state. But you don't have to say anything about that. You're able to just write normal JavaScript code here.

Okay, so that's great and all. And what that basically means is that when you say table.deletePerson.id, Starbeam knows that this people.rows.length invalidated, and therefore knows to re-render the template. Not the template, the JSX. So what's the next thing we want to do? Well, we have a non-working form here in this append, so let's go and implement it. So the thing we have right now is we just have e.preventDefault. Let's take a quick look at the form. So we have a form here, and it has an OnSubmit. And then we have inputType="text", name="name". So we're using the HTML way of giving it a name. We're saying it's required. There's some CSS stuff here for errors. And the second input field has the name of a location. We have a buttonType="submit", right? So that just means that when we hit Enter, we hit Tab and Space, we click whatever it's going to hit, it's going to call the Submit.

So what do we want to do with that? Well, the first thing we need to do is get the form out of the event. And the second thing we're going to do is we're going to make a new form data out of the form. Now, if you don't know what a form data is, it's pretty interesting. What it basically does is it takes the form, it gets all the names of fields that are valid, in other words non-disabled fields and stuff like that, and it turns it into an object that has those keys and those values. And what's really cool about form data is that it implements iterable of entries. So you can just say object.fromEntries of a form data, and you get back something that looks exactly like what you would expect. It's a little bit of incantations here, but we take a form, we make a form data, we do object.fromEntries, and we get back this. We get back an object that has a name and location, which is precisely what we want. Our table has an append on it. The append takes columns, which is the name and location. And when we're done with that, we're going to reset the form so it empties out what we already did. So at this point, we would kind of expect it to work, I think. So let's check. I'm going to add Lea-Silber, and I'm going to add Portland, and it worked. Great. So why did that work? What exactly happened here? So what basically happened is that when we clicked on table.append, that set a row on the map here. And because other parts of that same component read from, ultimately, the this.rows.values over here, which is in iteration, the fact that we added something to the map means that it invalidated anybody who tried to read, anybody who cared about the iteration, right? In other words, because I cared about, because at some point I computed a list of all the keys and the values, if the keys and values change, then anybody who read the list of keys needs to recompute, right? So the fact that I called append, it looks like, you know, I'm just mutating an object, Behind the scenes, Starbeam keeps track of every read, every write, and links them up together. Cool.

Okay, so now that we did that, the next thing we probably want to do is implement the filter. So in order to implement the filter, we're going to need a cell. So a cell in Starbeam is just a very simple object that is a space for storing one thing, right? So we have a cell here, and it's a space for storing a string because the filter is gonna have a string in it.

We're gonna want to make another field here that's just gonna be our filter. So what does that field look like? Well, it's going to have a default value of the current filter.current, and so filter.current is reading from that cell, right? So that's a thing, it's a reactive thing, it's reading from the cell. And what happens when you type something in? No problem, we set the filter, so filter.set is how you modify a cell with the value of the current target, right? So now, if I type something, I was able to type in the filter, but we didn't do anything yet, so we still need to do something here.

So in order to make it useful, we don't want to just make the rows just a bunch of rows, we want to make a query, right? So what's gonna be the query? The query is gonna be the people table that we have, and we're gonna use that filter function that we wrote before to filter based on filter dot current. Now note, just accessing filter dot current in here is enough to know that we're accessing the underlying filter. So we have a function here called query, it's a regular function, nothing special here, and we're making a new query, which filters by the thing we typed here, and we're also gonna sort by the locale for good measure.

Okay, so now that we did that, we're just gonna update the rows here to return the queries rows instead of the tables rows. And now if I type something, Portland, Yehuda, right, if I type Sherag, if I type NYC, right, all that worked. And so why did that work? Well, part of why it worked is that the filter does this somewhat complicated thing, right, it goes and for each row, it checks if the name or location includes the text. And when we said query.rows, that's the thing that actually went ahead and ran the filter, right? So again, this is just pretty normal JavaScript code. And all we did was make a new function here called query. And all we did was make our existing function rows use the query. But the fact that this code down here, the code that loops over says rows, the fact that that accessed the query, what does that mean? It means that it has a dependency on two things. It has a dependency on this filter thing. And it also has a dependency on this rows thing, which has a dependency ultimately on the table rows, which is this iteration. So basically, just the normal way of accessing, the normal way of writing code here means that our computation of rows here caused StarBeam to know that this whole component depends both on the filter and it also depends on the rows.

Okay, so one thing that I think is worth noting here is that there's surprisingly a few pieces of root state here for a pretty complicated setup. So we're going to add one more feature here and what we're going to do is we're going to make it so that if we filtered something, we want this to not say items for, we want it to say items some amount of filtered over for, right? So how are we going to do that? We're just going to replace this total function here. The first thing we're going to do is we're going to get our rows and that's going to be the amount of rows that were in the query, right? And the second thing we're going to do is we're going to get the total number of rows in the table. Now, if the two things are the same, the filter count and total count, we return what we had before. Otherwise, we say items filtered count filtered over total count total, right? So if we just reload the page, obviously nothing happened here. But if we start filtering, we say Gerog, we say NYC, we can see it worked. And once again, this total function has a dependency on rows. It has a dependency on table.rows, right? It has a dependency. And what does rows have a dependency? It has a dependency on the query, which has a dependency on the filter. So all this is just a pretty natural way of writing normal code without having to write anything special, without having to say anything special about how things are connected to each other. And it all sort of works out.

Okay. Now, I keep saying things are dependencies of other things. But you sort of have to imagine that. But let me show you a little debugging tool that we have that lets you see it more explicitly. And to turn it on, we're just going to grab the logger from starbeam. We're going to grab the logger from starbeam debug. Debug. We're going to say logger.level equals loglevel.debug. Debug.

Okay. And now once we do that, if we open up the dev tools, we see that we're starting to get some additional information. It's showing us that this use starbeam block, which is located over here. Let's pull that down. You can see exactly where it's located. It tells you that that has a dependency on this cell, has dependency on this map. I'll make it a bit smaller.

Okay. Now, the next thing that we can do with this debugging tool is if we invalidate something. Let's say we go back to this filter here and we say see. What we're going to see is that it tells us that use starbeam invalidated and tells us exactly what invalidated, which is this cell here. It gives us a link to exactly this location. Now, this is a little bit noisy. Built into this setup is a way of saying for each new piece of root state, you can give it a name. Here we can say cell, we can give it a name of filter. And we can go to our table and we can say I already did it. I gave map a name table, right? And we can go to, I think those are the only pieces of state, right? So now if we look at it, we'll see that it gives us the names instead of the very long words. And if you wanted to turn it on and you wanna see the stack traces anyway, the longer links so you can click on them, you can just always turn it on to trace mode. And that will give you the links no matter what, right? So you open it up and you always have these links here, great. Let's turn that off, okay. Now we have one last feature that I wanna implement.

Which is so far, everything is self-contained inside of StarBeam. But like we said, this is inside of a React app. And so we really would like to be able to have this component take some arguments from React. So in this case what I wanna do, instead of just using the system locale as a sort, I wanna get the locale from the React app.

Okay, so in order to facilitate that, I created a locale switcher here. So we're just gonna implement it using a pretty normal React pattern, right. We're gonna use state. We're going to just gonna grab some stuff here. I'm gonna format the locale. But it's a select box, right. It sets the state. And now that we did that, if we turn it on over here, right. And we can see that we have the select box.

And what we would like to be able to do, is just pass the locale directly into our component. And of course, there's no reason why we wouldn't be able to do that. This is just a regular React component. So we can say props locale string here. But there's a bit of a problem here, which is that the way React works is it's just gonna keep calling this function over and over again with new props, but Starbeam doesn't really have any idea what that's about. And so we really need a way of turning this locale into something that Starbeam understands. And for this kind of situation, there's a hook that we provide called useProp. So we can say cons locale equals useProp props.locale. Okay, we're gonna pull in useProp from Starbeam React. And now all we gotta do here is we just have to change system locale to locale.current, right, so that just shim the React world into the Starbeam world.

And now here's why I set it up this way. So this unwanted word, name, is differently sorted in Swedish and other languages. So let's switch to Swedish real quick. And as you can see, it's now sorted at the bottom. Let's bring back up our dev tools. And now what we can see is that we actually have three pieces of state here. We have this cell, the filter cell.

We have the Prop and we have the Map that we've been talking about the whole time. And just like anything else, we can give this a name. So let's just call it props.locale for convenience in our debugging. All right, so now we can see, okay, we have those three things. And now if I go and select Swedish, you can see that that is exactly the thing that invalidated it, right? And if I was to instead type in like NYC or something like that, what we can see is that now we know the filter's the thing that invalidated it.

Now this is still a pretty early debugging tool. This is just a logging just for convenience. We would expect some more elaborate debugging tools eventually built on this infrastructure. But the basic idea here is that from StarBeam's perspective, this function over here has dependencies of just three things. Now one of the things the Map is a little bit of an elaborate thing so that we can do more granular tracking. But in general, there's only three pieces of root state. It doesn't matter that we have this total function, it doesn't matter that we have this rows function, it doesn't matter that when we go and look at this rows thing, it's doing this complicated going through multiple steps, it's doing this complicated filters thing, none of that matters. At the end of the day, the only thing StarBeam actually cares about is that it has a dependency on filter, it has a dependency on the props, it has a dependency on the Map. And whenever we go and change something, let's go create a new person, right? So let's make a new person, we'll make Leia again, and we'll say pdx, right? What you can see is that the thing that invalidated is the Map, right? So at the end of the day, even though there's a lot of complexity here in your code, that complexity is all in very standard, normal JavaScript stuff. And the reactivity is really just saying that this callback here, this thing that generates JSX, has a dependency on three things. It has a dependency on a Map, on the iteration of the Map. It has a dependency on a filter. And it has a dependency on the locale, the locale prop. And now all StarBeam has to do is keep track of those three things. Whenever they change, it invalidates and notifies React and invalidates.

The nice thing about this is that if you have a lot of components in your app that use StarBeam, each individual one doesn't invalidate any of the other ones. It's like I said, it's kind of like a souped up react.memo. So what happens is without you having to say anything, simply by accessing values using normal functions, using normal getters, using normal methods, using normal access patterns, you're telling StarBeam exactly what the dependencies are. And StarBeam is able to keep track of exactly when it needs to invalidate. You can shim into the React world pretty easily, too, if you need to, and that works totally fine.

Now, one thing that's pretty cool, I think that last thing I want to say here, is if you go back and look at our table, there's no actual imports from StarBeam React or from React, right? And that's because this code, this table code, this query code, this people code, this is all pure StarBeam stuff. And that means that this exact same code will work in Svelte, it will work in Vue, it will work in Ember, and that's pretty cool. It means you can start writing libraries that are kind of like this toy example, but bigger, something like a GraphQL library, and you can write it mostly in StarBeam, in StarBeam concepts, and then expose it to React, to Svelte, to Vue using these adaptors. You don't have to build universal code with StarBeam, you can just build stuff inside of the React app, but you also could build these universal libraries, and I'm pretty excited to see what's going to happen once the ecosystem has the ability to start writing reactive code in a way that's decoupled from individual frameworks. I think that's going to be really awesome. If you're excited by this, definitely come check it out. Come to our Discord, you can come to our GitHub, you can start, you can like it, you can submit issues, you can try to integrate it, you can try to do some work. You can try to help with debugging tools, there's so much stuff going on. I'm pretty excited about how far we already got, but there's still a ton left to do. And if you're the kind of person who likes getting in on the ground floor and making a run for something, great, join us, we're excited to have you. Thanks so much, and enjoy the rest of your conference.