@swan-io/request

@swan-io/request

Wrapper for XMLHttpRequest with better data-structures

Installation

$ yarn add @swan-io/request @swan-io/boxed
# --- or ---
$ npm install --save @swan-io/request @swan-io/boxed

Design principles

• Has a strong contract with data-structures from Boxed (Future, Result & Option)
• Makes the request easily cancellable with Future API
• Gives freedom of interpretation for response status
• Handles onLoadStart & onProgress events
• Handles timeouts
• Types the response using the provided responseType

Getting started

import { Request, badStatusToError, emptyToError } from "@swan-io/request";

// Regular case
Request.make({ url: "/api/health" }).onResolve(console.log);
// Result.Ok({status: 200, ok: true, response: Option.Some("{\"ok\":true}")})

// Timeout
Request.make({ url: "/api/health", timeout: 50 }).onResolve(console.log);
// Result.Error(TimeoutError)

// Network error
Request.make({ url: "/api/health" }).onResolve(console.log);
// Result.Error(NetworkError)

// Custom response type
Request.make({ url: "/api/health", responseType: "json" }).onResolve(
  console.log,
);
// Result.Ok({status: 200, ok: true, response: Option.Some({ok: true})})

// Handle empty response as an error
Request.make({ url: "/api/health" })
  .mapOkToResult(emptyToError)
  .onResolve(console.log);
// Result.Error(EmptyResponseError)

// Handle bad status as an error
Request.make({ url: "/api/health" })
  .mapOkToResult(badStatusToError)
  .onResolve(console.log);
// Result.Error(BadStatusError)

// Cancel request
useEffect(() => {
  const future = Request.make({ url: "/api/health" });
  return () => future.cancel();
}, []);

API

Request.make(config)

config

• url: string
• method: GET (default), POST, OPTIONS, PATCH, PUT or DELETE
• responseType:
  • text: (default) response will be a string
  • arraybuffer: response will be a ArrayBuffer
  • document: response will be Document
  • blob: response will be Blob
  • json: response will be a JSON value
• body: request body
• headers: a record containing the headers
• withCredentials: boolean
• onLoadStart: event triggered on load start
• onProgress: event triggered at different times when the payload is being sent
• timeout: number

emptyToError

Helper to use with mapOkToResult to consider empty response as an error.

badStatusToError

Helper to use with mapOkToResult to consider a status outside of the 200-299 range as an error.

License