Home

Awesome

asdom

Use DOM APIs in AssemblyScript (TypeScript compiled to WebAssembly).

This allows us to write WebAssembly applications that can manipulate the DOM, and with potential for more speed!

Early Stages!

Work in progress (probably may always be), but right now it's early and many APIs need to be added.

Supported APIs so far

See the outline of supported APIs.

Usage

First you should get familiar with AssemblyScript and learn how to run AssemlyScript code in a browser.

The following asc compiler options are required: --exportRuntime, --exportTable.

The --explicitStart option is required only if any of your ES modules use DOM APIs at their top level (read the comments in the below example).

In your JavaScript code that loads your Wasm module, import Asdom and pass its wasmImports to your Wasm module's imports. The following snippet assumes the use of native ES Modules in the browser and a static HTTP server serving files at the root of a project that has node_modules:

import {Asdom} from './node_modules/asdom/glue/index.js'
import {instantiate} from './node_modules/@assemblyscript/loader/index.js'

async function main() {
	// Create an Asdom instance containing the glue code for DOM APIs.
	const asdom = new Asdom()

	const {exports} = await instantiate(fetch('/build/untouched.wasm'), {
		// Pass the wasmImports in.
		...asdom.wasmImports,

		// ...Add any other imports your apps needs as usual...
	})

	// Before you do anything, pass the the Wasm module's exports to asdom.
	asdom.wasmExports = exports

	// Now execute the Wasm module. Make sure you use the `--explicitStart`
	// compiler option so that a `_start()` method is automatically exported if
	// you will have any code that uses DOM APIs at the top level of any ES
	// module (i.e. top level of any file). Otherwise, you could skip using the
	// `--explicitStart` option and export your own method(s) to call, but in
	// that case you should not use any DOM APIs at the top level of any
	// modules or else the glue code won't be ready because asdom.wasmImports
	// will not be set by the time the top level of modules execute.
	exports._start()

	// If you didn't use `--explicitStart`, you can call your own export instead,
	// assuming no top-level ES module code uses DOM APIs, f.e.
	// exports.whatever()
}

main()

If you use a tool like Webpack or Rollup to bundle your application, or if you know how to write import maps for native ES Modules, then you can use Node.js-style import specifiers instead:

import {Asdom} from 'asdom/glue/index.js'
import {instantiate} from '@assemblyscript/loader/index.js'

Now in your AssemblyScript code, re-export the AssemblyScript glue, and then you can import document or window from asdom to start manipulating the DOM:

// Export AssemblyScript-side glue code or not everything will work (for example the customElements API).
export * from '../node_modules/asdom/assembly/glue'

import {document} from '../node_modules/asdom/assembly/index'

const el = document.createElement('h1')

el.setAttribute('foo', 'bar')

const s: string = el.getAttribute('foo')! // returns "bar"

el.innerHTML = /*html*/ `
  <span style="font-weight: normal; position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%)">
    <em>hello</em> from <strong>AssemblyScript</strong>
  </span>
`

document.body!.appendChild(el)

Caveats

TODO

We will add more DOM APIs as needed while we chisel away.