Clean up examples and tutorials as well as minor doc tweaks.

Also add a reconnect loop to collab clicker.

README.md

@@ -13,7 +13,7 @@
 <p>
 
 <p align="center">
-  Simplify with fewer moving parts: an easy to self-host, single-file,
+  Simplify with fewer moving parts: an easy to self-host, single-executable,
   extensible backend for your mobile, web or desktop application.
   Sub-millisecond latencies eliminate the need for dedicated caches, no more
   stale or inconsistent data.

docs/astro.config.mjs

@@ -37,12 +37,17 @@ export default defineConfig({
               slug: "getting-started/starting-up",
             },
             {
-              label: "First App",
-              slug: "getting-started/first-ui-app",
-            },
-            {
-              label: "A CLI App",
-              slug: "getting-started/first-cli-app",
+              label: "Tutorials",
+              items: [
+                {
+                  label: "API, Vector Search & UI",
+                  slug: "getting-started/first-ui-app",
+                },
+                {
+                  label: "Data CLI",
+                  slug: "getting-started/first-cli-app",
+                },
+              ],
             },
             {
               label: "Philosophy",

docs/src/content/docs/comparison/pocketbase.mdx

@@ -3,9 +3,9 @@ title: PocketBase
 description: Comparing TrailBase & PocketBase.
 ---
 
-Firstly, PocketBase is amazing! It based the trail for single-file, SQLite
-application bases, is incredibly easy-to-use, and a polished experience. Gani,
-the person behind it, is a mad scientist.
+Firstly, PocketBase is amazing! It based the trail for single-executable,
+SQLite application bases, is incredibly easy-to-use, and a polished
+experience. Gani, the person behind it, is a mad scientist.
 
 At the surface-level there are a lot of similarities between PocketBase and
 TrailBase. In this comparison, we'll dive a little deeper and have a closer
@@ -49,6 +49,7 @@ Likewise, TrailBase has a few nifty tricks up its sleeve:
   being enforced all the way down to the database level[^4].
 - TrailBase's JavaScript runtime supports full ES6, TypeScript transpilation,
   and is built on V8 making it [~40x faster](/reference/benchmarks/#javascript-performance).
+  Supporting ES makes it easier to integrate popular JS frameworks for SSR.
 - First-class access to all of SQLite's features and capabilities.
 - A simple auth UI.
 - Stateless JWT auth-tokens for simple, hermetic authentication in other

docs/src/content/docs/getting-started/first-cli-app.mdx

@@ -6,7 +6,7 @@ import { Code } from "@astrojs/starlight/components";
 import { Aside } from "@astrojs/starlight/components";
 
 In this tutorial, we'll set up a database with an IMDB test dataset, spin up
-TrailBase and write a simple client CLI application to access the data using
+TrailBase and write a simple client CLI application to query the data using
 *Record APIs*.
 
 In an effort to demonstrate TrailBase's loose coupling and the possibility of
@@ -161,12 +161,12 @@ version and copy&paste the JSON schema from above.
 With the generated types, we can use the TrailBase TypeScript client to write
 the following program:
 
-import fillCode from "@root/examples/tutorial/scripts/src/fill.ts?raw";
+import fillCode from "@root/examples/data-cli-tutorial/src/fill.ts?raw";
 
 <Code
   code={fillCode}
   lang="ts"
-  title={"examples/tutorial/scripts/src/fill.ts"}
+  title={"examples/data-cli-tutorial/src/fill.ts"}
   mark={[]}
 />
 

docs/src/content/docs/getting-started/first-ui-app.mdx

@@ -13,7 +13,7 @@ production-ready web app all in ~100 lines of code.
 
 <div class="flex justify-center">
   <div class="w-[80%] shadow-lg	 ">
-    ![screenshot](../../../../../examples/coffeesearch/assets/screenshot.png)
+    ![screenshot](../../../../../examples/coffee-vector-search/assets/screenshot.png)
   </div>
 </div>
 
@@ -24,7 +24,7 @@ can be downloaded to follow along by running:
 
 ```bash
 $ git clone https://github.com/trailbaseio/trailbase.git
-$ cd trailbase/examples/coffeesearch
+$ cd trailbase/examples/coffee-vector-search
 ```
 
 import GettingTrailBase from "./_getting_trailbase.md";
@@ -37,15 +37,15 @@ import GettingTrailBase from "./_getting_trailbase.md";
 
 Before building the app, let's import some data. Keeping it simple,
 we'll use the `sqlite3` CLI[^1] directly to import
-`examples/coffeesearch/arabica_data_cleaned.csv` with the following SQL
+`examples/coffee-vector-search/arabica_data_cleaned.csv` with the following SQL
 script:
 
-import importScript from "@root/examples/coffeesearch/import.sql?raw";
+import importScript from "@root/examples/coffee-vector-search/import.sql?raw";
 
 <Code
   code={importScript}
   lang="sql"
-  title={"examples/coffeesearch/import.sql"}
+  title={"examples/coffee-vector-search/import.sql"}
   mark={[]}
 />
 
@@ -54,7 +54,7 @@ Note that we didn't initialize the vector `embedding`. This is merely because
 We'll update the entries later on, adding the embedding as part of our initial
 database migrations[^2].
 
-From within the `example/coffeesearch` directory, you can execute the script
+From within the `example/coffee-vector-search` directory, you can execute the script
 above and import the coffee data by running:
 
 ```bash
@@ -91,16 +91,16 @@ Any time you start `trail run`[^3], JavaScript and TypeScript files under
 </Aside>
 
 We can use this to register custom HTTP API routes among other things.
-Let's have a quick look at `examples/coffeesearch/traildepot/scripts/main.ts`,
+Let's have a quick look at `examples/coffee-vector-search/traildepot/scripts/main.ts`,
 which defines a `/search` API route we'll later use in our application to
 find coffees most closely matching our desired coffee notes:
 
-import handlerCode from "@root/examples/coffeesearch/traildepot/scripts/main.ts?raw";
+import handlerCode from "@root/examples/coffee-vector-search/traildepot/scripts/main.ts?raw";
 
 <Code
   code={handlerCode}
   lang="ts"
-  title={"examples/coffeesearch/traildepot/scripts/main.ts"}
+  title={"examples/coffee-vector-search/traildepot/scripts/main.ts"}
   mark={[]}
 />
 
@@ -141,12 +141,12 @@ framework, e.g.: `npm create vite@latest my-project -- --template react`.
 Our provided reference implementation, renders 4 numeric input fields to search
 for coffee with a certain aroma, flavor, acidity and sweetness score:
 
-import uiCode from "../../../../../examples/coffeesearch/src/App.tsx?raw";
+import uiCode from "../../../../../examples/coffee-vector-search/src/App.tsx?raw";
 
 <Code
   code={uiCode}
   lang="ts"
-  title={"examples/coffeesearch/src/App.tsx"}
+  title={"examples/coffee-vector-search/src/App.tsx"}
   mark={[]}
 />
 
@@ -190,7 +190,7 @@ depending on a pyramid of shared libraries or requiring other services to be up
 and running like a separate database server.
 This makes it very easy to just copy the files over to your server or bundle
 everything in a single container.
-`examples/coffeesearch/Dockerfile` is an example of how you can both build and
+`examples/coffee-vector-search/Dockerfile` is an example of how you can both build and
 bundle using Docker. In fact,
 
 ```

docs/src/content/docs/index.mdx

@@ -103,9 +103,9 @@ import { Duration100kInsertsChart } from "./reference/_benchmarks/benchmarks.tsx
   <CardGrid>
 
     <Card title="Simple" icon="heart">
-      TrailBase is a small, single file, static binary that is incredibly easy
-      to deploy **consistently** across integration testing, development, pre-prod,
-      and production environments including edge.
+      TrailBase is a small static binary that is incredibly easy to deploy
+      **consistently** across integration testing, development, pre-prod, and
+      production environments including edge.
       Architecturally, TrailBase aims to be a simple, thin abstraction around
       standards helping full or piece-meal adoption and avoiding lock-in.
 

examples/coffeesearch/package.json → examples/coffee-vector-search/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "coffeesearch",
+  "name": "coffee-vector-search",
   "private": true,
   "version": "0.1.0",
   "type": "module",

examples/ssr/Makefile → examples/collab-clicker-ssr/Makefile

@@ -1,5 +1,5 @@
 TRAILBIN ?= RUST_BACKTRACE=1 cargo run --
-DISTDIR := solid-ssr-app/dist
+DISTDIR := dist
 
 run: traildepot/scripts/entry-server.js
 	${TRAILBIN} --data-dir=traildepot run --public-dir=${DISTDIR}/client
@@ -8,9 +8,9 @@ traildepot/scripts/entry-server.js: ${DISTDIR}/server/entry-server.js
 	cp $< $@
 
 ${DISTDIR}/server/entry-server.js:
-	cd solid-ssr-app; pnpm run build
+	pnpm run build
 
 clean:
-	rm -rf solid-ssr-app/dist
+	rm -rf dist
 
 .PHONY: run clean

examples/ssr/solid-ssr-app/eslint.config.mjs → examples/collab-clicker-ssr/eslint.config.mjs

@@ -6,7 +6,7 @@ export default [
   pluginJs.configs.recommended,
   ...tseslint.configs.recommended,
   {
-    ignores: ["dist/", "node_modules/"],
+    ignores: ["dist/", "node_modules/", "traildepot/"],
   },
   {
     files: ["**/*.{js,mjs,cjs,mts,ts,tsx,jsx}"],

examples/ssr/solid-ssr-app/package.json → examples/collab-clicker-ssr/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "solid-ssr-app",
+  "name": "collab-clicker-ssr",
   "private": true,
   "version": "0.0.1",
   "type": "module",

examples/collab-clicker-ssr/src/App.tsx

@@ -0,0 +1,77 @@
+import { createSignal, onMount } from "solid-js"
+
+export type Clicked = {
+  count: number
+};
+
+declare global {
+  interface Window {
+    __INITIAL_DATA__: Clicked | null;
+  }
+}
+
+export function App({ initialCount }: { initialCount?: number }) {
+  const [count, setCount] = createSignal(initialCount ?? 0)
+
+  const onClick = () => {
+    setCount((count) => count + 1);
+
+    fetch("/clicked").then(async (response) => {
+      const clicked = (await response.json()) as Clicked;
+      if (clicked.count > count()) {
+        setCount(clicked.count);
+      }
+    });
+  };
+
+  onMount(async () => {
+    const trailbase = await import("trailbase");
+    const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
+
+    const listen = async () => {
+      const client = new trailbase.Client(window.location.origin);
+      const api = client.records("counter");
+
+      const reader = (await api.subscribe(1)).getReader();
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          console.log("done");
+          break;
+        }
+
+        const update = value as { Update?: { value?: number } };
+        const updatedCount = update.Update?.value;
+        if (updatedCount && updatedCount > count()) {
+          setCount(updatedCount);
+        }
+      }
+    };
+
+    // Re-connect loop.
+    while (true) {
+      await listen().catch(console.error)
+      await sleep(5000);
+    }
+  });
+
+  return (
+    <div class="flex flex-col gap-4 text-neutral-800">
+      <h1>TrailBase Clicker</h1>
+
+      <div class="px-4 py-2">
+        <button
+          class="rounded bg-neutral-100 p-2 font-medium hover:scale-110 hover:outline outline-accent-600 active:scale-100 animate-all"
+          onClick={onClick}
+        >
+          clicked {count()} times
+        </button>
+      </div>
+
+      <p>
+        Click the button across different tabs, windows or browsers.
+      </p>
+    </div>
+  )
+}

examples/ssr/traildepot/scripts/main.ts → examples/collab-clicker-ssr/traildepot/scripts/main.ts

@@ -5,7 +5,7 @@ let _template: Promise<string> | null = null;
 
 async function getTemplate(): Promise<string> {
   if (_template == null) {
-    const template = _template = fs.readTextFile('solid-ssr-app/dist/client/index.html');
+    const template = _template = fs.readTextFile('dist/client/index.html');
     return await template;
   }
   return await _template;

examples/ssr/solid-ssr-app/tsconfig.json → examples/collab-clicker-ssr/tsconfig.json

@@ -24,7 +24,7 @@
 
     "paths": {
       "@/*": ["./src/*"],
-      "@bindings/*": ["../../../trailbase-core/bindings/*"]
+      "@bindings/*": ["../../trailbase-core/bindings/*"]
     }
   },
   "include": [

examples/data-cli-tutorial/Makefile

@@ -0,0 +1,10 @@
+read: fill
+	pnpm run read
+
+fill:
+	pnpm run fill
+
+clean:
+	rm -rf traildepot/data
+
+.PHONY: clean read fill

examples/tutorial/scripts/eslint.config.mjs → examples/data-cli-tutorial/eslint.config.mjs

@@ -5,10 +5,10 @@ export default [
   pluginJs.configs.recommended,
   ...tseslint.configs.recommended,
   {
-    ignores: ["dist/", "node_modules/", "types"],
+    ignores: ["dist/", "node_modules/", "types", "traildepot"],
   },
   {
-    files: ["scripts/*.{js,mjs,cjs,mts,ts,tsx,jsx}"],
+    files: ["src/*.{js,mjs,cjs,mts,ts,tsx,jsx}"],
     rules: {
       // https://typescript-eslint.io/rules/no-explicit-any/
       "@typescript-eslint/no-explicit-any": "warn",

examples/tutorial/scripts/tsconfig.json → examples/data-cli-tutorial/tsconfig.json

@@ -11,7 +11,7 @@
     "paths": {
       "@/*": ["./src/*"],
       "@schema/*": ["./types/*"],
-      "@bindings/*": ["../../../trailbase-core/bindings/*"]
+      "@bindings/*": ["../../trailbase-core/bindings/*"]
     }
   },
   "include": ["src/**/*"],