Add FormData read & edit functions, write documentation

.github/workflows/test.yml

@@ -18,6 +18,6 @@ jobs:
       - uses: erlef/setup-beam@v1
         with:
           otp-version: false
-          gleam-version: "1.6.0"
+          gleam-version: "1.8.1"
       - run: gleam test
       - run: gleam format --check src test

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v1.2.0 - Unreleased
+
+- Add support for formdata reading and editing.
+- Add documentation for every functions and improve README.
+
 ## v1.1.1 - 2025-02-06
 
 - Relaxed the `gleam_http` requirement to permit v4.

README.md

@@ -1,20 +1,32 @@
-# Fetch
+# Gleam Fetch
 
 <a href="https://github.com/gleam-lang/fetch/releases"><img src="https://img.shields.io/github/release/gleam-lang/fetch" alt="GitHub release"></a>
 <a href="https://discord.gg/Fm8Pwmy"><img src="https://img.shields.io/discord/768594524158427167?color=blue" alt="Discord chat"></a>
 
-Bindings to JavaScript's built in HTTP client, `fetch`.
+A library to use [`fetch`](https://developer.mozilla.org/docs/Web/API/Fetch_API), the built-in JavaScript HTTP client!
 
-If you are running your Gleam project on the Erlang target (the default
-for new Gleam projects) then you will want to use a different library
-which can run on Erlang, such as [gleam_httpc](https://github.com/gleam-lang/httpc).
+## Features
 
-```gleam
-import gleam/fetch
-import gleam/http/request
-import gleam/http/response
-import gleam/javascript/promise
+- Issue HTTP requests.
+- Handle HTTP responses in different formats (text, binary, JSON).
+- Read & Write [`FormData`](https://developer.mozilla.org/docs/Web/API/FormData).
+
+## Installation
+
+Add `gleam_fetch` & `gleam_http` to your Gleam project.
+
+```sh
+gleam add gleam_http gleam_fetch
+```
 
+> [!WARNING]
+> If you are running your Gleam project on the Erlang target (the default for
+> new Gleam projects) then you will want to use a different library which can
+> run on Erlang, such as [`gleam_httpc`](https://github.com/gleam-lang/httpc).
+
+## Usage
+
+```gleam
 pub fn main() {
   let assert Ok(req) = request.to("https://example.com")
 
@@ -32,3 +44,8 @@ pub fn main() {
   promise.resolve(Ok(Nil))
 }
 ```
+
+Documentation can be found at [https://hexdocs.pm/gleam_fetch](https://hexdocs.pm/gleam_fetch).
+
+`gleam_fetch` works on every JavaScript runtime implementing `fetch`, which
+implies all modern browsers, Node.js >= 18.0.0, Deno & Bun.

gleam.toml

@@ -1,5 +1,5 @@
 name = "gleam_fetch"
-version = "1.1.1"
+version = "1.2.0"
 licences = ["Apache-2.0"]
 description = "Make HTTP requests in Gleam JavaScript with Fetch"
 target = "javascript"
@@ -18,4 +18,3 @@ gleam_stdlib = ">= 0.32.0 and < 2.0.0"
 
 [dev-dependencies]
 gleeunit = ">= 1.0.0 and < 2.0.0"
-

src/gleam/fetch.gleam

@@ -4,21 +4,61 @@ import gleam/http/request.{type Request}
 import gleam/http/response.{type Response}
 import gleam/javascript/promise.{type Promise}
 
+/// Fetch errors can be due to a network error or a runtime error. A common
+/// mistake is to try to consume the response body twice, or to try to read the
+/// response body as JSON while it's not a valid JSON.
+///
+/// Take note that a 500 response is not considered as an error: it is a
+/// successful request, which indicates the server triggers an error.
 pub type FetchError {
+  /// A network error occured, maybe because user lost network connection,
+  /// because the network took to long to answer, or because the
+  /// server timed out.
   NetworkError(String)
+  /// Fetch is unable to read body, for example when body as already been read
+  /// once.
   UnableToReadBody
   InvalidJsonBody
 }
 
 pub type FetchBody
 
+/// Gleam equivalent of JavaScript [`Request`](https://developer.mozilla.org/docs/Web/API/Request).
 pub type FetchRequest
 
+/// Gleam equivalent of JavaScript [`Response`](https://developer.mozilla.org/docs/Web/API/Response).
 pub type FetchResponse
 
+/// Call directly `fetch` with a `Request`, and convert the result back to Gleam.
+/// Let you get back a `FetchResponse` instead of the Gleam
+/// `gleam/http/response.Response` data.
+///
+/// ```gleam
+/// request.new()
+/// |> request.set_host("example.com")
+/// |> request.set_path("/example")
+/// |> fetch.to_fetch_request
+/// |> fetch.raw_send
+/// // -> Promise(Result(FetchResponse, FetchError))
+/// ```
 @external(javascript, "../gleam_fetch_ffi.mjs", "raw_send")
 pub fn raw_send(a: FetchRequest) -> Promise(Result(FetchResponse, FetchError))
 
+/// Call `fetch` with a Gleam `Request(String)`, and convert the result back
+/// to Gleam. Use it to send strings or JSON stringified.
+///
+/// If you're looking for something more low-level, take a look at
+/// [`raw_send`](#raw_send).
+///
+/// ```gleam
+/// let my_data = json.object([#("field", "value")])
+/// request.new()
+/// |> request.set_host("example.com")
+/// |> request.set_path("/example")
+/// |> request.set_body(json.to_string(my_data))
+/// |> request.set_header("content-type", "application/json")
+/// |> fetch.send
+/// ```
 pub fn send(
   request: Request(String),
 ) -> Promise(Result(Response(FetchBody), FetchError)) {
@@ -30,6 +70,23 @@ pub fn send(
   })
 }
 
+/// Call `fetch` with a Gleam `Request(FormData)`, and convert the result back
+/// to Gleam. Request will be sent as a `multipart/form-data`, and should be
+/// decoded as-is on servers.
+///
+/// If you're looking for something more low-level, take a look at
+/// [`raw_send`](#raw_send).
+///
+/// ```gleam
+/// request.new()
+/// |> request.set_host("example.com")
+/// |> request.set_path("/example")
+/// |> request.set_body({
+///   form_data.new()
+///   |> form_data.append("key", "value")
+/// })
+/// |> fetch.send_form_data
+/// ```
 pub fn send_form_data(
   request: Request(FormData),
 ) -> Promise(Result(Response(FetchBody), FetchError)) {
@@ -41,6 +98,21 @@ pub fn send_form_data(
   })
 }
 
+/// Call `fetch` with a Gleam `Request(FormData)`, and convert the result back
+/// to Gleam. Binary will be sent as-is, and you probably want a proper
+/// content-type added.
+///
+/// If you're looking for something more low-level, take a look at
+/// [`raw_send`](#raw_send).
+///
+/// ```gleam
+/// request.new()
+/// |> request.set_host("example.com")
+/// |> request.set_path("/example")
+/// |> request.set_body(<<"data">>)
+/// |> request.set_header("content-type", "application/octet-stream")
+/// |> fetch.send_form_data
+/// ```
 pub fn send_bits(
   request: Request(BitArray),
 ) -> Promise(Result(Response(FetchBody), FetchError)) {
@@ -52,28 +124,140 @@ pub fn send_bits(
   })
 }
 
+/// Convert a Gleam `Request(String)` to a JavaScript
+/// [`Request`](https://developer.mozilla.org/docs/Web/API/Request), where
+/// `body` is a string.
+///
+/// Can be used in conjuction with `raw_send`, or when you need to reuse your
+/// `Request` in JavaScript FFI.
+///
+/// ```gleam
+/// let request =
+///   request.new()
+///   |> request.set_host("example.com")
+///   |> request.set_path("/example")
+/// fetch.to_fetch_request(request)
+/// // -> FetchRequest
+/// ```
 @external(javascript, "../gleam_fetch_ffi.mjs", "to_fetch_request")
 pub fn to_fetch_request(a: Request(String)) -> FetchRequest
 
+/// Convert a Gleam `Request(FormData)` to a JavaScript
+/// [`Request`](https://developer.mozilla.org/docs/Web/API/Request), where
+/// `body` is a JavaScript `FormData` object.
+///
+/// Can be used in conjuction with `raw_send`, or when you need to reuse your
+/// `Request` in JavaScript FFI.
+///
+/// ```gleam
+/// let request =
+///   request.new()
+///   |> request.set_host("example.com")
+///   |> request.set_path("/example")
+///   |> request.set_body({
+///     form_data.new()
+///     |> form_data.append("key", "value")
+///   })
+/// fetch.form_data_to_fetch_request(request)
+/// // -> FetchRequest
+/// ```
 @external(javascript, "../gleam_fetch_ffi.mjs", "form_data_to_fetch_request")
 pub fn form_data_to_fetch_request(a: Request(FormData)) -> FetchRequest
 
+/// Convert a Gleam `Request(BitArray)` to a JavaScript
+/// [`Request`](https://developer.mozilla.org/docs/Web/API/Request), where
+/// `body` is a JavaScript `UInt8Array` object.
+///
+/// Can be used in conjuction with `raw_send`, or when you need to reuse your
+/// `Request` in JavaScript FFI.
+///
+/// ```gleam
+/// let request =
+///   request.new()
+///   |> request.set_host("example.com")
+///   |> request.set_path("/example")
+///   |> request.set_body(<<"data">>)
+/// fetch.bitarray_request_to_fetch_request(request)
+/// // -> FetchRequest
+/// ```
 @external(javascript, "../gleam_fetch_ffi.mjs", "bitarray_request_to_fetch_request")
 pub fn bitarray_request_to_fetch_request(a: Request(BitArray)) -> FetchRequest
 
+/// Convert a JavaScript [`Response`](https://developer.mozilla.org/docs/Web/API/Response)
+/// into a Gleam `Response(FetchBody)`. Can be used with the result of
+/// `raw_send`, or with some data received through the FFI.
+///
+/// ```gleam
+/// request.new()
+/// |> request.set_host("example.com")
+/// |> request.set_path("/example")
+/// |> fetch.to_fetch_request
+/// |> fetch.raw_send
+/// |> promise.map_try(fetch.from_fetch_response)
+/// // -> Promise(Result(Response(FetchBody), FetchError))
+/// ```
 @external(javascript, "../gleam_fetch_ffi.mjs", "from_fetch_response")
 pub fn from_fetch_response(a: FetchResponse) -> Response(FetchBody)
 
+/// Read a response body as a BitArray. Returns an error when the body is not a
+/// valid BitArray. Because `fetch.send` returns a `Promise` and every
+/// functions to read response body are also asynchronous, take care to properly
+/// use `gleam/javascript/promise` to combine them.
+///
+/// ```gleam
+/// let my_data = json.object([#("field", "value")])
+/// request.new()
+/// |> request.set_host("example.com")
+/// |> request.set_path("/example")
+/// |> request.set_body(json.to_string(my_data))
+/// |> request.set_header("content-type", "application/json")
+/// |> fetch.send
+/// |> promise.try_await(fetch.read_bytes_body)
+/// ```
 @external(javascript, "../gleam_fetch_ffi.mjs", "read_bytes_body")
 pub fn read_bytes_body(
   a: Response(FetchBody),
 ) -> Promise(Result(Response(BitArray), FetchError))
 
+/// Read a response body as a String. Returns an error when the body is not a
+/// valid String. Because `fetch.send` returns a `Promise` and every
+/// functions to read response body are also asynchronous, take care to properly
+/// use `gleam/javascript/promise` to combine them.
+///
+/// ```gleam
+/// let my_data = json.object([#("field", "value")])
+/// request.new()
+/// |> request.set_host("example.com")
+/// |> request.set_path("/example")
+/// |> request.set_body(json.to_string(my_data))
+/// |> request.set_header("content-type", "application/json")
+/// |> fetch.send
+/// |> promise.try_await(fetch.read_text_body)
+/// ```
 @external(javascript, "../gleam_fetch_ffi.mjs", "read_text_body")
 pub fn read_text_body(
   a: Response(FetchBody),
 ) -> Promise(Result(Response(String), FetchError))
 
+/// Read a response body as a JSON. Returns an error when the body is not a
+/// valid String. Because `fetch.send` returns a `Promise` and every
+/// functions to read response body are also asynchronous, take care to properly
+/// use `gleam/javascript/promise` to combine them.
+///
+/// Once read, you probably want to use
+/// [`gleam/dynamic/decode`](https://hexdocs.pm/gleam_stdlib/gleam/dynamic/decode.html)
+/// to decode its content in proper Gleam data.
+///
+/// ```gleam
+/// let my_data = json.object([#("field", "value")])
+/// request.new()
+/// |> request.set_host("example.com")
+/// |> request.set_path("/example")
+/// |> request.set_body(json.to_string(my_data))
+/// |> request.set_header("content-type", "application/json")
+/// |> fetch.send
+/// |> promise.try_await(fetch.read_json_body)
+/// ```
 @external(javascript, "../gleam_fetch_ffi.mjs", "read_json_body")
 pub fn read_json_body(
   a: Response(FetchBody),