fastify-auto-sqlapi 0.0.4 → 0.1.1

package/AGENTS.md

@@ -8,9 +8,11 @@ The plugin generates REST endpoints (search, get, insert, update, delete, bulk u
 
 ## Documentation
 
-- **[AGENTS_BACKEND.md](./AGENTS_BACKEND.md)** — Setup workflow, CLI, schema/table generation, `defineTable()` complete reference, `buildRelation`, `extraFilters` + `extendedCondition`, **SqlApi** (programmatic high-level API for custom routes), ConditionBuilder API, QueryClient API, Swagger, multi-tenant configuration, **validation** (`validate` + `validateBulk`), hooks, key conventions, common backend patterns, FAQ/gotchas, dialect differences.
+- **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** — **READ FIRST when migrating.** Maps the old join API (`joinFilters`, `joins`, `joinGroups`) to the new alias-based one (`joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`). Covers `buildRelation` new options-object signature (alias defaults to `joinSchema.tableName`, plus `selection` and `unique`), request/response key renames, secondaries key renames, dotted notation rules, and validation/400 errors. Common to backend and frontend.
 
-- **[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)** — Generated endpoints overview, search (POST with body filters, conditions/advanced filters using ConditionBuilder methods, query params for ordering/pagination/aggregation), joinFilters (EXISTS-based filtering by related tables), GET, INSERT (with secondaries), UPDATE (with secondaries + deletions), DELETE, bulk upsert, bulk delete, response shapes (PK-only), **validation errors** (structured field-level 400 responses), joins usage, joinGroups/aggregations, pagination, computed values.
+- **[AGENTS_BACKEND.md](./AGENTS_BACKEND.md)** — Setup workflow, CLI, schema/table generation, `defineTable()` complete reference, `buildRelation` (alias + unique), `extraFilters` + `extendedCondition`, **SqlApi** (programmatic high-level API for custom routes), ConditionBuilder API, QueryClient API, Swagger, multi-tenant configuration, **validation** (`validate` + `validateBulk`), hooks, key conventions, common backend patterns, FAQ/gotchas, dialect differences.
+
+- **[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)** — Generated endpoints overview, search (POST with body filters, conditions/advanced filters using ConditionBuilder methods, query params for ordering/pagination/aggregation), `joinMustExist` (EXISTS-based filtering by related tables), `joinMultiple` (fetch child rows), `joinGroup` (aggregations), `joinLeft` (embed N:1 parent inline), GET, INSERT (with secondaries), UPDATE (with secondaries + deletions), DELETE, bulk upsert, bulk delete, response shapes (PK-only), **validation errors** (structured field-level 400 responses), pagination, computed values.
 
 ## Quick Reference
 
@@ -54,3 +56,14 @@ export const TableCustomer = defineTable({
   ...exportTableInfo(Schema),
 });
 ```
+
+### Joins at a glance
+
+| Family | Direction | Cardinality | Output |
+|--------|-----------|-------------|--------|
+| `joinMustExist` | child → main | 1:N | filters main via EXISTS |
+| `joinMultiple` | child → main | 1:N | side query, child rows in `result.joinMultiple.<alias>` |
+| `joinGroup` | child → main | 1:N | aggregations in `result.joinGroup.<alias>` |
+| `joinLeft` | parent → main | N:1 | real LEFT JOIN (on demand), parent rows in `result.joinLeft.<alias>` |
+
+Declare relations with `buildRelation(M, mF, J, jF, options?)`. Options are all optional: `alias` defaults to `joinSchema.tableName` (override only when joining the same table twice or to use a friendlier name), `selection` defaults to `'*'`, `unique` defaults to `false`. Set `unique: true` for N:1 (parent) relations to enable `joinLeft`. See [BREAKING_CHANGES.md](./BREAKING_CHANGES.md) for the full migration guide.

package/AGENTS_BACKEND.md

@@ -2,6 +2,8 @@
 
 How to set up schemas, tables, and configure the plugin.
 
+> ⚠️ **Migrating from a previous version?** The join API was redesigned (no backward compat). See **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** for the full migration guide — request/response key renames, `buildRelation` signature, and validation rules. Common to backend and frontend.
+
 ## Setup Workflow
 
 ### 1. Install
@@ -21,15 +23,16 @@ npm install @fastify/swagger @fastify/swagger-ui
 Create `sqlapi.config.ts` (or `.js`) in the project root. This config is used **only by the CLI** (`sqlapi-generate-schema` / `sqlapi-generate-tables`), NOT at runtime by the Fastify plugin.
 
 ```typescript
-// sqlapi.config.ts — interface: { outputDir: string; schema?: string; dialect?: DialectName }
+// sqlapi.config.ts — interface: { outputDir: string; schema?: string; dialect?: DialectName; envFile?: string }
 export default {
   outputDir: './src/db',       // base directory for generated files (default: './src/db')
   schema: 'public',            // DB schema to introspect (default: 'public', PostgreSQL only)
   dialect: 'postgres',         // 'postgres' | 'mysql' | 'mariadb' (default: 'postgres')
+  // envFile: '../../.env',    // path to .env file, relative to cwd (default: '.env')
 };
 ```
 
-That's it — only these three fields exist. **No connection string, no migration path.** If the file is missing, defaults are used. The `dialect` can also be passed via CLI flag `--dialect mysql`.
+That's it — only these four fields exist. **No connection string, no migration path.** If the file is missing, defaults are used. The `dialect` can also be passed via CLI flag `--dialect mysql`. The `envFile` is useful in monorepo setups where the `.env` lives at the repo root.
 
 ### 3. Configure database connection (env vars)
 
@@ -233,13 +236,20 @@ export const TableCustomer = defineTable({
   excludeFromCreation: ['id'],            // Fields omitted from INSERT — MUST include auto-increment PKs
   distinctResults: true,                  // Use SELECT DISTINCT
 
-  // JOINS — relations to other tables
-  allowedReadJoins: [                     // Available for search queries (joins, joinFilters, joinGroups)
-    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),
-    buildRelation(SchemaCustomer, 'id', SchemaAddress, 'customerId', 'id, city, zip'),
+  // JOINS — relations to other tables. Alias defaults to joinSchema.tableName —
+  // declare it explicitly only when joining the same table twice or when you want
+  // a friendlier name. Set `unique: true` for N:1 (parent) relations to enable `joinLeft`.
+  allowedReadJoins: [                     // Available for search: joinMustExist / joinMultiple / joinGroup / joinLeft
+    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                              // alias = 'order' (default)
+    buildRelation(SchemaCustomer, 'id', SchemaAddress, 'customerId', { selection: 'id, city, zip' }), // alias = 'address'
+    // N:1 example (enables joinLeft):
+    // buildRelation(SchemaSession, 'userId', SchemaUser, 'id', { unique: true }),               // alias = 'user'
+    // Alias multipli sulla stessa tabella (richiede alias espliciti):
+    // buildRelation(SchemaSession, 'createdBy', SchemaUser, 'id', { alias: 'creator', unique: true }),
+    // buildRelation(SchemaSession, 'updatedBy', SchemaUser, 'id', { alias: 'updater', unique: true }),
   ],
-  allowedWriteJoins: [                    // Available for insert/update secondaries
-    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),
+  allowedWriteJoins: [                    // Available for insert/update secondaries (alias is the request body key)
+    buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                              // alias = 'order'
   ],
 
   // UPSERT — ON CONFLICT resolution
@@ -270,8 +280,9 @@ export const TableCustomer = defineTable({
     if (main.name === '') {
       errors.push(['name', 'required', 'cannot be empty']);
     }
-    // Cross-entity: validate secondaries (e.g. date overlap in periods)
-    if (secondaries?.customer_order) {
+    // Cross-entity: validate secondaries (e.g. date overlap in periods).
+    // Note: secondaries are keyed by alias (declared in allowedWriteJoins), not by tableName.
+    if (secondaries?.orders) {
       // ... check overlaps, business rules across related records
     }
     return errors;
@@ -282,17 +293,17 @@ export const TableCustomer = defineTable({
     return []; // ValidationError[]
   },
 
-  // HOOKS — side effects (runs after validation)
+  // HOOKS — side effects (runs after validation). All receive camelCase (schema field names).
   beforeInsert: async (db, req, record) => {
-    // Mutate record before INSERT. record is snake_case.
-    record.created_by = req.user.id;
+    // Mutate record before INSERT. Use camelCase (schema) field names — conversion is automatic.
+    record.createdBy = req.user.id;
   },
   afterInsert: async (db, req, record, secondaryRecords) => {
-    // Called after INSERT + secondaries. record is camelCase.
+    // Called after INSERT + secondaries. record is camelCase (input merged with generated PK).
   },
   beforeUpdate: async (db, req, fields) => {
-    // Mutate fields before UPDATE. fields is snake_case.
-    fields.updated_by = req.user.id;
+    // Mutate fields before UPDATE. camelCase. PK is present for reference but excluded from UPDATE SET.
+    fields.updatedBy = req.user.id;
   },
 
   // AUTH — per-table request hooks
@@ -307,14 +318,42 @@ export const TableCustomer = defineTable({
 ### buildRelation signature
 
 ```typescript
-buildRelation(mainSchema, mainField, joinSchema, joinField, selection?)
+buildRelation(mainSchema, mainField, joinSchema, joinField, options?)
+
+// where options is fully optional:
+// {
+//   alias?: string;           // default = joinSchema.tableName. The key used in request/response
+//                             // payloads, secondaries/deletions, and dotted-notation orderBy/conditions.
+//   selection?: string;       // default '*'. Comma-separated columns: 'id, name, total'.
+//   unique?: boolean;         // default false.
+//                             //   false → 1:N (child→main). Allowed in joinMustExist/joinMultiple/joinGroup.
+//                             //   true  → N:1 (parent→main). Allowed in joinLeft only.
+// }
 ```
 
 - `mainField`: field(s) in main table (string or string[])
-- `joinField`: field in join table that references the main
-- `selection`: SQL columns to select (default `'*'`), e.g. `'id, name, total'`
+- `joinField`: field in join table that joins to `mainField`
+  - For 1:N (child→main): `joinField` is the FK on the child table → `mainField` is the PK on main
+  - For N:1 (parent→main): `joinField` is the PK on the parent table → `mainField` is the FK on main
+
+**When to declare an explicit `alias`**: only when (a) you join the same table multiple times in the same `allowedReadJoins`/`allowedWriteJoins`, or (b) you want a friendlier name in the public API surface than the SQL table name (e.g. `'orders'` instead of `'customer_order'`). Otherwise omit it — the default is `joinSchema.tableName`.
 
-The join works as: `SELECT {selection} FROM {joinTable} WHERE {joinField} IN ({mainField values})`
+**Choosing `unique`**: if `joinField` is the PK (or part of the composite PK) of `joinSchema`, the relation is N:1 — you almost certainly want `unique: true` so the alias is usable in `joinLeft`.
+
+**Aliasing the same table twice**: declare two `buildRelation` entries with different `alias`. Example: a `session` table referencing `user` for both `createdBy` and `updatedBy`:
+
+```typescript
+allowedReadJoins: [
+  buildRelation(SchemaSession, 'createdBy', SchemaUser, 'id', { alias: 'creator', unique: true }),
+  buildRelation(SchemaSession, 'updatedBy', SchemaUser, 'id', { alias: 'updater', unique: true }),
+]
+```
+
+If two entries in the same `allowedReadJoins`/`allowedWriteJoins` resolve to the same alias (explicit or implicit), `defineTable` throws at startup. So you cannot accidentally have two relations sharing an alias — the error tells you to disambiguate explicitly.
+
+The 1:N joins (`joinMustExist` / `joinMultiple` / `joinGroup`) work as: `SELECT {selection} FROM {childTable} WHERE {childFK} IN ({mainPK values})`. The N:1 join (`joinLeft`) adds `LEFT JOIN {parentTable} AS {alias} ON {alias}.{parentPK} = {main}.{mainFK}` to the main query, but only when the request actually needs it (filters/orderBy on parent fields). Otherwise a side query `SELECT FROM {parentTable} WHERE {parentPK} IN (distinct main FK values)` is used.
+
+**`joinLeft` limitation**: `extraFilters` declared via `extendedCondition` on the parent table are not applied inside `joinLeft.filters` (only schema fields). The other join families fully support extraFilters.
 
 ### extraFilters + extendedCondition
 
@@ -350,6 +389,89 @@ export const TableCustomer = defineTable({
 
 ---
 
+## Computed Fields (extension system)
+
+`computedFields` lets you declare **virtual fields** as SQL expressions on a per-table basis. Each computed becomes usable like a regular schema field across the search API: `filters` (equality), `conditions` (operators), `orderBy` (1-parte), `computeMin/Max/Sum/Avg`, and (opt-in) in `selectComputed` for the main response. Same machinery serves JSON column extraction, derived strings, dialect-aware date/calendar bucketing — without growing the library case-by-case.
+
+```typescript
+import { defineTable, exportTableInfo, Type } from 'fastify-auto-sqlapi';
+import { SchemaCustomer as Schema } from '../schemas/SchemaCustomer';
+
+export const TableCustomer = defineTable({
+  primary: 'id',
+  ...exportTableInfo(Schema),
+  computedFields: {
+    // JSON path extraction — dialect-aware (Postgres -> arrow, MySQL -> JSON_EXTRACT).
+    statusFromMeta: ({ db, qiCol }) => ({
+      expr: db.dialectName === 'postgres'
+        ? `${qiCol('metadata')}->>'status'`
+        : `JSON_UNQUOTE(JSON_EXTRACT(${qiCol('metadata')}, '$.status'))`,
+      values: [],
+      type: Type.String(),
+    }),
+    // Derived string column — dialect-aware concat.
+    fullName: ({ db, qiCol }) => ({
+      expr: db.dialectName === 'postgres'
+        ? `${qiCol('firstName')} || ' ' || ${qiCol('lastName')}`
+        : `CONCAT(${qiCol('firstName')}, ' ', ${qiCol('lastName')})`,
+      values: [],
+      type: Type.String(),
+    }),
+  },
+});
+```
+
+Client side, the computed name behaves like any other field:
+
+```json
+{
+  "filters": { "statusFromMeta": "active" },
+  "conditions": [
+    { "field": "fullName", "method": "isLike", "params": ["%Mario%"] }
+  ],
+  "orderBy": "fullName ASC",
+  "selectComputed": ["fullName", "statusFromMeta"]
+}
+```
+
+The values returned by `selectComputed` appear as extra fields on each `main[i]` row.
+
+### `ComputedFieldFn` signature
+
+```typescript
+type ComputedFieldFn = (ctx: {
+  db: QueryClient;                                 // dialect-aware (qi, ph, dialectName, dateTrunc, ...)
+  qiCol(field: string, opts?: { qualifier?: string }): string;
+}) => {
+  expr: string;                                    // SQL fragment
+  values: unknown[];                               // bound values (see limitations below)
+  type: TSchema;                                   // REQUIRED — used by Swagger and body validation
+};
+```
+
+`qiCol(field)` returns a properly-quoted column reference, optionally prefixed by an alias qualifier — the engine passes the alias automatically when the computed is invoked inside a `joinLeft` LEFT JOIN, so the same function works both inline on the main query and as a parent-side column.
+
+### Validation & startup checks
+
+`defineTable` throws synchronously if a computed name collides with a schema field or an `extraFilters` key on the same table. The error message tells you which name to change.
+
+### Side queries (`joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`)
+
+Computed fields are **per-table**: a side query operating on a join target reads `joinTableConf.computedFields`, not the main table's. So if you need `statusFromMeta` on `joinLeft.user.filters`, declare it on `TableUser`, not on `TableSession`.
+
+For `joinLeft` specifically, the computed expr is automatically alias-prefixed by `qiCol` (the engine forwards the alias). For the other three families the side query is a separate SELECT, so plain column references suffice.
+
+### Limitations (first round, by design)
+
+- **Bound `values` in computed expressions** are supported only on `filters`/`conditions` (main and `joinMustExist`/`joinMultiple`/`joinGroup`). They are rejected with 400 on `selectComputed`, `computeMin/Max/Sum/Avg`, `orderBy`, and `joinLeft.filters`/`conditions` — those paths require placeholder coordination not done in the first round. Most use cases (JSON extraction, concat, dateTrunc, simple ops) need no placeholders.
+- **Computed CAN be used in `joinGroup.aggregations.by`** (just pass the computed name as a string). Bound `values` are not supported in this position (rejected with 400). The existing FK-correlation rule for `orderBy <alias>.<fn>.<field>` still applies: 3-parti aggregation orderBy on a `by` that isn't the correlation FK is rejected — by definition a computed-by produces multiple groups per main row, so this is never valid.
+- **Computed cannot be used as aggregation function** (`sum`/`min`/`max`/...). The values inside `aggregations.sum: ['<name>']` must be schema field names. To aggregate on a derived expression, declare the derivation as a computed and pass the computed name as the field, BUT only via `computeMin/Max/Sum/Avg` (top-level main aggregates), not the joinGroup ones.
+- **No chained computed** (a computed referencing another computed). Flat-only.
+- **Read-only**. Computed fields are not usable in insert/update bodies — the consumer's `expr` is for SELECT/WHERE/ORDER BY, never for writes.
+- **Same expression evaluated multiple times** when used in WHERE + ORDER BY + SELECT. Cheap exprs are fine; for expensive ones, query planner CSE often helps.
+
+---
+
 ## ConditionBuilder API
 
 Used in `extendedCondition` callbacks, hooks, and exposed via the `conditions` field in the search API (see [AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md#conditions-advanced-filters)).
@@ -400,7 +522,7 @@ app.get('/billing/:customerId', async (request) => {
   const customerId = Number(request.params.customerId);
   return app.sqlApi.search('subscription', {
     filters: { customerId, status: 'active' },
-    joinFilters: { customer_order: { status: 'pending' } },
+    joinMustExist: { orders: { filters: { status: 'pending' } } },
     paginator: { page: 1, itemsPerPage: 50 },
   }, request);
 });
@@ -430,8 +552,13 @@ const sqlApi = createSqlApi(db, dbTables, { dialect: 'mysql' });
 
 ```typescript
 // Search — full filter, join, pagination, aggregation support
+// orderBy supports two dotted notations:
+//   - 3-parti `<alias>.<fn>.<field>` for joinGroup aggregations (must be declared in the request body)
+//   - 2-parti `<alias>.<field>` for joinLeft parent fields
+// See AGENTS_FRONTEND.md and BREAKING_CHANGES.md for the full reference.
 sqlApi.search(tableName, {
-  filters?, joinFilters?, joins?, joinGroups?,
+  filters?, conditions?,
+  joinMustExist?, joinMultiple?, joinGroup?, joinLeft?,
   orderBy?, paginator?, computeMin?, computeMax?, computeSum?, computeAvg?,
 }, request?): Promise<SearchResult>
 
@@ -590,14 +717,14 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 
 ## Key Conventions
 
-- **camelCase in API, snake_case in DB**: all request/response fields are camelCase. The plugin converts automatically via `col()`.
+- **camelCase in API, any case in DB**: all request/response fields are camelCase. The plugin converts via `col()` and `colMap`. For snake_case DB columns (default), conversion is automatic. For camelCase DB columns (e.g. betterauth), the CLI generates a `colMap` that preserves the original column names — no conversion needed. Manual schemas without `colMap` fall back to `toUnderscore()`.
 - **All fields Optional in response**: `RETURNING *` may return any subset. Response schemas use `Type.Partial`.
 - **`excludeFromCreation`**: **IMPORTANT** — auto-increment PKs (e.g. `id` serial/auto_increment) MUST be listed here, otherwise INSERT will try to send them and fail. The CLI auto-detects this and adds it by default. Also useful for `createdAt`/`updatedAt` columns managed by DB defaults or hooks.
 - **`upsertMap`**: when present for a schema, INSERT becomes upsert. PostgreSQL: `ON CONFLICT (...) DO UPDATE`. MySQL/MariaDB: `ON DUPLICATE KEY UPDATE`. Applies to both main and secondary tables.
 - **`schemaOverrides`**: override auto-generated schema fields with stricter TypeBox types (e.g. `{ email: Type.String({ format: 'email' }) }`). Overrides are merged into the body schema for insert, update, and bulk-upsert. The original Schema file is never modified. In updates, overridden fields are still wrapped in Optional (validates only when present). Overrides appear in Swagger.
 - **Validation receives camelCase**: `validate` receives the original camelCase record (as sent by the client) and secondaries. Field names match the schema definition, with full TypeScript inference (`main.startDate`, not `main.start_date`). It returns `ValidationError[]` — tuples of `[field, code]` or `[field, code, message]`. If any errors are returned, the request is rejected with 400 before hooks or SQL execute.
 - **`validateBulk` replaces `validate` in bulk**: when `validateBulk` is defined, it is called once with all items and per-item `validate` is skipped. This allows optimized batch queries instead of N individual checks. When only `validate` is defined, it runs per-item as fallback.
-- **Hooks receive snake_case, validate receives camelCase**: `validate(db, req, main, secondaries)` gets camelCase (pre-conversion). `beforeInsert(db, req, record)` and `beforeUpdate(db, req, fields)` get snake_case (post-conversion). `afterInsert` receives camelCase (post-DB).
+- **All hooks and validators receive camelCase records**: `validate`, `beforeInsert`, `beforeUpdate`, and `afterInsert` all get records keyed by schema field names (camelCase). Mutations propagate to the SQL (plugin converts to DB column format via `colMap` after the hook). The engine internally uses `snakecaseRecord(..., schema)` after user mutations to map field names to actual DB columns.
 - **Filters validation**: TypeBox schemas use `additionalProperties: false`. By default Fastify strips unknown fields silently. For 400 errors on unknown filters: `Fastify({ ajv: { customOptions: { removeAdditional: false } } })`.
 - **Tenant filtering**: when `tenantScope` is set on a table and `getTenantId` is provided in plugin options, all CRUD operations are automatically scoped to the tenant. `getTenantId` returning `null`/`undefined` = admin (no filter). Returning an array = multi-tenant user (IN clause).
 
@@ -637,7 +764,7 @@ const TableSession = defineTable({
   primary: 'id',
   ...exportTableInfo(SchemaSession),
   allowedWriteJoins: [
-    buildRelation(SchemaSession, 'id', SchemaPeriod, 'sessionId'),
+    buildRelation(SchemaSession, 'id', SchemaPeriod, 'sessionId', { alias: 'periods' }),
   ],
   validate: async (db, req, main, secondaries) => {
     // ValidationError is a tuple: [field, code] or [field, code, message]
@@ -657,13 +784,13 @@ const TableSession = defineTable({
       }
     }
 
-    // Cross-entity: validate periods don't overlap
-    const periods = secondaries?.session_period;
+    // Cross-entity: validate periods don't overlap (secondaries keyed by alias)
+    const periods = secondaries?.periods;
     if (periods?.length) {
       for (let i = 0; i < periods.length; i++) {
         for (let j = i + 1; j < periods.length; j++) {
           if (periods[i].startDate < periods[j].endDate && periods[j].startDate < periods[i].endDate) {
-            errors.push([`session_period[${j}].startDate`, 'overlap', 'overlaps with another period']);
+            errors.push([`periods[${j}].startDate`, 'overlap', 'overlaps with another period']);
           }
         }
       }
@@ -699,12 +826,13 @@ const TableCustomer = defineTable({
   primary: 'id',
   ...exportTableInfo(SchemaCustomer),
   beforeInsert: async (db, req, record) => {
-    record.created_by = req.user.id;
-    record.created_at = db.expression('NOW()');
+    // camelCase — schema field names. The plugin converts to the actual DB column names.
+    record.createdBy = req.user.id;
+    record.createdAt = db.expression('NOW()');
   },
   beforeUpdate: async (db, req, fields) => {
-    fields.updated_by = req.user.id;
-    fields.updated_at = db.expression('NOW()');
+    fields.updatedBy = req.user.id;
+    fields.updatedAt = db.expression('NOW()');
   },
 });
 ```