@coherentglobal/wasm-runner
v0.1.19
Published
Coherent WASM runner for Javascript and Node.js
Downloads
134
Keywords
Readme
WASM Runner
For managing and executing WASM on browser, mobile and NodeJS applications.
Here's a Demo App for reference.
Getting Started
Prerequisites
Here are the tools that you need for your setup.
NodeJS (we recommend to use v20 or later) for running and developing this project.
AWS CLI for publishing and downloading this package. Once installed, create a profile name
manila-dev
then execute the command below:aws sso login --profile manila-dev; aws codeartifact login --tool npm --repository coherent-global --domain coherent-global --domain-owner 792307798794 --region ap-southeast-1 --profile manila-dev
This should update your
.npmrc
. To confirm, you may check if you have this line and if tokens are updated.@coherentglobal:registry=https://coherent-global-792307798794.d.codeartifact.ap-southeast-1.amazonaws.com/npm/coherent-global/
Install
To have it installed in your new project, run this command.
npm install "@coherentglobal/wasm-runner"
or
yarn add "@coherentglobal/wasm-runner"
Usage
Browser ( HTML )
Runner can be used in an HTML by adding the minified JS file to your project.
<script src="https://wasm-runner-sdk.s3.ap-southeast-1.amazonaws.com/wasmrunner.min.js"></script>
Have your javascript initialize
the model and run some values through the execute
function.
/**
* `id` defines the model version ID and the `url` is
* the path of the zip relative to this file.
*/
const modelConfig = {
id: "f30f5935-36c2-4155-aede-523ab2245fd6",
url: "<zip url>",
};
/**
* Input values to be executed on the model. The structure and sample
* data can be found on Spark API Tester.
*/
const payload = {
request_data: {
inputs: {
age: 60,
insure: "Insure",
medical: "Yes",
plan: "Plan 1",
},
},
request_meta: {
service_uri: "",
service_uuid: "",
version: "",
version_uuid: "f30f5935-36c2-4155-aede-523ab2245fd6",
transaction_date: "2021-08-18T04:17:17.142Z",
call_purpose: "postman_request",
source_system: "",
correlation_id: "",
requested_output: "",
},
};
const wasmRunner = new WasmRunner(modelConfig);
await wasmRunner.initialize();
const response = await wasmRunner
.execute(payload)
.catch((err) => console.log(err));
// Do something with the response
ReactJS
You may follow the normal installation follow then import
the packge into your project.
import { WasmRunner } from "@coherentglobal/wasm-runner";
Then do model initialize
and execute
.
/**
* `id` defines the model version ID and the `url` is
* the path of the zip relative to this file.
*/
const modelConfig = {
id: "f30f5935-36c2-4155-aede-523ab2245fd6",
url: "<zip url>",
};
/**
* Input values to be executed on the model. The structure and sample
* data can be found on Spark API Tester.
*/
const payload = {
request_data: {
inputs: {
age: 60,
insure: "Insure",
medical: "Yes",
plan: "Plan 1",
},
},
request_meta: {
service_uri: "",
service_uuid: "",
version: "",
version_uuid: "f30f5935-36c2-4155-aede-523ab2245fd6",
transaction_date: "2021-08-18T04:17:17.142Z",
call_purpose: "postman_request",
source_system: "",
correlation_id: "",
requested_output: "",
},
};
const wasmRunner = new WasmRunner(modelConfig);
await wasmRunner.initialize();
const response = await wasmRunner
.execute(payload)
.catch((err) => console.log(err));
// Do something the response
NodeJS
You may follow the normal installation flow then import
the packge into your project.
const { WasmRunner } = require("@coherentglobal/wasm-runner");
/**
* `id` defines the model version ID and the `url` is
* the path of the zip relative to this file.
*/
const modelConfig = {
id: "f30f5935-36c2-4155-aede-523ab2245fd6",
url: "<zip url>",
};
/**
* Input values to be executed on the model. The structure and sample
* data can be found on Spark API Tester.
*/
const payload = {
request_data: {
inputs: {
age: 60,
insure: "Insure",
medical: "Yes",
plan: "Plan 1",
},
},
request_meta: {
service_uri: "",
service_uuid: "",
version: "",
version_uuid: "f30f5935-36c2-4155-aede-523ab2245fd6",
transaction_date: "2021-08-18T04:17:17.142Z",
call_purpose: "postman_request",
source_system: "",
correlation_id: "",
requested_output: "",
},
};
const wasmRunner = new WasmRunner(modelConfig);
await wasmRunner.initialize();
const response = await wasmRunner
.execute(payload)
.catch((err) => console.log(err));
Ways to load and initialize model
WASM Runner parameter
You may pass the cofig parameters directly to WasmRunner
class whenever you create an instance.
const wasmRunner = new WasmRunner({
id: "f30f5935-36c2-4155-aede-523ab2245fd6",
url: "<zip url>",
});
// Trigger initialize to load the passed model
await wasmRunner.initialize();
Append
Pass the model config to append
function after instantiation.
const wasmRunner = new WasmRunner();
// Pass the config details to `append` function
await wasmRunner.append({
id: "f30f5935-36c2-4155-aede-523ab2245fd6",
url: "<zip url>",
});
Combination of both
For scenarios that you need to load a lot of models, you may do both.
During the instance creation, you may pass a list of configs to WasmRunner
then do append
for additional models.
const initialModels = [
{
id: "f30f5935-36c2-4155-aede-523ab2245fd6",
url: "<zip url>",
},
{
id: "a5gf5935-36c2-6621-aede-a41ab226aa53",
url: "<zip url>",
},
];
const additionalModel = {
id: "e8ba9e7e-169c-4752-8a8e-d6eb0c78cb01",
url: "<zip url>",
};
const wasmRunner = new WasmRunner(initialModels);
await wasmRunner.initialize();
await wasmRunner.append(additionalModel);
const response = await wasmRunner
.execute(payload)
.catch((err) => console.log(err));
Development
Setup
Clone the repo, then install the dependencies
$ git clone https://github.com/CoherentCapital/wasm-runner-js.git
$ yarn install
Test
yarn test
Build
For generating distribution package
yarn build
Functions
initialize()
Triggers the loading and integration of WASM files to Runner module. This step is required before the execute
step.
Returns: Promise<void>
append(modelConfig)
Could be an alternative to initialize()
. This loads additional model that you might need during execute
after the Runner instantiation.
Returns: Promise<void>
execute(payload)
Performs the model calculation. Most common approach, Runner will use request_meta.version_id
from the payload
to locate the model to execute. So it is necessary to ensure that the model is loaded, could be through Runner instantiation or via append
.
Returns: Promise<Object>
isExist(id)
Checks if model exists from the list of initialized models.
Returns: Promise<Boolean>
remove(id)
Removes a model. This is the way to clean up memory allocation for unused loaded models.
Returns: Promise<void>
Limitations
Lower Level Error
Please note that if there's lower level error that occurs, wasm runner can't handle that kind of exception.