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.