Merge pull request #5 from sebastianwessel/improve_doc_and_code_cleanup

chore: Improve doc and code cleanup

Author: sebastianwessel

.vscode/settings.json

@@ -46,7 +46,7 @@
 		"mix.exs": ".credo.exs, .dialyzer_ignore.exs, .formatter.exs, .iex.exs, .tool-versions, mix.lock",
 		"next.config.*": "*.env, .babelrc*, .codecov, .cssnanorc*, .env.*, .envrc, .htmlnanorc*, .lighthouserc.*, .mocha*, .postcssrc*, .terserrc*, api-extractor.json, ava.config.*, babel.config.*, capacitor.config.*, contentlayer.config.*, cssnano.config.*, cypress.*, env.d.ts, formkit.config.*, formulate.config.*, histoire.config.*, htmlnanorc.*, i18n.config.*, ionic.config.*, jasmine.*, jest.config.*, jsconfig.*, karma*, lighthouserc.*, next-env.d.ts, next-i18next.config.*, panda.config.*, playwright.config.*, postcss.config.*, puppeteer.config.*, rspack.config.*, sst.config.*, svgo.config.*, tailwind.config.*, tsconfig.*, tsdoc.*, uno.config.*, unocss.config.*, vitest.config.*, vuetify.config.*, webpack.config.*, windi.config.*",
 		"nuxt.config.*": "*.env, .babelrc*, .codecov, .cssnanorc*, .env.*, .envrc, .htmlnanorc*, .lighthouserc.*, .mocha*, .nuxtignore, .nuxtrc, .postcssrc*, .terserrc*, api-extractor.json, ava.config.*, babel.config.*, capacitor.config.*, contentlayer.config.*, cssnano.config.*, cypress.*, env.d.ts, formkit.config.*, formulate.config.*, histoire.config.*, htmlnanorc.*, i18n.config.*, ionic.config.*, jasmine.*, jest.config.*, jsconfig.*, karma*, lighthouserc.*, panda.config.*, playwright.config.*, postcss.config.*, puppeteer.config.*, rspack.config.*, sst.config.*, svgo.config.*, tailwind.config.*, tsconfig.*, tsdoc.*, uno.config.*, unocss.config.*, vitest.config.*, vuetify.config.*, webpack.config.*, windi.config.*",
-		"package.json": ".browserslist*, .circleci*, .commitlint*, .cz-config.js, .czrc, .dlint.json, .dprint.json*, .editorconfig, .eslint*, .firebase*, .flowconfig, .github*, .gitlab*, .gitmojirc.json, .gitpod*, .huskyrc*, .jslint*, .knip.*, .lintstagedrc*, .markdownlint*, .node-version, .nodemon*, .npm*, .nvmrc, .pm2*, .pnp.*, .pnpm*, .prettier*, .pylintrc, .release-please*.json, .releaserc*, .ruff.toml, .sentry*, .simple-git-hooks*, .stackblitz*, .styleci*, .stylelint*, .tazerc*, .textlint*, .tool-versions, .travis*, .versionrc*, .vscode*, .watchman*, .xo-config*, .yamllint*, .yarnrc*, Procfile, apollo.config.*, appveyor*, azure-pipelines*, biome.json*, bower.json, build.config.*, bun.lockb, commitlint*, crowdin*, dangerfile*, dlint.json, dprint.json*, electron-builder.*, eslint*, firebase.json, grunt*, gulp*, jenkins*, knip.*, lerna*, lint-staged*, nest-cli.*, netlify*, nodemon*, npm-shrinkwrap.json, nx.*, package-lock.json, package.nls*.json, phpcs.xml, pm2.*, pnpm*, prettier*, pullapprove*, pyrightconfig.json, release-please*.json, release-tasks.sh, release.config.*, renovate*, rollup.config.*, rspack*, ruff.toml, simple-git-hooks*, sonar-project.properties, stylelint*, tslint*, tsup.config.*, turbo*, typedoc*, unlighthouse*, vercel*, vetur.config.*, webpack*, workspace.json, wrangler.toml, xo.config.*, yarn*, tsconfig.json",
+		"package.json": "jsr.json, .browserslist*, .circleci*, .commitlint*, .cz-config.js, .czrc, .dlint.json, .dprint.json*, .editorconfig, .eslint*, .firebase*, .flowconfig, .github*, .gitlab*, .gitmojirc.json, .gitpod*, .huskyrc*, .jslint*, .knip.*, .lintstagedrc*, .markdownlint*, .node-version, .nodemon*, .npm*, .nvmrc, .pm2*, .pnp.*, .pnpm*, .prettier*, .pylintrc, .release-please*.json, .releaserc*, .ruff.toml, .sentry*, .simple-git-hooks*, .stackblitz*, .styleci*, .stylelint*, .tazerc*, .textlint*, .tool-versions, .travis*, .versionrc*, .vscode*, .watchman*, .xo-config*, .yamllint*, .yarnrc*, Procfile, apollo.config.*, appveyor*, azure-pipelines*, biome.json*, bower.json, build.config.*, bun.lockb, commitlint*, crowdin*, dangerfile*, dlint.json, dprint.json*, electron-builder.*, eslint*, firebase.json, grunt*, gulp*, jenkins*, knip.*, lerna*, lint-staged*, nest-cli.*, netlify*, nodemon*, npm-shrinkwrap.json, nx.*, package-lock.json, package.nls*.json, phpcs.xml, pm2.*, pnpm*, prettier*, pullapprove*, pyrightconfig.json, release-please*.json, release-tasks.sh, release.config.*, renovate*, rollup.config.*, rspack*, ruff.toml, simple-git-hooks*, sonar-project.properties, stylelint*, tslint*, tsup.config.*, turbo*, typedoc*, unlighthouse*, vercel*, vetur.config.*, webpack*, workspace.json, wrangler.toml, xo.config.*, yarn*, tsconfig.json",
 		"Pipfile": ".editorconfig, .flake8, .isort.cfg, .python-version, Pipfile, Pipfile.lock, requirements*.in, requirements*.pip, requirements*.txt, tox.ini",
 		"pubspec.yaml": ".metadata, .packages, all_lint_rules.yaml, analysis_options.yaml, build.yaml, pubspec.lock, pubspec_overrides.yaml",
 		"pyproject.toml": ".commitlint*, .dlint.json, .dprint.json*, .editorconfig, .eslint*, .flake8, .flowconfig, .isort.cfg, .jslint*, .lintstagedrc*, .markdownlint*, .pdm-python, .pdm.toml, .prettier*, .pylintrc, .python-version, .ruff.toml, .stylelint*, .textlint*, .xo-config*, .yamllint*, MANIFEST.in, Pipfile, Pipfile.lock, biome.json*, commitlint*, dangerfile*, dlint.json, dprint.json*, eslint*, hatch.toml, lint-staged*, pdm.lock, phpcs.xml, poetry.lock, poetry.toml, prettier*, pyproject.toml, pyrightconfig.json, requirements*.in, requirements*.pip, requirements*.txt, ruff.toml, setup.cfg, setup.py, stylelint*, tox.ini, tslint*, xo.config.*",

docs/README.md

@@ -5,6 +5,11 @@ This TypeScript package allows you to safely execute JavaScript code within a We
 ## Documentation
 
 - [Installation](./intallation.md)
+- Usage and Best Practice:
+  - [Basic understanding](./basic.md)
+  - [Fetch in Guest System](./fetch.md)
+  - [Custom Node Modules](./custom-modules.md)
+  - [Custom File System](./custom-file-system.md)
 - Compatibility:
   - [Core Javascript](./core-js-compatibility.md)
   - [NodeJS](./node-compatibility.md)

docs/about.md

@@ -0,0 +1,274 @@
+---
+title: Basic Understanding
+description: Get a basic understanding on how to the QuickJS module works
+---
+
+This documentation provides essential information to help you avoid common pitfalls when working with QuickJS WebAssembly runtime. The terms "host" and "guest" are used to describe your main application and the QuickJS runtime, respectively.
+
+## Synchronous Execution
+
+### Blocking the JavaScript Event Loop
+
+When the `eval` method is called on the host, the event loop of the host system is blocked until the method returns.
+
+Here is an example of how the host system can be blocked 🔥:
+
+```typescript
+import { quickJS } from '@sebastianwessel/quickjs'
+
+const { createRuntime } = await quickJS()
+const { evalCode } = await createRuntime()
+
+setInterval(() => {
+  console.log('y')
+}, 2000)
+
+console.log('start')
+
+const result = await evalCode(`
+const fn = () => new Promise(() => {
+  while(true) {
+  }
+})
+export default await fn()
+`)
+```
+
+You might expect that this code does not block the host system, but it does, even with `await evalCode`. The host system must wait for the guest system to return a value. In this example, the value is never returned because of the endless while-loop.
+
+### Setting Execution Timeouts
+
+**❗ Set Execution Timeouts if Possible**  
+It is highly recommended to set a default timeout value to avoid blocking the host system indefinitely. The execution timeout can be set in the options of `createRuntime` and `evalCode`. The smaller value between the two functions will be chosen. Setting the `executionTimeout` to `0` or `undefined` disables the execution timeout.
+
+Timeout values are in seconds for better readability.
+
+### Workers and Threads
+
+It is **highly recommended** to run the guest system in separate workers or threads rather than the main thread. This approach has several critical benefits:
+
+1. It ensures that the main event loop is not blocked.
+2. Multiple workers can boost performance.
+3. The host application can terminate a single worker anytime. If the guest system exceeds the maximum runtime, restarting the worker ensures a clean state.
+
+## Asynchronous Behavior
+
+The provided QuickJS WebAssembly runtime does not have an internal event loop like a regular runtime. Instead, the host system must trigger the loop for any provided promises. This library starts an interval on the host that triggers `executePendingJobs` in QuickJS. The interval is automatically stopped and removed when no longer needed.
+
+When a promise is provided by the host and used by the client, the client executes until it reaches the promise. If the promise is not settled, the QuickJS runtime pauses execution. Once the promise is settled, the host needs to call `executePendingJobs` to instruct QuickJS to resume execution.
+
+## Data Exchange Between Host and Guest
+
+### Host to Guest
+
+The host system can provide various data types to the guest system, including primitives, objects, functions, and promises. This library uses an `env` pattern for data and functions provided by the host, which is mirrored to `process.env` inside the guest system.
+
+Example:
+
+```typescript
+import { quickJS } from '@sebastianwessel/quickjs'
+
+const { createRuntime } = await quickJS()
+
+const keyValueStoreOnHost = new Map<string, string>()
+
+const { evalCode } = await createRuntime({
+  env: {
+    MY_PROCESS_ENV: 'some environment variable provided by the host',
+    KV: {
+      set: (key: string, value: string) => keyValueStoreOnHost.set(key, value),
+      get: (key: string) => keyValueStoreOnHost.get(key),
+    },
+  },
+})
+
+const result = await evalCode(`
+console.log(env.MY_PROCESS_ENV)
+env.KV.set('guest-key', 'value set by guest system')
+const value = env.KV.get('guest-key')
+export default value
+`)
+
+console.log('result from guest:', result.data) // result from guest: value set by guest system
+console.log('result from host:', keyValueStoreOnHost.get('guest-key')) // result from host: value set by guest system
+```
+
+#### Wrapping Functions
+
+If a function is provided from host to guest, it should be wrapped in a dummy function.
+
+👎 **Incorrect**:
+
+```typescript
+const { evalCode } = await createRuntime({
+  env: {
+    KV: {
+      set: keyValueStoreOnHost.set,
+      get: keyValueStoreOnHost.get,
+    },
+  },
+})
+```
+
+👍 **Correct**:
+
+```typescript
+const { evalCode } = await createRuntime({
+  env: {
+    KV: {
+      set: (key: string, value: string) => keyValueStoreOnHost.set(key, value),
+      get: (key: string) => keyValueStoreOnHost.get(key),
+    },
+  },
+})
+```
+
+**🚨 Security Information ‼️**  
+The host system only provides the given values but never reads them back. Even if the guest system modifies `env.KV.set`, it will not impact the host side.
+
+Example:
+
+```typescript
+import { quickJS } from '@sebastianwessel/quickjs'
+
+const { createRuntime } = await quickJS()
+const keyValueStoreOnHost = new Map<string, string>()
+
+const { evalCode } = await createRuntime({
+  env: {
+    KV: {
+      set: (key: string, value: string) => keyValueStoreOnHost.set(key, value),
+      get: (key: string) => keyValueStoreOnHost.get(key),
+    },
+  },
+})
+
+const result = await evalCode(`
+env.KV.set('guest-key', 'value set by guest system')
+const value = env.KV.get('guest-key')
+env.KV.get = () => { throw new Error('Security!!!') }
+export default value
+`)
+
+console.log('result from guest:', result)
+console.log('result from host:', keyValueStoreOnHost.get('guest-key'))
+```
+
+### Guest to Host
+
+#### Usage of Return Value
+
+The guest system can return a final value using `export default`. The library sets the execution mode to `module`, expecting the executed script to provide its return value via `export default`.
+
+Example:
+
+```typescript
+import { quickJS } from '@sebastianwessel/quickjs'
+
+const { createRuntime } = await quickJS()
+const { evalCode } = await createRuntime()
+
+const result = await evalCode(`
+export default 'my value'
+`)
+
+console.log('result from guest:', result.data) // result from guest: my value
+```
+
+**❗ Promises Must Be Awaited**  
+If the executed script returns a promise, the promise must be awaited.
+
+👎 **Incorrect**:
+
+```typescript
+import { quickJS } from '@sebastianwessel/quickjs'
+
+const { createRuntime } = await quickJS()
+const { evalCode } = await createRuntime()
+
+const result = await evalCode(`
+const prom = async () => {
+  return 'my value'
+}
+export default prom() // promise is not awaited!!
+`)
+
+console.log('result from guest:', result.data) // result from guest: my value
+```
+
+👍 **Correct**:
+
+```typescript
+import { quickJS } from '@sebastianwessel/quickjs'
+
+const { createRuntime } = await quickJS()
+const { evalCode } = await createRuntime()
+
+const result = await evalCode(`
+const prom = async () => {
+  return 'my value'
+}
+export default await prom() // promise is awaited
+`)
+
+console.log('result from guest:', result.data) // result from guest: my value
+```
+
+The library wraps the result of the `eval` method into a result object, similar to the result of the `fetch` method. This makes handling success and error paths easier for developers.
+
+A success response:
+
+```typescript
+{
+  ok: true,
+  data: 'the return value'
+}
+```
+
+An error response:
+
+```typescript
+{
+  ok: false,
+  isSyntaxError: true,
+  error: {
+    name: "SyntaxError",
+    message: "unexpected end of string",
+    stack: "    at /src/index.js:9:1\n",
+  }
+}
+```
+
+#### Using Provided Env-Functions
+
+It is also possible to exchange values between client and host, while the guest system is running. Therefor, the recommended approach is to call functions, provided by the host, from the client system.
+Here, async functions are supported as well.
+
+#### Setting Values in Host by Guest System (Not Recommended!)
+
+The guest system can change the values in an object provided by the host. Although possible, this pattern is not recommended. Instead, provide functions to mutate the object or array on the host side, allowing for validation and additional functionality like emitting events. This approach keeps the control on the host side.
+
+Example of exchanging data by changing an object's key-value:
+
+```typescript
+import { quickJS } from '@sebastianwessel/quickjs'
+
+const { createRuntime } = await quickJS()
+const dangerousSync = {
+  mutable: 'init value',
+}
+
+const { evalCode } = await createRuntime({
+  dangerousSync,
+})
+
+await evalCode(`
+__dangerousSync.mutable = 'changed by guest'
+`)
+
+console.log(dangerousSync)
+```
+
+**🚨 Security Advice ‼️**
+
+As the guest system can access and potentially overwrite the values provided by the host, ensure that these values do not affect security. Do not provide functions and make sure the provided values are secure.

docs/basic.md

@@ -0,0 +1,6 @@
+---
+title: Custom File System
+description: Learn, how you can mount your own virtual file system into the QuickJS runtime
+---
+
+documentation soon.