feat: implement cast, right, left, replace expressions #894

cj848 · 2025-07-05T01:06:54Z

Motivation

This PR introduces new string manipulation functions (CAST, LEFT, RIGHT, REPLACE) to the Kotlin JDSL JPQL DSL. These functions align with the JPA 3.2 specification, providing enhanced capabilities for string operations directly within JPQL queries. This change aims to expand the functionality of Kotlin JDSL to support more advanced JPQL features as defined in the latest JPA specifications.

Modifications

Added cast, left, right, and replace functions to dsl/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/Jpql.kt for use within jpql {} blocks.
Implemented corresponding JpqlCast, JpqlLeft, JpqlRight, JpqlReplace expression types in query-model/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/querymodel/jpql/expression/impl/.
Added serializers for these new expression types in render/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/render/jpql/serializer/impl/.
Created unit tests for the new serializers in render/jpql/src/test/kotlin/com/linecorp/kotlinjdsl/render/jpql/serializer/impl/.
Added DSL usage tests for the new functions in dsl/jpql/src/test/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/expression/ExpressionDslTest.kt.
Updated documentation (docs/en/jpql-with-kotlin-jdsl/expressions.md and docs/ko/jpql-with-kotlin-jdsl/expressions.md) to include details and examples of the new functions, noting their addition in JPA 3.2.

Result

After this PR is merged, users will be able to utilize CAST, LEFT, RIGHT, and REPLACE functions directly within their Kotlin JDSL JPQL queries, enabling more powerful and flexible string manipulation operations. The documentation will also be updated to reflect these new capabilities.

Closes

N/A (No specific issue is being closed by this PR, it's a new feature implementation)

동기

이 PR은 Kotlin JDSL JPQL DSL에 새로운 문자열 조작 함수(CAST, LEFT, RIGHT, REPLACE)를 도입합니다. 이 함수들은 JPA 3.2 스펙에 맞춰 JPQL 쿼리 내에서 문자열 연산을 위한 향상된 기능을 제공합니다. 이 변경은 최신 JPA 스펙에 정의된 고급 JPQL 기능을 지원하기 위해 Kotlin JDSL의 기능을 확장하는 것을 목표로 합니다.

수정 사항

jpql {} 블록 내에서 사용할 수 있도록 dsl/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/Jpql.kt에 cast, left, right, replace 함수를 추가했습니다.
query-model/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/querymodel/jpql/expression/impl/에 해당 JpqlCast, JpqlLeft, JpqlRight, JpqlReplace expression 타입을 구현했습니다.
render/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/render/jpql/serializer/impl/에 새로운 expression 타입에 대한 Serializer를 추가했습니다.
render/jpql/src/test/kotlin/com/linecorp/kotlinjdsl/render/jpql/serializer/impl/에 새로운 Serializer에 대한 단위 테스트를 생성했습니다.
dsl/jpql/src/test/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/expression/ExpressionDslTest.kt에 새로운 함수에 대한 DSL 사용 테스트를 추가했습니다.
JPA 3.2에 추가된 기능임을 명시하고 새로운 함수에 대한 세부 정보 및 예제를 포함하도록 문서(docs/en/jpql-with-kotlin-jdsl/expressions.md 및 docs/ko/jpql-with-kotlin-jdsl/expressions.md)를 업데이트했습니다.

결과

이 PR이 병합되면 사용자는 Kotlin JDSL JPQL 쿼리 내에서 CAST, LEFT, RIGHT, REPLACE 함수를 직접 활용하여 더욱 강력하고 유연한 문자열 조작 작업을 수행할 수 있게 됩니다. 문서 또한 이러한 새로운 기능을 반영하여 업데이트될 것입니다.

닫는 이슈

N/A (이 PR은 특정 이슈를 닫지 않으며, 새로운 기능 구현입니다.)

codecov-commenter · 2025-07-05T01:17:38Z

Codecov Report

Attention: Patch coverage is 90.66667% with 7 lines in your changes missing coverage. Please review.

Project coverage is 90.75%. Comparing base (12b931d) to head (ae90af2).
Report is 1 commits behind head on develop.

Files with missing lines	Patch %	Lines
...in/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/Jpql.kt	80.00%	2 Missing ⚠️
...tlinjdsl/querymodel/jpql/expression/Expressions.kt	80.00%	1 Missing ⚠️
.../render/jpql/serializer/impl/JpqlCastSerializer.kt	87.50%	1 Missing ⚠️
.../render/jpql/serializer/impl/JpqlLeftSerializer.kt	87.50%	1 Missing ⚠️
...nder/jpql/serializer/impl/JpqlReplaceSerializer.kt	90.00%	1 Missing ⚠️
...render/jpql/serializer/impl/JpqlRightSerializer.kt	87.50%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #894      +/-   ##
===========================================
- Coverage    90.76%   90.75%   -0.01%     
===========================================
  Files          352      362      +10     
  Lines         3788     3863      +75     
  Branches       229      229              
===========================================
+ Hits          3438     3506      +68     
- Misses         276      283       +7     
  Partials        74       74

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

shouwn · 2025-07-14T23:39:12Z

dsl/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/Jpql.kt

+    @SinceJdsl("3.6.0")
+    fun <T : Any> cast(value: Expressionable<*>, type: KClass<T>): Expression<T> {
+        return Expressions.cast(value.toExpression(), type)
+    }
+
+    /**
+     * Creates an expression that represents the casting of a value to a different type.
+     */
+    @SinceJdsl("3.6.0")
+    inline fun <reified T : Any> cast(value: Expressionable<*>): Expression<T> {
+        return Expressions.cast(value.toExpression(), T::class)
+    }


https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2#typecasts

string_cast_function::= CAST(scalar_expression AS STRING) arithmetic_cast_function::= CAST(string_expression AS {INTEGER | LONG | FLOAT | DOUBLE})

Looking at the Jakarta specification, the range of castable types is limited depending on whether cast is a scalar type or a string type.

I believe this information should also be included in the function specification.

And I think it would be best to create a function form that is as similar as possible to the JPQL specification.

Therefore, I think it would be good to create CastStep, similar to TrimFromStep. Creating CastStep would also make it easier to implement type restrictions.

yeah. applied

Users can use the cast operator as follows:

cast(path(Book::price)).asString() // scalar expression as String cast(path(Book::authorId)).asInt() // string expression as integer cast(path(Book::authorId)).asLong() // string expression as long cast(path(Book::authorId)).asDouble() // string expression as float cast(path(Book::authorId)).asFloat() // string expression as double

shouwn · 2025-07-14T23:47:45Z

dsl/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/Jpql.kt

+    @SinceJdsl("3.6.0")
+    fun left(value: Expressionable<String>, count: Expressionable<Int>): Expression<String> {
+        return Expressions.left(value.toExpression(), count.toExpression())
+    }


https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2#_criteriabuilder_

Expression<String> left(Expression<String> x, int len); Expression<String> right(Expression<String> x, Expression<Integer> len); Expression<String> replace(Expression<String> x, Expression<String> substring, Expression<String> replacement);

It would be best to follow the parameter naming conventions of CriteriaBuilder.
count should be length, and search should be substring.

The parameter name x is not ideal, so it would be best to use the value as is.

thank you. your reviews applied

shouwn · 2025-07-14T23:48:58Z

...del/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/querymodel/jpql/expression/impl/JpqlCast.kt

+@SinceJdsl("3.6.0")
+data class JpqlCast<T : Any> internal constructor(


Since it is implementation code, it would be good to include the internal annotation.

thank you. your reviews applied

shouwn

Please change StringCastStep to something else.

shouwn · 2025-07-23T23:51:12Z

dsl/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/dsl/jpql/expression/StringCastStep.kt

+ * This corresponds to the BNF: CAST(scalar_expression AS STRING)
+ */
+@SinceJdsl("3.6.0")
+interface StringCastStep {


I think the name “String Cast Step” is confusing because it is unclear whether it refers to casting to a string or casting a string.

How about names such as “CastStepFromString” or “CastStepToString”?

ok. your reviews applied

…eature/implement-cast-right-left-replace # Conflicts: # query-model/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/querymodel/jpql/expression/Expressions.kt

cj848 requested review from pickmoment, huisam and shouwn as code owners July 5, 2025 01:06

cj848 changed the title ~~feat: implement cast, right, left, replace expressions~~ feat: implement cast, right, left, replace expressions (follow-up to #880) Jul 5, 2025

cj848 changed the title ~~feat: implement cast, right, left, replace expressions (follow-up to #880)~~ feat: implement cast, right, left, replace expressions Jul 5, 2025

cj848 force-pushed the feature/implement-cast-right-left-replace branch from 965d3e9 to b0d1e84 Compare July 5, 2025 01:52

feat: implement cast, right, left, replace expressions

1ccf936

cj848 force-pushed the feature/implement-cast-right-left-replace branch from b0d1e84 to 1ccf936 Compare July 5, 2025 01:53

shouwn reviewed Jul 14, 2025

View reviewed changes

fix: apply reviews

bef6134

cj848 force-pushed the feature/implement-cast-right-left-replace branch from 79ac669 to 0602e9d Compare July 19, 2025 10:12

fix: apply reviews

77cb87f

cj848 force-pushed the feature/implement-cast-right-left-replace branch from 0602e9d to 77cb87f Compare July 19, 2025 10:17

shouwn approved these changes Jul 23, 2025

View reviewed changes

cj848 added 2 commits July 24, 2025 12:40

fix: apply review

ff21748

Merge branch 'develop' of https://github.com/cj848/kotlin-jdsl into f…

ae90af2

…eature/implement-cast-right-left-replace # Conflicts: # query-model/jpql/src/main/kotlin/com/linecorp/kotlinjdsl/querymodel/jpql/expression/Expressions.kt

cj848 merged commit 8f3564a into line:develop Jul 24, 2025
4 checks passed

cj848 deleted the feature/implement-cast-right-left-replace branch July 24, 2025 03:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: implement cast, right, left, replace expressions #894

feat: implement cast, right, left, replace expressions #894

Uh oh!

cj848 commented Jul 5, 2025 •

edited

Loading

Uh oh!

codecov-commenter commented Jul 5, 2025 •

edited

Loading

Uh oh!

shouwn Jul 14, 2025

Uh oh!

shouwn Jul 14, 2025

Uh oh!

cj848 Jul 19, 2025 •

edited

Loading

Uh oh!

shouwn Jul 14, 2025

Uh oh!

cj848 Jul 18, 2025

Uh oh!

shouwn Jul 14, 2025

Uh oh!

cj848 Jul 18, 2025

Uh oh!

shouwn left a comment

Uh oh!

shouwn Jul 23, 2025

Uh oh!

cj848 Jul 24, 2025

Uh oh!

Uh oh!

Uh oh!

		@SinceJdsl("3.6.0")
		data class JpqlCast<T : Any> internal constructor(

feat: implement cast, right, left, replace expressions #894

feat: implement cast, right, left, replace expressions #894

Uh oh!

Conversation

cj848 commented Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Modifications

Result

Closes

동기

수정 사항

결과

닫는 이슈

Uh oh!

codecov-commenter commented Jul 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cj848 Jul 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shouwn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cj848 commented Jul 5, 2025 •

edited

Loading

codecov-commenter commented Jul 5, 2025 •

edited

Loading

cj848 Jul 19, 2025 •

edited

Loading