@dwtechs/antity-pgsql 0.13.0 → 0.14.0

package/README.md

@@ -190,6 +190,8 @@ class SQLEntity {
   get addOneSubstack(): SubstackTuple;
   get updateArraySubstack(): SubstackTuple;
   get updateOneSubstack(): SubstackTuple;
+  get upsertArraySubstack(): SubstackTuple;
+  get upsertOneSubstack(): SubstackTuple;
 
   query: {
     select: (
@@ -223,6 +225,15 @@ class SQLEntity {
         query: string;
           args: unknown[];
       };
+    upsert: (
+      rows: Record<string, unknown>[],
+      conflictTarget: string | string[],
+      consumerId?: number | string,
+      consumerName?: string,
+      rtn?: string) => {
+        query: string;
+        args: unknown[];
+      };
     delete: (ids: number[]) => {
       query: string;
       args: number[];
@@ -233,6 +244,7 @@ class SQLEntity {
   get: (req: Request, res: Response, next: NextFunction) => void;
   add: (req: Request, res: Response, next: NextFunction) => Promise<void>;
   update: (req: Request, res: Response, next: NextFunction) => Promise<void>;
+  upsert: (req: Request, res: Response, next: NextFunction) => Promise<void>;
   archive: (req: Request, res: Response, next: NextFunction) => Promise<void>;
   delete: (req: Request, res: Response, next: NextFunction) => Promise<void>;
   deleteArchive: (req: Request, res: Response, next: NextFunction) => void;
@@ -259,9 +271,11 @@ function execute(
 
 ### Middleware Methods for Express.js
 
-get(), add(), update(), archive(), delete(), deleteArchive() and getHistory() methods are made to be used as Express.js middlewares.
+get(), add(), update(), upsert(), archive(), delete(), deleteArchive() and getHistory() methods are made to be used as Express.js middlewares.
 Each method will look for data to work on in the **req.body.rows** parameter.
 
+The upsert() method additionally requires **req.body.conflictTarget** to specify which column(s) define uniqueness.
+
 ### Schema Qualification
 
 All SQL queries generated by Antity-pgsql use schema-qualified table names (e.g., `schema.table`). This provides:
@@ -279,17 +293,123 @@ Substacks are pre-composed middleware chains that combine normalization, validat
 - **addOneSubstack**: Combines `normalizeOne`, `validateOne`, and `add`. Use this for POST routes with `req.body` containing a single object.
 - **updateArraySubstack**: Combines `normalizeArray`, `validateArray`, and `update`. Use this for PUT routes with `req.body.rows` containing multiple objects.
 - **updateOneSubstack**: Combines `normalizeOne`, `validateOne`, and `update`. Use this for PUT routes with `req.body` containing a single object.
+- **upsertArraySubstack**: Combines `normalizeArray`, `validateArray`, and `upsert`. Use this for upsert routes with `req.body.rows` containing multiple objects. Requires `req.body.conflictTarget`.
+- **upsertOneSubstack**: Combines `normalizeOne`, `validateOne`, and `upsert`. Use this for upsert routes with `req.body` containing a single object. Requires `req.body.conflictTarget`.
 
 Using substacks simplifies your route definitions and ensures consistent data processing.
 
 ### Query Methods
 
 - **query.select()**: Generates a SELECT query. When the `rows` parameter is provided (not null), pagination is automatically enabled and the query includes `COUNT(*) OVER () AS total` to return the total number of rows. The total count is extracted from results and returned separately from the row data.
+- **query.insert()**: Generates an INSERT query. Accepts an array of objects with properties matching the entity definition. Optionally appends `consumerId` and `consumerName` for history tracking. Supports `RETURNING` clause via the `rtn` parameter.
+- **query.update()**: Generates an UPDATE query using CASE statements. Accepts an array of objects with `id` property. Optionally appends `consumerId` and `consumerName` for history tracking.
+- **query.upsert()**: Generates an INSERT ... ON CONFLICT ... DO UPDATE query. Accepts an array of objects and a `conflictTarget` (single column name or array of column names) that defines uniqueness. If a conflict occurs on the specified column(s), the row is updated; otherwise, it is inserted. Properties are automatically included if they have both INSERT and UPDATE operations. Optionally appends `consumerId` and `consumerName` for history tracking. Supports `RETURNING` clause via the `rtn` parameter.
 - **query.archive()**: Generates a simplified `UPDATE ... SET archived = true WHERE id IN (...)` query. Accepts an array of objects with `id` property. Optionally appends `consumerId` and `consumerName` for history tracking. Does not require an `archived` field in the rows — it is set directly in the SQL.
 - **delete()**: Deletes rows by their IDs. Expects `req.body.rows` to be an array of objects with `id` property: `[{id: 1}, {id: 2}]`
 - **deleteArchive()**: Deletes archived rows that were archived before a specific date using a PostgreSQL SECURITY DEFINER function. Expects `req.body.date` to be a Date object.
 - **getHistory()**: Retrieves modification history for rows from the `log.history` table. Expects `req.body.rows` to be an array of objects with `id` property. Returns all historical records for the specified entity IDs.
 
+### Upsert (Insert or Update)
+
+The upsert functionality uses PostgreSQL's `INSERT ... ON CONFLICT ... DO UPDATE` syntax to insert rows or update them if they already exist based on a unique constraint.
+
+#### How It Works
+
+1. **Conflict Target**: You specify which column(s) define uniqueness (e.g., `'id'`, `'email'`, or `['name', 'email']`)
+2. **Property Selection**: Properties are automatically included if they have **both** `INSERT` and `UPDATE` in their `operations` array
+3. **On Conflict**: When a conflict occurs, all columns except the conflict target are updated
+
+#### Usage Examples
+
+**Using the middleware with a single conflict target:**
+
+```javascript
+// Route definition
+router.post('/users/upsert', ...entity.upsertArraySubstack);
+
+// Request body
+{
+  rows: [
+    { id: 1, name: 'John Updated', email: 'john@example.com' },
+    { name: 'Jane New', email: 'jane@example.com' }
+  ],
+  conflictTarget: 'id'
+}
+```
+
+**Using email as conflict target:**
+
+```javascript
+// If a user with this email exists, update their name; otherwise, insert
+{
+  rows: [
+    { name: 'John', email: 'john@example.com', age: 30 }
+  ],
+  conflictTarget: 'email'
+}
+```
+
+**Using multiple columns as conflict target:**
+
+```javascript
+// Unique constraint on combination of name and email
+{
+  rows: [
+    { name: 'John', email: 'john@example.com', age: 30 }
+  ],
+  conflictTarget: ['name', 'email']
+}
+```
+
+**Using the query generator directly:**
+
+```javascript
+const { query, args } = entity.query.upsert(
+  [{ id: 1, name: 'John', email: 'john@example.com' }],
+  'id',
+  1, // consumerId (optional)
+  'admin', // consumerName (optional)
+  'RETURNING id' // return clause (optional)
+);
+// Generates:
+// INSERT INTO public.users (name, email, "consumerId", "consumerName")
+// VALUES ($1, $2, $3, $4)
+// ON CONFLICT (id) DO UPDATE SET 
+//   name = EXCLUDED.name,
+//   email = EXCLUDED.email,
+//   "consumerId" = EXCLUDED."consumerId",
+//   "consumerName" = EXCLUDED."consumerName"
+// RETURNING id
+```
+
+#### Property Configuration for Upsert
+
+Properties are automatically included in upsert if they have both INSERT and UPDATE operations:
+
+```javascript
+{
+  key: 'name',
+  operations: ['SELECT', 'INSERT', 'UPDATE'] // Included in upsert
+}
+
+{
+  key: 'id',
+  operations: ['SELECT', 'UPDATE'] // NOT included (no INSERT)
+}
+
+{
+  key: 'createdAt',
+  operations: ['SELECT', 'INSERT'] // NOT included (no UPDATE)
+}
+```
+
+#### Important Notes
+
+- **Conflict Target Required**: The `conflictTarget` parameter must specify an existing unique constraint or primary key
+- **Mixed Rows**: You can upsert rows with and without IDs in the same request if your conflict target handles it (e.g., using `SERIAL` primary key)
+- **Atomic Operation**: Unlike separate insert/update calls, upsert is a single atomic database operation
+- **Concurrent Safety**: Prevents race conditions when multiple requests try to create the same record
+
 ### Filters
 
 Filters support two formats for maximum flexibility:

package/dist/antity-pgsql.d.ts

@@ -98,6 +98,7 @@ export declare class SQLEntity extends Entity {
   private sel: unknown;
   private ins: unknown;
   private upd: unknown;
+  private ups: unknown;
   private arc: unknown;
   
   constructor(name: string, properties: Property[], schema?: string);
@@ -114,6 +115,8 @@ export declare class SQLEntity extends Entity {
   get addOneSubstack(): SubstackTuple;
   get updateArraySubstack(): SubstackTuple;
   get updateOneSubstack(): SubstackTuple;
+  get upsertArraySubstack(): SubstackTuple;
+  get upsertOneSubstack(): SubstackTuple;
   
   query: {
     select: (
@@ -155,6 +158,17 @@ export declare class SQLEntity extends Entity {
       args: unknown[];
     };
     
+    upsert: (
+      rows: Record<string, unknown>[],
+      conflictTarget: string | string[],
+      consumerId?: number | string,
+      consumerName?: string,
+      rtn?: string
+    ) => {
+      query: string;
+      args: unknown[];
+    };
+    
     delete: (ids: number[]) => {
       query: string;
       args: number[];
@@ -168,6 +182,7 @@ export declare class SQLEntity extends Entity {
   get(req: Request, res: Response, next: NextFunction): void;
   add(req: Request, res: Response, next: NextFunction): Promise<void>;
   update(req: Request, res: Response, next: NextFunction): Promise<void>;
+  upsert(req: Request, res: Response, next: NextFunction): Promise<void>;
   archive(req: Request, res: Response, next: NextFunction): Promise<void>;
   delete(req: Request, res: Response, next: NextFunction): Promise<void>;
   deleteArchive(req: Request, res: Response, next: NextFunction): void;

package/dist/antity-pgsql.js

@@ -372,6 +372,75 @@ class Update {
     }
 }
 
+class Upsert {
+    constructor() {
+        this._props = [];
+        this._quotedProps = [];
+        this._nbProps = 0;
+        this._cols = "";
+    }
+    addProp(prop) {
+        this._props.push(prop);
+        this._quotedProps.push(quoteIfUppercase(prop));
+        this._nbProps++;
+        this._cols = this._quotedProps.join(", ");
+    }
+    query(schema, table, rows, conflictTarget, consumerId, consumerName, rtn = "") {
+        if (!conflictTarget ||
+            (Array.isArray(conflictTarget) && conflictTarget.length === 0) ||
+            (typeof conflictTarget === 'string' && conflictTarget.trim() === '')) {
+            throw new Error('conflictTarget must be provided for upsert operation');
+        }
+        const propsToUse = [...this._props];
+        const quotedPropsToUse = [...this._quotedProps];
+        let nbProps = this._nbProps;
+        let cols = this._cols;
+        if (consumerId !== undefined && consumerName !== undefined) {
+            propsToUse.push("consumerId", "consumerName");
+            quotedPropsToUse.push(`"consumerId"`, `"consumerName"`);
+            nbProps += 2;
+            cols += `, "consumerId", "consumerName"`;
+        }
+        const conflictColumns = Array.isArray(conflictTarget)
+            ? conflictTarget.map(col => quoteIfUppercase(col)).join(", ")
+            : quoteIfUppercase(conflictTarget);
+        let query = `INSERT INTO ${quoteIfUppercase(schema)}.${quoteIfUppercase(table)} (${cols}) VALUES `;
+        const args = [];
+        let i = 0;
+        for (const row of rows) {
+            if (consumerId !== undefined && consumerName !== undefined) {
+                row.consumerId = consumerId;
+                row.consumerName = consumerName;
+            }
+            query += `${$i(nbProps, i)}, `;
+            for (const prop of propsToUse) {
+                args.push(row[prop]);
+            }
+            i += nbProps;
+        }
+        query = query.slice(0, -2);
+        query += ` ON CONFLICT (${conflictColumns}) DO UPDATE SET `;
+        const conflictTargetArray = Array.isArray(conflictTarget) ? conflictTarget : [conflictTarget];
+        const updateCols = quotedPropsToUse.filter((_, idx) => {
+            const propName = propsToUse[idx];
+            return !conflictTargetArray.includes(propName);
+        });
+        for (const col of updateCols) {
+            query += `${col} = EXCLUDED.${col}, `;
+        }
+        query = query.slice(0, -2);
+        if (rtn)
+            query += ` ${rtn}`;
+        return { query, args };
+    }
+    rtn(prop) {
+        return `RETURNING ${quoteIfUppercase(prop)}`;
+    }
+    execute(query, args, client) {
+        return execute(query, args, client);
+    }
+}
+
 var __awaiter$2 = (undefined && undefined.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -613,6 +682,7 @@ class SQLEntity extends Entity {
         this.sel = new Select();
         this.ins = new Insert();
         this.upd = new Update();
+        this.ups = new Upsert();
         this.arc = new Archive();
         this.query = {
             select: (first = 0, rows = null, sortField = null, sortOrder = null, filters = null) => {
@@ -624,6 +694,9 @@ class SQLEntity extends Entity {
             insert: (rows, consumerId, consumerName, rtn = "") => {
                 return this.ins.query(this.schema, this.table, rows, consumerId, consumerName, rtn);
             },
+            upsert: (rows, conflictTarget, consumerId, consumerName, rtn = "") => {
+                return this.ups.query(this.schema, this.table, rows, conflictTarget, consumerId, consumerName, rtn);
+            },
             delete: (ids) => {
                 return queryById(this.schema, this.table, ids);
             },
@@ -706,6 +779,39 @@ class SQLEntity extends Entity {
             l.rows = r;
             next();
         });
+        this.upsert = (req, res, next) => __awaiter(this, void 0, void 0, function* () {
+            const l = res.locals;
+            const rows = req.body.rows;
+            const conflictTarget = req.body.conflictTarget;
+            const dbClient = l.dbClient || null;
+            const cId = l.consumerId;
+            const cName = l.consumerName;
+            if (!conflictTarget) {
+                return next({ status: 400, msg: "Missing conflictTarget for upsert operation" });
+            }
+            if (!rows || !Array.isArray(rows) || rows.length === 0) {
+                return next({ status: 400, msg: "Missing or empty rows array for upsert operation" });
+            }
+            log.debug(`${LOGS_PREFIX}upsert(rows=${rows.length}, conflictTarget=${conflictTarget}, consumerId=${cId})`);
+            const rtn = this.ups.rtn("id");
+            const chunks = chunk(rows);
+            for (const c of chunks) {
+                const { query, args } = this.ups.query(this._schema, this._table, c, conflictTarget, cId, cName, rtn);
+                let db;
+                try {
+                    db = yield execute(query, args, dbClient);
+                }
+                catch (err) {
+                    return next(err);
+                }
+                const r = db.rows;
+                for (let i = 0; i < c.length; i++) {
+                    c[i].id = r[i].id;
+                }
+            }
+            l.rows = flatten(chunks);
+            next();
+        });
         this.archive = (req, res, next) => __awaiter(this, void 0, void 0, function* () {
             const l = res.locals;
             let r = req.body.rows;
@@ -813,7 +919,15 @@ class SQLEntity extends Entity {
     get updateOneSubstack() {
         return [this.normalizeOne, this.validateOne, this.update];
     }
+    get upsertArraySubstack() {
+        return [this.normalizeArray, this.validateArray, this.upsert];
+    }
+    get upsertOneSubstack() {
+        return [this.normalizeOne, this.validateOne, this.upsert];
+    }
     mapProps(operations, key) {
+        let hasInsert = false;
+        let hasUpdate = false;
         for (const o of operations) {
             switch (o) {
                 case "SELECT":
@@ -821,12 +935,17 @@ class SQLEntity extends Entity {
                     break;
                 case "UPDATE":
                     this.upd.addProp(key);
+                    hasUpdate = true;
                     break;
                 case "INSERT":
                     this.ins.addProp(key);
+                    hasInsert = true;
                     break;
             }
         }
+        if (hasInsert && hasUpdate) {
+            this.ups.addProp(key);
+        }
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dwtechs/antity-pgsql",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Open source library to add PostgreSQL support to @dwtechs/Antity entities.",
   "keywords": [
     "entities"