Improve UX of instances in scope

[gvolpe]

I've prepared the following standalone example to showcase in my upcoming book, and I was wondering if we could do better regarding the import of many given instances.

package demo

import trading.domain.IronCatsInstances.given // this will be import io.github.iltotore.iron.cats.* soon

import cats.*
import cats.derived.*
import io.circe.*
import io.circe.syntax.*
import io.github.iltotore.iron.{ given, * }
import io.github.iltotore.iron.circeSupport.given
import io.github.iltotore.iron.constraint.any.DescribedAs
import io.github.iltotore.iron.constraint.numeric.given
import io.github.iltotore.iron.constraint.numeric.{ Greater, Less }
import io.github.iltotore.iron.constraint.string.given
import io.github.iltotore.iron.constraint.string.{ Alphanumeric, MaxLength, MinLength }

type AgeR = DescribedAs[
  Greater[0] & Less[151],
  "Alien's age must be an integer between 1 and 150"
]

type NameR = DescribedAs[
  Alphanumeric & MinLength[1] & MaxLength[50],
  "Alien's name must be an alphanumeric of max length 50"
]

// format: off
case class Alien(
    name: String :| NameR,
    age: Int :| AgeR
) derives Codec.AsObject, Eq, Show
// format: on

@main def ironDemo =
  val alien = Alien("Bob", 120)
  println(alien.asJson.noSpaces)

Without the explicit given imports, this code would not compile.

Ideally, no explicit given should be visible. This is doable by having instances declared in companion objects directly, you can look at how Cats does it, for example.

If this sounds too complicated, I think we can get away with a single given import.

import io.github.iltotore.iron.{ given, * }

This could re-export the instances of numeric, collection, string and any to give a better user experience.

What do you think?

---

PS. I'd be happy to have a go at this if you agree with either solution (I'd prefer the former, no givens 😃)

[Iltotore]

This is doable by having instances declared in companion objects directly, you can look at how Cats does it, for example.

I was not aware that it is possible, thank you! It is even more suited to Iron since everytime you import given from the lib, you generally star import the package (i.e import io.github.iltotore.iron.{given, *}) too for the traits/extensions.

However, is this behaviour wanted by Scala or is it a bug/trick that could be patched in a new version?

Also, I struggle to find an example that declares given instances in Cats. Can you send an example?

[gvolpe]

I was not aware that it is possible, thank you!

No problems! I imagined you were not familiar with it :)

However, is this behaviour wanted by Scala or is it a bug/trick that could be patched in a new version?

Actually, declaring typeclass instances in companion objects is the default in Scala. So not a bug/trick ;)

Also, I struggle to find an example that declares given instances in Cats. Can you send an example?

Yeah, it's hard to see it in big projects like Cats, especially when they cross-compile to multiple Scala versions. Instead of pointing you somewhere else, I will give you an example on how it would look in Iron directly.

For example, let's take the following refinement type from the numeric package:

final class Greater[V]

object Greater: // this companion object is key
  private trait GreaterConstraint[A, V <: A] extends Constraint[A, Greater[V]]:

    override inline def message: String = "Should be greater than " + stringValue[V]

  inline given [V <: Int]: GreaterConstraint[Int, V] with
    override inline def test(value: Int): Boolean = value > constValue[V]

  inline given [V <: Long]: GreaterConstraint[Long, V] with
    override inline def test(value: Long): Boolean = value > constValue[V]

  inline given [V <: Float]: GreaterConstraint[Float, V] with
    override inline def test(value: Float): Boolean = value > constValue[V]

  inline given [V <: Double]: GreaterConstraint[Double, V] with
    override inline def test(value: Double): Boolean = value > constValue[V]

  given [V1, V2](using V1 > V2 =:= true): (Greater[V1] ==> Greater[V2]) = Implication()
  given [V1, V2](using V1 > V2 =:= true): (StrictEqual[V1] ==> Greater[V2]) = Implication()

If we move all the typeclass instances inside the Greater companion object, you will no longer need to explicitly import them when using it. This applies to all refinement types defined in Iron, instantly giving you 10x better UX.

You can also see it in this PR where I removed the following line from the catsForm example project:

import Account.given //Account entity codec

It is not necessary to do that because the JSON codecs are defined within the Account companion object. Now you'll see this pattern everywhere you look 😺

[Iltotore]

For example, let's take the following refinement type from the numeric package:

I am afraid this would be too much boilerplate. I'd like to keep the constraint creation as simple as possible. I will see how the entier numeric module looks when applying this change. I am also confused that it works in the companion object but not in a non-companion one like numeric.

You can also see it in this PR where I removed the following line from the catsForm example project:

It's late in my country but I will check it tomorrow. Thank you for the quick answer.

[gvolpe]

I am afraid this would be too much boilerplate.

The boilerplate is now on the user side, with all those imports that could go away. I think this would be a great improvement in the library. The approach taken by Iron at the moment is quite unconventional, if we are being honest 😄

Refined, much like other libraries, also provides typeclass instances in companion objects.

I am also confused that it works in the companion object but not in a non-companion one like numeric.

Happy to chat about this. It basically boils down to typeclass instances of your types vs orphan instances for external types. The latter need to be imported, but you can export this at the top level to give a better user experience.

It's late in my country but I will check it tomorrow.

I think we are on the same timezone (assuming you are in France), so feel free to ping me anytime :)