Webnative Elm

A thin wrapper around webnative for Elm.

QuickStart

elm install fission-suite/webnative-elm
npm install webnative-elm webnative

Setup the necessary ports on your Elm app.

port module Ports exposing (..)

import Webnative

port webnativeRequest : Webnative.Request -> Cmd msg
port wnfsRequest : Webnative.Request -> Cmd msg
port wnfsResponse : (Webnative.Response -> msg) -> Sub msg

Then import the javascript portion of this library to connect up the ports.

import * as webnative from "webnative"
import * as webnativeElm from "webnative-elm"

// elmApp = Elm.Main.init()

webnative
  .initialise({
    permissions: {
      app: { creator: "Fission", name: "Example" }
    }
  })
  .then(state => {
    webnativeElm.setup(elmApp, state.fs)
  })

Once we have that setup, we need can write our webnative Elm code.

import Webnative
import Wnfs


type Msg
  = ReadWnfsFile
  | WriteToWnfsFile
    --
  | GotWnfsResponse

type Tag
  = ReadHelloTxt
  | Mutation


base : Wnfs.Base Webnative.Response
base =
  Wnfs.AppData
    { creator = "Fission"
    , name = "Example"
    }

update : Msg -> Model -> (Model, Cmd Msg)
update msg model =
  case msg of
    ReadWnfsFile ->
      { path = [ "hello.txt" ]
      , tag = tagToString ReadHelloTxt
      }
        |> Wnfs.readUtf8 base
        |> Ports.wnfsRequest
        |> Tuple.pair model

    WriteToWnfsFile ->
      "👋"
        |> Wnfs.writeUtf8 base
          { path = [ "hello.txt" ]
          , tag = tagToString Mutation
          }
        |> Ports.wnfsRequest
        |> Tuple.pair model

    --

    GotWnfsResponse response ->
      case Wnfs.decodeResponse tagFromString response of
        Ok ( ReadHelloTxt, Wnfs.Utf8Content helloContents ) ->
          -- Do something with content from hello.txt

        Ok ( Mutation, _ ) ->
          ( model
          , Ports.wnfsRequest Wnfs.publish
          )

        Err errString ->
          -- Decoding, or tag parse, error.


-- TAG ENCODING/DECODING

tagToString : Tag -> String
tagToString tag =
  case tag of
    ReadHelloTxt -> "ReadHelloTxt"
    Mutation -> "Mutation"

tagFromString : String -> Result String Tag
tagFromString string =
  case string of
    "ReadHelloTxt" -> Ok ReadHelloTxt
    "Mutation" -> Ok Mutation
    _ -> Err "Invalid tag"

What's this tag thing?

You can chain webnative commands in Elm by providing a tag, which is then attached to the response. In the following example I have a custom type for my tags, which I then encode/decode to/from a string.

type Tag = Mutation

-- Request
Wnfs.writeUtf8 base
  { path = [ "hello.txt" ]
  , tag = tagToString Mutation
  }

-- Response
case Wnfs.decodeResponse tagFromString response of
  Ok ( Mutation, _ ) ->
    ( model
    , Ports.wnfsRequest Wnfs.publish
    )

API

We don't support all the functions from webnative yet.
For now you can do the following from Elm:

• All WNFS interactions
• Redirect to lobby

More coming later.
Let us know if you have any requests.

Customisation

You can customise the port names by passing in a third parameter.

webnativeElm.setup(elmApp, state.fs, {
  webnative: {
    incoming: "webnativeRequest"
  },
  wnfs: {
    incoming: "wnfsRequest",
    outgoing: "wnfsResponse"
  }
})