@async/db 0.2.0

package/examples/schema-manifest/README.md

@@ -0,0 +1,50 @@
+# Schema Manifest Example
+
+## What This Teaches
+
+Use this when an app wants committed schema metadata for admin, CMS, or form-building screens. It demonstrates `outputs.schemaManifest` and `schemaManifest.customizeField()`.
+
+## Files To Inspect
+
+- [db/projects.schema.jsonc](./db/projects.schema.jsonc): relation, enum, defaults, and descriptions.
+- [db/users.schema.jsonc](./db/users.schema.jsonc): field descriptions and a `bio` field customized for markdown.
+- [db.config.mjs](./db.config.mjs): writes `src/generated/db.schema.json` and customizes UI hints.
+- [src/generated/db.schema.json](./src/generated/db.schema.json): committed manifest output after sync.
+
+## Run It
+
+From the repository root, use the repo-internal CLI path:
+
+```bash
+npm run db -- sync --cwd ./examples/schema-manifest
+npm run db -- schema manifest --cwd ./examples/schema-manifest --out ./src/generated/db.schema.json
+npm run db -- serve --cwd ./examples/schema-manifest
+```
+
+## Expected Result
+
+`sync` writes both generated TypeScript types and a committed schema manifest. In the manifest, `projects.status` uses `segmented-control`, and `users.bio` uses `markdown`.
+
+## REST Request To Try
+
+Leave `serve` running and run this from another terminal:
+
+```bash
+curl 'http://127.0.0.1:7331/db/projects.json?expand=owner&select=id,name,status,owner.name'
+```
+
+## Features To Notice
+
+- [Schema manifest output](../../docs/generated-files.md#schema-manifest-output)
+- [Field UI metadata](../../docs/server-and-viewer.md#custom-viewer-manifest)
+- [Relationship expansion](../../docs/server-and-viewer.md#relationship-expansion)
+- [Fixture-like `.json` REST routes](../../docs/server-and-viewer.md#fixture-like-json-routes)
+
+## Cleanup
+
+Generated `.db/` output is ignored by git. The files under `src/generated/` are intentionally committed for this example.
+
+## More Docs
+
+- [Generated Files](../../docs/generated-files.md)
+- [Configuration](../../docs/configuration.md)

package/examples/schema-manifest/db/projects.schema.jsonc

@@ -0,0 +1,48 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "description": "Projects used to demonstrate generated form metadata.",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable project id."
+    },
+    "name": {
+      "type": "string",
+      "required": true,
+      "description": "Project display name."
+    },
+    "ownerId": {
+      "type": "string",
+      "required": true,
+      "description": "Owner user id.",
+      "relation": {
+        "name": "owner",
+        "to": "users",
+        "toField": "id",
+        "cardinality": "one"
+      }
+    },
+    "status": {
+      "type": "enum",
+      "values": ["planned", "active", "paused", "done"],
+      "default": "planned",
+      "description": "Workflow status for local admin forms."
+    },
+    "notes": {
+      "type": "string",
+      "maxLength": 500,
+      "description": "Internal project notes."
+    }
+  },
+  "seed": [
+    {
+      "id": "proj_1",
+      "name": "Local admin prototype",
+      "ownerId": "u_1",
+      "status": "active",
+      "notes": "Uses generated manifest metadata to choose form controls."
+    }
+  ]
+}

package/examples/schema-manifest/db/users.schema.jsonc

@@ -0,0 +1,35 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "description": "People who can own local projects.",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable user id."
+    },
+    "name": {
+      "type": "string",
+      "required": true,
+      "description": "Display name."
+    },
+    "email": {
+      "type": "string",
+      "required": true,
+      "unique": true,
+      "description": "Email shown in admin forms."
+    },
+    "bio": {
+      "type": "string",
+      "description": "Markdown biography for profile previews."
+    }
+  },
+  "seed": [
+    {
+      "id": "u_1",
+      "name": "Ada Lovelace",
+      "email": "ada@example.com",
+      "bio": "First programmer notes for local demos."
+    }
+  ]
+}

package/examples/schema-manifest/db.config.mjs

@@ -0,0 +1,41 @@
+// @ts-check
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  dbDir: './db',
+  outputs: {
+    stateDir: './.db',
+    types: './.db/types/index.d.ts',
+    committedTypes: './src/generated/db.types.d.ts',
+    schemaManifest: './src/generated/db.schema.json',
+  },
+  types: {
+    enabled: true,
+    emitComments: true,
+  },
+  schemaManifest: {
+    customizeField({ resourceName, fieldName, defaultManifest }) {
+      if (resourceName === 'projects' && fieldName === 'status') {
+        return {
+          ...defaultManifest,
+          ui: {
+            ...defaultManifest.ui,
+            component: 'segmented-control',
+          },
+        };
+      }
+
+      if (resourceName === 'users' && fieldName === 'bio') {
+        return {
+          ...defaultManifest,
+          ui: {
+            ...defaultManifest.ui,
+            component: 'markdown',
+          },
+        };
+      }
+
+      return defaultManifest;
+    },
+  },
+});

package/examples/schema-manifest/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Schema Manifest",
+  "description": "Committed schema metadata for admin or CMS-style forms with field customization hooks.",
+  "tags": ["manifest", "admin-ui", "customization"]
+}

package/examples/schema-manifest/src/generated/db.schema.json

@@ -0,0 +1,130 @@
+{
+  "version": 1,
+  "collections": {
+    "projects": {
+      "kind": "collection",
+      "name": "projects",
+      "fields": {
+        "id": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Stable project id.",
+          "ui": {
+            "label": "Id",
+            "component": "text",
+            "readonly": true
+          }
+        },
+        "name": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Project display name.",
+          "ui": {
+            "label": "Name",
+            "component": "text"
+          }
+        },
+        "ownerId": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Owner user id.",
+          "relation": {
+            "name": "owner",
+            "to": "users",
+            "toField": "id",
+            "cardinality": "one"
+          },
+          "ui": {
+            "label": "Owner Id",
+            "component": "relationSelect",
+            "optionsFrom": "users"
+          }
+        },
+        "status": {
+          "type": "enum",
+          "required": false,
+          "nullable": false,
+          "description": "Workflow status for local admin forms.",
+          "default": "planned",
+          "values": [
+            "planned",
+            "active",
+            "paused",
+            "done"
+          ],
+          "ui": {
+            "label": "Status",
+            "component": "segmented-control"
+          }
+        },
+        "notes": {
+          "type": "string",
+          "required": false,
+          "nullable": false,
+          "description": "Internal project notes.",
+          "maxLength": 500,
+          "ui": {
+            "label": "Notes",
+            "component": "textarea"
+          }
+        }
+      },
+      "description": "Projects used to demonstrate generated form metadata.",
+      "idField": "id"
+    },
+    "users": {
+      "kind": "collection",
+      "name": "users",
+      "fields": {
+        "id": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Stable user id.",
+          "ui": {
+            "label": "Id",
+            "component": "text",
+            "readonly": true
+          }
+        },
+        "name": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Display name.",
+          "ui": {
+            "label": "Name",
+            "component": "text"
+          }
+        },
+        "email": {
+          "type": "string",
+          "required": true,
+          "nullable": false,
+          "description": "Email shown in admin forms.",
+          "unique": true,
+          "ui": {
+            "label": "Email",
+            "component": "email"
+          }
+        },
+        "bio": {
+          "type": "string",
+          "required": false,
+          "nullable": false,
+          "description": "Markdown biography for profile previews.",
+          "ui": {
+            "label": "Bio",
+            "component": "markdown"
+          }
+        }
+      },
+      "description": "People who can own local projects.",
+      "idField": "id"
+    }
+  },
+  "documents": {}
+}

package/examples/schema-manifest/src/generated/db.types.d.ts

@@ -0,0 +1,50 @@
+/* eslint-disable */
+// This file is generated by db. Do not edit by hand.
+
+export type ProjectStatus =
+  | "planned"
+  | "active"
+  | "paused"
+  | "done";
+
+/** Projects used to demonstrate generated form metadata. */
+export type Project = {
+  /** Stable project id. */
+  id: string;
+  /** Project display name. */
+  name: string;
+  /** Owner user id. */
+  ownerId: string;
+  /** Workflow status for local admin forms. */
+  status?: ProjectStatus;
+  /** Internal project notes. */
+  notes?: string;
+};
+
+/** People who can own local projects. */
+export type User = {
+  /** Stable user id. */
+  id: string;
+  /** Display name. */
+  name: string;
+  /** Email shown in admin forms. */
+  email: string;
+  /** Markdown biography for profile previews. */
+  bio?: string;
+};
+
+export type DbCollections = {
+  projects: Project;
+  users: User;
+};
+
+export type DbDocuments = {
+};
+
+export type DbTypes = {
+  collections: DbCollections;
+  documents: DbDocuments;
+};
+
+export type DbCollectionName = keyof DbCollections;
+export type DbDocumentName = keyof DbDocuments;

package/examples/schema-ui/README.md

@@ -0,0 +1,103 @@
+# Schema UI Example
+
+## What This Teaches
+
+Use this when you want to see how committed schema JSON can drive a tiny admin or CMS UI. It reads `src/generated/db.schema.json` and maps each field's `ui.component` to simple view and editor HTML.
+
+The demo composes **SSR CMS routes ahead of the stock db handler**, so the same port serves **`/` SSR**, **`/__db`**, REST, and GraphQL.
+
+## Files To Inspect
+
+- [db/pages.schema.jsonc](./db/pages.schema.jsonc): CMS page schema with enum, relation, summary, and markdown body fields.
+- [db/users.schema.jsonc](./db/users.schema.jsonc): author records used by the relation picker metadata.
+- [db.config.mjs](./db.config.mjs): writes the schema manifest and customizes CMS UI hints.
+- [src/render-admin.mjs](./src/render-admin.mjs): static string-template preview (`/templates`) and CLI output for scaffolding comparisons.
+- [src/cms-ssr.mjs](./src/cms-ssr.mjs): SSR view/editor snippets filled with real record values and resolved relations.
+- [src/schema-ui-ssr-handler.mjs](./src/schema-ui-ssr-handler.mjs): SSR routing layer (middleware-style); hands off other paths to db.
+- [src/start-schema-ui-server.mjs](./src/start-schema-ui-server.mjs): wires SSR handler + `createDbRequestHandler` + file watching.
+- [serve.mjs](./serve.mjs): CLI entry; same stack as the examples launcher hook.
+- [serve-example.mjs](./serve-example.mjs): **`npm run examples`** hook — exports `createExampleRuntime` so `scripts/example-launcher.js` can mount this example without hard-coding it.
+- [src/generated/db.schema.json](./src/generated/db.schema.json): committed manifest input after sync.
+
+## Run It
+
+From the repository root:
+
+```bash
+node ./examples/schema-ui/serve.mjs
+```
+
+Open **http://127.0.0.1:7342/** — CMS home with links into each collection. The built-in viewer is **http://127.0.0.1:7342/__db**.
+
+### From the repo examples index
+
+```bash
+npm run examples
+```
+
+Pick **Schema UI** on the index page; it uses **`serve-example.mjs`** automatically and starts only after you open it (see `scripts/example-launcher.js`).
+
+Routes:
+
+| Path | Purpose |
+| --- | --- |
+| `/` | Home: collections and record counts |
+| `/cms/pages` | List pages from the mirror |
+| `/cms/pages/page_home` | SSR detail: resolved author link, markdown body text, filled editor controls |
+| `/templates` | Static component templates only (no database rows), matching the CLI renderer |
+| `/__db`, `/graphql`, `/db/pages.json`, … | Stock db viewer, GraphQL, and REST on the same origin |
+
+URLs are printed when the server starts.
+
+Options:
+
+```bash
+node ./examples/schema-ui/serve.mjs --port 8080 --host 127.0.0.1
+node ./examples/schema-ui/serve.mjs --no-sync
+```
+
+`--no-sync` skips fixture sync on startup (faster restart). Use it only after you have already synced once so `.db/state` exists.
+
+### Print Static Templates To A File
+
+```bash
+npm run db -- sync --cwd ./examples/schema-ui
+node ./examples/schema-ui/src/render-admin.mjs > /tmp/db-schema-ui.html
+```
+
+## Expected Result
+
+SSR pages show **live field values**: titles, markdown bodies escaped into `<article>`, relation links to `/cms/users/:id`, radios reflecting enum status, and selects populated from related rows.
+
+The standalone **`render-admin.mjs`** output still demonstrates placeholder-driven templates for comparison.
+
+## REST Request To Try
+
+With **`serve.mjs`** or **`npm run examples`** (same stack), REST is already on the demo port:
+
+```bash
+curl 'http://127.0.0.1:7342/db/pages.json?expand=author&select=id,title,status,author.name'
+```
+
+Or run the CLI server alone:
+
+```bash
+npm run db -- serve --cwd ./examples/schema-ui
+curl 'http://127.0.0.1:7331/db/pages.json?expand=author&select=id,title,status,author.name'
+```
+
+## Features To Notice
+
+- [Schema manifest output](../../docs/generated-files.md#schema-manifest-output)
+- [Custom viewer manifest](../../docs/server-and-viewer.md#custom-viewer-manifest)
+- [Relationship expansion](../../docs/server-and-viewer.md#relationship-expansion)
+- [Fixture-like `.json` REST routes](../../docs/server-and-viewer.md#fixture-like-json-routes)
+
+## Cleanup
+
+Generated `.db/` output is ignored by git. The files under `src/generated/` are intentionally committed for this example.
+
+## More Docs
+
+- [Generated Files](../../docs/generated-files.md)
+- [Configuration](../../docs/configuration.md)

package/examples/schema-ui/db/pages.schema.jsonc

@@ -0,0 +1,53 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "description": "CMS pages rendered by a tiny schema-driven UI example.",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable page id."
+    },
+    "title": {
+      "type": "string",
+      "required": true,
+      "description": "Page title shown in the CMS list."
+    },
+    "status": {
+      "type": "enum",
+      "values": ["draft", "review", "published"],
+      "default": "draft",
+      "description": "Publication state."
+    },
+    "authorId": {
+      "type": "string",
+      "required": true,
+      "description": "Page author.",
+      "relation": {
+        "name": "author",
+        "to": "users",
+        "toField": "id",
+        "cardinality": "one"
+      }
+    },
+    "summary": {
+      "type": "string",
+      "maxLength": 160,
+      "description": "Short page summary."
+    },
+    "bodyMarkdown": {
+      "type": "string",
+      "description": "Markdown body content."
+    }
+  },
+  "seed": [
+    {
+      "id": "page_home",
+      "title": "Home",
+      "status": "draft",
+      "authorId": "u_1",
+      "summary": "A small page record used by the schema UI example.",
+      "bodyMarkdown": "# Welcome\n\nThis body is edited with a markdown template."
+    }
+  ]
+}

package/examples/schema-ui/db/users.schema.jsonc

@@ -0,0 +1,30 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "description": "Authors that can own CMS pages.",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable author id."
+    },
+    "name": {
+      "type": "string",
+      "required": true,
+      "description": "Author display name."
+    },
+    "email": {
+      "type": "string",
+      "required": true,
+      "unique": true,
+      "description": "Author email address."
+    }
+  },
+  "seed": [
+    {
+      "id": "u_1",
+      "name": "Ada Lovelace",
+      "email": "ada@example.com"
+    }
+  ]
+}

package/examples/schema-ui/db.config.mjs

@@ -0,0 +1,55 @@
+// @ts-check
+import { defineConfig, mergeManifest } from '@async/db/config';
+
+export default defineConfig({
+  dbDir: './db',
+  outputs: {
+    stateDir: './.db',
+    types: './.db/types/index.d.ts',
+    committedTypes: './src/generated/db.types.d.ts',
+    schemaManifest: './src/generated/db.schema.json',
+  },
+  types: {
+    enabled: true,
+    emitComments: true,
+  },
+  schemaManifest: {
+    customizeResource({ resourceName, defaultManifest }) {
+      if (resourceName !== 'pages') {
+        return defaultManifest;
+      }
+
+      return mergeManifest(defaultManifest, {
+        editor: {
+          title: 'Pages',
+          description: 'CMS pages edited from generated schema metadata.',
+        },
+      });
+    },
+
+    customizeField({ resourceName, fieldName, defaultManifest }) {
+      if (resourceName !== 'pages') {
+        return defaultManifest;
+      }
+
+      if (fieldName === 'bodyMarkdown') {
+        return mergeManifest(defaultManifest, {
+          ui: {
+            label: 'Body',
+            component: 'markdown',
+          },
+        });
+      }
+
+      if (fieldName === 'status') {
+        return mergeManifest(defaultManifest, {
+          ui: {
+            component: 'segmented-control',
+          },
+        });
+      }
+
+      return defaultManifest;
+    },
+  },
+});

package/examples/schema-ui/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Schema UI",
+  "description": "Generate simple admin/CMS view and editor HTML from the committed schema manifest using string templates.",
+  "tags": ["manifest", "cms", "templates"]
+}