doc: update doc

sebastianwessel · Jul 7, 2024 · f3c6833 · f3c6833
1 parent 4838770
commit f3c6833
Show file tree

Hide file tree

Showing 13 changed files with 617 additions and 96 deletions.
diff --git a/README.md b/README.md
@@ -1,22 +1,23 @@
-# QuickJS package
-
-**@sebastianwessel/quickjs: Execute JavaScript in a WebAssembly QuickJS Sandbox**
+# QuickJS - Execute JavaScript in a WebAssembly QuickJS Sandbox
 
 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.
 
 ## Features
 
 - **Security**: Run untrusted JavaScript code in a safe, isolated environment.
-- **Performance**: Benefit from the lightweight and efficient QuickJS engine.
-- **Versatility**: Easily integrate with existing TypeScript projects.
-- **Simplicity**: User-friendly API for executing and managing JavaScript code in the sandbox.
 - **File System**: Can mount a virtual file system
 - **Custom Node Modules**: Custom node modules are mountable
 - **Fetch Client**: Can provide a fetch client to make http(s) calls
 - **Test-Runner**: Includes a test runner and chai based `expect`
+- **Performance**: Benefit from the lightweight and efficient QuickJS engine.
+- **Versatility**: Easily integrate with existing TypeScript projects.
+- **Simplicity**: User-friendly API for executing and managing JavaScript code in the sandbox.
+
+**[View the full documentation](https://sebastianwessel.github.io/quickjs/)**
 
+**[Find examples in the repository](https://github.com/sebastianwessel/quickjs/tree/main/example)**
 
-## Usage
+## Basic Usage
 
 Here's a simple example of how to use the package:
 
@@ -28,7 +29,7 @@ import { quickJS } from '@sebastianwessel/quickjs'
 const { createRuntime } = await quickJS()
 
 // Create a runtime instance each time a js code should be executed
-const { evalCode } = await this.createRuntime({
+const { evalCode } = await createRuntime({
   allowFetch: true, // inject fetch and allow the code to fetch data
   allowFs: true, // mount a virtual file system and provide node:fs module
   env: {
@@ -58,59 +59,6 @@ export default await fn()
 console.log(result) // { ok: true, data: '<!doctype html>\n<html>\n[....]</html>\n' }
 ```
 
-### Runtime options
-
-```js
-type RuntimeOptions = {
-  /**
-   * Mount a virtual file system
-   * @link https://github.com/streamich/memfs
-   */
-  mountFs?: DirectoryJSON
-  /**
-   * Mount custom node_modules in a virtual file system
-   * @link https://github.com/streamich/memfs
-   */
-  nodeModules?: DirectoryJSON
-  /**
-   * Enable file capabilities
-   * If enabled, the package node:fs becomes available
-   */
-  allowFs?: boolean
-  /**
-   * Allow code to make http(s) calls.
-   * When enabled, the global fetch will be available
-   */
-  allowFetch?: boolean
-  /**
-   * Per default, the console log inside of QuickJS is passed to the host console log.
-   * Here, you can customize the handling and provide your own logging methods.
-   */
-  console?: {
-  log: (message?: unknown, ...optionalParams: unknown[]) => void
-  error: (message?: unknown, ...optionalParams: unknown[]) => void
-  warn: (message?: unknown, ...optionalParams: unknown[]) => void
-  }
-  /**
-   * Key-value list of ENV vars, which should be available in QuickJS
-   *
-   * @example
-   * ```js
-   * // in config
-   * {
-   *   env: {
-   *     My_ENV: 'my var'
-   *   }
-   * }
-   *
-   * // inside of QuickJS
-   * console.log(env.My_ENV) // outputs: my var
-   * ```
-   */
-  env?: Record<string, unknown>
-}
-```
-
 ## Credits
 
 This lib is based on:

diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,96 @@
+---
+title: QuickJS - Execute JavaScript in a WebAssembly QuickJS Sandbox
+description: Run custom javascript inside a webassembly runtime from your Javascript/Typescript application
+---
+
+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.
 
 - [Installation](./intallation.md)
 - Compatibility:
   - [Core Javascript](./core-js-compatibility.md)
   - [NodeJS](./node-compatibility.md)
+- [Runtime options](./runtime-options.md)
 - [Run Tests in QuickJS](./running-tests.md)
-- [Credits](./credits.md)
+- [Credits](./credits.md)
+
+## Features
+
+- **Security**: Run untrusted JavaScript code in a safe, isolated environment.
+- **File System**: Can mount a virtual file system
+- **Custom Node Modules**: Custom node modules are mountable
+- **Fetch Client**: Can provide a fetch client to make http(s) calls
+- **Test-Runner**: Includes a test runner and chai based `expect`
+- **Performance**: Benefit from the lightweight and efficient QuickJS engine.
+- **Versatility**: Easily integrate with existing TypeScript projects.
+- **Simplicity**: User-friendly API for executing and managing JavaScript code in the sandbox.
+
+**[View the full documentation](https://sebastianwessel.github.io/quickjs/)**
+
+**[Find examples in the repository](https://github.com/sebastianwessel/quickjs/tree/main/example)**
+
+## Basic Usage
+
+Here's a simple example of how to use the package:
+
+```typescript
+import { quickJS } from '@sebastianwessel/quickjs'
+
+// General setup like loading and init of the QuickJS wasm
+// It is a ressource intensive job and should be done only once if possible 
+const { createRuntime } = await quickJS()
+
+// Create a runtime instance each time a js code should be executed
+const { evalCode } = await createRuntime({
+  allowFetch: true, // inject fetch and allow the code to fetch data
+  allowFs: true, // mount a virtual file system and provide node:fs module
+  env: {
+    MY_ENV_VAR: 'env var value'
+  },
+})
+
+
+const result = await evalCode(`
+import { join } as path from 'path'
+
+const fn = async ()=>{
+  console.log(join('src','dist')) // logs "src/dist" on host system
+
+  console.log(env.MY_ENV_VAR) // logs "env var value" on host system
+
+  const url = new URL('https://example.com')
+
+  const f = await fetch(url)
+
+  return f.text()
+}
+  
+export default await fn()
+`)
+
+console.log(result) // { ok: true, data: '<!doctype html>\n<html>\n[....]</html>\n' }
+```
+
+## Credits
+
+This lib is based on:
+
+- [quickjs-emscripten](https://github.com/justjake/quickjs-emscripten)
+- [quickjs-emscripten-sync](https://github.com/reearth/quickjs-emscripten-sync)
+- [memfs](https://github.com/streamich/memfs)
+
+Tools used:
+
+- [Bun](https://bun.sh)
+- [Biome](https://biomejs.dev)
+- [Hono](https://hono.dev)
+- [poolifier-web-worker](https://github.com/poolifier/poolifier-web-worker)
+- [tshy](https://github.com/isaacs/tshy)
+- [autocannon](https://github.com/mcollina/autocannon)
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+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.
diff --git a/docs/core-js-compatibility.md b/docs/core-js-compatibility.md
@@ -1,33 +1,42 @@
-# Core Javascript Compatibility
+---
+title: Core JavaScript Compatibility
+description: The QuickJS sandbox has build in compatibility for the basic NodeJS/Javascript functions
+---
 
 - ✅ mostly [ES2023](https://test262.fyi/#%7Cqjs,qjs_ng)
 - ✅ ESM import support (custom modules supported)
 - ✅ top-level await
 
+## Supported Methods
+
 | Method                 | Supported |
 |------------------------|-----------|
-| process.env            | ✅ (customizeable)       |
-| console.log            | ✅        |
-| console.error          | ✅        |
-| console.warn           | ✅        |
-| console.info           | ✅        |
-| console.debug          | ✅        |
-| console.trace          | ✅        |
-| console.assert         | ✅        |
-| console.count          | ✅        |
-| console.countReset     | ✅        |
-| console.dir            | ✅        |
-| console.dirxml         | ✅        |
-| console.group          | ✅        |
-| console.groupCollapsed | ✅        |
-| console.groupEnd       | ✅        |
-| console.table          | ✅        |
-| console.time           | ✅        |
-| console.timeEnd        | ✅        |
-| console.timeLog        | ✅        |
-| console.clear          | ✅        |
-| setTimeout             | ✅        |
-| clearTimeout           | ✅        |
-| setInterval            | ✅        |
-| clearInterval          | ✅        |
-| fetch                  | ✅ (set allowFetch=true)       |
+| `process.env`          | ✅ (customizable) |
+| `console.log`          | ✅ (customizable) |
+| `console.error`        | ✅ (customizable) |
+| `console.warn`         | ✅ (customizable) |
+| `console.info`         | ✅ (customizable) |
+| `console.debug`        | ✅ (customizable) |
+| `console.trace`        | ✅ (customizable) |
+| `console.assert`       | ✅ (customizable) |
+| `console.count`        | ✅ (customizable) |
+| `console.countReset`   | ✅ (customizable) |
+| `console.dir`          | ✅ (customizable) |
+| `console.dirxml`       | ✅ (customizable) |
+| `console.group`        | ✅ (customizable) |
+| `console.groupCollapsed` | ✅ (customizable) |
+| `console.groupEnd`     | ✅ (customizable) |
+| `console.table`        | ✅ (customizable) |
+| `console.time`         | ✅ (customizable) |
+| `console.timeEnd`      | ✅ (customizable) |
+| `console.timeLog`      | ✅ (customizable) |
+| `console.clear`        | ✅ (customizable) |
+| `setTimeout`           | ✅ |
+| `clearTimeout`         | ✅ |
+| `setInterval`          | ✅ |
+| `clearInterval`        | ✅ |
+| `fetch`                | ✅ (set `allowFetch=true`) |
+
+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. 
+
+For more information, refer to the [ES2023 compatibility tests](https://test262.fyi/#%7Cqjs,qjs_ng).
diff --git a/docs/intallation.md b/docs/intallation.md
@@ -1,4 +1,8 @@
-# Installation
+---
+title: Installation of @sebastianwessel/quickjs
+description: The QuickJS sandbox has build in compatibility for the basic NodeJS/Javascript functions
+---
+
 
 Install the package using npm, yarn, or bun:
 

diff --git a/docs/node-compatibility.md b/docs/node-compatibility.md
@@ -1,4 +1,7 @@
-# Node compatibility
+---
+title: Node compatibility
+description: This library provides basic support most common node core packages.
+---
 
 ## node:fs