@restura/core 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -1070,6 +1070,20 @@ declare abstract class SqlEngine {
     protected abstract generateOrderBy(req: RsRequest<unknown>, routeData: StandardRouteData): string;
     protected abstract generateWhereClause(req: RsRequest<unknown>, where: WhereData[], routeData: StandardRouteData, sqlParams: string[]): string;
     protected replaceParamKeywords(value: string | number, routeData: RouteData, req: RsRequest<unknown>, sqlParams: string[]): string | number;
+    /**
+     * Replaces local parameter keywords (e.g., $paramName) in SQL query strings with '?' placeholders
+     * and adds the corresponding parameter values to the sqlParams array for parameterized queries.
+     *
+     * Validates that each parameter keyword exists in the route's request schema before processing.
+     * If the value is not a string or routeData has no request schema, returns the value unchanged.
+     *
+     * @param value - The string or number value that may contain parameter keywords (e.g., "$userId")
+     * @param routeData - The route data containing the request schema for parameter validation
+     * @param req - The request object containing the actual parameter values in req.data
+     * @param sqlParams - Array to which parameter values are appended (modified by reference)
+     * @returns The value with parameter keywords replaced by '?' placeholders, or the original value if unchanged
+     * @throws {RsError} If a parameter keyword is found that doesn't exist in the route's request schema
+     */
     protected replaceLocalParamKeywords(value: string | number, routeData: RouteData, req: RsRequest<unknown>, sqlParams: string[]): string | number;
     protected replaceGlobalParamKeywords(value: string | number, routeData: RouteData, req: RsRequest<unknown>, sqlParams: string[]): string | number;
     abstract generateDatabaseSchemaFromSchema(schema: ResturaSchema): string;
@@ -1102,6 +1116,16 @@ declare class PsqlEngine extends SqlEngine {
     protected createNestedSelect(req: RsRequest<unknown>, schema: ResturaSchema, item: ResponseData, routeData: StandardRouteData, sqlParams: string[]): string;
     protected executeCreateRequest(req: RsRequest<unknown>, routeData: StandardRouteData, schema: ResturaSchema): Promise<DynamicObject>;
     protected executeGetRequest(req: RsRequest<unknown>, routeData: StandardRouteData, schema: ResturaSchema): Promise<DynamicObject | any[]>;
+    /**
+     * Executes an update request. The request will pull out the id and baseSyncVersion from the request body.
+     * (If Present) The baseSyncVersion is used to check if the record has been modified since the last sync.
+     * If the update fails because the baseSyncVersion has changed, a conflict error will be thrown.
+     * IDs can not be updated using this method.
+     * @param req - The request object.
+     * @param routeData - The route data object.
+     * @param schema - The schema object.
+     * @returns The response object.
+     */
     protected executeUpdateRequest(req: RsRequest<unknown>, routeData: StandardRouteData, schema: ResturaSchema): Promise<DynamicObject>;
     protected executeDeleteRequest(req: RsRequest<unknown>, routeData: StandardRouteData, schema: ResturaSchema): Promise<boolean>;
     protected generateJoinStatements(req: RsRequest<unknown>, joins: JoinData[], baseTable: string, routeData: StandardRouteData | CustomRouteData, schema: ResturaSchema, sqlParams: string[]): string;
@@ -1157,9 +1181,10 @@ declare function insertObjectQuery(table: string, obj: DynamicObject): string;
  * @param table Table name to update the object in
  * @param obj Data to update in the table
  * @param whereStatement Where clause to determine which rows to update
+ * @param incrementSyncVersion Whether to increment the syncVersion column
  * @returns the query to update the object in the table
  */
-declare function updateObjectQuery(table: string, obj: DynamicObject, whereStatement: string): string;
+declare function updateObjectQuery(table: string, obj: DynamicObject, whereStatement: string, incrementSyncVersion?: boolean): string;
 declare function isValueNumber(value: unknown): value is number;
 /**
  * This method is used to format a query and escape user input.

package/dist/index.js

@@ -1791,15 +1791,18 @@ INSERT INTO "${table}" (${columns})
   query = query.replace(/'(\?)'/, "?");
   return query;
 }
-function updateObjectQuery(table, obj, whereStatement) {
+function updateObjectQuery(table, obj, whereStatement, incrementSyncVersion = false) {
   const setArray = [];
   for (const i in obj) {
     setArray.push(`${escapeColumnName(i)} = ` + SQL`${obj[i]}`);
   }
+  if (incrementSyncVersion) {
+    setArray.push(`"syncVersion" = "syncVersion" + 1`);
+  }
   return `
-UPDATE ${escapeColumnName(table)}
-                 SET ${setArray.join(", ")} ${whereStatement}
-                 RETURNING *`;
+	UPDATE ${escapeColumnName(table)}
+		SET ${setArray.join(", ")} ${whereStatement}
+	RETURNING *`;
 }
 function isValueNumber2(value) {
   return !isNaN(Number(value));
@@ -1835,9 +1838,9 @@ var PsqlConnection = class {
     const startTime = process.hrtime();
     try {
       const response = await this.query(queryMetadata + formattedQuery, options);
-      this.logSqlStatement(formattedQuery, options, meta, startTime);
       if (response.rows.length === 0) throw new RsError("NOT_FOUND", "No results found");
       else if (response.rows.length > 1) throw new RsError("DUPLICATE", "More than one result found");
+      this.logSqlStatement(formattedQuery, options, meta, startTime);
       return response.rows[0];
     } catch (error) {
       this.logSqlStatement(formattedQuery, options, meta, startTime);
@@ -2042,6 +2045,20 @@ var SqlEngine = class {
     returnValue = this.replaceGlobalParamKeywords(returnValue, routeData, req, sqlParams);
     return returnValue;
   }
+  /**
+   * Replaces local parameter keywords (e.g., $paramName) in SQL query strings with '?' placeholders
+   * and adds the corresponding parameter values to the sqlParams array for parameterized queries.
+   *
+   * Validates that each parameter keyword exists in the route's request schema before processing.
+   * If the value is not a string or routeData has no request schema, returns the value unchanged.
+   *
+   * @param value - The string or number value that may contain parameter keywords (e.g., "$userId")
+   * @param routeData - The route data containing the request schema for parameter validation
+   * @param req - The request object containing the actual parameter values in req.data
+   * @param sqlParams - Array to which parameter values are appended (modified by reference)
+   * @returns The value with parameter keywords replaced by '?' placeholders, or the original value if unchanged
+   * @throws {RsError} If a parameter keyword is found that doesn't exist in the route's request schema
+   */
   replaceLocalParamKeywords(value, routeData, req, sqlParams) {
     if (!routeData.request) return value;
     const data = req.data;
@@ -2618,9 +2635,19 @@ var PsqlEngine = class extends SqlEngine {
       throw new RsError("UNKNOWN_ERROR", "Unknown route type.");
     }
   }
+  /**
+   * Executes an update request. The request will pull out the id and baseSyncVersion from the request body.
+   * (If Present) The baseSyncVersion is used to check if the record has been modified since the last sync.
+   * If the update fails because the baseSyncVersion has changed, a conflict error will be thrown.
+   * IDs can not be updated using this method.
+   * @param req - The request object.
+   * @param routeData - The route data object.
+   * @param schema - The schema object.
+   * @returns The response object.
+   */
   async executeUpdateRequest(req, routeData, schema) {
     const sqlParams = [];
-    const { id, ...bodyNoId } = req.body;
+    const { id, baseSyncVersion, ...bodyNoId } = req.body;
     const table = schema.database.find((item) => {
       return item.name === routeData.table;
     });
@@ -2628,6 +2655,8 @@ var PsqlEngine = class extends SqlEngine {
     if (table.columns.find((column) => column.name === "modifiedOn")) {
       bodyNoId.modifiedOn = (/* @__PURE__ */ new Date()).toISOString();
     }
+    let incrementSyncVersion = false;
+    if (table.columns.find((column) => column.name === "syncVersion")) incrementSyncVersion = true;
     for (const assignment of routeData.assignments) {
       const column = table.columns.find((column2) => column2.name === assignment.name);
       if (!column) continue;
@@ -2636,9 +2665,36 @@ var PsqlEngine = class extends SqlEngine {
         bodyNoId[assignmentEscaped] = Number(assignment.value);
       else bodyNoId[assignmentEscaped] = assignment.value;
     }
-    const whereClause = this.generateWhereClause(req, routeData.where, routeData, sqlParams);
-    const query = updateObjectQuery(routeData.table, bodyNoId, whereClause);
-    await this.psqlConnectionPool.queryOne(query, [...sqlParams], req.requesterDetails);
+    let whereClause = this.generateWhereClause(req, routeData.where, routeData, sqlParams);
+    const originalWhereClause = whereClause;
+    const originalSqlParams = [...sqlParams];
+    if (baseSyncVersion) {
+      const syncVersionCheck = whereClause ? `${whereClause} AND "syncVersion" = ?` : `"syncVersion" = ?`;
+      sqlParams.push(baseSyncVersion.toString());
+      whereClause = syncVersionCheck;
+    }
+    const query = updateObjectQuery(routeData.table, bodyNoId, whereClause, incrementSyncVersion);
+    try {
+      await this.psqlConnectionPool.queryOne(query, [...sqlParams], req.requesterDetails);
+    } catch (error) {
+      if (!baseSyncVersion || !(error instanceof RsError) || error.err !== "NOT_FOUND") throw error;
+      let isConflict = false;
+      try {
+        await this.psqlConnectionPool.queryOne(
+          `SELECT 1 FROM "${routeData.table}" ${originalWhereClause};`,
+          originalSqlParams,
+          req.requesterDetails
+        );
+        isConflict = true;
+      } catch {
+      }
+      if (isConflict)
+        throw new RsError(
+          "CONFLICT",
+          "The record has been modified since the baseSyncVersion value was provided."
+        );
+      throw error;
+    }
     return this.executeGetRequest(req, routeData, schema);
   }
   async executeDeleteRequest(req, routeData, schema) {