setup multiple dotnet versions

.gitea/workflows/publish-nuget.yaml

@@ -10,13 +10,16 @@ jobs:
   publish:
     runs-on: ubuntu-latest
 
+    env:
+      DOTNET_CLI_TELEMETRY_OPTOUT: true
+
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v5
 
     - name: Setup .NET
-      uses: https://github.com/actions/setup-dotnet@v3
+      uses: https://github.com/actions/setup-dotnet@v4
       with:
-        dotnet-version: 8.x
+        dotnet-version: 10.x
 
     - name: Restore dependencies
       run: dotnet restore Core/Core.csproj

.gitea/workflows/test-dotnet.yaml

@@ -14,28 +14,47 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    name: .NET tests
+
+    env:
+      DOTNET_CLI_TELEMETRY_OPTOUT: true
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v5
 
     - name: Setup .NET
-      uses: https://github.com/actions/setup-dotnet@v3
+      uses: https://github.com/actions/setup-dotnet@v4
       with:
-        dotnet-version: 8.x
+        dotnet-version: |
+          8.0.x
+          9.0.x
+          10.0.x
 
     - name: Restore dependencies
       run: dotnet restore
 
-    - name: Build
+    - name: Build .NET 10.0
-      run: dotnet build --no-restore
+      run: dotnet build --no-restore --framework net10.0 --configuration Release ./Core.Tests/Core.Tests.csproj
 
-    - name: Test
+    - name: Build .NET 9.0
-      run: dotnet test --no-build --verbosity normal --logger trx --results-directory "TestResults-8.x"
+      run: dotnet build --no-restore --framework net9.0 --configuration Release ./Core.Tests/Core.Tests.csproj
+
+    - name: Build .NET 8.0
+      run: dotnet build --no-restore --framework net8.0 --configuration Release ./Core.Tests/Core.Tests.csproj
+
+    - name: Test .NET 10.0
+      run: dotnet run --no-build --framework net10.0 --configuration Release --project ./Core.Tests/Core.Tests.csproj -- -trx TestResults/results-net10.trx
+
+    - name: Test .NET 9.0
+      run: dotnet run --no-build --framework net9.0 --configuration Release --project ./Core.Tests/Core.Tests.csproj -- -trx TestResults/results-net9.trx
+
+    - name: Test .NET 8.0
+      run: dotnet run --no-build --framework net8.0 --configuration Release --project ./Core.Tests/Core.Tests.csproj -- -trx TestResults/results-net8.trx
 
     - name: Upload dotnet test results
       uses: actions/upload-artifact@v3
       with:
-        name: dotnet-results-8.x
+        name: test-results
-        path: TestResults-8.x
+        path: TestResults
         if: ${{ always() }}
         retention-days: 30

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
     "dotnet.defaultSolution": "JustDotNet.Core.sln",
-    "dotnetAcquisitionExtension.enableTelemetry": false
+    "dotnetAcquisitionExtension.enableTelemetry": false,
+    "dotnet.testWindow.useTestingPlatformProtocol": true
 }

Core.Tests/Base32Conversions/Decode.cs

@@ -19,7 +19,7 @@ public class Decode
             var resultString = Base32.Encode(testBytes);
             var resultBytes = Base32.Decode(resultString);
 
-            resultBytes.Should().BeEquivalentTo(testBytes);
+            resultBytes.ShouldBeEquivalentTo(testBytes);
         }
     }
 
@@ -34,7 +34,7 @@ public class Decode
     public void WhenCalledWithValidString_ShouldReturnValidByteArray(string str, byte[] expected)
     {
         var actualBytesArray = Base32.Decode(str);
-        actualBytesArray.Should().Equal(expected);
+        actualBytesArray.ShouldBe(expected);
     }
 
     [Theory]
@@ -44,7 +44,7 @@ public class Decode
     public void WhenCalledWithValidStringThatEndsWithPaddingSign_ShouldReturnValidByteArray(string testString, byte[] expected)
     {
         var actualBytesArray = Base32.Decode(testString);
-        actualBytesArray.Should().Equal(expected);
+        actualBytesArray.ShouldBe(expected);
     }
 
     [Theory]
@@ -54,7 +54,7 @@ public class Decode
     public void WhenCalledWithValidStringWithoutPaddingSign_ShouldReturnValidByteArray(string testString, byte[] expected)
     {
         var actualBytesArray = Base32.Decode(testString);
-        actualBytesArray.Should().Equal(expected);
+        actualBytesArray.ShouldBe(expected);
     }
 
     [Theory]
@@ -66,14 +66,14 @@ public class Decode
     public void WhenCalledWithNotValidString_ShouldThrowFormatException(string testString)
     {
         Action action = () => Base32.Decode(testString);
-        action.Should().Throw<FormatException>();
+        action.ShouldThrow<FormatException>();
     }
 
     [Theory]
     [InlineData(null)]
     [InlineData("")]
-    public void WhenCalledWithNullString_ShouldReturnEmptyArray(string testString)
+    public void WhenCalledWithNullString_ShouldReturnEmptyArray(string? testString)
     {
-        Base32.Decode(testString).Should().BeEmpty();
+        Base32.Decode(testString).ShouldBeEmpty();
     }
 }

Core.Tests/Base32Conversions/Encode.cs

@@ -23,17 +23,22 @@ public class Encode
     [InlineData("GSHXGB5ORKNDSFLSU2YWALI=")]
     [InlineData("TMFSC64ZZNPQSNGCFIODS7TR")]
     [InlineData("ZTDUBU4QZFFMDJKBII334EIB")]
+    [InlineData("2IO2HTALCXZWCBD2AAAAAAAAAAAA====")]
+    [InlineData("WXYEOQUZULMCY6ZQTDOLTRUZZMKQ====")]
+    [InlineData("FG4M3ZQM3TVWDMBUP5L7N7V3JS7KBM2E")]
     public void WhenDecodedFromString_ShouldBeEncodedToTheSameString(string testString)
     {
         var resultBytes = Base32.Decode(testString);
         var resultString = Base32.Encode(resultBytes);
 
-        resultString.Should().BeEquivalentTo(testString);
+        resultString.ShouldBe(testString);
     }
 
     [Theory]
     [InlineData("FG4M3ZQM3TVWDMBUP5L7N7V3JS7KBM2E", new byte[] { 0x29, 0xb8, 0xcd, 0xe6, 0x0c, 0xdc, 0xeb, 0x61, 0xb0, 0x34, 0x7f, 0x57, 0xf6, 0xfe, 0xbb, 0x4c, 0xbe, 0xa0, 0xb3, 0x44, })]
     [InlineData("WXYEOQUZULMCY6ZQTDOLTRUZZMKQ====", new byte[] { 0xb5, 0xf0, 0x47, 0x42, 0x99, 0xa2, 0xd8, 0x2c, 0x7b, 0x30, 0x98, 0xdc, 0xb9, 0xc6, 0x99, 0xcb, 0x15, })]
+    [InlineData("2IO2HTALCXZWCBD2AAAAAAAAAAAA====", new byte[] { 0xd2, 0x1d, 0xa3, 0xcc, 0x0b, 0x15, 0xf3, 0x61, 0x04, 0x7a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, })]
+    [InlineData("2IO2HTALCXZWCBD2AAAAAAAA", new byte[] { 0xd2, 0x1d, 0xa3, 0xcc, 0x0b, 0x15, 0xf3, 0x61, 0x04, 0x7a, 0x00, 0x00, 0x00, 0x00, 0x00, })]
     [InlineData("2IO2HTALCXZWCBD2", new byte[] { 0xd2, 0x1d, 0xa3, 0xcc, 0x0b, 0x15, 0xf3, 0x61, 0x04, 0x7a, })]
     [InlineData("ZFXJMF5N", new byte[] { 0b11001001, 0b01101110, 0b10010110, 0b00010111, 0b10101101, })]
     [InlineData("CPIKTMY=", new byte[] { 0b00010011, 0b11010000, 0b10101001, 0b10110011, })]
@@ -42,15 +47,28 @@ public class Encode
     public void WhenCalledWithNotEmptyByteArray_ShouldReturnValidString(string expected, byte[] testArray)
     {
         var str = Base32.Encode(testArray);
-        str.Should().Be(expected);
+        str.ShouldBe(expected);
     }
 
     [Theory]
     [InlineData(new byte[] { })]
     [InlineData(null)]
-    public void WhenCalledWithEmptyByteArray_ShouldReturnEmptyString(byte[] testArray)
+    public void WhenCalledWithEmptyByteArray_ShouldReturnEmptyString(byte[]? testArray)
     {
         var actualBase32 = Base32.Encode(testArray);
-        actualBase32?.Should().Be(string.Empty);
+        actualBase32.ShouldBe(string.Empty);
+    }
+
+    [Theory]
+    [InlineData(new byte[] { })]
+    [InlineData(null)]
+    public void WhenCalledWithEmptyByteArray_ShouldReturnZeroAndNotChangeOutput(byte[]? testArray)
+    {
+        char[] output = ['1', '2', '3', '4'];
+
+        var charsWritten = Base32.Encode(testArray, output);
+
+        charsWritten.ShouldBe(0);
+        output.ShouldBe(['1', '2', '3', '4']);
     }
 }

Core.Tests/Base64UrlConversions/Decode.cs

@@ -7,7 +7,7 @@ public class Decode
     [InlineData(554121)]
     [InlineData(100454567)]
     [InlineData(3210589)]
-    public void WhenEncodedToString_ShouldBeDecodedToTheSameByteArray(int seed)
+    public void WhenBytesEncodedToString_ShouldBeDecodedToTheSameByteArray(int seed)
     {
         var rng = new Random(seed);
 
@@ -19,10 +19,47 @@ public class Decode
             var resultString = Base64Url.Encode(testBytes);
             var resultBytes = Base64Url.Decode(resultString);
 
-            resultBytes.Should().BeEquivalentTo(testBytes);
+            resultBytes.ShouldBeEquivalentTo(testBytes);
         }
     }
 
+    [Theory]
+    [InlineData(72121)]
+    [InlineData(554121)]
+    [InlineData(100454567)]
+    [InlineData(3210589)]
+    public void WhenLongEncodedToString_ShouldBeDecodedToTheSameLongArray(int seed)
+    {
+        var rng = new Random(seed);
+
+        for (int i = 1; i <= 512; i++)
+        {
+            var testLong = rng.NextInt64();
+
+            var resultString = Base64Url.Encode(testLong);
+            var resultLong = Base64Url.DecodeLong(resultString);
+
+            resultLong.ShouldBe(testLong);
+        }
+    }
+
+    [Theory]
+    [InlineData("RgGxr0_n1ZI", -7866126844696657594L)]
+    [InlineData("sxAPfpKB5kY", 5108913293478531251L)]
+    [InlineData("lO4_uitvLCg", 2894810894091415188L)]
+    [InlineData("awxjIqZWz10", 6759716837247880299L)]
+    [InlineData("VjNe72vug4U", -8825948697371200682L)]
+    [InlineData("AAAAAAAAAAA", 0L)]
+    [InlineData("__________8", -1L)]
+    [InlineData("AQAAAAAAAAA", 1L)]
+    [InlineData("CgAAAAAAAAA", 10L)]
+    [InlineData("6AMAAAAAAAA", 1000L)]
+    public void WhenCalled_ShouldReturnValidLong(string testString, long expected)
+    {
+        var result = Base64Url.DecodeLong(testString);
+        result.ShouldBe(expected);
+    }
+
     [Theory]
     [InlineData("5QrdUxDUVkCAEGw8pvLsEw", "53dd0ae5-d410-4056-8010-6c3ca6f2ec13")]
     [InlineData("6nE2uKQ4_0ar9kpmybgkdw", "b83671ea-38a4-46ff-abf6-4a66c9b82477")]
@@ -33,7 +70,7 @@ public class Decode
     {
         var result = Base64Url.DecodeGuid(testString);
         var expected = Guid.Parse(expectedStr);
-        result.Should().Be(expected);
+        result.ShouldBe(expected);
     }
 
     [Theory]
@@ -48,6 +85,51 @@ public class Decode
     public void WhenCalled_ShouldReturnValidBytes(string testString, byte[] expected)
     {
         var result = Base64Url.Decode(testString);
-        result.Should().BeEquivalentTo(expected);
+        result.ShouldBeEquivalentTo(expected);
+    }
+
+    [Theory]
+    [InlineData("  ")]
+    [InlineData("hg2&515i3215")]
+    [InlineData("hg712)21")]
+    [InlineData("hg712f 21")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1806:Do not ignore method results", Justification = "Test case")]
+    public void WhenCalledWithInvalidString_ShouldThrowFormatException(string testString)
+    {
+        Action action = () => Base64Url.Decode(testString);
+        action.ShouldThrow<FormatException>();
+    }
+
+    [Theory]
+    [InlineData("5QrdUxDUV CAEGw8pvLsEw")]
+    [InlineData("6nE2uKQ4$0ar9kpmybgkdw")]
+    [InlineData("PyD6zwDqXkG*S1HPsp41wQ")]
+    [InlineData("!dOlPOh3wEe9PlyQgTMt2g")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1806:Do not ignore method results", Justification = "Test case")]
+    public void WhenCalledWithInvalidGuidString_ShouldThrowFormatException(string testString)
+    {
+        Action action = () => Base64Url.DecodeGuid(testString);
+        action.ShouldThrow<FormatException>();
+    }
+
+    [Theory]
+    [InlineData("RgG&r0_n1ZI")]
+    [InlineData("sxA fpKB5kY")]
+    [InlineData("lO4_uitvL)g")]
+    [InlineData("awxjIqZ^z10")]
+    [InlineData("VjNe7!vug4U")]
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1806:Do not ignore method results", Justification = "Test case")]
+    public void WhenCalledWithInvalidLongString_ShouldThrowFormatException(string testString)
+    {
+        Action action = () => Base64Url.DecodeLong(testString);
+        action.ShouldThrow<FormatException>();
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    public void WhenCalledWithNullString_ShouldReturnEmptyArray(string? testString)
+    {
+        Base64Url.Decode(testString).ShouldBeEmpty();
     }
 }

Core.Tests/Base64UrlConversions/Encode.cs

@@ -12,7 +12,24 @@ public class Encode
     {
         var testGuid = Guid.Parse(testGuidString);
         var result = Base64Url.Encode(testGuid);
-        result.Should().Be(expected);
+        result.ShouldBe(expected);
+    }
+
+    [Theory]
+    [InlineData("RgGxr0_n1ZI", -7866126844696657594L)]
+    [InlineData("sxAPfpKB5kY", 5108913293478531251L)]
+    [InlineData("lO4_uitvLCg", 2894810894091415188L)]
+    [InlineData("awxjIqZWz10", 6759716837247880299L)]
+    [InlineData("VjNe72vug4U", -8825948697371200682L)]
+    [InlineData("AAAAAAAAAAA", 0L)]
+    [InlineData("__________8", -1L)]
+    [InlineData("AQAAAAAAAAA", 1L)]
+    [InlineData("CgAAAAAAAAA", 10L)]
+    [InlineData("6AMAAAAAAAA", 1000L)]
+    public void WhenCalledWithLong_ShouldReturnValidString(string expected, long testLong)
+    {
+        var result = Base64Url.Encode(testLong);
+        result.ShouldBe(expected);
     }
 
     [Theory]
@@ -27,6 +44,28 @@ public class Encode
     public void WhenCalled_ShouldReturnValidString(string expected, byte[] testBytes)
     {
         var result = Base64Url.Encode(testBytes);
-        result.Should().Be(expected);
+        result.ShouldBe(expected);
+    }
+
+    [Theory]
+    [InlineData(new byte[] { })]
+    [InlineData(null)]
+    public void WhenCalledWithEmptyByteArray_ShouldReturnEmptyString(byte[]? testArray)
+    {
+        var actualBase32 = Base64Url.Encode(testArray);
+        actualBase32.ShouldBe(string.Empty);
+    }
+
+    [Theory]
+    [InlineData(new byte[] { })]
+    [InlineData(null)]
+    public void WhenCalledWithEmptyByteArray_ShouldReturnZeroAndNotChangeOutput(byte[]? testArray)
+    {
+        char[] output = ['1', '2', '3', '4'];
+
+        var charsWritten = Base64Url.Encode(testArray, output);
+
+        charsWritten.ShouldBe(0);
+        output.ShouldBe((char[])['1', '2', '3', '4']);
     }
 }

Core.Tests/Core.Tests.csproj

@@ -1,9 +1,10 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
+    <OutputType>Exe</OutputType>
 
     <AssemblyName>Just.Core.Tests</AssemblyName>
     <RootNamespace>Just.Core.Tests</RootNamespace>
@@ -14,14 +15,9 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="FluentAssertions" Version="6.12.0" />
+    <PackageReference Include="Shouldly" Version="4.3.0" />
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.6.0" />
+    <PackageReference Include="xunit.v3" Version="3.2.0" />
-    <PackageReference Include="xunit" Version="2.4.2" />
+    <PackageReference Include="coverlet.collector" Version="6.0.4">
-    <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5">
-      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
-      <PrivateAssets>all</PrivateAssets>
-    </PackageReference>
-    <PackageReference Include="coverlet.collector" Version="6.0.0">
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>

Core.Tests/GlobalUsings.cs

@@ -1,2 +1,2 @@
 global using Xunit;
-global using FluentAssertions;
+global using Shouldly;

Core.Tests/GuidV8Tests/NewGuid.cs

@@ -0,0 +1,254 @@
+namespace Just.Core.Tests.GuidV8Tests;
+
+public class NewGuid
+{
+    [Theory]
+    [InlineData(RngEntropy.Weak)]
+    [InlineData(RngEntropy.Strong)]
+    public void Version_And_Variant_Should_Be_Correct(RngEntropy entropy)
+    {
+        var rng = new Random(25);
+        var referenceTime = new DateTime(2020, 05, 17, 15, 36, 13, 771, DateTimeKind.Utc);
+
+        for (int i = 0; i < 2000; i++)
+        {
+            var timestamp = referenceTime.AddSeconds(rng.Next());
+            var result = GuidV8.NewGuid(timestamp, entropy);
+
+#if NET9_0_OR_GREATER
+            result.Version.ShouldBe(8);
+            (result.Variant & 0b1100).ShouldBe(0b1000);
+#else
+            var bytes = result.ToByteArray();
+            // Check version (bits 4-7 of the 7th byte)
+            var version = (bytes[7] >> 4) & 0x0F;
+            version.ShouldBe(8); // UUID version 8
+            // Check variant (bits 6-7 of the 8th byte)
+            var variant = bytes[8] >> 6;
+            variant.ShouldBe(0b10); // Standard UUID variant
+#endif
+        }
+    }
+
+    [Theory]
+    [InlineData(RngEntropy.Weak,
+        -25000000, -20000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+        -2500, -1000, -500, -499, -497, -450, -300, -200, -50, -1, 0, 1, 2, 5, 10, 20, 50, 100, 200, 350, 500, 1000,
+        2500, 5000, 10000, 25000, 100000, 250000, 500000, 1000000, 2000000, 5000000, 10000000, 20000000, 50000000, 100000000)]
+    [InlineData(RngEntropy.Strong,
+        -25000000, -20000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+        -2500, -1000, -500, -499, -497, -450, -300, -200, -50, -1, 0, 1, 2, 5, 10, 20, 50, 100, 200, 350, 500, 1000,
+        2500, 5000, 10000, 25000, 100000, 250000, 500000, 1000000, 2000000, 5000000, 10000000, 20000000, 50000000, 100000000)]
+    [InlineData(RngEntropy.Weak,
+        -9863, -9740, -9214, -8878, -8674, -8652, -8640, -8565, -8518, -8449,
+        -8390, -8193, -8108, -7808, -7501, -7203, -7133, -7020, -6983, -6855,
+        -6576, -6162, -5630, -5505, -5472, -5382, -4706, -4680, -4509, -4454,
+        -4314, -3920, -3251, -3233, -3116, -2792, -2685, -2574, -2338, -2173,
+        -1934, -1914, -1528, -1483, -1410, -870, -757, -730, -263, -220,
+        151, 426, 588, 970, 1213, 1269, 1376, 1397, 1450, 1770,
+        2063, 2577, 2750, 2860, 3139, 3161, 3488, 3630, 3774, 4004,
+        4163, 4198, 4366, 4662, 4746, 4879, 5467, 5601, 5912, 5979,
+        6128, 6277, 6323, 6437, 6699, 6853, 7556, 7776, 7795, 8099,
+        8336, 8592, 8682, 8683, 8818, 8904, 9375, 9466, 9551, 9708)]
+    [InlineData(RngEntropy.Strong,
+        -9863, -9740, -9214, -8878, -8674, -8652, -8640, -8565, -8518, -8449,
+        -8390, -8193, -8108, -7808, -7501, -7203, -7133, -7020, -6983, -6855,
+        -6576, -6162, -5630, -5505, -5472, -5382, -4706, -4680, -4509, -4454,
+        -4314, -3920, -3251, -3233, -3116, -2792, -2685, -2574, -2338, -2173,
+        -1934, -1914, -1528, -1483, -1410, -870, -757, -730, -263, -220,
+        151, 426, 588, 970, 1213, 1269, 1376, 1397, 1450, 1770,
+        2063, 2577, 2750, 2860, 3139, 3161, 3488, 3630, 3774, 4004,
+        4163, 4198, 4366, 4662, 4746, 4879, 5467, 5601, 5912, 5979,
+        6128, 6277, 6323, 6437, 6699, 6853, 7556, 7776, 7795, 8099,
+        8336, 8592, 8682, 8683, 8818, 8904, 9375, 9466, 9551, 9708)]
+    [InlineData(RngEntropy.Weak,
+        10024, 28660, 289641, 356015, 443164, 478759, 599586, 705860, 791271, 876512,
+        884503, 894899, 898584, 980136, 1007927, 1680328, 1690193, 1804615, 1847117, 2005534,
+        2106684, 2111936, 2252935, 2271396, 2298685, 2385409, 2414094, 2451706, 2549138, 2605538,
+        2864629, 2923476, 3004288, 3182875, 3266693, 3379019, 3542110, 3851467, 3871420, 4035463,
+        4316004, 4726381, 4814068, 4902666, 4979292, 4993443, 5117765, 5240585, 5249671, 5319528,
+        5387595, 5434544, 5504506, 5531264, 5546173, 5780381, 5889341, 6066328, 6167883, 6185073,
+        6299021, 6412136, 6621498, 6666562, 6741169, 6870279, 6949855, 6965427, 7153467, 7184150,
+        7300456, 7311381, 7413697, 7505235, 7802811, 7979134, 8053665, 8177676, 8260284, 8260773,
+        8269944, 8406526, 8442932, 8475162, 8555250, 8853347, 8861733, 8892200, 9069869, 9117839,
+        9225445, 9245837, 9378644, 9497874, 9553625, 9650968, 9704053, 9713592, 9715054, 9735988)]
+    [InlineData(RngEntropy.Strong,
+        10024, 28660, 289641, 356015, 443164, 478759, 599586, 705860, 791271, 876512,
+        884503, 894899, 898584, 980136, 1007927, 1680328, 1690193, 1804615, 1847117, 2005534,
+        2106684, 2111936, 2252935, 2271396, 2298685, 2385409, 2414094, 2451706, 2549138, 2605538,
+        2864629, 2923476, 3004288, 3182875, 3266693, 3379019, 3542110, 3851467, 3871420, 4035463,
+        4316004, 4726381, 4814068, 4902666, 4979292, 4993443, 5117765, 5240585, 5249671, 5319528,
+        5387595, 5434544, 5504506, 5531264, 5546173, 5780381, 5889341, 6066328, 6167883, 6185073,
+        6299021, 6412136, 6621498, 6666562, 6741169, 6870279, 6949855, 6965427, 7153467, 7184150,
+        7300456, 7311381, 7413697, 7505235, 7802811, 7979134, 8053665, 8177676, 8260284, 8260773,
+        8269944, 8406526, 8442932, 8475162, 8555250, 8853347, 8861733, 8892200, 9069869, 9117839,
+        9225445, 9245837, 9378644, 9497874, 9553625, 9650968, 9704053, 9713592, 9715054, 9735988)]
+    public void Guids_Differing_By_Minutes_Should_Be_Sortable(RngEntropy entropy, params int[] seconds)
+    {
+        var rng = new Random(25);
+        var referenceTime = new DateTime(2024, 05, 17, 15, 36, 13, 771, DateTimeKind.Utc);
+        SortedList<DateTime, Guid> expected = new(seconds.Length);
+        foreach (var s in seconds)
+        {
+            var timestamp = referenceTime.AddMinutes(s);
+            expected.Add(timestamp, GuidV8.NewGuid(timestamp, entropy));
+        }
+
+        var sut = expected.Values.ToArray();
+        rng.Shuffle(sut);
+
+        sut.Order().ShouldBe(expected.Select(x => x.Value));
+        sut.OrderBy(x => x.ToString()).ShouldBe(expected.Select(x => x.Value));
+
+        sut.OrderDescending().ShouldBe(expected.Reverse().Select(x => x.Value));
+        sut.OrderByDescending(x => x.ToString()).ShouldBe(expected.Reverse().Select(x => x.Value));
+    }
+
+    [Theory]
+    [InlineData(RngEntropy.Weak,
+        -100000000, -25000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+        -2500, -1000, -500, -499, -497, -450, -300, -200, -50, -1, 0, 1, 2, 5, 10, 20, 50, 100, 200, 350, 500, 1000,
+        2500, 5000, 10000, 25000, 100000, 250000, 500000, 1000000, 2000000, 5000000, 10000000, 100000000, 200000000)]
+    [InlineData(RngEntropy.Strong,
+        -100000000, -25000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+        -2500, -1000, -500, -499, -497, -450, -300, -200, -50, -1, 0, 1, 2, 5, 10, 20, 50, 100, 200, 350, 500, 1000,
+        2500, 5000, 10000, 25000, 100000, 250000, 500000, 1000000, 2000000, 5000000, 10000000, 100000000, 200000000)]
+    [InlineData(RngEntropy.Weak,
+        -9863, -9740, -9214, -8878, -8674, -8652, -8640, -8565, -8518, -8449,
+        -8390, -8193, -8108, -7808, -7501, -7203, -7133, -7020, -6983, -6855,
+        -6576, -6162, -5630, -5505, -5472, -5382, -4706, -4680, -4509, -4454,
+        -4314, -3920, -3251, -3233, -3116, -2792, -2685, -2574, -2338, -2173,
+        -1934, -1914, -1528, -1483, -1410, -870, -757, -730, -263, -220,
+        151, 426, 588, 970, 1213, 1269, 1376, 1397, 1450, 1770,
+        2063, 2577, 2750, 2860, 3139, 3161, 3488, 3630, 3774, 4004,
+        4163, 4198, 4366, 4662, 4746, 4879, 5467, 5601, 5912, 5979,
+        6128, 6277, 6323, 6437, 6699, 6853, 7556, 7776, 7795, 8099,
+        8336, 8592, 8682, 8683, 8818, 8904, 9375, 9466, 9551, 9708)]
+    [InlineData(RngEntropy.Strong,
+        -9863, -9740, -9214, -8878, -8674, -8652, -8640, -8565, -8518, -8449,
+        -8390, -8193, -8108, -7808, -7501, -7203, -7133, -7020, -6983, -6855,
+        -6576, -6162, -5630, -5505, -5472, -5382, -4706, -4680, -4509, -4454,
+        -4314, -3920, -3251, -3233, -3116, -2792, -2685, -2574, -2338, -2173,
+        -1934, -1914, -1528, -1483, -1410, -870, -757, -730, -263, -220,
+        151, 426, 588, 970, 1213, 1269, 1376, 1397, 1450, 1770,
+        2063, 2577, 2750, 2860, 3139, 3161, 3488, 3630, 3774, 4004,
+        4163, 4198, 4366, 4662, 4746, 4879, 5467, 5601, 5912, 5979,
+        6128, 6277, 6323, 6437, 6699, 6853, 7556, 7776, 7795, 8099,
+        8336, 8592, 8682, 8683, 8818, 8904, 9375, 9466, 9551, 9708)]
+    [InlineData(RngEntropy.Weak,
+        6629058, 24114993, 40561510, 46245969, 46876997, 48747281, 80489854, 110237218, 117445694, 118974860,
+        135132579, 141760591, 149114066, 158322437, 159065333, 164925904, 173848639, 175086337, 175704556, 176335514,
+        200302773, 207133553, 230088723, 234521706, 239587338, 263755571, 264571928, 290118284, 292346548, 319322378,
+        320988273, 322638028, 324110126, 326855208, 332533719, 336668313, 350798512, 366520367, 380595181, 405033666,
+        410929500, 414099488, 417697882, 421269768, 431907031, 435262715, 442168482, 449797406, 458508845, 489039529,
+        503344305, 514934509, 537515867, 555210743, 563951463, 578783864, 580560518, 580902916, 605801607, 635231377,
+        636537435, 637241486, 676077268, 691630262, 696158602, 714007596, 715537265, 718873134, 724266320, 741049828,
+        749379956, 757561933, 758668417, 761735205, 770349479, 797570403, 805896481, 809050934, 821655964, 821980469,
+        830824227, 840429528, 851772315, 859717719, 859763860, 867675943, 912124563, 914880620, 923914294, 930298008,
+        932610035, 937468680, 945565998, 949277691, 949397209, 951283050, 953249971, 953953188, 976210158, 982233484, 982233485)]
+    [InlineData(RngEntropy.Strong,
+        6629058, 24114993, 40561510, 46245969, 46876997, 48747281, 80489854, 110237218, 117445694, 118974860,
+        135132579, 141760591, 149114066, 158322437, 159065333, 164925904, 173848639, 175086337, 175704556, 176335514,
+        200302773, 207133553, 230088723, 234521706, 239587338, 263755571, 264571928, 290118284, 292346548, 319322378,
+        320988273, 322638028, 324110126, 326855208, 332533719, 336668313, 350798512, 366520367, 380595181, 405033666,
+        410929500, 414099488, 417697882, 421269768, 431907031, 435262715, 442168482, 449797406, 458508845, 489039529,
+        503344305, 514934509, 537515867, 555210743, 563951463, 578783864, 580560518, 580902916, 605801607, 635231377,
+        636537435, 637241486, 676077268, 691630262, 696158602, 714007596, 715537265, 718873134, 724266320, 741049828,
+        749379956, 757561933, 758668417, 761735205, 770349479, 797570403, 805896481, 809050934, 821655964, 821980469,
+        830824227, 840429528, 851772315, 859717719, 859763860, 867675943, 912124563, 914880620, 923914294, 930298008,
+        932610035, 937468680, 945565998, 949277691, 949397209, 951283050, 953249971, 953953188, 976210158, 982233484, 982233485)]
+    public void Guids_Differing_By_Seconds_Should_Be_Sortable(RngEntropy entropy, params int[] seconds)
+    {
+        var rng = new Random(25);
+        var referenceTime = new DateTime(2024, 05, 17, 15, 36, 13, 771, DateTimeKind.Utc);
+        SortedList<DateTime, Guid> expected = new(seconds.Length);
+        foreach (var s in seconds)
+        {
+            var timestamp = referenceTime.AddSeconds(s);
+            expected.Add(timestamp, GuidV8.NewGuid(timestamp, entropy));
+        }
+
+        var sut = expected.Values.ToArray();
+        rng.Shuffle(sut);
+
+        sut.Order().ShouldBe(expected.Select(x => x.Value));
+        sut.OrderBy(x => x.ToString()).ShouldBe(expected.Select(x => x.Value));
+
+        sut.OrderDescending().ShouldBe(expected.Reverse().Select(x => x.Value));
+        sut.OrderByDescending(x => x.ToString()).ShouldBe(expected.Reverse().Select(x => x.Value));
+    }
+
+    [Theory]
+    [InlineData(RngEntropy.Weak,
+        -250000000, -25000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+        -2500, -1000, -500, -499, -497, -450, -300, -200, -50, -1, 0, 1, 2, 5, 10, 20, 50, 100, 200, 350, 500, 1000,
+        2500, 5000, 10000, 25000, 100000, 250000, 500000, 1000000, 2000000, 5000000, 10000000, 100000000, 2100000000)]
+    [InlineData(RngEntropy.Strong,
+        -250000000, -25000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+        -2500, -1000, -500, -499, -497, -450, -300, -200, -50, -1, 0, 1, 2, 5, 10, 20, 50, 100, 200, 350, 500, 1000,
+        2500, 5000, 10000, 25000, 100000, 250000, 500000, 1000000, 2000000, 5000000, 10000000, 100000000, 2100000000)]
+    [InlineData(RngEntropy.Weak,
+        -9863, -9740, -9214, -8878, -8674, -8652, -8640, -8565, -8518, -8449,
+        -8390, -8193, -8108, -7808, -7501, -7203, -7133, -7020, -6983, -6855,
+        -6576, -6162, -5630, -5505, -5472, -5382, -4706, -4680, -4509, -4454,
+        -4314, -3920, -3251, -3233, -3116, -2792, -2685, -2574, -2338, -2173,
+        -1934, -1914, -1528, -1483, -1410, -870, -757, -730, -263, -220,
+        151, 426, 588, 970, 1213, 1269, 1376, 1397, 1450, 1770,
+        2063, 2577, 2750, 2860, 3139, 3161, 3488, 3630, 3774, 4004,
+        4163, 4198, 4366, 4662, 4746, 4879, 5467, 5601, 5912, 5979,
+        6128, 6277, 6323, 6437, 6699, 6853, 7556, 7776, 7795, 8099,
+        8336, 8592, 8682, 8683, 8818, 8904, 9375, 9466, 9551, 9708)]
+    [InlineData(RngEntropy.Strong,
+        -9863, -9740, -9214, -8878, -8674, -8652, -8640, -8565, -8518, -8449,
+        -8390, -8193, -8108, -7808, -7501, -7203, -7133, -7020, -6983, -6855,
+        -6576, -6162, -5630, -5505, -5472, -5382, -4706, -4680, -4509, -4454,
+        -4314, -3920, -3251, -3233, -3116, -2792, -2685, -2574, -2338, -2173,
+        -1934, -1914, -1528, -1483, -1410, -870, -757, -730, -263, -220,
+        151, 426, 588, 970, 1213, 1269, 1376, 1397, 1450, 1770,
+        2063, 2577, 2750, 2860, 3139, 3161, 3488, 3630, 3774, 4004,
+        4163, 4198, 4366, 4662, 4746, 4879, 5467, 5601, 5912, 5979,
+        6128, 6277, 6323, 6437, 6699, 6853, 7556, 7776, 7795, 8099,
+        8336, 8592, 8682, 8683, 8818, 8904, 9375, 9466, 9551, 9708)]
+    [InlineData(RngEntropy.Weak,
+        6629058, 24114993, 40561510, 46245969, 46876997, 48747281, 80489854, 110237218, 117445694, 118974860,
+        135132579, 141760591, 149114066, 158322437, 159065333, 164925904, 173848639, 175086337, 175704556, 176335514,
+        200302773, 207133553, 230088723, 234521706, 239587338, 263755571, 264571928, 290118284, 292346548, 319322378,
+        320988273, 322638028, 324110126, 326855208, 332533719, 336668313, 350798512, 366520367, 380595181, 405033666,
+        410929500, 414099488, 417697882, 421269768, 431907031, 435262715, 442168482, 449797406, 458508845, 489039529,
+        503344305, 514934509, 537515867, 555210743, 563951463, 578783864, 580560518, 580902916, 605801607, 635231377,
+        636537435, 637241486, 676077268, 691630262, 696158602, 714007596, 715537265, 718873134, 724266320, 741049828,
+        749379956, 757561933, 758668417, 761735205, 770349479, 797570403, 805896481, 809050934, 821655964, 821980469,
+        830824227, 840429528, 851772315, 859717719, 859763860, 867675943, 912124563, 914880620, 923914294, 930298008,
+        932610035, 937468680, 945565998, 949277691, 949397209, 951283050, 953249971, 953953188, 976210158, 982233484, 982233485)]
+    [InlineData(RngEntropy.Strong,
+        6629058, 24114993, 40561510, 46245969, 46876997, 48747281, 80489854, 110237218, 117445694, 118974860,
+        135132579, 141760591, 149114066, 158322437, 159065333, 164925904, 173848639, 175086337, 175704556, 176335514,
+        200302773, 207133553, 230088723, 234521706, 239587338, 263755571, 264571928, 290118284, 292346548, 319322378,
+        320988273, 322638028, 324110126, 326855208, 332533719, 336668313, 350798512, 366520367, 380595181, 405033666,
+        410929500, 414099488, 417697882, 421269768, 431907031, 435262715, 442168482, 449797406, 458508845, 489039529,
+        503344305, 514934509, 537515867, 555210743, 563951463, 578783864, 580560518, 580902916, 605801607, 635231377,
+        636537435, 637241486, 676077268, 691630262, 696158602, 714007596, 715537265, 718873134, 724266320, 741049828,
+        749379956, 757561933, 758668417, 761735205, 770349479, 797570403, 805896481, 809050934, 821655964, 821980469,
+        830824227, 840429528, 851772315, 859717719, 859763860, 867675943, 912124563, 914880620, 923914294, 930298008,
+        932610035, 937468680, 945565998, 949277691, 949397209, 951283050, 953249971, 953953188, 976210158, 982233484, 982233485)]
+    public void Guids_Differing_By_Milliseconds_Should_Be_Sortable(RngEntropy entropy, params int[] seconds)
+    {
+        var rng = new Random(26);
+        var referenceTime = new DateTime(2024, 05, 17, 15, 36, 13, 771, DateTimeKind.Utc);
+        SortedList<DateTime, Guid> expected = new(seconds.Length);
+        foreach (var s in seconds)
+        {
+            var timestamp = referenceTime.AddMilliseconds(s);
+            expected.Add(timestamp, GuidV8.NewGuid(timestamp, entropy));
+        }
+
+        var sut = expected.Values.ToArray();
+        rng.Shuffle(sut);
+
+        sut.Order().ShouldBe(expected.Select(x => x.Value));
+        sut.OrderBy(x => x.ToString()).ShouldBe(expected.Select(x => x.Value));
+
+        sut.OrderDescending().ShouldBe(expected.Reverse().Select(x => x.Value));
+        sut.OrderByDescending(x => x.ToString()).ShouldBe(expected.Reverse().Select(x => x.Value));
+    }
+}

Core.Tests/SeqIdTests/NextId.cs

@@ -0,0 +1,141 @@
+
+namespace Just.Core.Tests.SeqIdTests;
+
+public class NextId
+{
+    private static readonly DateTime TestEpoch = new(2025, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+    private readonly SeqId _seqId = new(TestEpoch);
+
+    private const int TimestampShift = 22; // 63 - 41 = 22
+    private const long TimestampMask = 0x1FFFFFFFFFF; // 41 bits mask
+    private const int SeqShift = 14; // TimestampShift - 8 = 14
+    private const long SeqMask = 0xFF; // 8 bits mask
+    private const long RandMask = 0x3FFF; // 14 bits mask (since 2^14 = 16384)
+
+    [Fact]
+    public void NextId_ShouldHaveCorrectBitStructure()
+    {
+        // Arrange
+        var time = TestEpoch.AddMilliseconds(500);
+
+        // Act
+        long id = _seqId.Next(time);
+
+        // Assert
+        long timestampPart = (id >> TimestampShift) & TimestampMask;
+        long sequencePart = (id >> SeqShift) & SeqMask;
+        long randomPart = id & RandMask;
+
+        timestampPart.ShouldBe(500);
+        sequencePart.ShouldBe(0);
+        randomPart.ShouldBeInRange(0, RandMask);
+    }
+
+    [Fact]
+    public void NextId_ShouldIncrementSequenceForSameTimestamp()
+    {
+        // Arrange
+        var time = TestEpoch.AddMilliseconds(100);
+
+        // Act
+        long id1 = _seqId.Next(time);
+        long id2 = _seqId.Next(time);
+
+        // Assert
+        long sequence1 = (id1 >> SeqShift) & SeqMask;
+        long sequence2 = (id2 >> SeqShift) & SeqMask;
+
+        sequence2.ShouldBe(sequence1 + 1);
+    }
+
+    [Fact]
+    public void NextId_ShouldResetSequenceForNewTimestamp()
+    {
+        // Arrange
+        var time1 = TestEpoch.AddMilliseconds(100);
+        var time2 = time1.AddMilliseconds(1);
+
+        // Act
+        _ = _seqId.Next(time1); // Sequence increments to 0
+        _ = _seqId.Next(time1); // Sequence increments to 1
+        long id = _seqId.Next(time2); // Should reset to 0
+
+        // Assert
+        long sequence = (id >> SeqShift) & SeqMask;
+        sequence.ShouldBe(0);
+    }
+
+    [Fact]
+    public void NextId_ShouldThrowWhenTimestampDecreases()
+    {
+        // Arrange
+        var time1 = TestEpoch.AddMilliseconds(200);
+        var time2 = TestEpoch.AddMilliseconds(100);
+
+        // Act & Assert
+        _seqId.Next(time1); // First call sets last timestamp
+        Action act = () => _seqId.Next(time2);
+        act.ShouldThrow<InvalidOperationException>()
+            .WithMessage("Refused to create new SeqId. Last timestamp is in the future.");
+    }
+
+    [Fact]
+    public void NextId_ShouldThrowWhenSequenceExhausted()
+    {
+        // Arrange
+        var time = TestEpoch.AddMilliseconds(200);
+
+        // Act & Assert
+        for (int i = 0; i < 255; i++)
+        {
+            _seqId.Next(time); // Exhauste sequence
+        }
+        Action act = () => _seqId.Next(time);
+        act.ShouldThrow<IndexOutOfRangeException>()
+            .WithMessage("Refused to create new SeqId. Sequence exhausted.");
+    }
+
+    [Fact]
+    public void NextId_WithStrongEntropy_ShouldSetLower14Bits()
+    {
+        // Arrange
+        var time = TestEpoch.AddMilliseconds(300);
+
+        // Act
+        long id = _seqId.Next(time, RngEntropy.Strong);
+
+        // Assert
+        long randomPart = id & RandMask;
+        randomPart.ShouldBeInRange(0, RandMask);
+    }
+
+    [Fact]
+    public void NextId_WithWeakEntropy_ShouldSetLower14Bits()
+    {
+        // Arrange
+        var time = TestEpoch.AddMilliseconds(400);
+
+        // Act
+        long id = _seqId.Next(time, RngEntropy.Weak);
+
+        // Assert
+        long randomPart = id & RandMask;
+        randomPart.ShouldBeInRange(0, RandMask);
+    }
+
+    [Fact]
+    public void DefaultInstance_NextId_ShouldUseDefaultEpoch()
+    {
+        // Arrange
+        var now = DateTime.UtcNow;
+        var defaultEpoch = SeqId.DefaultEpoch;
+        long expectedTimestamp = ((long)(now - defaultEpoch).TotalMilliseconds) & TimestampMask; // Mask handles overflow
+
+        // Act
+        long id = SeqId.NextId();
+
+        // Assert
+        long timestampPart = (id >> TimestampShift) & TimestampMask;
+        timestampPart.ShouldBeInRange(expectedTimestamp, expectedTimestamp + 1);
+    }
+}

Core.Tests/ShouldlyExtensions.cs

@@ -0,0 +1,11 @@
+namespace Just.Core.Tests;
+
+public static class ShouldlyExtensions
+{
+    public static TException WithMessage<TException>(this TException exception, string expectedMessage, string? customMessage = null)
+        where TException : Exception
+    {
+        exception.Message.ShouldBe(expectedMessage, customMessage: customMessage);
+        return exception;
+    }
+}

Core.Tests/SystemIOStreamExtensionsTests/Populate.cs

@@ -0,0 +1,58 @@
+using Just.Core.Extensions;
+
+namespace Just.Core.Tests.SystemIOStreamExtensionsTests;
+
+public class Populate
+{
+    [Theory]
+    [InlineData(0, 0)]
+    [InlineData(0, 1)]
+    [InlineData(0, 3)]
+    [InlineData(0, 5)]
+    [InlineData(3, 0)]
+    [InlineData(3, 1)]
+    [InlineData(3, 5)]
+    [InlineData(5, 0)]
+    [InlineData(5, 1)]
+    [InlineData(5, 5)]
+    public void WhenCalled_ShouldPopulateSpecifiedRange(int offset, int length)
+    {
+        byte[] streamContent = [0x01, 0x02, 0x03, 0x04, 0x05,];
+        using var stream = new MemoryStream(streamContent);
+        var buffer = new byte[10];
+
+        stream.Populate(buffer, offset, length);
+
+        buffer.Skip(offset).Take(length).ShouldBe(streamContent.Take(length));
+    }
+
+    [Theory]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, }, 4)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, }, 4)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, }, 5)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, }, 5)]
+    public void WhenStreamContainsSameOrGreaterAmmountOfItems_ShouldPopulateBuffer(byte[] streamContent, int bufferSize)
+    {
+        using var stream = new MemoryStream(streamContent);
+        var buffer = new byte[bufferSize];
+
+        stream.Populate(buffer);
+
+        buffer.ShouldBe(streamContent.Take(bufferSize));
+    }
+
+    [Theory]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, }, 5)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, }, 6)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, }, 10)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, }, 9)]
+    public void WhenStreamContainsLessItems_ShouldThrowEndOfStreamException(byte[] streamContent, int bufferSize)
+    {
+        using var stream = new MemoryStream(streamContent);
+        var buffer = new byte[bufferSize];
+
+        Action action = () => stream.Populate(buffer);
+
+        action.ShouldThrow<EndOfStreamException>();
+    }
+}

Core.Tests/SystemIOStreamExtensionsTests/PopulateAsync.cs

@@ -0,0 +1,74 @@
+using Just.Core.Extensions;
+
+namespace Just.Core.Tests.SystemIOStreamExtensionsTests;
+
+public class PopulateAsync
+{
+    [Fact]
+    public async Task WhenCancellationRequested_ShouldThrowOperationCanceledException()
+    {
+        using var cts = new CancellationTokenSource();
+        byte[] streamContent = [0x01, 0x02, 0x03, 0x04, 0x05,];
+        using var stream = new MemoryStream(streamContent);
+        var buffer = new byte[5];
+
+        Func<Task> action = async () => await stream.PopulateAsync(buffer, cts.Token);
+        cts.Cancel();
+
+        await action.ShouldThrowAsync<OperationCanceledException>();
+    }
+
+    [Theory]
+    [InlineData(0, 0)]
+    [InlineData(0, 1)]
+    [InlineData(0, 3)]
+    [InlineData(0, 5)]
+    [InlineData(3, 0)]
+    [InlineData(3, 1)]
+    [InlineData(3, 5)]
+    [InlineData(5, 0)]
+    [InlineData(5, 1)]
+    [InlineData(5, 5)]
+    public async Task WhenCalled_ShouldPopulateSpecifiedRange(int offset, int length)
+    {
+        using var cts = new CancellationTokenSource(TimeSpan.FromMilliseconds(50));
+        byte[] streamContent = [0x01, 0x02, 0x03, 0x04, 0x05,];
+        using var stream = new MemoryStream(streamContent);
+        var buffer = new byte[10];
+
+        await stream.PopulateAsync(buffer, offset, length, cts.Token);
+
+        buffer.Skip(offset).Take(length).ShouldBe(streamContent.Take(length));
+    }
+
+    [Theory]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, }, 4)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, }, 4)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, }, 5)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, }, 5)]
+    public async Task WhenStreamContainsSameOrGreaterAmmountOfItems_ShouldPopulateBuffer(byte[] streamContent, int bufferSize)
+    {
+        using var cts = new CancellationTokenSource(TimeSpan.FromMilliseconds(50));
+        using var stream = new MemoryStream(streamContent);
+        var buffer = new byte[bufferSize];
+
+        await stream.PopulateAsync(buffer, cts.Token);
+
+        buffer.ShouldBe(streamContent.Take(bufferSize));
+    }
+
+    [Theory]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, }, 5)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, }, 6)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, }, 10)]
+    [InlineData(new byte[]{ 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, }, 9)]
+    public async Task WhenStreamContainsLessItems_ShouldThrowEndOfStreamException(byte[] streamContent, int bufferSize)
+    {
+        using var stream = new MemoryStream(streamContent);
+        var buffer = new byte[bufferSize];
+
+        Func<Task> action = async () => await stream.PopulateAsync(buffer);
+
+        await action.ShouldThrowAsync<EndOfStreamException>();
+    }
+}

Core/Base32.cs

@@ -4,40 +4,53 @@ public static class Base32
 {
     public const string Alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
     public const char Padding = '=';
+    public const int MaxBytesStack = 250;
 
     [Pure]
     public static string Encode(ReadOnlySpan<byte> input)
     {
-        if (input.Length == 0)
+        if (input.IsEmpty) return string.Empty;
-        {
-            return string.Empty;
-        }
 
         int outLength = 8 * ((input.Length + 4) / 5);
-        Span<char> output = stackalloc char[outLength];
+        Span<char> output = input.Length <= MaxBytesStack
+            ? stackalloc char[outLength]
+            : new char[outLength];
 
-        _ = Encode(input, output);
+        var size = Encode(input, output);
 
-        return new string(output);
+        return new string(output[..size]);
     }
 
     [Pure]
     public static int Encode(ReadOnlySpan<byte> input, Span<char> output)
     {
+        if (input.IsEmpty) return 0;
+
+        int outputLength = 8 * ((input.Length + 4) / 5);
+        if (output.Length < outputLength)
+        {
+            throw new ArgumentException("Encoded input can not fit in output span.", nameof(output));
+        }
+
+        output = output[..outputLength];
+
         int i = 0;
         ReadOnlySpan<char> alphabet = Alphabet;
+        Span<byte> alphabetKeys = stackalloc byte[8];
+
         for (int offset = 0; offset < input.Length;)
         {
-            int numCharsToOutput = GetNextGroup(input, ref offset, out byte a, out byte b, out byte c, out byte d, out byte e, out byte f, out byte g, out byte h);
+            alphabetKeys.Clear();
+            int numCharsToOutput = GetNextGroup(input, ref offset, alphabetKeys);
 
-            output[i++] = (numCharsToOutput > 0) ? alphabet[a] : Padding;
+            output[i++] = (numCharsToOutput > 0) ? alphabet[alphabetKeys[0]] : Padding;
-            output[i++] = (numCharsToOutput > 1) ? alphabet[b] : Padding;
+            output[i++] = (numCharsToOutput > 1) ? alphabet[alphabetKeys[1]] : Padding;
-            output[i++] = (numCharsToOutput > 2) ? alphabet[c] : Padding;
+            output[i++] = (numCharsToOutput > 2) ? alphabet[alphabetKeys[2]] : Padding;
-            output[i++] = (numCharsToOutput > 3) ? alphabet[d] : Padding;
+            output[i++] = (numCharsToOutput > 3) ? alphabet[alphabetKeys[3]] : Padding;
-            output[i++] = (numCharsToOutput > 4) ? alphabet[e] : Padding;
+            output[i++] = (numCharsToOutput > 4) ? alphabet[alphabetKeys[4]] : Padding;
-            output[i++] = (numCharsToOutput > 5) ? alphabet[f] : Padding;
+            output[i++] = (numCharsToOutput > 5) ? alphabet[alphabetKeys[5]] : Padding;
-            output[i++] = (numCharsToOutput > 6) ? alphabet[g] : Padding;
+            output[i++] = (numCharsToOutput > 6) ? alphabet[alphabetKeys[6]] : Padding;
-            output[i++] = (numCharsToOutput > 7) ? alphabet[h] : Padding;
+            output[i++] = (numCharsToOutput > 7) ? alphabet[alphabetKeys[7]] : Padding;
         }
         return i;
     }
@@ -45,9 +58,13 @@ public static class Base32
     [Pure]
     public static byte[] Decode(ReadOnlySpan<char> input)
     {
+        input = input.TrimEnd(Padding);
         if (input.IsEmpty) return [];
 
-        Span<byte> output = stackalloc byte[5 * input.Length / 8];
+        var outputLength = 5 * ((input.Length + 7) / 8);
+        Span<byte> output = outputLength <= MaxBytesStack
+            ? stackalloc byte[outputLength]
+            : new byte[outputLength];
 
         var size = Decode(input, output);
 
@@ -58,7 +75,19 @@ public static class Base32
     public static int Decode(ReadOnlySpan<char> input, Span<byte> output)
     {
         input = input.TrimEnd(Padding);
-        Span<char> inputspan = stackalloc char[input.Length];
+
+        var outputLength = 5 * ((input.Length + 7) / 8);
+        if (output.Length < outputLength)
+        {
+            throw new ArgumentException("Decoded input can not fit in output span.", nameof(output));
+        }
+
+        output = output[..outputLength];
+        output.Clear();
+
+        Span<char> inputspan = outputLength <= MaxBytesStack
+            ? stackalloc char[input.Length]
+            : new char[input.Length];
         input.ToUpperInvariant(inputspan);
 
         int bitIndex = 0;
@@ -104,10 +133,9 @@ public static class Base32
         return outputIndex + (outputBits + 7) / 8;
     }
 
-    
     // returns the number of bytes that were output
     [Pure]
-    private static int GetNextGroup(ReadOnlySpan<byte> input, ref int offset, out byte a, out byte b, out byte c, out byte d, out byte e, out byte f, out byte g, out byte h)
+    private static int GetNextGroup(ReadOnlySpan<byte> input, ref int offset, Span<byte> alphabetKeys)
     {
         var retVal = (input.Length - offset) switch
         {
@@ -123,14 +151,14 @@ public static class Base32
         uint b4 = (offset < input.Length) ? input[offset++] : 0U;
         uint b5 = (offset < input.Length) ? input[offset++] : 0U;
 
-        a = (byte)(b1 >> 3);
+        alphabetKeys[0] = (byte)(b1 >> 3);
-        b = (byte)(((b1 & 0x07) << 2) | (b2 >> 6));
+        alphabetKeys[1] = (byte)(((b1 & 0x07) << 2) | (b2 >> 6));
-        c = (byte)((b2 >> 1) & 0x1f);
+        alphabetKeys[2] = (byte)((b2 >> 1) & 0x1f);
-        d = (byte)(((b2 & 0x01) << 4) | (b3 >> 4));
+        alphabetKeys[3] = (byte)(((b2 & 0x01) << 4) | (b3 >> 4));
-        e = (byte)(((b3 & 0x0f) << 1) | (b4 >> 7));
+        alphabetKeys[4] = (byte)(((b3 & 0x0f) << 1) | (b4 >> 7));
-        f = (byte)((b4 >> 2) & 0x1f);
+        alphabetKeys[5] = (byte)((b4 >> 2) & 0x1f);
-        g = (byte)(((b4 & 0x3) << 3) | (b5 >> 5));
+        alphabetKeys[6] = (byte)(((b4 & 0x3) << 3) | (b5 >> 5));
-        h = (byte)(b5 & 0x1f);
+        alphabetKeys[7] = (byte)(b5 & 0x1f);
 
         return retVal;
     }

Core/Base64Url.cs

@@ -1,24 +1,41 @@
+using System.Runtime.InteropServices;
+
 namespace Just.Core;
 
 public static class Base64Url
 {
+    private const char Padding = '=';
+
+    [Pure] public static long DecodeLong(ReadOnlySpan<char> value)
+    {
+        ArgumentOutOfRangeException.ThrowIfNotEqual(value.Length, 11);
+
+        Span<byte> longBytes = stackalloc byte[8];
+        Span<char> chars = stackalloc char[12];
+
+        value.CopyTo(chars);
+        chars[^1] = Padding;
+
+        ReplaceNonUrlChars(chars);
+
+        if (!Convert.TryFromBase64Chars(chars, longBytes, out int _))
+            throw new FormatException("Invalid Base64 string.");
+
+        return MemoryMarshal.Read<long>(longBytes);
+    }
+
     [Pure] public static Guid DecodeGuid(ReadOnlySpan<char> value)
     {
         ArgumentOutOfRangeException.ThrowIfNotEqual(value.Length, 22);
 
         Span<byte> guidBytes = stackalloc byte[16];
         Span<char> chars = stackalloc char[24];
+
         value.CopyTo(chars);
-        for (int i = 0; i < value.Length; i++)
+        chars[^2..].Fill(Padding);
-        {
+
-            switch (value[i])
+        ReplaceNonUrlChars(chars);
-            {
+
-                case '-': chars[i] = '+'; continue;
-                case '_': chars[i] = '/'; continue;
-                default: continue;
-            }
-        }
-        chars[^2..].Fill('=');
         if (!Convert.TryFromBase64Chars(chars, guidBytes, out int _))
             throw new FormatException("Invalid Base64 string.");
 
@@ -40,21 +57,14 @@ public static class Base64Url
     {
         var padding = (4 - (value.Length & 3)) & 3;
         var charlen = value.Length + padding;
-        var outputBytes = charlen / 4;
+        var outputBytes = 3 * (charlen / 4);
         ArgumentOutOfRangeException.ThrowIfLessThan(output.Length, outputBytes);
         Span<char> chars = stackalloc char[charlen];
 
         value.CopyTo(chars);
-        for (int i = 0; i < value.Length; i++)
+        chars[^padding..].Fill(Padding);
-        {
+
-            switch (value[i])
+        ReplaceNonUrlChars(chars);
-            {
-                case '-': chars[i] = '+'; continue;
-                case '_': chars[i] = '/'; continue;
-                default: continue;
-            }
-        }
-        chars[^padding..].Fill('=');
 
         if (!Convert.TryFromBase64Chars(chars, output, out outputBytes))
             throw new FormatException("Invalid Base64 string.");
@@ -62,6 +72,18 @@ public static class Base64Url
         return outputBytes;
     }
 
+    [Pure] public static string Encode(in long id)
+    {
+        Span<byte> longBytes = stackalloc byte[8];
+        MemoryMarshal.Write(longBytes, id);
+
+        Span<char> chars = stackalloc char[12];
+        Convert.TryToBase64Chars(longBytes, chars, out int _);
+        ReplaceUrlChars(chars[..^1]);
+
+        return new string(chars[..^1]);
+    }
+
     [Pure] public static string Encode(in Guid id)
     {
         Span<byte> guidBytes = stackalloc byte[16];
@@ -69,15 +91,7 @@ public static class Base64Url
         Span<char> chars = stackalloc char[24];
         Convert.TryToBase64Chars(guidBytes, chars, out int _);
 
-        for (int i = 0; i < chars.Length - 2; i++)
+        ReplaceUrlChars(chars[..^2]);
-        {
-            switch (chars[i])
-            {
-                case '+': chars[i] = '-'; continue;
-                case '/': chars[i] = '_'; continue;
-                default: continue;
-            }
-        }
 
         return new string(chars[..^2]);
     }
@@ -86,7 +100,7 @@ public static class Base64Url
     {
         if (input.IsEmpty) return string.Empty;
 
-        int outLength = 8 * ((input.Length + 5) / 6);
+        int outLength = 4 * ((input.Length + 2) / 3);
         Span<char> output = stackalloc char[outLength];
 
         int strlen = Encode(input, output);
@@ -95,24 +109,49 @@ public static class Base64Url
 
     [Pure] public static int Encode(ReadOnlySpan<byte> input, Span<char> output)
     {
-        var charlen = 8 * ((input.Length + 5) / 6);
+        if (input.IsEmpty) return 0;
+
+        var charlen = 4 * ((input.Length + 2) / 3);
         Span<char> chars = stackalloc char[charlen];
         Convert.TryToBase64Chars(input, chars, out int charsWritten);
 
-        int i;
+        int i = ReplaceUrlChars(chars[..charsWritten]);
-        for (i = 0; i < charsWritten; i++)
+        chars[..i].CopyTo(output);
+
+        return i;
+    }
+
+    private static int ReplaceUrlChars(Span<char> chars)
+    {
+        int i = 0;
+        for (; i < chars.Length; i++)
         {
             switch (chars[i])
             {
                 case '+': chars[i] = '-'; continue;
                 case '/': chars[i] = '_'; continue;
-                case '=': goto exitLoop;
+                case Padding: goto break_loop;
                 default: continue;
             }
         }
-        exitLoop:
+        break_loop:
-        chars[..i].CopyTo(output);
+        return i;
+    }
 
+    private static int ReplaceNonUrlChars(Span<char> chars)
+    {
+        int i = 0;
+        for (; i < chars.Length; i++)
+        {
+            switch (chars[i])
+            {
+                case '-': chars[i] = '+'; continue;
+                case '_': chars[i] = '/'; continue;
+                case Padding: goto break_loop;
+                default: continue;
+            }
+        }
+        break_loop:
         return i;
     }
 }

Core/Collections/ImmutableSequence.cs

@@ -0,0 +1,83 @@
+using System.Collections;
+using System.Collections.Immutable;
+
+namespace Just.Core.Collections;
+
+public class ImmutableSequence<T> :
+    IEnumerable<T>,
+    IReadOnlyList<T>,
+    IEquatable<ImmutableSequence<T>>
+{
+    private static readonly Func<T?, T?, bool> CompareItem = EqualityComparer<T>.Default.Equals;
+    private readonly ImmutableList<T> _values;
+
+    public ImmutableSequence() => _values = [];
+    public ImmutableSequence(ImmutableList<T> values) => _values = values;
+    public ImmutableSequence(IEnumerable<T> values) => _values = [..values];
+    public ImmutableSequence(ReadOnlySpan<T> values) : this(ImmutableList.Create(values))
+    {
+    }
+
+    public bool IsEmpty => _values.IsEmpty;
+    public int Count => _values.Count;
+    public T this[int index] => _values[index];
+    public T this[Index index] => _values[index];
+    public ImmutableSequence<T> this[Range range]
+    {
+        get
+        {
+            var (offset, count) = range.GetOffsetAndLength(_values.Count);
+            return ConstructNew(_values.GetRange(offset, count));
+        }
+    }
+
+    protected virtual ImmutableSequence<T> ConstructNew(ImmutableList<T> values) => [..values];
+
+    public ImmutableSequence<T> Add(T value) => ConstructNew(_values.Add(value));
+    public ImmutableSequence<T> AddFront(T value) => ConstructNew(_values.Insert(0, value));
+
+    public ImmutableList<T>.Enumerator GetEnumerator() => _values.GetEnumerator();
+    IEnumerator<T> IEnumerable<T>.GetEnumerator() => ((IEnumerable<T>)_values).GetEnumerator();
+    IEnumerator IEnumerable.GetEnumerator() => ((IEnumerable)_values).GetEnumerator();
+
+    public override string ToString() => string.Join(Environment.NewLine, _values);
+
+    public virtual bool Equals([NotNullWhen(true)] ImmutableSequence<T>? other)
+    {
+        if (ReferenceEquals(this, other))
+        {
+            return true;
+        }
+
+        if (_values.Count != other?._values.Count)
+        {
+            return false;
+        }
+
+        for (int i = 0; i < _values.Count; i++)
+        {
+            if (!CompareItem(_values[i], other._values[i]))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    public override bool Equals([NotNullWhen(true)] object? obj) => Equals(obj as ImmutableSequence<T>);
+    public override int GetHashCode()
+    {
+        HashCode hash = new();
+
+        foreach (var value in _values)
+        {
+            hash.Add(value);
+        }
+
+        return hash.ToHashCode();
+    }
+
+    public static bool operator ==(ImmutableSequence<T>? left, ImmutableSequence<T>? right) => left is null ? right is null : left.Equals(right);
+    public static bool operator !=(ImmutableSequence<T>? left, ImmutableSequence<T>? right) => !(left == right);
+}

Core/Core.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
+    <TargetFrameworks>net8.0;net9.0;net10.0</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <AssemblyName>Just.Core</AssemblyName>
@@ -10,7 +10,7 @@
     <Description>Small .Net library with useful helper classes, functions and extensions.</Description>
     <PackageTags>extensions;helpers;helper-functions</PackageTags>
     <Authors>JustFixMe</Authors>
-    <Copyright>Copyright (c) 2023 JustFixMe</Copyright>
+    <Copyright>Copyright (c) 2023-2025 JustFixMe</Copyright>
     <PackageLicenseFile>LICENSE</PackageLicenseFile>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <RepositoryUrl>https://github.com/JustFixMe/Just.Core/</RepositoryUrl>

Core/Extensions/SystemIOStreamExtensions.cs

@@ -1,46 +1,114 @@
 namespace Just.Core.Extensions;
 
+/// <summary>
+/// Provides extension methods for <see cref="Stream"/> to fully populate buffers.
+/// </summary>
 public static class SystemIOStreamExtensions
 {
+    /// <summary>
+    /// Reads data from the stream until the specified section of the buffer is filled.
+    /// </summary>
+    /// <param name="stream">The stream to read from</param>
+    /// <param name="buffer">The buffer to populate</param>
+    /// <param name="offset">The starting offset in the buffer</param>
+    /// <param name="length">The number of bytes to read</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="stream"/> is null</exception>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when <paramref name="offset"/> or <paramref name="length"/> is invalid</exception>
+    /// <exception cref="EndOfStreamException">Thrown if the stream ends before filling the buffer</exception>
+    /// <exception cref="IOException">Thrown for I/O errors during reading</exception>
     public static void Populate(this Stream stream, byte[] buffer, int offset, int length)
         => stream.Populate(buffer.AsSpan(offset, length));
+    /// <summary>
+    /// Reads data from the stream until the entire buffer is filled.
+    /// </summary>
+    /// <param name="stream">The stream to read from</param>
+    /// <param name="buffer">The buffer to populate</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="stream"/> is null</exception>
+    /// <exception cref="EndOfStreamException">Thrown if the stream ends before filling the buffer</exception>
+    /// <exception cref="IOException">Thrown for I/O errors during reading</exception>
     public static void Populate(this Stream stream, byte[] buffer)
         => stream.Populate(buffer.AsSpan());
+    /// <summary>
+    /// Reads data from the stream until the specified span is filled.
+    /// </summary>
+    /// <param name="stream">The stream to read from</param>
+    /// <param name="buffer">The span to populate</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="stream"/> is null</exception>
+    /// <exception cref="EndOfStreamException">Thrown if the stream ends before filling the buffer</exception>
+    /// <exception cref="IOException">Thrown for I/O errors during reading</exception>
     public static void Populate(this Stream stream, Span<byte> buffer)
     {
-        do
+        ArgumentNullException.ThrowIfNull(stream);
-        {
-            var readed = stream.Read(buffer);
 
-            if (readed == 0)
+        while (!buffer.IsEmpty)
+        {
+            var bytesRead = stream.Read(buffer);
+
+            if (bytesRead == 0)
             {
                 throw new EndOfStreamException();
             }
 
-            buffer = buffer[readed..];
+            buffer = buffer[bytesRead..];
         }
-        while (buffer.Length > 0);
     }
 
-    public static async ValueTask PopulateAsync(this Stream stream, byte[] buffer, CancellationToken cancellationToken = default)
+    /// <summary>
-        => await stream.PopulateAsync(buffer.AsMemory(), cancellationToken);
+    /// Asynchronously reads data from the stream until the entire buffer is filled.
-    public static async ValueTask PopulateAsync(this Stream stream, byte[] buffer, int offset, int length, CancellationToken cancellationToken = default)
+    /// </summary>
-        => await stream.PopulateAsync(buffer.AsMemory(offset, length), cancellationToken);
+    /// <param name="stream">The stream to read from</param>
+    /// <param name="buffer">The buffer to populate</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>A ValueTask representing the asynchronous operation</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="stream"/> is null</exception>
+    /// <exception cref="EndOfStreamException">Thrown if the stream ends before filling the buffer</exception>
+    /// <exception cref="OperationCanceledException">Thrown if canceled via cancellation token</exception>
+    /// <exception cref="IOException">Thrown for I/O errors during reading</exception>
+    public static ValueTask PopulateAsync(this Stream stream, byte[] buffer, CancellationToken cancellationToken = default)
+        => stream.PopulateAsync(buffer.AsMemory(), cancellationToken);
+    /// <summary>
+    /// Asynchronously reads data from the stream until the specified section of the buffer is filled.
+    /// </summary>
+    /// <param name="stream">The stream to read from</param>
+    /// <param name="buffer">The buffer to populate</param>
+    /// <param name="offset">The starting offset in the buffer</param>
+    /// <param name="length">The number of bytes to read</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>A ValueTask representing the asynchronous operation</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="stream"/> is null</exception>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when <paramref name="offset"/> or <paramref name="length"/> is invalid</exception>
+    /// <exception cref="EndOfStreamException">Thrown if the stream ends before filling the buffer</exception>
+    /// <exception cref="OperationCanceledException">Thrown if canceled via cancellation token</exception>
+    /// <exception cref="IOException">Thrown for I/O errors during reading</exception>
+    public static ValueTask PopulateAsync(this Stream stream, byte[] buffer, int offset, int length, CancellationToken cancellationToken = default)
+        => stream.PopulateAsync(buffer.AsMemory(offset, length), cancellationToken);
+    /// <summary>
+    /// Asynchronously reads data from the stream until the specified memory region is filled.
+    /// </summary>
+    /// <param name="stream">The stream to read from</param>
+    /// <param name="buffer">The memory region to populate</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    /// <returns>A ValueTask representing the asynchronous operation</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="stream"/> is null</exception>
+    /// <exception cref="EndOfStreamException">Thrown if the stream ends before filling the buffer</exception>
+    /// <exception cref="OperationCanceledException">Thrown if canceled via cancellation token</exception>
+    /// <exception cref="IOException">Thrown for I/O errors during reading</exception>
     public static async ValueTask PopulateAsync(this Stream stream, Memory<byte> buffer, CancellationToken cancellationToken = default)
     {
-        do
+        ArgumentNullException.ThrowIfNull(stream);
+
+        while (!buffer.IsEmpty)
         {
             cancellationToken.ThrowIfCancellationRequested();
 
-            var readed = await stream.ReadAsync(buffer, cancellationToken);
+            var bytesRead = await stream.ReadAsync(buffer, cancellationToken).ConfigureAwait(false);
 
-            if (readed == 0)
+            if (bytesRead == 0)
             {
                 throw new EndOfStreamException();
             }
 
-            buffer = buffer[readed..];
+            buffer = buffer[bytesRead..];
         }
-        while (buffer.Length > 0);
     }
 }

Core/GuidV8.cs

@@ -0,0 +1,42 @@
+using System.Security.Cryptography;
+
+namespace Just.Core;
+
+public static class GuidV8
+{
+    private const long TicksPrecision = TimeSpan.TicksPerMillisecond / 10;
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static Guid NewGuid(RngEntropy entropy = RngEntropy.Strong) => NewGuid(DateTime.UtcNow, entropy);
+
+    public static Guid NewGuid(DateTime dateTime, RngEntropy entropy = RngEntropy.Strong)
+    {
+        var epoch = dateTime.Subtract(DateTime.UnixEpoch);
+        var timestamp = epoch.Ticks / TicksPrecision;
+
+        uint tsHigh = (uint)((timestamp >> 16) & 0xFFFFFFFF);
+        ushort tsLow = (ushort)(timestamp & 0x0000FFFF);
+
+        Span<byte> bytes = stackalloc byte[10];
+
+        if (entropy == RngEntropy.Strong)
+        {
+            RandomNumberGenerator.Fill(bytes);
+        }
+        else
+        {
+            Random.Shared.NextBytes(bytes);
+        }
+
+        bytes[0] = (byte)((bytes[0] & 0x0F) | 0x80); // Version 8
+        bytes[2] = (byte)((bytes[2] & 0x1F) | 0x80); // Variant 0b1000
+
+        ushort version = (ushort)((bytes[0] << 8) | bytes[1]);
+
+        return new Guid(
+            tsHigh,
+            tsLow,
+            version,
+            bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7], bytes[8], bytes[9]);
+    }
+}

Core/RngEntropy.cs

@@ -0,0 +1,16 @@
+namespace Just.Core;
+
+/// <summary>
+/// Specifies the quality of random entropy used in ID generation
+/// </summary>
+public enum RngEntropy
+{
+    /// <summary>
+    /// Cryptographically secure random numbers (slower but collision-resistant)
+    /// </summary>
+    Strong,
+    /// <summary>
+    /// Standard pseudo-random numbers (faster but less collision-resistant)
+    /// </summary>
+    Weak
+}

Core/SeqId.cs

@@ -0,0 +1,121 @@
+using System.Security.Cryptography;
+
+namespace Just.Core;
+
+/// <summary>
+/// Generates time-based sequential IDs with entropy
+/// <para>ID Structure (64 bits):</para>
+/// <list type="bullet">
+/// <item><description>[1 bit] Always 0 (positive signed longs)</description></item>
+/// <item><description>[41 bits] Milliseconds since epoch (covers ~69 years)</description></item>
+/// <item><description>[8 bits] Sequence counter (0-255 per millisecond)</description></item>
+/// <item><description>[14 bits] Random entropy (0-16383)</description></item>
+/// </list>
+/// </summary>
+/// <remarks>
+/// Important behaviors:
+/// <list type="bullet">
+/// <item><description>Guarantees monotonic ordering within same millisecond</description></item>
+/// <item><description>Throws <see cref="InvalidOperationException"/> on backward time jumps</description></item>
+/// <item><description>Sequence resets when timestamp advances</description></item>
+/// <item><description>Thread-safe through locking</description></item>
+/// </list>
+/// </remarks>
+public sealed class SeqId(DateTime epoch)
+{
+    private const int TimestampBits = 41;
+    private const int TimestampShift = 63 - TimestampBits;
+    private const long TimestampMask = 0x000001FF_FFFFFFFF;
+
+    private const int SeqBits = 8;
+    private const int SeqShift = TimestampShift - SeqBits;
+    private const long SeqMask = 0x00000000_000000FF;
+
+    private const int RandExclusiveUpper = 1 << SeqShift;
+
+    /// <summary>
+    /// Default epoch (2025-01-01 UTC) used for <see cref="Default"/> instance
+    /// </summary>
+    public static DateTime DefaultEpoch { get; } = new(2025, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+    /// <summary>
+    /// Default instance using <see cref="DefaultEpoch"/>
+    /// </summary>
+    public static SeqId Default { get; } = new(DefaultEpoch);
+
+    /// <summary>
+    /// Generates ID using default instance and current UTC time
+    /// </summary>
+    /// <param name="entropy">Entropy quality (default: Strong)</param>
+    /// <returns>64-bit sequential ID with random component</returns>
+    /// <exception cref="IndexOutOfRangeException">
+    /// Thrown if more than 255 IDs generated in 1ms
+    /// </exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static long NextId(RngEntropy entropy = RngEntropy.Strong) => Default.Next(DateTime.UtcNow, entropy);
+
+#if NET9_0_OR_GREATER
+    private readonly Lock _lock = new();
+#else
+    private readonly object _lock = new();
+#endif
+
+    private readonly DateTime _epoch = epoch;
+    private int _seqId = 0;
+    private long _lastTimestamp = -1L;
+
+    /// <summary>
+    /// Generates next ID using current UTC time
+    /// </summary>
+    /// <param name="entropy">Entropy quality (default: Strong)</param>
+    /// <returns>64-bit sequential ID with random component</returns>
+    /// <exception cref="IndexOutOfRangeException">
+    /// Thrown if more than 255 IDs generated in 1ms
+    /// </exception>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public long Next(RngEntropy entropy = RngEntropy.Strong) => Next(DateTime.UtcNow, entropy);
+
+    /// <summary>
+    /// Generates next ID with explicit timestamp
+    /// </summary>
+    /// <param name="dateTime">Timestamp basis for ID generation</param>
+    /// <param name="entropy">Entropy quality (default: Strong)</param>
+    /// <returns>64-bit sequential ID with random component</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown if <paramref name="dateTime"/> is earlier than last used timestamp
+    /// </exception>
+    /// <exception cref="IndexOutOfRangeException">
+    /// Thrown if more than 255 IDs generated in 1ms
+    /// </exception>
+    public long Next(DateTime dateTime, RngEntropy entropy = RngEntropy.Strong)
+    {
+        var epoch = dateTime.Subtract(_epoch);
+        var timestamp = ((epoch.Ticks / TimeSpan.TicksPerMillisecond) & TimestampMask) << TimestampShift;
+
+        long currentSeq;
+        lock (_lock)
+        {
+            if (timestamp > _lastTimestamp)
+            {
+                _lastTimestamp = timestamp;
+                _seqId = 0;
+            }
+            else if (timestamp < _lastTimestamp)
+            {
+                throw new InvalidOperationException("Refused to create new SeqId. Last timestamp is in the future.");
+            }
+
+            if (_seqId == SeqMask)
+            {
+                throw new IndexOutOfRangeException("Refused to create new SeqId. Sequence exhausted.");
+            }
+
+            currentSeq = ((_seqId++) & SeqMask) << SeqShift;
+        }
+
+        long currentRand = entropy == RngEntropy.Strong
+            ? RandomNumberGenerator.GetInt32(RandExclusiveUpper)
+            : Random.Shared.Next(RandExclusiveUpper);
+
+        return timestamp | currentSeq | currentRand;
+    }
+}

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2023 JustFixMe
+Copyright (c) 2023-2025 JustFixMe
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal