diff --git a/README.md b/README.md index 766b3c7..3f28871 100644 --- a/README.md +++ b/README.md @@ -1 +1,176 @@ # inline-webassembly + +Write your WebAssembly functions quick and conveniently! + +## Getting started + +### Add two numbers + +``` +const iw = require('inline-webassembly'); + +iw(` + (module + (func (export "add") (param $n1 i32) (param $n2 i32) (result i32) + get_local $n1 + get_local $n2 + i32.add))` +).then((wasmModule) => { + const sum = wasmModule.add(44, 99); + console.log(`Sum = ${sum}`); // 143 +}); +``` + +## Other examples + +### Read a string from memory + +``` +const iw = require('inline-webassembly'); + +iw(` + (module + (memory (export "memory") 1) + (func (export "hello") (result i32) + i32.const 16 + ) + (data (i32.const 16) + "Hello World" + ) + )` +).then((wasmModule) => { + const stringPointer = wasmModule.hello(44, 99); + const string = wasmModule.readString(stringPointer) + console.log(`Result = ${string}`); // Hello World +}); +``` + +### Call a JS function from WebAssembly + +``` +const iw = require('inline-webassembly'); + +const sayHey = function() { + console.log('Hey!') +} + +iw(` + (module + (import "env" "sayHey" (func $sayHey)) + (func (export "hello") + (call $sayHey) + ) + )`, { env: { sayHey }} +).then((wasmModule) => { + wasmModule.hello(); // Hey! +}); +``` + +### Reverse a string + +``` +const iw = require('inline-webassembly'); + +iw(` + (module + (memory $0 1) + (export "memory" (memory $0)) + ;; declaring and exporting a function named "reverse" + ;; it takes two arguments, the pointer to a string and its length + ;; and it returns a 32 bit integer which is going to be the pointer + ;; to the reversed string + (func (export "reverse") (param $sref i32) (param $slen i32) (result i32) + + ;; declaring new variable to store result pointer + (local $result i32) + + ;; seclaring iterator variable + (local $iterator i32) + + ;; write pointer + (local $write_to i32) + + ;; setting $result = $sref + $slen + 1 + (set_local $result + ;; adding 1 + (i32.add + ;; adding the string pointer with its length + (i32.add + (get_local $sref) + (get_local $slen) + ) + (i32.const 1) + ) + ) + + ;; setting iterator to 0, for the following loop + (set_local $iterator + (i32.const 0) + ) + + ;; we'll start writing to the start of the result + (set_local $write_to + (get_local $result) + ) + + (block + (loop + + ;; store one character from original string to resulting string + (i32.store + (get_local $write_to) + ;; load 1 byte and sign-extend i8 to i32 + (i32.load8_s + (i32.sub + (i32.sub + (i32.add + (get_local $sref) + (get_local $slen) + ) + (get_local $iterator) + ) + (i32.const 1) + ) + ) + ) + + ;; increment position to write to on next loop iteration + (set_local $write_to + (i32.add + (get_local $write_to) + (i32.const 1) + ) + ) + + ;; increment iterator by 1 for every loop iteration + (set_local $iterator + (i32.add + (get_local $iterator) + (i32.const 1) + ) + ) + + ;; break loop if iterator reaches string length + (br_if 1 + (i32.ge_s + (get_local $iterator) + (get_local $slen) + ) + ) + + ;; repeat loop + (br 0) + ) + ) + + ;; returning result which contains pointer to the reversed string + (get_local $result) + ) + )` +).then((wasmModule) => { + const stringToReverse = wasmModule.createString('Dorin'); + const resultPointer = wasmModule.reverse(stringToReverse, 5); + const resultString = wasmModule.readString(resultPointer); + console.log(`Result = ${resultString}`); +}); +``` \ No newline at end of file diff --git a/lib/index.d.ts b/lib/index.d.ts index 7ed3fdb..a768e90 100644 --- a/lib/index.d.ts +++ b/lib/index.d.ts @@ -3,7 +3,6 @@ import { WasmModule as WM } from "wabt"; declare namespace InlineWebAssembly {} interface WasmModule extends WM { - [any: string]: any; /** * Read a string from the module memory by providing a pointer (the position of the first character). * @@ -20,7 +19,7 @@ interface WasmModule extends WM { * For this to work as expected you have to either export the memory from the WebAseembly code or import it from * JavaScript, through the import object. */ - createString(string: string, memoryLocation: number): number; + createString(string: string, memoryLocation?: number): number; } declare function InlineWebAssembly(wasm: string, importObject?: any): Promise;