schematic-pg 0.1.5 → 0.1.7

package/README.md

@@ -201,11 +201,12 @@ npx schematic-pg init my-app
 cd my-app
 ```
 
-Edit `app.schema`, then generate code and start the API:
+Edit `app.schema`, then start the full dev loop:
 
 ```bash
 make dev
-# → starts PostgreSQL, generates code, bootstraps the DB, and runs the dev server
+# → starts PostgreSQL, generates code, bootstraps the DB, runs the dev server,
+#   and watches app.schema for changes (regenerate + bootstrap + restart)
 # → http://localhost:3000
 ```
 
@@ -213,17 +214,22 @@ Or run each step individually:
 
 ```bash
 # Start PostgreSQL (PostGIS-enabled, matches .env defaults)
-docker compose up -d
+docker compose up -d --wait
 
-# Generate schema.sql + generated/ (db client, routes, policies, Zod schemas)
-npx schematic-pg generate
-
-# Apply DDL to the database and snapshot schema state
-npx schematic-pg db:bootstrap
-
-# Regenerate client + API and start the server
+# Generate, bootstrap, start server, and watch app.schema (default)
 npx schematic-pg dev
 # → http://localhost:3000
+
+# One-shot dev server without schema watching:
+npx schematic-pg dev --no-watch
+```
+
+Manual split when you need finer control:
+
+```bash
+npx schematic-pg generate
+npx schematic-pg db:bootstrap
+npx schematic-pg dev --no-watch
 ```
 
 The `init` command creates everything you need to get running:
@@ -233,7 +239,7 @@ The `init` command creates everything you need to get running:
 | `app.schema` | Starter schema (one `User` model) — edit this |
 | `.env` | `DATABASE_URL`, JWT settings |
 | `docker-compose.yml` | Local PostGIS PostgreSQL on `:5432` |
-| `Makefile` | `make dev` — docker compose + generate + db:bootstrap + dev |
+| `Makefile` | `make dev` — docker compose (with health wait) + `schematic-pg dev` |
 | `tsconfig.json` | TypeScript config for `generated/` and `src/routes/` |
 | `package.json` | `schematic-pg` + runtime deps (`hono`, `pg`, `zod`, …) |
 | `src/routes/health.ts` | Example custom route mounted at `/health` |
@@ -261,7 +267,7 @@ Generated code imports the runtime from the `schematic-pg` package (`schematic-p
 | `JWT_ROLE_CLAIM` | `role` | JWT claim mapped to `auth.role` |
 | `JWT_USER_ID_CLAIM` | `sub` | JWT claim mapped to `auth.user.id` |
 
-Set these in `.env` before running `db:bootstrap` or `dev`.
+Set these in `.env` before running `dev` or `db:bootstrap`.
 
 ---
 
@@ -289,13 +295,22 @@ Run `generate:client` before `generate:api` when using the split commands — ro
 ### Development server
 
 ```bash
-schematic-pg dev [schema]   # generate:client + generate:api, then start generated/app.ts
+schematic-pg dev [schema] [--no-watch]
 ```
 
+`dev` runs the full local loop:
+
+1. `generate` — writes `schema.sql` and `generated/*`
+2. `db:bootstrap` — waits for Postgres, applies DDL, snapshots schema state
+3. Starts `generated/app.ts`
+4. Watches `app.schema` (default) — on change, re-runs generate, bootstrap, and server restart
+
+Pass `--no-watch` for a one-shot run without file watching.
+
 Equivalent npm scripts in a project created by `init`:
 
 ```bash
-make dev           # docker compose up -d + generate + db:bootstrap + dev
+make dev           # docker compose up -d --wait + schematic-pg dev
 npm run dev        # schematic-pg dev
 npm run generate   # schematic-pg generate
 ```
@@ -755,8 +770,8 @@ Every router exposes the same CRUD shape. Models with `@policy` attributes enfor
 
 | Method | Path | Handler | Validation |
 |--------|------|---------|------------|
-| `GET` | `/` | `findMany({ where: mergeWhere(queryWhere, policyWhere), orderBy, take, skip })` | Query params |
-| `GET` | `/{pk}` | `findUnique(mergeWhere(pk, policyWhere))` | Path params |
+| `GET` | `/` | `findMany({ where: mergeWhere(queryWhere, policyWhere), orderBy, take, skip, include })` | Query params |
+| `GET` | `/{pk}` | `findUnique(mergeWhere(pk, policyWhere), { include })` | Path params + query params |
 | `POST` | `/` | `create(body)` — policy check only | JSON body |
 | `PUT` | `/{pk}` | `update({ where: mergeWhere(pk, policyWhere), data })` | Path params + JSON body |
 | `DELETE` | `/{pk}` | `delete(mergeWhere(pk, policyWhere))` | Path params |
@@ -778,17 +793,43 @@ Query params use **API field names** (camelCase), not SQL column names:
 | `?limit=20` | `take: 20` (max 100) |
 | `?offset=40` | `skip: 40` |
 | `?sort=-createdAt` | `orderBy: { createdAt: 'desc' }` |
+| `?include=profile,orders` | `include: { profile: true, orders: true }` |
+| `?include=orders.products.product` | nested boolean includes |
 
 On models with `@policy`, user filters are combined with the policy row filter via `mergeWhere` (AND). A USER calling `GET /users?role=ADMIN` still only sees rows allowed by policy.
 
 ```bash
 curl "http://localhost:3000/products?category=books&limit=10"
 curl "http://localhost:3000/users?role=USER&isActive=true" -H "Authorization: Bearer $TOKEN"
+curl "http://localhost:3000/users/USER_ID?include=profile,orders" -H "Authorization: Bearer $TOKEN"
 ```
 
+### Relation includes (`GET /`, `GET /{pk}`)
+
+Load related models via the `include` query param. Paths are comma-separated; use dots for nesting:
+
+```bash
+curl "http://localhost:3000/users?include=profile,orders"
+curl "http://localhost:3000/users/USER_ID?include=orders.products.product"
+```
+
+Each segment must name a relation field on the current model (or nested target model). Unknown relations return `400`. Maximum depth and path count are capped (see `MAX_INCLUDE_DEPTH` / `MAX_INCLUDE_PATHS` in the runtime).
+
+Opt out of HTTP includes on a relation field with `@unincludeable`:
+
+```ts
+orders: Order[] @unincludeable
+```
+
+**v1 limits:**
+
+- Boolean includes only — no nested `where`, `take`, or `skip` via URL (use the DB client or a custom route for that).
+- `@policy` row filters apply to the **root** model only; included relations are not policy-filtered separately.
+- `@omit` fields are stripped recursively on nested included objects in read responses.
+
 ### Response shaping (`@omit`)
 
-Mark sensitive stored fields with `@omit` to exclude them from generated route JSON responses (`GET`, `POST`, `PUT`, `DELETE`). The ORM client still returns full entities.
+Mark sensitive stored fields with `@omit` to exclude them from generated route JSON responses. On read endpoints with `include`, omitted fields are stripped recursively on nested relation objects as well. Mutation responses (`POST`, `PUT`, `DELETE`) strip `@omit` fields on the root model only. The ORM client still returns full entities.
 
 ```ts
 passwordHash: VARCHAR(255) @omit @unfilterable @default("")

package/dist/api/utils/include-query.d.ts

@@ -0,0 +1,6 @@
+import type { IncludeInput } from '../../db/include/types.js';
+export interface IncludableRelationTree {
+    [relationName: string]: IncludableRelationTree;
+}
+export declare function validateIncludePaths(raw: string, tree: IncludableRelationTree): string | undefined;
+export declare function parseIncludeQuery(raw: string, tree: IncludableRelationTree): IncludeInput;

package/dist/api/utils/include-query.js

@@ -0,0 +1,75 @@
+import { MAX_INCLUDE_DEPTH, MAX_INCLUDE_PATHS } from '../../constants.js';
+export function validateIncludePaths(raw, tree) {
+    const segments = splitIncludePaths(raw);
+    if (segments.some((segment) => segment.length === 0)) {
+        return 'Include paths cannot contain empty relation segments';
+    }
+    if (segments.length === 0) {
+        return 'Include parameter must contain at least one relation path';
+    }
+    if (segments.length > MAX_INCLUDE_PATHS) {
+        return `Include parameter exceeds maximum of ${MAX_INCLUDE_PATHS} paths`;
+    }
+    for (const segment of segments) {
+        const parts = segment.split('.');
+        if (parts.length > MAX_INCLUDE_DEPTH) {
+            return `Include path "${segment}" exceeds maximum depth of ${MAX_INCLUDE_DEPTH}`;
+        }
+        let currentTree = tree;
+        for (const part of parts) {
+            if (!part) {
+                return 'Include paths cannot contain empty relation segments';
+            }
+            const nextTree = currentTree[part];
+            if (!nextTree) {
+                return `Unknown include relation "${part}" in path "${segment}"`;
+            }
+            currentTree = nextTree;
+        }
+    }
+    return undefined;
+}
+export function parseIncludeQuery(raw, tree) {
+    const error = validateIncludePaths(raw, tree);
+    if (error) {
+        throw new Error(error);
+    }
+    const root = {};
+    for (const segment of splitIncludePaths(raw)) {
+        mergeIncludePath(root, segment.split('.'));
+    }
+    return toIncludeInput(root);
+}
+function splitIncludePaths(raw) {
+    return raw.split(',').map((segment) => segment.trim());
+}
+function mergeIncludePath(root, parts) {
+    let current = root;
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        const isLeaf = index === parts.length - 1;
+        if (!current[part]) {
+            current[part] = {};
+        }
+        if (isLeaf) {
+            continue;
+        }
+        if (!current[part].include) {
+            current[part].include = {};
+        }
+        current = current[part].include;
+    }
+}
+function toIncludeInput(nodes) {
+    const include = {};
+    for (const [relationName, node] of Object.entries(nodes)) {
+        if (node.include && Object.keys(node.include).length > 0) {
+            include[relationName] = {
+                include: toIncludeInput(node.include),
+            };
+            continue;
+        }
+        include[relationName] = true;
+    }
+    return include;
+}

package/dist/api/utils/read-query.d.ts

@@ -0,0 +1,12 @@
+import type { FilterFieldMeta } from './list-query.js';
+import { buildListQuery } from './list-query.js';
+import type { IncludeInput } from '../../db/include/types.js';
+import type { IncludableRelationTree } from './include-query.js';
+export interface ReadQueryResult {
+    where: ReturnType<typeof buildListQuery>['where'];
+    orderBy?: ReturnType<typeof buildListQuery>['orderBy'];
+    take?: number;
+    skip?: number;
+    include?: IncludeInput;
+}
+export declare function buildReadQuery(query: Record<string, unknown>, fields: readonly FilterFieldMeta[], sortableFields: readonly string[], includableRelations: IncludableRelationTree): ReadQueryResult;

package/dist/api/utils/read-query.js

@@ -0,0 +1,10 @@
+import { buildListQuery } from './list-query.js';
+import { parseIncludeQuery } from './include-query.js';
+export function buildReadQuery(query, fields, sortableFields, includableRelations) {
+    const { where, orderBy, take, skip } = buildListQuery(query, fields, sortableFields);
+    const result = { where, orderBy, take, skip };
+    if (typeof query.include === 'string' && query.include.length > 0) {
+        result.include = parseIncludeQuery(query.include, includableRelations);
+    }
+    return result;
+}

package/dist/api/utils/response-shape.d.ts

@@ -0,0 +1,2 @@
+export declare function shapeResponse<T extends Record<string, unknown>>(row: T, modelName: string, omitByModel: Readonly<Record<string, readonly string[]>>, relationTargets: Readonly<Record<string, Readonly<Record<string, string>>>>): T;
+export declare function shapeResponseMany<T extends Record<string, unknown>>(rows: T[], modelName: string, omitByModel: Readonly<Record<string, readonly string[]>>, relationTargets: Readonly<Record<string, Readonly<Record<string, string>>>>): T[];

package/dist/api/utils/response-shape.js

@@ -0,0 +1,28 @@
+export function shapeResponse(row, modelName, omitByModel, relationTargets) {
+    const omitted = omitByModel[modelName] ?? [];
+    const relations = relationTargets[modelName] ?? {};
+    const result = { ...row };
+    for (const field of omitted) {
+        delete result[field];
+    }
+    for (const [relationName, targetModel] of Object.entries(relations)) {
+        if (!(relationName in result)) {
+            continue;
+        }
+        const value = result[relationName];
+        if (value === null || value === undefined) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            result[relationName] = value.map((entry) => shapeResponse(entry, targetModel, omitByModel, relationTargets));
+            continue;
+        }
+        if (typeof value === 'object') {
+            result[relationName] = shapeResponse(value, targetModel, omitByModel, relationTargets);
+        }
+    }
+    return result;
+}
+export function shapeResponseMany(rows, modelName, omitByModel, relationTargets) {
+    return rows.map((row) => shapeResponse(row, modelName, omitByModel, relationTargets));
+}

package/dist/api-generator/route-generator.d.ts

@@ -6,6 +6,7 @@ export declare class RouteGenerator {
     generate(): string;
     private jsonRow;
     private jsonRows;
+    private mutationJsonRow;
     private generateListRoute;
     private generateGetRoute;
     private generateCreateRoute;

package/dist/api-generator/route-generator.js

@@ -21,6 +21,7 @@ export class RouteGenerator {
         const whereFromParams = primaryKey.fields.map((field) => `${field}: params.${field}`).join(', ');
         const paramSchemaName = `${this.model.name}ParamSchema`;
         const listQuerySchemaName = `${this.model.name}ListQuerySchema`;
+        const getQuerySchemaName = `${this.model.name}GetQuerySchema`;
         const modelHasPolicies = hasPolicies(this.model);
         const constantPrefix = toModelConstantPrefix(this.model.name);
         return [
@@ -29,8 +30,10 @@ export class RouteGenerator {
             `import type { AppEnv } from '${PACKAGE_NAME}/api/types';`,
             `import { validateJson, validateParam, validateQuery } from '${PACKAGE_NAME}/api/middleware/validate';`,
             `import { notFoundResponse } from '${PACKAGE_NAME}/api/middleware/errors';`,
-            `import { buildListQuery } from '${PACKAGE_NAME}/api/utils/list-query';`,
-            `import { omitFields, omitFieldsMany } from '${PACKAGE_NAME}/api/utils/omit-fields';`,
+            `import { buildReadQuery } from '${PACKAGE_NAME}/api/utils/read-query';`,
+            `import { parseIncludeQuery } from '${PACKAGE_NAME}/api/utils/include-query';`,
+            `import { omitFields } from '${PACKAGE_NAME}/api/utils/omit-fields';`,
+            `import { shapeResponse, shapeResponseMany } from '${PACKAGE_NAME}/api/utils/response-shape';`,
             ...(modelHasPolicies
                 ? [
                     `import { assertPolicy, mergeWhere, resolvePolicyWhere } from '${PACKAGE_NAME}/api/auth/policy';`,
@@ -41,16 +44,20 @@ export class RouteGenerator {
             `  ${this.model.name}UpdateSchema,`,
             `  ${paramSchemaName},`,
             `  ${listQuerySchemaName},`,
+            `  ${getQuerySchemaName},`,
             `  ${constantPrefix}_LIST_QUERY_FIELDS,`,
+            `  ${constantPrefix}_INCLUDABLE_RELATIONS,`,
             `  ${constantPrefix}_OMIT_FIELDS,`,
             `  ${constantPrefix}_SORTABLE_FIELDS,`,
+            `  API_OMIT_FIELDS_BY_MODEL,`,
+            `  API_RELATION_TARGETS,`,
             `} from '../schemas/validation.js';`,
             '',
             'const router = new Hono<AppEnv>();',
             '',
             ...this.generateListRoute(clientKey, modelHasPolicies, listQuerySchemaName, constantPrefix),
             '',
-            ...this.generateGetRoute(clientKey, pathParams, paramSchemaName, whereFromParams, modelHasPolicies, constantPrefix),
+            ...this.generateGetRoute(clientKey, pathParams, paramSchemaName, getQuerySchemaName, whereFromParams, modelHasPolicies, constantPrefix),
             '',
             ...this.generateCreateRoute(clientKey, modelHasPolicies, constantPrefix),
             '',
@@ -62,32 +69,45 @@ export class RouteGenerator {
             '',
         ].join('\n');
     }
-    jsonRow(variableName, constantPrefix, statusCode) {
-        const payload = `omitFields(${variableName}, ${constantPrefix}_OMIT_FIELDS)`;
+    jsonRow(variableName, modelName, constantPrefix, statusCode) {
+        const payload = `shapeResponse(${variableName}, '${modelName}', API_OMIT_FIELDS_BY_MODEL, API_RELATION_TARGETS)`;
         if (statusCode === undefined) {
             return `c.json(${payload})`;
         }
         return `c.json(${payload}, ${statusCode})`;
     }
-    jsonRows(variableName, constantPrefix) {
-        return `c.json(omitFieldsMany(${variableName}, ${constantPrefix}_OMIT_FIELDS))`;
+    jsonRows(variableName, modelName) {
+        return `c.json(shapeResponseMany(${variableName}, '${modelName}', API_OMIT_FIELDS_BY_MODEL, API_RELATION_TARGETS))`;
+    }
+    mutationJsonRow(variableName, constantPrefix, statusCode) {
+        const payload = `omitFields(${variableName}, ${constantPrefix}_OMIT_FIELDS)`;
+        if (statusCode === undefined) {
+            return `c.json(${payload})`;
+        }
+        return `c.json(${payload}, ${statusCode})`;
     }
     generateListRoute(clientKey, modelHasPolicies, listQuerySchemaName, constantPrefix) {
         const listQueryBlock = [
             `  const query = c.req.valid('query');`,
-            `  const { where, orderBy, take, skip } = buildListQuery(`,
+            `  const { where, orderBy, take, skip, include } = buildReadQuery(`,
             `    query,`,
             `    ${constantPrefix}_LIST_QUERY_FIELDS,`,
             `    ${constantPrefix}_SORTABLE_FIELDS,`,
+            `    ${constantPrefix}_INCLUDABLE_RELATIONS,`,
             `  );`,
         ];
+        const findManyArgs = ['where', 'orderBy', 'take', 'skip', 'include']
+            .map((key) => `    ${key},`)
+            .join('\n');
         if (!modelHasPolicies) {
             return [
                 `router.get('/', validateQuery(${listQuerySchemaName}), async (c) => {`,
                 '  const db = c.get(\'db\');',
                 ...listQueryBlock,
-                `  const rows = await db.${clientKey}.findMany({ where, orderBy, take, skip });`,
-                `  return ${this.jsonRows('rows', constantPrefix)};`,
+                `  const rows = await db.${clientKey}.findMany({`,
+                findManyArgs,
+                '  });',
+                `  return ${this.jsonRows('rows', this.model.name)};`,
                 '});',
             ];
         }
@@ -103,37 +123,46 @@ export class RouteGenerator {
             '    orderBy,',
             '    take,',
             '    skip,',
+            '    include,',
             '  });',
-            `  return ${this.jsonRows('rows', constantPrefix)};`,
+            `  return ${this.jsonRows('rows', this.model.name)};`,
             '});',
         ];
     }
-    generateGetRoute(clientKey, pathParams, paramSchemaName, whereFromParams, modelHasPolicies, constantPrefix) {
+    generateGetRoute(clientKey, pathParams, paramSchemaName, getQuerySchemaName, whereFromParams, modelHasPolicies, constantPrefix) {
+        const includeBlock = [
+            '  const query = c.req.valid(\'query\');',
+            `  const include = query.include`,
+            `    ? parseIncludeQuery(query.include, ${constantPrefix}_INCLUDABLE_RELATIONS)`,
+            '    : undefined;',
+        ];
         if (!modelHasPolicies) {
             return [
-                `router.get('/${pathParams}', validateParam(${paramSchemaName}), async (c) => {`,
+                `router.get('/${pathParams}', validateParam(${paramSchemaName}), validateQuery(${getQuerySchemaName}), async (c) => {`,
                 '  const db = c.get(\'db\');',
                 '  const params = c.req.valid(\'param\');',
-                `  const row = await db.${clientKey}.findUnique({ ${whereFromParams} });`,
+                ...includeBlock,
+                `  const row = await db.${clientKey}.findUnique({ ${whereFromParams} }, { include });`,
                 '  if (!row) {',
                 '    return notFoundResponse(c);',
                 '  }',
-                `  return ${this.jsonRow('row', constantPrefix)};`,
+                `  return ${this.jsonRow('row', this.model.name, constantPrefix)};`,
                 '});',
             ];
         }
         return [
-            `router.get('/${pathParams}', validateParam(${paramSchemaName}), async (c) => {`,
+            `router.get('/${pathParams}', validateParam(${paramSchemaName}), validateQuery(${getQuerySchemaName}), async (c) => {`,
             '  const db = c.get(\'db\');',
             '  const auth = c.get(\'auth\');',
             `  const policy = assertPolicy('${this.model.name}', auth.role, 'select');`,
             '  const policyWhere = resolvePolicyWhere(policy, auth);',
             '  const params = c.req.valid(\'param\');',
-            `  const row = await db.${clientKey}.findUnique(mergeWhere({ ${whereFromParams} }, policyWhere));`,
+            ...includeBlock,
+            `  const row = await db.${clientKey}.findUnique(mergeWhere({ ${whereFromParams} }, policyWhere), { include });`,
             '  if (!row) {',
             '    return notFoundResponse(c);',
             '  }',
-            `  return ${this.jsonRow('row', constantPrefix)};`,
+            `  return ${this.jsonRow('row', this.model.name, constantPrefix)};`,
             '});',
         ];
     }
@@ -144,7 +173,7 @@ export class RouteGenerator {
                 '  const db = c.get(\'db\');',
                 '  const body = c.req.valid(\'json\');',
                 `  const row = await db.${clientKey}.create(body);`,
-                `  return ${this.jsonRow('row', constantPrefix, 201)};`,
+                `  return ${this.mutationJsonRow('row', constantPrefix, 201)};`,
                 '});',
             ];
         }
@@ -155,7 +184,7 @@ export class RouteGenerator {
             `  assertPolicy('${this.model.name}', auth.role, 'insert');`,
             '  const body = c.req.valid(\'json\');',
             `  const row = await db.${clientKey}.create(body);`,
-            `  return ${this.jsonRow('row', constantPrefix, 201)};`,
+            `  return ${this.mutationJsonRow('row', constantPrefix, 201)};`,
             '});',
         ];
     }
@@ -167,7 +196,7 @@ export class RouteGenerator {
                 '  const params = c.req.valid(\'param\');',
                 '  const body = c.req.valid(\'json\');',
                 `  const row = await db.${clientKey}.update({ where: { ${whereFromParams} }, data: body });`,
-                `  return ${this.jsonRow('row', constantPrefix)};`,
+                `  return ${this.mutationJsonRow('row', constantPrefix)};`,
                 '});',
             ];
         }
@@ -180,7 +209,7 @@ export class RouteGenerator {
             '  const params = c.req.valid(\'param\');',
             '  const body = c.req.valid(\'json\');',
             `  const row = await db.${clientKey}.update({ where: mergeWhere({ ${whereFromParams} }, policyWhere), data: body });`,
-            `  return ${this.jsonRow('row', constantPrefix)};`,
+            `  return ${this.mutationJsonRow('row', constantPrefix)};`,
             '});',
         ];
     }
@@ -191,7 +220,7 @@ export class RouteGenerator {
                 '  const db = c.get(\'db\');',
                 '  const params = c.req.valid(\'param\');',
                 `  const row = await db.${clientKey}.delete({ ${whereFromParams} });`,
-                `  return ${this.jsonRow('row', constantPrefix)};`,
+                `  return ${this.mutationJsonRow('row', constantPrefix)};`,
                 '});',
             ];
         }
@@ -203,7 +232,7 @@ export class RouteGenerator {
             '  const policyWhere = resolvePolicyWhere(policy, auth);',
             '  const params = c.req.valid(\'param\');',
             `  const row = await db.${clientKey}.delete(mergeWhere({ ${whereFromParams} }, policyWhere));`,
-            `  return ${this.jsonRow('row', constantPrefix)};`,
+            `  return ${this.mutationJsonRow('row', constantPrefix)};`,
             '});',
         ];
     }

package/dist/api-generator/utils/api-fields.d.ts

@@ -1,8 +1,14 @@
 import type { Field, Model, Schema } from '../../schema-dsl/ast.js';
+import type { IncludableRelationTree } from '../../api/utils/include-query.js';
 export declare function isStoredScalarField(field: Field, schema: Schema): boolean;
+export declare function isRelationField(field: Field, schema: Schema): boolean;
 export declare function isUnfilterable(field: Field): boolean;
+export declare function isUnincludeable(field: Field): boolean;
 export declare function isOmitted(field: Field): boolean;
 export declare function getFilterableFields(model: Model, schema: Schema): Field[];
 export declare function getOmittedFields(model: Model, schema: Schema): Field[];
+export declare function getIncludableRelationFields(model: Model, schema: Schema): Field[];
+export declare function buildIncludableRelationTree(model: Model, schema: Schema, visited?: Set<string>): IncludableRelationTree;
+export declare function buildRelationTargets(model: Model, schema: Schema): Record<string, string>;
 export declare function getSortableFieldNames(model: Model, schema: Schema): string[];
 export declare function toModelConstantPrefix(modelName: string): string;

package/dist/api-generator/utils/api-fields.js

@@ -3,9 +3,15 @@ export function isStoredScalarField(field, schema) {
     const modelNames = getModelNames(schema);
     return !modelNames.has(field.type.name);
 }
+export function isRelationField(field, schema) {
+    return getModelNames(schema).has(field.type.name);
+}
 export function isUnfilterable(field) {
     return fieldHasAttribute(field, 'unfilterable') || fieldHasAttribute(field, 'omit');
 }
+export function isUnincludeable(field) {
+    return fieldHasAttribute(field, 'unincludeable');
+}
 export function isOmitted(field) {
     return fieldHasAttribute(field, 'omit');
 }
@@ -15,6 +21,32 @@ export function getFilterableFields(model, schema) {
 export function getOmittedFields(model, schema) {
     return getStoredFields(model, getModelNames(schema)).filter((field) => isStoredScalarField(field, schema) && isOmitted(field));
 }
+export function getIncludableRelationFields(model, schema) {
+    return model.fields.filter((field) => isRelationField(field, schema) && !isUnincludeable(field));
+}
+export function buildIncludableRelationTree(model, schema, visited = new Set()) {
+    if (visited.has(model.name)) {
+        return {};
+    }
+    const nextVisited = new Set(visited);
+    nextVisited.add(model.name);
+    const tree = {};
+    for (const field of getIncludableRelationFields(model, schema)) {
+        const targetModel = schema.models.find((candidate) => candidate.name === field.type.name);
+        if (!targetModel) {
+            continue;
+        }
+        tree[field.name] = buildIncludableRelationTree(targetModel, schema, nextVisited);
+    }
+    return tree;
+}
+export function buildRelationTargets(model, schema) {
+    const targets = {};
+    for (const field of getIncludableRelationFields(model, schema)) {
+        targets[field.name] = field.type.name;
+    }
+    return targets;
+}
 export function getSortableFieldNames(model, schema) {
     return getStoredFields(model, getModelNames(schema))
         .filter((field) => isStoredScalarField(field, schema))

package/dist/api-generator/zod-schema-generator.d.ts

@@ -3,8 +3,11 @@ export declare class ZodSchemaGenerator {
     private readonly schema;
     constructor(schema: Schema);
     generate(): string;
+    private generateGlobalMetadata;
     private generateModelSchemas;
     private generateListQuerySchemas;
+    private generateIncludeRefinement;
+    private generateReadQueryRefinement;
     private generateListQueryFieldLines;
     private generateObjectField;
     private generateParamField;

package/dist/api-generator/zod-schema-generator.js

@@ -1,5 +1,6 @@
+import { PACKAGE_NAME } from '../constants.js';
 import { fieldHasAttribute, getFieldAttribute, getModelNames, getOptionalKvPair, getPrimaryKey, getStoredFields, } from '../sql-generator/utils/ast-helpers.js';
-import { getFilterableFields, getOmittedFields, getSortableFieldNames, toModelConstantPrefix, } from './utils/api-fields.js';
+import { buildIncludableRelationTree, buildRelationTargets, getFilterableFields, getOmittedFields, getSortableFieldNames, toModelConstantPrefix, } from './utils/api-fields.js';
 import { buildFilterFieldMeta, queryParamKey, toFilterZodType, } from './utils/filter-operators.js';
 export class ZodSchemaGenerator {
     schema;
@@ -12,9 +13,26 @@ export class ZodSchemaGenerator {
         return [
             '// Auto-generated by ZodSchemaGenerator. Do not edit manually.',
             "import { z } from 'zod';",
+            `import { validateIncludePaths } from '${PACKAGE_NAME}/api/utils/include-query';`,
             `import type {\n  ${typeImports},\n} from '../db-types.js';`,
             '',
             ...modelBlocks,
+            this.generateGlobalMetadata(),
+        ].join('\n');
+    }
+    generateGlobalMetadata() {
+        const omitByModel = Object.fromEntries(this.schema.models.map((model) => [
+            model.name,
+            getOmittedFields(model, this.schema).map((field) => field.name),
+        ]));
+        const relationTargets = Object.fromEntries(this.schema.models.map((model) => [
+            model.name,
+            buildRelationTargets(model, this.schema),
+        ]));
+        return [
+            `export const API_OMIT_FIELDS_BY_MODEL = ${JSON.stringify(omitByModel, null, 2)} as const;`,
+            `export const API_RELATION_TARGETS = ${JSON.stringify(relationTargets, null, 2)} as const;`,
+            '',
         ].join('\n');
     }
     generateModelSchemas(model) {
@@ -49,39 +67,79 @@ export class ZodSchemaGenerator {
         const omittedFields = getOmittedFields(model, this.schema);
         const filterFieldMeta = filterableFields.map((field) => buildFilterFieldMeta(field, this.schema));
         const queryLines = filterableFields.flatMap((field) => this.generateListQueryFieldLines(field, filterFieldMeta.find((meta) => meta.name === field.name)));
-        queryLines.push('limit: z.coerce.number().int().min(1).max(100).optional(),', 'offset: z.coerce.number().int().min(0).optional(),', 'sort: z.string().optional(),');
+        queryLines.push('limit: z.coerce.number().int().min(1).max(100).optional(),', 'offset: z.coerce.number().int().min(0).optional(),', 'sort: z.string().optional(),', 'include: z.string().optional(),');
         const sortableLiteral = sortableFields.map((field) => `'${field}'`).join(', ');
         const listQueryFieldsJson = JSON.stringify(filterFieldMeta, null, 2);
         const omitFieldNames = omittedFields.map((field) => field.name);
         const omitFieldsJson = JSON.stringify(omitFieldNames);
+        const includableRelationsJson = JSON.stringify(buildIncludableRelationTree(model, this.schema), null, 2);
         const responseType = omittedFields.length === 0
             ? `export type ${model.name}Response = ${model.name};`
             : `export type ${model.name}Response = Omit<${model.name}, ${omitFieldNames.map((name) => `'${name}'`).join(' | ')}>;`;
         return [
             `export const ${prefix}_SORTABLE_FIELDS = [${sortableLiteral}] as const;`,
             `export const ${prefix}_LIST_QUERY_FIELDS = ${listQueryFieldsJson} as const;`,
+            `export const ${prefix}_INCLUDABLE_RELATIONS = ${includableRelationsJson} as const;`,
             `export const ${prefix}_OMIT_FIELDS = ${omitFieldsJson} as const;`,
             responseType + '\n',
+            `export const ${model.name}GetQuerySchema = z`,
+            '  .object({',
+            '    include: z.string().optional(),',
+            '  })',
+            ...this.generateIncludeRefinement(prefix),
+            '\n',
             `export const ${model.name}ListQuerySchema = z`,
             '  .object({',
             ...queryLines.map((line) => `    ${line}`),
             '  })',
+            ...this.generateReadQueryRefinement(prefix),
+            '\n',
+        ];
+    }
+    generateIncludeRefinement(prefix) {
+        return [
             '  .superRefine((data, ctx) => {',
-            '    if (data.sort === undefined) {',
+            '    if (data.include === undefined) {',
             '      return;',
             '    }',
-            '    const descending = data.sort.startsWith(\'-\');',
-            '    const field = descending ? data.sort.slice(1) : data.sort;',
-            `    if (!(${prefix}_SORTABLE_FIELDS as readonly string[]).includes(field)) {`,
+            `    const includeError = validateIncludePaths(data.include, ${prefix}_INCLUDABLE_RELATIONS);`,
+            '    if (includeError) {',
             '      ctx.addIssue({',
             '        code: \'custom\',',
-            '        message: `Invalid sort field "${field}"`,',
-            '        path: [\'sort\'],',
+            '        message: includeError,',
+            '        path: [\'include\'],',
             '      });',
             '    }',
             '  });\n',
         ];
     }
+    generateReadQueryRefinement(prefix) {
+        return [
+            '  .superRefine((data, ctx) => {',
+            '    if (data.sort !== undefined) {',
+            '      const descending = data.sort.startsWith(\'-\');',
+            '      const field = descending ? data.sort.slice(1) : data.sort;',
+            `      if (!(${prefix}_SORTABLE_FIELDS as readonly string[]).includes(field)) {`,
+            '        ctx.addIssue({',
+            '          code: \'custom\',',
+            '          message: `Invalid sort field "${field}"`,',
+            '          path: [\'sort\'],',
+            '        });',
+            '      }',
+            '    }',
+            '    if (data.include !== undefined) {',
+            `      const includeError = validateIncludePaths(data.include, ${prefix}_INCLUDABLE_RELATIONS);`,
+            '      if (includeError) {',
+            '        ctx.addIssue({',
+            '          code: \'custom\',',
+            '          message: includeError,',
+            '          path: [\'include\'],',
+            '        });',
+            '      }',
+            '    }',
+            '  });\n',
+        ];
+    }
     generateListQueryFieldLines(field, meta) {
         const lines = [];
         for (const operator of meta.operators) {

package/dist/cli/db.js

@@ -5,6 +5,7 @@ import { applyPendingMigrations } from '../db/migrate.js';
 import { createMigration, getAppliedMigrationFilenames, listMigrationFiles } from '../db/migrations.js';
 import { snapshotExists } from '../db/schema-state.js';
 import { resolveSchemaPath } from './paths.js';
+import { waitForDatabase } from './wait-for-database.js';
 function parseDiffArgs(args) {
     let schemaPath = resolveSchemaPath();
     let name;
@@ -50,6 +51,7 @@ export async function runDbBootstrap(schemaPath) {
     const resolvedSchemaPath = resolveSchemaPath(schemaPath);
     const client = new DatabaseClient();
     try {
+        await waitForDatabase({ client });
         await bootstrapDatabase(resolvedSchemaPath, client);
         process.stdout.write(`Database bootstrapped from ${resolvedSchemaPath}\n`);
     }

package/dist/cli/dev.d.ts

@@ -1 +1 @@
-export declare function runDev(schemaPath?: string): Promise<void>;
+export declare function runDev(args?: string[]): Promise<void>;

package/dist/cli/dev.js

@@ -1,10 +1,150 @@
-import { execFileSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import { watch } from 'node:fs';
 import path from 'node:path';
-import { generateApi, generateClient } from './generate.js';
-import { DEFAULT_OUTPUT_DIR } from './paths.js';
-export async function runDev(schemaPath) {
-    await generateClient(schemaPath);
-    await generateApi(schemaPath);
+import { runDbBootstrap } from './db.js';
+import { generateAll } from './generate.js';
+import { DEFAULT_OUTPUT_DIR, resolveSchemaPath } from './paths.js';
+const WATCH_DEBOUNCE_MS = 300;
+const SERVER_STOP_TIMEOUT_MS = 5000;
+function parseDevArgs(args) {
+    let schemaPath = resolveSchemaPath();
+    let watchSchema = true;
+    for (const arg of args) {
+        if (arg === '--no-watch') {
+            watchSchema = false;
+            continue;
+        }
+        if (!arg.startsWith('--')) {
+            schemaPath = resolveSchemaPath(arg);
+        }
+    }
+    return { schemaPath, watchSchema };
+}
+function createDebouncer(fn, ms) {
+    let timer;
+    return () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            void fn();
+        }, ms);
+    };
+}
+function startServer(appPath) {
+    return spawn(process.execPath, ['--import', 'tsx', appPath], {
+        stdio: 'inherit',
+        cwd: process.cwd(),
+    });
+}
+function stopServer(serverProcess) {
+    if (!serverProcess || serverProcess.exitCode !== null || serverProcess.killed) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        serverProcess.once('exit', () => resolve());
+        if (process.platform === 'win32') {
+            serverProcess.kill();
+        }
+        else {
+            serverProcess.kill('SIGTERM');
+        }
+        setTimeout(() => {
+            if (serverProcess.exitCode === null && !serverProcess.killed) {
+                serverProcess.kill('SIGKILL');
+            }
+        }, SERVER_STOP_TIMEOUT_MS);
+    });
+}
+function waitForServerExit(serverProcess) {
+    return new Promise((resolve) => {
+        serverProcess.once('exit', () => resolve());
+    });
+}
+export async function runDev(args = []) {
+    const { schemaPath, watchSchema } = parseDevArgs(args);
     const appPath = path.resolve(DEFAULT_OUTPUT_DIR, 'app.ts');
-    execFileSync(process.execPath, ['--import', 'tsx', appPath], { stdio: 'inherit', cwd: process.cwd() });
+    let serverProcess = null;
+    let syncInProgress = false;
+    let restarting = false;
+    let shuttingDown = false;
+    async function syncAndServe() {
+        if (syncInProgress) {
+            return;
+        }
+        syncInProgress = true;
+        try {
+            await generateAll(schemaPath);
+            await runDbBootstrap(schemaPath);
+            await stopServer(serverProcess);
+            serverProcess = startServer(appPath);
+            serverProcess.on('exit', (code, signal) => {
+                if (restarting || shuttingDown) {
+                    return;
+                }
+                if (!watchSchema) {
+                    if (code !== 0 && code !== null) {
+                        process.exitCode = code;
+                    }
+                    return;
+                }
+                if (code !== 0 && code !== null) {
+                    process.stderr.write(`Dev server exited with code ${code}\n`);
+                    process.exitCode = code;
+                    shuttingDown = true;
+                }
+                else if (signal) {
+                    process.stderr.write(`Dev server terminated by signal ${signal}\n`);
+                }
+            });
+        }
+        finally {
+            syncInProgress = false;
+        }
+    }
+    async function reload() {
+        if (shuttingDown || syncInProgress) {
+            return;
+        }
+        process.stderr.write('\nSchema changed — regenerating, bootstrapping, and restarting...\n');
+        restarting = true;
+        try {
+            await syncAndServe();
+        }
+        finally {
+            restarting = false;
+        }
+    }
+    const scheduleReload = createDebouncer(reload, WATCH_DEBOUNCE_MS);
+    async function shutdown() {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        await stopServer(serverProcess);
+    }
+    process.once('SIGINT', () => {
+        void shutdown().finally(() => {
+            process.exit(process.exitCode ?? 0);
+        });
+    });
+    process.once('SIGTERM', () => {
+        void shutdown().finally(() => {
+            process.exit(process.exitCode ?? 0);
+        });
+    });
+    await syncAndServe();
+    if (!watchSchema) {
+        if (serverProcess) {
+            await waitForServerExit(serverProcess);
+        }
+        return;
+    }
+    watch(schemaPath, scheduleReload);
+    await new Promise((resolve) => {
+        const interval = setInterval(() => {
+            if (shuttingDown) {
+                clearInterval(interval);
+                resolve();
+            }
+        }, 100);
+    });
 }

package/dist/cli/init.js

@@ -105,8 +105,11 @@ export async function runInit(args) {
     console.log('  make dev');
     console.log('');
     console.log('  # or run individually:');
-    console.log('  docker compose up -d');
+    console.log('  docker compose up -d --wait');
+    console.log(`  npx ${PACKAGE_NAME} dev   # generate + bootstrap + server + schema watch`);
+    console.log('');
+    console.log('  # split steps (dev already includes generate, bootstrap, and watch):');
     console.log(`  npx ${PACKAGE_NAME} generate`);
     console.log(`  npx ${PACKAGE_NAME} db:bootstrap`);
-    console.log(`  npx ${PACKAGE_NAME} dev`);
+    console.log(`  npx ${PACKAGE_NAME} dev --no-watch`);
 }

package/dist/cli/templates.d.ts

@@ -1,8 +1,8 @@
 export declare const APP_SCHEMA_TEMPLATE = "extensions {\n\n}\n\nenums {\n\n}\n\nmodels {\n  model User {\n    id:        UUID        @id @default(gen_random_uuid())\n    email:     VARCHAR(255) @unique\n    name:      VARCHAR(150)\n    createdAt: TIMESTAMP   @default(now())\n  }\n}\n";
 export declare const ENV_TEMPLATE = "DATABASE_URL=postgresql://postgrest:postgrest@localhost:5432/postgrest\nJWT_SECRET=\nJWT_ROLE_CLAIM=role\nJWT_USER_ID_CLAIM=sub\n";
 export declare const GITIGNORE_TEMPLATE = "node_modules/\ndist/\n.env\ndocker_data/\n.DS_Store\n*.log\nnpm-debug.log*\n";
-export declare const DOCKER_COMPOSE_TEMPLATE = "services:\n  postgres:\n    image: postgis/postgis:16-3.4\n    container_name: schematic-pg-postgres\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgrest\n      POSTGRES_PASSWORD: postgrest\n      POSTGRES_DB: postgrest\n    volumes:\n      - ./docker_data/postgres:/var/lib/postgresql/data\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgrest -d postgrest\"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n";
+export declare const DOCKER_COMPOSE_TEMPLATE = "services:\n  postgres:\n    image: postgis/postgis:16-3.4\n    container_name: schematic-pg\n    restart: unless-stopped\n    ports:\n      - \"5432:5432\"\n    environment:\n      POSTGRES_USER: postgrest\n      POSTGRES_PASSWORD: postgrest\n      POSTGRES_DB: postgrest\n    volumes:\n      - ./docker_data/postgres:/var/lib/postgresql/data\n    healthcheck:\n      test: [\"CMD-SHELL\", \"pg_isready -U postgrest -d postgrest\"]\n      interval: 5s\n      timeout: 5s\n      retries: 5\n";
 export declare const TSCONFIG_TEMPLATE = "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"NodeNext\",\n    \"moduleResolution\": \"NodeNext\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"outDir\": \"dist\",\n    \"rootDir\": \".\"\n  },\n  \"include\": [\"generated/**/*\", \"src/**/*\"]\n}\n";
-export declare const MAKEFILE_TEMPLATE = ".PHONY: dev\n\ndev:\n\tdocker compose up -d\n\tnpx schematic-pg generate\n\tnpx schematic-pg db:bootstrap\n\tnpx schematic-pg dev\n";
+export declare const MAKEFILE_TEMPLATE = ".PHONY: dev\n\ndev:\n\tdocker compose up -d --wait\n\tnpx schematic-pg dev\n";
 export declare const HEALTH_ROUTE_TEMPLATE = "import { Hono } from 'hono';\nimport type { AppEnv } from 'schematic-pg/api/types';\n\nconst router = new Hono<AppEnv>();\nrouter.get('/', (c) => c.json({ ok: true }));\nexport default router;\n";
 export declare function createPackageJsonTemplate(projectName: string): string;

package/dist/cli/templates.js

@@ -32,7 +32,7 @@ npm-debug.log*
 export const DOCKER_COMPOSE_TEMPLATE = `services:
   postgres:
     image: postgis/postgis:16-3.4
-    container_name: schematic-pg-postgres
+    container_name: schematic-pg
     restart: unless-stopped
     ports:
       - "5432:5432"
@@ -65,9 +65,7 @@ export const TSCONFIG_TEMPLATE = `{
 export const MAKEFILE_TEMPLATE = `.PHONY: dev
 
 dev:
-\tdocker compose up -d
-\tnpx ${PACKAGE_NAME} generate
-\tnpx ${PACKAGE_NAME} db:bootstrap
+\tdocker compose up -d --wait
 \tnpx ${PACKAGE_NAME} dev
 `;
 export const HEALTH_ROUTE_TEMPLATE = `import { Hono } from 'hono';

package/dist/cli/wait-for-database.d.ts

@@ -0,0 +1,9 @@
+import { DatabaseClient } from '../db/client.js';
+export type WaitForDatabaseOptions = {
+    maxAttempts?: number;
+    intervalMs?: number;
+    client?: Pick<DatabaseClient, 'query'>;
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare function pingDatabase(client: Pick<DatabaseClient, 'query'>): Promise<void>;
+export declare function waitForDatabase(options?: WaitForDatabaseOptions): Promise<void>;

package/dist/cli/wait-for-database.js

@@ -0,0 +1,39 @@
+import { DatabaseClient } from '../db/client.js';
+export async function pingDatabase(client) {
+    const result = await client.query('SELECT 1 AS ok');
+    const ok = result.rows[0]?.ok;
+    if (ok !== 1) {
+        throw new Error(`Unexpected ping result: ${String(ok)}`);
+    }
+}
+export async function waitForDatabase(options = {}) {
+    const maxAttempts = options.maxAttempts ?? 30;
+    const intervalMs = options.intervalMs ?? 1000;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const ownClient = options.client ? null : new DatabaseClient();
+    const client = options.client ?? ownClient;
+    try {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                await pingDatabase(client);
+                if (attempt > 1) {
+                    process.stderr.write(`Database ready (attempt ${attempt}/${maxAttempts})\n`);
+                }
+                return;
+            }
+            catch (error) {
+                if (attempt === maxAttempts) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    throw new Error(`Database not ready after ${maxAttempts} attempts (${intervalMs}ms interval): ${message}`);
+                }
+                process.stderr.write(`Waiting for database (${attempt}/${maxAttempts})...\n`);
+                await sleep(intervalMs);
+            }
+        }
+    }
+    finally {
+        if (ownClient) {
+            await ownClient.close();
+        }
+    }
+}

package/dist/cli.js

@@ -12,7 +12,7 @@ Commands:
   generate:sql [schema]      Generate SQL DDL to stdout
   generate:client [schema]   Generate db client files
   generate:api [schema]      Generate API files
-  dev [schema]               Regenerate client + API and start server
+  dev [schema] [--no-watch]  Generate, bootstrap DB, start server, watch schema
   db:ping                    Test database connection
   db:bootstrap [schema]      Apply DDL and snapshot schema state
   db:diff [schema]           Show schema diff (--name <name> to write migration)
@@ -50,7 +50,7 @@ async function main() {
                 await generateApi(schemaPath);
                 break;
             case 'dev':
-                await runDev(schemaPath);
+                await runDev(args);
                 break;
             case 'db:ping':
                 await runDbPing();

package/dist/constants.d.ts

@@ -1,3 +1,4 @@
 export declare const PACKAGE_NAME = "schematic-pg";
 export declare const PACKAGE_VERSION: string;
 export declare const MAX_INCLUDE_DEPTH = 10;
+export declare const MAX_INCLUDE_PATHS = 10;

package/dist/constants.js

@@ -4,3 +4,4 @@ const { version } = require('../package.json');
 export const PACKAGE_NAME = 'schematic-pg';
 export const PACKAGE_VERSION = version;
 export const MAX_INCLUDE_DEPTH = 10;
+export const MAX_INCLUDE_PATHS = 10;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "schematic-pg",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Single-file backend framework for PostgreSQL and Node.js",
   "type": "module",
   "license": "MIT",