{"id":18611353,"url":"https://github.com/harlonwang/quickjs-wrapper","last_synced_at":"2025-05-16T12:03:16.098Z","repository":{"id":40639328,"uuid":"386456296","full_name":"HarlonWang/quickjs-wrapper","owner":"HarlonWang","description":"QuickJS wrapper for Android/JVM","archived":false,"fork":false,"pushed_at":"2025-03-17T02:56:59.000Z","size":1447,"stargazers_count":204,"open_issues_count":10,"forks_count":35,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-02T08:04:18.069Z","etag":null,"topics":["android","java","javascript","quickjs","wrapper"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HarlonWang.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-16T00:05:10.000Z","updated_at":"2025-03-19T00:31:24.000Z","dependencies_parsed_at":"2023-02-17T01:31:52.568Z","dependency_job_id":"a525cc02-27fd-410c-9abf-d30d4dd861af","html_url":"https://github.com/HarlonWang/quickjs-wrapper","commit_stats":{"total_commits":521,"total_committers":5,"mean_commits":104.2,"dds":"0.015355086372360827","last_synced_commit":"5fe44970718f447a5aac360a5f1d0ac026a616c8"},"previous_names":["harlonwang/quickjs-android-wrapper"],"tags_count":69,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HarlonWang%2Fquickjs-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HarlonWang%2Fquickjs-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HarlonWang%2Fquickjs-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HarlonWang%2Fquickjs-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HarlonWang","download_url":"https://codeload.github.com/HarlonWang/quickjs-wrapper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248018032,"owners_count":21034045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","java","javascript","quickjs","wrapper"],"created_at":"2024-11-07T03:13:40.122Z","updated_at":"2025-04-09T10:02:22.357Z","avatar_url":"https://github.com/HarlonWang.png","language":"Java","readme":"# QuickJS For Android/JVM\nQuickJS wrapper for Android/JVM.\n\n## Feature\n- Java types are supported with JavaScript\n- Support promise execute\n- JavaScript exception handler\n- Compile bytecode\n- Supports converting JS object types to Java HashMap.\n- ESModule (import, export)\n\nExperimental Features Stability not guaranteed.\n- Supports ArrayBuffer to a byte array type.\n\n## Download\n\n[![Maven Central](https://img.shields.io/maven-central/v/wang.harlon.quickjs/wrapper-android.svg?label=Maven%20Central\u0026color=blue)](https://search.maven.org/search?q=g:%22wang.harlon.quickjs%22%20AND%20a:%22wrapper-android%22)\n\n```Groovy\nrepositories {\n  mavenCentral()\n}\n\ndependencies {\n  // Pick one:\n\n  // 1. Android - Use wrapper in your public API:\n  api 'wang.harlon.quickjs:wrapper-android:latest.version'\n\n  // 2. JVM - Use wrapper in your implementation only:\n  implementation 'wang.harlon.quickjs:wrapper-java:latest.version'\n}\n```\n\n### SNAPSHOT \n[![Wrapper](https://img.shields.io/static/v1?label=snapshot\u0026message=wrapper\u0026logo=apache%20maven\u0026color=yellowgreen)](https://s01.oss.sonatype.org/content/repositories/snapshots/wang/harlon/quickjs/wrapper-android/) \u003cbr\u003e\n\n\u003cdetails\u003e\n \u003csummary\u003eSee how to import the snapshot\u003c/summary\u003e\n\n#### Including the SNAPSHOT\nSnapshots of the current development version of Wrapper are available, which track [the latest versions](https://s01.oss.sonatype.org/content/repositories/snapshots/wang/harlon/quickjs/wrapper-android/).\n\nTo import snapshot versions on your project, add the code snippet below on your gradle file:\n```Gradle\nrepositories {\n   maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots/' }\n}\n```\n\nNext, add the dependency below to your **module**'s `build.gradle` file:\n```gradle\ndependencies {\n    // For Android\n    implementation \"wang.harlon.quickjs:wrapper-android:latest-SNAPSHOT\"\n    // For JVM\n    implementation \"wang.harlon.quickjs:wrapper-java:latest-SNAPSHOT\"\n}\n```\n\n\u003c/details\u003e\n\n## Building the Project\nThis 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.\n```git\ngit clone --recursive https://github.com/HarlonWang/quickjs-wrapper.git\n```\n\nAlternatively, if you already have the project checked out, you can initialize the submodules manually.\n```git\ngit submodule update --init\n```\n\n## Usage\n\n### Initialization\nIn Android Platforms:\n```Java\n// You usually need to initialize it before using it..\nQuickJSLoader.init();\n```\n\n[Refer to here for other platforms.](./wrapper-java/README.md)\n\n### Create QuickJSContext\n\n```Java\nQuickJSContext context = QuickJSContext.create();\n\n// evaluating JavaScript\ncontext.evaluate(\"var a = 1 + 2;\");\n\n// destroy QuickJSContext\ncontext.destroy();\n```\n\n### Console Support\n```Java\ncontext.setConsole(your console implementation.);\n```\n\n### Supported Types\n\n#### Java and JavaScript can directly convert to each other for the following basic types\n| JavaScript  | Java              |\n|-------------|-------------------|\n| null        | null              |\n| undefined   | null              |\n| boolean     | Boolean           |\n| Number      | Long/Int/Double   |\n| string      | String            |\n| Array       | JSArray           |\n| object      | JSObject          |\n| Function    | JSFunction        |\n| ArrayBuffer | byte[](Deep copy) |\n\nSince JavaScript doesn't have a `long` type, additional information about `long`:\n\nJava --\u003e JavaScript\n  - The Long value \u003c= Number.MAX_SAFE_INTEGER, will be convert to Number type.\n  - The Long value \u003e Number.MAX_SAFE_INTEGER, will be convert to BigInt type.\n  - Number.MIN_SAFE_INTEGER is the same to above.\n\nJavaScript --\u003e Java\n  - Number(Int64) or BigInt --\u003e Long type\n\n\n### Set Property\nJava\n\n```java\nQuickJSContext context = QuickJSContext.create();\nJSObject globalObj = context.getGlobalObject();\nJSObject repository = context.createNewJSObject();\nobj1.setProperty(\"name\", \"QuickJS Wrapper\");\nobj1.setProperty(\"created\", 2022);\nobj1.setProperty(\"version\", 1.1);\nobj1.setProperty(\"signing_enabled\", true);\nobj1.setProperty(\"getUrl\", (JSCallFunction) args -\u003e {\n    return \"https://github.com/HarlonWang/quickjs-wrapper\";\n});\nglobalObj.setProperty(\"repository\", repository);\nrepository.release();\n```\n\nJavaScript\n\n```javascript\nrepository.name; // QuickJS Wrapper\nrepository.created; // 2022\nrepository.version; // 1.1\nrepository.signing_enabled; // true\nrepository.getUrl(); // https://github.com/HarlonWang/quickjs-wrapper\n```                \n\n### Get Property\nJavaScript\n\n```JavaScript\nvar repository = {\n\tname: 'QuickJS Wrapper',\n\tcreated: 2022,\n\tversion: 1.1,\n\tsigning_enabled: true,\n\tgetUrl: (name) =\u003e { return 'https://github.com/HarlonWang/quickjs-wrapper'; }\n}\n```\nJava\n\n```Java\nQuickJSContext context = QuickJSContext.create();\nJSObject globalObject = context.getGlobalObject();\nJSObject repository = globalObject.getJSObject(\"repository\");\nrepository.getString(\"name\"); // QuickJS Wrapper\nrepository.getInteger(\"created\"); // 2022\nrepository.getDouble(\"version\"); // 1.1\nrepository.getBoolean(\"signing_enabled\"); // true\nJSFunction fn = repository.getJSFunction(\"getUrl\");\nString url = fn.call(); // https://github.com/HarlonWang/quickjs-wrapper\nfn.release();\nrepository.release();\n```\n\n### Create JSObject in Java\n```Java\nQuickJSContext context = QuickJSContext.create();\nJSObject obj = context.createNewJSObject();\n// When not in use, it needs to be released, otherwise it will cause a memory leak.\nobj.release();\n```\n\n### Create JSArray in Java\n```Java\nQuickJSContext context = QuickJSContext.create();\nJSArray array = context.createNewJSArray();\narray.release();\n```\n\n### How to return Function to JavaScript in Java\n```Java\nQuickJSContext context = createContext();\ncontext.getGlobalObject().setProperty(\"test\", args -\u003e (JSCallFunction) args1 -\u003e \"123\");\ncontext.evaluate(\"console.log(test()());\");\n```\n\nAlso, you can view it in `QuickJSTest.testReturnJSCallback` code\n\n\n### Compile ByteCode\n\n```Java\nbyte[] code = context.compile(\"'hello, world!'.toUpperCase();\");\ncontext.execute(code);\n```\n\n### ESModule\nJava\n```Java\n// 1. string code mode\ncontext.setModuleLoader(new QuickJSContext.DefaultModuleLoader() {\n    @Override\n    public String getModuleStringCode(String moduleName) {\n       if (moduleName.equals(\"a.js\")) {\n           return \"export var name = 'Jack';\\n\" +\n                   \"export var age = 18;\";\n       }\n       return null;\n    }\n});\n\n// 2. bytecode mode\ncontext.setModuleLoader(new QuickJSContext.BytecodeModuleLoader() {\n    @Override\n    public byte[] getModuleBytecode(String moduleName) {\n        return context.compileModule(\"export var name = 'Jack';export var age = 18;\", moduleName);\n    }\n});\n\n// 3. use `evaluateModule` for module script\ncontext.evaluateModule(...);\n```\nJavaScript\n```JavaScript\nimport {name, age} from './a.js';\n\nconsole.log('name：' + name); // Jack\nconsole.log('age：' + age); // 18\n```\n\n### Object release\nWe 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.\n```java\nJSFunction func = xxx.getJSFunction(\"test\");\nfunc.call();\nfunc.release();\n\nJSObject obj = xxx.getJSObject(\"test\");\nint a = obj.getString(\"123\");\nobj.release();\n\n// If the return value is an object, it also needs to be released, \nJSObject ret = jsFunction.call();\nret.release();\n\n// If you don't need to handle the return value, it is recommended to call the following method.\njsFunction.callVoid(xxx);\n```\n\nIt's important to note that if the result is being returned for use in JavaScript, there is no need to release it.\n```java\ncontext.getGlobalObject().setProperty(\"test\", new JSCallFunction() {\n  @Override\n  public Object call(Object... args) {\n    JSObject ret = context.createNewJSObject();\n    // There is no need to call the release method here.\n    // ret.release();\n    return ret;\n  }\n});\n```\n\n## R8 / ProGuard\nIf you are using R8 the shrinking and obfuscation rules are included automatically.\n\nProGuard users must manually add the options from [consumer-rules.pro](/wrapper-android/consumer-rules.pro).\n\n## Concurrency\nJavaScript runtimes are single threaded. All execution in the JavaScript runtime is guaranteed thread safe, by way of Java synchronization.\n\n## Find this repository useful?\nSupport it by joining __[stargazers](https://github.com/HarlonWang/quickjs-wrapper/stargazers)__ for this repository. \u003cbr\u003e\nAlso, __[follow me](https://github.com/HarlonWang)__ on GitHub for my next creations! \n\n## Stargazers over time\n\n[![Stargazers over time](https://starchart.cc/HarlonWang/quickjs-wrapper.svg)](https://starchart.cc/HarlonWang/quickjs-wrapper)\n\n## Reference\n\n- [quickjs-java](https://github.com/cashapp/quickjs-java)\n- [quack](https://github.com/koush/quack)\n- [quickjs-android](https://github.com/taoweiji/quickjs-android)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharlonwang%2Fquickjs-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharlonwang%2Fquickjs-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharlonwang%2Fquickjs-wrapper/lists"}