fastify-auto-sqlapi 0.1.14 → 0.2.0

package/dist/lib/schema/search.js

@@ -1,5 +1,5 @@
 import { Type } from '@sinclair/typebox';
-import { ALLOWED_METHODS } from '../condition-methods.js';
+import { ALLOWED_METHODS, MAX_CONDITIONS, MAX_ORDER_BY_LENGTH } from '../condition-methods.js';
 import { readableFieldNames } from '../read-access.js';
 import { DEFAULT_MAX_ITEMS_PER_PAGE } from '../../types.js';
 /** Schema fields minus the ones hidden by `readExclude`. */
@@ -24,6 +24,100 @@ function readableFields(schema, tableConf) {
 function filtersObject(fields) {
     return Type.Partial(Type.Object(fields));
 }
+/**
+ * TypeBox types declared by a table's computed fields.
+ *
+ * Each computed is dry-run with a stub context purely to read its declared `type`; the
+ * functions are pure with respect to that context. Best-effort by design — a computed that
+ * throws is skipped, because this only feeds the Swagger/body schema and the engine
+ * validates for real at request time.
+ */
+function computedFieldTypes(tableConf) {
+    const out = {};
+    for (const [name, fn] of Object.entries(tableConf?.computedFields ?? {})) {
+        try {
+            const stub = fn({
+                db: { qi: (s) => s, dialectName: 'postgres' },
+                qiCol: () => '""',
+            });
+            if (stub.type)
+                out[name] = stub.type;
+        }
+        catch {
+            // ignore — schema generation is best-effort; runtime validates.
+        }
+    }
+    return out;
+}
+function buildJoinBodyProps(dbTables, tableConf, conditionItemSchema) {
+    const props = {
+        joinMustExist: {},
+        joinMultiple: {},
+        joinGroup: {},
+        joinLeft: {},
+    };
+    for (const joinDef of tableConf.allowedReadJoins ?? []) {
+        const { joinSchema, alias, unique } = joinDef;
+        const joinTableConf = dbTables[joinSchema.tableName];
+        const joinSchemaFields = joinTableConf
+            ? { ...readableFields(joinSchema, joinTableConf), ...computedFieldTypes(joinTableConf) }
+            : { ...joinSchema.fields };
+        // `extraFilters` are only honoured where the engine delegates to the join table's
+        // own `filters()` — buildJoinRefCondition, i.e. the unique:false paths. joinLeft
+        // builds its condition inline (buildLeftJoinClauses) and handles schema and computed
+        // fields only, so advertising extraFilters there would promise a silent no-op.
+        const joinFilterFields = { ...joinSchemaFields, ...(joinTableConf?.extraFilters ?? {}) };
+        const joinRefShape = {
+            filters: Type.Optional(filtersObject(joinFilterFields)),
+            conditions: Type.Optional(Type.Array(conditionItemSchema, { maxItems: MAX_CONDITIONS })),
+        };
+        if (unique) {
+            props.joinLeft[alias] = Type.Object({
+                filters: Type.Optional(filtersObject(joinSchemaFields)),
+                conditions: Type.Optional(Type.Array(conditionItemSchema, { maxItems: MAX_CONDITIONS })),
+                selection: Type.Optional(Type.String()),
+            });
+            continue;
+        }
+        props.joinMustExist[alias] = Type.Object(joinRefShape);
+        props.joinMultiple[alias] = Type.Object({
+            ...joinRefShape,
+            selection: Type.Optional(Type.String()),
+        });
+        props.joinGroup[alias] = Type.Object({
+            aggregations: Type.Object({
+                by: Type.Optional(Type.String()),
+                distinctCount: Type.Optional(Type.Array(Type.String())),
+                min: Type.Optional(Type.Array(Type.String())),
+                max: Type.Optional(Type.Array(Type.String())),
+                sum: Type.Optional(Type.Array(Type.String())),
+                avg: Type.Optional(Type.Array(Type.String())),
+                count: Type.Optional(Type.Array(Type.String())),
+            }),
+            filters: Type.Optional(filtersObject(joinFilterFields)),
+            conditions: Type.Optional(Type.Array(conditionItemSchema, { maxItems: MAX_CONDITIONS })),
+        });
+    }
+    return props;
+}
+/** Per-alias *response* shapes: the rows each join family contributes to the result. */
+function buildJoinResponseProps(dbTables, tableConf) {
+    const joinMultipleProps = {};
+    const joinLeftProps = {};
+    const joinGroupProps = {};
+    for (const joinDef of tableConf.allowedReadJoins ?? []) {
+        const { joinSchema, alias, unique } = joinDef;
+        const itemArray = Type.Array(Type.Partial(Type.Object(readableFields(joinSchema, dbTables[joinSchema.tableName]))));
+        if (unique) {
+            joinLeftProps[alias] = itemArray;
+        }
+        else {
+            joinMultipleProps[alias] = itemArray;
+            joinGroupProps[alias] = JoinGroupResultItem;
+        }
+    }
+    return { joinMultipleProps, joinLeftProps, joinGroupProps };
+}
 const JoinGroupResultItem = Type.Object({
     sum: Type.Optional(Type.Record(Type.String(), Type.Any())),
     min: Type.Optional(Type.Record(Type.String(), Type.Any())),
@@ -42,113 +136,28 @@ export function SearchTableBodyPost(dbTables, tableName) {
         method: methodEnum,
         params: Type.Optional(Type.Array(Type.Any())),
     });
-    // Build a TypeBox map of computed-field types (declared in defineTable).
-    const computedTypes = {};
-    if (tableConf.computedFields) {
-        for (const [name, fn] of Object.entries(tableConf.computedFields)) {
-            // Cheap dry-run with a stub context to extract the declared `type`.
-            // The fn is pure-functional w.r.t. ctx — only `type` is read here.
-            try {
-                const stub = fn({
-                    db: { qi: (s) => s, dialectName: 'postgres' },
-                    qiCol: () => '""',
-                });
-                if (stub.type)
-                    computedTypes[name] = stub.type;
-            }
-            catch {
-                // ignore — Swagger schema generation is best-effort; runtime validates.
-            }
-        }
-    }
+    const computedTypes = computedFieldTypes(tableConf);
     const filterFields = {
         ...readableFields(schema, tableConf),
         ...tableConf.extraFilters,
         ...computedTypes,
     };
     const filtersSchema = Type.Optional(filtersObject(filterFields));
-    // Per-alias entries split by unique flag:
-    //  - unique:false → joinMustExist / joinMultiple / joinGroup
-    //  - unique:true  → joinLeft
-    const joinMustExistProps = {};
-    const joinMultipleProps = {};
-    const joinGroupProps = {};
-    const joinLeftProps = {};
-    if (tableConf.allowedReadJoins) {
-        for (const joinDef of tableConf.allowedReadJoins) {
-            const { joinSchema, alias, unique } = joinDef;
-            const joinTableConf = dbTables[joinSchema.tableName];
-            const joinComputedTypes = {};
-            if (joinTableConf?.computedFields) {
-                for (const [name, fn] of Object.entries(joinTableConf.computedFields)) {
-                    try {
-                        const stub = fn({
-                            db: { qi: (s) => s, dialectName: 'postgres' },
-                            qiCol: () => '""',
-                        });
-                        if (stub.type)
-                            joinComputedTypes[name] = stub.type;
-                    }
-                    catch {
-                        // best-effort
-                    }
-                }
-            }
-            const joinSchemaFields = joinTableConf
-                ? { ...readableFields(joinSchema, joinTableConf), ...joinComputedTypes }
-                : { ...joinSchema.fields };
-            // `extraFilters` are only honoured where the engine delegates to the join table's
-            // own `filters()` — buildJoinRefCondition, i.e. the unique:false paths. joinLeft
-            // builds its condition inline (buildLeftJoinClauses) and handles schema and computed
-            // fields only, so advertising extraFilters there would promise a silent no-op.
-            const joinFilterFields = { ...joinSchemaFields, ...(joinTableConf?.extraFilters ?? {}) };
-            const joinRefShape = {
-                filters: Type.Optional(filtersObject(joinFilterFields)),
-                conditions: Type.Optional(Type.Array(conditionItemSchema)),
-            };
-            if (unique) {
-                joinLeftProps[alias] = Type.Object({
-                    filters: Type.Optional(filtersObject(joinSchemaFields)),
-                    conditions: Type.Optional(Type.Array(conditionItemSchema)),
-                    selection: Type.Optional(Type.String()),
-                });
-            }
-            else {
-                joinMustExistProps[alias] = Type.Object(joinRefShape);
-                joinMultipleProps[alias] = Type.Object({
-                    ...joinRefShape,
-                    selection: Type.Optional(Type.String()),
-                });
-                joinGroupProps[alias] = Type.Object({
-                    aggregations: Type.Object({
-                        by: Type.Optional(Type.String()),
-                        distinctCount: Type.Optional(Type.Array(Type.String())),
-                        min: Type.Optional(Type.Array(Type.String())),
-                        max: Type.Optional(Type.Array(Type.String())),
-                        sum: Type.Optional(Type.Array(Type.String())),
-                        avg: Type.Optional(Type.Array(Type.String())),
-                        count: Type.Optional(Type.Array(Type.String())),
-                    }),
-                    filters: Type.Optional(filtersObject(joinFilterFields)),
-                    conditions: Type.Optional(Type.Array(conditionItemSchema)),
-                });
-            }
-        }
-    }
+    const joins = buildJoinBodyProps(dbTables, tableConf, conditionItemSchema);
     const bodyProperties = {
         filters: filtersSchema,
-        conditions: Type.Optional(Type.Array(conditionItemSchema)),
+        conditions: Type.Optional(Type.Array(conditionItemSchema, { maxItems: MAX_CONDITIONS })),
     };
     if (Object.keys(computedTypes).length > 0) {
         bodyProperties.selectComputed = Type.Optional(Type.Array(Type.String()));
     }
-    if (Object.keys(joinMustExistProps).length > 0) {
-        bodyProperties.joinMustExist = Type.Optional(Type.Partial(Type.Object(joinMustExistProps)));
-        bodyProperties.joinMultiple = Type.Optional(Type.Partial(Type.Object(joinMultipleProps)));
-        bodyProperties.joinGroup = Type.Optional(Type.Partial(Type.Object(joinGroupProps)));
+    if (Object.keys(joins.joinMustExist).length > 0) {
+        bodyProperties.joinMustExist = Type.Optional(Type.Partial(Type.Object(joins.joinMustExist)));
+        bodyProperties.joinMultiple = Type.Optional(Type.Partial(Type.Object(joins.joinMultiple)));
+        bodyProperties.joinGroup = Type.Optional(Type.Partial(Type.Object(joins.joinGroup)));
     }
-    if (Object.keys(joinLeftProps).length > 0) {
-        bodyProperties.joinLeft = Type.Optional(Type.Partial(Type.Object(joinLeftProps)));
+    if (Object.keys(joins.joinLeft).length > 0) {
+        bodyProperties.joinLeft = Type.Optional(Type.Partial(Type.Object(joins.joinLeft)));
     }
     return Type.Object(bodyProperties);
 }
@@ -162,7 +171,7 @@ export function SearchTableBodyPost(dbTables, tableName) {
  */
 export function SearchTableQuery(maxItemsPerPage = DEFAULT_MAX_ITEMS_PER_PAGE) {
     return Type.Object({
-        orderBy: Type.Optional(Type.String()),
+        orderBy: Type.Optional(Type.String({ maxLength: MAX_ORDER_BY_LENGTH })),
         page: Type.Optional(Type.Integer({ minimum: 1 })),
         itemsPerPage: Type.Optional(Type.Integer({
             minimum: 1,
@@ -182,42 +191,12 @@ export function SearchTableResponse(dbTables, tableName) {
     const tableConf = dbTables[tableName];
     // Computed fields are present in main rows only when explicitly listed in
     // request body's selectComputed, so they're optional/Partial here.
-    const computedTypes = {};
-    if (tableConf.computedFields) {
-        for (const [name, fn] of Object.entries(tableConf.computedFields)) {
-            try {
-                const stub = fn({
-                    db: { qi: (s) => s, dialectName: 'postgres' },
-                    qiCol: () => '""',
-                });
-                if (stub.type)
-                    computedTypes[name] = stub.type;
-            }
-            catch {
-                // best-effort
-            }
-        }
-    }
+    const computedTypes = computedFieldTypes(tableConf);
     const mainReadable = readableFields(tableConf.Schema, tableConf);
     const mainItem = Object.keys(computedTypes).length > 0
         ? Type.Partial(Type.Object({ ...mainReadable, ...computedTypes }))
         : Type.Partial(Type.Object(mainReadable));
-    const joinMultipleProps = {};
-    const joinLeftProps = {};
-    const joinGroupProps = {};
-    if (tableConf.allowedReadJoins) {
-        for (const joinDef of tableConf.allowedReadJoins) {
-            const { joinSchema, alias, unique } = joinDef;
-            const itemArray = Type.Array(Type.Partial(Type.Object(readableFields(joinSchema, dbTables[joinSchema.tableName]))));
-            if (unique) {
-                joinLeftProps[alias] = itemArray;
-            }
-            else {
-                joinMultipleProps[alias] = itemArray;
-                joinGroupProps[alias] = JoinGroupResultItem;
-            }
-        }
-    }
+    const { joinMultipleProps, joinLeftProps, joinGroupProps } = buildJoinResponseProps(dbTables, tableConf);
     const responseProps = {
         table: Type.String(),
         main: Type.Array(mainItem),

package/dist/lib/sql-api.d.ts.map

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

package/dist/lib/tenant.d.ts

@@ -4,8 +4,34 @@ import { ConditionBuilder, type ConditionValue, type ConditionValueOrUndefined }
 import type { ITable, SqlApiPluginOptions, TenantId, TenantScope, TenantScopeIndirect, TenantContext } from '../types.js';
 export declare function resolveTenant(options: SqlApiPluginOptions, tableConf: ITable, request: FastifyRequest): Promise<TenantContext | undefined>;
 export declare function buildTenantCondition(db: QueryClient, scope: TenantScope, tenantIds: TenantId[], ownTable: string): ConditionBuilder;
+/**
+ * Re-target a tenant context onto a related table: the caller's tenant ids paired with that
+ * table's OWN scope. A child table declares its own `tenantScope`, which may differ in shape
+ * from the main table's, so a write to it must be checked against its own column/through-FK.
+ *
+ * Returns undefined for the two cases that must stay unscoped — no tenant context (admin) and
+ * a table that declares no scope — mirroring `appendJoinTenantScope` on the read side.
+ */
+export declare function tenantForTable(tenant: TenantContext | undefined, tableConf: ITable | undefined): TenantContext | undefined;
+/**
+ * Tenant guard as a self-contained boolean fragment, for the positions where the scope cannot
+ * be expressed as an extra INNER JOIN: a child DELETE, a LEFT JOIN's ON clause, and the
+ * correlated subquery of an aggregation. A direct scope compares the table's own column; an
+ * indirect one tests the through table with a correlated EXISTS rather than a join.
+ *
+ * `tableRef` is the name the scoped rows go by in that statement — the table name in a DELETE,
+ * the join alias in an ON clause, the subquery alias inside a correlated SELECT. Returns
+ * undefined without a tenant context (admin).
+ */
+export declare function buildTenantRowGuard(db: QueryClient, tenant: TenantContext | undefined, tableRef: string): ConditionBuilder | undefined;
 export declare function buildTenantJoin(db: QueryClient, scope: TenantScopeIndirect, mainTableName: string): string;
+/** Writes the tenant value into a record according to its scope.
+ * @testonly Exported only so unit tests can exercise it directly.
+ */
 export declare function injectTenantValue(record: Record<string, unknown>, scope: TenantScope, tenantIds: TenantId[]): void;
+/** Checks that an indirect-scope FK really belongs to the tenant.
+ * @testonly Exported only so unit tests can exercise it directly.
+ */
 export declare function validateTenantFK(db: QueryClient, scope: TenantScopeIndirect, tenantIds: TenantId[], fkValues: unknown[]): Promise<void>;
 /**
  * Build WHERE clause for DELETE with tenant filtering.

package/dist/lib/tenant.d.ts.map

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

package/dist/lib/tenant.js

@@ -30,12 +30,55 @@ export function buildTenantCondition(db, scope, tenantIds, ownTable) {
     cb.isIn(qualifier, tenantIds);
     return cb;
 }
+/**
+ * Re-target a tenant context onto a related table: the caller's tenant ids paired with that
+ * table's OWN scope. A child table declares its own `tenantScope`, which may differ in shape
+ * from the main table's, so a write to it must be checked against its own column/through-FK.
+ *
+ * Returns undefined for the two cases that must stay unscoped — no tenant context (admin) and
+ * a table that declares no scope — mirroring `appendJoinTenantScope` on the read side.
+ */
+export function tenantForTable(tenant, tableConf) {
+    const scope = tableConf?.tenantScope;
+    if (!tenant || !scope)
+        return undefined;
+    return { ids: tenant.ids, scope };
+}
+/**
+ * Tenant guard as a self-contained boolean fragment, for the positions where the scope cannot
+ * be expressed as an extra INNER JOIN: a child DELETE, a LEFT JOIN's ON clause, and the
+ * correlated subquery of an aggregation. A direct scope compares the table's own column; an
+ * indirect one tests the through table with a correlated EXISTS rather than a join.
+ *
+ * `tableRef` is the name the scoped rows go by in that statement — the table name in a DELETE,
+ * the join alias in an ON clause, the subquery alias inside a correlated SELECT. Returns
+ * undefined without a tenant context (admin).
+ */
+export function buildTenantRowGuard(db, tenant, tableRef) {
+    if (!tenant)
+        return undefined;
+    const cb = new ConditionBuilder('AND', db.cbDialect);
+    if (!isIndirect(tenant.scope)) {
+        cb.append(buildTenantCondition(db, tenant.scope, tenant.ids, tableRef));
+        return cb;
+    }
+    const { through, column } = tenant.scope;
+    const throughRef = db.qi(through.schema.tableName);
+    const markers = tenant.ids.map(() => '?').join(', ');
+    cb.raw(`EXISTS (SELECT 1 FROM ${throughRef} WHERE ` +
+        `${throughRef}.${db.qi(through.foreignField)} = ${db.qi(tableRef)}.${db.qi(through.localField)} AND ` +
+        `${throughRef}.${db.qi(column)} IN (${markers}))`, tenant.ids);
+    return cb;
+}
 export function buildTenantJoin(db, scope, mainTableName) {
     const throughTable = scope.through.schema.tableName;
     const localField = scope.through.localField;
     const foreignField = scope.through.foreignField;
     return `INNER JOIN ${db.qi(throughTable)} ON ${db.qi(mainTableName)}.${db.qi(localField)} = ${db.qi(throughTable)}.${db.qi(foreignField)}`;
 }
+/** Writes the tenant value into a record according to its scope.
+ * @testonly Exported only so unit tests can exercise it directly.
+ */
 export function injectTenantValue(record, scope, tenantIds) {
     if (isIndirect(scope))
         return;
@@ -52,6 +95,9 @@ export function injectTenantValue(record, scope, tenantIds) {
     }
     throw httpError(400, 'Ambiguous tenant: specify the tenant value');
 }
+/** Checks that an indirect-scope FK really belongs to the tenant.
+ * @testonly Exported only so unit tests can exercise it directly.
+ */
 export async function validateTenantFK(db, scope, tenantIds, fkValues) {
     if (!fkValues.length)
         return;

package/dist/routes/auto/route-helpers.d.ts

@@ -1,7 +1,5 @@
 import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
 import type { ITable, SqlApiPluginOptions, DbTables, TableOperation } from '../../types.js';
-type RequestHook = (request: FastifyRequest, reply: FastifyReply) => Promise<void | FastifyReply>;
-export declare function mergeOnRequests(options: SqlApiPluginOptions, tableConf: ITable): RequestHook[];
 export declare function buildWriteDescription(action: string, tableName: string, tableConf: ITable): string;
 interface RouteSchema {
     body?: any;
@@ -31,11 +29,6 @@ export interface AutoRouteSpec {
      * the registrar will reply.status(successStatus).send(returnValue). */
     handle: (fastify: FastifyInstance, tableName: string, tableConf: ITable, request: FastifyRequest, reply: FastifyReply) => Promise<unknown>;
 }
-/**
- * Iterates over every table in `options.DbTables` and registers one Fastify route for it
- * following `spec`. Centralizes onRequest hook merging, tags, schema response wrapping,
- * default reply when handler returns a value.
- */
 export declare function registerForAllTables(fastify: FastifyInstance, options: SqlApiPluginOptions, spec: AutoRouteSpec): Promise<void>;
 export {};
 //# sourceMappingURL=route-helpers.d.ts.map

package/dist/routes/auto/route-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE5F,KAAK,WAAW,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;AAElG,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CAE9F;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,gFAAgF;IAChF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAkDf"}
+{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQ5F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,gFAAgF;IAChF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AA6DD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/routes/auto/route-helpers.js

@@ -1,6 +1,6 @@
 import { ensureSqlApiDecorator } from '../../lib/sql-api-decorator.js';
 import { isCompositePrimary } from '../../types.js';
-export function mergeOnRequests(options, tableConf) {
+function mergeOnRequests(options, tableConf) {
     return [...(options.onRequests || []), ...(tableConf.onRequests || [])];
 }
 export function buildWriteDescription(action, tableName, tableConf) {
@@ -17,46 +17,62 @@ export function buildWriteDescription(action, tableName, tableConf) {
  * following `spec`. Centralizes onRequest hook merging, tags, schema response wrapping,
  * default reply when handler returns a value.
  */
+/**
+ * Whether this table is addressable by the spec's route shape.
+ *
+ * A single-PK route cannot address a composite-PK table. Skipping is the default, but when
+ * the consumer explicitly listed the operation it is a configuration error: failing at
+ * startup beats a route that silently never exists.
+ */
+function isTableRoutable(tableName, tableConf, spec) {
+    // operations acts as a whitelist; when omitted every operation is exposed.
+    if (tableConf.operations && !tableConf.operations.includes(spec.operation))
+        return false;
+    if (!spec.singlePkOnly || !isCompositePrimary(tableConf.primary))
+        return true;
+    if (tableConf.operations?.includes(spec.operation)) {
+        throw new Error(`Table "${tableName}" has a composite primary key (${tableConf.primary.join(', ')}): ` +
+            `operation "${spec.operation}" addresses records by a single PK value and cannot be exposed. ` +
+            `Remove it from "operations", or handle the table via search/update or a custom route.`);
+    }
+    return false;
+}
+/**
+ * Fastify route schema for one table.
+ *
+ * Only keys that are actually defined are included: Fastify checks for key *presence*
+ * (not an undefined value) to decide whether to emit FSTWRN001.
+ */
+function buildRouteSchema(tableName, tableConf, spec, schemas) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const schema = {
+        tags: [`SqlAPI-${tableName}`],
+        summary: `${spec.summary} ${tableName}`,
+        description: spec.description(tableName, tableConf, schemas),
+    };
+    if (schemas.body !== undefined)
+        schema.body = schemas.body;
+    if (schemas.params !== undefined)
+        schema.params = schemas.params;
+    if (schemas.querystring !== undefined)
+        schema.querystring = schemas.querystring;
+    if (schemas.response !== undefined)
+        schema.response = { [spec.successStatus]: schemas.response };
+    return schema;
+}
 export async function registerForAllTables(fastify, options, spec) {
     // Granular composition support: when a route plugin is registered without the
     // main plugin, no ancestor has decorated `sqlApi` — create it in this scope.
     ensureSqlApiDecorator(fastify, options);
     const { DbTables } = options;
     for (const [tableName, tableConf] of Object.entries(DbTables)) {
-        // operations acts as a whitelist; when omitted every operation is exposed.
-        if (tableConf.operations && !tableConf.operations.includes(spec.operation))
-            continue;
-        // Single-PK routes cannot address composite-PK tables — skip them (default) or,
-        // when the consumer explicitly asked for the operation, fail loudly at startup.
-        if (spec.singlePkOnly && isCompositePrimary(tableConf.primary)) {
-            if (tableConf.operations?.includes(spec.operation)) {
-                throw new Error(`Table "${tableName}" has a composite primary key (${tableConf.primary.join(', ')}): ` +
-                    `operation "${spec.operation}" addresses records by a single PK value and cannot be exposed. ` +
-                    `Remove it from "operations", or handle the table via search/update or a custom route.`);
-            }
+        if (!isTableRoutable(tableName, tableConf, spec))
             continue;
-        }
         const schemas = spec.schemas(DbTables, tableName, tableConf);
-        // Only include schema keys that are actually defined: Fastify checks for key
-        // *presence* (not undefined value) to decide whether to emit FSTWRN001.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const schema = {
-            tags: [`SqlAPI-${tableName}`],
-            summary: `${spec.summary} ${tableName}`,
-            description: spec.description(tableName, tableConf, schemas),
-        };
-        if (schemas.body !== undefined)
-            schema.body = schemas.body;
-        if (schemas.params !== undefined)
-            schema.params = schemas.params;
-        if (schemas.querystring !== undefined)
-            schema.querystring = schemas.querystring;
-        if (schemas.response !== undefined)
-            schema.response = { [spec.successStatus]: schemas.response };
         fastify.route({
             method: spec.method,
             url: spec.url(tableConf),
-            schema,
+            schema: buildRouteSchema(tableName, tableConf, spec, schemas),
             onRequest: mergeOnRequests(options, tableConf),
             handler: async (request, reply) => {
                 const result = await spec.handle(fastify, tableName, tableConf, request, reply);

package/dist/routes/auto/search.routes.js

@@ -15,7 +15,6 @@ export default async function searchRoutes(fastify, options) {
         }),
         summary: 'Search',
         description: (name, _tc, schemas) => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const body = schemas.body;
             const multiAliases = Object.keys(body?.properties?.joinMultiple?.properties || {});
             const leftAliases = Object.keys(body?.properties?.joinLeft?.properties || {});

package/dist/types/table.d.ts

@@ -30,7 +30,7 @@ export interface ITable<F extends Record<string, TSchema> = Record<string, TSche
     extraFilters: Record<string, TSchema>;
     /**
      * Virtual fields produced by a SQL expression. Usable like schema fields in
-     * `filters`, `conditions` (non-dotted), `orderBy` (1-parte),
+     * `filters`, `conditions` (non-dotted), `orderBy` (1-part),
      * `computeMin/Max/Sum/Avg`, and (opt-in) in `selectComputed` for the main
      * response. Each entry MUST declare `type` for Swagger and validation.
      *

package/docs/GLOSSARY.md

@@ -0,0 +1,28 @@
+# Glossary
+
+One name per concept. Use these words in code, tests and docs — a second name for an
+existing concept makes search fail and the concept get built twice.
+
+| Term | Meaning |
+|---|---|
+| Table config | `defineTable()` result describing one table's routes, guards and joins. (not: model, entity) |
+| Schema | TypeBox definition of a table's columns, generated from the DB. (not: model) |
+| Relation | `buildRelation()` link between two schemas, identified by an alias. (not: association) |
+| Alias | Request/response key naming one relation; defaults to the joined table name. |
+| `joinMustExist` | Child→main 1:N filter via EXISTS; never returns child rows. |
+| `joinMultiple` | Child→main 1:N side query; child rows land in `result.joinMultiple.<alias>`. |
+| `joinGroup` | Child→main 1:N aggregations in `result.joinGroup.<alias>`. |
+| `joinLeft` | Parent→main N:1 real LEFT JOIN; needs `unique: true` on the relation. |
+| Secondaries | Child rows written in the same request as the main row. (not: nested, children) |
+| Deletions | Child rows removed in the same request as the main row update. |
+| Computed field | Server-side derived value resolved during search. (not: virtual, derived) |
+| Extra filter | Non-column search filter declared per table. (not: custom filter) |
+| Extended condition | Consumer-supplied SQL fragment merged into a search WHERE. |
+| Dotted notation | `orderBy`/condition key counted in parts: 1-part `field`, 2-part `alias.field`, 3-part `alias.fn.field`. (not: parti) |
+| Tenant scope | Row-level isolation: `direct` (own column) or `indirect` (via FK). |
+| Engine | Dialect-agnostic function performing one operation. (not: service, handler) |
+| Route | Fastify plugin exposing an engine over HTTP. (not: controller) |
+| Dialect | Per-DB SQL differences (`postgres` \| `mysql`). |
+| QueryClient | Connection wrapper the engines run SQL through. (not: db, connection) |
+| Paginator | Request object carrying page and items-per-page. (not: pagination, pager) |
+| Manifest | Runtime description of a deployment's tables, for agent clients. |

package/docs/adr/0012-anti-duplication-tooling.md

@@ -0,0 +1,59 @@
+# 0012. Repository rules are enforced by executable gates, not by documentation
+
+- **Status**: accepted
+- **Date**: 2026-08-01
+
+## Context
+
+Every session starts with an empty context window. An agent that cannot find existing code
+rewrites it, invents a second name for an existing concept, and scatters logic across the
+tree. Documentation does not prevent this: it is only read when someone remembers to read
+it, and `CLAUDE.md` is weighted context, not configuration.
+
+The repository had no ESLint, no Prettier, no git hooks and no CI beyond publish-on-tag.
+Measured starting point: 2.50% duplicated lines (3.27% of tokens, 18 clones), naming drift
+effectively zero, layering already clean, and `fastify-plugin` imported but absent from
+`package.json` — a real packaging bug that no human review had caught.
+
+## Decision
+
+Anything that must not happen is a hook or a lint rule. Prose is reserved for what cannot
+be executed.
+
+Gates are **silent and zero-tolerance by default**; pre-existing debt is switched off and
+surfaced by `npm run debt` (`lint:strict`, `dup:strict`, `depcruise:strict`,
+`knip:strict`). npm scripts are the source of truth — git hooks only call them — so any
+gate can be run without touching git history.
+
+Rejected the ratchet-on-a-warning-count approach that was tried first: a run that always
+prints 241 warnings trains everyone to ignore its output, and the number drifts upward
+unnoticed. A rule is either enforced or explicitly deferred, never "warned about".
+
+## Alternatives considered
+
+- **Baseline thresholds with warnings** (`--max-warnings 241`) — rejected after
+  implementing it: noisy output is ignored output, and the boundary is invisible.
+- **Barrel enforcement via `no-restricted-imports`** — rejected: the repo has one barrel,
+  `src/index.ts`, which is the npm surface. Blocking deep imports would break every
+  internal import and require restructuring into per-module barrels. `dependency-cruiser`
+  encodes the same boundaries without moving a single file.
+- **Intent tags with a closed vocabulary, and `cspell`** — rejected: 64 files, coherent
+  naming, one maintainer. A half-maintained tag system is worse than none, and spellchecking
+  a 951-line README full of SQL identifiers is pure noise.
+- **Session worklog** — rejected: without a compaction ritual nobody will run, an
+  append-only log becomes context noise within weeks.
+
+## Consequences
+
+- New violations fail immediately; the deferred list in `eslint.config.js` is the debt
+  ledger and may only shrink.
+- `docs/INDEX.md` is generated and CI fails when it is stale, like a lockfile. It is
+  excluded from the npm package: publishing 204 internal declarations would invite
+  consumers to import what is not public API.
+- Type-only import cycles through `src/types.ts` are deferred, not fixed. Verified they
+  are erased on emit — the compiled `dist/` graph has zero cycles.
+- `knip` checks exports and types with no exclusions. The 16 symbols that were exported but
+  used only inside their own file lost the keyword; the 5 that only unit tests use are
+  tagged `@testonly`, which documents why they stay exported instead of hiding them.
+- Maintainer scripts require Node ≥22.18 (native TypeScript type stripping). The published
+  package still supports Node ≥18.