documentation update

README.md

@@ -1,18 +1,92 @@
-# .Net library with helpers, functions and extensions
+# Just.Core
 
-Just some stuff that is used in different projects...
+Small .NET library with useful helper classes, functions, and extensions — stuff used across multiple projects.
+
+[![NuGet](https://img.shields.io/nuget/v/Just.Core)](https://www.nuget.org/packages/Just.Core)
+
+## Install
+
+```sh
+dotnet add package Just.Core
+```
 
 ## Features
 
-- ```Map``` and ```DataMap``` collection types
-- Extensions for ```System.String``` and ```System.IO.Stream```
-- Small converters for **Base32** and **Base64Url** encodings
-  
-## Getting Started
+### Encoding
 
-### Install from NuGet.org
+**Base32** — RFC 4648 encoder/decoder with lowercase and no-padding options.
 
-```sh
-# install the package using NuGet
-dotnet add package Just.Core
+```csharp
+var encoded = Base32.Encode(bytes);                           // "ABCDEFGH..."
+var encoded = Base32.Encode(bytes, Base32EncodeOptions.LowerCaseNoPadding);
+var bytes   = Base32.Decode("ABCDEFGH...");
 ```
+
+**Base64Url** — URL-safe Base64 for bytes, `long`, and `Guid`.
+
+```csharp
+var str  = Base64Url.Encode(myGuid);           // "5QrdUxDUVkCAEGw8pvLsEw"
+var guid = Base64Url.DecodeGuid(str);
+var str  = Base64Url.Encode(123456789L);       // "7NcVAAAAAA"
+var val  = Base64Url.DecodeLong(str);
+```
+
+### IDs
+
+**SeqId** — Time-based 64-bit sequential ID with configurable entropy. Thread-safe.
+
+```csharp
+var id = SeqId.NextId();                       // default instance, Strong entropy
+var id = SeqId.NextId(RngEntropy.Weak);        // faster, less collision-resistant
+
+// Custom epoch
+var generator = new SeqId(new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc));
+var id = generator.Next();
+```
+
+Structure: `[1 bit reserved][41 bits ms since epoch][8 bits sequence][14 bits random]`
+
+**GuidV8** — Time-sortable UUID v8 with extractable timestamp.
+
+```csharp
+var guid = GuidV8.NewGuid();                   // current UTC, Strong entropy
+var guid = GuidV8.NewGuid(specificTime);
+var when = GuidV8.ExtractTimestamp(guid);      // recover timestamp (100µs precision)
+```
+
+### Collections
+
+**Map<T> / DataMap<T>** — 2D grid container with indexing, enumeration, and min/max.
+
+```csharp
+var map = new Map<int>(width: 10, height: 10, values);
+var value = map[3, 5];                         // integer or double coordinates
+var point = map.Get(3.5, 5.2);                 // MapPoint<T> with position metadata
+
+var dmap = new DataMap<double>(values, 10, 10);
+var min = dmap.Min;                            // MapPoint<double> — cached
+var max = dmap.Max;                            // lazy, thread-safe on first access
+
+// Stream serialization (sync + async)
+dmap.WriteToStream(stream);
+var copy = DataMap.ReadFromStream<double>(stream);
+```
+
+**ImmutableSequence&lt;T&gt;** — Immutable list with structural value equality.
+
+```csharp
+var seq = new ImmutableSequence<int>([1, 2, 3]);
+var seq2 = seq.Add(4);                         // new instance, seq unchanged
+seq == seq2;                                   // false — 3 vs 4 elements
+new ImmutableSequence<int>([1, 2, 3]) == seq;  // true — value equality
+```
+
+## Supported Targets
+
+- .NET 8.0 (LTS)
+- .NET 9.0
+- .NET 10.0
+
+## License
+
+MIT — see [LICENSE](LICENSE).