Versioning.Base

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 Since and Until type families.

Example:

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
    }

Besides reducing the number of data declarations, this approach also has other advantages:

• It makes migrations declarative and self-documenting.
• It allows for less verbose version-upcasting functions, since the fields that have a non-parametric type do not need to be copied.
• It is a foundation on which other useful abstractions can be built.

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.

Types

data V

The version of a data model

Constructors

VZero

VSucc V

Instances

Eq V

Defined in Versioning.Base

Methods

(==) :: V -> V -> Bool

(/=) :: V -> V -> Bool

Show V

Defined in Versioning.Base

Methods

showsPrec :: Int -> V -> ShowS

show :: V -> String

showList :: [V] -> ShowS

type family VPred (v :: V) :: V where ...

Get the previous version

Equations

VPred (VSucc v) = v

VPred VZero = VZero

type VSucc = VSucc

type family VNat (v :: V) :: Nat where ...

Get the type-level natural of a version

Equations

VNat v = VNat' v 0

type family VCmp (v :: V) (w :: V) :: Ordering where ...

Compare two versions

Equations

VCmp VZero VZero = EQ

VCmp VZero v = LT

VCmp v VZero = GT

VCmp (VSucc v) (VSucc w) = VCmp v w

type family Since (s :: V) (v :: V) a where ...

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.

Equations

Since s v a = Since' (VCmp s v) a

type family Until (u :: V) (v :: V) a where ...

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.

Equations

Until u v a = Until' (VCmp u v) a

type NA = Maybe Bare

A type indicating absence. The Maybe is a hack needed to let aeson parse a record successfully even if a field of type NA is missing.

Ideally we would like to define it as

data NA = NA

but this would not work with FromJSON instances that are derived with Generic.

na :: NA

A placeholder for an absent value.

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

Functions

versionNumber :: forall a v. KnownNat (VNat v) => a v -> Natural

Get the version number of a versioned value