Skip to content

Commit 923c01f

Browse files
committed
docs: trim README and link to technical deep dive
1 parent c6dfe92 commit 923c01f

1 file changed

Lines changed: 19 additions & 21 deletions

File tree

README.md

Lines changed: 19 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ KEncode provides three standalone entry points:
3333
3. **EncodedFormat**: A string format serializer that wraps the above to produce
3434
small deterministic string identifiers.
3535

36+
For a walkthrough of the bit-packing layout and design choices, see the
37+
[technical deep dive](https://eignex.com/posts/kencode-packing-data-for-strict-limits/).
38+
3639
### Installation
3740

3841
```kotlin
@@ -71,19 +74,16 @@ val decoded = EncodedFormat.decodeFromString<Payload>(encoded)
7174

7275
## PackedFormat
7376

74-
PackedFormat is a BinaryFormat designed to produce the smallest feasible
75-
payloads for Kotlin classes by moving structural metadata into a compact header.
77+
PackedFormat is a `BinaryFormat` for Kotlin classes that emits compact byte
78+
payloads.
7679

77-
* Bit-Packing: Booleans and nullability markers are stored in a single
78-
bit-header (about 1 bit per field).
79-
* VarInts: Int/Long fields can be optimized using `@PackedType(IntPacking.DEFAULT)`
80-
(unsigned varint) or `@PackedType(IntPacking.SIGNED)` (ZigZag) annotations.
81-
The names match `kotlinx-serialization-protobuf`'s `ProtoIntegerType`, and
82-
`@ProtoType` annotations are recognized automatically as a fallback.
83-
* Full Graph Support: Handles nested objects, lists, maps, and polymorphism
84-
recursively. While this is supported it will not produce as compact
85-
representations as flat structures that can pack all metadata into the same
86-
header.
80+
* Bit-Packing: Booleans and nullability markers share a single bit-header
81+
(~1 bit per field).
82+
* VarInts: annotate `Int`/`Long` fields with `@PackedType(IntPacking.DEFAULT)`
83+
(unsigned varint) or `@PackedType(IntPacking.SIGNED)` (ZigZag). `@ProtoType`
84+
is recognized as a fallback.
85+
* Full Graph Support: nested objects, lists, maps, and polymorphism are
86+
handled recursively.
8787

8888
```kotlin
8989
val compactFormat = PackedFormat {
@@ -104,10 +104,9 @@ composing three layers:
104104

105105
1. Binary Layer: PackedFormat (default) or ProtoBuf (recommended for
106106
cross-language compatibility).
107-
2. Transform Layer: Optional `PayloadTransform` applied after serialization.
108-
Use `CompactZeros` to strip leading zero bytes, `Checksum.asTransform()` for
109-
integrity checks, or supply your own for encryption or error-correcting codes.
110-
Chain multiple transforms with `PayloadTransform.then`.
107+
2. Transform Layer: Optional `PayloadTransform` applied after serialization
108+
(e.g. `CompactZeros`, `Checksum.asTransform()`, or a custom transform for
109+
encryption or ECC). Chain transforms with `PayloadTransform.then`.
111110
3. Text Layer: Base62 (default), Base36, Base64, or Base85.
112111

113112
```kotlin
@@ -132,10 +131,9 @@ val withBoth = EncodedFormat {
132131
KEncode includes standalone codecs for byte-to-text conversion. All
133132
implementations support custom alphabets.
134133

135-
* Base62 / Base36: Uses fixed-block encoding for predictable lengths without
136-
padding. Main use is to have 100% alpha-numeric output, with or without
137-
upper-case.
138-
* Base85: High-density encoding (4 bytes to 5 characters).
134+
* Base62 / Base36: fixed-block encoding with predictable lengths and no
135+
padding; alpha-numeric output, with or without upper-case.
136+
* Base85: high-density encoding (4 bytes → 5 characters).
139137
* Base64 / Base64Url: RFC 4648 compatible.
140138

141139
Encoding `"any byte data"` (13 bytes):
@@ -175,7 +173,7 @@ val decoded = secureFormat.decodeFromString(SecretPayload.serializer(), token)
175173
```
176174

177175
See [EncryptionExample](https://github.com/Eignex/kencode/blob/main/src/jvmTest/kotlin/com/eignex/kencode/EncryptionExample.kt)
178-
for the full exapmle using BouncyCastle.
176+
for the full example using BouncyCastle.
179177

180178
### Error Correction
181179

0 commit comments

Comments
 (0)