FabienHenon / remote-resource / RemoteResource

Remote Resource alllows you to handle foreground and background resources, using https://package.elm-lang.org/packages/krisajenkins/remotedata/latest/.

For instance, let's say you want to retrieve a list of posts. You are using the RemoteData package, thus you can handle the state of your request (Loading, Success, etc...). You will probably display a loading icon while your request is in progress, and once it has been fully retrieved you will display your posts. But now, let's say you know your posts have changed and you would like to update them. You will probably want to send another request to your webservice with the same Elm RemoteData you used when you first retrieved your posts. That means your users will see your posts disapear for a few milliseconds (depending on the latency and network speed), replaced by a loading icon, to be finally updated and displayed again to your users.

Now, with RemoteResource you can refresh your posts in the background. Than means that you keep displaying your "old" posts to your users, and when the new data has been retrieved you can replace your old posts by the new ones without your users seeing some loading icon!

Definitions


type alias RemoteDataResource error res =
RemoteData error res

This is just an alias for RemoteData error res


type RemoteResource error res

Definition of the RemoteResource.

Initialization

init : RemoteResource error res

Initializes the remote resource. This is the first thing to do to get a brand new RemoteResource.

loading : RemoteResource error res -> RemoteResource error res

To mark you foreground resource as Loading. Your background resource will be reset to NotAsked.

    RemoteResource.init |> RemoteResource.loading

reloading : RemoteResource error res -> RemoteResource error res

To mark your background resource as Loading This does not change your foreground resource.

    RefreshPosts ->
        ( posts |> RemoteResource.reloading, Cmd.none )

Updating state

setResource : RemoteDataResource error res -> RemoteResource error res -> RemoteResource error res

Set the foreground resource. This will reset the background resource to NotAsked.

setOnlyResource : RemoteDataResource error res -> RemoteResource error res -> RemoteResource error res

Set the foreground resource without resetting the background resource.

setBackground : RemoteDataResource error res -> RemoteResource error res -> RemoteResource error res

If the foreground resource is in Loading state, this function will update the foreground resource. Otherwise, this will update the background resource without changing the foreground resource.

That means that you can use this function both when this is the first time you retrieve your resources (in this case you want to set the foreground resource), and when you want to refresh your resources and you already have foreground resources (in this case, maybe you want to store your background resources and tell your users there are new resources awailable before replacing the foreground resources))

setOnlyBackground : RemoteDataResource error res -> RemoteResource error res -> RemoteResource error res

Directly update the background resource without changing the foreground resource

replaceResourceByBackground : RemoteResource error res -> RemoteResource error res

If the current background resource is in Success state, then we replace the foreground resource by the background resource and we set the background resource to NotAsked

Getters

resource : RemoteResource error res -> RemoteDataResource error res

Get the current foreground resource

backgroundResource : RemoteResource error res -> RemoteDataResource error res

Get the current background resource

resourceAndBackgroundWithDefault : res -> RemoteResource error res -> ( res, res )

Get a tuple with the foreground resource and the background resource. You will retrieve the final resource, thus, if the resource is not in Success state, the default resource will be returned.

Advanced

map : (res -> res) -> RemoteResource error res -> RemoteResource error res

Map your foreground resource (RemoteData.map is applied to the foreground resource)

mapBackground : (res -> res) -> RemoteResource error res -> RemoteResource error res

Map your background resource (RemoteData.map is applied to the background resource)

hasNewResource : (res -> res -> Basics.Bool) -> RemoteResource error res -> Basics.Bool

Compare the foreground and the background resources to check if there are different (In this case you could tell your users new resources have arrived).