lobanov / elm-localstorage / LocalStorage

Exposes browser's window.localStorage and window.sessionStorage API as Elm Tasks. Thanks to the latter, interactions with the local and session storage could be chained or mixed with other Task-based APIs, such as elm/http.

See package documentation for examples of using the module.

General


type alias Key =
String

Convenience alias for string keys used to store and retrive values in window.localStorage and window.sessionStorage objects.

Local storage

localGet : Key -> TaskPort.Task (Maybe String)

Returns a Task retrieving a value from the browser's window.localStorage object. The result will have Nothing if there is no value associated with a given key in the local storage.

type Msg = GotValue (TaskPort.Result (Maybe String))
LocalStorage.localGet "key" |> Task.attempt GotValue

localPut : Key -> String -> TaskPort.Task ()

Returns a Task storing a value with a given key in the browser's window.localStorage object. Most likely this is going to be used to synchronise browser's local storage with the application model after it changes.

type Msg = Saved (TaskPort.Result ())
LocalStorage.localPut "key" "value" |> Task.attempt Saved

It is likely you will need to store objects which are more complex than strings. It is easy to chain the use of Json.Encode.encode as follow.

Json.Encode.list Json.Encode.string [ 'v1', 'v2' ]
    |> Json.Encode.encode 0
    |> LocalStorage.localPut "key"

localRemove : Key -> TaskPort.Task ()

Returns a Task removing a value stored in the browser's window.localStorage object under a given key.

type Msg = Saved (TaskPort.Result ())
LocalStorage.localRemove "key" |> Task.attempt Removed

localListKeys : TaskPort.Task (List Key)

Returns a Task enumerating all keys in the browser's window.localStorage object.

type Msg = GotKeys (TaskPort.Result (List String))
LocalStorage.localListKeys "key" |> Task.attempt GotKeys

localClear : TaskPort.Task ()

Returns a Task deleting all items from the browser's window.localStorage object. A good place to do this is when user clicks 'log off' button.

type Msg = Cleared (TaskPort.Result ())
LocalStorage.localClear |> Task.attempt Cleared

Session storage

sessionGet : Key -> TaskPort.Task (Maybe String)

Returns a Task retrieving a value from the browser's window.sessionStorage object. The result will have Nothing if there is no value associated with a given key in the local storage.

type Msg = GotValue (TaskPort.Result (Maybe String))
LocalStorage.sessionGet "key" |> Task.attempt GotValue

sessionPut : Key -> String -> TaskPort.Task ()

Returns a Task storing a value with a given key in the browser's window.sessionStorage object. Most likely this is going to be used to synchronise browser's window session state with the application model after it changes.

type Msg = Saved (TaskPort.Result ())
LocalStorage.sessionPut "key" "value" |> Task.attempt Saved

It is likely you will need to store objects which are more complex than strings. It is easy to chain the use of Json.Encode.encode as follow.

Json.Encode.list Json.Encode.string [ 'v1', 'v2' ]
    |> Json.Encode.encode 0
    |> LocalStorage.sessionPut "key"

sessionRemove : Key -> TaskPort.Task ()

Returns a Task removing a value stored in the browser's window.localStorage object under a given key.

type Msg = Saved (TaskPort.Result ())
LocalStorage.sessionRemove "key" |> Task.attempt Removed

sessionListKeys : TaskPort.Task (List Key)

Returns a Task enumerating all keys in the browser's window.sessionStorage object.

type Msg = GotKeys (TaskPort.Result (List Key))
LocalStorage.sessionListKeys "key" |> Task.attempt GotKeys

sessionClear : TaskPort.Task ()

Returns a Task deleting all items from the browser's window.sessionStorage object. A good place to do this is when user clicks 'log off' button.

type Msg = Cleared (TaskPort.Result ())
LocalStorage.sessionClear |> Task.attempt Cleared