First stab at JS/TS scripting documentation.

README.md

@@ -8,8 +8,8 @@
 
 <p align="center">
   A <a href="https://trailbase.io/reference/benchmarks/">blazingly</a> fast,
-  single-file, open-source application server with type-safe APIs, Auth, and
-  Admin UI built on Rust+SQLite.
+  single-file, open-source application server with type-safe APIs, built-in
+  JS/ES6/TS Runtime, Auth, and Admin UI built on Rust+SQLite+V8.
 <p>
 
 <p align="center">

client/testfixture/scripts/index.ts

@@ -1,4 +1,4 @@
-import { addRoute, parsePath, query, htmlHandler, jsonHandler, stringHandler, HttpError } from "../trailbase.js";
+import { addRoute, parsePath, query, htmlHandler, jsonHandler, stringHandler, HttpError, StatusCodes } from "../trailbase.js";
 import type { JsonRequestType, ParsedPath, StringRequestType } from "../trailbase.d.ts";
 
 addRoute("GET", "/test", stringHandler(async (req: StringRequestType) => {
@@ -45,5 +45,5 @@ addRoute("GET", "/json", jsonHandler((_req: JsonRequestType) => {
 }));
 
 addRoute("GET", "/error", jsonHandler((_req: JsonRequestType) => {
-  throw new HttpError(418, "I'm a teapot");
+  throw new HttpError(StatusCodes.IM_A_TEAPOT, "I'm a teapot");
 }));

client/trailbase-dart/README.md

@@ -1,8 +1,8 @@
 # TrailBase client library for Dart and Flutter
 
 TrailBase is a [blazingly](https://trailbase.io/reference/benchmarks/) fast,
-single-file, open-source application server with type-safe APIs, Auth, and
-Admin UI built on Rust+SQLite.
+single-file, open-source application server with type-safe APIs, built-in
+JS/ES6/TS Runtime, Auth, and Admin UI built on Rust+SQLite+V8.
 
 For more context, documentation, and an online demo, check out our website
 [trailbase.io](https://trailbase.io).

client/trailbase-ts/README.md

@@ -1,8 +1,8 @@
 # JS/TS client for TrailBase
 
 TrailBase is a [blazingly](https://trailbase.io/reference/benchmarks/) fast,
-single-file, open-source application server with type-safe APIs, Auth, and
-Admin UI built on Rust+SQLite.
+single-file, open-source application server with type-safe APIs, built-in
+JS/ES6/TS Runtime, Auth, and Admin UI built on Rust+SQLite+V8.
 
 For more context, documentation, and an online demo, check out our website
 [trailbase.io](https://trailbase.io).

docs/src/content/docs/_roadmap.md

@@ -12,7 +12,6 @@ For context, some larger features we have on our Roadmap:
 - Service-accounts for authenticating and authorizing backends not end-users.
 - Custom scheduled operations. Also enabling more time series use-cases.
 - Many SQLite databases: imagine a separate database by tenant or user.
-- Maybe integrate an ES6 JavaScript runtime or similar.
 - Streamline code-generation, the bindings life-cycle, and first-party
   support for more languages.
 - Maybe TLS termination and proxy capabilities.

docs/src/content/docs/documentation/APIs/js_apis.mdx

@@ -0,0 +1,58 @@
+---
+title: JS/TS APIs
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+You can place JavaScript and TypeScript into `traildepot/scripts` and TrailBase
+will automatically load them on startup.
+For now we support custom HTTP handlers letting you register routes, act on
+requests, query the database and build arbitrary responses.
+
+## Runtime
+
+Before we jump into details, let's quickly talk about the runtime itself. At
+its heart, it's a pool of V8-js-engines alongside a runtime that supports basic
+tasks such as file I/O, web requests, timers, etc.
+However, it is *not* a complete Node.js runtime, at least for now, since it
+would pull in a lot of extra dependencies.
+Note further, that the pool of workers/isolates does not share state, i.e. you
+cannot use global state to reliably share state across requests. You should
+rely on the database for persisting and sharing state.
+
+## Http Endpoints
+
+The following example illustrates a few things:
+
+* Hot to register a parameterized route with `:table`.
+* How implement a handler that returns `text/plain` content. There is also
+  `jsonHandler` and `htmlHandler`.
+* How to query the database.
+* How to return an error.
+
+```js
+import {
+  addRoute,
+  query,
+  stringHandler,
+  HttpError,
+  StatusCodes
+} from "../trailbase.js";
+
+addRoute("GET", "/test/:table", stringHandler(async (req) => {
+  const table = req.params["table"];
+  if (table) {
+    const rows = await query(`SELECT COUNT(*) FROM ${table}`, [])
+    return `entries: ${rows[0][0]}`;
+  }
+
+  throw new HttpError(StatusCodes.BAD_REQUEST, "Missing '?table=' search query parm");
+}));
+```
+
+More examples can be found in the repository in
+`client/testfixture/scripts/index.ts`.
+
+<Aside type="note" title="ToDO">
+  Needs more extensive documentation.
+</Aside>

docs/src/content/docs/documentation/extending.mdx

@@ -67,9 +67,13 @@ TrailBase provides three main ways to embed your code and expose custom APIs:
 Beware that the Rust APIs and [Query APIs](/documentation/apis/query_apis/) are
 likely subject to change. We rely on semantic versioning to explicitly signal
 breaking changes.
-Eventually, we would like to lower the barrier of entry by providing stable
-bindings to a higher-level runtime within TrailBase, likely a
-TypeScript/ES6/JavaScript runtime.
+
+### Using ES6 JavaScript & TypeScript
+
+You can write custom HTTP endpoints using both full ES6 JavaScript and/or
+TypeScript. TrailBase will transpile your code on the fly and execute it on a
+speedy V8-engine, the same engine found across Chrome, node.js and deno.
+More information can be found in the [API docs](/documentation/apis/js_apis/).
 
 ### Using Rust
 

docs/src/content/docs/index.mdx

@@ -1,9 +1,9 @@
 ---
 title: Welcome to TrailBase
-description: Blazingly fast, single-file, open-source server for your Applications
+description: A blazingly fast, single-file, open-source application server with type-safe APIs, built-in JS/ES6/TS Runtime, Auth, and Admin UI built on Rust+SQLite+V8
 template: splash
 hero:
-  tagline: A blazingly fast, single-file, open-source application server with type-safe APIs, Auth, and Admin UI built on Rust+SQLite
+  tagline: A blazingly fast, single-file, open-source application server with type-safe APIs, built-in JS/ES6/TS Runtime, Auth, and Admin UI built on Rust+SQLite+V8
   image:
     file: ../../assets/logo_512.webp
   actions:
@@ -81,10 +81,12 @@ import { Duration100kInsertsChart } from "./reference/_benchmarks/benchmarks.tsx
       * Rust: one of the lowest overhead languages,
       * Axum: one of the fastest HTTP servers,
       * SQLite/Libsql: one of the fastest full-SQL databases.
+      * V8: one of the fastest JS runtimes
 
-      TrailBase is [6-7x faster than PocketBase and 15x faster than SupaBase
+      TrailBase APIs are [6-7x faster than PocketBase and 15x faster than SupaBase
       needing only a fraction of the footprint](/reference/benchmarks), allowing
       you to serve millions of customers from a tiny box.
+      TrailBase JS runtime is ~45x faster than PocketBase's.
     </Card>
 
     <Card title="Simple" icon="heart">
@@ -108,7 +110,7 @@ import { Duration100kInsertsChart } from "./reference/_benchmarks/benchmarks.tsx
     </Card>
 
     <Card title="Authentication" icon="open-book">
-      TrailBase comes with an authentication system and UI built-in supporting
+      TrailBase comes with an authentication system and UI built in supporting
       both password-based and Social/OAuth (Google, Discord, ...) sign-ups.
 
       TrailBase authentication system follows standards and best-practices
@@ -119,7 +121,9 @@ import { Duration100kInsertsChart } from "./reference/_benchmarks/benchmarks.tsx
 
     <Card title="APIs & File Storage" icon="random">
       Provide access to your tables and views through fast, flexible and
-      **type-safe** restful CRUD APIs.
+      **type-safe** restful CRUD APIs. Extend functionality using a fast V8
+      JS/ES6 runtime with built-in support for TypeScript.
+
       Authorize users based on ACLs and SQL access rules letting you
       easily build higher-level access management or moderation facilities
       like groups or capabilities.

docs/src/content/docs/reference/benchmarks.mdx

@@ -156,6 +156,20 @@ being roughly 5x longer than therr p50.
 Slower insertions can take north of 100ms. There may or may not be a connection
 to the variability in CPU utilization we've seen above.
 
+## JavaScript-Runtime Benchmarks
+
+The [benchmarks](https://github.com/trailbaseio/trailbase-benchmark)
+implement a custom HTTP endpoint `/fibonacci?n=<N>` to calculate Fibonacci
+numbers, both for PocketBase and TrailBase.
+We use Fibonacci numbers as a proxy for computationally heavy workloads to
+primarily benchmark the performance of the underlying JavaScript engines:
+[goja](https://github.com/dop251/goja) for PocketBase and V8 for TrailBase.
+In other words, any difference in performance is dominated by the engines'
+performance rather than PocketBase or TrailBase themselves.
+
+We found that for `fib(40)` V8 (TrailBase) is around *45x faster* than
+goja (PocketBase).
+
 ## Final Words
 
 We're very happy to confirm that TrailBase is quick. The significant