Represents a file. From there you can read the content, check the metadata, send it over a port, etc.

Decode File values. For example, if you want to create a drag-and-drop file uploader, you can listen for drop events with a decoder like this:

import Json.Decode exposing (Decoder, field, list)
import ValuableFile exposing (ValuableFile)

files : Decode.Decoder (List ValuableFile)
files =
    field "dataTransfer" (field "files" (list ValuableFile.decoder))

Once you have the files, you can use functions like ValuableFile.toString to process the content. Or you can send the file along to someone else with the elm/http package.

Encode File values. This is useful to send them through a port:

import ValuableFile

port sendFile : Value -> msg

then in an update function:

case msg of
    ValuableFileSelected (Ok file) ->
        ( model, sendFile (ValuableFile.encode file) )

Convert to a standard elm/file File, for example to send it over elm/http.

import Http

Http.multipartBody
    [ stringPart "product" "Ikea Bekant"
    , stringPart "description" "Great desk for home office."
    , filePart "image[]" (ValuableFile.toFile file1)
    , filePart "image[]" (ValuableFile.toFile file2)
    , filePart "image[]" (ValuableFile.toFile file3)
    ]

Extract the content of a File as a String. So if you have a notes.md file you could read the content like this:

import Task
import ValuableFile exposing (ValuableFile)

type Msg
    = MarkdownLoaded String

read : ValuableFile -> Cmd Msg
read file =
    Task.perform MarkdownLoaded (ValuableFile.toString file)

Reading the content is asynchronous because browsers want to avoid allocating the file content into memory if possible. (E.g. if you are just sending files along to a server with elm/http there is no point having their content in memory!)

Extract the content of a File as Bytes. So if you have an archive.zip file you could read the content like this:

import Bytes exposing (Bytes)
import Task
import ValuableFile exposing (ValuableFile)

type Msg
    = ZipLoaded Bytes

read : ValuableFile -> Cmd Msg
read file =
    Task.perform ZipLoaded (ValuableFile.toBytes file)

From here you can use the elm/bytes package to work with the bytes and turn them into whatever you want.

The File.toUrl function will convert files into URLs like this:

• data:*/*;base64,V2hvIGF0ZSBhbGwgdGhlIHBpZT8=
• data:*/*;base64,SXQgd2FzIG1lLCBXaWxleQ==
• data:*/*;base64,SGUgYXRlIGFsbCB0aGUgcGllcywgYm95IQ==

This is using a Base64 encoding to turn arbitrary binary data into ASCII characters that safely fit in strings.

This is primarily useful when you want to show images that were just uploaded because an <img> tag expects its src attribute to be a URL. So if you have a website for selling furniture, using File.toUrl could make it easier to create a screen to preview and reorder images. This way people can make sure their old table looks great!

Get the name of a file.

ValuableFile.name file1 == "README.md"

ValuableFile.name file2 == "math.gif"

ValuableFile.name file3 == "archive.zip"

Get the MIME type of a file.

ValuableFile.mime file1 == "text/markdown"

ValuableFile.mime file2 == "image/gif"

ValuableFile.mime file3 == "application/zip"

Get the size of the file in bytes.

ValuableFile.size file1 == 395

ValuableFile.size file2 == 65813

ValuableFile.size file3 == 81481

Get the time the file was last modified.

ValuableFile.lastModified file1 -- 1536872423

ValuableFile.lastModified file2 -- 860581394

ValuableFile.lastModified file3 -- 1340375405

Learn more about how time is represented by reading through the elm/time package!