@async/db 0.2.0

package/docs/generated-files.md

@@ -0,0 +1,174 @@
+# Generated Files
+
+@async/db writes generated output during `sync`, `serve`, package API startup, and some smoke commands. Know which files are runtime state and which files are intentionally committed.
+
+## Default Generated Output
+
+Default sync output:
+
+```txt
+.db/schema.generated.json
+.db/types/index.d.ts
+.db/state/*.json
+```
+
+`.db/` is normally uncommitted. It contains generated schema metadata, generated TypeScript types, source metadata, and writable runtime store state.
+
+## Runtime State
+
+With the default JSON store:
+
+```txt
+db/users.json              source fixture
+.db/state/users.json   writable runtime JSON store
+```
+
+REST writes, GraphQL mutations, package API writes, and viewer operations write to runtime state. Changed source fixtures refresh state based on source hashes; unchanged source fixtures preserve runtime edits.
+
+## Generated Ids
+
+Collections need ids. If a JSON, JSONC, or CSV collection fixture omits `id`, @async/db adds counter ids in the selected runtime store.
+
+Source fixtures stay unchanged by default. For resources bound to the `sourceFile` store, @async/db may write generated ids back to plain `.json` collection fixtures when configured intentionally.
+
+## Generated Types
+
+Default generated TypeScript output:
+
+```txt
+.db/types/index.d.ts
+```
+
+Use `outputs.committedTypes` when TypeScript imports should work before anyone runs sync:
+
+```js
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  outputs: {
+    committedTypes: './src/generated/db.types.d.ts',
+  },
+});
+```
+
+Field descriptions become TypeScript JSDoc:
+
+```ts
+export type User = {
+  /** Stable user id. */
+  id: string;
+
+  /** Email address used for local sign-in. */
+  email: string;
+};
+```
+
+Selected examples intentionally commit generated type output:
+
+```txt
+examples/advanced/src/generated/db.types.d.ts
+examples/basic/src/generated/db.types.d.ts
+examples/computed-fields/src/generated/db.types.d.ts
+examples/content-collections/src/generated/db.types.d.ts
+examples/production-json/src/generated/db.types.d.ts
+examples/schema-first/src/generated/db.types.d.ts
+examples/schema-manifest/src/generated/db.types.d.ts
+examples/schema-ui/src/generated/db.types.d.ts
+```
+
+## Schema Manifest Output
+
+Use `outputs.schemaManifest` when a local admin, CMS, or form-building UI needs runtime schema metadata:
+
+```js
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  outputs: {
+    schemaManifest: './src/generated/db.schema.json',
+  },
+});
+```
+
+`async-db sync` writes the manifest when `outputs.schemaManifest` is set. You can also generate it directly:
+
+```bash
+npm run db -- schema manifest --out ./src/generated/db.schema.json
+```
+
+The manifest includes normalized resource and field metadata such as `type`, `required`, `nullable`, `default`, `values`, nested `fields`, array `items`, relations, and generated UI defaults. The manifest file is metadata output only. Schema field defaults still drive configured runtime behavior such as create-time defaults and safe additive store hydration.
+
+The manifests at [examples/schema-manifest/src/generated/db.schema.json](../examples/schema-manifest/src/generated/db.schema.json) and [examples/schema-ui/src/generated/db.schema.json](../examples/schema-ui/src/generated/db.schema.json) are intentionally committed.
+
+## Viewer Manifest Output
+
+Use `outputs.viewerManifest` when a custom data viewer needs the same JSON metadata used by the built-in viewer:
+
+```js
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  outputs: {
+    viewerManifest: './src/generated/db.viewer.json',
+  },
+});
+```
+
+`async-db sync` writes the viewer manifest when `outputs.viewerManifest` is set. You can also generate it directly:
+
+```bash
+npm run db -- viewer manifest --out ./src/generated/db.viewer.json
+```
+
+The viewer manifest includes field metadata, UI hints, relation hints, diagnostics, capabilities, configured viewer links, and API links such as `/__db/manifest`, `/__db/manifest.json`, `/__db/manifest.html`, `/__db/manifest.md`, `/__db/batch`, `/graphql`, and scoped REST resource routes under `/__db/rest`. It does not include seed records, source paths, source hashes, runtime state paths, or GraphQL SDL. Fetch actual records from REST or GraphQL.
+
+## Operation Registry And Client Contract
+
+Use `outputs.operationRegistry` for the full server-side operation registry and
+`outputs.operationRefs` for the client-safe refs file:
+
+```js
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  outputs: {
+    operationRegistry: './src/generated/db.operations.json',
+    operationRefs: './src/generated/db.operation-refs.json',
+  },
+});
+```
+
+Build both files with:
+
+```bash
+npm run db -- operations build
+```
+
+`db.operations.json` contains full templates and should stay server-side.
+`db.operation-refs.json` is the browser-facing surface: it exposes operation
+names and callable refs only, not paths, query templates, variables, request
+bodies, or server registry internals.
+
+For CI, use the deterministic contract view:
+
+```bash
+npm run db -- operations contract --check
+```
+
+The check compares the current generated client contract with
+`outputs.operationRefs` by default. It ignores volatile `generatedAt` values and
+fails only when exposed operation names or refs change.
+
+## Cleanup Rules
+
+- Do not commit `.db/` unless a task explicitly asks for generated runtime state.
+- Do commit configured `outputs.committedTypes` output when an app needs stable imports in a fresh checkout.
+- Do commit configured `outputs.schemaManifest` output when an app needs stable schema metadata at runtime.
+- Do commit configured `outputs.viewerManifest` output when a custom viewer needs stable metadata and route links at runtime.
+- Do commit configured `outputs.operationRefs` output when app or CI code imports approved registered operation refs.
+- Smoke commands against examples may create `examples/*/.db/`; remove that generated runtime output before finalizing.
+
+## Related Examples
+
+- [Basic](../examples/basic/README.md)
+- [Schema Manifest](../examples/schema-manifest/README.md)

package/docs/getting-started.md

@@ -0,0 +1,165 @@
+# Getting Started
+
+This guide takes a project from one fixture file to a local API, viewer, generated schema metadata, and generated TypeScript types.
+
+## Install
+
+Install @async/db from npm:
+
+```bash
+npm install @async/db
+```
+
+Add package scripts for the CLI commands you want to run often:
+
+```json
+{
+  "scripts": {
+    "db": "async-db",
+    "db:sync": "async-db sync",
+    "db:serve": "async-db serve",
+    "db:types": "async-db types"
+  }
+}
+```
+
+If you need an unreleased fix, pin a reviewed GitHub commit or release tag instead of the moving default branch:
+
+```json
+{
+  "devDependencies": {
+    "@async/db": "github:async-framework/async-db#<reviewed-commit-sha-or-tag>"
+  }
+}
+```
+
+The scripts use the local `node_modules/.bin/async-db` binary, so each project controls its own @async/db version.
+
+## Create A Fixture
+
+@async/db uses `./db` by default:
+
+```bash
+mkdir -p db
+cat > db/users.json <<'JSON'
+[
+  {
+    "id": "u_1",
+    "name": "Ada Lovelace",
+    "email": "ada@example.com"
+  }
+]
+JSON
+```
+
+## Sync
+
+```bash
+npm run db:sync
+```
+
+Sync reads fixtures and writes generated runtime output:
+
+```txt
+.db/schema.generated.json
+.db/types/index.d.ts
+.db/state/users.json
+```
+
+By default, app writes update the generated JSON store under `.db/state`. Source fixtures stay unchanged.
+
+## Serve
+
+In terminal 1:
+
+```bash
+npm run db:serve
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+In terminal 2, call the REST API:
+
+```bash
+curl http://127.0.0.1:7331/db/users.json
+```
+
+You can also read one record through the fixture-shaped URL:
+
+```bash
+curl 'http://127.0.0.1:7331/db/users.json?id=u_1'
+```
+
+Create another 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 new record is written to `.db/state/users.json`, not `db/users.json`.
+
+## Add A Schema
+
+Add schema when the contract matters: required fields, defaults, descriptions, enums, uniqueness, relations, or stricter validation.
+
+Create `db/users.schema.json`:
+
+```json
+{
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": { "type": "string", "required": true },
+    "name": { "type": "string", "required": true },
+    "email": {
+      "type": "string",
+      "required": true,
+      "unique": true,
+      "description": "Email address used for local sign-in."
+    },
+    "role": {
+      "type": "enum",
+      "values": ["admin", "user"],
+      "default": "user"
+    }
+  }
+}
+```
+
+Validate:
+
+```bash
+npm run db -- schema validate
+```
+
+When `db/users.schema.json` and `db/users.json` both exist, the schema defines the contract and the data file provides seed records.
+
+## Run A Repo Example
+
+From this repository root:
+
+```bash
+npm run db -- sync --cwd ./examples/basic
+npm run db -- serve --cwd ./examples/basic
+```
+
+Open:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+The example README has the exact files and requests for that workflow: [examples/basic](../examples/basic/README.md).
+
+## Next Steps
+
+- Use [Concepts](./concepts.md) to understand data-first, schema-first, mixed resources, runtime stores, and source writebacks.
+- Use [Fixtures And Schemas](./fixtures-and-schemas.md) to author richer fixtures and schemas.
+- Use [Server And Viewer](./server-and-viewer.md) for REST, GraphQL, viewer, and watch behavior.
+- Use [Generated Files](./generated-files.md) before committing generated output.

package/docs/integrations.md

@@ -0,0 +1,206 @@
+# Integrations
+
+@async/db keeps integrations optional. The core package remains dependency-light; apps opt into Vite, Hono, SQLite, or generated starter code when they need those paths.
+
+## Vite Dev Server Plugin
+
+Vite apps can mount @async/db into the existing dev server instead of running `async-db serve` on a second port:
+
+```js
+import { defineConfig } from 'vite';
+import { dbPlugin } from '@async/db/vite';
+
+export default defineConfig({
+  plugins: [
+    dbPlugin(),
+  ],
+});
+```
+
+The plugin is dev-only (`apply: 'serve'`). It does not run during `vite build`, and it does not add a mandatory Vite dependency to @async/db.
+
+By default, app data routes use `/db`, while dev-tool routes stay scoped under `/__db`:
+
+```txt
+GET  /db/users.json
+GET  /__db
+GET  /__db/schema
+POST /__db/batch
+POST /__db/graphql
+GET  /__db/rest/users
+GET  /__db/rest/users/u_1
+```
+
+Use the virtual browser client from app code:
+
+```ts
+import db from 'virtual:db/client';
+
+const users = await db.rest.get('/users');
+const selected = await db.rest.get('/users?select=id,name');
+```
+
+Plugin options include `cwd`, `dbDir`, `outputs`, legacy `stateDir`, `apiBase`, `dataPath`, `restBasePath`, `graphqlPath`, `rootRoutes`, `clientVirtualModule`, `clientImport`, and `clientCache`.
+The plugin uses `apiBase` first, then `server.apiBase`, then `/__db` for scoped dev routes.
+Use `server.dataPath: false` to disable the `/db` app-facing data route alias.
+
+Set `clientCache: true` to opt the virtual browser client into the default
+memory cache during Vite dev. Object form supports serializable cache policy
+options:
+
+```ts
+dbPlugin({
+  clientCache: {
+    enabled: true,
+    readPolicy: 'cache-and-network',
+    writePolicy: 'merge-and-invalidate',
+    eventPolicy: 'refetch',
+  },
+});
+```
+
+Use `createDbClient()` directly when you need an explicit browser storage
+adapter such as `createIndexedDbCacheStorage(...)`.
+
+Add `trace` to the plugin options to override `db.config.mjs` for Vite dev
+requests:
+
+```ts
+dbPlugin({
+  trace: {
+    enabled: true,
+    slowMs: 100,
+  },
+});
+```
+
+Set `rootRoutes: true` only when you intentionally want Vite dev to also answer unscoped routes like `/users`. Standalone `async-db serve` keeps those root REST routes by default.
+
+The plugin watches fixture sources, not generated runtime output. @async/db also skips rewriting generated and state files when their content is unchanged, so normal `sync` or `openDb()` calls should not trigger Vite reloads by changing mtimes alone.
+
+If an app commits generated files under frontend source, Vite may still reload when those files genuinely change. Ignore only generated files that the browser does not need to hot reload.
+
+```ts
+export default defineConfig({
+  server: {
+    watch: {
+      ignored: [
+        '../.db/**',
+        // Only include committed generated files here when browser code
+        // does not import them at runtime.
+        'src/generated/db.schema.json',
+        'src/generated/db.types.d.ts',
+      ],
+    },
+  },
+});
+```
+
+## Hono Route Registration
+
+Apps that own a Hono instance can register @async/db REST routes and wrap them with lifecycle hooks.
+
+```ts
+import { registerDbRoutes } from '@async/db/hono';
+
+registerDbRoutes(app, db, {
+  prefix: '/api',
+  operations: true,
+  trace: true,
+  resources: ['pages', 'charts'],
+  lifecycleHooks: {
+    beforeRequest({ c }) {
+      const session = readSession(c.req.header('authorization'));
+      if (!session) return c.json({ error: 'Unauthorized' }, 401);
+      c.set('session', session);
+    },
+    beforeWrite({ c, body }) {
+      if (c.get('session')?.role !== 'admin') {
+        return c.json({ error: 'Forbidden' }, 403);
+      }
+      if (body) body.updatedAt = new Date().toISOString();
+    },
+  },
+  hooks: {
+    beforeCreate({ body }) {
+      body.createdAt ??= body.updatedAt;
+    },
+  },
+});
+```
+
+Resource hook order is deterministic:
+
+1. `beforeRequest`
+2. `beforeWrite` for `create`, `patch`, `put`, or `delete`
+3. matching global method hook
+4. matching resource method hook
+5. @async/db operation
+
+Any hook can return a Hono response to short-circuit the request. Write hooks can mutate `body` before @async/db validates and writes it.
+Registered operation routes run `lifecycleHooks.beforeRequest` before operation
+execution with `method: 'operation'` and the operation `ref`. They do not run
+resource write or resource method hooks.
+When tracing is enabled, hook phases and short-circuit responses are included in
+the request trace event without recording request or response bodies.
+
+Registered operations mount at `POST {prefix}/operations/:ref` when
+`db.config.operations.enabled` is true. Set `operations: false` for a REST-only
+mount, `operations: true` to explicitly use global config, or pass a local
+registry/resolver when a Hono app owns a custom build step:
+
+```ts
+registerDbRoutes(app, db, {
+  prefix: '/api/db',
+  operations: {
+    registry: generatedOperations.operations,
+    acceptRefs: 'ref',
+  },
+});
+```
+
+See [examples/hono-auth](../examples/hono-auth/README.md) for a runnable Hono app with bearer-token auth.
+
+For guidance on moving local `/db/*` prototype routes to `/api/db/*` or
+`/api/*` production namespaces, registered operation refs, and locked-down
+route exposure, see the
+[Prototype To Production REST Guide](./prototype-to-production.md).
+
+## Hono And SQLite Starter Generation
+
+When fixtures and schemas have settled enough to graduate toward a real database API, generate a Hono starter:
+
+```bash
+async-db generate hono
+async-db generate hono --api rest,graphql --out ./server
+async-db generate hono --api none --app module
+```
+
+The default output is `./db-api` with REST routes, a portable repository interface, a `node:sqlite` adapter, validators, and an initial SQL migration.
+
+Generated standalone apps are TypeScript-first and target Node.js `>=22.13` because SQLite output uses `node:sqlite`.
+
+The main package stays dependency-light. Generated apps declare their own `hono`, `@hono/node-server`, `typescript`, and `tsx` dependencies.
+
+Generation fails on schema errors and, by default, on schema warnings so production starter code only uses declared schema fields. Pass `--allow-warnings` only when you intentionally want to generate with warning diagnostics.
+
+## Optional Runtime Hono/SQLite
+
+Apps can also use optional runtime exports directly:
+
+```ts
+import { Hono } from 'hono';
+import { createDbHonoApp } from '@async/db/hono';
+
+const app = new Hono();
+app.route('/api', await createDbHonoApp({
+  dbDir: './db',
+  storage: {
+    kind: 'sqlite',
+    file: './data/app.sqlite',
+  },
+  api: ['rest'],
+}));
+```
+
+These integrations are opt-in. They should not make `hono`, `@hono/node-server`, or SQLite libraries mandatory dependencies of the core package.

package/docs/json-production.md

@@ -0,0 +1,120 @@
+# Production JSON Database
+
+`@async/db/json` is the first-party file database surface for @async/db. It is for resources that should stay simple, reviewable, and file-backed while the app talks to the same @async/db API layer it would use for SQLite, Postgres, or a custom store.
+
+The product split is:
+
+- `@async/db` owns the app-facing data layer: schemas, generated types, clients, REST/GraphQL metadata, registered operations, and store switching.
+- `@async/db/json` owns the simple JSON file database surface: JSON store capability metadata and safe JSON state-file helpers.
+
+JSON controls the app. Databases record the app.
+
+## Good Production Fits
+
+Use the JSON store for small low-write resources that are naturally files:
+
+- app settings
+- feature flags and rollout rules
+- navigation, labels, and UI configuration
+- CMS/content records, docs metadata, and templates
+- prompt templates and model/provider defaults
+- plan, pricing, and entitlement definitions
+- policy rules and permission maps
+- seed data, demo data, fixtures, mocks, and test baselines
+
+These are control-plane resources. They are valuable in production when they stay easy to review, snapshot, diff, and promote between environments.
+
+See [examples/production-json](../examples/production-json/README.md) for a runnable feature flags and app settings example that keeps JSON as the store while browser traffic uses registered operation refs.
+
+## Hard Limits
+
+Do not use the JSON store as the primary production store for:
+
+- chat messages, activity feeds, analytics events, or logs
+- payments, ledgers, balances, inventory counters, or booking availability
+- high-write user data or large searchable datasets
+- data written by multiple app instances at the same time
+- multi-region writes or cross-process transactional workflows
+- compliance-heavy records that require database-level audit, retention, or access controls
+
+The default JSON store writes complete resource files under `.db/state`. Writes are atomic at the file/resource level and queued in-process, but that is not the same as a database transaction, cross-process lock, query planner, or replicated storage system.
+
+Treat 1,000 collection records as a review point. `async-db doctor` already warns when a JSON-backed collection has more than 1,000 seed records without index metadata. For fast-changing or query-heavy collections, graduate the resource before users depend on it.
+
+If a JSON state file is corrupt or only partially recoverable, `@async/db/json` reports `JSON_STATE_INVALID` with the file path and parser message. Restore that file from a known-good snapshot, delete it only when rehydrating from seed data is safe, or fix the JSON syntax before restarting the app.
+
+## Production API Boundary
+
+Do not expose local `async-db serve` as an unauthenticated public database API.
+
+For production-facing traffic:
+
+1. Move app routes to `/api/db/*` or `/api/*`.
+2. Register stable operations for browser-facing reads and writes.
+3. Generate client-safe operation refs.
+4. Use `server.expose.rest: 'registered-only'` when raw REST should be blocked.
+5. Add app-owned auth, authorization, rate limits, and monitoring around the mounted API.
+
+The browser should call the data contract, not the JSON files. With the built-in operation system, that means calling generated operation refs:
+
+```ts
+const flags = await db.query(operationRefs.operations.ListFeatureFlags.ref);
+```
+
+The operation template can read JSON today and later point at a SQLite, Postgres, Redis, or custom-backed resource while the client call stays the same. App-owned servers can also wrap the operation route with auth, rate limits, policy checks, and flag evaluation before returning a client-safe result.
+
+## Public JSON Helpers
+
+Use `@async/db/json` when app or tooling code needs to inspect the built-in JSON database surface directly:
+
+```ts
+import {
+  jsonStoreCapabilities,
+  jsonStatePathForResource,
+  readJsonState,
+  writeJsonState,
+} from '@async/db/json';
+
+if (jsonStoreCapabilities.production === 'small-local') {
+  const file = jsonStatePathForResource({ stateDir: './.db' }, 'settings');
+  const settings = await readJsonState(file, {});
+  await writeJsonState(file, settings);
+}
+```
+
+Most app code should still use `openDb()`, `createDbClient()`, and registered operations. The JSON helpers are for tooling, diagnostics, migrations, exports, and advanced local workflows.
+
+## Mixed Stores
+
+Keep JSON for control-plane resources and graduate data-plane resources independently:
+
+```js
+export default {
+  stores: {
+    default: 'json',
+    appDb: postgresStore({ client }),
+  },
+  resources: {
+    featureFlags: { store: 'json' },
+    settings: { store: 'json' },
+    activityEvents: { store: 'appDb' },
+    orders: { store: 'appDb' },
+  },
+};
+```
+
+The app-facing contract stays in @async/db. Frontend code calls the same generated types, REST resources, or registered operation refs while each resource chooses the storage boundary that fits its write rate and operational risk.
+
+For the full resource-by-resource migration path, see [Resource Graduation And Mixed Stores](./store-graduation.md).
+
+## Readiness Checklist
+
+- Run `async-db doctor --production` before treating JSON-backed resources as production data. Use `async-db check --strict --production` when warnings should fail CI.
+- Use explicit schemas for production JSON resources.
+- Prefer `schema.unknownFields: 'error'` when drift should fail.
+- Keep JSON-backed writes low-volume and single-writer.
+- Snapshot or back up `.db/state` before deployments and migrations.
+- Practice recovery for `JSON_STATE_INVALID` by restoring a known-good state snapshot.
+- Keep browser traffic behind registered operations when exposing production APIs.
+- Return evaluated feature flags or policy decisions to the browser, not sensitive rule internals.
+- Move a resource to SQLite, Postgres, or a custom store when write rate, size, query needs, or concurrency exceed file-backed JSON limits.