feat: #348 Add/remove operations for InnerTableLink references

[obabichevjb]

Description

Summary of the change: This PR implements add/remove operations for many-to-many relationships created with InnerTableLink / via, allowing incremental modifications without reassigning the entire collection.

Detailed description:

• Why: Issue Improve support for references created with InnerTableLink/via #348 requested support for incremental add/remove operations on via references. Previously, users had to reassign the entire collection via SizedCollection, which was inconvenient for adding/removing single items.

• What:

  • Added MutableSizedIterable<T> interface extending SizedIterable<T> with methods: add(), remove(), addAll(), removeAll(), clear()
  • Implemented MutableReferenceCollection<SID, Source, ID, Target> class that tracks pending additions and removals in memory
  • Modified InnerTableLink to return MutableSizedIterable<Target> from getValue() while maintaining backward compatibility
  • Changes are delayed-flushed (tracked in memory and applied during entity flush), addressing both tasks in Improve support for references created with InnerTableLink/via #348

• How:

  • MutableReferenceCollection wraps the underlying database query result and maintains two sets: pendingAdditions and pendingRemovals
  • When iterating, it combines the database state with pending changes to provide an up-to-date view
  • On flush, it applies the diff to the intermediate table (DELETE removed items, INSERT new items)
  • Ordering is preserved by maintaining the original sequence and appending new items

Example usage:

val root = Node.new { name = "root" }
val child1 = Node.new { name = "child1" }
val child2 = Node.new { name = "child2" }

// Traditional approach (still supported)
root.children = SizedCollection(listOf(child1, child2))

// New approach - incremental add/remove
(root.children as MutableSizedIterable<Node>).add(child3)
(root.children as MutableSizedIterable<Node>).remove(child1)

Note: Users must cast to MutableSizedIterable if the property is declared as SizedIterable to access the mutable methods. Alternatively, they can declare the property type as MutableSizedIterable (though SizedIterable is recommended for backward compatibility).

---

Type of Change

Please mark the relevant options with an "X":

• Bug fix
• New feature
• Documentation update

Updates/remove existing public API methods:

• Is breaking change

Affected databases:

• MariaDB
• Mysql5
• Mysql8
• Oracle
• Postgres
• SqlServer
• H2
• SQLite

Checklist

• Unit tests are in place
• The build is green (including the Detekt check)
• All public methods affected by my PR has up to date API docs
• Documentation for my change is up to date

---

Related Issues

Closes #348

🤖 Generated with Claude Code