// Core: opaque types, nullable extensions
libraryDependencies += "africa.shuwari" %% "boilerplate" % "<version>"

// Effect: typed-error effects atop cats-effect
libraryDependencies += "africa.shuwari" %% "boilerplate-effect" % "<version>"

SNX.dependencies += "africa.shuwari" %% "boilerplate-native" % "<version>" % NativeClassifier

import boilerplate.*

import boilerplate.*

opaque type UserId = String

object UserId extends OpaqueType[UserId, String], OpaqueType.Eq[UserId]:
  type Error = IllegalArgumentException

  inline def wrap(s: String): UserId     = s
  inline def unwrap(id: UserId): String  = id
  inline def apply(inline value: String): UserId = fromUnsafe(value)

  protected inline def validate(s: String): Option[Error] =
    if s.nonEmpty then None
    else Some(new IllegalArgumentException("UserId cannot be empty"))

opaque type SecretToken = String

object SecretToken extends OpaqueType[SecretToken, String]:
  type Error = IllegalArgumentException
  // ...
  // SecretToken values cannot be compared with == (compile error under strictEquality)

// Via companion
val direct: UserId                                 = UserId("user-123")
val safe: Either[IllegalArgumentException, UserId] = UserId.from("user-123")

// Via extension syntax
val ext1: Either[IllegalArgumentException, UserId]  = "user-123".as[UserId]
val ext2: UserId                                    = "user-123".asUnsafe[UserId]
val ext3: UserId                                    = "user-123".const[UserId]

val underlying: String = direct.unwrap

opaque type PositiveInt = Int

object PositiveInt extends OpaqueType[PositiveInt, Int], OpaqueType.Eq[PositiveInt]:
  type Error = IllegalArgumentException

  inline def wrap(n: Int): PositiveInt    = n
  inline def unwrap(p: PositiveInt): Int  = p

  inline def apply(inline value: Int): PositiveInt =
    inline if value <= 0 then compiletime.error("value must be positive")
    else wrap(value)

  protected inline def validate(n: Int): Option[Error] =
    if n > 0 then None
    else Some(new IllegalArgumentException(s"$n must be positive"))

PositiveInt(42)   // compiles
PositiveInt(-1)   // compile-time error: "value must be positive"

import boilerplate.nullable.*

val value: String | Null = javaMethod()

value.option                          // Option[String]
value.either("was null")              // Either[String, String]
value.getOrElse("fallback")           // String
value.unsafe                          // String (throws NPE if null)
value.unsafe("descriptive message")   // String (throws NPE with message if null)
value.fold("default")(_.toUpperCase)  // String - no intermediate Option
value.mapOpt(_.length)                // Option[Int]
value.flatMapOpt(s => Option(s))      // Option[String]

val opt: Option[String | Null] = Some(javaMethod())

opt.flattenNull             // Option[String] - Some(null) becomes None
opt.mapNull(_.toUpperCase)  // Option[String]
opt.flatMapNull(s => Some(s.trim))  // Option[String]

val result: Either[String, String | Null] = Right(javaMethod())

result.flattenNull("null value")              // Either[String, String]
result.mapNull("null value")(_.toUpperCase)   // Either[String, String]
result.flatMapNull("null value")(s => Right(s.trim))  // Either[String, String]

import boilerplate.Slice

val buf: Array[Byte] = receive()
val header = Slice.of(buf).take(8)      // a view of the first 8 bytes - no copy
val body   = Slice.of(buf).drop(8)      // the rest - no copy
val owned  = header.toArray             // copy out to an owned Array[Byte]

val s = Slice.of(new Array[Byte](4))
s.writeBE[Int](0, 256)  // bytes now 00 00 01 00
s(2)                    // 1: Byte
s.readBE[Int](0)        // 256
s.readLE[Int](0)        // 65536

Slice.of(frame).sliceOrError(offset, offset + len) match
  case Right(field)                          => decode(field)
  case Left(SliceError.OutOfBounds(_, _, _)) => reject()

import boilerplate.{Platform, Os, Arch}

// Compile-time branching - unreachable branches are eliminated
inline if Platform.linux then linuxImpl()
else inline if Platform.mac then macImpl()
else windowsImpl()

// Enum values for runtime dispatch
Platform.os match
  case Os.Linux   => // ...
  case Os.Mac     => // ...
  case Os.Windows => // ...

Platform.arch match
  case Arch.X86_64  => // ...
  case Arch.Aarch64 => // ...

import boilerplate.effect.*
import cats.effect.IO
import cats.syntax.all.*

import scala.util.control.NoStackTrace

sealed abstract class AppError(msg: String) extends Exception(msg) with NoStackTrace derives CanEqual
object AppError:
  final case class NotFound(id: String) extends AppError(s"not found: $id")
  final case class Invalid(reason: String) extends AppError(s"invalid: $reason")

case class User(id: String, name: String)

def findUser(id: String): Eff[IO, AppError.NotFound, User] =
  if id == "1" then Eff.succeed(User("1", "Alice"))
  else Eff.fail(AppError.NotFound(id))

def validateUser(user: User): Eff[IO, AppError.Invalid, User] =
  if user.name.nonEmpty then Eff.succeed(user)
  else Eff.fail(AppError.Invalid("name required"))

// for-comprehension: the error channel widens to the union automatically - no widenError
val workflow: Eff[IO, AppError, User] = for
  user      <- findUser("1")
  validated <- validateUser(user)
yield validated

// Exhaustive error handling - fold both channels back to the base effect
val message: IO[String] = workflow.fold(
  {
    case AppError.NotFound(id) => s"user $id not found"
    case AppError.Invalid(msg) => s"invalid: $msg"
  },
  user => s"welcome ${user.name}"
)

// Reify the typed channel on demand
val io: IO[Either[AppError, User]] = workflow.either

Eff[IO].succeed(42)                    // UEff[IO, Int]
Eff[IO].fail(AppError.NotFound("u1"))  // Eff[IO, AppError.NotFound, Nothing]
Eff[IO].from(Right(1))                 // Eff[IO, Nothing, Int]
Eff[IO].liftF(IO.pure(42))             // UEff[IO, Int]
Eff[IO].unit                           // UEff[IO, Unit]
Eff[IO].suspend(sideEffect())          // UEff[IO, A]

// success-only composition over a non-IO Monad - no MonadThrow, no TypeTest
val overOption: Eff[Option, Nothing, Int] = for
  a <- Eff.succeed[Option, Nothing, Int](20)
  b <- Eff.liftF[Option, Nothing, Int](Some(22))
yield a + b
// overOption.absolve == Some(42)

def findUser(id: String): EffIO[AppError.NotFound, User] =
  if id == "1" then EffIO.succeed(User("1", "Alice"))
  else EffIO.fail(AppError.NotFound(id))

def validateUser(user: User): EffIO[AppError.Invalid, User] =
  if user.name.nonEmpty then EffIO.succeed(user)
  else EffIO.fail(AppError.Invalid("name required"))

// Distinct error types unify into their union automatically
val workflow: EffIO[AppError, User] = for
  user      <- findUser("1")
  validated <- validateUser(user)
yield validated

EffIO.succeed(42)               // UEffIO[Int]
EffIO.fail(AppError.Timeout)    // EffIO[AppError.Timeout.type, Nothing]
EffIO.liftF(IO.pure(42))        // UEffIO[Int]

workflow.map(user => user.name) // EffIO[AppError, String]
workflow.either                 // IO[Either[AppError, User]]

val consumed: EffIO[IoError | AppError, Unit] = ...
val handled: EffIO[IoError, Unit] = consumed.catchOnly((app: AppError) => log(app))

val asEff: Eff[IO, AppError, User] = workflow.toEff
val asEffIO: EffIO[AppError, User] = EffIO.fromEff(asEff)

val widen: EffIO.Of[AppError.NotFound] ~> EffIO.Of[AppError] = EffIO.widenK[AppError.NotFound, AppError]
val liftK: IO ~> EffIO.Of[Nothing]                           = EffIO.liftK

import cats.effect.kernel.GenConcurrent
import scala.concurrent.duration.*

val C = summon[GenConcurrent[Eff.Of[IO, AppError], Throwable]]

val program: Eff[IO, AppError, Int] = for
  ref      <- C.ref(0)
  deferred <- C.deferred[Int]
  _        <- ref.update(_ + 1)
  _        <- deferred.complete(42)
  result   <- deferred.get
yield result

val convenient: Eff[IO, AppError, Int] = for
  ref  <- Eff.ref[IO, AppError, Int](0)
  _    <- Eff.sleep[IO, AppError](10.millis)
  time <- Eff.monotonic[IO, AppError]
yield 42

// Named lift methods on the Eff companion
Eff.liftResource(resource)   // Resource[Eff.Of[IO, E], A]
Eff.liftRef(ref)             // Ref[Eff.Of[IO, E], A]
Eff.liftDeferred(deferred)   // Deferred[Eff.Of[IO, E], A]
Eff.liftQueue(queue)         // Queue[Eff.Of[IO, E], A]
Eff.liftSemaphore(semaphore) // Semaphore[Eff.Of[IO, E]]
Eff.liftLatch(latch)         // CountDownLatch[Eff.Of[IO, E]]
Eff.liftBarrier(barrier)     // CyclicBarrier[Eff.Of[IO, E]]
Eff.liftCell(cell)           // AtomicCell[Eff.Of[IO, E], A]
Eff.liftSupervisor(sup)      // Supervisor[Eff.Of[IO, E]]

// .eff[E] extension syntax (equivalent) - E must be a Throwable subtype
resource.eff[AppError]
ref.eff[AppError]
deferred.eff[AppError]
queue.eff[AppError]
semaphore.eff[AppError]

// Natural transformations for mapK
val fk: IO ~> Eff.Of[IO, AppError]                              = Eff.functionK[IO, AppError]
val widen: Eff.Of[IO, AppError.NotFound] ~> Eff.Of[IO, AppError] = Eff.widenK[IO, AppError.NotFound, AppError]

import boilerplate.Slice

// make a working copy, use it, and zero it once `use` completes - however it completes
IO(Slice.of(secret.toArray)).wiping.useEffIO(use) // : EffIO[E, A]

import boilerplate.effect.*
import cats.effect.IO
import cats.effect.kernel.{GenConcurrent, Outcome}
import cats.syntax.all.*
import scala.concurrent.duration.*
import scala.util.control.NoStackTrace

sealed abstract class AppError(msg: String) extends Exception(msg) with NoStackTrace derives CanEqual
object AppError:
  final case class NotFound(id: String) extends AppError(s"not found: $id")
  final case class ValidationError(reason: String) extends AppError(s"invalid: $reason")
  case object Cancelled extends AppError("cancelled")
  case object Timeout extends AppError("timed out")

case class User(id: String, name: String)

given C: GenConcurrent[Eff.Of[IO, AppError], Throwable] =
  summon[GenConcurrent[Eff.Of[IO, AppError], Throwable]]

def fetchUser(id: String): Eff[IO, AppError.NotFound, User] =
  if id == "1" then Eff.succeed(User("1", "Alice"))
  else Eff.fail(AppError.NotFound(id))

def validateUser(user: User): Eff[IO, AppError.ValidationError, User] =
  if user.name.nonEmpty then Eff.succeed(user)
  else Eff.fail(AppError.ValidationError("name required"))

// Distinct typed errors unify into their union automatically - no widenError
val workflow: Eff[IO, AppError, User] = for
  user      <- fetchUser("1")
  validated <- validateUser(user)
yield validated

// Concurrency with typed errors; a fibre's typed failure is Outcome.Errored
val concurrent: Eff[IO, AppError, User] = for
  ref    <- C.ref(0)
  _      <- ref.update(_ + 1)
  fiber  <- workflow.start
  result <- fiber.joinOrFail(AppError.Cancelled)
yield result

// Racing, parallel composition, and timeout
val raced: Eff[IO, AppError, Either[User, User]] =
  workflow.race(workflow)

val parallel: Eff[IO, AppError, (User, User)] =
  workflow.both(workflow)

val withTimeout: Eff[IO, AppError, User] =
  workflow.timeout(5.seconds, AppError.Timeout)

// Guaranteed cleanup - a typed failure surfaces as Outcome.Errored
val withCleanup: Eff[IO, AppError, User] =
  workflow.guaranteeCase {
    case Outcome.Succeeded(_) => Eff.liftF(IO.println("success"))
    case Outcome.Errored(_)   => Eff.liftF(IO.println("error"))
    case Outcome.Canceled()   => Eff.liftF(IO.println("cancelled"))
  }

val io: IO[Either[AppError, User]] = concurrent.either