Resource.hs

{-# LANGUAGE TypeFamilies #-}

module Kiroku.Store.Effect.Resource (
    -- * The KirokuStoreResource effect
    KirokuStoreResource,

    -- * Operations
    getKirokuStore,

    -- * Bracket-style runner
    withKirokuStore,

    -- * Runner over an existing handle
    runKirokuStoreWith,
) where

import Effectful (Dispatch (..), DispatchOf, Eff, Effect, IOE, UnliftStrategy (..), withEffToIO, (:>))
import Effectful.Dispatch.Static (SideEffects (..), StaticRep, evalStaticRep, getStaticRep)
import Kiroku.Store.Connection (ConnectionSettings, KirokuStore, withStore)

-- ---------------------------------------------------------------------------
-- KirokuStoreResource static effect
-- ---------------------------------------------------------------------------

{- | Static effect carrying a 'KirokuStore' handle.

Static rather than dynamic because the store handle is acquired exactly
once per program and is not meant to be mocked — the dynamic mocking
surface lives on the 'Kiroku.Store.Effect.Store' effect that operates
against the handle. Splitting the resource (static) from the operations
(dynamic) keeps mocking ergonomic without requiring callers to swap the
handle itself.

@Static WithSideEffects@ rather than @Static NoSideEffects@ because the
underlying connection pool performs IO during operation lookup.
-}
data KirokuStoreResource :: Effect

type instance DispatchOf KirokuStoreResource = Static WithSideEffects

newtype instance StaticRep KirokuStoreResource = KirokuStoreResource KirokuStore

-- | Retrieve the 'KirokuStore' handle from the effect stack.
getKirokuStore :: (KirokuStoreResource :> es) => Eff es KirokuStore
getKirokuStore = do
    KirokuStoreResource store <- getStaticRep
    pure store

-- | Bracket-style runner: acquire the store, install the effect, run the action, release.
withKirokuStore ::
    (IOE :> es) =>
    ConnectionSettings ->
    Eff (KirokuStoreResource : es) a ->
    Eff es a
withKirokuStore settings action = withEffToIO SeqUnlift $ \unlift ->
    withStore settings $ \store ->
        unlift (evalStaticRep (KirokuStoreResource store) action)

{- | Install an /already acquired/ 'KirokuStore' into the effect stack.

Unlike 'withKirokuStore', this neither acquires nor releases: the caller owns
the handle's lifetime. Use it when a process has opened exactly one store (the
documented arrangement) and needs to run several independent effectful actions
against it. Acquiring a store per action instead costs a connection pool, a
dedicated @LISTEN@ connection, and a publisher thread each time.

There is no bracket and no unlifting here, but @IOE@ is still required:
'KirokuStoreResource' is @Static WithSideEffects@, and 'evalStaticRep' demands
@IOE@ for any effect declared that way.
-}
runKirokuStoreWith ::
    (IOE :> es) =>
    KirokuStore ->
    Eff (KirokuStoreResource : es) a ->
    Eff es a
runKirokuStoreWith = evalStaticRep . KirokuStoreResource