schematic-pg 0.1.6 → 0.1.7

package/README.md

@@ -770,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 |
@@ -793,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/templates.d.ts

@@ -1,7 +1,7 @@
 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 --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";

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"

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.6",
+  "version": "0.1.7",
   "description": "Single-file backend framework for PostgreSQL and Node.js",
   "type": "module",
   "license": "MIT",