-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Provides a eventsourcing high level API.
--   
--   Please read README.md.
@package eventsource-api
@version 1.0.1


module EventSource.Types

-- | Opaque data type used to store raw data.
data Data
Data :: ByteString -> Data
DataAsJson :: Value -> Data

-- | Sometimes, having to implement a <a>FromJSON</a> instance isn't
--   flexible enough. <a>JsonParsing</a> allow to pass parameters when
--   parsing from a JSON value while remaining composable.
newtype JsonParsing a
JsonParsing :: (Value -> Parser a) -> JsonParsing a

-- | Returns <a>Data</a> content as a <a>ByteString</a>.
dataAsBytes :: Data -> ByteString

-- | Creates a <a>Data</a> object from a raw <a>ByteString</a>.
dataFromBytes :: ByteString -> Data

-- | Creates a <a>Data</a> object from a JSON object.
dataFromJson :: ToJSON a => a -> Data

-- | Returns <a>Data</a> content as any value that implements
--   <a>FromJSON</a> type-class.
dataAsJson :: FromJSON a => Data -> Either Text a

-- | Uses a <a>JsonParsing</a> comuputation to extract a value.
dataAsParsing :: Data -> JsonParsing a -> Either Text a

-- | Like <a>dataAsParsing</a> but doesn't require you to use
--   <a>JsonParsing</a>.
dataAsParse :: Data -> (Value -> Parser a) -> Either Text a

-- | Used to store a set a properties. One example is to be used as
--   <a>Event</a> metadata.
newtype Properties
Properties :: (Map Text Text) -> Properties

-- | Retrieves a value associated with the given key.
property :: MonadPlus m => Text -> Properties -> m Text

-- | Builds a <a>Properties</a> with a single pair of key-value.
singleton :: Text -> Text -> Properties

-- | Adds a pair of key-value into given <a>Properties</a>.
setProperty :: Text -> Text -> Properties -> Properties

-- | Returns all associated key-value pairs as a list.
properties :: Properties -> [(Text, Text)]

-- | Used to identify an event.
newtype EventId
EventId :: UUID -> EventId

-- | Generates a fresh <a>EventId</a>.
freshEventId :: MonadIO m => m EventId

-- | Represents a stream name.
newtype StreamName
StreamName :: Text -> StreamName

-- | Used to identity the type of an <a>Event</a>.
newtype EventType
EventType :: Text -> EventType

-- | Sets <a>EventType</a> for an <a>Event</a>.
setEventType :: EventType -> State Event ()

-- | Sets <tt>Eventid</tt> for an <a>Event</a>.
setEventId :: EventId -> State Event ()

-- | Sets a payload for an <a>Event</a>.
setEventPayload :: Data -> State Event ()

-- | Sets metadata for an <a>Event</a>.
setEventMetadata :: Properties -> State Event ()

-- | Encapsulates an event which is about to be saved.
data Event
Event :: EventType -> EventId -> Data -> Maybe Properties -> Event
[eventType] :: Event -> EventType
[eventId] :: Event -> EventId
[eventPayload] :: Event -> Data
[eventMetadata] :: Event -> Maybe Properties

-- | Represents an event index in a stream.
newtype EventNumber
EventNumber :: Int32 -> EventNumber

-- | Represents an event that's saved into the event store.
data SavedEvent
SavedEvent :: EventNumber -> Event -> SavedEvent
[eventNumber] :: SavedEvent -> EventNumber
[savedEvent] :: SavedEvent -> Event

-- | Deserializes a <a>SavedEvent</a>.
savedEventAs :: DecodeEvent a => SavedEvent -> Either Text a

-- | Represents batch of events read from a store.
data Slice
Slice :: [SavedEvent] -> Bool -> EventNumber -> Slice
[sliceEvents] :: Slice -> [SavedEvent]
[sliceEndOfStream] :: Slice -> Bool
[sliceNextEventNumber] :: Slice -> EventNumber

-- | Deserializes a <tt>Slice'</tt>s events.
sliceEventsAs :: DecodeEvent a => Slice -> Either Text [a]

-- | Encodes a data object into an <a>Event</a>. <a>encodeEvent</a> get
--   passed an <a>EventId</a> in a case where a fresh id is needed.
class EncodeEvent a
encodeEvent :: EncodeEvent a => a -> State Event ()

-- | Decodes an <a>Event</a> into a data object.
class DecodeEvent a
decodeEvent :: DecodeEvent a => Event -> Either Text a
newtype DecodeEventException
DecodeEventException :: Text -> DecodeEventException

-- | The purpose of <a>ExpectedVersion</a> is to make sure a certain stream
--   state is at an expected point in order to carry out a write.
data ExpectedVersion
AnyVersion :: ExpectedVersion
NoStream :: ExpectedVersion
StreamExists :: ExpectedVersion
ExactVersion :: EventNumber -> ExpectedVersion

-- | Statuses you can get on every read attempt.
data ReadStatus a
ReadSuccess :: a -> ReadStatus a
ReadFailure :: ReadFailure -> ReadStatus a

-- | Returns <a>True</a> is <a>ReadStatus</a> is a <a>ReadSuccess</a>.
isReadSuccess :: ReadStatus a -> Bool

-- | Returns <a>False</a> is <a>ReadStatus</a> is a <a>ReadFailure</a>.
isReadFailure :: ReadStatus a -> Bool

-- | Represents the different kind of failure you can get when reading.
data ReadFailure
StreamNotFound :: ReadFailure
ReadError :: (Maybe Text) -> ReadFailure
AccessDenied :: ReadFailure
instance GHC.Show.Show a => GHC.Show.Show (EventSource.Types.ReadStatus a)
instance GHC.Show.Show EventSource.Types.ReadFailure
instance GHC.Show.Show EventSource.Types.ExpectedVersion
instance GHC.Show.Show EventSource.Types.DecodeEventException
instance GHC.Show.Show EventSource.Types.Slice
instance GHC.Show.Show EventSource.Types.SavedEvent
instance GHC.Show.Show EventSource.Types.EventNumber
instance GHC.Enum.Enum EventSource.Types.EventNumber
instance GHC.Num.Num EventSource.Types.EventNumber
instance GHC.Classes.Ord EventSource.Types.EventNumber
instance GHC.Classes.Eq EventSource.Types.EventNumber
instance GHC.Show.Show EventSource.Types.Event
instance GHC.Classes.Eq EventSource.Types.EventType
instance GHC.Classes.Ord EventSource.Types.StreamName
instance GHC.Classes.Eq EventSource.Types.StreamName
instance GHC.Classes.Ord EventSource.Types.EventId
instance GHC.Classes.Eq EventSource.Types.EventId
instance GHC.Show.Show EventSource.Types.Data
instance GHC.Base.Functor EventSource.Types.JsonParsing
instance GHC.Base.Applicative EventSource.Types.JsonParsing
instance GHC.Base.Monad EventSource.Types.JsonParsing
instance GHC.Base.Monoid EventSource.Types.Properties
instance GHC.Show.Show EventSource.Types.Properties
instance Data.Aeson.Types.ToJSON.ToJSON EventSource.Types.Properties
instance Data.Aeson.Types.FromJSON.FromJSON EventSource.Types.Properties
instance GHC.Show.Show EventSource.Types.EventId
instance GHC.Show.Show EventSource.Types.StreamName
instance Data.String.IsString EventSource.Types.StreamName
instance GHC.Show.Show EventSource.Types.EventType
instance Data.String.IsString EventSource.Types.EventType
instance GHC.Exception.Exception EventSource.Types.DecodeEventException
instance EventSource.Types.DecodeEvent EventSource.Types.Event
instance GHC.Base.Functor EventSource.Types.ReadStatus
instance Data.Foldable.Foldable EventSource.Types.ReadStatus
instance Data.Traversable.Traversable EventSource.Types.ReadStatus


module EventSource.Store

-- | Represents batch information needed to read a stream.
data Batch
Batch :: EventNumber -> Int32 -> Batch
[batchFrom] :: Batch -> EventNumber
[batchSize] :: Batch -> Int32

-- | A subscription allows to be notified on every change occuring on a
--   stream.
data Subscription
Subscription :: SubscriptionId -> (forall m. MonadIO m => m (Either SomeException SavedEvent)) -> Subscription
[subscriptionId] :: Subscription -> SubscriptionId
[nextEvent] :: Subscription -> forall m. MonadIO m => m (Either SomeException SavedEvent)

-- | Represents a subscription id.
data SubscriptionId
data ExpectedVersionException
ExpectedVersionException :: ExpectedVersion -> ExpectedVersion -> ExpectedVersionException
[versionExceptionExpected] :: ExpectedVersionException -> ExpectedVersion
[versionExceptionActual] :: ExpectedVersionException -> ExpectedVersion

-- | Main event store abstraction. It exposes essential features expected
--   from an event store.
class Store store

-- | Appends a batch of events at the end of a stream.
appendEvents :: (Store store, EncodeEvent a, MonadIO m) => store -> StreamName -> ExpectedVersion -> [a] -> m (Async EventNumber)

-- | Appends a batch of events at the end of a stream.
readBatch :: (Store store, MonadIO m) => store -> StreamName -> Batch -> m (Async (ReadStatus Slice))

-- | Subscribes to given stream.
subscribe :: (Store store, MonadIO m) => store -> StreamName -> m Subscription

-- | Utility type to pass any store that implements <a>Store</a> typeclass.
data SomeStore
SomeStore :: store -> SomeStore

-- | Allows to easily iterate over a stream's events.
data StreamIterator
iteratorNext :: StreamIterator -> forall m. MonadIO m => m (Maybe SavedEvent)

-- | Reads the next available event from the <a>StreamIterator</a> and try
--   to deserialize it at the same time.
iteratorNextEvent :: (DecodeEvent a, MonadIO m, MonadPlus m) => StreamIterator -> m (Maybe a)

-- | Reads all events from the <a>StreamIterator</a> until reaching end of
--   stream.
iteratorReadAll :: MonadIO m => StreamIterator -> m [SavedEvent]

-- | Like <a>iteratorReadAll</a> but try to deserialize the events at the
--   same time.
iteratorReadAllEvents :: (DecodeEvent a, MonadIO m, MonadPlus m) => StreamIterator -> m [a]

-- | Returns a <a>StreamIterator</a> for the given stream name. The
--   returned <a>StreamIterator</a> IS NOT THREADSAFE.
streamIterator :: (Store store, MonadIO m) => store -> StreamName -> m (ReadStatus StreamIterator)

-- | Returns a fresh subscription id.
freshSubscriptionId :: MonadIO m => m SubscriptionId

-- | Starts a <a>Batch</a> from a given point. The batch size is set to
--   default, which is 500.
startFrom :: EventNumber -> Batch

-- | Waits for the next event and deserializes it on the go.
nextEventAs :: (DecodeEvent a, MonadIO m) => Subscription -> m (Either SomeException a)

-- | Folds over every event coming from the subscription until the end of
--   the universe, unless an <a>Exception</a> raises from the subscription.
--   <a>SomeException</a> is used because we let the underlying
--   subscription model exposed its own <a>Exception</a>. If the callback
--   that handles incoming events throws an exception, it will not be catch
--   by the error callback.
foldSub :: (DecodeEvent a, MonadIO m) => Subscription -> (a -> m ()) -> (SomeException -> m ()) -> m ()

-- | Asynchronous version of <a>foldSub</a>.
foldSubAsync :: DecodeEvent a => Subscription -> (a -> IO ()) -> (SomeException -> IO ()) -> IO (Async ())

-- | Appends a single event at the end of a stream.
appendEvent :: (EncodeEvent a, MonadIO m, Store store) => store -> StreamName -> ExpectedVersion -> a -> m (Async EventNumber)

-- | Iterates over all events of stream given a starting point and a batch
--   size.
forEvents :: (MonadIO m, DecodeEvent a, Store store) => store -> StreamName -> (a -> m ()) -> ExceptT ForEventFailure m ()

-- | Like <a>forEvents</a> but expose signature similar to <a>foldM</a>.
foldEventsM :: (MonadIO m, DecodeEvent a, Store store) => store -> StreamName -> (s -> a -> m s) -> s -> ExceptT ForEventFailure m s

-- | Like <a>foldEventsM</a> but expose signature similar to <a>foldl</a>.
foldEvents :: (MonadIO m, DecodeEvent a, Store store) => store -> StreamName -> (s -> a -> s) -> s -> ExceptT ForEventFailure m s

-- | Like <a>forEvents</a> but provides access to <a>SavedEvent</a> instead
--   of decoded event.
forSavedEvents :: (MonadIO m, Store store) => store -> StreamName -> (SavedEvent -> m ()) -> ExceptT ForEventFailure m ()

-- | Like <a>forSavedEvents</a> but expose signature similar to
--   <a>foldM</a>.
foldSavedEventsM :: (MonadIO m, Store store) => store -> StreamName -> (s -> SavedEvent -> m s) -> s -> ExceptT ForEventFailure m s

-- | Like <a>foldSavedEventsM</a> but expose signature similar to
--   <a>foldl</a>.
foldSavedEvents :: (MonadIO m, Store store) => store -> StreamName -> (s -> SavedEvent -> s) -> s -> ExceptT ForEventFailure m s

-- | Similar to <a>foldSub</a> but provides access to the <a>SavedEvent</a>
--   instead of decoded event.
foldSubSaved :: (MonadIO m) => Subscription -> (SavedEvent -> m ()) -> (SomeException -> m ()) -> m ()

-- | Asynchronous version of <a>foldSubSaved</a>.
foldSubSavedAsync :: Subscription -> (SavedEvent -> IO ()) -> (SomeException -> IO ()) -> IO (Async ())

-- | Represents failures that can occurs when using <a>forEvents</a>.
data ForEventFailure
ForEventReadFailure :: ReadFailure -> ForEventFailure
ForEventDecodeFailure :: Text -> ForEventFailure
instance GHC.Show.Show EventSource.Store.ForEventFailure
instance GHC.Show.Show EventSource.Store.ExpectedVersionException
instance GHC.Show.Show EventSource.Store.SubscriptionId
instance GHC.Classes.Ord EventSource.Store.SubscriptionId
instance GHC.Classes.Eq EventSource.Store.SubscriptionId
instance GHC.Exception.Exception EventSource.Store.ExpectedVersionException
instance EventSource.Store.Store EventSource.Store.SomeStore
instance GHC.Show.Show EventSource.Store.StreamIterator


module EventSource