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

trailbaseio · Jan 24, 2025 · 9c34949 · 9c34949
1 parent 6699129
commit 9c34949
Show file tree

Hide file tree

Showing 69 changed files with 83 additions and 234 deletions.
diff --git a/README.md b/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.

diff --git a/docs/astro.config.mjs b/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",

diff --git a/docs/src/content/docs/comparison/pocketbase.mdx b/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

diff --git a/docs/src/content/docs/getting-started/first-cli-app.mdx b/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={[]}
 />
 

diff --git a/docs/src/content/docs/getting-started/first-ui-app.mdx b/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,
 
 ```

diff --git a/docs/src/content/docs/index.mdx b/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.
 

diff --git a/examples/coffeesearch/.dockerignore → examples/coffee-vector-search/.dockerignore b/examples/coffeesearch/.dockerignore → examples/coffee-vector-search/.dockerignore
diff --git a/examples/coffeesearch/.gitignore → examples/coffee-vector-search/.gitignore b/examples/coffeesearch/.gitignore → examples/coffee-vector-search/.gitignore
diff --git a/examples/coffeesearch/Dockerfile → examples/coffee-vector-search/Dockerfile b/examples/coffeesearch/Dockerfile → examples/coffee-vector-search/Dockerfile
diff --git a/examples/coffeesearch/Makefile → examples/coffee-vector-search/Makefile b/examples/coffeesearch/Makefile → examples/coffee-vector-search/Makefile
diff --git a/examples/coffeesearch/README.md → examples/coffee-vector-search/README.md b/examples/coffeesearch/README.md → examples/coffee-vector-search/README.md
diff --git a/...les/coffeesearch/arabica_data_cleaned.csv → ...ee-vector-search/arabica_data_cleaned.csv b/...les/coffeesearch/arabica_data_cleaned.csv → ...ee-vector-search/arabica_data_cleaned.csv
diff --git a/examples/coffeesearch/assets/screenshot.png → ...offee-vector-search/assets/screenshot.png b/examples/coffeesearch/assets/screenshot.png → ...offee-vector-search/assets/screenshot.png
diff --git a/examples/coffeesearch/eslint.config.js → ...les/coffee-vector-search/eslint.config.js b/examples/coffeesearch/eslint.config.js → ...les/coffee-vector-search/eslint.config.js
diff --git a/examples/coffeesearch/import.sql → examples/coffee-vector-search/import.sql b/examples/coffeesearch/import.sql → examples/coffee-vector-search/import.sql
diff --git a/examples/coffeesearch/index.html → examples/coffee-vector-search/index.html b/examples/coffeesearch/index.html → examples/coffee-vector-search/index.html
diff --git a/examples/coffeesearch/package.json → examples/coffee-vector-search/package.json b/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",

diff --git a/examples/coffeesearch/src/App.css → examples/coffee-vector-search/src/App.css b/examples/coffeesearch/src/App.css → examples/coffee-vector-search/src/App.css
diff --git a/examples/coffeesearch/src/App.tsx → examples/coffee-vector-search/src/App.tsx b/examples/coffeesearch/src/App.tsx → examples/coffee-vector-search/src/App.tsx
diff --git a/examples/coffeesearch/src/index.css → examples/coffee-vector-search/src/index.css b/examples/coffeesearch/src/index.css → examples/coffee-vector-search/src/index.css
diff --git a/examples/coffeesearch/src/main.tsx → examples/coffee-vector-search/src/main.tsx b/examples/coffeesearch/src/main.tsx → examples/coffee-vector-search/src/main.tsx
diff --git a/examples/coffeesearch/src/vite-env.d.ts → ...es/coffee-vector-search/src/vite-env.d.ts b/examples/coffeesearch/src/vite-env.d.ts → ...es/coffee-vector-search/src/vite-env.d.ts
diff --git a/examples/coffeesearch/traildepot/.gitignore → ...offee-vector-search/traildepot/.gitignore b/examples/coffeesearch/traildepot/.gitignore → ...offee-vector-search/traildepot/.gitignore
diff --git a/.../coffeesearch/traildepot/config.textproto → ...vector-search/traildepot/config.textproto b/.../coffeesearch/traildepot/config.textproto → ...vector-search/traildepot/config.textproto
diff --git a/...tions/U1732092075__crate_coffee_table.sql → ...tions/U1732092075__crate_coffee_table.sql b/...tions/U1732092075__crate_coffee_table.sql → ...tions/U1732092075__crate_coffee_table.sql
diff --git a/...s/coffeesearch/traildepot/scripts/main.ts → ...-vector-search/traildepot/scripts/main.ts b/...s/coffeesearch/traildepot/scripts/main.ts → ...-vector-search/traildepot/scripts/main.ts
diff --git a/examples/coffeesearch/tsconfig.json → examples/coffee-vector-search/tsconfig.json b/examples/coffeesearch/tsconfig.json → examples/coffee-vector-search/tsconfig.json
diff --git a/examples/coffeesearch/vite.config.ts → examples/coffee-vector-search/vite.config.ts b/examples/coffeesearch/vite.config.ts → examples/coffee-vector-search/vite.config.ts
diff --git a/examples/ssr/solid-ssr-app/.gitignore → examples/colab-clicker-ssr/.gitignore b/examples/ssr/solid-ssr-app/.gitignore → examples/colab-clicker-ssr/.gitignore
diff --git a/examples/ssr/Makefile → examples/colab-clicker-ssr/Makefile b/examples/ssr/Makefile → examples/colab-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

diff --git a/examples/ssr/README.md → examples/colab-clicker-ssr/README.md b/examples/ssr/README.md → examples/colab-clicker-ssr/README.md
diff --git a/examples/ssr/solid-ssr-app/eslint.config.mjs → examples/colab-clicker-ssr/eslint.config.mjs b/examples/ssr/solid-ssr-app/eslint.config.mjs → examples/colab-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}"],

diff --git a/examples/ssr/solid-ssr-app/index.html → examples/colab-clicker-ssr/index.html b/examples/ssr/solid-ssr-app/index.html → examples/colab-clicker-ssr/index.html
diff --git a/examples/ssr/solid-ssr-app/package.json → examples/colab-clicker-ssr/package.json b/examples/ssr/solid-ssr-app/package.json → examples/colab-clicker-ssr/package.json
diff --git a/examples/ssr/solid-ssr-app/pnpm-lock.yaml → examples/colab-clicker-ssr/pnpm-lock.yaml b/examples/ssr/solid-ssr-app/pnpm-lock.yaml → examples/colab-clicker-ssr/pnpm-lock.yaml
diff --git a/examples/ssr/solid-ssr-app/server.js → examples/colab-clicker-ssr/server.js b/examples/ssr/solid-ssr-app/server.js → examples/colab-clicker-ssr/server.js
diff --git a/examples/ssr/solid-ssr-app/src/App.tsx → examples/colab-clicker-ssr/src/App.tsx b/examples/ssr/solid-ssr-app/src/App.tsx → examples/colab-clicker-ssr/src/App.tsx
diff --git a/...es/ssr/solid-ssr-app/src/entry-client.tsx → ...es/colab-clicker-ssr/src/entry-client.tsx b/...es/ssr/solid-ssr-app/src/entry-client.tsx → ...es/colab-clicker-ssr/src/entry-client.tsx
diff --git a/...es/ssr/solid-ssr-app/src/entry-server.tsx → ...es/colab-clicker-ssr/src/entry-server.tsx b/...es/ssr/solid-ssr-app/src/entry-server.tsx → ...es/colab-clicker-ssr/src/entry-server.tsx
diff --git a/examples/ssr/solid-ssr-app/src/index.css → examples/colab-clicker-ssr/src/index.css b/examples/ssr/solid-ssr-app/src/index.css → examples/colab-clicker-ssr/src/index.css
diff --git a/examples/ssr/solid-ssr-app/src/vite-env.d.ts → examples/colab-clicker-ssr/src/vite-env.d.ts b/examples/ssr/solid-ssr-app/src/vite-env.d.ts → examples/colab-clicker-ssr/src/vite-env.d.ts
diff --git a/...ples/ssr/solid-ssr-app/tailwind.config.ts → ...ples/colab-clicker-ssr/tailwind.config.ts b/...ples/ssr/solid-ssr-app/tailwind.config.ts → ...ples/colab-clicker-ssr/tailwind.config.ts
diff --git a/examples/ssr/traildepot/.gitignore → ...s/colab-clicker-ssr/traildepot/.gitignore b/examples/ssr/traildepot/.gitignore → ...s/colab-clicker-ssr/traildepot/.gitignore
diff --git a/examples/ssr/traildepot/config.textproto → ...b-clicker-ssr/traildepot/config.textproto b/examples/ssr/traildepot/config.textproto → ...b-clicker-ssr/traildepot/config.textproto
diff --git a/...ations/U1725019360__create_admin_user.sql → ...ations/U1725019360__create_admin_user.sql b/...ations/U1725019360__create_admin_user.sql → ...ations/U1725019360__create_admin_user.sql
diff --git a/...ons/U1737638313__create_table_counter.sql → ...ons/U1737638313__create_table_counter.sql b/...ons/U1737638313__create_table_counter.sql → ...ons/U1737638313__create_table_counter.sql
diff --git a/examples/ssr/traildepot/scripts/main.ts → ...ab-clicker-ssr/traildepot/scripts/main.ts b/examples/ssr/traildepot/scripts/main.ts → ...ab-clicker-ssr/traildepot/scripts/main.ts
diff --git a/examples/ssr/solid-ssr-app/tsconfig.json → examples/colab-clicker-ssr/tsconfig.json b/examples/ssr/solid-ssr-app/tsconfig.json → examples/colab-clicker-ssr/tsconfig.json
@@ -24,7 +24,7 @@
 
     "paths": {
       "@/*": ["./src/*"],
-      "@bindings/*": ["../../../trailbase-core/bindings/*"]
+      "@bindings/*": ["../../trailbase-core/bindings/*"]
     }
   },
   "include": [

diff --git a/examples/ssr/solid-ssr-app/vite.config.ts → examples/colab-clicker-ssr/vite.config.ts b/examples/ssr/solid-ssr-app/vite.config.ts → examples/colab-clicker-ssr/vite.config.ts
diff --git a/examples/tutorial/scripts/.gitignore → examples/data-cli-tutorial/.gitignore b/examples/tutorial/scripts/.gitignore → examples/data-cli-tutorial/.gitignore
diff --git a/examples/data-cli-tutorial/Makefile b/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
diff --git a/examples/tutorial/README.md → examples/data-cli-tutorial/README.md b/examples/tutorial/README.md → examples/data-cli-tutorial/README.md
diff --git a/examples/tutorial/data/README.md → examples/data-cli-tutorial/data/README.md b/examples/tutorial/data/README.md → examples/data-cli-tutorial/data/README.md
diff --git a/...data/Top_1000_IMDb_movies_New_version.csv → ...data/Top_1000_IMDb_movies_New_version.csv b/...data/Top_1000_IMDb_movies_New_version.csv → ...data/Top_1000_IMDb_movies_New_version.csv
diff --git a/examples/tutorial/scripts/eslint.config.mjs → examples/data-cli-tutorial/eslint.config.mjs b/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",

diff --git a/examples/tutorial/scripts/package.json → examples/data-cli-tutorial/package.json b/examples/tutorial/scripts/package.json → examples/data-cli-tutorial/package.json
diff --git a/examples/tutorial/scripts/schema/movie.json → examples/data-cli-tutorial/schema/movie.json b/examples/tutorial/scripts/schema/movie.json → examples/data-cli-tutorial/schema/movie.json
diff --git a/examples/tutorial/scripts/src/fill.ts → examples/data-cli-tutorial/src/fill.ts b/examples/tutorial/scripts/src/fill.ts → examples/data-cli-tutorial/src/fill.ts
diff --git a/examples/tutorial/scripts/src/index.ts → examples/data-cli-tutorial/src/index.ts b/examples/tutorial/scripts/src/index.ts → examples/data-cli-tutorial/src/index.ts
diff --git a/examples/tutorial/traildepot/.gitignore → ...s/data-cli-tutorial/traildepot/.gitignore b/examples/tutorial/traildepot/.gitignore → ...s/data-cli-tutorial/traildepot/.gitignore
diff --git a/...ples/tutorial/traildepot/config.textproto → ...-cli-tutorial/traildepot/config.textproto b/...ples/tutorial/traildepot/config.textproto → ...-cli-tutorial/traildepot/config.textproto
diff --git a/...igrations/U1725019360__add_admin_user.sql → ...igrations/U1725019360__add_admin_user.sql b/...igrations/U1725019360__add_admin_user.sql → ...igrations/U1725019360__add_admin_user.sql
diff --git a/...ions/U1728810800__create_table_movies.sql → ...ions/U1728810800__create_table_movies.sql b/...ions/U1728810800__create_table_movies.sql → ...ions/U1728810800__create_table_movies.sql
diff --git a/examples/tutorial/scripts/tsconfig.json → examples/data-cli-tutorial/tsconfig.json b/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/**/*"],

diff --git a/examples/tutorial/scripts/types/movie.ts → examples/data-cli-tutorial/types/movie.ts b/examples/tutorial/scripts/types/movie.ts → examples/data-cli-tutorial/types/movie.ts
diff --git a/examples/tutorial/Makefile b/examples/tutorial/Makefile
diff --git a/examples/tutorial/scripts/Makefile b/examples/tutorial/scripts/Makefile