Feedback on a Hasql Effect

[shinzui]

We're currently using fused-effect in our projects, and I'm considering transitioning to Effectful for upcoming services. My initial step was to migrate the simplest effect from our stack. I've tried to follow our existing fused-effects patterns, but I'm looking for feedback on best practices with Effectful.

Here's my translation of our hasql effect:

import Effectful
import Effectful.Dispatch.Dynamic
import Effectful.Error.Static
import Effectful.Reader.Static
import Hasql.Pool (Pool, UsageError, use)
import Hasql.Session (Session)

data Hasql :: Effect where
  RunSession :: Session a -> Hasql m a

type instance DispatchOf Hasql = Dynamic

runSession :: (Hasql :> es) => Session a -> Eff es a
runSession = send . RunSession

runHasqlIO ::
  forall es a.
  ( IOE :> es,
    Reader Pool :> es,
    Error UsageError :> es
  ) =>
  Eff (Hasql : es) a ->
  Eff es a
runHasqlIO = interpret $ \_ -> \case
  RunSession session -> do
    pool <- ask @Pool
    r <- liftIO $ use pool session
    either throwError pure r

Here's an example demonstrating its usage:

data User 

userDecoder :: D.Row User
userDecoder = undefined

userEncoder :: E.Params User
userEncoder = undefined

insertUser_ :: Statement User Int32
insertUser_ = undefined

findUserById_ :: Statement Int32 (Maybe User)
findUserById_ = undefined

findUserById :: Int32 -> Session (Maybe User)
findUserById = undefined

insertUser :: User -> Session Int32
insertUser = undefined 

createUser :: (Hasql :> es) => User -> Eff es Int32
createUser user = undefined

findUser ::  (Hasql :> es) => Int32 -> Eff es (Maybe User)
findUser userId = undefined

newUser :: User
newUser = undefined

exampleApp :: (Hasql :> es) => Eff es (Maybe User)
exampleApp = do
  userId <- createUser newUser
  findUser userId

Given the setup above, I'd like to ask if it's advisable to encapsulate the Reader Pool and Error UsageError within an internal effect stack. Would this make it more user-friendly for developers who use the package to run the effect?

Currently running the effect would look something like that:

run :: Pool -> Eff [Hasql, Reader Pool, Error UsageError, IOE] a -> IO (Either (CallStack, UsageError) a)
run pool = runEff . runError @UsageError . runReader pool . runHasqlIO

runWithErrorHandler :: Pool -> (CallStack -> UsageError -> Eff '[IOE] a) -> Eff [Hasql, Reader Pool, Error UsageError, IOE] a -> IO a
runWithErrorHandler pool errHandler = runEff . runErrorWith @UsageError errHandler . runReader pool . runHasqlIO

[arybczak]

Looks good to me 👍 You might want to include HasCallStack constraint in the signature of runSession to be able to get accurate stack traces in case of errors.

Given the setup above, I'd like to ask if it's advisable to encapsulate the Reader Pool and Error UsageError within an internal effect stack

I'd not include Reader at all and just pass pool as a parameter to runHasqlIO:

runHasqlIO ::
  forall es a.
  ( IOE :> es,
    Error UsageError :> es
  ) =>
  Eff (Hasql : es) a ->
  Eff es a
runHasqlIO pool = interpret $ \_ -> \case
  RunSession session -> do
    r <- liftIO $ use pool session
    either throwError pure r

since I don't think you'll use local from outside to modify the pool?

As for the error handling, you can have a look at #149, it has some pondering that might be helpful, especially this comment.

If you do this, then it would be

import Effectful
import Effectful.Dispatch.Dynamic
import Effectful.Error.Static
import Effectful.Reader.Static
import Hasql.Pool (Pool, UsageError, use)
import Hasql.Session (Session)

data Hasql :: Effect where
  RunSession :: Error UsageError :> es => Session a -> Hasql (Eff es) a

type instance DispatchOf Hasql = Dynamic

runSession :: (HasCallStack, Error UsageError :> es, Hasql :> es) => Session a -> Eff es a
runSession = send . RunSession

runHasqlIO ::
  forall es a.
  ( IOE :> es,
  ) =>
  Pool ->
  Eff (Hasql : es) a ->
  Eff es a
runHasqlIO pool = interpret $ \env -> \case
  RunSession session -> do
    r <- liftIO $ use pool session
    localSeqUnlift env $ \unlift -> unlift $ do
      either throwError pure r

The difference is that now you don't need the Error effect to be in scope when you run the Hasql handler, you only need it for the runSession operation (which might or not might matter in this particular case, it depends on the effect which pattern you would like to employ).

[shinzui]

Thank you for your comprehensive response, @arybczak. I'm working on deepening my understanding of your proposed error-handling strategy.

runSession is the primary use of the Hasql effect. A significant advantage of the API you've suggested is that the call sites are now explicit about throwing the UsageError (for example createUser :: (Hasql :> es, Error UsageError :> es) => User -> Eff es Int32).

Regarding the discussion in #149, could you clarify when one should use explicit errors like:

ReadFile :: Error FsReadError :> es => FilePath -> FileSystem (Eff es) String 

instead of:

ReadFile  :: FilePath -> FileSystem m String

[arybczak]

Sorry for a delayed reply.

could you clarify when one should use explicit errors

I don't have a rule for this 🙂 I think this depends on the situation and (perhaps mostly) your preferences.