fastify-auto-sqlapi 0.0.1 → 0.0.4

package/AGENTS_FRONTEND.md

@@ -0,0 +1,414 @@
+# fastify-auto-sqlapi — Frontend API Usage
+
+How to call the auto-generated CRUD endpoints.
+
+## Generated Endpoints
+
+The plugin defines routes with these base paths: `/search/`, `/rest/`, `/bulk/`. The prefix from `register()` is prepended by Fastify. For a table `customer` with `prefix: '/auto'`:
+
+```
+POST   /auto/search/customer           — search with filters in body
+GET    /auto/rest/customer/:id         — get single record by PK
+POST   /auto/rest/customer             — insert record (+ secondaries)
+PUT    /auto/rest/customer             — update record (+ secondaries + deletions)
+DELETE /auto/rest/customer/:id         — delete record by PK
+PUT    /auto/bulk/customer             — bulk upsert (array of items)
+POST   /auto/bulk/customer/delete      — bulk delete (array of PKs)
+```
+
+Without prefix, routes are at root: `/search/customer`, `/rest/customer/:id`, etc.
+
+---
+
+## POST /search/{tableName}
+
+**Important**: Search uses `POST` (not GET) because filters are passed in the request body as JSON.
+
+### Query parameters (all optional)
+
+```
+?orderBy=name ASC, id DESC
+&page=1&itemsPerPage=20
+&computeMin=id&computeMax=id&computeSum=total&computeAvg=total
+```
+
+- `orderBy` — SQL ORDER BY clause (default: `defaultOrder` from table config)
+- `page` + `itemsPerPage` — pagination (when either is present, response includes `pagination` object; `page` defaults to 1, `itemsPerPage` defaults to 500)
+- `computeMin`, `computeMax`, `computeSum`, `computeAvg` — aggregate a column, returned in `pagination.computed`
+
+### Body (all fields optional, empty `{}` returns all records)
+
+```json
+{
+  "filters": { "name": "Mario", "q": "search term" },
+  "conditions": [
+    { "field": "createdAt", "method": "isGreater", "params": ["2024-01-01"] }
+  ],
+  "joinFilters": {
+    "customer_label_link": { "labelId": 1 }
+  },
+  "joins": {
+    "customer_order": { "filters": { "status": "pending" } }
+  },
+  "joinGroups": {
+    "customer_order": {
+      "aggregations": {
+        "by": "status",
+        "sum": ["total"],
+        "min": ["total"],
+        "max": ["total"],
+        "distinctCount": ["status"]
+      },
+      "filters": { "status": "active" }
+    }
+  }
+}
+```
+
+### Filters
+
+Pass any schema field as a key in `filters`. The plugin auto-applies `WHERE col = value` for each. Extra filters (defined via `extraFiltersValidation` in the table config) are also accepted but handled by custom logic.
+
+### Conditions (advanced filters)
+
+`conditions` allows using any ConditionBuilder method for advanced comparisons. Each condition specifies a `field`, a `method`, and `params` (values after the field).
+
+```json
+{
+  "filters": { "status": "active" },
+  "conditions": [
+    { "field": "total", "method": "isGreater", "params": [100] },
+    { "field": "total", "method": "isLess", "params": [500] },
+    { "field": "name", "method": "isILike", "params": ["%mario%"] },
+    { "field": "createdAt", "method": "isBetween", "params": ["2024-01-01", "2024-12-31"] },
+    { "field": "status", "method": "isIn", "params": [["active", "pending"]] },
+    { "field": "deletedAt", "method": "isNull", "params": [] }
+  ]
+}
+```
+
+**Available methods** (mapped to ConditionBuilder):
+
+| Method | SQL | params |
+|---|---|---|
+| `isEqual`, `isNotEqual` | `= $1` / `!= $1` | `[value]` |
+| `isGreater`, `isGreaterOrEqual` | `> $1` / `>= $1` | `[value]` |
+| `isLess`, `isLessOrEqual` | `< $1` / `<= $1` | `[value]` |
+| `isLike`, `isNotLike` | `LIKE $1` | `["%pattern%"]` |
+| `isILike`, `isNotILike` | `ILIKE $1` | `["%pattern%"]` |
+| `isIn`, `isNotIn` | `IN (...)` | `[[val1, val2]]` |
+| `isBetween`, `isNotBetween` | `BETWEEN $1 AND $2` | `[from, to]` |
+| `isNull`, `isNotNull` | `IS NULL` / `IS NOT NULL` | `[]` |
+
+Also available: `isNotGreater`, `isNotGreaterOrEqual`, `isNotLess`, `isNotLessOrEqual`.
+
+- **Multiple conditions on the same field** — it's an array, so `total > 100 AND total < 500` is natural
+- **Combinable** with `filters` (equality), `joinFilters` (EXISTS), pagination, etc.
+- **Field validation** — field names are validated against the table schema (400 if unknown)
+- **Method validation** — only whitelisted methods are allowed (`raw`, `append` etc. are blocked)
+
+### Join Filters (filter main by related table)
+
+`joinFilters` restrict **main table results** based on conditions on a related table. Only tables listed in `allowedReadJoins` are available. Uses `EXISTS` subquery — no duplicate rows, works correctly with pagination.
+
+```json
+{
+  "filters": { "name": "Mario" },
+  "joinFilters": {
+    "customer_label_link": { "labelId": 1 }
+  }
+}
+```
+
+SQL generated:
+```sql
+SELECT * FROM "customer"
+WHERE "name" = $1
+  AND EXISTS (SELECT 1 FROM "customer_label_link"
+    WHERE "customer_id" = "customer"."id" AND "label_id" = $2)
+```
+
+`joinFilters` support the same filter fields as the related table (schema fields + extra filters defined via `extendedCondition`). Can be combined with `filters`, `joins`, `joinGroups`, and pagination.
+
+**Key difference from `joins`**: `joinFilters` filter which main records are returned. `joins` fetch related data for the returned main records. They can be used together.
+
+### Joins
+
+Request related table data via `joins`. Only tables listed in `allowedReadJoins` are available. Each join key is the table name, with optional `filters` to narrow the joined results.
+
+The join executes as a separate query: `SELECT ... FROM {joinTable} WHERE {fk} IN ({main PKs})`. Results are grouped by FK.
+
+### Join Groups (Aggregations)
+
+`joinGroups` compute aggregated data on related tables:
+
+```json
+{
+  "joinGroups": {
+    "customer_order": {
+      "aggregations": {
+        "by": "status",
+        "sum": ["total"],
+        "min": ["total"],
+        "max": ["total"],
+        "distinctCount": ["status"]
+      },
+      "filters": { "status": "active" }
+    }
+  }
+}
+```
+
+- `by` — GROUP BY field
+- `sum`, `min`, `max` — aggregate functions on specified columns
+- `distinctCount` — COUNT(DISTINCT col)
+- `filters` — optional, narrow rows before aggregation
+
+### Ordering
+
+Use the `orderBy` query parameter:
+
+```
+?orderBy=name ASC
+?orderBy=name ASC, id DESC
+?orderBy=created_at DESC
+```
+
+If not specified, the table's `defaultOrder` is used.
+
+### Pagination
+
+Add `page` or `itemsPerPage` to the query string to enable pagination:
+
+```
+?page=1&itemsPerPage=20
+?itemsPerPage=10          # page defaults to 1
+```
+
+When either is present, the response includes a `pagination` object with total count, total pages, and the paginator values. `page` defaults to 1, `itemsPerPage` defaults to 500.
+
+### Computed values (aggregations on main table)
+
+```
+?computeMin=id&computeMax=id&computeSum=total&computeAvg=total
+```
+
+These compute aggregates on the main table's result set (respecting filters). Results appear in `pagination.computed`. Requires pagination to be active (`page` or `itemsPerPage` set).
+
+### Response
+
+```json
+{
+  "table": "customer",
+  "main": [{ "id": 1, "name": "Mario", "email": "m@t.it" }],
+  "joins": {
+    "customer_order": [{ "id": 10, "customerId": 1, "total": 50 }]
+  },
+  "joinGroups": {
+    "customer_order": {
+      "sum": { "total": 150 },
+      "rows": [{ "by": "pending", "sum_total": 100 }]
+    }
+  },
+  "pagination": {
+    "total": 25,
+    "pages": 3,
+    "computed": { "min": { "id": 1 }, "max": { "id": 100 } },
+    "paginator": { "page": 1, "itemsPerPage": 20 }
+  }
+}
+```
+
+`joins`, `joinGroups`, `pagination` appear ONLY if requested. A simple search returns just `{ table, main }`.
+
+---
+
+## GET /rest/{tableName}/:id
+
+Returns a single record by primary key.
+
+**Response (200):**
+
+```json
+{ "main": { "id": 1, "name": "Mario", "email": "m@t.it" } }
+```
+
+Returns 404 if not found.
+
+---
+
+## POST /rest/{tableName} (Insert)
+
+**Body:**
+
+```json
+{
+  "main": { "name": "Mario", "email": "m@t.it" },
+  "secondaries": {
+    "customer_order": [
+      { "total": 50, "status": "pending" }
+    ]
+  }
+}
+```
+
+- `main` — the record to insert. Omit auto-increment PKs (they are in `excludeFromCreation`).
+- `secondaries` — optional. Related records to insert. Only tables in `allowedWriteJoins` are accepted. FK fields (e.g. `customerId` in orders) are auto-filled from the inserted main record's PK.
+
+**Response (201):** PK-only for main and secondaries.
+
+```json
+{
+  "main": { "id": 1 },
+  "secondaries": {
+    "customer_order": [{ "id": 10 }]
+  }
+}
+```
+
+---
+
+## PUT /rest/{tableName} (Update)
+
+**Body:**
+
+```json
+{
+  "main": { "id": 1, "name": "Mario Updated", "email": "new@t.it" },
+  "secondaries": {
+    "customer_order": [{ "total": 75, "status": "shipped" }]
+  },
+  "deletions": {
+    "customer_order": [{ "id": 10 }]
+  }
+}
+```
+
+- `main` — MUST include the PK. Only changed fields need to be sent (partial update).
+- `secondaries` — optional. New related records to insert (FK auto-filled).
+- `deletions` — optional. Related records to delete (by PK).
+
+**Response (200):** PK-only for main, secondaries, and deletions.
+
+```json
+{
+  "main": { "id": 1 },
+  "secondaries": { "customer_order": [{ "id": 20 }] },
+  "deletions": { "customer_order": [{ "id": 10 }] }
+}
+```
+
+---
+
+## DELETE /rest/{tableName}/:id
+
+Deletes a single record by primary key.
+
+**Response (200):** PK-only.
+
+```json
+{ "main": { "id": 1 } }
+```
+
+404 if not found.
+
+---
+
+## PUT /bulk/{tableName} (Bulk Upsert)
+
+Insert or update multiple records in a single request.
+
+**Body:**
+
+```json
+[
+  {
+    "main": { "name": "Mario", "email": "m@t.it" },
+    "secondaries": { "customer_order": [{ "total": 50 }] },
+    "deletions": { "customer_order": [{ "id": 99 }] }
+  },
+  {
+    "main": { "name": "Luigi", "email": "l@t.it" }
+  }
+]
+```
+
+All main records are inserted/upserted in a single SQL query. Secondaries and deletions are processed per-item.
+
+**Response (200):** Array of `{ main (PK-only), secondaries? (PK-only), deletions? }`.
+
+---
+
+## POST /bulk/{tableName}/delete (Bulk Delete)
+
+Delete multiple records by PK.
+
+**Body:**
+
+```json
+[{ "id": 1 }, { "id": 2 }, { "id": 3 }]
+```
+
+Each object must contain the PK field. All deletions execute as a single `DELETE WHERE pk IN (...)`.
+
+**Response (200):** Array of PK-only objects.
+
+```json
+[{ "main": { "id": 1 } }, { "main": { "id": 2 } }]
+```
+
+---
+
+## Validation Errors
+
+Insert, update, and bulk-upsert endpoints may return **structured field-level validation errors** (400). Two sources:
+
+1. **Schema validation** (TypeBox/Ajv) — type mismatches, missing required fields
+2. **Custom validation** (`validate` / `validateBulk` on the table) — business rules, cross-entity checks
+
+Both return the same response format:
+
+```json
+{
+  "statusCode": 400,
+  "error": "Bad Request",
+  "message": "Validation failed",
+  "fields": [
+    { "path": "body.main.name", "code": "required", "message": "must have required property 'name'" },
+    { "path": "session_period[1].startDate", "code": "overlap", "message": "overlaps with another period" }
+  ]
+}
+```
+
+Each entry in `fields`:
+- `path` — the field path (e.g. `body.main.name` for schema errors, `name` or `session_period[1].startDate` for custom validation)
+- `code` — machine-readable error code (e.g. `required`, `type`, `overlap`, `unique`)
+- `message` — human-readable description
+
+### Handling validation errors in the frontend
+
+```typescript
+const response = await fetch('/api/rest/session', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ main: { name: '' }, secondaries: { session_period: periods } }),
+});
+
+if (!response.ok) {
+  const error = await response.json();
+  if (error.fields) {
+    // Field-level errors — display inline on the form
+    for (const { path, message } of error.fields) {
+      setFieldError(path, message);
+    }
+  }
+}
+```
+
+---
+
+## Response Conventions
+
+- **PK-only responses**: Insert, update, delete, bulk operations return only the primary key fields, not the full record. This is by design for performance and consistency.
+- **camelCase fields**: All request and response fields use camelCase (e.g. `customerId`, not `customer_id`). The plugin converts automatically.
+- **Joins are virtual**: Not SQL JOINs. They execute separate queries and group results by FK. This keeps the main query simple and avoids N+1 issues through batching.

package/README.md

@@ -12,6 +12,7 @@ Point it at your database, and get a full REST API with search, pagination, join
 - **Virtual joins** — fetch related records without complex SQL
 - **Bulk operations** — batch insert/upsert/delete in single queries
 - **Multi-tenant** — automatic row-level isolation, zero code in handlers
+- **Validation** — structured field-level validation with cross-entity support
 - **Hooks** — `beforeInsert`, `beforeUpdate`, `afterInsert` for custom logic
 - **Swagger UI** — optional, auto-configured from your schemas
 - **Composable** — register all routes or pick only what you need
@@ -155,10 +156,27 @@ const TableCustomer = defineTable({
     buildUpsertRule(SchemaCustomer, ['id']),
   ),
 
+  // Schema overrides (tighten generated schema without editing Schema files)
+  schemaOverrides: {
+    email: Type.String({ format: 'email' }),
+  },
+
   // Multi-tenant isolation
   tenantScope: { column: 'organization_id' },
 
-  // Hooks
+  // Validation (runs after schema validation, before hooks)
+  validate: async (db, req, main, secondaries) => {
+    // Return ValidationError[] — tuple: [field, code] or [field, code, message]
+    // message defaults to code if omitted
+    if (!main.name) return [['name', 'required']];
+    return [];
+  },
+  validateBulk: async (db, req, items) => {
+    // Bulk-upsert only. Called once with all items for cross-item validation.
+    return [];
+  },
+
+  // Hooks (runs after validation)
   beforeInsert: async (db, req, record) => { /* record is snake_case */ },
   beforeUpdate: async (db, req, fields) => { /* fields is snake_case */ },
   afterInsert: async (db, req, record, secondaryRecords) => { /* record is camelCase */ },

package/dist/bin/generate-tables.js

@@ -54,8 +54,8 @@ async function main() {
     display('++++++ fastify-auto-sqlapi: generating tables template ++++++', CONSOLE_COLORS.yellow);
     const config = await loadConfig();
     const outputDir = path.resolve(process.cwd(), cliArgs.output || config.outputDir);
-    const schemasDir = path.join(outputDir, 'schemas');
-    const tablesDir = path.join(outputDir, 'tables');
+    const schemasDir = outputDir;
+    const tablesDir = outputDir;
     if (!fs.existsSync(schemasDir)) {
         error(`Schemas directory not found: ${schemasDir}`);
         display('Run sqlapi-generate-schema first.', CONSOLE_COLORS.magenta);

package/dist/index.d.ts

@@ -30,5 +30,5 @@ export { BulkDeleteTableBody, BulkDeleteTableResponse } from './lib/schema/bulk-
 export { default as bulkDeleteRoutes } from './routes/auto/bulk-delete.routes.js';
 export { Type, type Static } from '@sinclair/typebox';
 export { ConditionBuilder, Expression } from 'node-condition-builder';
-export type { SqlApiConfig, ColumnInfo, TableMap, Queryable, SqlResult, DbRecord, DbRecordValue, SelectOptions, SchemaDefinition, JoinDefinition, ITable, DbTables, SqlApiPluginOptions, SwaggerOptions, SearchParams, SearchResult, Paginator, PaginationResult, TableFilterFn, ExtendedConditionFn, FilterRecord, AggregationRequest, JoinGroupRequest, GetParams, GetResult, DeleteParams, DeleteResult, InsertParams, InsertResult, BulkUpsertItem, BulkUpsertParams, BulkUpsertResult, BulkDeleteParams, BulkDeleteResult, ConditionMethod, SearchCondition, UpdateParams, UpdateResult, TenantId, TenantScope, TenantScopeDirect, TenantScopeIndirect, TenantContext, } from './types.js';
+export type { SqlApiConfig, ColumnInfo, TableMap, Queryable, SqlResult, DbRecord, DbRecordValue, SelectOptions, SchemaDefinition, JoinDefinition, ITable, DbTables, SqlApiPluginOptions, SwaggerOptions, SearchParams, SearchResult, Paginator, PaginationResult, TableFilterFn, ExtendedConditionFn, FilterRecord, AggregationRequest, JoinGroupRequest, GetParams, GetResult, DeleteParams, DeleteResult, InsertParams, InsertResult, BulkUpsertItem, BulkUpsertParams, BulkUpsertResult, BulkDeleteParams, BulkDeleteResult, ConditionMethod, SearchCondition, UpdateParams, UpdateResult, TenantId, TenantScope, TenantScopeDirect, TenantScopeIndirect, TenantContext, ValidationError, ValidatorFn, BulkValidatorItem, BulkValidatorFn, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/cli/pg-introspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pg-introspect.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/pg-introspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,wBAAgB,qBAAqB,IAAI,MAAM,CAY9C;AAED,wBAAsB,gBAAgB,CACpC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC,CA4BvB"}
+{"version":3,"file":"pg-introspect.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/pg-introspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,wBAAgB,qBAAqB,IAAI,MAAM,CAY9C;AAED,wBAAsB,gBAAgB,CACpC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC,CAkCvB"}

package/dist/lib/cli/pg-introspect.js

@@ -19,7 +19,14 @@ export async function introspectTables(connectionString, schema) {
         pg = require('pg');
     }
     catch {
-        throw new Error('pg is required for PostgreSQL introspection. Install it with: npm install pg');
+        try {
+            // Fallback: resolve from the package's own node_modules
+            const require = createRequire(import.meta.url);
+            pg = require('pg');
+        }
+        catch {
+            throw new Error('pg is required for PostgreSQL introspection. Install it with: npm install pg');
+        }
     }
     const client = new pg.Client({ connectionString });
     try {

package/dist/lib/cli/tables-codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tables-codegen.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/tables-codegen.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA2BpE;AAgBD,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,gBAAgB,EAAE,CAwB3E;AAID,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,MAAM,CAiGhG;AAID,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAqBrE;AAID,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAoFlE"}
+{"version":3,"file":"tables-codegen.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/tables-codegen.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA2BpE;AAgBD,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,gBAAgB,EAAE,CAwB3E;AAID,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,MAAM,CAuHhG;AAID,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAqBrE;AAID,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CA6FlE"}

package/dist/lib/cli/tables-codegen.js

@@ -140,6 +140,27 @@ export function generateSingleTableFile(schema, allSchemas) {
         lines.push(`  // allowedReadJoins: [],`);
     }
     lines.push(`  // upsertMap: buildUpsertRules(buildUpsertRule(Schema, ['${pk}'])),`);
+    // schemaOverrides: suggest email format if email field exists, otherwise minLength on first string field
+    const emailField = schema.fields.find(f => f.toLowerCase().includes('email'));
+    if (emailField) {
+        lines.push(`  // schemaOverrides: { ${emailField}: Type.String({ format: 'email' }) },`);
+    }
+    else {
+        const stringField = schema.fields.find(f => f !== pk && schema.fieldTypes[f]?.includes('String'));
+        if (stringField) {
+            lines.push(`  // schemaOverrides: { ${stringField}: Type.String({ minLength: 1 }) },`);
+        }
+        else {
+            lines.push(`  // schemaOverrides: {},`);
+        }
+    }
+    // validate: use first non-PK field for example
+    const exampleField = schema.fields.find(f => f !== pk) || schema.fields[0];
+    lines.push(`  validate: async (db, req, main, secondaries) => {`);
+    lines.push(`    const errors = [];`);
+    lines.push(`    // if (!main.${exampleField}) errors.push(['${exampleField}', 'required']);`);
+    lines.push(`    return errors;`);
+    lines.push(`  },`);
     lines.push(`  // beforeInsert: async (db, req, record) => {},`);
     lines.push(`  // beforeUpdate: async (db, req, fields) => {},`);
     if (childRels.length > 0) {
@@ -223,6 +244,13 @@ export function generateTablesFile(schemas) {
             lines.push(`  // allowedReadJoins: [],`);
         }
         lines.push(`  // upsertMap: buildUpsertRules(buildUpsertRule(${schema.schemaName}, ['${pk}'])),`);
+        lines.push(`  // schemaOverrides: {},`);
+        const exampleFieldLegacy = schema.fields.find(f => f !== pk) || schema.fields[0];
+        lines.push(`  validate: async (db, req, main, secondaries) => {`);
+        lines.push(`    const errors = [];`);
+        lines.push(`    // if (!main.${exampleFieldLegacy}) errors.push(['${exampleFieldLegacy}', 'required']);`);
+        lines.push(`    return errors;`);
+        lines.push(`  },`);
         lines.push(`  // beforeInsert: async (db, req, record) => {},`);
         lines.push(`  // beforeUpdate: async (db, req, fields) => {},`);
         const childRels = relsByChild.get(schema.schemaName) || [];

package/dist/lib/engine/bulk/bulk-upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAGjB,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAuF5F"}
+{"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAGjB,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAgG5F"}

package/dist/lib/engine/bulk/bulk-upsert.js

@@ -1,6 +1,7 @@
 import { camelcaseObject, snakecaseRecord } from '../../naming.js';
 import { removeExcludedFields, processSecondaries, processDeletions } from '../write-helpers.js';
 import { injectTenantValue, validateTenantFK } from '../../tenant.js';
+import { runValidation, runBulkValidation } from '../validate.js';
 import { primaryAsString } from '../../../types.js';
 export async function bulkUpsertEngine(params) {
     const { db, tableConf, dbTables, request, items, tenant } = params;
@@ -29,13 +30,22 @@ export async function bulkUpsertEngine(params) {
             }
         }
     }
-    // 2. beforeInsert hook per record
+    // 2. Custom validation (receives original camelCase records)
+    if (tableConf.validateBulk) {
+        await runBulkValidation(db, request, tableConf, items);
+    }
+    else {
+        for (let i = 0; i < items.length; i++) {
+            await runValidation(db, request, tableConf, items[i].main, items[i].secondaries);
+        }
+    }
+    // 3. beforeInsert hook per record
     if (tableConf.beforeInsert) {
         for (const rec of preparedMains) {
             await tableConf.beforeInsert(db, request, rec);
         }
     }
-    // 3. Bulk upsert all mains in one query → returns PK-only
+    // 4. Bulk upsert all mains in one query → returns PK-only
     const upsertKeys = tableConf.upsertMap?.get(tableConf.Schema);
     let pkRows;
     if (upsertKeys) {
@@ -46,7 +56,7 @@ export async function bulkUpsertEngine(params) {
         pkRows = await db.bulkInsert(tableConf.Schema.tableName, preparedMains, pkCol);
     }
     const pksCamel = pkRows.map((r) => camelcaseObject(r));
-    // 4. Process secondaries and deletions per item
+    // 5. Process secondaries and deletions per item
     const results = [];
     for (let i = 0; i < items.length; i++) {
         const item = items[i];
@@ -64,7 +74,7 @@ export async function bulkUpsertEngine(params) {
             if (Object.keys(del).length > 0)
                 result.deletions = del;
         }
-        // 5. afterInsert hook per item
+        // 6. afterInsert hook per item
         if (tableConf.afterInsert) {
             await tableConf.afterInsert(db, request, mainForFK, result.secondaries);
         }

package/dist/lib/engine/rest/insert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/insert.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAsE9E"}
+{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/insert.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAyE9E"}

package/dist/lib/engine/rest/insert.js

@@ -1,6 +1,7 @@
 import { camelcaseObject, snakecaseRecord } from '../../naming.js';
 import { removeExcludedFields, processSecondaries } from '../write-helpers.js';
 import { injectTenantValue, validateTenantFK } from '../../tenant.js';
+import { runValidation } from '../validate.js';
 import { primaryAsString } from '../../../types.js';
 export async function insertEngine(params) {
     const { db, tableConf, dbTables, request, record, secondaries, tenant } = params;
@@ -22,11 +23,13 @@ export async function insertEngine(params) {
             injectTenantValue(mainRecord, tenant.scope, tenant.ids);
         }
     }
-    // 2. beforeInsert hook
+    // 2. Custom validation (receives original camelCase record)
+    await runValidation(db, request, tableConf, record, secondaries);
+    // 3. beforeInsert hook
     if (tableConf.beforeInsert) {
         await tableConf.beforeInsert(db, request, mainRecord);
     }
-    // 3. Insert main → returns PK-only
+    // 4. Insert main → returns PK-only
     let pkResult;
     const upsertKeys = tableConf.upsertMap?.get(tableConf.Schema);
     if (upsertKeys) {
@@ -37,19 +40,19 @@ export async function insertEngine(params) {
         pkResult = await db.insert(tableConf.Schema.tableName, mainRecord, pkCol);
     }
     const mainPkCamel = camelcaseObject(pkResult);
-    // 4. Secondaries: need full record for FK auto-fill
+    // 5. Secondaries: need full record for FK auto-fill
     let secondaryResults;
     if (secondaries && Object.keys(secondaries).length > 0) {
         // Merge input record + PK for FK auto-fill
         const mainForFK = { ...camelcaseObject(mainRecord), ...mainPkCamel };
         secondaryResults = await processSecondaries(db, tableConf, dbTables, mainForFK, secondaries);
     }
-    // 5. afterInsert hook
+    // 6. afterInsert hook
     if (tableConf.afterInsert) {
         const mainForHook = { ...camelcaseObject(mainRecord), ...mainPkCamel };
         await tableConf.afterInsert(db, request, mainForHook, secondaryResults);
     }
-    // 6. Return PK-only
+    // 7. Return PK-only
     const result = { main: mainPkCamel };
     if (secondaryResults && Object.keys(secondaryResults).length > 0) {
         result.secondaries = secondaryResults;

package/dist/lib/engine/rest/update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/update.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CA6H9E"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/update.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAgI9E"}