go-applets

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: MIT

README

go-applets

Applets are small, untrusted TypeScript files that change a stream of JSON objects. They are type-checked, compiled and run safely in a sandboxed WebAssembly environment, from within a Go application or using a dedicated gRPC service (planned).

An applet receives its parameters, then a stream of input objects, and produces a stream of output objects. Applets run with limits on memory and time, and without access to the network, the filesystem or anything else the host doesn't explicitly give them.

The repository contains the following components:

  • The javy directory embeds Javy's plugin, containing a JavaScript on WebAssembly compiler and runtime, embedding QuickJS. This is a separate module so it can be used without the rest of this repository.
  • The build directory uses TypeScript (via skybitsnl/go-tsc) for type-checking applets, esbuild for bundling them, Javy for compiling them to bytecode, then watgo for wrapping the bytecode into a small WASM module.
  • The runner directory takes a WASM module as produced by build (or compatible with it), and runs it within a WebAssembly sandbox provided by wazero.
  • The cmd/appletor directory contains a command-line tool that runs an applet over files, with tac.ts as an example.

Status: under development. build and runner work in their most basic form: building has no resource limits yet, and runs have no time limits other than the context the caller passes. The gRPC service does not exist yet.

Usage

The package example of build builds an applet from TypeScript and runs it. The package documentation of build also describes how to have an editor type-check applets.

To try an applet on files, run it with appletor. For example, this reverses the order of the lines in each passed file:

go run ./cmd/appletor cmd/appletor/tac.ts file-1.txt file-2.txt

Development

go test ./...
go -C javy test ./...

The root module uses the javy module from this repository, through a replace directive in go.mod.

License

MIT, see LICENSE, except the javy module, which embeds the Javy plugin and shares Javy's license: the Apache License 2.0 with LLVM exceptions, see javy/LICENSE.

build embeds the TypeScript compiler through go-tsc, under the Apache License 2.0. Programs that use build must pass on TypeScript's license and notice when they are distributed; go-tsc provides both.

Directories

Path Synopsis
appletpb module
Package build turns the TypeScript source of an applet into a WebAssembly module that package runner can run.
Package build turns the TypeScript source of an applet into a WebAssembly module that package runner can run.
cmd
appletor command
Command appletor runs an applet over files, and overwrites each file with what the applet outputs for it.
Command appletor runs an applet over files, and overwrites each file with what the applet outputs for it.
javy module
Package runner runs applets in a WebAssembly sandbox.
Package runner runs applets in a WebAssembly sandbox.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL