Run is a tiny library that runs user-provided code into a Web Worker. Its main purpose is to allow data transformation through snippet of code, therefore some global capabilities are disabled.
The library takes a chunk of javascript code (as string) and a data payload and return the result from its execution.
It does try to run "untrusted" code as safer as possible, since:
- The Web Worker can't access the DOM
- The Web Worker can't access the domain context of the host application
- The Web Worker runs in a separated thread, it doesn't block the UI
- The Web Worker shouldn't be able to make network operations (still in investigation)
The main use-case is within low-code applications where users can run snippets of code (not necessarily created by the same user) for a variety of tasks.
Run will be used in our upcoming Open Source Dashboard SDK project Slashd.
There's a little sandbox app here to play with.
With UnPkg CDN:
<script src="https://unpkg.com/@slashd/run"></script>
With SkyPack CDN:
<script type="module">
import SlashdRun from 'https://cdn.skypack.dev/@slashd/run'
// your code
</script>
With a package manager:
npm install @slashd/run
Then, include it in the browser:
<script src="node_modules/@slashd/run/dist/slashd-run.min.js"></script>
or with ES6 in a module with a bundler:
import SlashdRun from '@slashd/run'
You can create one or more tasks (independent workers):
import SlashdRun from '@slashd/run'
const task = new SlashdRun()
The exe
method returns a promise, so you can use it with await
:
const myCode = `return Math.random() * param`
const res = await task.exe(myCode, {param:20})
// res is i.e. 12.345657676
You can catch code error with:
const myCode = `return MathRandom * param`
try{
const res = await task.exe(myCode, {param:20})
}catch(e){
console.log(e)
}
// ReferenceError: MathRandom is not defined
You can use async code, thanks to @rob-gordon:
const myCode = `return new Promise((resolve, reject) => {
setTimeout(() => {
resolve(Math.random())
}, 2000)
})`
const res = await task.exe(myCode, {param:20})
// res is i.e. 12.345657676
or, with restrict:false
option:
const myCode = `return await fetch('https://jsonplaceholder.typicode.com/todos').then(res => res.json())`
const res = await task.exe(myCode, {param:20})
// 200 [{...}, ...]
You can specify to load external libraries within the worker by adding the prop deps
in the setup as an array of external paths:
const task = new SlashdRun({deps:['https://unpkg.com/lodash', 'https://www.example.com/mylibrary.js']})
With the above setup, it's possible to use lodash
in the provided code:
const myCode = `_.difference(arr1, arr2);`
const res = await task.exe(myCode, {arr1:[2, 1], arr2:[2, 3]})
// => [1]
By default the library tries to block some capabilities of the Web Worker, such as the network functions.
If you want to disable this behavior and keep all the standard Web Worker capabilities, add the prop restrict
set to false
:
const task = new SlashdRun({restrict:false})
With this option the user-provided code can make network operations, such fetch()
.
You can also configure the library globally using a specific init
static method. This way all the tasks will use the same setting:
import { init } from '@slashd/run'
init({deps:['https://unpkg.com/lodash'], restrict:false})
To terminate the worker you can use:
task.destroy()
If you need to get a task from a pre-defined pool of available workers (in order to limit the creation of workers), you can use this static method instead of the new SlashdRun
way:
import { init, getFromPool } from '@slashd/run'
init({maxWorkers:3}) // required!
const task = getFromPool()
In this case, the library configuration need to be done with the init
method. Also, the maxWorkers
is required and be at least 1
or greater. Please, consider that browsers have hard limits in term of number of concurrent workers that can be run. From our experience 3/4 is a good safe max number. In general one worker is enough, though.
To dispose the pool and its workers, use this method:
import { disposePool } from '@slashd/run'
disposePool()
Install dependencies:
npm i
Start the watcher
npm start