develop

README.md

@@ -100,6 +100,73 @@ val selectQuery = QuerySelect.builder("users")
     selectQuery.limit(10, 5) 
 
 val sqlString = selectQuery.asSql()
+
+### ⬆️ ORDER BY
+
+Para ordenar los resultados puedes utilizar el método `orderBy` con `OrderBy.Asc`, `OrderBy.Desc` o una lista mediante `OrderBy.Multiple`.
+
+`OrderBy.Asc` y `OrderBy.Desc` aceptan tres parámetros:
+
+| Parámetro   | Tipo                   | Descripción |
+|-------------|------------------------|-------------|
+| `column`    | `String`               | Nombre de la columna. |
+| `collation` | `Collation`            | Cláusula COLLATE que se añade **al final** de la expresión (por defecto `Collation.NONE`). |
+| `transform` | `(String) -> String`   | Función que envuelve la columna en SQL arbitrario (REPLACE, LOWER, etc.). Se aplica **antes** del COLLATE. Por defecto es la identidad `{ it }`. |
+
+```kotlin
+// ORDER BY simple asc
+val q1 = QuerySelect.builder("users")
+    .where(SQLOperator.Equals("status", "active"))
+    .build()
+q1.orderBy(OrderBy.Asc("name")) // -> ORDER BY name ASC
+
+// ORDER BY con múltiples columnas y direcciones mezcladas
+q1.orderBy(OrderBy.Multiple(listOf(
+    OrderBy.Asc("department"),
+    OrderBy.Desc("created_at")
+))) // -> ORDER BY department ASC, created_at DESC
+
+// ORDER BY usando Collation (ej: NOCASE o RTRIM)
+q1.orderBy(OrderBy.Asc("name", collation = Collation.NOCASE))
+// -> ORDER BY name COLLATE NOCASE ASC
+
+q1.orderBy(OrderBy.Desc("name", collation = Collation.RTRIM))
+// -> ORDER BY RTRIM(name) DESC
+```
+
+#### 🔄 Transform + Collation
+
+Usa `transform` para aplicar funciones SQL sobre la columna (como `REPLACE`) y `collation` para
+el `COLLATE`. El `transform` envuelve la columna **antes** de que se añada el COLLATE,
+garantizando SQL correcto como:
+
+```sql
+SELECT * FROM vehicle
+ORDER BY REPLACE(identification, '-', '') COLLATE NOCASE ASC
+```
+
+> **Nota:** En SQLite, `LOWER()` no garantiza un ordenamiento case-insensitive correcto.
+> Usa siempre `COLLATE NOCASE` para ignorar mayúsculas/minúsculas al ordenar.
+
+```kotlin
+// Eliminar guiones e ignorar mayúsculas/minúsculas
+val strip = "-".removeCharsTransform()   // extensión de CollationUtils
+q1.orderBy(OrderBy.Asc("identification", collation = Collation.NOCASE, transform = strip))
+// -> ORDER BY REPLACE(identification, '-', '') COLLATE NOCASE ASC
+
+// Solo COLLATE NOCASE (sin transform)
+q1.orderBy(OrderBy.Asc("name", collation = Collation.NOCASE))
+// -> ORDER BY name COLLATE NOCASE ASC
+
+// Quitar espacios, guiones y puntos + COLLATE NOCASE
+val stripChars = " -.".removeCharsTransform()
+q1.orderBy(OrderBy.Asc("name", collation = Collation.NOCASE, transform = stripChars))
+// -> ORDER BY REPLACE(REPLACE(REPLACE(name, ' ', ''), '-', ''), '.', '') COLLATE NOCASE ASC
+
+// Combinar RTRIM + NOCASE con transform
+val stripDash = "-".removeCharsTransform()
+q1.orderBy(OrderBy.Asc("code", collation = Collation.RTRIM and Collation.NOCASE, transform = stripDash))
+// -> ORDER BY RTRIM(REPLACE(code, '-', '')) COLLATE NOCASE ASC
 ```
 
 ### ➕ INSERT

TESTING_GUIDELINES.md

@@ -0,0 +1,259 @@
+# Testing Guidelines for Agents
+
+## 1. Test Naming Convention
+
+Test names must follow **snake_case** format and clearly describe:
+- **What** is expected to happen (should)
+- **What behavior** is being tested
+- **When** that behavior occurs
+    - **Which method** is being tested (in_invoke, in_execute, etc.)
+
+### Format:
+```
+should_{action}_whent_{condition}_in_{method}
+```
+
+### Examples:
+```kotlin
+@Test
+fun should_remove_item_from_cart_when_quantity_is_zero_in_invoke()
+
+@Test
+fun should_throw_QuantityMustBePositive_when_quantity_is_negative_in_invoke()
+
+@Test
+fun should_update_quantity_when_quantity_is_valid_and_stock_is_sufficient_in_invoke()
+```
+
+## 2. Test Structure: Given-When-Then
+
+All tests must be divided into **3 clearly identified sections** with comments:
+
+```kotlin
+@Test
+fun should_do_something_when_condition_in_invoke() = runTest {
+    //GIVEN
+    // Preparation: variables, mocks, initial setup
+
+    //WHEN
+    // Execution: call to the method being tested
+
+    //THEN
+    // Verification: asserts and behavior verifications
+}
+```
+
+### Complete example:
+```kotlin
+@Test
+fun should_update_quantity_when_quantity_is_valid_and_stock_is_sufficient_in_invoke() = runTest {
+    //GIVEN
+    val productId = "1"
+    val quantity = 3
+    val product = productBuilder {
+        withId(productId)
+        withStock(5)
+    }
+    every { productRepository.getProductById(productId) } returns flowOf(product)
+
+    //WHEN
+    useCase.invoke(productId, quantity)
+
+    //THEN
+    coVerify { cartItemRepository.updateQuantity(productId, quantity) }
+}
+```
+
+## 3. Exception Testing
+
+To test exceptions, **use `runCatching`** to capture the result and verify the exception type:
+
+```kotlin
+@Test
+fun should_throw_QuantityMustBePositive_when_quantity_is_negative_in_invoke() = runTest {
+    //GIVEN
+    val productId = "1"
+    val quantity = -1
+
+    //WHEN
+    val result = runCatching { useCase.invoke(productId, quantity) }
+
+    //THEN
+    assert(result.exceptionOrNull() is AppError.Validation.QuantityMustBePositive)
+}
+```
+
+### Advantages of runCatching vs assertThrows:
+- More idiomatic in Kotlin
+- Allows easy inspection of exception properties
+- Cleaner and clearer syntax
+
+### Verifying exception properties:
+```kotlin
+@Test
+fun should_throw_InsufficientStock_when_quantity_exceeds_product_stock_in_invoke() = runTest {
+    //GIVEN
+    val productId = "1"
+    val quantity = 10
+    val product = productBuilder {
+        withId(productId)
+        withStock(5)
+    }
+    every { productRepository.getProductById(productId) } returns flowOf(product)
+
+    //WHEN
+    val result = runCatching { useCase.invoke(productId, quantity) }
+
+    //THEN
+    val exception = result.exceptionOrNull() as? AppError.Validation.InsufficientStock
+    assert(exception != null)
+    assertEquals(5, exception?.available)
+}
+```
+
+## 4. Builder Pattern for Object Creation
+
+To create test objects, **use the Builder pattern** with default values that allow easy creation of valid objects.
+
+### Location:
+Builders must be in a package named `builder` at the root of the corresponding test directory.
+
+Example path:
+```
+app/src/test/java/com/package/feature/domain/usecase/builder/
+```
+
+### Builder Structure:
+
+```kotlin
+class CartItemBuilder {
+    private var productId: String = "product-1"
+    private var quantity: Int = 2
+
+    fun withProductId(productId: String) = apply { this.productId = productId }
+    fun withQuantity(quantity: Int) = apply { this.quantity = quantity }
+
+    fun build(): CartItem {
+        return CartItem(productId, quantity)
+    }
+}
+
+fun cartItem(block: CartItemBuilder.() -> Unit): CartItem = 
+    CartItemBuilder().apply(block).build()
+```
+
+### Using the Builder in Tests:
+
+#### Case 1: Using default values
+```kotlin
+//GIVEN
+val cartItem = cartItem { }
+```
+
+#### Case 2: Customizing some values
+```kotlin
+//GIVEN
+val cartItem = cartItem {
+    withProductId("custom-id")
+    withQuantity(5)
+}
+```
+
+#### Case 3: Customizing only one value
+```kotlin
+//GIVEN
+val cartItem = cartItem {
+    withQuantity(10)
+}
+// productId will have the default value "product-1"
+```
+
+### Builder Pattern Advantages:
+- **Default values**: Tests are more concise, you only specify what matters
+- **Readability**: Code is self-documenting
+- **Maintainability**: If the model changes, you only update the builder
+- **Flexibility**: Easy to create different test scenarios
+
+## 5. Complete Test Example
+
+```kotlin
+class UpdateCartItemUseCaseTest {
+
+    private lateinit var cartItemRepository: CartItemRepository
+    private lateinit var productRepository: ProductRepository
+    private lateinit var useCase: UpdateCartItemUseCase
+
+    @Before
+    fun setUp() {
+        cartItemRepository = mockk(relaxed = true)
+        productRepository = mockk()
+        useCase = UpdateCartItemUseCase(cartItemRepository, productRepository)
+    }
+
+    @Test
+    fun should_throw_QuantityMustBePositive_when_quantity_is_negative_in_invoke() = runTest {
+        //GIVEN
+        val productId = "1"
+        val quantity = -1
+
+        //WHEN
+        val result = runCatching { useCase.invoke(productId, quantity) }
+
+        //THEN
+        assert(result.exceptionOrNull() is AppError.Validation.QuantityMustBePositive)
+    }
+
+    @Test
+    fun should_remove_item_from_cart_when_quantity_is_zero_in_invoke() = runTest {
+        //GIVEN
+        val productId = "1"
+        val quantity = 0
+
+        //WHEN
+        useCase.invoke(productId, quantity)
+
+        //THEN
+        coVerify { cartItemRepository.removeFromCart(productId) }
+        coVerify(exactly = 0) { cartItemRepository.updateQuantity(any(), any()) }
+    }
+
+    @Test
+    fun should_update_quantity_when_quantity_is_valid_and_stock_is_sufficient_in_invoke() = runTest {
+        //GIVEN
+        val productId = "1"
+        val quantity = 3
+        val product = productBuilder {
+            withId(productId)
+            withStock(5)
+        }
+        every { productRepository.getProductById(productId) } returns flowOf(product)
+
+        //WHEN
+        useCase.invoke(productId, quantity)
+
+        //THEN
+        coVerify { cartItemRepository.updateQuantity(productId, quantity) }
+    }
+}
+```
+
+## 6. Best Practices Summary
+
+✅ **DO:**
+- Use descriptive names in snake_case with `_in_{method}` suffix
+- Divide tests into GIVEN-WHEN-THEN
+- Use `runCatching` to capture exceptions
+- Use builders to create test objects
+- Define sensible default values in builders
+- Use `runTest` for tests with coroutines
+
+❌ **DON'T:**
+- Never include comments in the code
+- Use backticks in test names
+- Use `assertThrows` (prefer `runCatching`)
+- Create objects manually in each test
+- Use `mockk(relaxed = true)` for repositories 
+- Mix preparation, execution, and verification logic
+- Omit the method name in the test name
+
+

app/build.gradle.kts

@@ -2,7 +2,6 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
     alias(libs.plugins.android.application)
-    alias(libs.plugins.kotlin.android)
     alias(libs.plugins.kotlin.compose)
 }
 
@@ -35,15 +34,15 @@ android {
         sourceCompatibility = JavaVersion.VERSION_17
         targetCompatibility = JavaVersion.VERSION_17
     }
-    kotlin{
-        compilerOptions {
-            jvmTarget = JvmTarget.JVM_17
-        }
-    }
     buildFeatures {
         compose = true
     }
 }
+kotlin{
+    compilerOptions {
+        jvmTarget = JvmTarget.JVM_17
+    }
+}
 
 dependencies {
     implementation(libs.androidx.core.ktx)

build.gradle.kts

@@ -1,7 +1,8 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 plugins {
     alias(libs.plugins.android.application) apply false
-    alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.kotlin.compose) apply false
     alias(libs.plugins.android.library) apply false
-}
+}
+
+version = "0.13.3"

gradle.properties

@@ -20,4 +20,4 @@ kotlin.code.style=official
 # Enables namespacing of each library's R class so that its R class includes only the
 # resources declared in the library itself and none from the library's dependencies,
 # thereby reducing the size of the R class for that library
-android.nonTransitiveRClass=true
+android.nonTransitiveRClass=true