fastify-auto-sqlapi 0.0.5 → 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
@@ -234,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
@@ -271,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;
@@ -308,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
 
@@ -351,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)).
@@ -401,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);
 });
@@ -431,10 +552,13 @@ const sqlApi = createSqlApi(db, dbTables, { dialect: 'mysql' });
 
 ```typescript
 // Search — full filter, join, pagination, aggregation support
-// orderBy supports dot notation for joinGroup aggregations: "session.sum.duration DESC"
-// (requires the joinGroup to be declared in the same request, see AGENTS_FRONTEND.md)
+// 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>
 
@@ -640,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]
@@ -660,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']);
           }
         }
       }