QuickJS wrapper for Android/JVM.
- Java types are supported with JavaScript
- Support promise execute
- JavaScript exception handler
- Compile bytecode
- Supports converting JS object types to Java HashMap.
- ESModule (import, export)
Experimental Features Stability not guaranteed.
- Supports ArrayBuffer to a byte array type.
repositories {
mavenCentral()
}
dependencies {
// Pick one:
// 1. Android - Use wrapper in your public API:
api 'wang.harlon.quickjs:wrapper-android:latest.version'
// 2. JVM - Use wrapper in your implementation only:
implementation 'wang.harlon.quickjs:wrapper-java:latest.version'
}
See how to import the snapshot
Snapshots of the current development version of Wrapper are available, which track the latest versions.
To import snapshot versions on your project, add the code snippet below on your gradle file:
repositories {
maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots/' }
}
Next, add the dependency below to your module's build.gradle
file:
dependencies {
// For Android
implementation "wang.harlon.quickjs:wrapper-android:latest-SNAPSHOT"
// For JVM
implementation "wang.harlon.quickjs:wrapper-java:latest-SNAPSHOT"
}
This repository use git submodules and so when you are checking out the app, you'll need to ensure the submodules are initialized properly. You can use the --recursive
flag when cloning the project to do this.
git clone --recursive https://github.com/HarlonWang/quickjs-wrapper.git
Alternatively, if you already have the project checked out, you can initialize the submodules manually.
git submodule update --init
In Android Platforms:
// You usually need to initialize it before using it..
QuickJSLoader.init();
Refer to here for other platforms.
QuickJSContext context = QuickJSContext.create();
// evaluating JavaScript
context.evaluate("var a = 1 + 2;");
// destroy QuickJSContext
context.destroy();
context.setConsole(your console implementation.);
JavaScript | Java |
---|---|
null | null |
undefined | null |
boolean | Boolean |
Number | Long/Int/Double |
string | String |
Array | JSArray |
object | JSObject |
Function | JSFunction |
ArrayBuffer | byte[](Deep copy) |
Since JavaScript doesn't have a long
type, additional information about long
:
Java --> JavaScript
- The Long value <= Number.MAX_SAFE_INTEGER, will be convert to Number type.
- The Long value > Number.MAX_SAFE_INTEGER, will be convert to BigInt type.
- Number.MIN_SAFE_INTEGER is the same to above.
JavaScript --> Java
- Number(Int64) or BigInt --> Long type
Java
QuickJSContext context = QuickJSContext.create();
JSObject globalObj = context.getGlobalObject();
JSObject repository = context.createNewJSObject();
obj1.setProperty("name", "QuickJS Wrapper");
obj1.setProperty("created", 2022);
obj1.setProperty("version", 1.1);
obj1.setProperty("signing_enabled", true);
obj1.setProperty("getUrl", (JSCallFunction) args -> {
return "https://github.com/HarlonWang/quickjs-wrapper";
});
globalObj.setProperty("repository", repository);
repository.release();
JavaScript
repository.name; // QuickJS Wrapper
repository.created; // 2022
repository.version; // 1.1
repository.signing_enabled; // true
repository.getUrl(); // https://github.com/HarlonWang/quickjs-wrapper
JavaScript
var repository = {
name: 'QuickJS Wrapper',
created: 2022,
version: 1.1,
signing_enabled: true,
getUrl: (name) => { return 'https://github.com/HarlonWang/quickjs-wrapper'; }
}
Java
QuickJSContext context = QuickJSContext.create();
JSObject globalObject = context.getGlobalObject();
JSObject repository = globalObject.getJSObject("repository");
repository.getString("name"); // QuickJS Wrapper
repository.getInteger("created"); // 2022
repository.getDouble("version"); // 1.1
repository.getBoolean("signing_enabled"); // true
JSFunction fn = repository.getJSFunction("getUrl");
String url = fn.call(); // https://github.com/HarlonWang/quickjs-wrapper
fn.release();
repository.release();
QuickJSContext context = QuickJSContext.create();
JSObject obj = context.createNewJSObject();
// When not in use, it needs to be released, otherwise it will cause a memory leak.
obj.release();
QuickJSContext context = QuickJSContext.create();
JSArray array = context.createNewJSArray();
array.release();
QuickJSContext context = createContext();
context.getGlobalObject().setProperty("test", args -> (JSCallFunction) args1 -> "123");
context.evaluate("console.log(test()());");
Also, you can view it in QuickJSTest.testReturnJSCallback
code
byte[] code = context.compile("'hello, world!'.toUpperCase();");
context.execute(code);
Java
// 1. string code mode
context.setModuleLoader(new QuickJSContext.DefaultModuleLoader() {
@Override
public String getModuleStringCode(String moduleName) {
if (moduleName.equals("a.js")) {
return "export var name = 'Jack';\n" +
"export var age = 18;";
}
return null;
}
});
// 2. bytecode mode
context.setModuleLoader(new QuickJSContext.BytecodeModuleLoader() {
@Override
public byte[] getModuleBytecode(String moduleName) {
return context.compileModule("export var name = 'Jack';export var age = 18;", moduleName);
}
});
JavaScript
import {name, age} from './a.js';
console.log('name:' + name); // Jack
console.log('age:' + age); // 18
We typically recommend releasing reference relationships actively after using Java objects to avoid memory leaks. Additionally, the engine will release unreleased objects when destroy, but this timing may be a bit later.
JSFunction func = xxx.getJSFunction("test");
func.call();
func.release();
JSObject obj = xxx.getJSObject("test");
int a = obj.getString("123");
obj.release();
// If the return value is an object, it also needs to be released,
JSObject ret = jsFunction.call();
ret.release();
// If you don't need to handle the return value, it is recommended to call the following method.
jsFunction.callVoid(xxx);
It's important to note that if the result is being returned for use in JavaScript, there is no need to release it.
context.getGlobalObject().setProperty("test", new JSCallFunction() {
@Override
public Object call(Object... args) {
JSObject ret = context.createNewJSObject();
// There is no need to call the release method here.
// ret.release();
return ret;
}
});
If you are using R8 the shrinking and obfuscation rules are included automatically.
ProGuard users must manually add the options from consumer-rules.pro.
JavaScript runtimes are single threaded. All execution in the JavaScript runtime is guaranteed thread safe, by way of Java synchronization.
Support it by joining stargazers for this repository.
Also, follow me on GitHub for my next creations!