Imports

[00:00:00]
>> We've now learned how to export functions from assembly scripts to TypeScript into JavaScript, and then we called it here. We can go the other way too. We can import functions into our assembly scripts. This is where it gets a little bit more tricky. And I know I've been saying that the entire course like, this is gonna get a little more complicated, this is gonna get a little more complicated.

[00:00:24]
Yeah, this is totally iterative. We are building step by step by step. So by the end, we will have something that is gonna look a little complex but we're gonna understand everything that we're doing here. So I am now in the Working repo, I'm now in 3. So if something went terribly wrong and you're having issues, you're getting the bad magic number error, things like that, you can just go to this repo error and you'll be exactly where I am.

[00:00:57]
We're gonna talk about custom imports, but for now we're gonna do a few built in imports. One of the more useful function imports we want to call in our assembly script is the abort function. The abort function allows us to terminate execution if something has gone terribly wrong.

[00:01:16]
Which it shouldn't for this course, but it's really useful to know. So let's go back to our -1 and let's add an abort if a certain number is passed, and just we'll call abort. So I'm jumping back. I'm gonna close all these other files since I will get confused.

[00:01:38]
Close you. And so now I'm back in our assembly directory in index.ts. So now I can say if n = Else this should be equals 44. And we're just gonna call abort on that. Then we save it. And we're gonna stop that server. Actually what I'm gonna do now, NPM run, I'm gonna run, so I opened a new terminal.

[00:02:16]
And I'm just gonna run the server in the background because I hate to keep stopping and starting and we will keep jumping back to the terminal. So now, in case you get confused later, there is another terminal and the server is running in the background. Okay, and let's just verify that localhost 3000, still working, cool.

[00:02:34]
Next we need to compile our assembly script to function again. So NPM run sbuild. Okay? So jumping back, so that means if we call 44 it should throw an error. So we're passing 44 here. Let's see if that works. Hey it did. Actually no, it didn't work. Aah.

[00:03:04]
So, assembly script has the concept of built in functions. But to use those functions, we have to use that assembly script loader. Remember earlier in the steps when we imported that for saving dev, where we import it as save dev the assemble script loader separately from the assembly script library itself.

[00:03:25]
The loader is a tiny utility function that wraps glue code that does some of the heavy lifting for us. So the abort function is built into the loader, but unfortunately, we're not using the loader right now, we're gonna use it in the next step. But for now, we can pass our own custom version of aborts.

[00:03:45]
So we can make it do whatever we want. The abort function is just a JavaScript call that has no specific meaning to WebAssembly itself. It only knows that it's an important function, when we call it, it reaches back out to JavaScript to execute that. So let's create an abort function that, what do we want to do?

[00:04:04]
We want it to throw an error, because that's what we're doing. We want it to throw so it'll pause execution of our program, all right? So let's go and do that. So I'm going to refer back to my notes now. A word on imports. So imports are the second argument to instantiate streaming and instantiate.

[00:04:33]
The first one they take is the actual WebAssembly module itself. But it also takes this idea of imports. That is the imported functions into WebAssembly that we're gonna call, because it's a two way street. You can call a function from WebAssembly, you can call functions from JavaScript as well.

[00:04:52]
But to do that, we need to define them and then pass them in. So we're gonna do that with the imports object, and it's gonna look something like this. So, let's code that up. So I'm gonna go into, our loader file again. And we're gonna make use of this constructor.

[00:05:12]
So I'm gonna say this underscore imports equals an object. And we're gonna call this inf, which I'll explain why in a second. And that itself is an object, and within the object, we're gonna find the abort function. And so right now we're designing the functionality that we want to happen in WebAssembly when this function is called.

[00:05:38]
So in this case, I wanna throw a new error that's gonna say, abort called from, WASM file. Okay, that's fine. But we still need to actually pass those imports into that compile time when we compile and instantiate our WebAssembly code. So I'm gonna add a second argument to our WASM, let me say by default we're gonna get our own imports, but we're gonna use this default value for now.

[00:06:22]
And then I'm gonna take those imports, and I'm gonna pass them both to the WASM fallback. And as the second argument through instantiate streaming. And then we're gonna do the same thing for the WASM fallback, and we're gonna pass it in and instantiate. So, this is colloquially known as the imports object, I like to call it imports, but you'll see referred to as imports object, because it's an object containing all of the functions that we're gonna import into our code.

[00:06:53]
So now, because we're not actually touching the assembly script, this is just the glue code, we don't need to recompile. Let's go ahead and try our code again and see if that works. And it did work. And if we want to get specific, I'm gonna go to sources and I can say pause on exceptions.

[00:07:17]
And now it's gonna pause because it's being called in our WebAssembly.