@async/db 0.2.0

package/examples/advanced/README.md

@@ -0,0 +1,55 @@
+# Advanced Example
+
+## What This Teaches
+
+Use this after the basics when you want to see several features working together: mixed-mode fixtures, `.schema.mjs`, defaults, nested objects, and committed generated types.
+
+## Files To Inspect
+
+- [db/users.schema.mjs](./db/users.schema.mjs): schema helper API from `@async/db/schema`.
+- [db/users.json](./db/users.json): data seed for the schema-backed `users` collection.
+- [db/projects.schema.jsonc](./db/projects.schema.jsonc): nested object defaults.
+- [src/generated/db.types.d.ts](./src/generated/db.types.d.ts): committed generated types.
+
+## Run It
+
+From the repository root, use the repo-internal CLI path:
+
+```bash
+npm run db -- sync --cwd ./examples/advanced
+npm run db -- serve --cwd ./examples/advanced
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+## Expected Result
+
+`sync` loads mixed data and schema sources, applies defaults in the selected runtime store, and writes committed generated types.
+
+## REST Request To Try
+
+Leave `serve` running and run this from another terminal:
+
+```bash
+curl 'http://127.0.0.1:7331/db/projects.json?select=id,name,status,metadata'
+```
+
+## Features To Notice
+
+- [JavaScript schema sources](../../docs/fixtures-and-schemas.md#javascript-schema-sources)
+- [Schema defaults](../../docs/configuration.md#schema-defaults)
+- [Fixture-like `.json` REST routes](../../docs/server-and-viewer.md#fixture-like-json-routes)
+- [Generated types](../../docs/generated-files.md#generated-types)
+
+## 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)
+- [Package API](../../docs/package-api.md)

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

@@ -0,0 +1,44 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true
+    },
+    "name": {
+      "type": "string",
+      "required": true
+    },
+    "ownerId": {
+      "type": "string",
+      "required": true
+    },
+    "status": {
+      "type": "enum",
+      "values": ["planned", "active", "paused", "done"],
+      "default": "planned"
+    },
+    "metadata": {
+      "type": "object",
+      "default": {},
+      "fields": {
+        "priority": {
+          "type": "string",
+          "default": "normal"
+        }
+      }
+    }
+  },
+  "seed": [
+    {
+      "id": "proj_1",
+      "name": "Local checkout",
+      "ownerId": "u_1",
+      "status": "active",
+      "metadata": {
+        "priority": "high"
+      }
+    }
+  ]
+}

package/examples/advanced/db/settings.jsonc

@@ -0,0 +1,9 @@
+{
+  // Singleton app settings with JSONC comments.
+  "theme": "dark",
+  "locale": "en-US",
+  "features": {
+    "billing": true,
+    "graphql": true,
+  },
+}

package/examples/advanced/db/users.json

@@ -0,0 +1,23 @@
+[
+  {
+    "id": "u_1",
+    "name": "Ada Lovelace",
+    "email": "ada@example.com",
+    "role": "admin",
+    "profile": {
+      "title": "Mathematician",
+      "location": "London"
+    },
+    "twitterHandle": "@ada"
+  },
+  {
+    "id": "u_2",
+    "name": "Katherine Johnson",
+    "email": "katherine@example.com",
+    "role": "editor",
+    "profile": {
+      "title": "Research mathematician",
+      "location": "Virginia"
+    }
+  }
+]

package/examples/advanced/db/users.schema.mjs

@@ -0,0 +1,31 @@
+import { collection, field } from '@async/db/schema';
+
+export default collection({
+  description: 'Users who can sign into the local test app.',
+  idField: 'id',
+  fields: {
+    id: field.string({
+      required: true,
+      description: 'Stable user id.',
+    }),
+    name: field.string({
+      required: true,
+      description: 'Display name shown in the UI.',
+    }),
+    email: field.string({
+      required: true,
+      description: 'Unique email address.',
+    }),
+    role: field.enum(['admin', 'editor', 'user'], {
+      default: 'user',
+      description: 'Local authorization role.',
+    }),
+    twitterHandle: field.string({
+      description: 'Optional social handle used by local profile demos.',
+    }),
+    profile: field.object({
+      title: field.string({ default: 'Contributor' }),
+      location: field.string({ default: 'Remote' }),
+    }),
+  },
+});

package/examples/advanced/db.config.mjs

@@ -0,0 +1,18 @@
+// @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',
+  },
+});

package/examples/advanced/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Advanced Schema Mix",
+  "description": "Mixed data and schema sources, .schema.mjs helpers, defaults, nested objects, and committed generated types.",
+  "tags": ["schema-mjs", "mixed-mode", "defaults"]
+}

package/examples/advanced/src/generated/db.types.d.ts

@@ -0,0 +1,64 @@
+/* eslint-disable */
+// This file is generated by db. Do not edit by hand.
+
+export type ProjectStatus =
+  | "planned"
+  | "active"
+  | "paused"
+  | "done";
+
+export type UserRole = "admin" | "editor" | "user";
+
+export type Project = {
+  id: string;
+  name: string;
+  ownerId: string;
+  status?: ProjectStatus;
+  metadata?: {
+    priority?: string;
+  };
+};
+
+export type Settings = {
+  features?: {
+    billing?: boolean;
+    graphql?: boolean;
+  };
+  locale?: string;
+  theme?: string;
+};
+
+/** Users who can sign into the local test app. */
+export type User = {
+  /** Stable user id. */
+  id: string;
+  /** Display name shown in the UI. */
+  name: string;
+  /** Unique email address. */
+  email: string;
+  /** Local authorization role. */
+  role?: UserRole;
+  /** Optional social handle used by local profile demos. */
+  twitterHandle?: string;
+  profile?: {
+    title?: string;
+    location?: string;
+  };
+};
+
+export type DbCollections = {
+  projects: Project;
+  users: User;
+};
+
+export type DbDocuments = {
+  settings: Settings;
+};
+
+export type DbTypes = {
+  collections: DbCollections;
+  documents: DbDocuments;
+};
+
+export type DbCollectionName = keyof DbCollections;
+export type DbDocumentName = keyof DbDocuments;

package/examples/basic/README.md

@@ -0,0 +1,95 @@
+# Basic Example
+
+## What This Teaches
+
+Start here when you want the smallest schema-backed db workflow. It demonstrates sync, committed generated types, the viewer, fixture-like `.json` REST reads, and creating a record.
+
+## Files To Inspect
+
+- [db/users.schema.jsonc](./db/users.schema.jsonc): schema-backed collection with seed data.
+- [db/settings.json](./db/settings.json): singleton document inferred from data.
+- [db/operations/get-user.jsonc](./db/operations/get-user.jsonc): optional registered REST operation template.
+- [src/generated/db.types.d.ts](./src/generated/db.types.d.ts): committed generated types.
+
+## Run It
+
+From the repository root, use the repo-internal CLI path:
+
+```bash
+npm run db -- sync --cwd ./examples/basic
+npm run db -- operations build --cwd ./examples/basic
+npm run db -- serve --cwd ./examples/basic
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+## Expected Result
+
+`sync` writes generated schema, types, and runtime state under `examples/basic/.db/`, plus the committed type copy in `src/generated/`.
+
+`operations build` writes a full server registry and client-safe refs under
+`examples/basic/src/generated/`.
+
+To review the browser-facing operation contract without volatile timestamps:
+
+```bash
+npm run db -- operations contract --cwd ./examples/basic
+npm run db -- operations contract --cwd ./examples/basic --check
+```
+
+## REST Request To Try
+
+Leave `serve` running and run this from another terminal:
+
+```bash
+curl http://127.0.0.1:7331/db/users.json
+```
+
+The `.json` route is intentional: a source fixture such as `db/users.json`
+maps naturally to `GET /db/users.json`, while the server still reads from the
+synced runtime resource under `.db/state`.
+
+Create a local runtime record:
+
+```bash
+curl -X POST http://127.0.0.1:7331/db/users \
+  -H 'content-type: application/json' \
+  -d '{"id":"u_2","name":"Grace Hopper","email":"grace@example.com"}'
+```
+
+The equivalent CLI smoke command is:
+
+```bash
+npm run db -- create users '{"id":"u_2","name":"Grace Hopper","email":"grace@example.com"}' --cwd ./examples/basic
+```
+
+## Registered Operation To Try
+
+Build operations, then use the generated ref from
+`examples/basic/src/generated/db.operation-refs.json`:
+
+```bash
+curl -X POST http://127.0.0.1:7331/__db/operations/REF \
+  -H 'content-type: application/json' \
+  -d '{"variables":{"id":"u_1"}}'
+```
+
+## Features To Notice
+
+- [Fixture-like `.json` REST routes](../../docs/server-and-viewer.md#fixture-like-json-routes)
+- [Schema-backed fixtures](../../docs/fixtures-and-schemas.md#schema-files)
+- [Generated types](../../docs/generated-files.md#generated-types)
+- [Registered REST operations](../../docs/server-and-viewer.md#registered-rest-operations)
+
+## Cleanup
+
+Generated `.db/` output is ignored by git and can be removed whenever you want a fresh mirror.
+
+## More Docs
+
+- [Getting Started](../../docs/getting-started.md)
+- [Generated Files](../../docs/generated-files.md)

package/examples/basic/db/operations/get-user.jsonc

@@ -0,0 +1,8 @@
+{
+  "name": "GetUser",
+  "method": "GET",
+  "path": "/users/{id}.json",
+  "query": {
+    "select": "id,name,email"
+  }
+}

package/examples/basic/db/settings.json

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

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

@@ -0,0 +1,36 @@
+{
+  // Users who can sign into the local test app.
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable user id."
+    },
+    "name": {
+      "type": "string",
+      "required": true,
+      "description": "Display name shown in the UI."
+    },
+    "email": {
+      "type": "string",
+      "required": true,
+      "description": "Unique email address."
+    },
+    "role": {
+      "type": "enum",
+      "values": ["admin", "user"],
+      "default": "user",
+      "description": "Local authorization role."
+    }
+  },
+  "seed": [
+    {
+      "id": "u_1",
+      "name": "Ada Lovelace",
+      "email": "ada@example.com",
+      "role": "admin"
+    }
+  ]
+}

package/examples/basic/db.config.mjs

@@ -0,0 +1,68 @@
+// @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',
+    operationRegistry: './src/generated/db.operations.json',
+    operationRefs: './src/generated/db.operation-refs.json',
+  },
+  types: {
+    enabled: true,
+    emitComments: true,
+  },
+  schema: {
+    unknownFields: 'warn',
+  },
+  operations: {
+    enabled: false,
+    sourceDir: './db/operations',
+  },
+  rest: {
+    formats: {
+      yaml: {
+        mediaTypes: ['application/yaml', 'text/yaml'],
+        contentType: 'application/yaml; charset=utf-8',
+        render({ data }) {
+          return `${toYaml(data)}\n`;
+        },
+      },
+    },
+  },
+});
+
+function toYaml(value, indent = 0) {
+  const pad = ' '.repeat(indent);
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      if (item && typeof item === 'object') {
+        return `${pad}-\n${toYaml(item, indent + 2)}`;
+      }
+      return `${pad}- ${formatYamlScalar(item)}`;
+    }).join('\n');
+  }
+
+  if (value && typeof value === 'object') {
+    return Object.entries(value).map(([key, item]) => {
+      if (item && typeof item === 'object') {
+        return `${pad}${key}:\n${toYaml(item, indent + 2)}`;
+      }
+      return `${pad}${key}: ${formatYamlScalar(item)}`;
+    }).join('\n');
+  }
+
+  return `${pad}${formatYamlScalar(value)}`;
+}
+
+function formatYamlScalar(value) {
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+  if (value === null) {
+    return 'null';
+  }
+  return String(value);
+}

package/examples/basic/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Basic",
+  "description": "The smallest schema-backed workflow: sync fixtures, inspect the viewer, and create a record through REST or the CLI.",
+  "tags": ["quick-start", "schema", "rest"]
+}

package/examples/basic/src/generated/db.types.d.ts

@@ -0,0 +1,39 @@
+/* eslint-disable */
+// This file is generated by db. Do not edit by hand.
+
+export type UserRole = "admin" | "user";
+
+export type Settings = {
+  features?: {
+    billing?: boolean;
+  };
+  locale?: string;
+  theme?: string;
+};
+
+export type User = {
+  /** Stable user id. */
+  id: string;
+  /** Display name shown in the UI. */
+  name: string;
+  /** Unique email address. */
+  email: string;
+  /** Local authorization role. */
+  role?: UserRole;
+};
+
+export type DbCollections = {
+  users: User;
+};
+
+export type DbDocuments = {
+  settings: Settings;
+};
+
+export type DbTypes = {
+  collections: DbCollections;
+  documents: DbDocuments;
+};
+
+export type DbCollectionName = keyof DbCollections;
+export type DbDocumentName = keyof DbDocuments;

package/examples/cms-json-publish/README.md

@@ -0,0 +1,21 @@
+# CMS JSON Publish Example
+
+This example shows how an app can build CMS behavior on top of generic `@async/db` primitives. The CMS helper is app code, not package API.
+
+Run it from the repository root:
+
+```bash
+npm run db -- sync --cwd ./examples/cms-json-publish
+node ./examples/cms-json-publish/src/cms.mjs
+```
+
+The script:
+
+- creates a tenant fork
+- creates `draft` and `published` branches
+- saves draft content in `draft`
+- filters public records in app code
+- writes only published records into `published`
+- serves public JSON from the `published` branch
+
+`@async/db/json` stores the branch files; the app decides what `published` means.

package/examples/cms-json-publish/db/navigation.json

@@ -0,0 +1,7 @@
+[
+  {
+    "id": "nav_home",
+    "label": "Home",
+    "slug": "home"
+  }
+]

package/examples/cms-json-publish/db/pages.json

@@ -0,0 +1,18 @@
+[
+  {
+    "id": "home",
+    "slug": "home",
+    "title": "Home",
+    "status": "published",
+    "summary": "Public home page",
+    "bodyMarkdown": "# Home"
+  },
+  {
+    "id": "roadmap",
+    "slug": "roadmap",
+    "title": "Roadmap",
+    "status": "draft",
+    "summary": "Draft roadmap",
+    "bodyMarkdown": "# Roadmap"
+  }
+]

package/examples/cms-json-publish/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "CMS JSON Publish",
+  "description": "App-owned CMS helper that uses branches to publish public JSON.",
+  "tags": ["cms", "forks", "branches", "json"]
+}

package/examples/cms-json-publish/src/cms.mjs

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { openDb } from '@async/db';
+
+export function createCms(db, { tenantId }) {
+  return {
+    async setup() {
+      const tenant = await db.forks.ensure(tenantId, {
+        from: 'main',
+        metadata: {
+          purpose: 'tenant',
+          app: 'cms-json-publish',
+        },
+      });
+      await tenant.branches.ensure('draft', { from: 'main', metadata: { purpose: 'draft' } });
+      await tenant.branches.ensure('published', { from: 'main', metadata: { purpose: 'published' } });
+    },
+
+    async saveDraft(pageId, changes) {
+      const tenant = await db.forks.open(tenantId);
+      const draft = await tenant.branches.open('draft');
+      return draft.collection('pages').patch(pageId, {
+        ...changes,
+        status: 'draft',
+        updatedAt: new Date().toISOString(),
+      });
+    },
+
+    async createPreview(previewId) {
+      const tenant = await db.forks.open(tenantId);
+      return tenant.branches.create(previewId, {
+        from: 'draft',
+        metadata: { purpose: 'preview' },
+      });
+    },
+
+    async publish({ label = 'publish' } = {}) {
+      const tenant = await db.forks.open(tenantId);
+      const draft = await tenant.branches.open('draft');
+      const published = await tenant.branches.open('published');
+      const snapshot = await draft.snapshots.create({
+        label,
+        resources: ['pages', 'navigation'],
+      });
+      const pages = await draft.collection('pages').all();
+      const publicPages = pages
+        .filter((page) => page.status === 'published')
+        .map(({ id, slug, title, status, summary, bodyMarkdown }) => ({
+          id,
+          slug,
+          title,
+          status,
+          summary,
+          bodyMarkdown,
+        }));
+
+      await published.collection('pages').replaceAll(publicPages);
+      await published.collection('navigation').replaceAll(await draft.collection('navigation').all());
+
+      return {
+        snapshot,
+        publicPages,
+      };
+    },
+
+    async listPublishedPages() {
+      const tenant = await db.forks.open(tenantId);
+      const published = await tenant.branches.open('published');
+      return published.collection('pages').all();
+    },
+  };
+}
+
+async function main() {
+  const db = await openDb({
+    cwd: new URL('../', import.meta.url).pathname,
+  });
+  const cms = createCms(db, { tenantId: 'tenant_acme' });
+
+  await cms.setup();
+  await cms.saveDraft('roadmap', {
+    title: 'Private roadmap',
+  });
+  await cms.createPreview('preview_homepage');
+  const { publicPages } = await cms.publish({ label: 'initial-public-json' });
+
+  assert.deepEqual(publicPages.map((page) => page.slug), ['home']);
+  assert.deepEqual(await cms.listPublishedPages(), [
+      {
+        id: 'home',
+        slug: 'home',
+        title: 'Home',
+        status: 'published',
+        summary: 'Public home page',
+        bodyMarkdown: '# Home',
+      },
+  ]);
+
+  await db.close();
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  await main();
+}