feat: Add attachJoinRef extension method

[chinhtrung]

Summary

Add attachJoinRef extension method to TypeSafeCriteriaBuilder that creates joins and returns both the criteria and join reference for reuse.

Motivation

I have seen some cases that we implement a base helper method that can be reused in different query methods. However, it's a bit troublesome when the usage wants to reuse the join reference that has been called in the base query. This method help us ease the process.

What's Changed

• Added getOrCreateJoinRef method that prevents duplicate join errors by reusing existing joins
• Added attachJoinRef extension method that returns a TypeSafeCriteriaWithJoinRef wrapper
• Created TypeSafeCriteriaWithJoinRef data class to hold both criteria and join reference
• Added comprehensive tests demonstrating basic usage and duplicate join prevention

Benefits

• Enables fluent API for creating reusable join references
• Prevents duplicate join errors when the same join is used multiple times
• Improves query building ergonomics by providing both criteria and join ref in one call

Example Usage

val result = session.query(BookTable).attachJoinRef { author }
result.criteria.applyJoinRef(result.joinRef) { authors ->
    addLike(authors.name, "J.%")
}

[luanpotter]

will column def equality work like that?

[chinhtrung]

yes I think so, I think we want to check the same object reference in this case.

[luanpotter]

My only concern with getOrCreateJoinRef is that when it is hidden within attachJoinRef it makes it a bit less clear and more magical that you might be re-using joins. the design behind having join refs in the first place was to separate intent on re-using a join versus creating a duplicate join (which is totally valid in SQL). having such a function will hide this distinction, making the existence of join refs in the first place less grounded

[luanpotter]

LGTM