@async/db 0.2.0

package/examples/content-collections/db/site.schema.jsonc

@@ -0,0 +1,21 @@
+{
+  "kind": "document",
+  "description": "Site-level content settings stored as an embedded schema seed before aggregate bundle splits it out.",
+  "fields": {
+    "title": {
+      "type": "string",
+      "required": true
+    },
+    "description": {
+      "type": "string"
+    },
+    "baseUrl": {
+      "type": "string"
+    }
+  },
+  "seed": {
+    "title": "Local Content Lab",
+    "description": "A small dependency-free content collection workflow.",
+    "baseUrl": "https://example.test"
+  }
+}

package/examples/content-collections/db.config.mjs

@@ -0,0 +1,26 @@
+// @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',
+  },
+  types: {
+    enabled: true,
+    emitComments: true,
+  },
+  schema: {
+    unknownFields: 'warn',
+  },
+  resources: {
+    blog: {
+      store: 'static',
+    },
+    docs: {
+      store: 'static',
+    },
+  },
+});

package/examples/content-collections/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Content Collections",
+  "description": "Dependency-free docs and blog folders with frontmatter, raw MDX bodies, static stores, computed fields, and aggregate schema bundling.",
+  "tags": ["content", "mdx", "schema-mjs"]
+}

package/examples/content-collections/src/content-preview.mjs

@@ -0,0 +1,66 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openDb } from '@async/db';
+
+const exampleRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const db = await openDb({ cwd: exampleRoot });
+await db.runtime.hydrate();
+
+const [docs, blog] = await Promise.all([
+  db.collection('docs').all(),
+  db.collection('blog').all(),
+]);
+
+const output = [
+  '<main>',
+  ...docs
+    .sort((left, right) => (left.order ?? 100) - (right.order ?? 100))
+    .map((record) => renderArticle('doc', record)),
+  ...blog.map((record) => renderArticle('blog', {
+    ...record,
+    href: `/blog/${record.id}`,
+  })),
+  '</main>',
+  '',
+].join('\n');
+
+console.log(output);
+
+export function renderArticle(kind, record) {
+  const title = escapeHtml(record.title ?? record.id);
+  const body = renderMdxPreview(record.body ?? '');
+  const href = record.href ? ` data-href="${escapeHtml(record.href)}"` : '';
+  return [
+    `<article data-kind="${kind}" data-id="${escapeHtml(record.id)}"${href}>`,
+    `  <h2>${title}</h2>`,
+    `  <p>${escapeHtml(record.summary ?? '')}</p>`,
+    `  <div>${body}</div>`,
+    '</article>',
+  ].join('\n');
+}
+
+function renderMdxPreview(source) {
+  return String(source)
+    .split(/\n{2,}/u)
+    .map((block) => block.trim())
+    .filter(Boolean)
+    .map((block) => {
+      if (block.startsWith('# ')) {
+        return `<h1>${escapeHtml(block.slice(2))}</h1>`;
+      }
+      if (block.startsWith('## ')) {
+        return `<h2>${escapeHtml(block.slice(3))}</h2>`;
+      }
+      const withoutJsxTags = block.replace(/<\/?[A-Z][^>]*>/gu, '');
+      return `<p>${escapeHtml(withoutJsxTags)}</p>`;
+    })
+    .join('');
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}

package/examples/content-collections/src/generated/db.types.d.ts

@@ -0,0 +1,81 @@
+/* eslint-disable */
+// This file is generated by db. Do not edit by hand.
+
+export type AuthorRole = "Editor" | "Author";
+
+export type BlogStatus = "draft" | "published";
+
+/** People who write or edit content records. */
+export type Author = {
+  /** Stable author id used by content frontmatter. */
+  id: string;
+  /** Display name shown on bylines. */
+  name: string;
+  /** Editorial role in the local content workflow. */
+  role?: AuthorRole;
+};
+
+/** Blog posts loaded from frontmatter and raw MDX body files. */
+export type Blog = {
+  /** Stable post id. Defaults to the filename when frontmatter omits id. */
+  id: string;
+  /** Post title from frontmatter. */
+  title: string;
+  /** Publication state. */
+  status?: BlogStatus;
+  /** Publication timestamp. */
+  publishedAt?: string;
+  /** Author id from the authors fixture. */
+  authorId: string;
+  /** Comma-separated tags kept scalar for the dependency-free frontmatter parser. */
+  tags?: string;
+  /** Short post summary. */
+  summary?: string;
+  /** Raw MDX body. Rendering and compilation are app-owned. */
+  body: string;
+  /** Read-only URL path derived from the post id. */
+  permalink?: string;
+  /** Read-only one-minute minimum estimate derived from the raw body. */
+  readingTimeMinutes?: number;
+};
+
+/** Documentation pages loaded from frontmatter and raw MDX body files. */
+export type Doc = {
+  /** Stable document id. Defaults to the filename when frontmatter omits id. */
+  id: string;
+  /** Page title from frontmatter. */
+  title: string;
+  /** Navigation group for this page. */
+  section: string;
+  /** Sort order inside the section. */
+  order?: number;
+  /** Short page summary. */
+  summary?: string;
+  /** Raw MDX body. Rendering and compilation are app-owned. */
+  body: string;
+};
+
+/** Site-level content settings stored as an embedded schema seed before aggregate bundle splits it out. */
+export type Site = {
+  title: string;
+  description?: string;
+  baseUrl?: string;
+};
+
+export type DbCollections = {
+  authors: Author;
+  blog: Blog;
+  docs: Doc;
+};
+
+export type DbDocuments = {
+  site: Site;
+};
+
+export type DbTypes = {
+  collections: DbCollections;
+  documents: DbDocuments;
+};
+
+export type DbCollectionName = keyof DbCollections;
+export type DbDocumentName = keyof DbDocuments;

package/examples/csv/README.md

@@ -0,0 +1,52 @@
+# CSV Example
+
+## What This Teaches
+
+Use this when product, customer, or spreadsheet-like data starts as CSV. db scans the header row, infers field shapes, generates types, and mirrors the rows into JSON runtime state.
+
+## Files To Inspect
+
+- [db/customers.csv](./db/customers.csv): source CSV fixture.
+- [db.config.mjs](./db.config.mjs): default mirror setup using `defineConfig`.
+
+## Run It
+
+From the repository root, use the repo-internal CLI path:
+
+```bash
+npm run db -- sync --cwd ./examples/csv
+npm run db -- serve --cwd ./examples/csv
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+## Expected Result
+
+`sync` writes `.db/state/customers.json`. When `db/customers.csv` changes, the source hash changes and the JSON store refreshes from CSV.
+
+## REST Request To Try
+
+Leave `serve` running and run this from another terminal:
+
+```bash
+curl 'http://127.0.0.1:7331/db/customers.json?select=id,name,email'
+```
+
+## Features To Notice
+
+- [CSV fixtures](../../docs/fixtures-and-schemas.md#csv-fixtures)
+- [Runtime state refreshes](../../docs/generated-files.md#runtime-state)
+- [Fixture-like `.json` REST routes](../../docs/server-and-viewer.md#fixture-like-json-routes)
+
+## Cleanup
+
+Generated `.db/` output is ignored by git and can be removed whenever you want fresh runtime state.
+
+## More Docs
+
+- [Fixtures And Schemas](../../docs/fixtures-and-schemas.md)
+- [Generated Files](../../docs/generated-files.md)

package/examples/csv/db/customers.csv

@@ -0,0 +1,4 @@
+Customer ID,Name,Email,Plan,Active,Signup Score,Postal Code
+c_1,Ada Lovelace,ada@example.com,team,true,98,02139
+c_2,Grace Hopper,grace@example.com,enterprise,true,95,10001
+c_3,Katherine Johnson,katherine@example.com,starter,false,88,23666

package/examples/csv/db.config.mjs

@@ -0,0 +1,13 @@
+// @ts-check
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  dbDir: './db',
+  outputs: {
+    stateDir: './.db',
+    types: './.db/types/index.d.ts',
+  },
+  types: {
+    enabled: true,
+  },
+});

package/examples/csv/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "CSV Fixtures",
+  "description": "CSV source loading with inferred fields, source hashes, and runtime JSON store refreshes.",
+  "tags": ["csv", "inference", "sync"]
+}

package/examples/data-first/README.md

@@ -0,0 +1,54 @@
+# Data-First Example
+
+## What This Teaches
+
+Use this when you have fixture data before you have a contract. db infers collections, singleton documents, REST routes, GraphQL fields, and TypeScript types from plain JSON.
+
+## Files To Inspect
+
+- [db/users.json](./db/users.json): collection inferred from an array.
+- [db/posts.json](./db/posts.json): second inferred collection.
+- [db/settings.json](./db/settings.json): singleton document inferred from an object.
+
+## Run It
+
+From the repository root, use the repo-internal CLI path:
+
+```bash
+npm run db -- sync --cwd ./examples/data-first
+npm run db -- serve --cwd ./examples/data-first
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+## Expected Result
+
+`sync` infers schema and writes generated runtime state under `examples/data-first/.db/`.
+
+## REST Request To Try
+
+Leave `serve` running and run this from another terminal:
+
+```bash
+curl 'http://127.0.0.1:7331/db/users.json?select=id,name,email'
+```
+
+## Features To Notice
+
+- [Data-first JSON fixtures](../../docs/fixtures-and-schemas.md#data-first-json-or-jsonc)
+- [Fixture-like `.json` REST routes](../../docs/server-and-viewer.md#fixture-like-json-routes)
+- [REST query parameters](../../docs/server-and-viewer.md#rest-routes)
+- [Runtime state](../../docs/generated-files.md#runtime-state)
+
+## Cleanup
+
+Generated `.db/` output is ignored by git and can be removed whenever you want a fresh mirror.
+
+## More Docs
+
+- [Concepts](../../docs/concepts.md)
+- [Fixtures And Schemas](../../docs/fixtures-and-schemas.md)

package/examples/data-first/db/posts.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "p_1",
+    "authorId": "u_1",
+    "title": "Notes on analytical engines",
+    "published": true,
+    "tags": ["history", "computing"]
+  },
+  {
+    "id": "p_2",
+    "authorId": "u_2",
+    "title": "Debugging at sea",
+    "published": false,
+    "tags": ["debugging"]
+  }
+]

package/examples/data-first/db/settings.json

@@ -0,0 +1,8 @@
+{
+  "theme": "light",
+  "locale": "en-US",
+  "features": {
+    "billing": false,
+    "graphql": true
+  }
+}

package/examples/data-first/db/users.json

@@ -0,0 +1,14 @@
+[
+  {
+    "id": "u_1",
+    "name": "Ada Lovelace",
+    "email": "ada@example.com",
+    "role": "admin"
+  },
+  {
+    "id": "u_2",
+    "name": "Grace Hopper",
+    "email": "grace@example.com",
+    "role": "user"
+  }
+]

package/examples/data-first/db.config.mjs

@@ -0,0 +1,13 @@
+// @ts-check
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  dbDir: './db',
+  outputs: {
+    stateDir: './.db',
+    types: './.db/types/index.d.ts',
+  },
+  types: {
+    enabled: true,
+  },
+});

package/examples/data-first/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Data First",
+  "description": "Plain JSON fixtures with inferred schema, generated types, REST routes, and a writable mirror.",
+  "tags": ["data-first", "inference", "rest"]
+}

package/examples/diagnostics/README.md

@@ -0,0 +1,55 @@
+# Diagnostics Example
+
+## What This Teaches
+
+Use this when you want to see how db reports local fixture drift. It intentionally includes schema/data mismatches so the viewer can show source diagnostics while valid resources still work.
+
+## Files To Inspect
+
+- [db/users.schema.jsonc](./db/users.schema.jsonc): schema-backed collection.
+- [db/users.json](./db/users.json): contains an extra `twitterHandle` field.
+- [db/projects.schema.jsonc](./db/projects.schema.jsonc): contains a nested field mismatch.
+
+## Run It
+
+From the repository root, use the repo-internal CLI path:
+
+```bash
+npm run db -- sync --cwd ./examples/diagnostics
+npm run db -- serve --cwd ./examples/diagnostics
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+## Expected Result
+
+`sync` reports warnings. The viewer surfaces diagnostics for the broken source files instead of making unrelated resources unusable.
+
+## REST Request To Try
+
+Leave `serve` running and run this from another terminal:
+
+```bash
+curl http://127.0.0.1:7331/db/users.json
+```
+
+Expected diagnostics include an extra `twitterHandle` field in `users.json` and an undefined nested `metadata.priority` field in `projects.schema.jsonc`.
+
+## Features To Notice
+
+- [Diagnostics workflow](../../docs/concepts.md#diagnostics)
+- [Schema validation](../../docs/fixtures-and-schemas.md#schema-files)
+- [Fixture-like `.json` REST routes](../../docs/server-and-viewer.md#fixture-like-json-routes)
+
+## Cleanup
+
+Generated `.db/` output is ignored by git and can be removed whenever you want a fresh mirror.
+
+## More Docs
+
+- [Concepts](../../docs/concepts.md)
+- [Fixtures And Schemas](../../docs/fixtures-and-schemas.md)

package/examples/diagnostics/db/projects.schema.jsonc

@@ -0,0 +1,27 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true
+    },
+    "name": {
+      "type": "string",
+      "required": true
+    },
+    "metadata": {
+      "type": "object",
+      "default": {}
+    }
+  },
+  "seed": [
+    {
+      "id": "proj_1",
+      "name": "Diagnostics demo",
+      "metadata": {
+        "priority": "high"
+      }
+    }
+  ]
+}

package/examples/diagnostics/db/users.json

@@ -0,0 +1,9 @@
+[
+  {
+    "id": "u_1",
+    "name": "Ada Lovelace",
+    "email": "ada@example.com",
+    "role": "admin",
+    "twitterHandle": "@ada"
+  }
+]

package/examples/diagnostics/db/users.schema.jsonc

@@ -0,0 +1,23 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true
+    },
+    "name": {
+      "type": "string",
+      "required": true
+    },
+    "email": {
+      "type": "string",
+      "required": true
+    },
+    "role": {
+      "type": "enum",
+      "values": ["admin", "user"],
+      "default": "user"
+    }
+  }
+}

package/examples/diagnostics/db.config.mjs

@@ -0,0 +1,16 @@
+// @ts-check
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  dbDir: './db',
+  outputs: {
+    stateDir: './.db',
+    types: './.db/types/index.d.ts',
+  },
+  types: {
+    enabled: true,
+  },
+  schema: {
+    unknownFields: 'warn',
+  },
+});

package/examples/diagnostics/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Diagnostics",
+  "description": "Intentional schema and source warnings so the viewer can show file-specific diagnostics while valid resources keep working.",
+  "tags": ["diagnostics", "viewer", "warnings"]
+}

package/examples/free-plan-upgrade/README.md

@@ -0,0 +1,22 @@
+# Free Plan Upgrade Example
+
+This example shows app code for a free-plan tenant upgrade. `@async/db` only provides forks, branches, snapshots, migration locks, resource migration, and routing. The app decides that moving `projects` from JSON to another store means "upgrade to paid."
+
+Run it from the repository root:
+
+```bash
+npm run db -- sync --cwd ./examples/free-plan-upgrade
+node ./examples/free-plan-upgrade/src/upgrade-tenant-to-paid.mjs
+```
+
+The script:
+
+- creates a tenant fork from the root JSON data
+- snapshots `projects`
+- locks `projects` as read-only
+- migrates `projects` to a fake paid store
+- verifies count/checksum
+- switches routing
+- keeps the original JSON snapshot as backup data
+
+The fake paid store stands in for Postgres so the example stays dependency-light.

package/examples/free-plan-upgrade/db/appSettings.json

@@ -0,0 +1,4 @@
+{
+  "appName": "Upgrade Demo",
+  "plan": "free"
+}

package/examples/free-plan-upgrade/db/projects.json

@@ -0,0 +1,7 @@
+[
+  {
+    "id": "p_1",
+    "name": "Launch checklist",
+    "status": "active"
+  }
+]

package/examples/free-plan-upgrade/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Free Plan Upgrade",
+  "description": "App-owned upgrade flow that moves one tenant resource from JSON to another store.",
+  "tags": ["forks", "migration", "json", "postgres"]
+}