Calling other packages
A module can call functions that other packages export, and export its own. Packages describe these functions in WIT, so this works across languages: an AssemblyScript module can call a Rust package, and the other way around.
Exporting
A package exports an interface in a WIT package named after itself: acme/weather exports acme:weather/api, for example. With the AssemblyScript SDK, every function index.ts exports, other than handle, becomes part of interface api, and so does every function in exports.ts:
// exports.ts
import { Result } from "@codetje/assemblyscript";
export class Forecast { city: string = ""; celsius: f64 = 0; }
export function getForecast(city: string): Result<Forecast, string> {
const f = new Forecast();
f.city = city;
f.celsius = 12;
return Result.ok<Forecast, string>(f);
}
The build needs to know the package and version it will be published as. The console's editor fills that in, and from the command line you pass it:
npx codetje-as build . -o build/weather.wasm --package acme/[email protected]
Names become kebab-case in WIT (getForecast is get-forecast). Don't export helpers from index.ts: once published, they're part of the interface others rely on. A module can be only a provider, with no handle, in which case it has no URL.
Importing
Import from the package by its name:
import { getForecast } from "acme/weather";
const forecast = getForecast("Delft");
if (forecast.isOk) println(forecast.value.city);
The build fetches the package's WIT from the registry and generates bindings for it. A package that exports more than api is imported by interface, as acme/weather/<interface>.
To import a private package of your own, the build needs a token: set CODETJE_TOKEN to an access token. The console's editor uses your session.
Versions
codetje.lock, next toindex.ts, records the version of each package the build used, like{"acme/weather": "0.1.0"}, so a rebuild gives the same bytes. A package that isn't in it gets its newest version, which is then added. Change or delete an entry to move to a newer one.- At publish, the registry picks the newest version of each import that's compatible with the one you built against, and pins it by digest. Compatible means the same major version, the same minor for
0.x, and exactly the same for0.0.x. Pre-releases count only if you built against one.rt publish --dep acme/[email protected]pins an exact version instead. - At run time, the runner runs exactly what was pinned, and never looks for newer versions. To pick up a new release of a provider, publish a new version of your module.
A provider's releases must stay compatible within a line: a new 0.1.x must keep every function the previous one had, with the same types. A breaking change needs a new line, like 0.2.0.
Who can import what
- Packages in your own namespace can import each other right away, public or not.
- Another namespace's package must be public and importable when you publish, and public every time yours runs. If its owner makes it private, your package gets a 403 until you publish without it.
How providers run
Each provider runs in its own instance, created on the first call during a request and thrown away with your module's. Calls within one request share that instance; nothing survives between requests.
It runs with the env and fetch origins you set for it (see Imports), never its owner's, and with none if you've set nothing. Its output goes to your logs. It shares your request's memory, CPU and time budget. If it traps, your request fails with a message naming the package, and the reason goes to your logs.
Imports go at most 4 levels deep, with at most 8 instances in all.
Types
| WIT | AssemblyScript |
|---|---|
bool, s8…s64, u8…u64, f32, f64 |
bool, i8…i64, u8…u64, f32, f64 |
string |
string |
list<T> |
Array<T> |
option<T> |
T | null, or Some<T> | null when T is a number or bool |
result<T, E> |
Result<T, E> |
record |
a class |
Result and Some come from the SDK. Result.value and Result.error abort on the wrong case, so check isOk or isErr first. Resources, futures and streams can't cross packages, and the AssemblyScript SDK doesn't support char, tuples, variants, enums or flags yet.