integrate macros within ElasticClientApi

Author: fupelaqu

build.sbt

@@ -158,7 +158,11 @@ lazy val core = project
   .configs(IntegrationTest)
   .settings(
     Defaults.itSettings,
-    moduleSettings
+    moduleSettings,
+    scalacOptions ++= Seq(
+      "-language:experimental.macros",
+      "-Ymacro-debug-lite"
+    )
   )
   .dependsOn(
     macros % "compile->compile;test->test;it->it"
@@ -213,6 +217,10 @@ def testkitProject(esVersion: String, ss: Def.SettingsDefinition*): Project = {
       Defaults.itSettings,
       app.softnetwork.Info.infoSettings,
       moduleSettings,
+      scalacOptions ++= Seq(
+        "-language:experimental.macros",
+        "-Ymacro-debug-lite"
+      ),
       elasticSearchVersion := esVersion,
       buildInfoKeys += BuildInfoKey("elasticVersion" -> elasticSearchVersion.value),
       buildInfoObject := "SoftClient4esCoreTestkitBuildInfo",

core/src/main/scala/app/softnetwork/elastic/client/ElasticClientDelegator.scala

@@ -521,9 +521,9 @@ trait ElasticClientDelegator extends ElasticClientApi with BulkTypes {
     *   true if the entity was indexed successfully, false otherwise
     */
   override def index(
-    index: JSONResults,
-    id: JSONResults,
-    source: JSONResults,
+    index: String,
+    id: String,
+    source: String,
     wait: Boolean = false
   ): ElasticResult[Boolean] =
     delegate.index(index, id, source, wait)
@@ -990,9 +990,10 @@ trait ElasticClientDelegator extends ElasticClientApi with BulkTypes {
     * @return
     *   the entities matching the query
     */
-  override def searchAs[U](
+  override def searchAsUnchecked[U](
     sqlQuery: SQLQuery
-  )(implicit m: Manifest[U], formats: Formats): ElasticResult[Seq[U]] = delegate.searchAs(sqlQuery)
+  )(implicit m: Manifest[U], formats: Formats): ElasticResult[Seq[U]] =
+    delegate.searchAsUnchecked(sqlQuery)
 
   /** Searches and converts results into typed entities.
     *
@@ -1035,6 +1036,9 @@ trait ElasticClientDelegator extends ElasticClientApi with BulkTypes {
     delegate.multisearchAs(elasticQueries, fieldAliases, aggregations)
 
   /** Asynchronous search with conversion to typed entities.
+    *
+    * @note
+    *   This method is a variant of searchAsyncAs without compile-time SQL validation.
     *
     * @param sqlQuery
     *   the SQL query
@@ -1043,11 +1047,12 @@ trait ElasticClientDelegator extends ElasticClientApi with BulkTypes {
     * @return
     *   a Future containing the entities
     */
-  override def searchAsyncAs[U](sqlQuery: SQLQuery)(implicit
+  override def searchAsyncAsUnchecked[U](sqlQuery: SQLQuery)(implicit
     m: Manifest[U],
     ec: ExecutionContext,
     formats: Formats
-  ): Future[ElasticResult[Seq[U]]] = delegate.searchAsyncAs(sqlQuery)
+  ): Future[ElasticResult[Seq[U]]] =
+    delegate.searchAsyncAsUnchecked(sqlQuery)
 
   /** Asynchronous search with conversion to typed entities.
     *
@@ -1150,13 +1155,32 @@ trait ElasticClientDelegator extends ElasticClientApi with BulkTypes {
     system: ActorSystem
   ): Source[(Map[String, Any], ScrollMetrics), NotUsed] = delegate.scroll(sql, config)
 
-  /** Typed scroll source
+  /** Scroll and convert results into typed entities from an SQL query.
+    *
+    * @note
+    *   This method is a variant of scrollAs without compile-time SQL validation.
+    *
+    * @param sql
+    *   - SQL query
+    * @param config
+    *   - Scroll configuration
+    * @param system
+    *   - Actor system
+    * @param m
+    *   - Manifest for type T
+    * @param formats
+    *   - JSON formats
+    * @tparam T
+    *   - Target type
+    * @return
+    *   - Source of tuples (T, ScrollMetrics)
     */
-  override def scrollAs[T](sql: SQLQuery, config: ScrollConfig)(implicit
+  override def scrollAsUnchecked[T](sql: SQLQuery, config: ScrollConfig)(implicit
     system: ActorSystem,
     m: Manifest[T],
     formats: Formats
-  ): Source[(T, ScrollMetrics), NotUsed] = delegate.scrollAs(sql, config)
+  ): Source[(T, ScrollMetrics), NotUsed] =
+    delegate.scrollAsUnchecked(sql, config)
 
   override private[client] def scrollClassic(
     elasticQuery: ElasticQuery,

core/src/main/scala/app/softnetwork/elastic/client/ScrollApi.scala

@@ -27,11 +27,13 @@ import app.softnetwork.elastic.client.scroll.{
   UseScroll,
   UseSearchAfter
 }
+import app.softnetwork.elastic.sql.macros.SQLQueryMacros
 import app.softnetwork.elastic.sql.query.{SQLAggregation, SQLQuery}
 import org.json4s.{Formats, JNothing}
 import org.json4s.jackson.JsonMethods.parse
 
 import scala.concurrent.{ExecutionContext, Promise}
+import scala.language.experimental.macros
 import scala.util.{Failure, Success}
 
 /** API for scrolling through search results using Akka Streams.
@@ -167,9 +169,57 @@ trait ScrollApi extends ElasticClientHelpers {
     hasSorts: Boolean = false
   )(implicit system: ActorSystem): Source[Map[String, Any], NotUsed]
 
-  /** Typed scroll source
+  /** Typed scroll source converting results into typed entities from an SQL query
+    *
+    * @note
+    *   This method provides compile-time SQL validation via macros.
+    *
+    * @param sql
+    *   - SQL query
+    * @param config
+    *   - Scroll configuration
+    * @param system
+    *   - Actor system
+    * @param m
+    *   - Manifest for type T
+    * @param formats
+    *   - JSON formats
+    * @tparam T
+    *   - Target type
+    * @return
+    *   - Source of tuples (T, ScrollMetrics)
     */
   def scrollAs[T](
+    sql: String,
+    config: ScrollConfig = ScrollConfig()
+  )(implicit
+    system: ActorSystem,
+    m: Manifest[T],
+    formats: Formats
+  ): Source[(T, ScrollMetrics), NotUsed] =
+    macro SQLQueryMacros.scrollAsImpl[T]
+
+  /** Scroll and convert results into typed entities from an SQL query.
+    *
+    * @note
+    *   This method is a variant of scrollAs without compile-time SQL validation.
+    *
+    * @param sql
+    *   - SQL query
+    * @param config
+    *   - Scroll configuration
+    * @param system
+    *   - Actor system
+    * @param m
+    *   - Manifest for type T
+    * @param formats
+    *   - JSON formats
+    * @tparam T
+    *   - Target type
+    * @return
+    *   - Source of tuples (T, ScrollMetrics)
+    */
+  def scrollAsUnchecked[T](
     sql: SQLQuery,
     config: ScrollConfig = ScrollConfig()
   )(implicit

core/src/main/scala/app/softnetwork/elastic/client/SearchApi.scala

@@ -22,12 +22,14 @@ import app.softnetwork.elastic.client.result.{
   ElasticResult,
   ElasticSuccess
 }
+import app.softnetwork.elastic.sql.macros.SQLQueryMacros
 import app.softnetwork.elastic.sql.query.{SQLAggregation, SQLQuery, SQLSearchRequest}
 import com.google.gson.{Gson, JsonElement, JsonObject, JsonParser}
 import org.json4s.Formats
 
 import scala.concurrent.{ExecutionContext, Future}
 import scala.jdk.CollectionConverters._
+import scala.language.experimental.macros
 import scala.reflect.{classTag, ClassTag}
 import scala.util.{Failure, Success, Try}
 
@@ -400,14 +402,34 @@ trait SearchApi extends ElasticConversion with ElasticClientHelpers {
 
   /** Searches and converts results into typed entities from an SQL query.
     *
-    * @param sqlQuery
+    * @note
+    *   This method uses compile-time macros to validate the SQL query against the type U.
+    *
+    * @param query
     *   the SQL query containing fieldAliases and aggregations
     * @tparam U
     *   the type of entities to return
     * @return
     *   the entities matching the query
     */
   def searchAs[U](
+    query: String
+  )(implicit m: Manifest[U], formats: Formats): ElasticResult[Seq[U]] =
+    macro SQLQueryMacros.searchAsImpl[U]
+
+  /** Searches and converts results into typed entities from an SQL query.
+    *
+    * @note
+    *   This method is a variant of searchAs without compile-time SQL validation.
+    *
+    * @param sqlQuery
+    *   the SQL query containing fieldAliases and aggregations
+    * @tparam U
+    *   the type of entities to return
+    * @return
+    *   the entities matching the query
+    */
+  def searchAsUnchecked[U](
     sqlQuery: SQLQuery
   )(implicit m: Manifest[U], formats: Formats): ElasticResult[Seq[U]] = {
     for {
@@ -473,14 +495,38 @@ trait SearchApi extends ElasticConversion with ElasticClientHelpers {
 
   /** Asynchronous search with conversion to typed entities.
     *
-    * @param sqlQuery
+    * @note
+    *   This method uses compile-time macros to validate the SQL query against the type U.
+    *
+    * @param query
     *   the SQL query
     * @tparam U
     *   the type of entities to return
     * @return
     *   a Future containing the entities
     */
   def searchAsyncAs[U](
+    query: String
+  )(implicit
+    m: Manifest[U],
+    ec: ExecutionContext,
+    formats: Formats
+  ): Future[ElasticResult[Seq[U]]] =
+    macro SQLQueryMacros.searchAsyncAsImpl[U]
+
+  /** Asynchronous search with conversion to typed entities.
+    *
+    * @note
+    *   This method is a variant of searchAsyncAs without compile-time SQL validation.
+    *
+    * @param sqlQuery
+    *   the SQL query
+    * @tparam U
+    *   the type of entities to return
+    * @return
+    *   a Future containing the entities
+    */
+  def searchAsyncAsUnchecked[U](
     sqlQuery: SQLQuery
   )(implicit
     m: Manifest[U],

core/src/main/scala/app/softnetwork/elastic/client/metrics/MetricsElasticClient.scala

@@ -663,14 +663,17 @@ class MetricsElasticClient(
     * @return
     *   the entities matching the query
     */
-  override def searchAs[U](
+  override def searchAsUnchecked[U](
     sqlQuery: SQLQuery
   )(implicit m: Manifest[U], formats: Formats): ElasticResult[Seq[U]] =
     measureResult("searchAs") {
-      delegate.searchAs[U](sqlQuery)
+      delegate.searchAsUnchecked[U](sqlQuery)
     }
 
   /** Asynchronous search with conversion to typed entities.
+    *
+    * @note
+    *   This method is a variant of searchAsyncAs without compile-time SQL validation.
     *
     * @param sqlQuery
     *   the SQL query
@@ -679,13 +682,13 @@ class MetricsElasticClient(
     * @return
     *   a Future containing the entities
     */
-  override def searchAsyncAs[U](sqlQuery: SQLQuery)(implicit
+  override def searchAsyncAsUnchecked[U](sqlQuery: SQLQuery)(implicit
     m: Manifest[U],
     ec: ExecutionContext,
     formats: Formats
   ): Future[ElasticResult[Seq[U]]] =
     measureAsync("searchAsyncAs") {
-      delegate.searchAsyncAs[U](sqlQuery)
+      delegate.searchAsyncAsUnchecked[U](sqlQuery)
     }
 
   override def singleSearch(
@@ -900,16 +903,33 @@ class MetricsElasticClient(
 
   }
 
-  /** Typed scroll source
+  /** Scroll and convert results into typed entities from an SQL query.
+    *
+    * @note
+    *   This method is a variant of scrollAs without compile-time SQL validation.
+    * @param sql
+    *   - SQL query
+    * @param config
+    *   - Scroll configuration
+    * @param system
+    *   - Actor system
+    * @param m
+    *   - Manifest for type T
+    * @param formats
+    *   - JSON formats
+    * @tparam T
+    *   - Target type
+    * @return
+    *   - Source of tuples (T, ScrollMetrics)
     */
-  override def scrollAs[T](sql: SQLQuery, config: ScrollConfig)(implicit
+  override def scrollAsUnchecked[T](sql: SQLQuery, config: ScrollConfig)(implicit
     system: ActorSystem,
     m: Manifest[T],
     formats: Formats
   ): Source[(T, ScrollMetrics), NotUsed] = {
     // Note: For streams, we measure at the beginning but not every element
     val startTime = System.currentTimeMillis()
-    val source = delegate.scrollAs[T](sql, config)
+    val source = delegate.scrollAsUnchecked[T](sql, config)
 
     source.watchTermination() { (_, done) =>
       done.onComplete { result =>

macros/src/main/scala/app/softnetwork/elastic/client/macros/TestElasticClientApi.scala

@@ -1,3 +1,19 @@
+/*
+ * Copyright 2025 SOFTNETWORK
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package app.softnetwork.elastic.client.macros
 
 import app.softnetwork.elastic.sql.macros.SQLQueryMacros