swan-io
@swan-io/request
Wrapper for fetch with better data-structures
Installation
$ yarn add @swan-io/request @swan-io/boxed
# --- or ---
$ npm install --save @swan-io/request @swan-io/boxedDesign principles
- Has a strong contract with data-structures from Boxed (
Future,Result&Option) - Makes the request easily cancellable with
FutureAPI - Gives freedom of interpretation for response status
- Handles timeouts
- Types the response using the provided
type
Getting started
import { Request, badStatusToError, emptyToError } from "@swan-io/request";
// Regular case
Request.make({ url: "/api/health", type: "text" }).onResolve(console.log);
// Result.Ok({status: 200, ok: true, response: Option.Some("{\"ok\":true}")})
// Timeout
Request.make({ url: "/api/health", type: "text", timeout: 2000 }).onResolve(
console.log,
);
// Result.Error(TimeoutError)
// Network error
Request.make({ url: "/api/health", type: "text" }).onResolve(console.log);
// Result.Error(NetworkError)
// Custom response type
Request.make({ url: "/api/health", type: "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", type: "text" })
.mapOkToResult(emptyToError)
.onResolve(console.log);
// Result.Error(EmptyResponseError)
// Handle bad status as an error
Request.make({ url: "/api/health", type: "text" })
.mapOkToResult(badStatusToError)
.onResolve(console.log);
// Result.Error(BadStatusError)
// Cancel request
useEffect(() => {
const future = Request.make({ url: "/api/health", type: "text" });
return () => future.cancel();
}, []);API
Request.make(config)
config
url: stringmethod:GET(default),POST,OPTIONS,PATCH,PUTorDELETEtype:text: (default) response will be astringarraybuffer: response will be aArrayBufferblob: response will beBlobjson: response will be a JSON value
body: request bodyheaders: a record containing the headerscreatials:omit,same-originorincludetimeout: number
Return value
Returns a Future<Result<Response<T>, NetworkError | TimeoutError>>, where Response<T> has the following properties:
status:numberok:booleanresponse:Option<T>url:string
T is the type associated with the responseType provided in the config object.
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.