@async/db 0.2.0

package/examples/free-plan-upgrade/src/upgrade-tenant-to-paid.mjs

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { openDb } from '@async/db';
+
+const paidStoreData = new Map();
+
+export async function openUpgradeDemoDb() {
+  return openDb({
+    cwd: new URL('../', import.meta.url).pathname,
+    stores: {
+      default: 'json',
+      paidPostgres: {
+        read(resource, fallback) {
+          return paidStoreData.has(resource.name) ? paidStoreData.get(resource.name) : fallback;
+        },
+        write(resource, value) {
+          paidStoreData.set(resource.name, value);
+        },
+      },
+    },
+  });
+}
+
+export async function upgradeTenantToPaid({ db, tenantId }) {
+  const tenant = await db.forks.ensure(tenantId, {
+    from: 'main',
+    metadata: {
+      purpose: 'tenant',
+      plan: 'free',
+    },
+  });
+
+  const backup = await tenant.snapshots.create({
+    label: 'before-paid-upgrade',
+    resources: ['projects'],
+  });
+
+  await tenant.migrations.start('projects-to-paid-postgres', {
+    resources: ['projects'],
+    mode: 'read-only',
+  });
+
+  await tenant.resources.migrate('projects', {
+    from: 'json',
+    to: 'paidPostgres',
+  });
+
+  await tenant.migrations.verify('projects-to-paid-postgres', {
+    resources: ['projects'],
+    checks: ['count', 'checksum'],
+  });
+
+  await tenant.routing.set({
+    projects: 'paidPostgres',
+  });
+
+  await tenant.migrations.finish('projects-to-paid-postgres');
+
+  return {
+    tenant,
+    backup,
+  };
+}
+
+async function main() {
+  const db = await openUpgradeDemoDb();
+  const { tenant, backup } = await upgradeTenantToPaid({
+    db,
+    tenantId: 'tenant_acme',
+  });
+
+  assert.equal(backup.resources.includes('projects'), true);
+  assert.deepEqual(await tenant.collection('projects').all(), [
+    {
+      id: 'p_1',
+      name: 'Launch checklist',
+      status: 'active',
+    },
+  ]);
+
+  await tenant.collection('projects').create({
+    id: 'p_2',
+    name: 'Paid workspace project',
+    status: 'active',
+  });
+
+  assert.deepEqual(paidStoreData.get('projects'), [
+    {
+      id: 'p_1',
+      name: 'Launch checklist',
+      status: 'active',
+    },
+    {
+      id: 'p_2',
+      name: 'Paid workspace project',
+      status: 'active',
+    },
+  ]);
+
+  await db.close();
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  await main();
+}

package/examples/hono-auth/README.md

@@ -0,0 +1,74 @@
+# Hono Auth Example
+
+## What This Teaches
+
+Use this when your app already has a Hono server and you want db to own the CRUD routes while your app owns auth, permissions, and write normalization.
+
+## Files To Inspect
+
+- [src/app.mjs](./src/app.mjs): registers db REST routes with `beforeRequest`, `beforeWrite`, and a pages-specific create hook.
+- [src/server.mjs](./src/server.mjs): starts the Hono app locally.
+- [db/pages.schema.jsonc](./db/pages.schema.jsonc): schema-backed page collection with timestamps set by hooks.
+- [db/users.schema.jsonc](./db/users.schema.jsonc): demo users used by the bearer-token sessions.
+
+## Run It
+
+From this example directory:
+
+```bash
+npm install
+npm run sync
+npm run dev
+```
+
+## Requests To Try
+
+Leave `npm run dev` running and run these from another terminal.
+
+Missing tokens are rejected:
+
+```bash
+curl -i 'http://127.0.0.1:8787/api/pages'
+```
+
+Reader tokens can read:
+
+```bash
+curl -H 'Authorization: Bearer user-token' 'http://127.0.0.1:8787/api/pages'
+```
+
+Reader tokens cannot write:
+
+```bash
+curl -i -X PATCH 'http://127.0.0.1:8787/api/pages/home' \
+  -H 'Authorization: Bearer user-token' \
+  -H 'content-type: application/json' \
+  -d '{"title":"Draft"}'
+```
+
+Admin tokens can write. The shared write hook trims strings and sets `updatedAt`:
+
+```bash
+curl -X PATCH 'http://127.0.0.1:8787/api/pages/home' \
+  -H 'Authorization: Bearer admin-token' \
+  -H 'content-type: application/json' \
+  -d '{"title":"  Homepage  "}'
+```
+
+## Token Map
+
+- `Bearer admin-token`: read and write.
+- `Bearer user-token`: read only.
+
+This is intentionally tiny demo auth. In a real app, `beforeRequest` would read your session or token source, and `beforeWrite` would call your permission policy.
+
+## Features To Notice
+
+- [Hono route registration](../../docs/integrations.md#hono-route-registration)
+- [Lifecycle hooks](../../docs/integrations.md#hono-route-registration)
+- [Schema-backed fixtures](../../docs/fixtures-and-schemas.md#schema-files)
+
+## More Docs
+
+- [Integrations](../../docs/integrations.md)
+- [Server And Viewer](../../docs/server-and-viewer.md)

package/examples/hono-auth/db/pages.schema.jsonc

@@ -0,0 +1,44 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable page id used in routes and links."
+    },
+    "title": {
+      "type": "string",
+      "required": true,
+      "description": "Human-readable page title."
+    },
+    "visibility": {
+      "type": "enum",
+      "values": ["public", "private"],
+      "default": "private",
+      "description": "Whether the page can be shown publicly."
+    },
+    "body": {
+      "type": "string",
+      "description": "Short markdown-like page body for the demo."
+    },
+    "createdAt": {
+      "type": "datetime",
+      "description": "Timestamp assigned by the pages create hook."
+    },
+    "updatedAt": {
+      "type": "datetime",
+      "description": "Timestamp assigned by the shared write hook."
+    }
+  },
+  "seed": [
+    {
+      "id": "home",
+      "title": "Home",
+      "visibility": "public",
+      "body": "Welcome to the db Hono auth example.",
+      "createdAt": "2026-05-14T00:00:00.000Z",
+      "updatedAt": "2026-05-14T00:00:00.000Z"
+    }
+  ]
+}

package/examples/hono-auth/db/users.schema.jsonc

@@ -0,0 +1,42 @@
+{
+  "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 app."
+    },
+    "email": {
+      "type": "string",
+      "required": true,
+      "unique": true,
+      "description": "Email address used for local sign-in."
+    },
+    "role": {
+      "type": "enum",
+      "values": ["admin", "user"],
+      "default": "user",
+      "description": "Local authorization role."
+    }
+  },
+  "seed": [
+    {
+      "id": "u_admin",
+      "name": "Admin Example",
+      "email": "admin@example.com",
+      "role": "admin"
+    },
+    {
+      "id": "u_user",
+      "name": "Reader Example",
+      "email": "reader@example.com",
+      "role": "user"
+    }
+  ]
+}

package/examples/hono-auth/db.config.mjs

@@ -0,0 +1,17 @@
+// @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,
+    emitComments: true,
+  },
+  schema: {
+    unknownFields: 'warn',
+  },
+});

package/examples/hono-auth/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Hono Auth",
+  "description": "A small Hono app that uses registerDbRoutes lifecycle hooks for bearer-token auth, write permissions, and payload normalization.",
+  "tags": ["hono", "auth", "rest"]
+}

package/examples/hono-auth/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "db-hono-auth-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node ./src/server.mjs",
+    "sync": "async-db sync --cwd ."
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.13.8",
+    "hono": "^4.6.0",
+    "@async/db": "file:../.."
+  }
+}

package/examples/hono-auth/src/app.mjs

@@ -0,0 +1,79 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { openDb } from '@async/db';
+import { registerDbRoutes } from '@async/db/hono';
+
+const exampleRoot = fileURLToPath(new URL('..', import.meta.url));
+
+export const demoAuthorizationHeaders = {
+  admin: 'Bearer admin-token',
+  user: 'Bearer user-token',
+};
+
+const demoSessions = new Map([
+  [authorizationToken(demoAuthorizationHeaders.admin), { userId: 'u_admin', role: 'admin' }],
+  [authorizationToken(demoAuthorizationHeaders.user), { userId: 'u_user', role: 'user' }],
+]);
+
+export async function createApp(options = {}) {
+  const { Hono } = await import('hono');
+  const app = new Hono();
+  const db = options.db ?? await openDb({
+    cwd: options.cwd ?? path.resolve(exampleRoot),
+  });
+
+  registerDbRoutes(app, db, {
+    prefix: '/api',
+    resources: ['pages', 'users'],
+    lifecycleHooks: {
+      beforeRequest(ctx) {
+        const session = sessionFromAuthorizationHeader(ctx.c.req.header('authorization'));
+        if (!session) {
+          return ctx.c.json({ error: 'Unauthorized' }, 401);
+        }
+        ctx.c.set('session', session);
+      },
+      beforeWrite(ctx) {
+        const session = ctx.c.get('session');
+        if (session?.role !== 'admin') {
+          return ctx.c.json({ error: 'Forbidden' }, 403);
+        }
+        normalizeWriteBody(ctx.body);
+      },
+    },
+    resourceOptions: {
+      pages: {
+        hooks: {
+          beforeCreate(ctx) {
+            ctx.body.createdAt ??= ctx.body.updatedAt;
+          },
+        },
+      },
+    },
+  });
+
+  return app;
+}
+
+export function sessionFromAuthorizationHeader(header) {
+  return demoSessions.get(authorizationToken(header)) ?? null;
+}
+
+function authorizationToken(header) {
+  const match = /^Bearer\s+(.+)$/i.exec(String(header ?? ''));
+  return match?.[1] ?? null;
+}
+
+function normalizeWriteBody(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return;
+  }
+
+  for (const [key, value] of Object.entries(body)) {
+    if (typeof value === 'string') {
+      body[key] = value.trim();
+    }
+  }
+
+  body.updatedAt = new Date().toISOString();
+}

package/examples/hono-auth/src/server.mjs

@@ -0,0 +1,13 @@
+import { serve } from '@hono/node-server';
+import { createApp } from './app.mjs';
+
+const port = Number(process.env.PORT ?? 8787);
+const app = await createApp();
+
+serve({
+  fetch: app.fetch,
+  hostname: '127.0.0.1',
+  port,
+});
+
+console.log(`db Hono auth example: http://127.0.0.1:${port}`);

package/examples/production-json/README.md

@@ -0,0 +1,102 @@
+# Production JSON Example
+
+## What This Teaches
+
+Use this when an app has small production control-plane data that should stay in reviewed JSON while browser traffic goes through registered operations. It models feature flags and public app settings as file-backed JSON resources, then exposes only operation refs to client code.
+
+## Files To Inspect
+
+- [db/featureFlags.schema.jsonc](./db/featureFlags.schema.jsonc): low-write feature flag records with explicit schema.
+- [db/appSettings.schema.jsonc](./db/appSettings.schema.jsonc): singleton production settings document.
+- [db/operations](./db/operations): registered operation templates for browser-facing reads.
+- [db.config.mjs](./db.config.mjs): enables operation-only REST exposure and ref-only operation calls.
+- [src/client-demo.mjs](./src/client-demo.mjs): tiny client script that calls generated operation refs.
+- [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/production-json
+npm run db -- operations build --cwd ./examples/production-json
+npm run db -- serve --cwd ./examples/production-json
+```
+
+In another terminal:
+
+```bash
+ASYNC_DB_URL=http://127.0.0.1:7331 node ./examples/production-json/src/client-demo.mjs
+```
+
+## Expected Result
+
+`sync` writes generated schema, types, and runtime state under `examples/production-json/.db/`, plus the committed type copy in `src/generated/`.
+
+`operations build` writes client-safe operation refs under `examples/production-json/src/generated/`. The server reads templates from `db/operations`, while the demo script reads generated refs and calls `GetControlPlane` and `GetFeatureFlag` through `client.query()`.
+
+To review the browser-facing operation contract without volatile timestamps:
+
+```bash
+npm run db -- operations contract --cwd ./examples/production-json
+npm run db -- operations contract --cwd ./examples/production-json --check
+```
+
+## Operation Requests To Try
+
+Build operations, then use the generated ref from `examples/production-json/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":"flag_billing_v2"}}'
+```
+
+Raw REST routes are intentionally not the production-facing API in this example. `server.expose.rest: 'registered-only'` keeps app traffic on the registered operation boundary while the JSON files remain the first-party store.
+
+## Why This Shape?
+
+Feature flags and app settings are control-plane resources: small, low-write, easy to review, and useful to snapshot. That makes them a realistic production fit for `@async/db/json`.
+
+The app should still evaluate sensitive targeting, auth, rate limits, and policy in app-owned code. The JSON store keeps the reviewed flag definitions; registered operations keep browser calls stable if a resource later graduates to SQLite, Postgres, Redis, or a custom store.
+
+## Graduating One Resource
+
+Keep `appSettings` and `featureFlags` on JSON when they remain small and low-write. If a new `orders` resource outgrows JSON, add a database store and move only that resource:
+
+```js
+import { defineConfig } from '@async/db/config';
+import { postgresStore } from '@async/db/postgres';
+import { pool } from './src/server/postgres-client.js';
+
+export default defineConfig({
+  stores: {
+    default: 'json',
+    appDb: postgresStore({ client: pool }),
+  },
+  resources: {
+    appSettings: { store: 'json' },
+    featureFlags: { store: 'json' },
+    orders: { store: 'appDb' },
+  },
+  operations: {
+    enabled: true,
+    acceptRefs: 'ref',
+    sourceDir: './db/operations',
+  },
+});
+```
+
+Operation templates that read `appSettings`, `featureFlags`, or `orders` stay behind the same `client.query(ref, variables)` call shape. The resource store changes; the browser contract does not.
+
+## Features To Notice
+
+- [Production JSON Database](../../docs/json-production.md)
+- [Resource Graduation And Mixed Stores](../../docs/store-graduation.md)
+- [Registered REST operations](../../docs/server-and-viewer.md#registered-rest-operations)
+- [Operation-only exposure](../../docs/configuration.md#server-exposure)
+- [Generated operation refs](../../docs/generated-files.md#operation-registry-output)
+
+## Cleanup
+
+Generated `.db/` output is ignored by git and can be removed whenever you want a fresh mirror. Generated operation ref files under `src/generated/` are safe to regenerate after operation template changes.

package/examples/production-json/db/appSettings.schema.jsonc

@@ -0,0 +1,41 @@
+{
+  "kind": "document",
+  "description": "Small production settings that are safe to keep as reviewed JSON.",
+  "fields": {
+    "appName": {
+      "type": "string",
+      "required": true,
+      "description": "Public product name shown by the app shell."
+    },
+    "environment": {
+      "type": "enum",
+      "values": ["development", "staging", "production"],
+      "required": true,
+      "description": "Deployment lane this settings file belongs to."
+    },
+    "maintenanceMode": {
+      "type": "boolean",
+      "required": true,
+      "default": false,
+      "description": "Whether the public app should show maintenance UI."
+    },
+    "defaultLocale": {
+      "type": "string",
+      "required": true,
+      "default": "en-US",
+      "description": "Fallback locale for unauthenticated visitors."
+    },
+    "supportEmail": {
+      "type": "string",
+      "required": true,
+      "description": "Public support contact shown in product chrome."
+    }
+  },
+  "seed": {
+    "appName": "Launch Console",
+    "environment": "production",
+    "maintenanceMode": false,
+    "defaultLocale": "en-US",
+    "supportEmail": "support@example.test"
+  }
+}

package/examples/production-json/db/featureFlags.schema.jsonc

@@ -0,0 +1,84 @@
+{
+  "kind": "collection",
+  "description": "Low-write production feature flags that control app behavior.",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable flag id used by operations and review notes."
+    },
+    "key": {
+      "type": "string",
+      "required": true,
+      "unique": true,
+      "description": "Stable application flag key."
+    },
+    "enabled": {
+      "type": "boolean",
+      "required": true,
+      "default": false,
+      "description": "Global default before app-owned targeting runs."
+    },
+    "audience": {
+      "type": "enum",
+      "values": ["everyone", "staff", "beta", "enterprise"],
+      "required": true,
+      "default": "staff",
+      "description": "Coarse audience label consumed by the app policy layer."
+    },
+    "rolloutPercent": {
+      "type": "number",
+      "required": true,
+      "default": 0,
+      "description": "Default rollout percentage for app-owned evaluation."
+    },
+    "description": {
+      "type": "string",
+      "required": true,
+      "description": "Human review note explaining the flag."
+    },
+    "owner": {
+      "type": "string",
+      "required": true,
+      "description": "Team or person responsible for changing this flag."
+    },
+    "updatedAt": {
+      "type": "string",
+      "required": true,
+      "description": "ISO timestamp for the last reviewed flag change."
+    }
+  },
+  "seed": [
+    {
+      "id": "flag_billing_v2",
+      "key": "billing.v2",
+      "enabled": true,
+      "audience": "beta",
+      "rolloutPercent": 25,
+      "description": "Expose the new billing flow to beta accounts.",
+      "owner": "growth",
+      "updatedAt": "2026-05-01T12:00:00Z"
+    },
+    {
+      "id": "flag_enterprise_dashboard",
+      "key": "dashboard.enterprise",
+      "enabled": true,
+      "audience": "enterprise",
+      "rolloutPercent": 100,
+      "description": "Show enterprise reporting navigation.",
+      "owner": "platform",
+      "updatedAt": "2026-05-03T09:30:00Z"
+    },
+    {
+      "id": "flag_editor_command_palette",
+      "key": "editor.commandPalette",
+      "enabled": false,
+      "audience": "staff",
+      "rolloutPercent": 0,
+      "description": "Internal preview of command palette shortcuts.",
+      "owner": "product",
+      "updatedAt": "2026-05-05T16:45:00Z"
+    }
+  ]
+}

package/examples/production-json/db/operations/get-control-plane.jsonc

@@ -0,0 +1,6 @@
+{
+  "name": "GetControlPlane",
+  "kind": "graphql",
+  "operationName": "GetControlPlane",
+  "query": "query GetControlPlane { appSettings { appName environment maintenanceMode defaultLocale supportEmail } featureFlags { id key enabled audience rolloutPercent description owner updatedAt } }"
+}

package/examples/production-json/db/operations/get-feature-flag.jsonc

@@ -0,0 +1,9 @@
+{
+  "name": "GetFeatureFlag",
+  "method": "GET",
+  "path": "/feature-flags.json",
+  "query": {
+    "id": "{id}",
+    "select": "id,key,enabled,audience,rolloutPercent,description,owner,updatedAt"
+  }
+}

package/examples/production-json/db/operations/list-feature-flags.jsonc

@@ -0,0 +1,8 @@
+{
+  "name": "ListFeatureFlags",
+  "method": "GET",
+  "path": "/feature-flags.json",
+  "query": {
+    "select": "id,key,enabled,audience,rolloutPercent,description,owner,updatedAt"
+  }
+}

package/examples/production-json/db/operations/read-public-settings.jsonc

@@ -0,0 +1,8 @@
+{
+  "name": "ReadPublicSettings",
+  "method": "GET",
+  "path": "/app-settings.json",
+  "query": {
+    "select": "appName,environment,maintenanceMode,defaultLocale,supportEmail"
+  }
+}