Skip to content

Commit 8021401

Browse files
sebastianwesselsebastianwessel
committed
doc: add api doc
1 parent b13431b commit 8021401

37 files changed

+2127
-0
lines changed

‎website/api/README.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
**@sebastianwessel/quickjs v2.3.1**
2+
3+
***
4+
5+
# QuickJS - Execute JavaScript and TypeScript in a WebAssembly QuickJS Sandbox
6+
7+
This TypeScript package allows you to safely execute **JavaScript AND TypeScript 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.
8+
9+
**[View the full documentation](https://sebastianwessel.github.io/quickjs/)** | **[Find examples in the repository](https://github.com/sebastianwessel/quickjs/tree/main/example)** | **[Online Playground](https://sebastianwessel.github.io/quickjs/playground.html)**
10+
11+
## Features
12+
13+
- **Security**: Run untrusted JavaScript and TypeScript code in a safe, isolated environment.
14+
- **Basic Node.js modules**: Provides basic standard Node.js module support for common use cases.
15+
- **File System**: Can mount a virtual file system.
16+
- **Custom Node Modules**: Custom node modules are mountable.
17+
- **Fetch Client**: Can provide a fetch client to make http(s) calls.
18+
- **Test-Runner**: Includes a test runner and chai based `expect`.
19+
- **Performance**: Benefit from the lightweight and efficient QuickJS engine.
20+
- **Versatility**: Easily integrate with existing TypeScript projects.
21+
- **Simplicity**: User-friendly API for executing and managing JavaScript and TypeScript code in the sandbox.
22+
23+
## Basic Usage
24+
25+
Here's a simple example of how to use the package:
26+
27+
```typescript
28+
import variant from "@jitl/quickjs-ng-wasmfile-release-sync";
29+
import { type SandboxOptions, loadQuickJs } from "@sebastianwessel/quickjs";
30+
31+
// General setup like loading and init of the QuickJS wasm
32+
// It is a ressource intensive job and should be done only once if possible
33+
const { runSandboxed } = await loadQuickJs(variant);
34+
35+
const options: SandboxOptions = {
36+
allowFetch: true, // inject fetch and allow the code to fetch data
37+
allowFs: true, // mount a virtual file system and provide node:fs module
38+
env: {
39+
MY_ENV_VAR: "env var value",
40+
},
41+
};
42+
43+
const code = `
44+
import { join } from 'path'
45+
46+
const fn = async ()=>{
47+
console.log(join('src','dist')) // logs "src/dist" on host system
48+
49+
console.log(env.MY_ENV_VAR) // logs "env var value" on host system
50+
51+
const url = new URL('https://example.com')
52+
53+
const f = await fetch(url)
54+
55+
return f.text()
56+
}
57+
58+
export default await fn()
59+
`;
60+
61+
const result = await runSandboxed(
62+
async ({ evalCode }) => evalCode(code),
63+
options,
64+
);
65+
66+
console.log(result); // { ok: true, data: '<!doctype html>\n<html>\n[....]</html>\n' }
67+
```
68+
69+
**[View the full documentation](https://sebastianwessel.github.io/quickjs/)**
70+
71+
**[Find examples in the repository](https://github.com/sebastianwessel/quickjs/tree/main/example)**
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+
- [Chai](https://www.chaijs.com)
81+
82+
Tools used:
83+
84+
- [Bun](https://bun.sh)
85+
- [Biome](https://biomejs.dev)
86+
- [Hono](https://hono.dev)
87+
- [poolifier-web-worker](https://github.com/poolifier/poolifier-web-worker)
88+
- [tshy](https://github.com/isaacs/tshy)
89+
- [autocannon](https://github.com/mcollina/autocannon)
90+
91+
## License
92+
93+
This project is licensed under the MIT License.
94+
95+
---
96+
97+
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.

‎website/api/functions/addSerializer.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / addSerializer
6+
7+
# Function: addSerializer()
8+
9+
> **addSerializer**(`name`, `fn`): `Map`\<`string`, [`Serializer`](../type-aliases/Serializer.md)\>
10+
11+
Defined in: [sandbox/handleToNative/serializer/index.ts:17](https://github.com/sebastianwessel/quickjs/blob/main/src/sandbox/handleToNative/serializer/index.ts#L17)
12+
13+
Add a new Serializer
14+
15+
## Parameters
16+
17+
### name
18+
19+
`string`
20+
21+
### fn
22+
23+
[`Serializer`](../type-aliases/Serializer.md)
24+
25+
## Returns
26+
27+
`Map`\<`string`, [`Serializer`](../type-aliases/Serializer.md)\>

‎website/api/functions/createVirtualFileSystem.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / createVirtualFileSystem
6+
7+
# Function: createVirtualFileSystem()
8+
9+
> **createVirtualFileSystem**(`runtimeOptions`): `object`
10+
11+
Defined in: [createVirtualFileSystem.ts:31](https://github.com/sebastianwessel/quickjs/blob/main/src/createVirtualFileSystem.ts#L31)
12+
13+
Create the virtual file system for the sandbox
14+
Creates a node_modules folder with packages and ensures the src folder
15+
16+
## Parameters
17+
18+
### runtimeOptions
19+
20+
[`RuntimeOptions`](../type-aliases/RuntimeOptions.md) = `{}`
21+
22+
## Returns
23+
24+
`object`
25+
26+
filesystem fs and volume vol
27+
28+
### fs
29+
30+
> **fs**: `IFs`
31+
32+
### vol
33+
34+
> **vol**: `Volume`

‎website/api/functions/expose.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / expose
6+
7+
# Function: expose()
8+
9+
> **expose**(`ctx`, `_parentScope`, `input`, `parent?`): `void`
10+
11+
Defined in: [sandbox/expose/expose.ts:173](https://github.com/sebastianwessel/quickjs/blob/main/src/sandbox/expose/expose.ts#L173)
12+
13+
## Parameters
14+
15+
### ctx
16+
17+
`QuickJSContext` | `QuickJSAsyncContext`
18+
19+
### \_parentScope
20+
21+
`Scope`
22+
23+
### input
24+
25+
`Record`\<`string`, `unknown`\>
26+
27+
### parent?
28+
29+
`QuickJSHandle`
30+
31+
## Returns
32+
33+
`void`

‎website/api/functions/getAsyncModuleLoader.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / getAsyncModuleLoader
6+
7+
# Function: getAsyncModuleLoader()
8+
9+
> **getAsyncModuleLoader**(`fs`, `_runtimeOptions`): `JSModuleLoaderAsync`
10+
11+
Defined in: [sandbox/asyncVersion/getAsyncModuleLoader.ts:7](https://github.com/sebastianwessel/quickjs/blob/main/src/sandbox/asyncVersion/getAsyncModuleLoader.ts#L7)
12+
13+
## Parameters
14+
15+
### fs
16+
17+
`IFs`
18+
19+
### \_runtimeOptions
20+
21+
[`RuntimeOptions`](../type-aliases/RuntimeOptions.md)
22+
23+
## Returns
24+
25+
`JSModuleLoaderAsync`

‎website/api/functions/getDefaultFetchAdapter.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / getDefaultFetchAdapter
6+
7+
# Function: getDefaultFetchAdapter()
8+
9+
> **getDefaultFetchAdapter**(`adapterOptions`): *typeof* `fetch`
10+
11+
Defined in: [adapter/fetch.ts:96](https://github.com/sebastianwessel/quickjs/blob/main/src/adapter/fetch.ts#L96)
12+
13+
Create a default fetch adapter
14+
15+
## Parameters
16+
17+
### adapterOptions
18+
19+
[`GetFetchAdapterOptions`](../type-aliases/GetFetchAdapterOptions.md) = `{}`
20+
21+
Options for creating the fetch adapter
22+
23+
## Returns
24+
25+
*typeof* `fetch`
26+
27+
A fetch adapter function

‎website/api/functions/getHandle.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / getHandle
6+
7+
# Function: getHandle()
8+
9+
> **getHandle**(`scope`, `ctx`, `name`, `input`): `QuickJSHandle`
10+
11+
Defined in: [sandbox/expose/expose.ts:6](https://github.com/sebastianwessel/quickjs/blob/main/src/sandbox/expose/expose.ts#L6)
12+
13+
## Parameters
14+
15+
### scope
16+
17+
`Scope`
18+
19+
### ctx
20+
21+
`QuickJSContext` | `QuickJSAsyncContext`
22+
23+
### name
24+
25+
`string`
26+
27+
### input
28+
29+
`unknown`
30+
31+
## Returns
32+
33+
`QuickJSHandle`

‎website/api/functions/getModuleLoader.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / getModuleLoader
6+
7+
# Function: getModuleLoader()
8+
9+
> **getModuleLoader**(`fs`, `_runtimeOptions`): `JSModuleLoader`
10+
11+
Defined in: [sandbox/syncVersion/getModuleLoader.ts:7](https://github.com/sebastianwessel/quickjs/blob/main/src/sandbox/syncVersion/getModuleLoader.ts#L7)
12+
13+
## Parameters
14+
15+
### fs
16+
17+
`IFs`
18+
19+
### \_runtimeOptions
20+
21+
[`RuntimeOptions`](../type-aliases/RuntimeOptions.md)
22+
23+
## Returns
24+
25+
`JSModuleLoader`

‎website/api/functions/getSerializer.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / getSerializer
6+
7+
# Function: getSerializer()
8+
9+
> **getSerializer**(`name`): `undefined` \| [`Serializer`](../type-aliases/Serializer.md)
10+
11+
Defined in: [sandbox/handleToNative/serializer/index.ts:22](https://github.com/sebastianwessel/quickjs/blob/main/src/sandbox/handleToNative/serializer/index.ts#L22)
12+
13+
Get a Serializer by constructor name
14+
15+
## Parameters
16+
17+
### name
18+
19+
`string`
20+
21+
## Returns
22+
23+
`undefined` \| [`Serializer`](../type-aliases/Serializer.md)

‎website/api/functions/getTypescriptSupport.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
[**@sebastianwessel/quickjs v2.3.1**](../README.md)
2+
3+
***
4+
5+
[@sebastianwessel/quickjs](../globals.md) / getTypescriptSupport
6+
7+
# Function: getTypescriptSupport()
8+
9+
> **getTypescriptSupport**(`enabled`, `typescriptImportFile?`, `options?`): `Promise`\<\{ `transpileFile`: (`value`, `_compilerOptions?`, `_fileName?`, `_diagnostics?`, `_moduleName?`) => `string`; `transpileNestedDirectoryJSON`: (`mountFsJson`, `_option?`) => `NestedDirectoryJSON`; `transpileVirtualFs`: (`fs`, `_options?`) => `IFs`; \}\>
10+
11+
Defined in: [getTypescriptSupport.ts:18](https://github.com/sebastianwessel/quickjs/blob/main/src/getTypescriptSupport.ts#L18)
12+
13+
Add support for handling typescript files and code.
14+
Requires the optional dependency 'typescript'.
15+
16+
## Parameters
17+
18+
### enabled
19+
20+
`boolean` = `false`
21+
22+
### typescriptImportFile?
23+
24+
`string`
25+
26+
### options?
27+
28+
`CompilerOptions`
29+
30+
## Returns
31+
32+
`Promise`\<\{ `transpileFile`: (`value`, `_compilerOptions?`, `_fileName?`, `_diagnostics?`, `_moduleName?`) => `string`; `transpileNestedDirectoryJSON`: (`mountFsJson`, `_option?`) => `NestedDirectoryJSON`; `transpileVirtualFs`: (`fs`, `_options?`) => `IFs`; \}\>

0 commit comments

Comments
 (0)