Add type info to serialization format, move logic to dedicated serializer class, and improve test coverage

- Serialization now includes encoded type information to prevent cross-type deserialization.
- Moved serialization/deserialization logic to a dedicated `HllSerializer` class for better maintainability.
- Added guard clause to detect type mismatches during deserialization.
- Introduced unit test to verify type safety during deserialization.
- Updated internal documentation to reflect new format and structure.

Author: MCUnderground

HLL.NET.Examples/Program.cs

@@ -20,5 +20,4 @@
 Console.WriteLine($"Error:                  {Math.Abs(trueUniqueCount - estimatedCount) / trueUniqueCount:P2}");
 
 
-
 AccuracyTester.RunAllTests();

HLL.NET.Tests/HyperLogLogSerializationTests.cs

@@ -47,6 +47,23 @@ public void Deserialize_UnsupportedVersion_ShouldThrow()
             Assert.Throws<NotSupportedException>(() =>
                 HyperLogLog<string>.Deserialize(data, _stringHasher));
         }
+
+        [Fact]
+        public void Deserialize_WrongType_ShouldThrow()
+        {
+            var stringHasher = new StringHasher();
+            var intHasher = new IntHasher(); // Assume you have one
+
+            var hllString = new HyperLogLog<string>(new HllPrecision(14), stringHasher);
+            hllString.Add("test");
+
+            byte[] serialized = hllString.Serialize();
+
+            // Attempt to deserialize as HyperLogLog<int>
+            Assert.Throws<InvalidOperationException>(() =>
+                HyperLogLog<int>.Deserialize(serialized, intHasher));
+        }
+
     }
 }
 

HLL.NET.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
-VisualStudioVersion = 17.13.35919.96 d17.13
+VisualStudioVersion = 17.13.35919.96
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HLL.NET", "HLL.NET\HLL.NET.csproj", "{E44905AB-CE39-4D45-82A8-938D58DDE890}"
 EndProject
@@ -15,6 +15,11 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "HLL.NET.Examples", "HLL.NET
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "examples", "examples", "{CD93B0C7-3D16-41EE-93B3-BD1E08FB9117}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{3699A8BF-2E93-4E00-8C78-6287149E7846}"
+	ProjectSection(SolutionItems) = preProject
+		serialization_format.md = serialization_format.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU

HLL.NET/HLL.NET.csproj

@@ -3,7 +3,7 @@
 	<PropertyGroup>
 		<TargetFramework>netstandard2.0</TargetFramework>
 		<PackageId>HLL.NET</PackageId>
-		<Version>1.0.3</Version>
+		<Version>1.0.4</Version>
 		<Authors>MCUnderground</Authors>
 		<Description>A simple and efficient C# implementation of HyperLogLog for approximate cardinality estimation.</Description>
 		<PackageLicenseExpression>MIT</PackageLicenseExpression>

HLL.NET/HyperLogLog.cs

@@ -3,11 +3,16 @@
 using System.Linq;
 using System;
 using HLL.NET.Maths;
+using System.Text;
+using HLL.NET.Serialization;
 
 namespace HLL.NET
 {
     public class HyperLogLog<T> 
     {
+        internal HllRegister[] Registers => _registers;
+        internal HllPrecision Precision => _precision;
+
         private readonly HllPrecision _precision;
         private readonly int _numRegisters;
         private readonly HllRegister[] _registers;
@@ -74,36 +79,9 @@ private double GetAlphaMM()
                 default: return (0.7213 / (1 + 1.079 / _numRegisters)) * _numRegisters * _numRegisters;
             }
         }
+        public byte[] Serialize() => HllSerializer.Serialize(this);
 
-        const byte FormatVersion = 1;
-
-        public byte[] Serialize()
-        {
-            var data = new byte[3 + _registers.Length]; // version + hasherId + precision + registers
-            data[0] = FormatVersion;
-            data[1] = (byte)_precision.Value;
-            for (int i = 0; i < _registers.Length; i++)
-                data[i + 2] = _registers[i].Value;
-
-            return data;
-        }
-        public static HyperLogLog<T> Deserialize(byte[] data, IHasher<T> hasher)
-        {
-            if (data == null || data.Length < 4)
-                throw new ArgumentException("Invalid serialized data");
-
-            var version = data[0];
-            var precision = new HllPrecision(data[1]);
-
-            if (version != FormatVersion)
-                throw new NotSupportedException($"Unsupported HLL format version: {version}");
-
-            var hll = new HyperLogLog<T>(precision, hasher);
-            for (int i = 0; i < hll._registers.Length; i++)
-                hll._registers[i] = new HllRegister(data[i + 2]);
-
-            return hll;
-        }
-
+        public static HyperLogLog<T> Deserialize(byte[] data, IHasher<T> hasher) =>
+            HllSerializer.Deserialize<T>(data, hasher);
     }
 }

HLL.NET/Serialization/HllSerializer.cs

@@ -0,0 +1,90 @@
+using HLL.NET.Hashing;
+using HLL.NET.Models;
+using System;
+using System.Text;
+
+namespace HLL.NET.Serialization
+{
+
+    //docs/serialization_format.md
+    internal static class HllSerializer
+    {
+        private const byte FormatVersion = 2;
+
+        public static byte[] Serialize<T>(HyperLogLog<T> hll)
+        {
+            var typeNameBytes = EncodeTypeName(typeof(T));
+            byte typeNameLength = (byte)typeNameBytes.Length;
+
+            var data = new byte[1 + 1 + typeNameLength + 1 + hll.Registers.Length];
+            int index = 0;
+
+            data[index++] = FormatVersion;
+            data[index++] = typeNameLength;
+            Array.Copy(typeNameBytes, 0, data, index, typeNameLength);
+            index += typeNameLength;
+
+            data[index++] = (byte)hll.Precision.Value;
+            WriteRegisters(hll, data, ref index);
+
+            return data;
+        }
+
+        public static HyperLogLog<T> Deserialize<T>(byte[] data, IHasher<T> hasher)
+        {
+            if (data == null || data.Length < 4)
+                throw new ArgumentException("Invalid serialized data");
+
+            int index = 0;
+
+            ValidateVersion(data[index++]);
+
+            var typeName = ReadTypeName(data, ref index);
+            EnsureCorrectType<T>(typeName);
+
+            var precision = new HllPrecision(data[index++]);
+            var hll = new HyperLogLog<T>(precision, hasher);
+
+            ReadRegisters(hll, data, ref index);
+
+            return hll;
+        }
+
+
+        private static byte[] EncodeTypeName(Type type) =>
+            Encoding.UTF8.GetBytes(type.FullName);
+
+        private static void WriteRegisters<T>(HyperLogLog<T> hll, byte[] data, ref int index)
+        {
+            foreach (var reg in hll.Registers)
+                data[index++] = reg.Value;
+        }
+
+        private static void ReadRegisters<T>(HyperLogLog<T> hll, byte[] data, ref int index)
+        {
+            for (int i = 0; i < hll.Registers.Length; i++)
+                hll.Registers[i] = new HllRegister(data[index++]);
+        }
+
+        private static void ValidateVersion(byte version)
+        {
+            if (version != FormatVersion)
+                throw new NotSupportedException($"Unsupported HLL format version: {version}");
+        }
+
+        private static string ReadTypeName(byte[] data, ref int index)
+        {
+            var length = data[index++];
+            var typeName = Encoding.UTF8.GetString(data, index, length);
+            index += length;
+            return typeName;
+        }
+
+        private static void EnsureCorrectType<T>(string serializedTypeName)
+        {
+            var expected = typeof(T).FullName;
+            if (serializedTypeName != expected)
+                throw new InvalidOperationException($"Type mismatch. Serialized for '{serializedTypeName}', but deserializing as '{expected}'.");
+        }
+    }
+}

README.md

@@ -16,15 +16,6 @@ A fast and memory-efficient implementation of the [HyperLogLog](https://en.wikip
 - 🧱 Configurable precision (4–16) with built-in validation
 - 💼 Fully compatible with .NET Standard for broad platform support
 
----
-
-## 📦 Installation
-
-```bash
-dotnet add package HLL.NET
-```
-
----
 
 
 ### ✅ Accuracy Highlights (based on benchmark tests)
@@ -39,6 +30,15 @@ Handles duplicate values correctly, estimating only **unique** cardinality. Exam
 - Input: 10,000 identical values
 - Estimated: ~10,000 (error: <1%)
 
+---
+
+## 📦 Installation
+
+```bash
+dotnet add package HLL.NET
+```
+
+---
 
 ## 🧑‍💻 Usage
 

serialization_format.md

@@ -0,0 +1,34 @@
+# HyperLogLog Serialization Format (HLL.NET)
+
+This document describes the binary format used for serializing `HyperLogLog<T>` instances.
+
+## Format Structure
+
+The serialized data is a byte array with the following layout:
+
+| Offset | Size     | Description                                      |
+|--------|----------|--------------------------------------------------|
+| 0      | 1 byte   | Format version (currently `2`)                   |
+| 1      | 1 byte   | Type name length (`L`)                           |
+| 2      | 1 byte   | Precision value (`p`, between 4–16)              |
+| 3      | `L`      | UTF-8 encoded full type name (`typeof(T).FullName`) |
+| 3+L    | N bytes  | HLL registers (one byte per register; length = `2^p`) |
+
+### Example
+
+For a `HyperLogLog<string>` with precision 14:
+
+- Format version = `2`
+- Type name = `System.String`, which has length = `13`
+- Registers count = `2^14 = 16384`
+- Total bytes = `1 + 1 + 1 + 13 + 16384 = 16400 bytes`
+
+## Versioning
+
+- Current format version: `2`
+- Future versions must increment the first byte and adjust parsing logic accordingly.
+
+## Notes
+
+- If the deserialized type `T` does not match the stored type name, deserialization will fail.
+- Type names are used to avoid logic errors when deserializing to the wrong generic type.