Skip to content

Commit f3c6833

Browse files
sebastianwesselsebastianwessel
committed
doc: update doc
1 parent 4838770 commit f3c6833

File tree

13 files changed

+617
-96
lines changed

13 files changed

+617
-96
lines changed

‎README.md

Lines changed: 9 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,23 @@
1-
# QuickJS package
2-
3-
**@sebastianwessel/quickjs: Execute JavaScript in a WebAssembly QuickJS Sandbox**
1+
# QuickJS - Execute JavaScript in a WebAssembly QuickJS Sandbox
42

53
This TypeScript package allows you to safely execute JavaScript code within a WebAssembly sandbox using the QuickJS engine. Perfect for isolating and running untrusted code securely, it leverages the lightweight and fast QuickJS engine compiled to WebAssembly, providing a robust environment for code execution.
64

75
## Features
86

97
- **Security**: Run untrusted JavaScript code in a safe, isolated environment.
10-
- **Performance**: Benefit from the lightweight and efficient QuickJS engine.
11-
- **Versatility**: Easily integrate with existing TypeScript projects.
12-
- **Simplicity**: User-friendly API for executing and managing JavaScript code in the sandbox.
138
- **File System**: Can mount a virtual file system
149
- **Custom Node Modules**: Custom node modules are mountable
1510
- **Fetch Client**: Can provide a fetch client to make http(s) calls
1611
- **Test-Runner**: Includes a test runner and chai based `expect`
12+
- **Performance**: Benefit from the lightweight and efficient QuickJS engine.
13+
- **Versatility**: Easily integrate with existing TypeScript projects.
14+
- **Simplicity**: User-friendly API for executing and managing JavaScript code in the sandbox.
15+
16+
**[View the full documentation](https://sebastianwessel.github.io/quickjs/)**
1717

18+
**[Find examples in the repository](https://github.com/sebastianwessel/quickjs/tree/main/example)**
1819

19-
## Usage
20+
## Basic Usage
2021

2122
Here's a simple example of how to use the package:
2223

@@ -28,7 +29,7 @@ import { quickJS } from '@sebastianwessel/quickjs'
2829
const { createRuntime } = await quickJS()
2930

3031
// Create a runtime instance each time a js code should be executed
31-
const { evalCode } = await this.createRuntime({
32+
const { evalCode } = await createRuntime({
3233
allowFetch: true, // inject fetch and allow the code to fetch data
3334
allowFs: true, // mount a virtual file system and provide node:fs module
3435
env: {
@@ -58,59 +59,6 @@ export default await fn()
5859
console.log(result) // { ok: true, data: '<!doctype html>\n<html>\n[....]</html>\n' }
5960
```
6061

61-
### Runtime options
62-
63-
```js
64-
type RuntimeOptions = {
65-
/**
66-
* Mount a virtual file system
67-
* @link https://github.com/streamich/memfs
68-
*/
69-
mountFs?: DirectoryJSON
70-
/**
71-
* Mount custom node_modules in a virtual file system
72-
* @link https://github.com/streamich/memfs
73-
*/
74-
nodeModules?: DirectoryJSON
75-
/**
76-
* Enable file capabilities
77-
* If enabled, the package node:fs becomes available
78-
*/
79-
allowFs?: boolean
80-
/**
81-
* Allow code to make http(s) calls.
82-
* When enabled, the global fetch will be available
83-
*/
84-
allowFetch?: boolean
85-
/**
86-
* Per default, the console log inside of QuickJS is passed to the host console log.
87-
* Here, you can customize the handling and provide your own logging methods.
88-
*/
89-
console?: {
90-
log: (message?: unknown, ...optionalParams: unknown[]) => void
91-
error: (message?: unknown, ...optionalParams: unknown[]) => void
92-
warn: (message?: unknown, ...optionalParams: unknown[]) => void
93-
}
94-
/**
95-
* Key-value list of ENV vars, which should be available in QuickJS
96-
*
97-
* @example
98-
* ```js
99-
* // in config
100-
* {
101-
* env: {
102-
* My_ENV: 'my var'
103-
* }
104-
* }
105-
*
106-
* // inside of QuickJS
107-
* console.log(env.My_ENV) // outputs: my var
108-
* ```
109-
*/
110-
env?: Record<string, unknown>
111-
}
112-
```
113-
11462
## Credits
11563

11664
This lib is based on:

‎docs/README.md

Lines changed: 90 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,96 @@
1+
---
2+
title: QuickJS - Execute JavaScript in a WebAssembly QuickJS Sandbox
3+
description: Run custom javascript inside a webassembly runtime from your Javascript/Typescript application
4+
---
5+
6+
This TypeScript package allows you to safely execute JavaScript code within a WebAssembly sandbox using the QuickJS engine. Perfect for isolating and running untrusted code securely, it leverages the lightweight and fast QuickJS engine compiled to WebAssembly, providing a robust environment for code execution.
17

28
- [Installation](./intallation.md)
39
- Compatibility:
410
- [Core Javascript](./core-js-compatibility.md)
511
- [NodeJS](./node-compatibility.md)
12+
- [Runtime options](./runtime-options.md)
613
- [Run Tests in QuickJS](./running-tests.md)
7-
- [Credits](./credits.md)
14+
- [Credits](./credits.md)
15+
16+
## Features
17+
18+
- **Security**: Run untrusted JavaScript code in a safe, isolated environment.
19+
- **File System**: Can mount a virtual file system
20+
- **Custom Node Modules**: Custom node modules are mountable
21+
- **Fetch Client**: Can provide a fetch client to make http(s) calls
22+
- **Test-Runner**: Includes a test runner and chai based `expect`
23+
- **Performance**: Benefit from the lightweight and efficient QuickJS engine.
24+
- **Versatility**: Easily integrate with existing TypeScript projects.
25+
- **Simplicity**: User-friendly API for executing and managing JavaScript code in the sandbox.
26+
27+
**[View the full documentation](https://sebastianwessel.github.io/quickjs/)**
28+
29+
**[Find examples in the repository](https://github.com/sebastianwessel/quickjs/tree/main/example)**
30+
31+
## Basic Usage
32+
33+
Here's a simple example of how to use the package:
34+
35+
```typescript
36+
import { quickJS } from '@sebastianwessel/quickjs'
37+
38+
// General setup like loading and init of the QuickJS wasm
39+
// It is a ressource intensive job and should be done only once if possible
40+
const { createRuntime } = await quickJS()
41+
42+
// Create a runtime instance each time a js code should be executed
43+
const { evalCode } = await createRuntime({
44+
allowFetch: true, // inject fetch and allow the code to fetch data
45+
allowFs: true, // mount a virtual file system and provide node:fs module
46+
env: {
47+
MY_ENV_VAR: 'env var value'
48+
},
49+
})
50+
51+
52+
const result = await evalCode(`
53+
import { join } as path from 'path'
54+
55+
const fn = async ()=>{
56+
console.log(join('src','dist')) // logs "src/dist" on host system
57+
58+
console.log(env.MY_ENV_VAR) // logs "env var value" on host system
59+
60+
const url = new URL('https://example.com')
61+
62+
const f = await fetch(url)
63+
64+
return f.text()
65+
}
66+
67+
export default await fn()
68+
`)
69+
70+
console.log(result) // { ok: true, data: '<!doctype html>\n<html>\n[....]</html>\n' }
71+
```
72+
73+
## Credits
74+
75+
This lib is based on:
76+
77+
- [quickjs-emscripten](https://github.com/justjake/quickjs-emscripten)
78+
- [quickjs-emscripten-sync](https://github.com/reearth/quickjs-emscripten-sync)
79+
- [memfs](https://github.com/streamich/memfs)
80+
81+
Tools used:
82+
83+
- [Bun](https://bun.sh)
84+
- [Biome](https://biomejs.dev)
85+
- [Hono](https://hono.dev)
86+
- [poolifier-web-worker](https://github.com/poolifier/poolifier-web-worker)
87+
- [tshy](https://github.com/isaacs/tshy)
88+
- [autocannon](https://github.com/mcollina/autocannon)
89+
90+
## License
91+
92+
This project is licensed under the MIT License.
93+
94+
---
95+
96+
This package is ideal for developers looking to execute JavaScript code securely within a TypeScript application, ensuring both performance and safety with the QuickJS WebAssembly sandbox.

‎docs/core-js-compatibility.md

Lines changed: 35 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,42 @@
1-
# Core Javascript Compatibility
1+
---
2+
title: Core JavaScript Compatibility
3+
description: The QuickJS sandbox has build in compatibility for the basic NodeJS/Javascript functions
4+
---
25

36
- ✅ mostly [ES2023](https://test262.fyi/#%7Cqjs,qjs_ng)
47
- ✅ ESM import support (custom modules supported)
58
- ✅ top-level await
69

10+
## Supported Methods
11+
712
| Method | Supported |
813
|------------------------|-----------|
9-
| process.env | ✅ (customizeable) |
10-
| console.log | ✅ |
11-
| console.error | ✅ |
12-
| console.warn | ✅ |
13-
| console.info | ✅ |
14-
| console.debug | ✅ |
15-
| console.trace | ✅ |
16-
| console.assert | ✅ |
17-
| console.count | ✅ |
18-
| console.countReset | ✅ |
19-
| console.dir | ✅ |
20-
| console.dirxml | ✅ |
21-
| console.group | ✅ |
22-
| console.groupCollapsed | ✅ |
23-
| console.groupEnd | ✅ |
24-
| console.table | ✅ |
25-
| console.time | ✅ |
26-
| console.timeEnd | ✅ |
27-
| console.timeLog | ✅ |
28-
| console.clear | ✅ |
29-
| setTimeout | ✅ |
30-
| clearTimeout | ✅ |
31-
| setInterval | ✅ |
32-
| clearInterval | ✅ |
33-
| fetch | ✅ (set allowFetch=true) |
14+
| `process.env` | ✅ (customizable) |
15+
| `console.log` | ✅ (customizable) |
16+
| `console.error` | ✅ (customizable) |
17+
| `console.warn` | ✅ (customizable) |
18+
| `console.info` | ✅ (customizable) |
19+
| `console.debug` | ✅ (customizable) |
20+
| `console.trace` | ✅ (customizable) |
21+
| `console.assert` | ✅ (customizable) |
22+
| `console.count` | ✅ (customizable) |
23+
| `console.countReset` | ✅ (customizable) |
24+
| `console.dir` | ✅ (customizable) |
25+
| `console.dirxml` | ✅ (customizable) |
26+
| `console.group` | ✅ (customizable) |
27+
| `console.groupCollapsed` | ✅ (customizable) |
28+
| `console.groupEnd` | ✅ (customizable) |
29+
| `console.table` | ✅ (customizable) |
30+
| `console.time` | ✅ (customizable) |
31+
| `console.timeEnd` | ✅ (customizable) |
32+
| `console.timeLog` | ✅ (customizable) |
33+
| `console.clear` | ✅ (customizable) |
34+
| `setTimeout` | ✅ |
35+
| `clearTimeout` | ✅ |
36+
| `setInterval` | ✅ |
37+
| `clearInterval` | ✅ |
38+
| `fetch` | ✅ (set `allowFetch=true`) |
39+
40+
This documentation provides a comprehensive overview of the core JavaScript methods and their compatibility with the given environment. Each method listed above is supported, ensuring robust functionality and flexibility for development.
41+
42+
For more information, refer to the [ES2023 compatibility tests](https://test262.fyi/#%7Cqjs,qjs_ng).

‎docs/intallation.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Installation
1+
---
2+
title: Installation of @sebastianwessel/quickjs
3+
description: The QuickJS sandbox has build in compatibility for the basic NodeJS/Javascript functions
4+
---
5+
26

37
Install the package using npm, yarn, or bun:
48

‎docs/node-compatibility.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Node compatibility
1+
---
2+
title: Node compatibility
3+
description: This library provides basic support most common node core packages.
4+
---
25

36
## node:fs
47

0 commit comments

Comments
 (0)