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


-- | Type-safe data versioning.
--   
--   This package provides various tools to deal with data versioning in a
--   type-safe way.
@package versioning
@version 0.3.2.0

module Versioning.Internal.Base

-- | An uninhabited type. We define our own type instead of using
--   <a>Data.Void</a> because we need additional instances. Moreover this
--   type is internal. Users are supposed to use <tt>NA</tt> to express
--   absence.
data Bare
instance GHC.Classes.Eq Versioning.Internal.Base.Bare
instance GHC.Generics.Generic Versioning.Internal.Base.Bare
instance GHC.Show.Show Versioning.Internal.Base.Bare
instance Data.Aeson.Types.FromJSON.FromJSON Versioning.Internal.Base.Bare
instance Data.Aeson.Types.ToJSON.ToJSON Versioning.Internal.Base.Bare


-- | This module provides some tools to encode multiple versions of a data
--   model in a single data-type parametrized by version number. The
--   addition or removal of a field can be expressed through the
--   <a>Since</a> and <a>Until</a> type families.
--   
--   Example:
--   
--   <pre>
--   data Rec v = Rec
--       { foo :: Int               -- this field exists in all versions
--       , bar :: Since V2 v Bool   -- this field has been introduced in V2
--       , baz :: Until V2 v Double -- this field has been removed in V3
--       }
--   </pre>
--   
--   Besides reducing the number of data declarations, this approach also
--   has other advantages:
--   
--   <ul>
--   <li>It makes migrations declarative and self-documenting.</li>
--   <li>It allows for less verbose version-upcasting functions, since the
--   fields that have a non-parametric type do not need to be copied.</li>
--   <li>It is a foundation on which other useful abstractions can be
--   built.</li>
--   </ul>
--   
--   Please note that some classes may require a separate standalone
--   deriving clause for each version of a data-type or some kind of
--   inductive deriving mechanism.
module Versioning.Base

-- | The version of a data model
data V
VZero :: V
VSucc :: V -> V

-- | Get the previous version
type family VPred (v :: V) :: V
type VSucc = 'VSucc

-- | Get the type-level natural of a version
type family VNat (v :: V) :: Nat

-- | Compare two versions
type family VCmp (v :: V) (w :: V) :: Ordering

-- | This allows us to express that a field is only present since a given
--   version. The first parameter is the version in which the field has
--   been introduced, the second parameter is the actual version of the
--   data-type.
type family Since (s :: V) (v :: V) a

-- | Same as <a>Since</a>, for sum types. The only difference between
--   <a>Since</a> and <a>SinceS</a> is in the type used to indicate
--   absence. In <a>Since</a> absence is expressed with <a>NA</a>, which is
--   isomorphic to <tt>()</tt>. In <a>SinceS</a> it is expressed with
--   <a>Bare</a>, which is isomorphic to <tt>Void</tt>.
type family SinceS (s :: V) (v :: V) a

-- | This allows us to express that a field is only present until a given
--   version. The first parameter is the last version in which the field is
--   present, the second parameter is the actual version of the data-type.
type family Until (u :: V) (v :: V) a

-- | Same as <a>Until</a>, for sum types.
type family UntilS (u :: V) (v :: V) a

-- | A type indicating absence. The <a>Maybe</a> is a hack needed to let
--   aeson parse a record successfully even if a field of type <a>NA</a> is
--   missing.
--   
--   Ideally we would like to define it as
--   
--   <pre>
--   data NA = NA
--   </pre>
--   
--   but this would not work with <tt>FromJSON</tt> instances that are
--   derived with Generic.
type NA = Maybe Bare

-- | A placeholder for an absent value.
na :: NA
type V0 = 'VZero
type V1 = 'VSucc V0
type V2 = 'VSucc V1
type V3 = 'VSucc V2
type V4 = 'VSucc V3
type V5 = 'VSucc V4
type V6 = 'VSucc V5
type V7 = 'VSucc V6
type V8 = 'VSucc V7
type V9 = 'VSucc V8
type V10 = 'VSucc V9
type V11 = 'VSucc V10
type V12 = 'VSucc V11
type V13 = 'VSucc V12
type V14 = 'VSucc V13
type V15 = 'VSucc V14
type V16 = 'VSucc V15
type V17 = 'VSucc V16
type V18 = 'VSucc V17
type V19 = 'VSucc V18
type V20 = 'VSucc V19

-- | Get the version number of a versioned value
versionNumber :: forall a v. KnownNat (VNat v) => a v -> Natural
instance GHC.Show.Show Versioning.Base.V
instance GHC.Classes.Eq Versioning.Base.V

module Versioning.Upgrade

-- | Adapt from a version to another
class Adapt (v :: V) (w :: V) (a :: V -> Type)
adapt :: Adapt v w a => a v -> a w

-- | This constraint specifies that a value of type <tt>a</tt> can be
--   upgraded from version <tt>v</tt> to version <tt>w</tt>.
type Upgrade v w a = Upgrade' (v == w) v w a

-- | Upgrade from a lower to a higher version by calling <a>adapt</a> on
--   all the intermediary steps.
upgrade :: forall v w a. Upgrade v w a => a v -> a w

-- | This constraint specifies that a value of type <tt>a</tt> can be
--   downgraded from version <tt>v</tt> to version <tt>w</tt>.
type Downgrade v w a = Downgrade' (v == w) v w a

-- | Downgrade from a higher to a lower version by calling <a>adapt</a> on
--   all the intermediary steps.
downgrade :: forall v w a. Downgrade v w a => a v -> a w
instance (v GHC.Types.~ w) => Versioning.Upgrade.Downgrade' 'GHC.Types.True v w a
instance (Versioning.Upgrade.Adapt v (Versioning.Base.VPred v) a, Versioning.Upgrade.Downgrade' (Versioning.Base.VPred v Versioning.Internal.Equality.== w) (Versioning.Base.VPred v) w a) => Versioning.Upgrade.Downgrade' 'GHC.Types.False v w a
instance (v GHC.Types.~ w) => Versioning.Upgrade.Upgrade' 'GHC.Types.True v w a
instance (Versioning.Upgrade.Adapt v (Versioning.Base.VSucc v) a, Versioning.Upgrade.Upgrade' (Versioning.Base.VSucc v Versioning.Internal.Equality.== w) (Versioning.Base.VSucc v) w a) => Versioning.Upgrade.Upgrade' 'GHC.Types.False v w a


-- | Encoding-agnosting deserialization utilities.
module Versioning.Internal.Decoding

-- | The result type of the action that has been applied to the decoded
--   object with <a>withAnyVersion</a> or <a>withAnyVersionM</a>.
type family Applied (c :: Type -> Constraint) (a :: V -> Type) :: Type

-- | The pure function to apply to the decoded object with
--   <a>withAnyVersion</a>
type Apply a c = forall v. c (a v) => a v -> Applied c a

-- | The action to apply to the decoded object with <a>withAnyVersionM</a>
type ApplyM m a c = forall v. c (a v) => a v -> m (Applied c a)

-- | Handy constraint synonym to be used with <a>decodeAnyVersion</a>
type DecodableTo dec v a = DecodableToFrom V0 dec v a
type DecodableToFrom from dec v a = DecodeAnyVersionFrom from v v a dec
type DecodeAnyVersion v w a dec = DecodeAnyVersionFrom V0 v w a dec

-- | The function that will perform the actual decoding
newtype Decoder dec enc t a
Decoder :: (forall v. dec (a v) => enc -> t (a v)) -> Decoder dec enc t a
type WithAnyVersion v a c dec = WithAnyVersionFrom V0 v a c dec
type WithAnyVersionFrom from v a c dec = WithAnyVersion' (from == v) from v a c dec
decodeAnyVersion :: forall v a dec enc t. (Alt t, Applicative t, DecodableTo dec v a) => Decoder dec enc t a -> enc -> t (a v)

-- | Decode by trying all the versions decrementally and upgrade the
--   decoded object to the newest version.
decodeAnyVersionFrom :: forall from v a dec enc t. (Alt t, Applicative t, DecodableToFrom from dec v a) => Decoder dec enc t a -> enc -> t (a v)

-- | Pure version of <a>withAnyVersionM</a>.
withAnyVersion :: forall v c a dec enc t. (WithAnyVersion v a c dec, c (a v), Alt t, Applicative t, Traversable t) => Decoder dec enc t a -> Apply a c -> enc -> t (Applied c a)

-- | Decode by trying all the versions decrementally and apply an action to
--   the decoded object at its original version.
withAnyVersionM :: forall v c a dec enc m t. (WithAnyVersion v a c dec, Alt t, Applicative t, Traversable t, Applicative m, c (a v)) => Decoder dec enc t a -> ApplyM m a c -> enc -> m (t (Applied c a))

-- | Like <a>withAnyVersionM</a>, with an additional type-parameter
--   indicating the oldest version you want to be able to decode
withAnyVersionFromM :: forall from v c a dec enc m t. (WithAnyVersionFrom from v a c dec, Alt t, Applicative t, Traversable t, Applicative m, c (a v)) => Decoder dec enc t a -> ApplyM m a c -> enc -> m (t (Applied c a))

-- | Pure version of <a>withAnyVersionFromM</a>.
withAnyVersionFrom :: forall from v c a dec enc t. (WithAnyVersionFrom from v a c dec, c (a v), Alt t, Applicative t, Traversable t) => Decoder dec enc t a -> Apply a c -> enc -> t (Applied c a)
instance (from GHC.Types.~ v, dec (a from), c (a from)) => Versioning.Internal.Decoding.WithAnyVersion' 'GHC.Types.True from v a c dec
instance (Versioning.Internal.Decoding.WithAnyVersion' (Versioning.Base.VPred v Versioning.Internal.Equality.== from) from (Versioning.Base.VPred v) a c dec, dec (a v), dec (a (Versioning.Base.VPred v)), c (a v), c (a (Versioning.Base.VPred v))) => Versioning.Internal.Decoding.WithAnyVersion' 'GHC.Types.False from v a c dec
instance (from GHC.Types.~ v, dec (a from), Versioning.Upgrade.Upgrade from w a) => Versioning.Internal.Decoding.DecodeAnyVersion' 'GHC.Types.True from v w a dec
instance (Versioning.Internal.Decoding.DecodeAnyVersion' (Versioning.Base.VPred v Versioning.Internal.Equality.== from) from (Versioning.Base.VPred v) w a dec, dec (a v), dec (a (Versioning.Base.VPred v)), Versioning.Upgrade.Upgrade v w a) => Versioning.Internal.Decoding.DecodeAnyVersion' 'GHC.Types.False from v w a dec


-- | JSON-specific deserialization utilities.
module Versioning.JSON

-- | The result type of the action that has been applied to the decoded
--   object with <a>withAnyVersion</a> or <a>withAnyVersionM</a>.
type family Applied (c :: Type -> Constraint) (a :: V -> Type) :: Type

-- | Handy constraint synonym to be used with <a>fromJsonAnyVersion</a>
type JsonDecodableTo v a = JsonDecodableToFrom V0 v a

-- | Like <a>JsonDecodableTo</a>, with an additional type-parameter
--   indicating the oldest version you want to be able to decode
type JsonDecodableToFrom from v a = DecodableToFrom from FromJSON v a

-- | Decode a JSON string by trying all the versions decrementally and
--   upgrade the decoded object to the newest version.
fromJsonAnyVersion :: forall v a. JsonDecodableTo v a => ByteString -> Maybe (a v)

-- | Like <a>fromJsonAnyVersion</a> but it reads from a strict
--   <tt>ByteString</tt>
fromJsonAnyVersionStrict :: forall v a. JsonDecodableTo v a => ByteString -> Maybe (a v)

-- | Like <a>fromJsonAnyVersion</a> but returns a message when decoding
--   fails
fromJsonAnyVersionEither :: forall v a. JsonDecodableTo v a => ByteString -> Either String (a v)

-- | Like <a>fromJsonAnyVersionStrict</a> but returns a message when
--   decoding fails
fromJsonAnyVersionEitherStrict :: forall v a. JsonDecodableTo v a => ByteString -> Either String (a v)

-- | Like <a>fromJsonAnyVersion</a>, with an additional type-parameter
--   indicating the oldest version you want to be able to decode
fromJsonAnyVersionFrom :: forall from v a. JsonDecodableToFrom from v a => ByteString -> Maybe (a v)

-- | Decode a JSON string by trying all the versions decrementally and
--   apply a pure function to the decoded object at its original version.
withJsonAnyVersion :: forall c a v. (WithAnyVersion v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Maybe (Applied c a)

-- | Like <a>withJsonAnyVersion</a> but it reads from a strict
--   <tt>ByteString</tt>
withJsonAnyVersionStrict :: forall c a v. (WithAnyVersion v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Maybe (Applied c a)

-- | Like <a>withJsonAnyVersion</a> but returns a message when decoding
--   fails
withJsonAnyVersionEither :: forall c a v. (WithAnyVersion v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Either String (Applied c a)

-- | Like <a>withJsonAnyVersionStrict</a> but returns a message when
--   decoding fails
withJsonAnyVersionEitherStrict :: forall c a v. (WithAnyVersion v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Either String (Applied c a)

-- | Like <a>withJsonAnyVersion</a>, with an additional type-parameter
--   indicating the oldest version you want to be able to decode
withJsonAnyVersionFrom :: forall from c a v. (WithAnyVersionFrom from v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Maybe (Applied c a)

-- | Decode a JSON string by trying all the versions decrementally and
--   apply an action to the decoded object at its original version.
withJsonAnyVersionM :: forall c a v m. (WithAnyVersion v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Maybe (Applied c a))

-- | Like <a>withJsonAnyVersionM</a> but it reads from a strict
--   <tt>ByteString</tt>
withJsonAnyVersionStrictM :: forall c a v m. (WithAnyVersion v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Maybe (Applied c a))

-- | Like <a>withJsonAnyVersionM</a> but returns a message when decoding
--   fails
withJsonAnyVersionEitherM :: forall c a v m. (WithAnyVersion v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Either String (Applied c a))

-- | Like <a>withJsonAnyVersionStrictM</a> but returns a message when
--   decoding fails
withJsonAnyVersionEitherStrictM :: forall c a v m. (WithAnyVersion v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Either String (Applied c a))

-- | Like <a>withJsonAnyVersionM</a>, with an additional type-parameter
--   indicating the oldest version you want to be able to decode
withJsonAnyVersionFromM :: forall from c a v m. (WithAnyVersionFrom from v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Maybe (Applied c a))