@async/db 0.2.0

package/examples/computed-fields/README.md

@@ -0,0 +1,93 @@
+# Computed Fields Example
+
+## What This Teaches
+
+Use this when you want to see several ways to model computed fields with `.schema.mjs`. Computed fields are read-only projections: stored fixture records stay small, and REST or GraphQL resolves the computed value only when a client selects it.
+
+## Files To Inspect
+
+- [db/users.schema.mjs](./db/users.schema.mjs): `field.computed(type, function)` shorthand using `this.value`.
+- [db/posts.schema.mjs](./db/posts.schema.mjs): object form with `resolveMany` for reading time.
+- [db/products.schema.mjs](./db/products.schema.mjs): arrow resolver for simple price formatting.
+- [db/orders.schema.mjs](./db/orders.schema.mjs): normal function resolver that uses `this.get('db')` to read product prices.
+- [src/generated/db.types.d.ts](./src/generated/db.types.d.ts): committed generated types where computed fields are optional read-only projections.
+
+## Run It
+
+From the repository root:
+
+```bash
+npm run db -- sync --cwd ./examples/computed-fields
+npm run db -- serve --cwd ./examples/computed-fields
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+## REST Requests To Try
+
+Default reads return stored fields only:
+
+```bash
+curl http://127.0.0.1:7331/db/orders.json
+```
+
+Select computed fields when you need them:
+
+```bash
+curl 'http://127.0.0.1:7331/db/users.json?select=id,fullName'
+curl 'http://127.0.0.1:7331/db/posts.json?select=id,title,readingTimeMinutes'
+curl 'http://127.0.0.1:7331/db/products.json?select=id,name,priceLabel'
+curl 'http://127.0.0.1:7331/db/orders.json?select=id,itemCount,totalCents,receiptLine'
+```
+
+## GraphQL Query To Try
+
+```graphql
+{
+  users {
+    id
+    fullName
+  }
+  products {
+    id
+    priceLabel
+  }
+  orders {
+    id
+    itemCount
+    totalCents
+    receiptLine
+  }
+}
+```
+
+## Why This Shape?
+
+Each model shows a different computed-field use case:
+
+- `users.fullName` combines stored fields from `this.value` for display.
+- `posts.readingTimeMinutes` uses `resolveMany` so a collection page can be computed in one batch.
+- `products.priceLabel` formats raw `priceCents` without changing the stored number.
+- `orders.totalCents` and `orders.receiptLine` use normal resolver functions so the delegated resolver context can read related product prices with `this.get('db')`.
+
+Normal function resolvers can read internal runtime values such as `db`, `value`,
+`record`, `fieldName`, and `services` with `this.get(name)`. App code can pass a
+context object to `schema.resolver(...)` to override or add values; `this._internal`
+keeps the original internal view available when a resolver needs it.
+
+Computed fields are useful for values that are cheap to derive, read-only, and easier to keep out of source fixtures. They should not replace stored data that users need to edit directly.
+
+## Features To Notice
+
+- [Computed fields](../../docs/fixtures-and-schemas.md#computed-fields)
+- [JavaScript schema sources](../../docs/fixtures-and-schemas.md#javascript-schema-sources)
+- [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.

package/examples/computed-fields/db/orders.schema.mjs

@@ -0,0 +1,62 @@
+import { collection, field } from '@async/db/schema';
+
+export default collection({
+  description: 'Orders that derive totals from nested items and related products.',
+  idField: 'id',
+  fields: {
+    id: field.string({
+      required: true,
+      description: 'Stable order id.',
+    }),
+    customerName: field.string({
+      required: true,
+      description: 'Stored customer display name.',
+    }),
+    items: field.array(field.object({
+      productId: field.string({ required: true }),
+      quantity: field.number({ required: true }),
+    }), {
+      description: 'Stored line items.',
+    }),
+    itemCount: field.computed(field.number({
+      description: 'Total quantity across line items.',
+    }), ({ record }) => itemCount(record)),
+    totalCents: field.computed(field.number({
+      description: 'Order total calculated from current product prices.',
+    }), async function orders_totalCents_resolver({ record }) {
+      return orderTotalCents(this.get('db'), record);
+    }),
+    receiptLine: field.computed(field.string({
+      description: 'Human-readable receipt summary.',
+    }), async function orders_receiptLine_resolver({ record }) {
+      const total = await orderTotalCents(this.get('db'), record);
+      return `${record.customerName} - ${itemCount(record)} items - ${formatMoney(total)}`;
+    }),
+  },
+  seed: [
+    {
+      id: 'ord_1',
+      customerName: 'Ada Lovelace',
+      items: [
+        { productId: 'prod_sticker', quantity: 3 },
+        { productId: 'prod_mug', quantity: 2 },
+      ],
+    },
+  ],
+});
+
+function itemCount(order) {
+  return (order.items ?? []).reduce((total, item) => total + Number(item.quantity ?? 0), 0);
+}
+
+async function orderTotalCents(db, order) {
+  const products = await db.collection('products').all();
+  const prices = new Map(products.map((product) => [product.id, product.priceCents]));
+  return (order.items ?? []).reduce((total, item) => (
+    total + Number(prices.get(item.productId) ?? 0) * Number(item.quantity ?? 0)
+  ), 0);
+}
+
+function formatMoney(cents) {
+  return `$${(Number(cents ?? 0) / 100).toFixed(2)}`;
+}

package/examples/computed-fields/db/posts.schema.mjs

@@ -0,0 +1,59 @@
+import { collection, field } from '@async/db/schema';
+
+export default collection({
+  description: 'Posts with derived reading metadata.',
+  idField: 'id',
+  fields: {
+    id: field.string({
+      required: true,
+      description: 'Stable post id.',
+    }),
+    title: field.string({
+      required: true,
+      description: 'Post title.',
+    }),
+    authorId: field.string({
+      required: true,
+      description: 'Author user id.',
+      relation: {
+        name: 'author',
+        to: 'users',
+        toField: 'id',
+        cardinality: 'one',
+      },
+    }),
+    body: field.string({
+      required: true,
+      description: 'Stored markdown body.',
+    }),
+    readingTimeMinutes: field.computed(field.number({
+      description: 'One-minute minimum reading estimate derived from the body.',
+    }), {
+      resolveMany({ records }) {
+        return new Map(records.map((record) => [
+          record.id,
+          readingTimeMinutes(record.body),
+        ]));
+      },
+    }),
+  },
+  seed: [
+    {
+      id: 'post_intro',
+      title: 'Computed fields are projections',
+      authorId: 'u_1',
+      body: 'Computed fields keep stored fixture data small while adding useful values when a client selects them.',
+    },
+    {
+      id: 'post_release',
+      title: 'Batch resolver example',
+      authorId: 'u_2',
+      body: 'resolveMany can derive values for an entire selected page at once.',
+    },
+  ],
+});
+
+function readingTimeMinutes(body) {
+  const wordCount = String(body ?? '').trim().split(/\s+/u).filter(Boolean).length;
+  return Math.max(1, Math.ceil(wordCount / 200));
+}

package/examples/computed-fields/db/products.schema.mjs

@@ -0,0 +1,39 @@
+import { collection, field } from '@async/db/schema';
+
+export default collection({
+  description: 'Products that store cents and expose formatted display values.',
+  idField: 'id',
+  fields: {
+    id: field.string({
+      required: true,
+      description: 'Stable product id.',
+    }),
+    name: field.string({
+      required: true,
+      description: 'Product name.',
+    }),
+    priceCents: field.number({
+      required: true,
+      description: 'Stored integer price in cents.',
+    }),
+    priceLabel: field.computed(field.string({
+      description: 'Formatted price for UI display.',
+    }), ({ record }) => formatMoney(record.priceCents)),
+  },
+  seed: [
+    {
+      id: 'prod_sticker',
+      name: 'Async DB Sticker',
+      priceCents: 500,
+    },
+    {
+      id: 'prod_mug',
+      name: 'Local Data Mug',
+      priceCents: 2000,
+    },
+  ],
+});
+
+function formatMoney(cents) {
+  return `$${(Number(cents ?? 0) / 100).toFixed(2)}`;
+}

package/examples/computed-fields/db/users.schema.mjs

@@ -0,0 +1,43 @@
+import { collection, field } from '@async/db/schema';
+
+export default collection({
+  description: 'People used by posts and orders.',
+  idField: 'id',
+  fields: {
+    id: field.string({
+      required: true,
+      description: 'Stable user id.',
+    }),
+    firstName: field.string({
+      required: true,
+      description: 'Given name stored in the fixture.',
+    }),
+    lastName: field.string({
+      required: true,
+      description: 'Family name stored in the fixture.',
+    }),
+    role: field.enum(['admin', 'editor', 'customer'], {
+      default: 'customer',
+      description: 'Local role for examples.',
+    }),
+    fullName: field.computed(field.string({
+      description: 'Display name assembled from first and last name.',
+    }), function users_fullName_resolver() {
+      return `${this.value.firstName} ${this.value.lastName}`;
+    }),
+  },
+  seed: [
+    {
+      id: 'u_1',
+      firstName: 'Ada',
+      lastName: 'Lovelace',
+      role: 'admin',
+    },
+    {
+      id: 'u_2',
+      firstName: 'Grace',
+      lastName: 'Hopper',
+      role: 'editor',
+    },
+  ],
+});

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

@@ -0,0 +1,5 @@
+{
+  "title": "Computed Fields",
+  "description": "Several schema-backed models showing computed fields for display names, formatted prices, reading time, and cross-resource order totals.",
+  "tags": ["computed", "schema-mjs", "graphql"]
+}

package/examples/computed-fields/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 UserRole = "admin" | "editor" | "customer";
+
+/** Orders that derive totals from nested items and related products. */
+export type Order = {
+  /** Stable order id. */
+  id: string;
+  /** Stored customer display name. */
+  customerName: string;
+  /** Stored line items. */
+  items?: Array<{
+    productId: string;
+    quantity: number;
+  }>;
+  /** Total quantity across line items. */
+  itemCount?: number;
+  /** Order total calculated from current product prices. */
+  totalCents?: number;
+  /** Human-readable receipt summary. */
+  receiptLine?: string;
+};
+
+/** Posts with derived reading metadata. */
+export type Post = {
+  /** Stable post id. */
+  id: string;
+  /** Post title. */
+  title: string;
+  /** Author user id. */
+  authorId: string;
+  /** Stored markdown body. */
+  body: string;
+  /** One-minute minimum reading estimate derived from the body. */
+  readingTimeMinutes?: number;
+};
+
+/** Products that store cents and expose formatted display values. */
+export type Product = {
+  /** Stable product id. */
+  id: string;
+  /** Product name. */
+  name: string;
+  /** Stored integer price in cents. */
+  priceCents: number;
+  /** Formatted price for UI display. */
+  priceLabel?: string;
+};
+
+/** People used by posts and orders. */
+export type User = {
+  /** Stable user id. */
+  id: string;
+  /** Given name stored in the fixture. */
+  firstName: string;
+  /** Family name stored in the fixture. */
+  lastName: string;
+  /** Local role for examples. */
+  role?: UserRole;
+  /** Display name assembled from first and last name. */
+  fullName?: string;
+};
+
+export type DbCollections = {
+  orders: Order;
+  posts: Post;
+  products: Product;
+  users: User;
+};
+
+export type DbDocuments = {
+};
+
+export type DbTypes = {
+  collections: DbCollections;
+  documents: DbDocuments;
+};
+
+export type DbCollectionName = keyof DbCollections;
+export type DbDocumentName = keyof DbDocuments;

package/examples/content-collections/README.md

@@ -0,0 +1,91 @@
+# Content Collections Example
+
+## What This Teaches
+
+Use this when you want a dependency-free version of the content collection pattern: docs and blog posts live as MDX files, `index.schema.mjs` files describe the record shape, and async-db exposes the content through generated types, REST, GraphQL, and the local viewer.
+
+This example does not install `content-collections`, a frontmatter package, or an MDX compiler. Core reads simple scalar frontmatter plus the raw MDX body. The app-owned preview script shows where rendering or richer parsing belongs.
+
+## Files To Inspect
+
+- [db/docs/index.schema.mjs](./db/docs/index.schema.mjs): docs collection marker using `source: files(..., { read })`.
+- [db/blog/index.schema.mjs](./db/blog/index.schema.mjs): blog collection with file sources, relations, and computed fields.
+- [db.config.mjs](./db.config.mjs): config-owned `static` store selection for docs and blog.
+- [db/blog/launch-notes.mdx](./db/blog/launch-notes.mdx): frontmatter plus raw MDX body.
+- [db/authors.json](./db/authors.json): normal writable fixture records used by blog relations.
+- [db/site.schema.jsonc](./db/site.schema.jsonc): embedded document seed for aggregate bundle seed splitting.
+- [src/content-preview.mjs](./src/content-preview.mjs): dependency-free app-owned preview renderer.
+
+## Run It
+
+From the repository root, use the repo-internal CLI path:
+
+```bash
+npm run db -- sync --cwd ./examples/content-collections
+npm run db -- serve --cwd ./examples/content-collections
+```
+
+Open the viewer:
+
+```txt
+http://127.0.0.1:7331/__db
+```
+
+Render the local preview:
+
+```bash
+node ./examples/content-collections/src/content-preview.mjs
+```
+
+## Expected Result
+
+`sync` loads `authors`, `blog`, `docs`, and `site`. The docs and blog collections are static because `db.config.mjs` assigns those resources to the static store. The authors fixture stays writable in the runtime store.
+
+## REST And GraphQL Requests To Try
+
+Leave `serve` running and run these from another terminal:
+
+```bash
+curl http://127.0.0.1:7331/db/docs.json
+curl 'http://127.0.0.1:7331/db/blog.json?select=id,title,permalink,readingTimeMinutes'
+```
+
+GraphQL selections use the same computed fields:
+
+```graphql
+{
+  blog {
+    id
+    title
+    permalink
+    readingTimeMinutes
+  }
+}
+```
+
+## Bundle The Schemas
+
+Aggregate bundle writes a root schema registry and keeps seed data out of that root file:
+
+```bash
+npm run db -- schema bundle --all --cwd ./examples/content-collections --out db.schema.mjs
+```
+
+Because `db/site.schema.jsonc` has embedded seed and no `db/site.json`, the command first writes `db/site.json`, then writes `db.schema.mjs`. Folder collection source globs are rebased so the root file points back to `files('./db/docs/**/*.mdx', { read: 'frontmatter' })` and `files('./db/blog/**/*.mdx', { read: 'frontmatter' })`.
+
+## Why This Shape?
+
+Docs and blog posts are static content, so their source of truth is the MDX file. Authors are normal fixture data because an app may create or edit them during local development. The relation from `blog.authorId` to `authors.id` keeps the content file small while still letting REST and GraphQL expand author data.
+
+`tags` is a comma-separated scalar string on purpose. The built-in frontmatter parser is lightweight and dependency-free; if your app needs arrays, nested frontmatter, or full MDX compilation, keep that parser or compiler in app code like [src/content-preview.mjs](./src/content-preview.mjs).
+
+## Features To Notice
+
+- [Folder content collections](../../docs/fixtures-and-schemas.md#folder-content-collections)
+- [Computed fields](../../docs/fixtures-and-schemas.md#computed-fields)
+- [Bundle and unbundle](../../docs/fixtures-and-schemas.md#bundle-and-unbundle)
+- [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. If you run the aggregate bundle command in this example folder, it intentionally creates `db.schema.mjs` and `db/site.json`; remove those files when you want to return to the per-resource authoring shape.

package/examples/content-collections/db/authors.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": "author_ada",
+    "name": "Ada Lovelace",
+    "role": "Editor"
+  },
+  {
+    "id": "author_grace",
+    "name": "Grace Hopper",
+    "role": "Author"
+  }
+]

package/examples/content-collections/db/authors.schema.mjs

@@ -0,0 +1,20 @@
+import { collection, field } from '@async/db/schema';
+
+export default collection({
+  description: 'People who write or edit content records.',
+  idField: 'id',
+  fields: {
+    id: field.string({
+      required: true,
+      description: 'Stable author id used by content frontmatter.',
+    }),
+    name: field.string({
+      required: true,
+      description: 'Display name shown on bylines.',
+    }),
+    role: field.enum(['Editor', 'Author'], {
+      default: 'Author',
+      description: 'Editorial role in the local content workflow.',
+    }),
+  },
+});

package/examples/content-collections/db/blog/draft-roadmap.mdx

@@ -0,0 +1,12 @@
+---
+title: Draft Roadmap
+status: draft
+publishedAt: 2026-05-22T12:00:00.000Z
+authorId: author_grace
+tags: roadmap,draft
+summary: A draft post that still validates against the same schema.
+---
+# Draft Roadmap
+
+Draft content can live beside published content. The `status` field lets the app
+decide what to show publicly.

package/examples/content-collections/db/blog/index.schema.mjs

@@ -0,0 +1,61 @@
+import { collection, field, files } from '@async/db/schema';
+
+export default collection({
+  description: 'Blog posts loaded from frontmatter and raw MDX body files.',
+  source: files('./**/*.mdx', { read: 'frontmatter' }),
+  idField: 'id',
+  fields: {
+    id: field.string({
+      required: true,
+      description: 'Stable post id. Defaults to the filename when frontmatter omits id.',
+    }),
+    title: field.string({
+      required: true,
+      description: 'Post title from frontmatter.',
+    }),
+    status: field.enum(['draft', 'published'], {
+      default: 'draft',
+      description: 'Publication state.',
+    }),
+    publishedAt: field.datetime({
+      description: 'Publication timestamp.',
+    }),
+    authorId: field.string({
+      required: true,
+      description: 'Author id from the authors fixture.',
+      relation: {
+        name: 'author',
+        to: 'authors',
+        toField: 'id',
+        cardinality: 'one',
+      },
+    }),
+    tags: field.string({
+      description: 'Comma-separated tags kept scalar for the dependency-free frontmatter parser.',
+    }),
+    summary: field.string({
+      description: 'Short post summary.',
+    }),
+    body: field.string({
+      required: true,
+      description: 'Raw MDX body. Rendering and compilation are app-owned.',
+    }),
+    permalink: field.computed(field.string({
+      description: 'Read-only URL path derived from the post id.',
+    }), function blog_permalink_resolver({ record }) {
+      return `/blog/${record.id}`;
+    }),
+    readingTimeMinutes: field.computed(field.number({
+      description: 'Read-only one-minute minimum estimate derived from the raw body.',
+    }), {
+      resolveMany({ records }) {
+        return records.map((record) => readingTimeMinutes(record.body));
+      },
+    }),
+  },
+});
+
+function readingTimeMinutes(body) {
+  const wordCount = String(body ?? '').trim().split(/\s+/u).filter(Boolean).length;
+  return Math.max(1, Math.ceil(wordCount / 200));
+}

package/examples/content-collections/db/blog/launch-notes.mdx

@@ -0,0 +1,15 @@
+---
+title: Launch Notes
+status: published
+publishedAt: 2026-05-21T09:00:00.000Z
+authorId: author_ada
+tags: local,content,mdx
+summary: Why folder content works well for local apps.
+---
+# Launch Notes
+
+## Why local content
+
+Docs and posts often start as files, but apps still need typed records, route
+metadata, and API access. This example keeps the files readable while making the
+records available through async-db.

package/examples/content-collections/db/docs/index.schema.mjs

@@ -0,0 +1,32 @@
+import { collection, field, files } from '@async/db/schema';
+
+export default collection({
+  description: 'Documentation pages loaded from frontmatter and raw MDX body files.',
+  source: files('./**/*.mdx', { read: 'frontmatter' }),
+  idField: 'id',
+  fields: {
+    id: field.string({
+      required: true,
+      description: 'Stable document id. Defaults to the filename when frontmatter omits id.',
+    }),
+    title: field.string({
+      required: true,
+      description: 'Page title from frontmatter.',
+    }),
+    section: field.string({
+      required: true,
+      description: 'Navigation group for this page.',
+    }),
+    order: field.number({
+      default: 100,
+      description: 'Sort order inside the section.',
+    }),
+    summary: field.string({
+      description: 'Short page summary.',
+    }),
+    body: field.string({
+      required: true,
+      description: 'Raw MDX body. Rendering and compilation are app-owned.',
+    }),
+  },
+});

package/examples/content-collections/db/docs/intro.mdx

@@ -0,0 +1,11 @@
+---
+title: Intro To Local Content
+section: Guide
+order: 1
+summary: A first document loaded from a folder collection.
+---
+# Intro To Local Content
+
+This page is stored as a normal MDX file under `db/docs`.
+
+<Callout tone="info">Apps can compile or render this body with their own MDX pipeline.</Callout>

package/examples/content-collections/db/docs/schema-workflow.mdx

@@ -0,0 +1,10 @@
+---
+title: Schema Workflow
+section: Guide
+order: 2
+summary: How folder content maps into typed local records.
+---
+# Schema Workflow
+
+The `index.schema.mjs` marker describes the content contract. The matching MDX
+files provide frontmatter fields plus the raw body string.