fastify-auto-sqlapi 0.3.0 → 0.4.1

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

@@ -62,8 +62,21 @@ export function convertColType(udtName, columnInfo) {
             return wrap('Type.String()');
     }
 }
+/**
+ * Turn the per-column index names into the table's unique keys: one field list per distinct
+ * column set, fields in table order, keys sorted so regenerating yields a stable file.
+ */
+function collectUniqueKeys(indexes) {
+    const bySet = new Map();
+    for (const fields of indexes.values()) {
+        bySet.set(JSON.stringify([...fields].sort()), fields);
+    }
+    return [...bySet.values()].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+}
 export function buildTableMap(rows) {
-    return rows.reduce((acc, row) => {
+    // schema name → unique index name → fields (camelCase), in table column order
+    const uniqueIndexes = new Map();
+    const tableMap = rows.reduce((acc, row) => {
         const schemaName = toSchemaName(row.table_name);
         if (!acc[schemaName]) {
             acc[schemaName] = {
@@ -73,7 +86,9 @@ export function buildTableMap(rows) {
                 primary: [],
                 generated: [],
                 isView: row.is_view === true,
+                uniqueKeys: [],
             };
+            uniqueIndexes.set(schemaName, new Map());
         }
         const fieldName = toCamelCase(row.column_name);
         // Two columns mapping to the same camelCase field (e.g. user_name + userName) would
@@ -92,8 +107,16 @@ export function buildTableMap(rows) {
         if (row.is_generated) {
             acc[schemaName].generated.push(fieldName);
         }
+        const indexes = uniqueIndexes.get(schemaName);
+        for (const indexName of row.unique_keys ?? []) {
+            indexes.set(indexName, [...(indexes.get(indexName) ?? []), fieldName]);
+        }
         return acc;
     }, {});
+    for (const [schemaName, indexes] of uniqueIndexes) {
+        tableMap[schemaName].uniqueKeys = collectUniqueKeys(indexes);
+    }
+    return tableMap;
 }
 /** Compile a config glob — `*` is the only wildcard, everything else is literal. */
 function globToRegExp(pattern) {
@@ -174,6 +197,8 @@ export function applyExcludeColumns(tableMap, excludeColumns) {
             delete table.fields[field];
             delete table.colMap[field];
             table.generated = table.generated.filter((f) => f !== field);
+            // A key naming a column the API cannot write can never be an upsert key
+            table.uniqueKeys = table.uniqueKeys?.filter((key) => !key.includes(field));
             excluded.push(`${table.name}.${columnName}`);
         }
         if (Object.keys(table.fields).length === 0) {
@@ -183,7 +208,7 @@ export function applyExcludeColumns(tableMap, excludeColumns) {
     }
     return excluded;
 }
-export function generateSchemaFile(schemaName, tableName, fields, colMap, primary, generated, isView) {
+export function generateSchemaFile(schemaName, tableName, fields, colMap, primary, generated, isView, uniqueKeys) {
     const fieldsStr = JSON.stringify(fields, null, 2).replace(/"(.*?)"\s*:\s*"Type(.*?)"/g, '$1: Type$2');
     const colMapStr = JSON.stringify(colMap, null, 2);
     const primaryKeyLine = primary?.length ? `\n  primaryKey: ${JSON.stringify(primary)},` : '';
@@ -193,6 +218,9 @@ export function generateSchemaFile(schemaName, tableName, fields, colMap, primar
     // A view has no PRIMARY KEY constraint to introspect, so the table generator has to be told
     // it may not read the absence of one as "no key exists on this data".
     const isViewLine = isView ? `\n  isView: true,` : '';
+    // Emitted even when empty: `defineTable` refuses an upsert rule it cannot verify, and an
+    // absent property is what says "generated before unique keys were known" (ADR 0021).
+    const uniqueKeysLine = uniqueKeys ? `\n  uniqueKeys: ${JSON.stringify(uniqueKeys)},` : '';
     const usesNullable = Object.values(fields).some((t) => t.includes('Nullable('));
     const valueImports = usesNullable ? 'Type, Nullable' : 'Type';
     return `// Auto-generated by fastify-auto-sqlapi. Do not edit.
@@ -220,7 +248,7 @@ export const Schema = {
   fields: _Schema,
   validation,
   tableName: "${tableName}",
-  partialValidation,${primaryKeyLine}${generatedLine}${isViewLine}
+  partialValidation,${primaryKeyLine}${generatedLine}${isViewLine}${uniqueKeysLine}
 };
 export const ${schemaName} = Schema;
 export type TypeSchema = Static<typeof Schema.validation>;

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

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

package/dist/lib/db.js

@@ -4,6 +4,8 @@ import { getDialect } from './dialect.js';
 // PostgreSQL's hard limit of 65535 bind parameters per statement (≈ 130 columns × 500 rows).
 // Override per-call via the `chunkSize` argument when working with extremely wide tables.
 const DEFAULT_CHUNK_SIZE = 500;
+// Column tagging each row of an upsert key lookup with its record's position in the chunk
+const LOOKUP_POSITION = 'sqlapi_lookup_position';
 /** @deprecated Use db.qi() instead */
 export const escapeIdent = (f) => f.replace(/"/g, '""');
 export class QueryClient {
@@ -90,39 +92,34 @@ export class QueryClient {
     #q(fields) {
         return fields.map((f) => this.dialect.qi(f)).join(', ');
     }
+    // The SQL for one value: a raw Expression inline, anything else bound as the next placeholder
+    #bind(val, values) {
+        if (val instanceof Expression)
+            return val.value;
+        values.push(val);
+        return this.dialect.ph(values.length);
+    }
     // Appends record fields/values to a shared values array, auto-indexing placeholders
     #params(record, values) {
         const fields = [];
         const placeholders = [];
         for (const [field, val] of Object.entries(record)) {
             fields.push(field);
-            if (val instanceof Expression) {
-                placeholders.push(val.value);
-            }
-            else {
-                values.push(val);
-                placeholders.push(this.dialect.ph(values.length));
-            }
+            placeholders.push(this.#bind(val, values));
         }
         return { fields, placeholders };
     }
+    // Builds `col = placeholder` pairs joined by `separator` (', ' for SET, ' AND ' for WHERE)
+    #equalities(record, values, separator) {
+        const { fields, placeholders } = this.#params(record, values);
+        return fields.map((f, i) => `${this.dialect.qi(f)} = ${placeholders[i]}`).join(separator);
+    }
     // Builds multi-row VALUES string for bulk operations
     #bulkValues(fields, records) {
         const values = [];
         const rowPlaceholders = [];
         for (const record of records) {
-            const cols = [];
-            for (const field of fields) {
-                const val = record[field];
-                if (val instanceof Expression) {
-                    cols.push(val.value);
-                }
-                else {
-                    values.push(val);
-                    cols.push(this.dialect.ph(values.length));
-                }
-            }
-            rowPlaceholders.push(`(${cols.join(', ')})`);
+            rowPlaceholders.push(`(${fields.map((field) => this.#bind(record[field], values)).join(', ')})`);
         }
         return { values, rows: rowPlaceholders.join(', ') };
     }
@@ -170,30 +167,179 @@ export class QueryClient {
         return this.#extractPkRows(result, pkCol, [record])[0];
     }
     async insertOrUpdate(table, record, conflictKeys, pkCol) {
-        const values = [];
-        const { fields, placeholders } = this.#params(record, values);
-        if (!fields.length)
+        if (!Object.keys(record).length)
             throw new Error('Cannot execute empty insert');
-        const upsertClause = this.dialect.upsertSql(this.#q(conflictKeys), this.dialect.upsertUpdateSet(fields, conflictKeys));
-        const returning = this.dialect.returningPk(this.#quotedPkCols(pkCol));
+        const [pkRow] = await this.#bulkWrite(table, [record], pkCol, 1, { conflictKeys, keepAsIs: conflictKeys });
+        return pkRow;
+    }
+    /**
+     * Group records by their exact field set, keeping each record's input position. A bulk write
+     * is N single writes issued efficiently (ADR 0003), so every record writes only its own
+     * fields: records with different fields cannot share a statement, or a field missing from
+     * the statement is dropped and a field missing from the record is bound as NULL — which
+     * skips the column default on insert and overwrites the stored value on upsert.
+     */
+    #groupByFields(records) {
+        const groups = new Map();
+        records.forEach((record, i) => {
+            const fields = Object.keys(record);
+            const key = JSON.stringify([...fields].sort());
+            const group = groups.get(key);
+            if (group)
+                group.indexes.push(i);
+            else
+                groups.set(key, { fields, indexes: [i] });
+        });
+        return [...groups.values()];
+    }
+    /**
+     * Rows found by each record's key, keyed by the record's position. One statement for the
+     * whole chunk: a `UNION ALL` part per record, each row tagged with its position, so the order
+     * the database returns them in does not matter and value comparison stays the database's
+     * (types, collations). Records whose key holds a null are not looked up: NULL never matches.
+     */
+    async #findByKey(table, records, pkCol, keys) {
+        const found = new Map();
+        const values = [];
+        const position = this.dialect.qi(LOOKUP_POSITION);
+        const from = `${this.#quotedPkCols(pkCol)} FROM ${this.dialect.qi(table)}`;
+        const lookups = records.flatMap((record, i) => {
+            if (keys.some((k) => record[k] == null))
+                return [];
+            const where = this.#equalities(Object.fromEntries(keys.map((k) => [k, record[k]])), values, ' AND ');
+            return [`SELECT ${i} AS ${position}, ${from} WHERE ${where}`];
+        });
+        if (!lookups.length)
+            return found;
+        const result = await this.query(lookups.join(' UNION ALL '), values);
+        for (const { [LOOKUP_POSITION]: i, ...pk } of result.rows) {
+            found.set(Number(i), [...(found.get(Number(i)) ?? []), pk]);
+        }
+        for (const rows of found.values()) {
+            if (rows.length > 1) {
+                throw new Error(`An upsert key (${keys.join(', ')}) of "${table}" matches several rows: it is not unique ` +
+                    `in the database — nothing was written (ADR 0021)`);
+            }
+        }
+        return found;
+    }
+    /**
+     * PK rows for postgres upsert records that update nothing on conflict: `DO NOTHING` returns no
+     * row for an existing one. The record gives its PK when it holds every PK column; otherwise
+     * the row — inserted or untouched — is looked up by its conflict keys.
+     */
+    async #untouchedPkRows(table, records, pkCol, conflictKeys) {
+        const pkCols = Array.isArray(pkCol) ? pkCol : [pkCol];
+        const holdsPk = (record) => pkCols.every((c) => record[c] != null && !(record[c] instanceof Expression));
+        const found = await this.#findByKey(table, records.map((r) => (holdsPk(r) ? {} : r)), pkCol, conflictKeys);
+        return records.map((record, i) => {
+            if (holdsPk(record))
+                return Object.fromEntries(pkCols.map((c) => [c, record[c]]));
+            const [row] = found.get(i) ?? [];
+            if (!row) {
+                throw new Error(`Cannot resolve the primary key of an upserted "${table}" row: no row matches its conflict keys (${conflictKeys.join(', ')})`);
+            }
+            return row;
+        });
+    }
+    /**
+     * One multi-row INSERT for records sharing `fields`; `tail` is the upsert clause, if any.
+     * Returns the PK rows in the records' order.
+     */
+    async #insertRows(table, fields, records, pkCol, tail = '') {
+        const { values, rows } = this.#bulkValues(fields, records);
         const result = await this.query(`${this.#insertHead(table, fields)}
-       VALUES (${placeholders.join(', ')})
-       ${upsertClause}${returning}`, values);
-        return this.#extractPkRows(result, pkCol, [record])[0];
+       VALUES ${rows}
+       ${tail}${this.dialect.returningPk(this.#quotedPkCols(pkCol))}`, values);
+        return this.#extractPkRows(result, pkCol, records);
+    }
+    /**
+     * Update existing rows by their key in one statement: each column takes a `CASE` over the
+     * keys, and the WHERE names the same keys, so a row can only be reached through its own key.
+     * Every row must be matched: one deleted since it was read is an error, never a skipped write.
+     */
+    async #updateByKey(table, columns, records, keys) {
+        const values = [];
+        const match = (record) => `(${this.#equalities(Object.fromEntries(keys.map((k) => [k, record[k]])), values, ' AND ')})`;
+        const set = columns.map((col) => {
+            const cases = records.map((r) => `WHEN ${match(r)} THEN ${this.#bind(r[col], values)}`);
+            return `${this.dialect.qi(col)} = CASE ${cases.join(' ')} END`;
+        });
+        const where = records.map(match).join(' OR ');
+        const result = await this.query(`UPDATE ${this.dialect.qi(table)} SET ${set.join(', ')} WHERE ${where}`, values);
+        if (result.affectedRows !== records.length) {
+            throw new Error(`Upsert on "${table}": ${records.length - result.affectedRows} of ${records.length} rows ` +
+                `to update were not found — deleted after the upsert read them`);
+        }
+    }
+    /**
+     * Upsert by key for dialects whose upsert syntax names no conflict target (mysql/mariadb,
+     * ADR 0021): probe which keys exist, insert the rest, update the found rows by their key.
+     * Only the row the key names can be written — a collision on another unique index is an
+     * error, as it is on postgres. PKs come from the probe and from the insert.
+     */
+    async #upsertByKey(table, fields, records, pkCol, upsert) {
+        // A group missing a key field can only insert: nothing to probe
+        const found = upsert.conflictKeys.every((k) => fields.includes(k))
+            ? await this.#findByKey(table, records, pkCol, upsert.conflictKeys)
+            : new Map();
+        const pkRows = new Array(records.length);
+        const inserts = records.flatMap((_, i) => (found.has(i) ? [] : [i]));
+        if (inserts.length) {
+            const inserted = await this.#insertRows(table, fields, inserts.map((i) => records[i]), pkCol);
+            inserts.forEach((i, k) => { pkRows[i] = inserted[k]; });
+        }
+        const updates = [...found.keys()];
+        const columns = fields.filter((f) => !upsert.keepAsIs.includes(f));
+        if (updates.length && columns.length) {
+            await this.#updateByKey(table, columns, updates.map((i) => records[i]), upsert.conflictKeys);
+        }
+        for (const i of updates)
+            pkRows[i] = found.get(i)[0];
+        return pkRows;
+    }
+    /**
+     * One chunk of records sharing `fields`: a plain insert, or an upsert — `ON CONFLICT (key)`
+     * where the dialect has it, by key otherwise. PK rows in the records' order.
+     */
+    async #writeChunk(table, fields, records, pkCol, upsert) {
+        if (!upsert)
+            return this.#insertRows(table, fields, records, pkCol);
+        const onConflict = this.dialect.onConflict;
+        if (!onConflict)
+            return this.#upsertByKey(table, fields, records, pkCol, upsert);
+        const updateSet = onConflict.updateSet(fields, upsert.keepAsIs);
+        const pkRows = await this.#insertRows(table, fields, records, pkCol, onConflict.sql(this.#q(upsert.conflictKeys), updateSet));
+        // Nothing to update: `DO NOTHING` returns no row for an existing one. A group missing a key
+        // field can only insert, and RETURNING names every row it inserted.
+        if (!updateSet && upsert.conflictKeys.every((k) => fields.includes(k))) {
+            return this.#untouchedPkRows(table, records, pkCol, upsert.conflictKeys);
+        }
+        return pkRows;
+    }
+    /**
+     * Write `records`, one chunk at a time within each same-fields group (a single chunk when
+     * every record has the same fields). With `upsert`, an existing row gets the record's fields
+     * except `keepAsIs` — the conflict keys and the columns never overwritten. PK rows are
+     * returned in input order.
+     */
+    async #bulkWrite(table, records, pkCol, chunkSize, upsert) {
+        const results = new Array(records.length);
+        for (const { fields, indexes } of this.#groupByFields(records)) {
+            for (let i = 0; i < indexes.length; i += chunkSize) {
+                const chunkIndexes = indexes.slice(i, i + chunkSize);
+                const pkRows = await this.#writeChunk(table, fields, chunkIndexes.map((j) => records[j]), pkCol, upsert);
+                pkRows.forEach((row, k) => {
+                    results[chunkIndexes[k]] = row;
+                });
+            }
+        }
+        return results;
     }
     async bulkInsert(table, records, pkCol, chunkSize = DEFAULT_CHUNK_SIZE) {
         if (!records.length)
             return [];
-        const fields = Object.keys(records[0]);
-        const returning = this.dialect.returningPk(this.#quotedPkCols(pkCol));
-        const results = [];
-        for (let i = 0; i < records.length; i += chunkSize) {
-            const chunk = records.slice(i, i + chunkSize);
-            const { values, rows } = this.#bulkValues(fields, chunk);
-            const result = await this.query(`${this.#insertHead(table, fields)} VALUES ${rows}${returning}`, values);
-            results.push(...this.#extractPkRows(result, pkCol, chunk));
-        }
-        return results;
+        return this.#bulkWrite(table, records, pkCol, chunkSize);
     }
     /**
      * `immutableCols` are written when the row is inserted but left untouched when the statement
@@ -203,34 +349,18 @@ export class QueryClient {
     async bulkInsertOrUpdate(table, records, conflictKeys, pkCol, chunkSize = DEFAULT_CHUNK_SIZE, immutableCols = []) {
         if (!records.length)
             return [];
-        const fields = Object.keys(records[0]);
         const keepAsIs = immutableCols.length ? [...conflictKeys, ...immutableCols] : conflictKeys;
-        const upsertClause = this.dialect.upsertSql(this.#q(conflictKeys), this.dialect.upsertUpdateSet(fields, keepAsIs));
-        const returning = this.dialect.returningPk(this.#quotedPkCols(pkCol));
-        const results = [];
-        for (let i = 0; i < records.length; i += chunkSize) {
-            const chunk = records.slice(i, i + chunkSize);
-            const { values, rows } = this.#bulkValues(fields, chunk);
-            const result = await this.query(`${this.#insertHead(table, fields)}
-         VALUES ${rows}
-         ${upsertClause}${returning}`, values);
-            results.push(...this.#extractPkRows(result, pkCol, chunk));
-        }
-        return results;
+        return this.#bulkWrite(table, records, pkCol, chunkSize, { conflictKeys, keepAsIs });
     }
     async update(table, record, where, extraCondition) {
         const values = [];
-        const { fields: setF, placeholders: setP } = this.#params(record, values);
-        const { fields: whereF, placeholders: whereP } = this.#params(where, values);
+        const setClause = this.#equalities(record, values, ', ');
+        const whereClause = this.#equalities(where, values, ' AND ');
         let extraWhere = '';
         if (extraCondition) {
             extraWhere = ` AND ${extraCondition.build(values.length + 1, this.dialect.ph)}`;
             values.push(...extraCondition.getValues());
         }
-        const setClause = setF.map((f, i) => `${this.dialect.qi(f)} = ${setP[i]}`).join(', ');
-        const whereClause = whereF
-            .map((f, i) => `${this.dialect.qi(f)} = ${whereP[i]}`)
-            .join(' AND ');
         const result = await this.query(`UPDATE ${this.dialect.qi(table)}
        SET ${setClause}
        WHERE ${whereClause}${extraWhere}`, values);
@@ -238,15 +368,12 @@ export class QueryClient {
     }
     async delete(table, where, extraCondition) {
         const values = [];
-        const { fields, placeholders } = this.#params(where, values);
+        const whereClause = this.#equalities(where, values, ' AND ');
         let extraWhere = '';
         if (extraCondition) {
             extraWhere = ` AND ${extraCondition.build(values.length + 1, this.dialect.ph)}`;
             values.push(...extraCondition.getValues());
         }
-        const whereClause = fields
-            .map((f, i) => `${this.dialect.qi(f)} = ${placeholders[i]}`)
-            .join(' AND ');
         const result = await this.query(`DELETE FROM ${this.dialect.qi(table)}
        WHERE ${whereClause}${extraWhere}`, values);
         return result.affectedRows;

package/dist/lib/dialect.d.ts

@@ -9,18 +9,23 @@ export interface SqlDialect {
     /** ConditionBuilder dialect name */
     cbDialect: 'postgres' | 'mysql';
     supportsReturning: boolean;
-    /** ON CONFLICT / ON DUPLICATE KEY syntax */
-    upsertSql(quotedConflictKeys: string, quotedUpdateSet: string): string;
-    /** RETURNING pk_col suffix or empty string */
-    returningPk(quotedPkCol: string): string;
     /**
-     * Build the SET body for an upsert: the column list (separated by ', ') that the dialect
-     * uses to copy "incoming row" values into a conflicting row.
-     * - postgres: `"col" = EXCLUDED."col"`
-     * - mysql/mariadb: `` `col` = VALUES(`col`) ``
-     * Returns '' when there is nothing to update (i.e. all `fields` are conflict keys).
+     * The upsert clause of a dialect whose syntax names its conflict target — postgres
+     * `ON CONFLICT (key)`, which matches exactly the declared key. Absent on mysql/mariadb:
+     * `ON DUPLICATE KEY UPDATE` fires on ANY unique index, so there the QueryClient upserts by
+     * key explicitly — probe, insert, update (ADR 0021).
      */
-    upsertUpdateSet(fields: string[], conflictKeys: string[]): string;
+    onConflict?: {
+        /** `ON CONFLICT (keys) DO UPDATE SET …`, or `DO NOTHING` when the update set is empty. */
+        sql(quotedConflictKeys: string, quotedUpdateSet: string): string;
+        /**
+         * The SET body copying the incoming row into the conflicting one (`"col" = EXCLUDED."col"`)
+         * for every field not in `keepAsIs`; '' when nothing is left to update.
+         */
+        updateSet(fields: string[], keepAsIs: string[]): string;
+    };
+    /** RETURNING pk_col suffix or empty string */
+    returningPk(quotedPkCol: string): string;
     /**
      * Truncate a timestamp/date column to the start of the given unit and
      * return it as an ISO-style string. The output is always a STRING:

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

@@ -1 +1 @@
-{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../../src/lib/dialect.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,KAAK,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,gEAAgE;IAChE,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,sDAAsD;IACtD,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,oCAAoC;IACpC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC;IAChC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4CAA4C;IAC5C,SAAS,CAAC,kBAAkB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;IACvE,8CAA8C;IAC9C,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC;;;;;;OAMG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAClE;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7D;AAqFD,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAIxD"}
+{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../../src/lib/dialect.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,KAAK,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,gEAAgE;IAChE,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,sDAAsD;IACtD,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,oCAAoC;IACpC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC;IAChC,iBAAiB,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE;QACX,0FAA0F;QAC1F,GAAG,CAAC,kBAAkB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;QACjE;;;WAGG;QACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;KACzD,CAAC;IACF,8CAA8C;IAC9C,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7D;AAsED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAIxD"}

package/dist/lib/dialect.js

@@ -1,19 +1,20 @@
+const pgQi = (id) => `"${id.replace(/"/g, '""')}"`;
 const PostgresDialect = {
     name: 'postgres',
-    qi: (id) => `"${id.replace(/"/g, '""')}"`,
+    qi: pgQi,
     ph: (i) => `$${i}`,
     cbDialect: 'postgres',
     supportsReturning: true,
-    upsertSql(quotedConflictKeys, quotedUpdateSet) {
-        if (!quotedUpdateSet)
-            return `ON CONFLICT (${quotedConflictKeys}) DO NOTHING`;
-        return `ON CONFLICT (${quotedConflictKeys}) DO UPDATE SET ${quotedUpdateSet}`;
-    },
-    upsertUpdateSet(fields, conflictKeys) {
-        const updateCols = fields.filter((f) => !conflictKeys.includes(f));
-        if (!updateCols.length)
-            return '';
-        return updateCols.map((f) => `${this.qi(f)} = EXCLUDED.${this.qi(f)}`).join(', ');
+    onConflict: {
+        sql(quotedConflictKeys, quotedUpdateSet) {
+            if (!quotedUpdateSet)
+                return `ON CONFLICT (${quotedConflictKeys}) DO NOTHING`;
+            return `ON CONFLICT (${quotedConflictKeys}) DO UPDATE SET ${quotedUpdateSet}`;
+        },
+        updateSet(fields, keepAsIs) {
+            const updateCols = fields.filter((f) => !keepAsIs.includes(f));
+            return updateCols.map((f) => `${pgQi(f)} = EXCLUDED.${pgQi(f)}`).join(', ');
+        },
     },
     returningPk(quotedPkCol) {
         return ` RETURNING ${quotedPkCol}`;
@@ -33,26 +34,12 @@ function mysqlDateTrunc(unit, col) {
         case 'hour': return `DATE_FORMAT(${col}, '%Y-%m-%dT%H:00:00')`;
     }
 }
-function mysqlUpsertUpdateSet(fields, conflictKeys) {
-    const updateCols = fields.filter((f) => !conflictKeys.includes(f));
-    if (!updateCols.length)
-        return '';
-    return updateCols.map((f) => `${this.qi(f)} = VALUES(${this.qi(f)})`).join(', ');
-}
 const MysqlDialect = {
     name: 'mysql',
     qi: (id) => `\`${id.replace(/`/g, '``')}\``,
     ph: () => '?',
     cbDialect: 'mysql',
     supportsReturning: false,
-    upsertSql(_quotedConflictKeys, quotedUpdateSet) {
-        // MySQL requires at least one assignment in ON DUPLICATE KEY UPDATE; when there's nothing
-        // user-meaningful to update, assign the first conflict key to itself (no-op).
-        if (!quotedUpdateSet)
-            return `ON DUPLICATE KEY UPDATE ${_quotedConflictKeys.split(', ')[0]} = ${_quotedConflictKeys.split(', ')[0]}`;
-        return `ON DUPLICATE KEY UPDATE ${quotedUpdateSet}`;
-    },
-    upsertUpdateSet: mysqlUpsertUpdateSet,
     returningPk() {
         return '';
     },
@@ -64,12 +51,6 @@ const MariadbDialect = {
     ph: () => '?',
     cbDialect: 'mysql',
     supportsReturning: true,
-    upsertSql(_quotedConflictKeys, quotedUpdateSet) {
-        if (!quotedUpdateSet)
-            return `ON DUPLICATE KEY UPDATE ${_quotedConflictKeys.split(', ')[0]} = ${_quotedConflictKeys.split(', ')[0]}`;
-        return `ON DUPLICATE KEY UPDATE ${quotedUpdateSet}`;
-    },
-    upsertUpdateSet: mysqlUpsertUpdateSet,
     returningPk(quotedPkCol) {
         return ` RETURNING ${quotedPkCol}`;
     },

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":"AASA,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AA+D3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0C5F"}
+{"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AAgE3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0C5F"}

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

@@ -1,5 +1,5 @@
 import { camelcaseObject } from '../../naming.js';
-import { processSecondaries, processDeletions, prepareInsertRecord } from '../write-helpers.js';
+import { processSecondaries, processDeletions, prepareInsertRecord, assertUpsertKeys, } from '../write-helpers.js';
 import { enforceTenantOnWrites, assertTenantOwnsConflicts, tenantImmutableColumns, } from '../../tenant.js';
 import { runBulkValidation } from '../validate.js';
 import { primaryAsCols } from '../../../types.js';
@@ -12,6 +12,7 @@ function upsertMains(params, preparedMains, pkCol) {
         return db.bulkInsert(schema.tableName, preparedMains, pkCol);
     }
     const conflictCols = upsertKeys.map((k) => schema.col(k));
+    assertUpsertKeys(schema, conflictCols, [pkCol].flat(), preparedMains);
     // Tenant isolation: a conflicting upsert must not overwrite rows owned by another tenant, nor
     // re-assign the owner of a row it legitimately updates.
     return assertTenantOwnsConflicts(db, tenant, schema.tableName, conflictCols, preparedMains)

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,EAEb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAmE9E"}
+{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/insert.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAoE9E"}

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

@@ -1,5 +1,5 @@
 import { camelcaseObject } from '../../naming.js';
-import { processSecondaries, prepareInsertRecord } from '../write-helpers.js';
+import { processSecondaries, prepareInsertRecord, assertUpsertKeys } from '../write-helpers.js';
 import { enforceTenantOnWrites, assertTenantOwnsConflicts } from '../../tenant.js';
 import { primaryAsCols } from '../../../types.js';
 export async function insertEngine(params) {
@@ -20,6 +20,7 @@ export async function insertEngine(params) {
         const upsertKeys = tableConf.upsertMap?.get(schema);
         if (upsertKeys) {
             const conflictCols = upsertKeys.map((k) => schema.col(k));
+            assertUpsertKeys(schema, conflictCols, [pkCol].flat(), [mainRecord]);
             // Tenant isolation: a conflicting upsert must not overwrite a row owned by another tenant.
             await assertTenantOwnsConflicts(tx, tenant, schema.tableName, conflictCols, [mainRecord]);
             pkResult = await tx.insertOrUpdate(schema.tableName, mainRecord, conflictCols, pkCol);

package/dist/lib/engine/search/aggregations.d.ts

@@ -11,9 +11,16 @@ import { Expression } from 'node-condition-builder';
 import type { QueryClient } from '../../db.js';
 import type { QueryParams } from '../query-params.js';
 import type { DbTables, ITable, JoinGroupRequest, SearchCondition, TenantContext } from '../../../types.js';
+/**
+ * One aggregation function, as SQL. `zeroWhenEmpty`: over no rows it means 0 (nothing counted,
+ * nothing summed), so the correlated subquery coalesces its NULL to 0. min/max/avg over no rows
+ * have no value and stay NULL — a 0 would be invented data on numeric columns and a type error
+ * on text/date ones.
+ */
 export interface AggFn {
     sql: string;
     distinct: boolean;
+    zeroWhenEmpty: boolean;
 }
 export declare const AGG_FN: Record<string, AggFn>;
 export declare function aggExpr(fn: AggFn, qualifiedCol: string): string;

package/dist/lib/engine/search/aggregations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAoB,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD,OAAO,KAAK,EACV,QAAQ,EACR,MAAM,EACN,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,KAAK;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE;AAEzD,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAOxC,CAAC;AAEF,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,UAAU,CAgEZ;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,eAAe,EAAE,EAC7B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,MAAM,CAyBR"}
+{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/aggregations.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAoB,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD,OAAO,KAAK,EACV,QAAQ,EACR,MAAM,EACN,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,aAAa,EAAE,OAAO,CAAA;CAAE;AAEjF,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAOxC,CAAC;AAEF,wBAAgB,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,UAAU,CAiEZ;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,eAAe,EAAE,EAC7B,EAAE,EAAE,WAAW,EACf,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,EACvD,MAAM,CAAC,EAAE,aAAa,GACrB,MAAM,CAyBR"}

package/dist/lib/engine/search/aggregations.js

@@ -14,12 +14,12 @@ import { err400, validateSchemaField } from './fields.js';
 import { requireJoin, extractJoinRefs, subqueryAlias } from './joins.js';
 import { buildJoinRefCondition, dispatchConditionMethod } from './conditions.js';
 export const AGG_FN = {
-    sum: { sql: 'SUM', distinct: false },
-    min: { sql: 'MIN', distinct: false },
-    max: { sql: 'MAX', distinct: false },
-    avg: { sql: 'AVG', distinct: false },
-    count: { sql: 'COUNT', distinct: false },
-    distinctCount: { sql: 'COUNT', distinct: true },
+    sum: { sql: 'SUM', distinct: false, zeroWhenEmpty: true },
+    min: { sql: 'MIN', distinct: false, zeroWhenEmpty: false },
+    max: { sql: 'MAX', distinct: false, zeroWhenEmpty: false },
+    avg: { sql: 'AVG', distinct: false, zeroWhenEmpty: false },
+    count: { sql: 'COUNT', distinct: false, zeroWhenEmpty: true },
+    distinctCount: { sql: 'COUNT', distinct: true, zeroWhenEmpty: true },
 };
 export function aggExpr(fn, qualifiedCol) {
     return fn.distinct ? `COUNT(DISTINCT ${qualifiedCol})` : `${fn.sql}(${qualifiedCol})`;
@@ -81,7 +81,8 @@ export function buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joi
         }
     }
     const qualifiedCol = `${subRef}.${db.qi(fieldCol)}`;
-    const expr = `COALESCE((SELECT ${aggExpr(aggFn, qualifiedCol)} FROM ${refs.joinTable} AS ${subRef} WHERE ${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${tenantWhere}${filterWhere}), 0)`;
+    const subquery = `(SELECT ${aggExpr(aggFn, qualifiedCol)} FROM ${refs.joinTable} AS ${subRef} WHERE ${subRef}.${refs.fkCol} = ${refs.mainTable}.${refs.mainCol}${tenantWhere}${filterWhere})`;
+    const expr = aggFn.zeroWhenEmpty ? `COALESCE(${subquery}, 0)` : subquery;
     return new Expression(expr, [...tenantVals, ...filterVals]);
 }
 /** HAVING-style conditions: the dotted `<alias>.<fn>.<field>` entries of `conditions`. */