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
-      run: dotnet build --no-restore
+    - name: Build .NET 10.0
+      run: dotnet build --no-restore --framework net10.0 --configuration Release ./Core.Tests/Core.Tests.csproj
 
-    - name: Test
-      run: dotnet test --no-build --verbosity normal --logger trx --results-directory "TestResults-8.x"
+    - name: Build .NET 9.0
+      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
-        path: TestResults-8.x
+        name: test-results
+        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,9 +34,9 @@ public class Decode
     public void WhenCalledWithValidString_ShouldReturnValidByteArray(string str, byte[] expected)
     {
         var actualBytesArray = Base32.Decode(str);
-        actualBytesArray.Should().Equal(expected);
+        actualBytesArray.ShouldBe(expected);
     }
-    
+
     [Theory]
     [InlineData("ZFXJMF5N====", new byte[] { 0b11001001, 0b01101110, 0b10010110, 0b00010111, 0b10101101, })]
     [InlineData("CPIKTMY=====", new byte[] { 0b00010011, 0b11010000, 0b10101001, 0b10110011, })]
@@ -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,9 +54,9 @@ public class Decode
     public void WhenCalledWithValidStringWithoutPaddingSign_ShouldReturnValidByteArray(string testString, byte[] expected)
     {
         var actualBytesArray = Base32.Decode(testString);
-        actualBytesArray.Should().Equal(expected);
+        actualBytesArray.ShouldBe(expected);
     }
-    
+
     [Theory]
     [InlineData("  ")]
     [InlineData("hg2515i3215")]
@@ -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,10 +1,11 @@
 <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="Microsoft.NET.Test.Sdk" Version="17.6.0" />
-    <PackageReference Include="xunit" Version="2.4.2" />
-    <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">
+    <PackageReference Include="Shouldly" Version="4.3.0" />
+    <PackageReference Include="xunit.v3" Version="3.2.0" />
+    <PackageReference Include="coverlet.collector" Version="6.0.4">
       <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

@@ -3,15 +3,43 @@ namespace Just.Core.Tests.GuidV8Tests;
 public class NewGuid
 {
     [Theory]
-    [InlineData(GuidV8Entropy.Weak,
-        -25000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+    [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, 100000000, 250000000)]
-    [InlineData(GuidV8Entropy.Strong,
-        -25000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+        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, 100000000, 250000000)]
-    [InlineData(GuidV8Entropy.Weak,
+        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,
@@ -22,7 +50,7 @@ public class NewGuid
         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(GuidV8Entropy.Strong,
+    [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,
@@ -33,29 +61,29 @@ public class NewGuid
         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(GuidV8Entropy.Weak,
-        5635912, 6673780, 17277183, 17512959, 19098799, 21672621, 30581958, 30824885, 31874213, 35192781,
-        36337094, 37752116, 38387215, 39154682, 40525427, 52288093, 55218356, 59065156, 65231785, 75430932,
-        76289058, 79078058, 85770685, 85925884, 94726743, 94864163, 95781967, 96150006, 96482085, 102570414,
-        107768232, 110571078, 110680108, 117974892, 119800380, 126381415, 135895862, 140034471, 149039187, 150906974,
-        156853001, 160514433, 166446323, 170148965, 171759448, 176494242, 184537553, 188558155, 197194403, 197615804,
-        201195323, 202294490, 203040975, 203331457, 205016944, 213460258, 217072025, 217185345, 231344025, 232390198,
-        235053215, 240175073, 245030721, 252275255, 252310334, 277070940, 277359970, 280624756, 288601124, 292427106,
-        292563035, 299285016, 303834917, 310357836, 315078337, 316367236, 318311758, 318873972, 319675272, 321784171,
-        324204294, 327667283, 330287252, 338438172, 349863360, 360777768, 366398711, 368637150, 368776734, 371900343,
-        379094084, 379818879, 381448333, 381814627, 382393101, 382483709, 385600870, 389455134, 396115960, 399364095)]
-    [InlineData(GuidV8Entropy.Strong,
-        5635912, 6673780, 17277183, 17512959, 19098799, 21672621, 30581958, 30824885, 31874213, 35192781,
-        36337094, 37752116, 38387215, 39154682, 40525427, 52288093, 55218356, 59065156, 65231785, 75430932,
-        76289058, 79078058, 85770685, 85925884, 94726743, 94864163, 95781967, 96150006, 96482085, 102570414,
-        107768232, 110571078, 110680108, 117974892, 119800380, 126381415, 135895862, 140034471, 149039187, 150906974,
-        156853001, 160514433, 166446323, 170148965, 171759448, 176494242, 184537553, 188558155, 197194403, 197615804,
-        201195323, 202294490, 203040975, 203331457, 205016944, 213460258, 217072025, 217185345, 231344025, 232390198,
-        235053215, 240175073, 245030721, 252275255, 252310334, 277070940, 277359970, 280624756, 288601124, 292427106,
-        292563035, 299285016, 303834917, 310357836, 315078337, 316367236, 318311758, 318873972, 319675272, 321784171,
-        324204294, 327667283, 330287252, 338438172, 349863360, 360777768, 366398711, 368637150, 368776734, 371900343,
-        379094084, 379818879, 381448333, 381814627, 382393101, 382483709, 385600870, 389455134, 396115960, 399364095)]
-    public void Guids_Differing_By_Minutes_Should_Be_Sortable(GuidV8Entropy entropy, params int[] seconds)
+    [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);
@@ -69,23 +97,23 @@ public class NewGuid
         var sut = expected.Values.ToArray();
         rng.Shuffle(sut);
 
-        sut.Order().Should().Equal(expected.Select(x => x.Value));
-        sut.OrderBy(x => x.ToString()).Should().Equal(expected.Select(x => x.Value));
+        sut.Order().ShouldBe(expected.Select(x => x.Value));
+        sut.OrderBy(x => x.ToString()).ShouldBe(expected.Select(x => x.Value));
 
-        sut.OrderDescending().Should().Equal(expected.Reverse().Select(x => x.Value));
-        sut.OrderByDescending(x => x.ToString()).Should().Equal(expected.Reverse().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(GuidV8Entropy.Weak,
-        -250000000, -25000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+    [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, 2100000000)]
-    [InlineData(GuidV8Entropy.Strong,
-        -250000000, -25000000, -10000000, -5000000, -2000000, -1000000, -500000, -250000, -100000, -25000, -10000, -5000,
+        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, 2100000000)]
-    [InlineData(GuidV8Entropy.Weak,
+        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,
@@ -96,7 +124,7 @@ public class NewGuid
         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(GuidV8Entropy.Strong,
+    [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,
@@ -107,7 +135,7 @@ public class NewGuid
         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(GuidV8Entropy.Weak,
+    [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,
@@ -118,7 +146,7 @@ public class NewGuid
         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(GuidV8Entropy.Strong,
+    [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,
@@ -129,7 +157,7 @@ public class NewGuid
         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(GuidV8Entropy entropy, params int[] seconds)
+    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);
@@ -143,23 +171,23 @@ public class NewGuid
         var sut = expected.Values.ToArray();
         rng.Shuffle(sut);
 
-        sut.Order().Should().Equal(expected.Select(x => x.Value));
-        sut.OrderBy(x => x.ToString()).Should().Equal(expected.Select(x => x.Value));
+        sut.Order().ShouldBe(expected.Select(x => x.Value));
+        sut.OrderBy(x => x.ToString()).ShouldBe(expected.Select(x => x.Value));
 
-        sut.OrderDescending().Should().Equal(expected.Reverse().Select(x => x.Value));
-        sut.OrderByDescending(x => x.ToString()).Should().Equal(expected.Reverse().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(GuidV8Entropy.Weak,
+    [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(GuidV8Entropy.Strong,
+    [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(GuidV8Entropy.Weak,
+    [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,
@@ -170,7 +198,7 @@ public class NewGuid
         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(GuidV8Entropy.Strong,
+    [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,
@@ -181,7 +209,7 @@ public class NewGuid
         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(GuidV8Entropy.Weak,
+    [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,
@@ -192,7 +220,7 @@ public class NewGuid
         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(GuidV8Entropy.Strong,
+    [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,
@@ -203,7 +231,7 @@ public class NewGuid
         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(GuidV8Entropy entropy, params int[] seconds)
+    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);
@@ -217,10 +245,10 @@ public class NewGuid
         var sut = expected.Values.ToArray();
         rng.Shuffle(sut);
 
-        sut.Order().Should().Equal(expected.Select(x => x.Value));
-        sut.OrderBy(x => x.ToString()).Should().Equal(expected.Select(x => x.Value));
+        sut.Order().ShouldBe(expected.Select(x => x.Value));
+        sut.OrderBy(x => x.ToString()).ShouldBe(expected.Select(x => x.Value));
 
-        sut.OrderDescending().Should().Equal(expected.Reverse().Select(x => x.Value));
-        sut.OrderByDescending(x => x.ToString()).Should().Equal(expected.Reverse().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)
-        {
-            return string.Empty;
-        }
+        if (input.IsEmpty) 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 > 1) ? alphabet[b] : Padding;
-            output[i++] = (numCharsToOutput > 2) ? alphabet[c] : Padding;
-            output[i++] = (numCharsToOutput > 3) ? alphabet[d] : Padding;
-            output[i++] = (numCharsToOutput > 4) ? alphabet[e] : Padding;
-            output[i++] = (numCharsToOutput > 5) ? alphabet[f] : Padding;
-            output[i++] = (numCharsToOutput > 6) ? alphabet[g] : Padding;
-            output[i++] = (numCharsToOutput > 7) ? alphabet[h] : Padding;
+            output[i++] = (numCharsToOutput > 0) ? alphabet[alphabetKeys[0]] : Padding;
+            output[i++] = (numCharsToOutput > 1) ? alphabet[alphabetKeys[1]] : Padding;
+            output[i++] = (numCharsToOutput > 2) ? alphabet[alphabetKeys[2]] : Padding;
+            output[i++] = (numCharsToOutput > 3) ? alphabet[alphabetKeys[3]] : Padding;
+            output[i++] = (numCharsToOutput > 4) ? alphabet[alphabetKeys[4]] : Padding;
+            output[i++] = (numCharsToOutput > 5) ? alphabet[alphabetKeys[5]] : Padding;
+            output[i++] = (numCharsToOutput > 6) ? alphabet[alphabetKeys[6]] : Padding;
+            output[i++] = (numCharsToOutput > 7) ? alphabet[alphabetKeys[7]] : Padding;
         }
         return i;
     }
@@ -45,10 +58,14 @@ 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);
 
         return output[..size].ToArray();
@@ -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;
@@ -77,7 +106,7 @@ public static class Base32
             {
                 throw new FormatException("Provided string contains invalid characters.");
             }
-            
+
             bitPos = 5 - bitIndex;
             outBitPos = 8 - outputBits;
             bits = bitPos < outBitPos ? bitPos : outBitPos;
@@ -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);
-        b = (byte)(((b1 & 0x07) << 2) | (b2 >> 6));
-        c = (byte)((b2 >> 1) & 0x1f);
-        d = (byte)(((b2 & 0x01) << 4) | (b3 >> 4));
-        e = (byte)(((b3 & 0x0f) << 1) | (b4 >> 7));
-        f = (byte)((b4 >> 2) & 0x1f);
-        g = (byte)(((b4 & 0x3) << 3) | (b5 >> 5));
-        h = (byte)(b5 & 0x1f);
+        alphabetKeys[0] = (byte)(b1 >> 3);
+        alphabetKeys[1] = (byte)(((b1 & 0x07) << 2) | (b2 >> 6));
+        alphabetKeys[2] = (byte)((b2 >> 1) & 0x1f);
+        alphabetKeys[3] = (byte)(((b2 & 0x01) << 4) | (b3 >> 4));
+        alphabetKeys[4] = (byte)(((b3 & 0x0f) << 1) | (b4 >> 7));
+        alphabetKeys[5] = (byte)((b4 >> 2) & 0x1f);
+        alphabetKeys[6] = (byte)(((b4 & 0x3) << 3) | (b5 >> 5));
+        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++)
-        {
-            switch (value[i])
-            {
-                case '-': chars[i] = '+'; continue;
-                case '_': chars[i] = '/'; continue;
-                default: continue;
-            }
-        }
-        chars[^2..].Fill('=');
+        chars[^2..].Fill(Padding);
+
+        ReplaceNonUrlChars(chars);
+
         if (!Convert.TryFromBase64Chars(chars, guidBytes, out int _))
             throw new FormatException("Invalid Base64 string.");
 
@@ -28,9 +45,9 @@ public static class Base64Url
     [Pure] public static byte[] Decode(ReadOnlySpan<char> input)
     {
         if (input.IsEmpty) return [];
-        
+
         Span<byte> output = stackalloc byte[3 * ((input.Length + 3) / 4)];
-        
+
         var size = Decode(input, output);
 
         return output[..size].ToArray();
@@ -40,28 +57,33 @@ 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++)
-        {
-            switch (value[i])
-            {
-                case '-': chars[i] = '+'; continue;
-                case '_': chars[i] = '/'; continue;
-                default: continue;
-            }
-        }
-        chars[^padding..].Fill('=');
+        chars[^padding..].Fill(Padding);
+
+        ReplaceNonUrlChars(chars);
 
         if (!Convert.TryFromBase64Chars(chars, output, out outputBytes))
             throw new FormatException("Invalid Base64 string.");
 
         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++)
-        {
-            switch (chars[i])
-            {
-                case '+': chars[i] = '-'; continue;
-                case '/': chars[i] = '_'; continue;
-                default: continue;
-            }
-        }
+        ReplaceUrlChars(chars[..^2]);
 
         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;
-        for (i = 0; i < charsWritten; i++)
+        int i = ReplaceUrlChars(chars[..charsWritten]);
+        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:
-        chars[..i].CopyTo(output);
+        break_loop:
+        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

@@ -1,27 +1,19 @@
 using System.Collections;
 using System.Collections.Immutable;
-using System.Numerics;
 
 namespace Just.Core.Collections;
 
 public class ImmutableSequence<T> :
     IEnumerable<T>,
     IReadOnlyList<T>,
-    IEquatable<ImmutableSequence<T>>,
-    IEqualityOperators<ImmutableSequence<T>, ImmutableSequence<T>, bool>
+    IEquatable<ImmutableSequence<T>>
 {
-    private static readonly int InitialHash = typeof(ImmutableSequence<T>).GetHashCode();
     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() : this(ImmutableArray<T>.Empty)
-    {
-    }
-    public ImmutableSequence(IEnumerable<T> values)
-    {
-        _values = [..values];
-    }
+    public ImmutableSequence(IEnumerable<T> values) => _values = [..values];
     public ImmutableSequence(ReadOnlySpan<T> values) : this(ImmutableList.Create(values))
     {
     }
@@ -39,10 +31,10 @@ public class ImmutableSequence<T> :
         }
     }
 
-    protected virtual ImmutableSequence<T> ConstructNew(ImmutableList<T> values) => new(values);
+    protected virtual ImmutableSequence<T> ConstructNew(ImmutableList<T> values) => [..values];
 
-    public ImmutableSequence<T> Add(T value) => ConstructNew([.._values, value]);
-    public ImmutableSequence<T> AddFront(T value) => ConstructNew([value, .._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();
@@ -77,7 +69,6 @@ public class ImmutableSequence<T> :
     public override int GetHashCode()
     {
         HashCode hash = new();
-        hash.Add(InitialHash);
 
         foreach (var value in _values)
         {

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
-        {
-            var readed = stream.Read(buffer);
+        ArgumentNullException.ThrowIfNull(stream);
 
-            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)
-        => await stream.PopulateAsync(buffer.AsMemory(), cancellationToken);
-    public static async ValueTask PopulateAsync(this Stream stream, byte[] buffer, int offset, int length, CancellationToken cancellationToken = default)
-        => await stream.PopulateAsync(buffer.AsMemory(offset, length), cancellationToken);
+    /// <summary>
+    /// Asynchronously 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>
+    /// <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

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