forge-sql-orm 1.0.23 → 1.0.25

package/dist/ForgeSQLORM.js

@@ -4,23 +4,30 @@ const mysql = require("@mikro-orm/mysql");
 const sql = require("@forge/sql");
 const moment = require("moment");
 const entityGenerator = require("@mikro-orm/entity-generator");
-const transformValue = (value) => {
+const wrapIfNeeded = (data, wrap) => {
+  return wrap ? `'${data}'` : data;
+};
+const transformValue = (value, wrapValue = false) => {
   switch (value.type) {
     case "text":
     case "string":
-      return `'${value.value}'`;
+      return wrapIfNeeded(`${value.value}`, wrapValue);
     case "datetime":
-      return `'${moment(value.value).format("YYYY-MM-DDTHH:mm:ss.SSS")}'`;
+      return wrapIfNeeded(`${moment(value.value).format("YYYY-MM-DDTHH:mm:ss.SSS")}`, wrapValue);
     case "date":
-      return `'${moment(value.value).format("YYYY-MM-DD")}'`;
+      return wrapIfNeeded(`${moment(value.value).format("YYYY-MM-DD")}`, wrapValue);
     case "time":
-      return `'${moment(value.value).format("HH:mm:ss.SSS")}'`;
+      return wrapIfNeeded(`${moment(value.value).format("HH:mm:ss.SSS")}`, wrapValue);
     default:
       return value.value;
   }
 };
 const parseDateTime = (value, format) => {
-  return moment(value, format).toDate();
+  const m = moment(value, format, true);
+  if (!m.isValid()) {
+    return moment(value).toDate();
+  }
+  return m.toDate();
 };
 class ForgeSQLCrudOperations {
   forgeOperations;
@@ -30,57 +37,86 @@ class ForgeSQLCrudOperations {
     this.options = options;
   }
   /**
-   * Generates an SQL insert query with values.
+   * Generates an SQL INSERT statement for the provided models.
+   * If a version field exists in the schema, its value is set accordingly.
+   *
    * @param schema - The entity schema.
    * @param models - The list of entities to insert.
    * @param updateIfExists - Whether to update the row if it already exists.
-   * @returns An object containing the SQL query, fields, and values.
+   * @returns An object containing the SQL query, column names, and values.
    */
   async generateInsertScript(schema, models, updateIfExists) {
-    const fieldNames = /* @__PURE__ */ new Set();
-    const fieldValueMaps = [];
+    const columnNames = /* @__PURE__ */ new Set();
+    const modelFieldValues = [];
     models.forEach((model) => {
-      const fieldValueMap = {};
-      schema.meta.props.forEach((p) => {
-        const modelValue = model[p.name];
-        if (p.kind === "scalar" && modelValue !== void 0) {
-          fieldNames.add(p.fieldNames[0] || p.name);
-          fieldValueMap[p.fieldNames[0]] = {
-            type: p.type,
-            value: modelValue
-          };
+      const fieldValues = {};
+      schema.meta.props.forEach((prop) => {
+        const value = model[prop.name];
+        if (prop.kind === "scalar" && value !== void 0) {
+          const columnName = this.getRealFieldNameFromSchema(prop);
+          columnNames.add(columnName);
+          fieldValues[columnName] = { type: prop.type, value };
         }
       });
-      fieldValueMaps.push(fieldValueMap);
+      modelFieldValues.push(fieldValues);
     });
-    const fields = Array.from(fieldNames);
-    const values = fieldValueMaps.flatMap(
-      (fieldValueMap) => fields.map(
-        (f) => fieldValueMap[f] || {
+    const versionField = this.getVersionField(schema);
+    if (versionField) {
+      modelFieldValues.forEach((mv) => {
+        const versionRealName = this.getRealFieldNameFromSchema(versionField);
+        if (mv[versionRealName]) {
+          mv[versionRealName].value = transformValue(
+            { value: this.createVersionField(versionField), type: versionField.name },
+            true
+          );
+        } else {
+          mv[versionRealName] = {
+            type: versionField.type,
+            value: transformValue(
+              { value: this.createVersionField(versionField), type: versionField.name },
+              true
+            )
+          };
+          columnNames.add(versionField.name);
+        }
+      });
+    }
+    const columns = Array.from(columnNames);
+    const values = modelFieldValues.flatMap(
+      (fieldValueMap) => columns.map(
+        (column) => fieldValueMap[column] || {
           type: "string",
           value: null
         }
       )
     );
+    const insertValues = modelFieldValues.map((fieldValueMap) => {
+      const rowValues = columns.map(
+        (column) => transformValue(
+          fieldValueMap[column] || { type: "string", value: null },
+          true
+        )
+      ).join(",");
+      return `(${rowValues})`;
+    }).join(", ");
+    const insertEmptyValues = modelFieldValues.map(() => {
+      const rowValues = columns.map(
+        () => "?"
+      ).join(",");
+      return `(${rowValues})`;
+    }).join(", ");
+    const updateClause = updateIfExists ? ` ON DUPLICATE KEY UPDATE ${columns.map((col) => `${col} = VALUES(${col})`).join(",")}` : "";
     return {
-      sql: `INSERT INTO ${schema.meta.collection} (${fields.join(",")}) VALUES ${fieldValueMaps.map(
-        (fieldValueMap) => `(${fields.map(
-          (f) => transformValue(
-            fieldValueMap[f] || {
-              type: "string",
-              value: null
-            }
-          )
-        ).join(",")})`
-      ).join(
-        ", "
-      )} ${updateIfExists ? `ON DUPLICATE KEY UPDATE ${fields.map((f) => `${f} = VALUES(${f})`).join(",")}` : ""}`,
-      fields,
+      sql: `INSERT INTO ${schema.meta.collection} (${columns.join(",")}) VALUES ${insertValues}${updateClause}`,
+      query: `INSERT INTO ${schema.meta.collection} (${columns.join(",")}) VALUES ${insertEmptyValues}${updateClause}`,
+      fields: columns,
       values
     };
   }
   /**
    * Inserts records into the database.
+   * If a version field exists in the schema, versioning is applied.
+   *
    * @param schema - The entity schema.
    * @param models - The list of entities to insert.
    * @param updateIfExists - Whether to update the row if it already exists.
@@ -90,27 +126,29 @@ class ForgeSQLCrudOperations {
     if (!models || models.length === 0) return 0;
     const query = await this.generateInsertScript(schema, models, updateIfExists);
     if (this.options?.logRawSqlQuery) {
-      console.debug("INSERT SQL: " + query.sql);
+      console.debug("INSERT SQL: " + query.query);
     }
     const sqlStatement = sql.sql.prepare(query.sql);
-    const updateQueryResponseResult = await sqlStatement.execute();
-    return updateQueryResponseResult.rows.insertId;
+    const result = await sqlStatement.execute();
+    return result.rows.insertId;
   }
   /**
-   * Retrieves the primary keys for the given entity schema.
+   * Retrieves the primary key properties from the entity schema.
+   *
    * @param schema - The entity schema.
    * @returns An array of primary key properties.
    * @throws If no primary keys are found.
    */
   getPrimaryKeys(schema) {
-    const primaryKeys = schema.meta.props.filter((p) => p.primary);
+    const primaryKeys = schema.meta.props.filter((prop) => prop.primary);
     if (!primaryKeys.length) {
       throw new Error(`No primary keys found for schema: ${schema.meta.className}`);
     }
     return primaryKeys;
   }
   /**
-   * Deletes a record by its ID.
+   * Deletes a record by its primary key.
+   *
    * @param id - The ID of the record to delete.
    * @param schema - The entity schema.
    * @returns The number of rows affected.
@@ -126,33 +164,303 @@ class ForgeSQLCrudOperations {
     queryBuilder.andWhere({ [primaryKey.name]: { $eq: id } });
     const query = queryBuilder.getFormattedQuery();
     if (this.options?.logRawSqlQuery) {
-      console.debug("DELETE SQL: " + query);
+      console.debug("DELETE SQL: " + queryBuilder.getQuery());
     }
     const sqlStatement = sql.sql.prepare(query);
-    const updateQueryResponseResult = await sqlStatement.execute();
-    return updateQueryResponseResult.rows.affectedRows;
+    const result = await sqlStatement.execute();
+    return result.rows.affectedRows;
   }
   /**
-   * Updates a record by its ID.
+   * Retrieves the version field from the entity schema.
+   * The version field must be of type datetime, integer, or decimal, not a primary key, and not nullable.
+   *
+   * @param schema - The entity schema.
+   * @returns The version field property if it exists.
+   */
+  getVersionField(schema) {
+    if (this.options.disableOptimisticLocking) {
+      return void 0;
+    }
+    return schema.meta.props.filter((prop) => prop.version).filter((prop) => {
+      const validType = prop.type === "datetime" || prop.type === "integer" || prop.type === "decimal";
+      if (!validType) {
+        console.warn(
+          `Version field "${prop.name}" in table ${schema.meta.tableName} must be datetime, integer, or decimal, but is "${prop.type}"`
+        );
+      }
+      return validType;
+    }).filter((prop) => {
+      if (prop.primary) {
+        console.warn(
+          `Version field "${prop.name}" in table ${schema.meta.tableName} cannot be a primary key`
+        );
+        return false;
+      }
+      return true;
+    }).find((prop) => {
+      if (prop.nullable) {
+        console.warn(
+          `Version field "${prop.name}" in table ${schema.meta.tableName} should not be nullable`
+        );
+        return false;
+      }
+      return true;
+    });
+  }
+  /**
+   * Increments the version field of an entity.
+   * For datetime types, sets the current date; for numeric types, increments by 1.
+   *
+   * @param versionField - The version field property.
+   * @param updateModel - The entity to update.
+   */
+  incrementVersionField(versionField, updateModel) {
+    const key = versionField.name;
+    switch (versionField.type) {
+      case "datetime": {
+        updateModel[key] = /* @__PURE__ */ new Date();
+        break;
+      }
+      case "decimal":
+      case "integer": {
+        updateModel[key] = updateModel[key] + 1;
+        break;
+      }
+      default:
+        throw new Error(`Unsupported version field type: ${versionField.type}`);
+    }
+  }
+  /**
+   * Creates the initial version field value for an entity.
+   * For datetime types, returns the current date; for numeric types, returns 0.
+   *
+   * @param versionField - The version field property.
+   */
+  createVersionField(versionField) {
+    switch (versionField.type) {
+      case "datetime": {
+        return /* @__PURE__ */ new Date();
+      }
+      case "decimal":
+      case "integer": {
+        return 0;
+      }
+      default:
+        throw new Error(`Unsupported version field type: ${versionField.type}`);
+    }
+  }
+  /**
+   * Updates a record by its primary key using the provided entity data.
+   *
    * @param entity - The entity with updated values.
    * @param schema - The entity schema.
-   * @throws If the primary key value is missing in the entity.
    */
   async updateById(entity, schema) {
+    const fields = schema.meta.props.filter((prop) => prop.kind === "scalar").map((prop) => prop.name);
+    await this.updateFieldById(entity, fields, schema);
+  }
+  /**
+   * Updates specified fields of records based on provided conditions.
+   * If the "where" parameter is not provided, the WHERE clause is built from the entity fields
+   * that are not included in the list of fields to update.
+   *
+   * @param entity - The object containing values to update and potential criteria for filtering.
+   * @param fields - Array of field names to update.
+   * @param schema - The entity schema.
+   * @param where - Optional filtering conditions for the WHERE clause.
+   * @returns The number of affected rows.
+   * @throws If no filtering criteria are provided (either via "where" or from the remaining entity fields).
+   */
+  async updateFields(entity, fields, schema, where) {
+    const updateData = this.filterEntityFields(entity, fields);
+    const updateModel = this.modifyModel(updateData, schema);
+    let queryBuilder = this.forgeOperations.createQueryBuilder(schema.meta.class).getKnexQuery();
+    queryBuilder.update(updateModel);
+    if (where) {
+      queryBuilder.where(where);
+    } else {
+      const filterCriteria = Object.keys(entity).filter((key) => !fields.includes(key)).reduce((criteria, key) => {
+        if (entity[key] !== void 0) {
+          criteria[key] = entity[key];
+        }
+        return criteria;
+      }, {});
+      if (Object.keys(filterCriteria).length === 0) {
+        throw new Error(
+          "Filtering criteria (WHERE clause) must be provided either via the 'where' parameter or through non-updated entity fields"
+        );
+      }
+      queryBuilder.where(filterCriteria);
+    }
+    if (this.options?.logRawSqlQuery) {
+      console.debug("UPDATE SQL (updateFields): " + queryBuilder.toSQL().sql);
+    }
+    const sqlQuery = queryBuilder.toQuery();
+    const updateQueryResponse = await this.forgeOperations.fetch().executeRawUpdateSQL(sqlQuery);
+    return updateQueryResponse.affectedRows;
+  }
+  /**
+   * Updates specific fields of a record identified by its primary key.
+   * If a version field exists in the schema, versioning is applied.
+   *
+   * @param entity - The entity with updated values.
+   * @param fields - The list of field names to update.
+   * @param schema - The entity schema.
+   * @throws If the primary key is not included in the update fields.
+   */
+  async updateFieldById(entity, fields, schema) {
     const primaryKeys = this.getPrimaryKeys(schema);
-    const queryBuilder = this.forgeOperations.createQueryBuilder(schema.meta.class).update(entity);
     primaryKeys.forEach((pk) => {
-      const value = entity[pk.name];
-      if (value === null || value === void 0) {
-        throw new Error(`Primary Key ${pk.name} must exist in the model`);
+      if (!fields.includes(pk.name)) {
+        throw new Error("Update fields must include primary key: " + pk.name);
       }
-      queryBuilder.andWhere({ [pk.name]: { $eq: value } });
     });
-    const query = queryBuilder.getFormattedQuery();
+    const updatedEntity = this.filterEntityFields(entity, fields);
+    let queryBuilder = this.forgeOperations.createQueryBuilder(schema.meta.class).getKnexQuery();
+    const versionField = this.getVersionField(schema);
+    const useVersion = Boolean(versionField);
+    let updateModel = { ...updatedEntity };
+    if (useVersion && versionField) {
+      let oldModel = entity;
+      if (entity[versionField.name] === void 0 || entity[versionField.name] === null) {
+        oldModel = await this.getOldModel(primaryKeys, entity, schema, versionField);
+      }
+      const primaryFieldNames = primaryKeys.map((pk) => pk.name);
+      const fieldsToRetain = primaryFieldNames.concat(versionField.name);
+      const fromEntries = Object.fromEntries(fieldsToRetain.map((key) => [key, oldModel[key]]));
+      updateModel = { ...updatedEntity, ...fromEntries };
+      this.incrementVersionField(versionField, updateModel);
+      updateModel = this.modifyModel(updateModel, schema);
+      queryBuilder.update(updateModel);
+      if (oldModel[versionField.name] !== void 0 || oldModel[versionField.name] !== null && this.isValid(oldModel[versionField.name])) {
+        queryBuilder.andWhere(this.optWhere(oldModel, versionField));
+      }
+    } else {
+      updateModel = this.modifyModel(updatedEntity, schema);
+      queryBuilder.update(updateModel);
+    }
+    this.addPrimaryWhere(queryBuilder, primaryKeys, updateModel);
+    const sqlQuery = queryBuilder.toQuery();
     if (this.options?.logRawSqlQuery) {
-      console.debug("UPDATE SQL: " + query);
+      console.debug("UPDATE SQL: " + queryBuilder.toSQL().sql);
+    }
+    const updateQueryResponse = await this.forgeOperations.fetch().executeRawUpdateSQL(sqlQuery);
+    if (versionField && !updateQueryResponse.affectedRows) {
+      throw new Error(
+        "Optimistic locking failed: the record with primary key(s) " + primaryKeys.map((p) => updateModel[p.name]).join(", ") + " has been modified by another process."
+      );
     }
-    await this.forgeOperations.fetch().executeRawUpdateSQL(query);
+  }
+  /**
+   * Constructs an optional WHERE clause for the version field.
+   *
+   * @param updateModel - The model containing the current version field value.
+   * @param versionField - The version field property.
+   * @returns A filter query for the version field.
+   */
+  optWhere(updateModel, versionField) {
+    const currentVersionValue = transformValue(
+      { value: updateModel[versionField.name], type: versionField.type },
+      false
+    );
+    return { [versionField.name]: currentVersionValue };
+  }
+  /**
+   * Retrieves the current state of a record from the database.
+   *
+   * @param primaryKeys - The primary key properties.
+   * @param entity - The entity with updated values.
+   * @param schema - The entity schema.
+   * @param versionField - The version field property.
+   * @returns The existing record from the database.
+   * @throws If the record does not exist or if multiple records are found.
+   */
+  async getOldModel(primaryKeys, entity, schema, versionField) {
+    const primaryFieldNames = primaryKeys.map((pk) => pk.name);
+    const fieldsToSelect = primaryFieldNames.concat(versionField.name);
+    const queryBuilder = this.forgeOperations.createQueryBuilder(schema).select(fieldsToSelect);
+    this.addPrimaryWhere(queryBuilder, primaryKeys, entity);
+    const formattedQuery = queryBuilder.getFormattedQuery();
+    const models = await this.forgeOperations.fetch().executeSchemaSQL(formattedQuery, schema);
+    if (!models || models.length === 0) {
+      throw new Error(`Cannot modify record because it does not exist in table ${schema.meta.tableName}`);
+    }
+    if (models.length > 1) {
+      throw new Error(
+        `Cannot modify record because multiple rows with the same ID were found in table ${schema.meta.tableName}. Please verify the table metadata.`
+      );
+    }
+    return models[0];
+  }
+  /**
+   * Adds primary key conditions to the query builder.
+   *
+   * @param queryBuilder - The Knex query builder instance.
+   * @param primaryKeys - The primary key properties.
+   * @param entity - The entity containing primary key values.
+   * @throws If any primary key value is missing.
+   */
+  addPrimaryWhere(queryBuilder, primaryKeys, entity) {
+    primaryKeys.forEach((pk) => {
+      const fieldName = this.getRealFieldNameFromSchema(pk);
+      const value = entity[fieldName];
+      if (value === null || value === void 0) {
+        throw new Error(`Primary key ${fieldName} must exist in the model`);
+      }
+      queryBuilder.andWhere({ [fieldName]: value });
+    });
+  }
+  /**
+   * Filters the entity to include only the specified fields.
+   *
+   * @param entity - The original entity.
+   * @param fields - The list of fields to retain.
+   * @returns A partial entity object containing only the specified fields.
+   */
+  filterEntityFields = (entity, fields) => fields.reduce((result, field) => {
+    if (field in entity) {
+      result[field] = entity[field];
+    }
+    return result;
+  }, {});
+  /**
+   * Transforms and modifies the updated entity model based on the schema.
+   *
+   * @param updatedEntity - The updated entity.
+   * @param schema - The entity schema.
+   * @returns The modified entity.
+   */
+  modifyModel(updatedEntity, schema) {
+    const modifiedModel = {};
+    schema.meta.props.filter((p) => p.kind === "scalar").forEach((p) => {
+      const value = updatedEntity[p.name];
+      if (value !== void 0 && value !== null) {
+        const fieldName = this.getRealFieldNameFromSchema(p);
+        modifiedModel[fieldName] = transformValue({ value, type: p.type }, false);
+      }
+    });
+    return modifiedModel;
+  }
+  /**
+   * Returns the real field name from the entity property based on the schema.
+   *
+   * @param p - The entity property.
+   * @returns The real field name.
+   */
+  getRealFieldNameFromSchema(p) {
+    return p.fieldNames && p.fieldNames.length ? p.fieldNames[0] : p.name;
+  }
+  /**
+   * Validates the provided value.
+   *
+   * @param value - The value to validate.
+   * @returns True if the value is valid, false otherwise.
+   */
+  isValid(value) {
+    if (value instanceof Date) {
+      return !isNaN(value.getTime());
+    }
+    return true;
   }
 }
 class ForgeSQLSelectOperations {
@@ -160,6 +468,16 @@ class ForgeSQLSelectOperations {
   constructor(options) {
     this.options = options;
   }
+  async executeSchemaSQLOnlyOne(query, schema) {
+    const results = await this.executeSchemaSQL(query, schema);
+    if (!results || results.length === 0) {
+      return void 0;
+    }
+    if (results.length > 1) {
+      throw new Error("Expected 1 record but returned " + results.length);
+    }
+    return results[0];
+  }
   /**
    * Executes a schema-based SQL query and maps the result to the entity schema.
    * @param query - The SQL query to execute.
@@ -211,13 +529,14 @@ class ForgeSQLSelectOperations {
   /**
    * Executes a raw SQL update query.
    * @param query - The raw SQL update query.
+   * @param params - sql parameters.
    * @returns The update response containing affected rows.
    */
-  async executeRawUpdateSQL(query) {
-    if (this.options.logRawSqlQuery) {
-      console.debug("Executing update SQL: " + query);
-    }
+  async executeRawUpdateSQL(query, params) {
     const sqlStatement = sql.sql.prepare(query);
+    if (params) {
+      sqlStatement.bindParams(params);
+    }
     const updateQueryResponseResults = await sqlStatement.execute();
     return updateQueryResponseResults.rows;
   }
@@ -254,7 +573,7 @@ class ForgeSQLORMImpl {
         preferTs: false,
         debug: false
       });
-      const newOptions = options ?? { logRawSqlQuery: false };
+      const newOptions = options ?? { logRawSqlQuery: false, disableOptimisticLocking: false };
       this.crudOperations = new ForgeSQLCrudOperations(this, newOptions);
       this.fetchOperations = new ForgeSQLSelectOperations(newOptions);
     } catch (error) {
@@ -265,11 +584,12 @@ class ForgeSQLORMImpl {
   /**
    * Returns the singleton instance of ForgeSQLORMImpl.
    * @param entities - List of entities (required only on first initialization).
+   * @param options - Options for configuring ForgeSQL ORM behavior.
    * @returns The singleton instance of ForgeSQLORMImpl.
    */
-  static getInstance(entities) {
+  static getInstance(entities, options) {
     if (!ForgeSQLORMImpl.instance) {
-      ForgeSQLORMImpl.instance = new ForgeSQLORMImpl(entities);
+      ForgeSQLORMImpl.instance = new ForgeSQLORMImpl(entities, options);
     }
     return ForgeSQLORMImpl.instance;
   }
@@ -298,7 +618,7 @@ class ForgeSQLORMImpl {
     return this.mikroORM.em.createQueryBuilder(entityName, alias, void 0, loggerContext);
   }
   /**
-   * Provides access to the underlying Knex instance for executing raw queries and building complex query parts.
+   * Provides access to the underlying Knex instance for building complex query parts.
    * enabling advanced query customization and performance tuning.
    * @returns The Knex instance, which can be used for query building.
    */
@@ -308,8 +628,8 @@ class ForgeSQLORMImpl {
 }
 class ForgeSQLORM {
   ormInstance;
-  constructor(entities) {
-    this.ormInstance = ForgeSQLORMImpl.getInstance(entities);
+  constructor(entities, options) {
+    this.ormInstance = ForgeSQLORMImpl.getInstance(entities, options);
   }
   /**
    * Proxies the `crud` method from `ForgeSQLORMImpl`.