1. Introduction to Deno and Custom JavaScript Runtime
Hi, folks. I'm Bartek from the Deno team. We'll talk about creating a custom JavaScript runtime, based on our experience with Run.js. Deano is a JavaScript and TypeScript runtime, similar to Node.js. It supports importing source codes, transpiling TypeScript, and has a lot of tooling. Deano also provides support for many web APIs.
Hi, folks. My name is Bartek, and I'm from the Deno team, and welcome to your own JavaScript runtime. Shortly about me. I started contributing to Deno in 2018, and then I've become the employee of the company in late 2019, and I've been with the company ever since. I'm currently leading the Deno CLI team, and should you have any questions or follow-ups, feel free to reach out with one of the links provided here.
So, in this talk, we're going to talk a bit how to create or roll your own custom JavaScript runtime. We're not going to be doing this from scratch. This talk is based on a couple of blog posts we did in the past. We created a small JavaScript runtime called Run.js, and you can follow the links and the recording here if you want to learn a bit more about the history of the project. Well, in our opinion, it's quite easy to get started if you wanted to create your own JavaScript runtime. Thanks to the technologies we can now use, which are the engine for executing JavaScript, but also some of the infrastructure the Deano team provides. So, without a further ado, let's jump right into it.
But before we do that, we need to learn a bit more about Deano itself. So, Deano is a JavaScript and TypeScript runtime. It aims to be fun and productive to use. Deano supports importing source codes from a file system, from remote servers, using HTTP or HTTPS protocol, and we also support NPM imports using these NPM column specifiers. Deano is a TypeScript runtime in a sense that it's not needed to explicitly build your TypeScript sources to JavaScript before executing them. Deano can take care of that for you. It can transpile the sources, but it also can type check them. And Deano is built using Rust and using the JavaScript engine, so in one sense it's very similar to Node.js because we both use the same JavaScript engine. However, Deano uses Rust for its native code while Node.js uses C++.
Deano comes with batteries included. We got a lot of tooling that allows you to get up and running in seconds. You got Formatter, TestRunner, Linter. You can even create a self-contained binary, that is you'll package all of the source code you provide and then give you a single executable file. It's kind of similar to the PKG MPM package you can use. Deano is also very heavily invested in web APIs. We've got a lot of them, most notably Fetch, TextEncoder, TextDecoder, Blob. We got support for WebStreams API as well as WebWorker API. There's many, many more of these APIs and I strongly suggest you visit the MDM page for the API you're interested in and see if Deano supports the API.
2. Deano in Rust: Building Custom Runtimes
Deano in Rust was a significant decision for the project, as it allowed for quick development and leveraged a vast ecosystem of high-quality crates. Building Deano is easy with Cargo integration, and pre-built binary archives save time. Rust's crate system enables modular code organization, and Deano offers two runtimes: CLI for local development and Deano deploy for cloud deployment. Users can mix and match crates and APIs to create custom runtimes. The run.js example runtime already supports ES modules, transpilation, file I/O, console APIs, and a basic fetch API.
Deano in Rust is, well, we need to understand a bit of history here in that the first iteration of Deano, the first prototype was not really written in Rust. Instead, it was written in Go. However, due to the nature of Go that is garbage collected just like JavaScript, it was decided that we should go away from Go so we don't run into a situation where two garbage collectors are contesting against each other.
So Deano was written in Rust, which is a low level language, or system's language that doesn't have a garbage collector. And I can say that this is probably the most influential decision ever made for the Deano project. Rust allows us to move very quickly and it allows us to leverage a huge ecosystem of the crates available. Most of the crates are very high quality, for example, an http crate that implements the http protocol is very well tested and it has a great coverage, so we're very confident using it that we will be adhering to the defined protocol.
And last but not least, building Deano is really a breeze. Since Deano is fully integrated with Cargo, which is Rust's build tool or build system, it's just one command to run that will build your whole Deano binary, including V8, but not really. We don't force you to build V8 yourself, instead we do that in our CI pipeline so that you can use already pre-built binary archives, which saves you a lot of hassle, since V8 is a huge project that takes quite a long time to compile. Another thing is that Deano is not a monolith. Rust provides you with an easy way to factor out pieces of your code to so-called crates. Crates are the equivalent of npm packages so these are self-contained and reusable libraries that you can download and use whenever you want and Deano, the CLI that you can download, is actually a collection of these crates that is intertwined together and they are made to work together very well. So one of the consequences is that we actually, at Deano here at Deano company, we don't actually ship just one runtime. We actually ship two different runtimes. We have the Deano CLI but we also have Deano deploy which is our cloud offering. These runtimes are very similar however they are not identical. Deano CLI is geared towards local development and deploying your code on your own server or Lambdas while Deano deploy is geared towards being deployed to cloud native containers and such. So as a consequence you as a user can choose which crates and APIs you need and then you can mix and match them to roll your own runtime that fits your needs. So back to our runjs example runtime. What can it do right now? Well, it's just 140 lines of Rust and 37 lines of JavaScript so that's not very, very much code but it already has support for ES modules. It can transpile JavaScript to typescript on the fly just before executions similar to how Deno can do it. We got an API to read a file, an API to write a file, and delete a file. We got some rudimentary console APIs so we can do console.log and console.error and we have a very basic fetch API, so it looks like fetch but it can only really do get requests. However, with only 180 lines of both Rust and JavaScript, I think this is pretty phenomenal. So let me give you a super quick demo of the run.js runtime. So I am in the repository that was already linked to you and we can do cargo.run dash dash example.ts. So we'll be executing a typescript file right here and we got hello run.js as well content from fetch. So if we decide to inspect our example.ts file, we can see that it uses console.log, then we got an interface. So that's definitely typescript.
3. Implementing a setTimeout API in runJS
And then we do await run.js.fetches. So we're also using top level await here. Why would you want to use your own JavaScript runtime? There are a few use cases. First, running untrusted code. You might want a limited set of APIs. On the other hand, you will use much less resources. Second, being resource constrained. Dno ships with batteries included, but you might not need every API. Lastly, your project could benefit from shipping a self-contained single binary. Let's do some coding. Implementing a setTimeout API in runJS.
And then we do await run.js.fetches. So we're also using top level await here. And sorry for the squeaky mice, but it seems my VS code setup doesn't understand it here.
All right. So let's jump into some actual interesting things. So why would you want to use your own JavaScript runtime? So there are a few use cases. First of them is running untrusted code. So you might not believe us shipping Dno that it's totally safe to run untrusted code. So you might want to run it inside that container. However, now you've got a JavaScript runtime and then a container. So there's a bit of slowdown you can expect and resource utilization from doing this double wrapping or double sandboxing. Because remember V8, the JavaScript engine is already a pretty good sandbox. So you might want a limited set of APIs.
But on the other hand, you will use much less resources, which leads us to the second point that you might be resource constrained. So Dno ships with batteries included. We got a lot of tooling in the CLI, but sometimes that binary might be too heavy for you, or you might not need every API that we provide. And we provide many of them. You can interact with file system. You can do networking. There's a huge implementation of various web APIs. But if you don't need them, maybe you can just use a subset of them, resulting in a smaller and slimmer binary. Or lastly, maybe your project could benefit from essentially shipping a self-contained single binary. You can already do this with Dino, but sometimes you maybe want to customize it a bit more or again, remove some of the fat that is not needed in your particular use case. Right here, I linked you to a project of mine, a site project, where I tried to wrap ESLint into a binary file that uses the same technologies we're going to be using in this example.
Okay, so let's actually do some coding. Let's do something a bit exciting. I think we may try to implement a setTimeout API and runJS. Of course, this will not be the same setTimeout API you can see in browsers or in Dino or in Node.js, because while this API is really easy to grasp and use, there are a lot of intricacies to it. What I want to do is essentially implement setTimeout in a way that will take a delay in milliseconds. It will take a callback and then just fire this callback.
4. Implementing setTimeout in Runtime.js
But we will skip validation and jump right into the code. We need to implement the setTimeout function ourselves since it's not built into the JavaScript engine. In the Runtime.js file, we assign the console object and the run.js API. Now, let's add the globaldisk.settimeout API, which accepts a callback and a delay in milliseconds. We'll call an async function in Rust to wait for the given delay and then fire the callback.
But we will skip validation, ensuring that everything is property-adhering to WebIDL and so forth and so on. All right. So, let's jump right into the code. I'm going back to my VS Code.
So, let's start by removing this example and let's try to do setTimeout, and I'm going to do I'll make this bigger for you. I'll do hello world from timeout. And I want this to fire after a second. So, the delay we pass is a millisecond. So, thousand milliseconds is a second, and now, if we try to execute this code again, and let me make this bigger for you again. So, we executed our example.ts and got a reference error. SetTimeout is not defined. Well, this is expected. SetTimeout is not built into the JavaScript engine. Instead, it's a web API, or a built-in API in Node.js. But we don't have it here. We need to implement it ourselves. So, let's do just that.
I'm going to drop into the Runtime.js file, which is a file in which we implement all the APIs available in our Run.js example. So, as you can see here, we are assigning to globaldisk.console a console object, which oops, I don't want to see the typing, I want to see the actual object. Our console object has log and error function, and then we're assigning globaldisk.runjs with run.js, which contains the four APIs we already talked about. So, let's add another one. This time it's going to be globaldisk.settimeout. And our settimeout needs to accept two parameters. The first one is the callback, and the second one is the delay in milliseconds. So, how are we going to do that? Well, copilot is jumping the gun here, but that's not exactly what we'll do. We need to call into Rust to do something that will wait for the given delay, and only when we've finished waiting we will fire out the callback. So, let's start by adding, by calling car of async, and we'll call it offsetTimeout. Then we'll do delay as a first argument. That seems reasonable. And then we want to fire the callback.
5. Fixing the Undefined Function Error
So, if we just try to run it now, we get an error saying that ops name is not a function. Let's fix it by defining the function in the main.rs file, which implements our runtime.
So, yeah, that's pretty much it. Okay. So, what will happen if we just try to run it now? Oh, no. A typer. It says ops name is not a function. Well, that is expected. So, we just try to call a random function from JavaScript, and this function is supposed to be defined in Rust. However, we haven't defined anything yet. So, let's fix it right now. I'm just going to copy the name of this function, and I'm going to go to the main.rs file. This is the file that actually implements our whole runtime. As I told you earlier, this whole file is just 140 something lines.
6. Implementing the Opposite Timeout Function
We define the op attribute and implement the opposite timeout function using fast grades and Tokyo. We create a duration from the given delay in milliseconds and asynchronously wait for it. After registering the function with our extension, we successfully wait for a second and print to the console.
So, if we scroll to the top, we can see that we got an async function that is op write file. Then we got op fetch, op remove file, and op read file. These are the four functions that were also defined in our JavaScript runtime code. So, you got read file here, write file here, remove file, and fetch.
Let's just use one of them as an example to provide our opposite timeout. I'm going to start with defining the op attribute. The op attribute is coming from Deno. So, this is something we provided for you. Our opposite timeout will return a result. This will be just identity, and then return any error, but we don't really need this error here, but let's just keep it. So, the return value will be okay, and now let's actually do the fun part.
We need to somehow sleep for given delay, which I haven't passed here yet. So, we get delay, which will be U64, and now I'm going to leverage the fantastic ecosystem of fast grades to actually asynchronously wait for the given delay. So, I'm going to use Tokyo for that, which we already used in another API. So, I'm going to use Tokyo, time, delay, sleep, and now I need to pass a duration. Duration comes from STD time duration, and now I need to create it from milliseconds. Sure. Whoops, seems like my IntelliSense is acting up. So, we're going to sleep for a duration taken from the delay variable defined in milliseconds, and then we're just going to await it. So, will this actually be enough? Oh, sure. We don't need to use a question mark here.
So, we defined this in JavaScript. We defined this in Rust. Will it work now? Let's try. Oh, no. It's still not working. Well, even though we created this function, we haven't really told our genocrates to use it, so we need to register it here with our extension, and I'm just going to say OPSET TIMEOUT DECU, and run it again. There we go. We just waited for a second, and we printed something out to a console. That's pretty awesome.
7. Creating a Basic SET TIMEOUT Implementation
Here we have a basic implementation of SET TIMEOUT using RAST code and JavaScript. This knowledge can help you add more APIs, like creating a plugin system for your game server. Deno provides infrastructure for implementing web APIs, file systems, and networking, allowing you to tailor it to your needs. The possibilities of what you can create are endless. Stay tuned for future blog posts and recordings on rolling your own runtime with more features. All the source code will be available in the repository. Feel free to reach out with any questions. Thank you for joining!
What do we have here? One, two, three, four, five, six lines of RAST code, and then we got another three lines of JavaScript. So, yeah, here we got SET TIMEOUT, a very basic implementation of SET TIMEOUT working.
Let's jump right back into the presentation. Yeah, so we created a minimal SET TIMEOUT. I think this knowledge, even though it's very minimal and it only took us a few minutes, should be enough for you to be able to keep adding more APIs that you might need. So maybe you'd like to create a plugin system for your game server and JavaScript. You can use Deno's crate like we saw in this run.js example, and add some more Ops to provide the plugin system. The thing is that Deno, even though it's JavaScript and TypeScript runtime, we also give you a lot of infrastructure if you want to drop to a lower level and do something that is really tailored for your needs, so you can use the same infrastructure we used to implement web APIs or file systems or networking, but you can pick just some of them that fit your needs.
And to be honest, the possibilities of what you create with this infrastructure and writing out more on your own is just endless. You're limited by your own imagination here. We're going to keep doing these blog posts and recordings for how you can roll your own runtime with more and more features in the future, so please stay tuned for the next part. And that's it from me. I'm sorry that it was so short and I had to speed run through it, but I hope you found it interesting. All of the source code, all the nine lines that we did here will be available at this repository, so please drop by and visit it. And again, if you have any questions, I'll be more than happy to answer them. Shoot me an email or send me a DM over Twitter, and make sure to visit our website. Thank you for having me here, and I hope you enjoyed this talk.
Comments