Skip to content
Enterprise Backend Blueprint

BaseServiceOperations: OneToMany Update — Detailed Flows

This document is a companion to BaseServiceOperations: OneToMany Update. It provides visual transaction flow diagrams and step-by-step payload examples for each update scenario.

Flow Chart: update() Method

Section titled “Flow Chart: update() Method”

Main Transaction Flow

Section titled “Main Transaction Flow”
flowchart TD
    A([START<br/>update<br/>id, data, currentUser]) --> B

    subgraph TXN ["🔒 manager.transaction()"]
        B["txRepo = transactionalManager<br/>.getRepository(Entity)"] --> C
        C["dataRecord = { ...data }<br/>(spread DTO to plain object)"] --> D

        D["🔍 Inspect metadata<br/>manyToManyRelations = relations<br/>&nbsp;&nbsp;.filter(isManyToMany and isOwning)<br/>oneToManyRelations = relations<br/>&nbsp;&nbsp;.filter(isOneToMany)"] --> E

        subgraph EXTRACT ["Step 2–3: Extract Relations from DTO"]
            E["📦 Extract M2M<br/>for each manyToManyRelation:<br/>&nbsp;&nbsp;if propertyName in DTO →<br/>&nbsp;&nbsp;&nbsp;&nbsp;manyToManyPayload[name] = value<br/>&nbsp;&nbsp;&nbsp;&nbsp;delete dataRecord[name]"] --> F
            F["📦 Extract OneToMany<br/>for each oneToManyRelation:<br/>&nbsp;&nbsp;if propertyName in DTO →<br/>&nbsp;&nbsp;&nbsp;&nbsp;oneToManyPayload[name] = value<br/>&nbsp;&nbsp;&nbsp;&nbsp;delete dataRecord[name]<br/>&nbsp;&nbsp;&nbsp;&nbsp;mark as explicitlySet"]
        end

        F --> G

        subgraph PRELOAD ["Step 4–5: Preload & Save Parent"]
            G["⚙️ preload scalar fields only<br/>preloadData = { id, ...dataRecord }<br/>if currentUser → set updated_by"] --> H
            H{entity<br/>found?}
            H -- No --> ERR1(["❌ NotFoundException"])
            H -- Yes --> I
            I["💾 txRepo.save(entityToUpdate)<br/>Save parent scalars only<br/>No cascade on relations"]
        end

        I --> J

        subgraph O2M ["Step 6: Handle OneToMany — Bypass Cascade"]
            J{Has<br/>oneToManyPayload?}
            J -- No --> M
            J -- Yes --> K
            K["🔎 Resolve FK from metadata<br/>fkDbName = inverseRelation<br/>&nbsp;&nbsp;.joinColumns[0].databaseName<br/>fkColumn = inverseEntityMetadata<br/>&nbsp;&nbsp;.columns.find(databaseName)"] --> L
            L["💾 childRepo.save(children)<br/>for each child:<br/>&nbsp;&nbsp;child[fkColumn.propertyName] = id  ← FK!<br/>&nbsp;&nbsp;delete child[inverseSidePropertyPath]<br/>→ no id = INSERT ✅<br/>→ has id = UPDATE ✅"]
        end

        L --> M

        subgraph M2M ["Step 7: Sync ManyToMany — addAndRemove"]
            M{Has<br/>manyToManyPayload?}
            M -- No --> P
            M -- Yes --> N
            N["📡 _syncManyToManyRelations()<br/>for each M2M relation:<br/>&nbsp;&nbsp;loadMany() current junction items<br/>&nbsp;&nbsp;filter soft-deleted is_deleted<br/>&nbsp;&nbsp;diff: toAdd / toRemove<br/>&nbsp;&nbsp;addAndRemove(toAdd, toRemove)"]
        end

        N --> P

        subgraph RELOAD ["Step 8: Reload for Complete Response"]
            P["updatedRelationNames =<br/>&nbsp;&nbsp;[...keys oneToManyPayload,<br/>&nbsp;&nbsp;&nbsp;...keys manyToManyPayload]"]
            P --> Q{Has updated<br/>relation names?}
            Q -- No (scalar only) --> S
            Q -- Yes --> R
            R["🔄 txRepo.findOne<br/>&nbsp;&nbsp;where: { id, ...softDeleteFilter }<br/>&nbsp;&nbsp;relations: updatedRelationNames<br/>← 1 extra query for full relation response"]
        end
    end

    R --> T{reloaded<br/>!= null?}
    T -- Yes --> U(["✅ return reloaded"])
    T -- No --> S(["✅ return saved"])

    style TXN fill:#1e3a5f,stroke:#4a9eff,color:#fff
    style EXTRACT fill:#1a3a2a,stroke:#4aff7a,color:#fff
    style PRELOAD fill:#2a1a3a,stroke:#9a4aff,color:#fff
    style O2M fill:#3a1a1a,stroke:#ff4a4a,color:#fff
    style M2M fill:#3a2a1a,stroke:#ffaa4a,color:#fff
    style RELOAD fill:#1a2a3a,stroke:#4aaaff,color:#fff
    style ERR1 fill:#8b0000,stroke:#ff0000,color:#fff

_syncManyToManyRelations Detail

Section titled “_syncManyToManyRelations Detail”
flowchart TD
    A(["syncOne<br/>relationName, newItems"]) --> B
    B["relationMeta = metadata.relations<br/>&nbsp;&nbsp;.find(propertyName)"] --> C
    C{relationMeta<br/>found?}
    C -- No --> Z(["return — skip"])
    C -- Yes --> D

    D["inverseEntity = relationMeta<br/>&nbsp;&nbsp;.inverseEntityMetadata<br/>hasSoftDelete = columns.some<br/>&nbsp;&nbsp;(propertyName === is_deleted)"] --> E

    E["📡 loadMany<br/>rawItems = createQueryBuilder<br/>&nbsp;&nbsp;.relation(Entity, relationName)<br/>&nbsp;&nbsp;.of(entityId)<br/>&nbsp;&nbsp;.loadMany()"] --> F

    F{hasSoftDelete?}
    F -- Yes --> G["currentIds = rawItems<br/>&nbsp;&nbsp;.filter(item.is_deleted !== true)<br/>&nbsp;&nbsp;.map(i => i.id)"]
    F -- No --> H["currentIds = rawItems<br/>&nbsp;&nbsp;.map(i => i.id)"]

    G --> I
    H --> I

    I["newIds = newItems<br/>&nbsp;&nbsp;.map(i => i.id).filter(Boolean)"] --> J

    J["🔀 Diff<br/>toAdd = newIds.filter(nid not in currentIds)<br/>toRemove = currentIds.filter(cid not in newIds)"] --> K

    K{toAdd.length > 0<br/>OR<br/>toRemove.length > 0?}
    K -- No changes --> L(["✅ no-op — skip"])
    K -- Has changes --> M

    M["⚡ addAndRemove(toAdd, toRemove)<br/>ATOMIC:<br/>&nbsp;&nbsp;INSERT junction rows for toAdd<br/>&nbsp;&nbsp;DELETE junction rows for toRemove"] --> N(["✅ done"])

    style A fill:#1a3a2a,stroke:#4aff7a,color:#fff
    style M fill:#1e3a5f,stroke:#4a9eff,color:#fff
    style L fill:#2a3a1a,stroke:#aaff4a,color:#fff
    style N fill:#2a3a1a,stroke:#aaff4a,color:#fff

Transaction Scope & Rollback

Section titled “Transaction Scope & Rollback”
flowchart LR
    subgraph OK ["✅ Happy Path"]
        direction TB
        A1["Save parent scalar"] --> A2["Save OneToMany children"]
        A2 --> A3["Sync ManyToMany junction"]
        A3 --> A4["Reload with relations"]
        A4 --> A5["COMMIT"]
    end

    subgraph FAIL ["❌ Any Step Fails"]
        direction TB
        B1["Save parent scalar"] --> B2["Save OneToMany children"]
        B2 -->|ERROR| B3["❌ throw"]
        B3 --> B4["AUTO ROLLBACK<br/>All operations cancelled"]
    end

    TXN(["manager.transaction()"]) --> OK
    TXN --> FAIL

    style OK fill:#1a3a1a,stroke:#4aff4a,color:#fff
    style FAIL fill:#3a1a1a,stroke:#ff4a4a,color:#fff
    style TXN fill:#1e3a5f,stroke:#4a9eff,color:#fff

Reference Entity Model

Section titled “Reference Entity Model”

The examples below use this parent/child relationship:

// Order (parent) — owns the relations
@Entity()
export class Order {
    @PrimaryGeneratedColumn('uuid') id: string;


    // OneToMany (cascade save enabled)
    @OneToMany(() => OrderItem, (item) => item.order, { cascade: true })
    items: OrderItem[];


    // ManyToMany (owning side — has @JoinTable)
    @ManyToMany(() => Tag)
    @JoinTable({ name: 'orders_tags', ... })
    tags: Tag[];
}


// OrderItem (child) — has explicit FK column + ManyToOne back-reference
@Entity()
export class OrderItem {
    @Column({ type: 'uuid' })           // explicit FK column — NOT nullable
    order_id: string;


    @ManyToOne(() => Order, (o) => o.items)
    @JoinColumn({ name: 'order_id' })
    order: Order;                        // relation object


    @Column({ type: 'boolean' })
    is_primary: boolean;
}

The explicit order_id FK column is the key to avoiding the 23502 error. It gives childRepo.save() a concrete column to populate — bypassing the ambiguity of the cascade relation object.

Payload Walkthroughs

Section titled “Payload Walkthroughs”

Example 1: Update Scalar Fields Only

Section titled “Example 1: Update Scalar Fields Only”
PATCH /orders/uuid-parent
{
  "name": "Updated Order Name",
  "is_active": true
}
Flow:
  preload({ id, name, is_active })
  → save(entity)
  → no relation keys in DTO → no reload needed


Response:
  { id, name: "Updated Order Name", is_active: true, ... }

Example 2: Update ManyToMany (Tags)

Section titled “Example 2: Update ManyToMany (Tags)”
PATCH /orders/uuid-parent
{
  "tags": [{ "id": "tag-express" }, { "id": "tag-priority" }]
}
Flow:
  1. Extract tags from DTO → manyToManyPayload
  2. preload({ id })                              ← tags excluded from preload
  3. save(entity)                                 ← scalar only (no-op here)
  4. loadMany(tags of order)                      → currentIds: ["tag-express"]
  5. diff: toAdd=["tag-priority"], toRemove=[]
  6. addAndRemove(["tag-priority"], [])            ✅ no duplicate inserts
  7. findOne({ relations: ['tags'] })             ← reload with full tag objects


Response:
  { id, ..., tags: [{ id: "tag-express", ... }, { id: "tag-priority", ... }] }

Example 3: Add New Child to OneToMany

Section titled “Example 3: Add New Child to OneToMany”
PATCH /orders/uuid-parent
{
  "items": [{ "is_primary": true, "lookup_item_id": "item-abc" }]
}
Flow:
  1. Extract items from DTO → oneToManyPayload
  2. preload({ id })                              ← items excluded from preload
  3. entityToUpdate.items === undefined           ← cascade won't trigger
  4. save(entityToUpdate)                         ← parent saved first
  5. childRepo.save([{
       is_primary: true,
       lookup_item_id: "item-abc",
       order_id: "uuid-parent"                   ← FK set explicitly
     }])                                          ✅ INSERT with correct FK
  6. findOne({ relations: ['items'] })            ← reload


Response:
  { id, ..., items: [{ id: "new-uuid", is_primary: true, ... }] }

Example 4: Update Existing + Add New Child Together

Section titled “Example 4: Update Existing + Add New Child Together”
PATCH /orders/uuid-parent
{
  "items": [
    { "id": "item-A", "is_primary": false, "lookup_item_id": "item-abc" },
    { "is_primary": true, "lookup_item_id": "item-xyz" }
  ]
}
Flow:
  1. Extract items from DTO
  2. preload + save parent (scalar fields)
  3. childRepo.save([
       { id: "item-A", is_primary: false, ..., order_id: "uuid-parent" }, → UPDATE item-A
       { is_primary: true, ..., order_id: "uuid-parent" }                 → INSERT new
     ])                                           ✅ both have correct FK
  4. findOne({ relations: ['items'] })            ← reload all children


Response:
  {
    id,
    items: [
      { id: "item-A", is_primary: false, ... },  ← updated
      { id: "new-uuid", is_primary: true, ... }  ← inserted
    ]
  }


Note: item-B (if in DB but absent from DTO) will be soft-deleted by default
      and will NOT appear in the response, since the reload only fetches
      non-deleted children.

Example 5: ManyToMany + OneToMany Together (One Transaction)

Section titled “Example 5: ManyToMany + OneToMany Together (One Transaction)”
PATCH /orders/uuid-parent
{
  "tags": [{ "id": "tag-priority" }],
  "items": [{ "id": "item-A", "is_primary": true }]
}
Flow (single transaction):
  1. Extract tags  → manyToManyPayload
  2. Extract items → oneToManyPayload
  3. preload({ id })                              ← clean — no relations
  4. save(entityToUpdate)                         ← parent updated
  5. childRepo.save([{ id: "item-A", ..., order_id: "..." }])  ← OneToMany
  6. addAndRemove(["tag-priority"], [...])         ← ManyToMany
  7. findOne({ relations: ['items', 'tags'] })    ← ONE reload for everything
  All in one transaction → atomic ✅


Response:
  {
    id,
    items: [{ id: "item-A", is_primary: true, ... }],
    tags: [{ id: "tag-priority", ... }]
  }

Transaction & Rollback

Section titled “Transaction & Rollback”

Everything runs inside manager.transaction():

return this.typeOrmRepository.manager.transaction(async (transactionalManager) => {
    const txRepo = transactionalManager.getRepository(Entity);
    // All operations — parent save, children save, M2M sync — use txRepo
    // from the same transactional manager
});

If any step throws an error:

  • TypeORM automatically rolls back the entire transaction
  • The parent update, children saves, and M2M sync are all reverted
  • executeDbOperation() catches and re-throws a formatted HttpException — no manual rollback needed

Soft Delete Filter in M2M Sync

Section titled “Soft Delete Filter in M2M Sync”

_syncManyToManyRelations checks whether the related entity has an is_deleted column before computing the diff:

const hasSoftDelete = inverseEntity.columns.some((c) => c.propertyName === 'is_deleted');


const rawItems = await repo
    .createQueryBuilder()
    .relation(Entity, relationName)
    .of(entityId)
    .loadMany();


// Exclude soft-deleted records from "current" set
const currentIds = hasSoftDelete
    ? rawItems.filter((item) => item.is_deleted !== true).map((i) => i.id)
    : rawItems.map((i) => i.id);

This prevents soft-deleted records from being counted as “currently related” and then accidentally re-added to the junction table on the next update.