refactor: integrate PayloadTransform for encryption in Examples test and update README

Author: rasros

README.md

@@ -102,14 +102,16 @@ composing three layers:
 
 1. Binary Layer: PackedFormat (default) or ProtoBuf (recommended for
    cross-language compatibility).
-2. Checksum Layer: Optional Crc16 or Crc32 appended to the binary payload.
+2. Transform Layer: Optional `PayloadTransform` applied after serialization —
+   use `Checksum.asTransform()` for integrity checks, or supply your own for
+   encryption or error-correcting codes.
 3. Text Layer: Base62 (default), Base36, Base64, or Base85.
 
 ```kotlin
 val customFormat = EncodedFormat {
-    codec = Base36          // Use Base36 instead of Base62 (for lowercase)
-    checksum = Crc16        // Append a 2-byte checksum
-    binaryFormat = ProtoBuf // Use ProtoBuf instead of PackedFormat (or the compactFormat from previous example)
+    codec = Base36                  // Use Base36 instead of Base62 (for lowercase)
+    checksum = Crc16                // Convenience shorthand for transform = Crc16.asTransform()
+    binaryFormat = ProtoBuf         // Use ProtoBuf instead of PackedFormat
 }
 
 val token = customFormat.encodeToString(payload)
@@ -132,20 +134,23 @@ implementations support custom alphabets.
 
 ## Encryption
 
-Typical confidential payload pattern:
+Wrap a cipher as a `PayloadTransform` and pass it to `EncodedFormat`:
 
 ```kotlin
 @Serializable
 data class SecretPayload(val id: Long)
 
-// 1. Serialize
-val binary = PackedFormat.encodeToByteArray(payload)
+val encryptingTransform = object : PayloadTransform {
+    override fun encode(data: ByteArray): ByteArray = cipher.encrypt(data)
+    override fun decode(data: ByteArray): ByteArray = cipher.decrypt(data)
+}
 
-// 2. Encrypt (e.g., AES or XTEA)
-val encrypted = cipher.doFinal(binary)
+val secureFormat = EncodedFormat {
+    transform = encryptingTransform
+}
 
-// 3. Encode to Text
-val token = Base62.encode(encrypted)
+val token = secureFormat.encodeToString(SecretPayload.serializer(), payload)
+val decoded = secureFormat.decodeFromString(SecretPayload.serializer(), token)
 ```
 
 See [Examples](https://github.com/Eignex/kencode/blob/main/src/test/kotlin/com/eignex/kencode/Examples.kt)

src/jvmTest/kotlin/com/eignex/kencode/Examples.kt

@@ -19,7 +19,7 @@ class Examples {
     // Exmaple from readme
 
     @Serializable
-    data class Payload constructor(
+    data class Payload(
 
         // only uses as many bytes as needed
         @PackedType(PackedIntegerType.DEFAULT)
@@ -91,38 +91,39 @@ class Examples {
 
     @Test
     fun `encryption serialization`() {
-
-        // Initialization
         Security.addProvider(BouncyCastleProvider())
         val random = SecureRandom()
 
         // This key is stored permanently so we can read payloads after jvm restart
         val keyBytes = ByteArray(16)
         random.nextBytes(keyBytes)
         val key = SecretKeySpec(keyBytes, "XTEA")
-        val cipher = Cipher.getInstance("XTEA/CTR/NoPadding", "BC")
 
-        // Encrypt one payload
-        // we use 8 bytes as the initialization vector
+        // Wrap XTEA/CTR as a PayloadTransform.
+        // Each encode prepends a fresh 8-byte IV; decode reads it back.
+        val xteaTransform = object : PayloadTransform {
+            override fun encode(data: ByteArray): ByteArray {
+                val iv = ByteArray(8).also { random.nextBytes(it) }
+                val cipher = Cipher.getInstance("XTEA/CTR/NoPadding", "BC")
+                cipher.init(Cipher.ENCRYPT_MODE, key, IvParameterSpec(iv))
+                return iv + cipher.doFinal(data)
+            }
+
+            override fun decode(data: ByteArray): ByteArray {
+                val iv = data.copyOfRange(0, 8)
+                val cipher = Cipher.getInstance("XTEA/CTR/NoPadding", "BC")
+                cipher.init(Cipher.DECRYPT_MODE, key, IvParameterSpec(iv))
+                return cipher.doFinal(data.copyOfRange(8, data.size))
+            }
+        }
+
+        val secureFormat = EncodedFormat { transform = xteaTransform }
+
         val payload = SensitiveData(random.nextLong())
-        val iv8 = ByteArray(8)
-        random.nextBytes(iv8)
-        cipher.init(Cipher.ENCRYPT_MODE, key, IvParameterSpec(iv8))
-
-        // This particular encryption adds 16-bytes in an initialization vector
-        // regardless of how big the payload is.
-        val encrypted =
-            iv8 + cipher.doFinal(PackedFormat.encodeToByteArray(payload))
-        val encoded = Base62.encode(encrypted)
-        println(encoded)
+        val token = secureFormat.encodeToString(SensitiveData.serializer(), payload)
+        println(token)
 
-        // This recovers the initial payload
-        val iv8received = encrypted.copyOfRange(0, 8)
-        val received = encrypted.copyOfRange(8, encrypted.size)
-        cipher.init(Cipher.DECRYPT_MODE, key, IvParameterSpec(iv8received))
-        val decoded = Base62.decode(encoded)
-        val decrypted = cipher.doFinal(received)
-        val result: SensitiveData = PackedFormat.decodeFromByteArray(decrypted)
+        val result = secureFormat.decodeFromString(SensitiveData.serializer(), token)
         println(result)
 
         assertEquals(payload, result)