Enhance Random Effect with Additional Generators & Seeding

[haskiindahouse]

Summary

The current Random effect exposes only three basic methods:

Random.nextBoolean
Random.nextInt
Random.nextDouble

To support a broader range of use-cases—statistical simulations, property-based testing, cryptography utilities, etc.—we should expand the Random API with advanced generators and enable deterministic reproducibility via seeding.

Motivation

• Richer functionality
  Advanced generators such as nextGaussian (normal distribution) and nextBytes ❓ unlock Monte Carlo algorithms, numeric simulations, realistic test data, and more.
• Determinism & Reproducibility
  Seeding the RNG is critical for writing repeatable tests and debugging non-deterministic issues.

Proposed API Additions

import in.rcard.yaes.Random

trait Random:
  ...
  /** Gaussian (normal) distribution with mean 0.0 and std-dev 1.0 */
  def nextGaussian: Double

  /** Returns a new Random instance initialized with the specified seed */
  def withSeed(seed: Long): Random

Implementation Sketch

• Leverage java.util.random.RandomGenerator (Java 17+) under the hood for all methods. (now using scala.random package)

Acceptance Criteria

1. API surface
   • Implement nextGaussian.
   • Add withSeed(seed: Long) for deterministic instances.
2. Correctness
   • Property-based tests confirming Gaussian mean ≈ 0.0.
   • Uniformity tests for nextInt(n) and nextBytes.
3. Documentation
   • Update README with usage examples.
4. Compatibility
   • Preserve binary compatibility for existing calls to nextInt, nextDouble, and nextBoolean.

References

• Java 17 RandomGenerator API – rich RNG support with seeding.
• ScalaCheck – examples of deterministic generators in property-based tests.
• Cats Effect (cats.effect.std.Random) – inspiration for method signatures and semantics.

[rcardin]

@haskiindahouse, if we use the Java RandomGenerator API, we'll also lose the chance to implement YAES for ScalaJs and ScalaNative. I know that the whole Async DSL is bound to the Java world, but I'd like to extend it in the future.

What are your thoughts?

[haskiindahouse]

@rcardin I noticed in the Scala.js 1.19.0 release notes (https://www.scala-js.org/news/2025/04/21/announcing-scalajs-1.19.0/) that java.util.random.RandomGenerator still isn’t fully supported.

How critical is Scala .js / Scala Native compatibility for YÆS right now? Full support will probably land eventually, but until then we could:

• keep using scala.util.Random under the hood, and
• simply monitor the progress on RandomGenerator support for JS/Native.

We could add a platform-specific factory later, yet it might be unnecessary complexity at this stage.

[rcardin]

@haskiindahouse, as I said, the whole Async effect depends on Java Virtual Threads. So, the elephant in the room is there.

Let's move on with this issue and implement it. It will port the value to the library bound to Java. If needed, we'll study a multiplatform strategy in the future.

I assigned the issue to you if you'd like to proceed. Again, thanks for your time. 🙏