Add VersionControl

elm.json

@@ -7,7 +7,8 @@
     "exposed-modules": [
         "Matrix",
         "Internal.Tools.Hashdict",
-        "Internal.Tools.Iddict"
+        "Internal.Tools.Iddict",
+        "Internal.Tools.VersionControl"
     ],
     "elm-version": "0.19.0 <= v < 0.20.0",
     "dependencies": {

src/Internal/Tools/VersionControl.elm

@@ -0,0 +1,365 @@
+module Internal.Tools.VersionControl exposing
+    ( VersionControl, withBottomLayer
+    , sameForVersion, MiddleLayer, addMiddleLayer
+    , isSupported, toDict, fromVersion, mostRecentFromVersionList, fromVersionList
+    )
+
+{-|
+
+
+# Version Control module
+
+This module helps you maintain different functions based on their version.
+
+Not every Matrix homeserver is the same. Some keep up with the latest Matrix
+specifications, while others stay behind because they have to support legacy
+projects who do not support new API endpoints (yet). The Elm SDK aims to support
+as many homeserver versions as possible - at the same time.
+
+Support for legacy versions can be difficult! The Elm SDK expects one way of
+getting information, and translating every Matrix spec(ification) version to it
+can take time. But what if a new Matrix spec version adds a new feature? Do we
+need to re-translate every single version to accomodate any future updates?
+
+The VersionControl helps define different API rules for different spec versions
+in an easy way. The VersionControl module puts all the versions in a linear
+timeline. (Because, you know, updates are usually newer versions of older
+versions.) This way, you can define different behaviour while still having only
+one input, one output.
+
+The module can be best described as a layered version type.
+
+    |----------------------------------------------|
+    | VersionControl                               |
+    |                     input            output  |
+    |                       |                ^     |
+    |---------------------- | -------------- | ----|
+                            |                |
+    |---------------------- | -------------- | ----|
+    | MiddleLayer v3        |                |     |
+    |                       [---> current ---]     |
+    |                       |                |     |
+    |                    downcast          upcast  |
+    |                       |                ^     |
+    |---------------------- | -------------- | ----|
+                            |                |
+    |---------------------- | -------------- | ----|
+    | MiddleLayer v2        |                |     |
+    |                       [---> current ---]     |
+    |                       |                |     |
+    |                    downcast          upcast  |
+    |                       |                ^     |
+    |---------------------- | -------------- | ----|
+                            |                |
+    |---------------------- | -------------- | ----|
+    | BottomLayer v1        |                |     |
+    |                       \---> current ---/     |
+    |                                              |
+    |----------------------------------------------|
+
+This method means you only need to write one downcast, one current and one
+upcast whenever you introduce a new version. In other words, you can instantly
+update all functions without having to write every version!
+
+The VersionControl keeps tracks the version order. This way, you can either get
+the VersionControl type to render the function for the most recent supported
+version, or you can choose for yourself which version you prefer to use.
+
+
+## Building a VersionControl
+
+To build a VersionControl type, one must start with the bottom layer and start
+building up to newer versions with middle layers.
+
+
+### Create
+
+@docs VersionControl, withBottomLayer
+
+
+### Expand
+
+@docs sameForVersion, MiddleLayer, addMiddleLayer
+
+
+## Getting functions
+
+Once you've successfully built the VersionControl type, there's a variety of
+ways in which you can find an appropriate function.
+
+@docs isSupported, toDict, fromVersion, mostRecentFromVersionList, fromVersionList
+
+-}
+
+import Dict exposing (Dict)
+
+
+{-| The VersionControl layer is the layer on top that keeps track of all the
+available versions. It is usually defined with a bottom layer and a few layers
+on top.
+-}
+type VersionControl input output
+    = VersionControl
+        { latestVersion : input -> output
+        , order : List String
+        , versions : Dict String (input -> output)
+        }
+
+
+{-| The middle layer is placed between a VersionControl and a BottomLayer to
+support a new function for a new version. The abbreviations stand for the
+following:
+
+  - `cin` means **current in**. It is the Middle Layer's input.
+
+  - `cout` means **current out**. It is the Middle Layer's output.
+
+  - `din` means **downcast in**. It is the Bottom Layer's input.
+
+  - `dout` means **downcast out**. It is the Bottom Layer's output.
+
+As a result, we have the following model to explain the MiddleLayer:
+
+    |----------------------------------------------|
+    | VersionControl                               |
+    |                     input            output  |
+    |                       |                ^     |
+    |---------------------- | -------------- | ----|
+                           [cin]           [cout]
+    |---------------------- | -------------- | ----|
+    | MiddleLayer           |                |     |
+    |                       [---> current ---]     |
+    |                       |                |     |
+    |                    downcast          upcast  |
+    |                       |                ^     |
+    |---------------------- | -------------- | ----|
+                          [din]            [dout]
+    |---------------------- | -------------- | ----|
+    | BottomLayer           |                |     |
+    |                       \---> current ---/     |
+    |                                              |
+    |----------------------------------------------|
+
+To sew a MiddleLayer type, we need the `downcast` and `upcast` functions to
+translate the `cin` and `cout` to meaningful values `din` and `dout` for the
+BottomLayer function.
+
+Usually, this means transforming the data. For example, say our BottomLayer
+still has an old version where people had just one name, and our MiddleLayer
+version has two fields: a first and last name.
+
+    type alias NewUser =
+        { firstName : String, lastName : String, age : Int }
+
+    type alias OldUser =
+        { name : String, age : Int }
+
+An appropriate downcasting function could then something like the following:
+
+    downcast : NewUser -> OldUser
+    downcast user =
+        { name = user.firstName ++ " " ++ user.lastName, age = user.age }
+
+-}
+type alias MiddleLayer cin cout din dout =
+    { current : cin -> cout
+    , downcast : cin -> din
+    , upcast : dout -> cout
+    , version : String
+    }
+
+
+{-| Add a MiddleLayer to the VersionControl, effectively updating all old
+functions with a downcast and upcast to deal with the inputs and outputs of all
+functions at the same time.
+
+For example, using the `NewUser` and `OldUser` types, one could create the
+following example to get the user's names:
+
+    vc : VersionControl NewUser String
+    vc =
+        withBottomLayer
+            { current = .name
+            , version = "v1"
+            }
+            |> sameForVersion "v2"
+            |> sameForVersion "v3"
+            |> sameForVersion "v4"
+            |> sameForVersion "v5"
+            |> sameForVersion "v6"
+            |> addMiddleLayer
+                { downcast = \user -> { name = user.firstName ++ " " ++ user.lastName, age = user.age }
+                , current = \user -> user.firstName ++ " " ++ user.lastName
+                , upcast = identity
+                , version = "v7"
+                }
+
+Effectively, even though versions `v1` through `v6` still require an `OldUser`
+type as an input, all functions have now been updated to the new standard of
+getting a `NewUser` as an input thanks to the `downcast` function.
+
+-}
+addMiddleLayer : MiddleLayer cin cout din dout -> VersionControl din dout -> VersionControl cin cout
+addMiddleLayer { current, downcast, upcast, version } (VersionControl d) =
+    VersionControl
+        { latestVersion = current
+        , order = version :: d.order
+        , versions =
+            d.versions
+                |> Dict.map (\_ f -> downcast >> f >> upcast)
+                |> Dict.insert version current
+        }
+
+
+{-| Get the function that corresponds with a given version. Returns `Nothing` if
+the version has never been inserted into the VersionControl type.
+-}
+fromVersion : String -> VersionControl a b -> Maybe (a -> b)
+fromVersion version (VersionControl { versions }) =
+    Dict.get version versions
+
+
+{-| Provided a list of versions, this function will provide a list of compatible versions to you in your preferred order.
+
+If you just care about getting the most recent function, you will be better off using `mostRecentFromVersionList`,
+but this function can help if you care about knowing which Matrix spec version you're using.
+
+-}
+fromVersionList : List String -> VersionControl a b -> List ( String, a -> b )
+fromVersionList versionList vc =
+    List.filterMap
+        (\version ->
+            vc
+                |> fromVersion version
+                |> Maybe.map (\f -> ( version, f ))
+        )
+        versionList
+
+
+{-| Determine if a version is supported by the VersionControl.
+
+    vc : VersionControl NewUser String
+    vc =
+        withBottomLayer
+            { current = .name
+            , version = "v1"
+            }
+            |> sameForVersion "v2"
+            |> sameForVersion "v3"
+            |> sameForVersion "v4"
+
+    isSupported "v3" vc -- True
+    isSupported "v9" vc -- False
+
+-}
+isSupported : String -> VersionControl a b -> Bool
+isSupported version (VersionControl d) =
+    Dict.member version d.versions
+
+
+{-| Get the most recent event based on a list of versions. Returns `Nothing` if
+the list is empty, or if none of the versions are supported.
+
+    vc : VersionControl a b
+    vc =
+      withBottomLayer
+        { current = foo
+        , version = "v1"
+        }
+        |> sameForVersion "v2"
+        |> sameForVersion "v3"
+        |> sameForVersion "v4"
+        |> sameForVersion "v5"
+        |> sameForVersion "v6"
+
+    -- This returns the function for v6 because that is the most recent version
+    -- in the provided version list
+    mostRecentFromVersionList [ "v5", "v3", "v7", "v6", "v8" ] vc
+
+-}
+mostRecentFromVersionList : List String -> VersionControl a b -> Maybe (a -> b)
+mostRecentFromVersionList versionList ((VersionControl { order }) as vc) =
+    order
+        |> List.filter (\o -> List.member o versionList)
+        |> List.filterMap (\v -> fromVersion v vc)
+        |> List.head
+
+
+{-| Not every version overhauls every interaction. For this reason, many version
+functions are identical to their previous functions.
+
+This function adds a new version to the VersionControl and tells it that the
+version uses the same function as the previous version.
+
+    vc : VersionControl User String
+    vc =
+        withBottomLayer
+            { current = .name
+            , version = "v1"
+            }
+            |> sameForVersion "v2"
+            |> sameForVersion "v3"
+            |> sameForVersion "v4"
+            |> sameForVersion "v5"
+            |> sameForVersion "v6"
+
+The example above lists the function `.name` for versions `v1` through `v6`.
+
+-}
+sameForVersion : String -> VersionControl a b -> VersionControl a b
+sameForVersion version (VersionControl data) =
+    VersionControl
+        { data
+            | order = version :: data.order
+            , versions = Dict.insert version data.latestVersion data.versions
+        }
+
+
+{-| Get a dict of all available functions.
+
+
+    vc : VersionControl NewUser String
+    vc =
+        withBottomLayer
+            { current = .name
+            , version = "v1"
+            }
+            |> sameForVersion "v2"
+            |> sameForVersion "v3"
+            |> sameForVersion "v4"
+            |> toDict
+
+    -- Dict.fromList
+    --     [ ( "v1", <internal> )
+    --     , ( "v2", <internal> )
+    --     , ( "v3", <internal> )
+    --     , ( "v4", <internal> )
+    --     ]
+
+-}
+toDict : VersionControl a b -> Dict String (a -> b)
+toDict (VersionControl d) =
+    d.versions
+
+
+{-| You cannot create an empty VersionControl layer, you must always start with a BottomLayer
+and then stack MiddleLayer types on top until you've reached the version that you're happy with.
+
+    vc : VersionControl User String
+    vc =
+        withBottomLayer
+            { current = .name
+            , version = "v1"
+            }
+
+    type alias User =
+        { name : String, age : Int }
+
+-}
+withBottomLayer : { current : input -> output, version : String } -> VersionControl input output
+withBottomLayer { current, version } =
+    VersionControl
+        { latestVersion = current
+        , order = List.singleton version
+        , versions = Dict.singleton version current
+        }