wasm-rquickjs

Introduction

Command line tool and library to generate a Rust crate wrapping JavaScript code into a WebAssembly Component using the QuickJS engine.

Comparison with ComponentizeJS

ComponentizeJS achieves the same goal of wrapping JavaScript code into a WebAssembly Component, but it does it using a modified version of the SpiderMonkey engine.

Advantages of wasm-rquickjs over ComponentizeJS:

• At the time of writing, there are known bugs in ComponentizeJS (or one of its underlying modules) that prevents it from being used in production.
• Much simpler to develop and debug, as everything exposed for JavaScript is implemented in async Rust using the rquickjs library
• The WIT-JS mapping rules and the set of available JavaScript APIs are well defined
• Smaller WASM binary size

Advantages of ComponentizeJS over wasm-rquickjs:

• Faster runtime (due to the SpiderMonkey engine)
• Faster startup time (it does pre-initialization with Wizer)
• No need for the Rust toolchain for end users

Comparison with wasmedge-quickjs

The project is similar to wasmedge-quickjs in using te QuickJS engine compiled to WASM to run JavaScript code, but it is different in the following ways:

• It does not provide support for using the component model from JS (defining imports and exports using WIT)
• The imports the resulting WASM component has are WasmEdge specific

Usage

The tool can be used as a command line tool or as a library. The command line tool has two top level commands:

  generate-wrapper-crate  Generate the wrapper crate for a JavaScript module
  generate-dts            Generate TypeScript module definitions

Generating the wrapper crate

This is the primary command that generates the Rust crate embedding the JavaScript code into a WebAssembly Component.

Usage: wasm-rquickjs generate-wrapper-crate --js <JS> --wit <WIT> --output <OUTPUT>

• The --js arguments is the path to the JavaScript file to be wrapped. There can be only one JavaScript file, containing an ES6 module exporting the necessary functions and classes as described below.
• The --wit argument is the path to the WIT root containing a single world that describes the imports and exports of the component
• The --output argument is the path to the output directory where the generated Rust crate will be created.

The output directory is going to contain a self-contained Rust crate that can be compiled into a WASM component using the cargo-component tool.

The generated crate has some features that control what imports the component will have beside the ones defined in the user's WIT world:

• logging: enables the wasi:logging import to be used for the JavaScript console API
• http: enables the wasi:http import to be used for the JavaScript fetch API

By default both feature flags are enabled.

Generating TypeScript module definitions

The generate-dts command generates TypeScript module definitions for all the exported and imported interfaces:

Usage: wasm-rquickjs generate-dts --wit <WIT> --output <OUTPUT>

• The --wit argument is the path to the WIT root containing a single world that describes the imports and exports of the component.
• The --output argument is the path to the output directory where the generated TypeScript module definitions ( .d.ts) will be created.

Using with Golem

wasm-rquickjs is integrated into Golem's command line interface, so it can be directly used using Golem app templates.

Mappings

Exports

Top level exported functions

The following WIT code:

package demo:pkg;

world example {
  export hello: func() -> string;
}

must be implemented in JavaScript as:

export const hello = () => {
    return "Hello, world!";
};

The this is bound to the module object. The JS function name is always in camelCase.

Exported interfaces

Exported interfaces has to be exported from JavaScript as objects:

The following WIT example:

package demo:pkg;

interface sample-api {
  get-string-length: func(value: string) -> u64;
}

world example {
  export sample-api;
}

has to be implemented in JavaScript as:

export const sampleApi = {
    getStringLength: (value) => {
        return value.length;
    }
};

All names are converted to camelCase. The JavaScript this is bound to object representing the exporter interface, in the above example it is sampleApi.

Exported resources

Exported resources are implemented as classes in JS:

The following WIT example:

package demo:pkg;

interface iface {
  resource example-resource {
    constructor(name: string);
    get-name: func() -> string;
    compare: static func(h1: borrow<example-resource>, h2: borrow<example-resource>) -> s32;
    merge: static func(h1: own<example-resource>, h2: own<example-resource>) -> hello;
  }
}

world example {
  export iface;
}

Must be exported from JavaScript in the following way:

class Hello {
    constructor(name) {
        this.name = name;
    }

    // async to demonstrate it is possible
    async getName() {
        return this.name;
    }

    static compare(h1, h2) {
        if (h1.name === h2.name) {
            return 0;
        } else if h1.name < h2.name) {
            return -1;
        } else {
            return 1;
        }
    }

    static merge(h1, h2) {
        return new Hello(`${h1.name} & ${h2.name}`);
    }
}

export const iface = {
    Hello: Hello,
};

The classes have a UpperCamelCase name and their methods are in camelCase. All methods and static methods can be either sync or async.

Types

Limitations

• Maximum number of function parameters is 26
• Anonymous interface exports/imports are not supported
• Imported individual functions into the world are not supported (only whole interfaces)

Available JavaScript APIs

APIs

Console

If the logging feature flag is enabled in the generated crate, it depends on wasi:logging, otherwise just on the core WASI interfaces.

• assert
• clear
• count
• countReset
• debug
• dir
• dirXml
• error
• group
• groupCollapsed
• groupEnd
• info
• log
• table
• time
• timeEnd
• timeLog
• trace
• warn

HTTP (fetch)

Only if the http feature flag is enabled in the generated crate. It depends on wasi:http.

• fetch
• Headers
• Request
• Response
• FormData
• Blob
• File

URL

• URL
• URLSearchParams

Streams

Implemented by https://github.com/MattiasBuelens/web-streams-polyfill

• ByteLengthQueuingStrategy
• CountQueuingStrategy
• ReadableByteStreamController
• ReadableStream
• ReadableStreamBYOBReader
• ReadableStreamBYOBRequest
• ReadableStreamDefaultController
• ReadableStreamDefaultReader
• TransformStream
• TransformStreamDefaultController
• WritableStream
• WritableStreamDefaultController

Timeout functions

• setTimeout

• clearTimeout

• setInterval

• clearInterval

• setImmediate

Encoding

• TextEncoder
• TextDecoder
• TextDecoderStream
• TextEncoderStream

node:util

• format
• deprecate
• debugLog
• inspect
• isArray
• isBoolean
• isNull
• isNullOrUndefined
• isNumber
• isString
• isSymbol
• isUndefined
• isRegExp
• isObject
• isDate
• isError
• isFunction
• isPrimitive
• isBuffer
• log
• _extend
• promisify
• callbackify

node:buffer

• Buffer
• INSPECT_MAX_BYTES
• kMaxLength
• kStringMaxLength
• constants
• SlowBuffer

node:fs

• readFile
• readFileSync
• writeFile
• writeFileSync

node:process

• argv
• argv0
• env
• cwd

base64-js

• byteLength
• toByteArray
• fromByteArray

ieee754

• read
• write

Coming from QuickJS

• Global:

  • parseInt
  • parseFloat
  • isNaN
  • isFinite
  • quickMicrotask
  • decodeURI
  • decodeURIComponent
  • encodeURI
  • encodeURIComponent
  • escape
  • unescape
  • Infinity
  • NaN
  • undefined
  • [Symbol.toStringTag]

• Object

  • static methods and properties:
    • create
    • getPrototypeOf
    • setPrototypeOf
    • defineProperty
    • defineProperties
    • getOwnPropertyNames
    • getOwnPropertySymbols
    • groupBy
    • keys
    • values
    • entries
    • isExtensible
    • preventExtensions
    • getOwnPropertyDescriptor
    • getOwnPropertyDescriptors
    • is
    • assign
    • seal
    • freeze
    • isSealed
    • isFrozen
    • fromEntries
    • hasOwn
  • methods and properties:
    • toString
    • toLocaleString
    • valueOf
    • hasOwnProperty
    • isPrototypeOf
    • propertyIsEnumerable
    • __proto__
    • __defineGetter__
    • __defineSetter__
    • __lookupGetter__
    • __lookupSetter__

• Function

  • methods and properties:
    • call
    • apply
    • bind
    • toString
    • [Symbol.hasInstance]
    • fileName
    • lineNumber
    • columnNumber

• Error

  • methods and properties:
    • name
    • message
    • toString
  • static methods and properties:
    • isError
    • captureStackTrace
    • stackTraceLimit
    • prepareStackTrace

• Generator

  • methods and properties:
    • next
    • return
    • throw
    • [Symbol.toStringTag]
  • static methods and properties:
    • from

• Iterator

  • static methods and properties:
    • from
  • methods and properties:
    • drop filter flatMap map take every find forEach some reduce toArray [Symbol.iterator] [Symbol.toStringTag]

• Array

  • static methods and properties:
    • isArray
    • from
    • of
    • [Symbol.species]
  • methods and properties:
    • at
    • with
    • concat
    • every
    • some
    • forEach
    • map
    • filter
    • reduce
    • reduceRight
    • fill
    • find
    • findIndex
    • findLast
    • findLastIndex
    • indexOf
    • lastIndexOf
    • includes
    • join
    • toString
    • toLocaleString
    • pop
    • push
    • shift
    • unshift
    • reverse
    • toReversed
    • sort
    • toSorted
    • slice
    • splice
    • toSpliced
    • copyWithin
    • flatMap
    • flat
    • values
    • [Symbol.iterator]
    • keys
    • entries

• Number

  • static methods and properties:
    • parseInt
    • parseFloat
    • isNaN
    • isFinite
    • isInteger
    • isSafeInteger
    • MAX_VALUE
    • MIN_VALUE
    • NaN
    • NEGATIVE_INFINITY
    • POSITIVE_INFINITY
    • EPSILON
    • MAX_SAFE_INTEGER
    • MIN_SAFE_INTEGER
  • methods and properties:
    • toExponential
    • toFixed
    • toPrecision
    • toString
    • toLocaleString
    • valueOf

• Boolean

  • methods and properties:
    • toString
    • valueOf

• String

  • static methods and properties:
    • fromCharCode
    • fromCodePoint
    • raw
  • methods and properties:
    • length
    • at
    • charCodeAt
    • charAt
    • concat
    • codePointAt
    • isWellFormed
    • toWellFormed
    • indexOf
    • lastIndexOf
    • includes
    • endsWith
    • startsWith
    • match
    • matchAll
    • search
    • split
    • substring
    • substr
    • slice
    • repeat
    • replace
    • replaceAll
    • padEnd
    • padStart
    • trim
    • trimEnd
    • trimRight
    • trimStart
    • trimLeft
    • toString
    • valueOf
    • localeCompare
    • normalize
    • toLowerCase
    • toUpperCase
    • toLocaleLowerCase
    • toLocaleUpperCase
    • [Symbol.iterator]
    • anchor
    • big
    • blink
    • bold
    • fixed
    • fontcolor
    • fontsize
    • italics
    • link
    • small
    • strike
    • sub
    • sup

• Symbol

  • static methods and properties:
    • for
    • keyFor
  • methods and properties:
    • toString
    • valueOf
    • description
    • [Symbol.toPrimitive]
    • [Symbol.toStringTag]

• Map

  • static methods and properties:
    • groupBy
    • [Symbol.species]
  • methods and properties:
    • set
    • get
    • has
    • delete
    • clear
    • size
    • forEach
    • values
    • keys
    • entries
    • [Symbol.iterator]
    • [Symbol.toStringTag]

• Set

  • static methods and properties:
    • [Symbol.species]
  • methods and properties:
    • add
    • has
    • delete
    • clear
    • size
    • forEach
    • isDisjointFrom
    • isSubsetOf
    • isSupersetOf
    • intersection
    • difference
    • symmetricDifference
    • union
    • values
    • keys
    • [Symbol.iterator]
    • entries
    • [Symbol.toStringTag]

• WeakMap

  • methods and properties:
    • set
    • get
    • has
    • delete
    • [Symbol.toStringTag]

• WeakSet

  • methods and properties:
    • add
    • has
    • delete
    • [Symbol.toStringTag]

• GeneratorFunction

  • methods and properties:
    • [Symbol.toStringTag]

• Math

  • static methods and properties:
    • min
    • max
    • abs
    • floor
    • ceil
    • round
    • sqrt
    • acos
    • asin
    • atan
    • atan2
    • cos
    • exp
    • log
    • pow
    • sin
    • tan
    • trunc
    • sign
    • cosh
    • sinh
    • tanh
    • acosh
    • asinh
    • atanh
    • expm1
    • log1p
    • log2
    • log10
    • cbrt
    • hypot
    • random
    • f16round
    • fround
    • imul
    • clz32
    • sumPrecise
    • [Symbol.toStringTag]
    • E
    • LN10
    • LN2
    • LOG2E
    • LOG10E
    • PI
    • SQRT1_2
    • SQRT2

• Reflect

  • static methods and properties:
    • apply
    • construct
    • defineProperty
    • deleteProperty
    • get
    • getOwnPropertyDescriptor
    • getPrototypeOf
    • has
    • isExtensible
    • ownKeys
    • preventExtensions
    • set
    • setPrototypeOf
    • [Symbol.toStringTag]

• RegExp

  • static methods and properties:
    • escape
    • [Symbol.species]
  • methods and properties:
    • flags
    • source
    • global
    • ignoreCase
    • multiline
    • dotAll
    • unicode
    • unicodeSets
    • sticky
    • hasIndices
    • exec
    • compile
    • test
    • toString
    • [Symbol.replace]
    • [Symbol.match]
    • [Symbol.matchAll]
    • [Symbol.search]
    • [Symbol.split]

• JSON

  • static methods and properties:
    • parse
    • stringify
    • [Symbol.toStringTag]

• Promise

  • static methods and properties:
    • resolve
    • reject
    • all
    • allSettled
    • any
    • try
    • race
    • withResolvers
    • [Symbol.species]
  • methods and properties:
    • then
    • catch
    • finally
    • [Symbol.toStringTag]

• AsyncFunction

  • methods and properties:
    • [Symbol.toStringTag]

• AsyncIterator

  • methods and properties:
    • next
    • return
    • throw

• AsyncGeneratorFunction

  • methods and properties:
    • [Symbol.toStringTag]

• AsyncGenerator

  • methods and properties:
    • next
    • return
    • throw
    • [Symbol.toStringTag]

• Date

  • static methods and properties:
    • now
    • parse
    • UTC
  • methods and properties:
    • valueOf
    • toString
    • [Symbol.toPrimitive]
    • toUTCString
    • toGMTString
    • toISOString
    • toDateString
    • toTimeString
    • toLocaleString
    • toLocaleDateString
    • toLocaleTimeString
    • getTimezoneOffset
    • getTime
    • getYear
    • getFullYear
    • getUTCFullYear
    • getMonth
    • getUTCMonth
    • getDate
    • getUTCDate
    • getHours
    • getUTCHours
    • getMinutes
    • getUTCMinutes
    • getSeconds
    • getUTCSeconds
    • getMilliseconds
    • getUTCMilliseconds
    • getDay
    • getUTCDay
    • setTime
    • setMilliseconds
    • setUTCMilliseconds
    • setSeconds
    • setUTCSeconds
    • setMinutes
    • setUTCMinutes
    • setHours
    • setUTCHours
    • setDate
    • setUTCDate
    • setMonth
    • setUTCMonth
    • setYear
    • setFullYear
    • setUTCFullYear
    • toJSON

• BigInt

  • static methods and properties:
    • asIntN
    • asUintN
  • methods and properties:
    • toString
    • valueOf
    • [Symbol.toStringTag]

• ArrayBuffer

  • static methods and properties:
    • isView
    • [Symbol.species
  • methods and properties:
    • byteLength
    • maxByteLength
    • resizeable
    • detached
    • resize
    • slice
    • transfer
    • transferToFixedLength
    • [Symbol.toStringTag]

• SharedArrayBuffer

  • static methods and properties:
    • [Symbol.species]
  • methods and properties:
    • byteLength
    • maxByteLength
    • growable
    • grow
    • slice
    • [Symbol.toStringTag]

• Typed arrays (Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array, BigUint64Array, Float32Array, Float64Array, Float16Array)

  • static methods and properties:
    • from
    • of
    • [Symbol.species]
  • methods and properties:
    • length
    • at
    • with
    • buffer
    • byteLength
    • set
    • byteOffset
    • values
    • [Symbol.iterator]
    • keys
    • entries
    • [Symbol.toStringTag]
    • copyWithin
    • every
    • some
    • forEach
    • map
    • filter
    • reduce
    • reduceRight
    • fill
    • find
    • findIndex
    • findLast
    • findLastIndex
    • reverse
    • toReversed
    • slice
    • subarray
    • sort
    • toSorted
    • join
    • toLocaleString
    • indexOf
    • lastIndexOf
    • includes

• DataView

  • methods and properties:
    • buffer
    • byteLength
    • byteOffset
    • getInt8
    • getUint8
    • getInt16
    • getUint16
    • getInt32
    • getUint32
    • getBigInt64
    • getBigUint64
    • getFloat16
    • getFloat32
    • getFloat64
    • setInt8
    • setUint8
    • setInt16
    • setUint16
    • setInt32
    • setUint32
    • setBigInt64
    • setBigUint64
    • setFloat16
    • setFloat32
    • setFloat64
    • [Symbol.toStringTag]

• Atomics

  • static methods and properties:
    • add
    • and
    • or
    • sub
    • xor
    • exchange
    • compareExchange
    • load
    • store
    • isLockFree
    • pause
    • wait
    • notify
    • [Symbol.toStringTag]

• Performance

  • methods and properties:
    • now

• WeakRef

  • methods and properties:
    • deref
    • [Symbol.toStringTag]

• FinalizationRegistry

  • methods and properties:
    • register
    • unregister
    • [Symbol.toStringTag]

• Callsite

  • methods and properties: -isNative
    • getFileName
    • getFunction
    • getFunctionName
    • getColumnNumber
    • getLineNumber
    • [Symbol.toStringTag]

• Proxy

Developing

There are a few important things to keep in mind when working on the project:

• The skeleton crate can be opened and compiled separately when working on the APIs provided for JavaScript. Unfortunately we cannot use the Cargo.toml file name in it because that breaks Rust packaging - so before working on it, it has to be renamed to Cargo.toml and before committing back it has to be renamed back to Cargo.toml_.

• If the skeleton crate was compiled for testing, and then wasm-rquickjs is compiled, the include_dir! macro is embedding everything from the skeleton directory including the target directory, resulting in slow compilation times and huge resulting binaries. Use the cleanup-skeleton.sh script to quickly remove the target directory from the skeleton crate.