@async/db 0.2.0

package/examples/production-json/db.config.mjs

@@ -0,0 +1,33 @@
+// @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',
+    operationRefs: './src/generated/db.operation-refs.json',
+  },
+  types: {
+    enabled: true,
+    emitComments: true,
+  },
+  schema: {
+    unknownFields: 'error',
+  },
+  operations: {
+    enabled: true,
+    acceptRefs: 'ref',
+    sourceDir: './db/operations',
+  },
+  server: {
+    expose: {
+      rest: 'registered-only',
+      graphql: false,
+      viewer: 'dev',
+      schema: 'dev',
+      manifest: 'dev',
+    },
+  },
+});

package/examples/production-json/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Production JSON",
+  "description": "Feature flags and app settings kept in the first-party JSON store while browser traffic uses registered operations.",
+  "tags": ["json", "production", "operations"]
+}

package/examples/production-json/src/client-demo.mjs

@@ -0,0 +1,28 @@
+import { readFile } from 'node:fs/promises';
+import { createDbClient } from '@async/db/client';
+
+const baseUrl = process.env.ASYNC_DB_URL ?? 'http://127.0.0.1:7331';
+const refsUrl = new URL('./generated/db.operation-refs.json', import.meta.url);
+const operationRefs = await readOperationRefs(refsUrl);
+const client = createDbClient({ baseUrl });
+
+const controlPlane = await client.query(operationRefs.operations.GetControlPlane.ref);
+const billingFlag = await client.query(operationRefs.operations.GetFeatureFlag.ref, {
+  id: 'flag_billing_v2',
+});
+
+console.log(JSON.stringify({
+  controlPlane,
+  billingFlag,
+}, null, 2));
+
+async function readOperationRefs(url) {
+  try {
+    return JSON.parse(await readFile(url, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error('Run `npm run db -- operations build --cwd ./examples/production-json` before running this demo.');
+    }
+    throw error;
+  }
+}

package/examples/production-json/src/generated/db.types.d.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+// This file is generated by db. Do not edit by hand.
+
+export type AppSettingsEnvironment = "development" | "staging" | "production";
+
+export type FeatureFlagAudience =
+  | "everyone"
+  | "staff"
+  | "beta"
+  | "enterprise";
+
+/** Small production settings that are safe to keep as reviewed JSON. */
+export type AppSettings = {
+  /** Public product name shown by the app shell. */
+  appName: string;
+  /** Deployment lane this settings file belongs to. */
+  environment: AppSettingsEnvironment;
+  /** Whether the public app should show maintenance UI. */
+  maintenanceMode: boolean;
+  /** Fallback locale for unauthenticated visitors. */
+  defaultLocale: string;
+  /** Public support contact shown in product chrome. */
+  supportEmail: string;
+};
+
+/** Low-write production feature flags that control app behavior. */
+export type FeatureFlag = {
+  /** Stable flag id used by operations and review notes. */
+  id: string;
+  /** Stable application flag key. */
+  key: string;
+  /** Global default before app-owned targeting runs. */
+  enabled: boolean;
+  /** Coarse audience label consumed by the app policy layer. */
+  audience: FeatureFlagAudience;
+  /** Default rollout percentage for app-owned evaluation. */
+  rolloutPercent: number;
+  /** Human review note explaining the flag. */
+  description: string;
+  /** Team or person responsible for changing this flag. */
+  owner: string;
+  /** ISO timestamp for the last reviewed flag change. */
+  updatedAt: string;
+};
+
+export type DbCollections = {
+  featureFlags: FeatureFlag;
+};
+
+export type DbDocuments = {
+  appSettings: AppSettings;
+};
+
+export type DbTypes = {
+  collections: DbCollections;
+  documents: DbDocuments;
+};
+
+export type DbCollectionName = keyof DbCollections;
+export type DbDocumentName = keyof DbDocuments;

package/examples/relations/README.md

@@ -0,0 +1,56 @@
+# Relations Example
+
+## What This Teaches
+
+Use this when local fixtures need related records but you still want plain ids in JSON. It demonstrates to-one relation metadata, explicit REST `expand`, and nested `select`.
+
+## Files To Inspect
+
+- [db/users.schema.jsonc](./db/users.schema.jsonc): target collection.
+- [db/posts.schema.jsonc](./db/posts.schema.jsonc): `authorId` declares a relation to `users.id`.
+- [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/relations
+npm run db -- serve --cwd ./examples/relations
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+## Expected Result
+
+The viewer lists `posts` and `users`. The posts schema shows an `author` relation derived from `authorId`.
+
+## REST Request To Try
+
+Leave `serve` running and run this from another terminal:
+
+```bash
+curl 'http://127.0.0.1:7331/db/posts.json?expand=author&select=id,title,author.name'
+```
+
+Relation expansion is intentionally explicit and depth 1 in this version.
+
+## Features To Notice
+
+- [Relationship expansion](../../docs/server-and-viewer.md#relationship-expansion)
+- [Nested `select` fields](../../docs/server-and-viewer.md#rest-routes)
+- [Schema relation metadata](../../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
+
+- [Fixtures And Schemas](../../docs/fixtures-and-schemas.md)
+- [Server And Viewer](../../docs/server-and-viewer.md)

package/examples/relations/db/posts.schema.jsonc

@@ -0,0 +1,46 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable post id."
+    },
+    "title": {
+      "type": "string",
+      "required": true,
+      "description": "Post title shown in lists."
+    },
+    "authorId": {
+      "type": "string",
+      "required": true,
+      "description": "User id for the author.",
+      "relation": {
+        "name": "author",
+        "to": "users",
+        "toField": "id",
+        "cardinality": "one"
+      }
+    },
+    "status": {
+      "type": "enum",
+      "values": ["draft", "published"],
+      "default": "draft"
+    }
+  },
+  "seed": [
+    {
+      "id": "p_1",
+      "title": "Analytical engines for local demos",
+      "authorId": "u_1",
+      "status": "published"
+    },
+    {
+      "id": "p_2",
+      "title": "Orbital mechanics as fixture data",
+      "authorId": "u_2",
+      "status": "draft"
+    }
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "description": "Stable user id."
+    },
+    "name": {
+      "type": "string",
+      "required": true,
+      "description": "Display name shown beside authored content."
+    },
+    "email": {
+      "type": "string",
+      "required": true,
+      "unique": true,
+      "description": "Author email address."
+    }
+  },
+  "seed": [
+    {
+      "id": "u_1",
+      "name": "Ada Lovelace",
+      "email": "ada@example.com"
+    },
+    {
+      "id": "u_2",
+      "name": "Katherine Johnson",
+      "email": "katherine@example.com"
+    }
+  ]
+}

package/examples/relations/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/relations/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Relations",
+  "description": "Users and posts with to-one relation metadata, REST expand, and nested select examples.",
+  "tags": ["relations", "expand", "select"]
+}

package/examples/rest-client/README.md

@@ -0,0 +1,54 @@
+# REST Client Example
+
+## What This Teaches
+
+Use this when you want to call db from app or test code instead of typing `curl` commands. It demonstrates `createDbClient()`, direct REST calls, and a REST batch request.
+
+## Files To Inspect
+
+- [db/users.schema.jsonc](./db/users.schema.jsonc): schema-backed collection with defaults and unique email validation.
+- [db/settings.json](./db/settings.json): singleton document inferred from data.
+- [src/client-demo.mjs](./src/client-demo.mjs): tiny consumer script using `@async/db/client`.
+
+## Run It
+
+From the repository root, use the repo-internal CLI path:
+
+```bash
+npm run db -- sync --cwd ./examples/rest-client
+npm run db -- serve --cwd ./examples/rest-client
+```
+
+In another terminal:
+
+```bash
+ASYNC_DB_URL=http://127.0.0.1:7331 node ./examples/rest-client/src/client-demo.mjs
+```
+
+## Expected Result
+
+`sync` writes generated schema, types, and runtime state under `examples/rest-client/.db/`. The demo script prints users from `/db/users.json`, settings from `/db/settings.json`, and a two-item batch result.
+
+## 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
+
+- [HTTP client operations](../../docs/package-api.md#http-client)
+- [Fixture-like `.json` REST routes](../../docs/server-and-viewer.md#fixture-like-json-routes)
+- [REST batching](../../docs/server-and-viewer.md#rest-batching)
+- [Schema-backed fixtures](../../docs/fixtures-and-schemas.md#schema-files)
+
+## Cleanup
+
+Generated `.db/` output is ignored by git and can be removed whenever you want a fresh mirror.
+
+## More Docs
+
+- [Package API](../../docs/package-api.md)
+- [Server And Viewer](../../docs/server-and-viewer.md)

package/examples/rest-client/db/settings.json

@@ -0,0 +1,5 @@
+{
+  "theme": "system",
+  "itemsPerPage": 20,
+  "showBetaFeatures": true
+}

package/examples/rest-client/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_1",
+      "name": "Ada Lovelace",
+      "email": "ada@example.com",
+      "role": "admin"
+    },
+    {
+      "id": "u_2",
+      "name": "Grace Hopper",
+      "email": "grace@example.com",
+      "role": "user"
+    }
+  ]
+}

package/examples/rest-client/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/rest-client/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "REST Client",
+  "description": "A tiny consumer script that calls the local REST API with createDbClient, including direct and batched requests.",
+  "tags": ["client", "rest", "batching"]
+}

package/examples/rest-client/src/client-demo.mjs

@@ -0,0 +1,24 @@
+import { createDbClient } from '@async/db/client';
+
+const baseUrl = process.env.ASYNC_DB_URL ?? 'http://127.0.0.1:7331';
+const db = createDbClient({
+  baseUrl,
+  batching: true,
+});
+
+const users = await db.rest.get('/db/users.json', { batch: false });
+const settings = await db.rest.get('/db/settings.json', { batch: false });
+const batch = await db.rest.batch([
+  { method: 'GET', path: '/db/users.json?select=id,name' },
+  { method: 'GET', path: '/db/settings.json' },
+]);
+
+console.log(JSON.stringify({
+  baseUrl,
+  users: users.body,
+  settings: settings.body,
+  batch: batch.map((item) => ({
+    status: item.status,
+    body: item.body,
+  })),
+}, null, 2));

package/examples/schema-first/README.md

@@ -0,0 +1,55 @@
+# Schema-First Example
+
+## What This Teaches
+
+Use this when you know the local contract before you have real records. It defines resources with `.schema.jsonc`, including a type-only collection with no seed records.
+
+## Files To Inspect
+
+- [db/users.schema.jsonc](./db/users.schema.jsonc): collection with seed data.
+- [db/settings.schema.jsonc](./db/settings.schema.jsonc): singleton document schema.
+- [db/auditEvents.schema.jsonc](./db/auditEvents.schema.jsonc): schema-only collection with an empty runtime state.
+- [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/schema-first
+npm run db -- serve --cwd ./examples/schema-first
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+## Expected Result
+
+`sync` initializes empty runtime state for schema-only resources 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/audit-events.json
+```
+
+## Features To Notice
+
+- [Schema-first resources](../../docs/concepts.md#schema-first)
+- [Schema files](../../docs/fixtures-and-schemas.md#schema-files)
+- [Generated types](../../docs/generated-files.md#generated-types)
+- [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/schema-first/db/auditEvents.schema.jsonc

@@ -0,0 +1,24 @@
+{
+  // Audit events generated during local development.
+  "kind": "collection",
+  "idField": "id",
+  "fields": {
+    "id": {
+      "type": "string",
+      "required": true
+    },
+    "type": {
+      "type": "string",
+      "required": true
+    },
+    "createdAt": {
+      "type": "string",
+      "required": true
+    },
+    "payload": {
+      "type": "object",
+      "default": {}
+    }
+  },
+  "seed": []
+}

package/examples/schema-first/db/settings.schema.jsonc

@@ -0,0 +1,29 @@
+{
+  "kind": "document",
+  "fields": {
+    "theme": {
+      "type": "string",
+      "default": "light"
+    },
+    "locale": {
+      "type": "string",
+      "default": "en-US"
+    },
+    "features": {
+      "type": "object",
+      "fields": {
+        "billing": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    }
+  },
+  "seed": {
+    "theme": "light",
+    "locale": "en-US",
+    "features": {
+      "billing": false
+    }
+  }
+}

package/examples/schema-first/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/schema-first/db.config.mjs

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

package/examples/schema-first/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Schema First",
+  "description": "Schema-only resources, empty seed records, generated types, and contract-first local APIs.",
+  "tags": ["schema-first", "types", "empty-seed"]
+}

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

@@ -0,0 +1,47 @@
+/* eslint-disable */
+// This file is generated by db. Do not edit by hand.
+
+export type UserRole = "admin" | "user";
+
+export type AuditEvent = {
+  id: string;
+  type: string;
+  createdAt: string;
+  payload?: Record<string, unknown>;
+};
+
+export type Settings = {
+  theme?: string;
+  locale?: string;
+  features?: {
+    billing?: boolean;
+  };
+};
+
+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 = {
+  auditEvents: AuditEvent;
+  users: User;
+};
+
+export type DbDocuments = {
+  settings: Settings;
+};
+
+export type DbTypes = {
+  collections: DbCollections;
+  documents: DbDocuments;
+};
+
+export type DbCollectionName = keyof DbCollections;
+export type DbDocumentName = keyof DbDocuments;