git.iko.soy/lynxjs-elm/compiler
on master help sign in
lynxjs-elm/compiler/packages/http/README.md
211 lines 3.9 kB history raw
1# lynxjs-elm/http
3HTTP requests for Elm on LynxJS. Replaces XMLHttpRequest with the Fetch API and AbortController.
5## Setup
7Add to your `elm.json`:
9```json
11 "dependencies": {
12 "direct": {
13 "lynxjs-elm/http": "1.0.0"
14 }
15 }
17```
19## Module: Http
21```elm
22import Http
23```
25### Basic Requests
27```elm
28get :
29 { url : String
30 , expect : Expect msg
31 }
32 -> Cmd msg
33```
35```elm
36post :
37 { url : String
38 , body : Body
39 , expect : Expect msg
40 }
41 -> Cmd msg
42```
44```elm
45request :
46 { method : String
47 , headers : List Header
48 , url : String
49 , body : Body
50 , expect : Expect msg
51 , timeout : Maybe Float
52 , tracker : Maybe String
53 }
54 -> Cmd msg
55```
57Full-control request. `timeout` is in milliseconds. `tracker` enables cancellation via `cancel`.
59### Headers
61```elm
62type Header
64header : String -> String -> Header
65```
67### Request Bodies
69```elm
70type Body
72emptyBody : Body
73stringBody : String -> String -> Body -- MIME type, content
74jsonBody : Json.Value -> Body
75bytesBody : String -> Bytes -> Body -- MIME type, bytes
76fileBody : File -> Body
77multipartBody : List Part -> Body
78```
80```elm
81type Part
83stringPart : String -> String -> Part -- name, value
84filePart : String -> File -> Part -- name, file
85bytesPart : String -> String -> Bytes -> Part -- name, MIME type, bytes
86```
88### Response Handling
90```elm
91type Expect msg
92```
94```elm
95expectString : (Result Error String -> msg) -> Expect msg
96expectJson : (Result Error a -> msg) -> Json.Decoder a -> Expect msg
97expectBytes : (Result Error a -> msg) -> Bytes.Decoder a -> Expect msg
98expectWhatever : (Result Error () -> msg) -> Expect msg
99```
101For custom error handling:
103```elm
104expectStringResponse : (Result x a -> msg) -> (Response String -> Result x a) -> Expect msg
105expectBytesResponse : (Result x a -> msg) -> (Response Bytes -> Result x a) -> Expect msg
106```
108### Types
110```elm
111type Error
112 = BadUrl String
113 | Timeout
114 | NetworkError
115 | BadStatus Int
116 | BadBody String
117```
119```elm
120type Response body
121 = BadUrl_ String
122 | Timeout_
123 | NetworkError_
124 | BadStatus_ Metadata body
125 | GoodStatus_ Metadata body
126```
128```elm
129type alias Metadata =
130 { url : String
131 , statusCode : Int
132 , statusText : String
133 , headers : Dict String String
134 }
135```
137### Progress Tracking
139```elm
140track : String -> (Progress -> msg) -> Sub msg
141```
143Subscribe to progress updates for a tracked request. Note: the Fetch API has limited progress support — tracking primarily enables cancellation.
145```elm
146type Progress
147 = Sending { sent : Int, size : Int }
148 | Receiving { received : Int, size : Maybe Int }
150fractionSent : { sent : Int, size : Int } -> Float
151fractionReceived : { received : Int, size : Maybe Int } -> Float
152```
154```elm
155cancel : String -> Cmd msg
156```
158Cancel a tracked request by its tracker name. Uses AbortController under the hood.
160### Task API
162```elm
163task :
164 { method : String
165 , headers : List Header
166 , url : String
167 , body : Body
168 , resolver : Resolver x a
169 , timeout : Maybe Float
170 }
171 -> Task x a
172```
174```elm
175type Resolver x a
177stringResolver : (Response String -> Result x a) -> Resolver x a
178bytesResolver : (Response Bytes -> Result x a) -> Resolver x a
179```
181### Risky Requests
183```elm
184riskyRequest : { ... } -> Cmd msg
185riskyTask : { ... } -> Task x a
186```
188Same as `request`/`task` but allows cookies from other domains (CORS credentials).
190### Example
192```elm
193import Http
194import Json.Decode as D
196type Msg
197 = GotQuote (Result Http.Error String)
199getQuote : Cmd Msg
200getQuote =
201 Http.get
202 { url = "https://api.example.com/quote"
203 , expect = Http.expectJson GotQuote (D.field "quote" D.string)
204 }
205```
207---
209## License
211BSD-3-Clause