Method upsert

packages/core/src/EntityManager.ts:1218–1364

* Creates or updates the entity, based on whether it is already present in the database. * This method performs an `insert on conflict merge` query ensuring the database is in sync, returning a managed * entity instance. The method accepts either `entityName` together with the entity `data`, o

(
    entityNameOrEntity: EntityName<Entity> | Entity,
    data?: EntityData<Entity> | NoInfer<Entity>,
    options: UpsertOptions<Entity, Fields> = {},
  )

   * If the entity is already present in current context, there won't be any queries - instead, the entity data will be assigned and an explicit `flush` will be required for those changes to be persisted.
   */
  async upsert<Entity extends object, Fields extends string = any>(
    entityNameOrEntity: EntityName<Entity> | Entity,
    data?: EntityData<Entity> | NoInfer<Entity>,
    options: UpsertOptions<Entity, Fields> = {},
  ): Promise<Entity> {
    if (options.disableIdentityMap ?? this.config.get('disableIdentityMap')) {
      const em = this.getContext(false);
      const fork = em.fork({ keepTransactionContext: true });
      const ret = await fork.upsert(entityNameOrEntity, data, { ...options, disableIdentityMap: false });
      fork.clear();

      return ret;
    }

    const em = this.getContext(false);
    em.prepareOptions(options);

    let entityName: EntityName<Entity>;
    let where: FilterQuery<Entity>;
    let entity: Entity | null = null;

    if (data === undefined) {
      entityName = (entityNameOrEntity as Dictionary).constructor;
      data = entityNameOrEntity as Entity;
    } else {
      entityName = entityNameOrEntity as EntityName<Entity>;
    }

    const meta = this.metadata.get<Entity>(entityName);
    const convertCustomTypes = !Utils.isEntity(data);

    if (Utils.isEntity(data)) {
      entity = data as Entity;

      if (helper(entity).__managed && helper(entity).__em === em && !this.config.get('upsertManaged')) {
        em.#entityFactory.mergeData(meta, entity, data, { initialized: true });
        return entity;
      }

      where = helper(entity).getPrimaryKey() as FilterQuery<Entity>;
      em.#entityFactory.assignDefaultValues(entity, meta);
      data = em.#comparator.prepareEntity(entity);
    } else {
      data = Utils.copy(QueryHelper.processParams(data));
      where = Utils.extractPK(data, meta) as FilterQuery<Entity>;

      if (where && !this.config.get('upsertManaged')) {
        const exists = em.#unitOfWork.getById<Entity>(entityName, where as Primary<Entity>, options.schema);

        if (exists) {
          return em.assign(exists, data as any) as any;
        }
      }

      em.#entityFactory.assignDefaultValues(data as Entity, meta, true);

      for (const key of Object.keys(data!)) {
        const prop = meta.properties[key as EntityKey<Entity>];