Nervously Proposing Marriage
Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

@space-labs/warp

1.0.0 • Public • Published

Warp

Warp is a Bucklescript library enabling http-requests over XHR.

If you find a bug or think some feature is missing, don't hesitate to file an issue or even a pull request.

Every little bit of help is very welcome!

Table of contents

How do I install it?

yarn add @space-labs/warp

or

npm install @space-labs/warp --save

Then add @space-labs/warp as a dependency to bsconfig.json:

"bs-dependencies": [
+  "@space-labs/warp"
]

API

Methods

Warp.Method.options("https://domain.com/");
Warp.Method.get("https://domain.com/");
Warp.Method.head("https://domain.com/");
Warp.Method.post("https://domain.com/");
Warp.Method.put("https://domain.com/");
Warp.Method.delete("https://domain.com/");
Warp.Method.trace("https://domain.com/");
Warp.Method.connect("https://domain.com/");

Settings

client->Warp.Settings.async(false);
client->Warp.Settings.timeout(5000);
client->Warp.Settings.withCredentials(true);
client->Warp.Settings.auth("user", "password");
client->Warp.Settings.overrideMimeType("text/plain");

Query Strings

client->Warp.QueryString.set([("key", "value"), ("key2", "value2")]);
client->Warp.QueryString.add("key", "value");
client->Warp.QueryString.remove("key");

Form Data

 client->Warp.FormData.set([("key", "value"), ("key2", "value2")]);
 client->Warp.FormData.add("key", "value");
 client->Warp.FormData.remove("key");

Headers

client->Warp.Header.set([("key", "value"), ("key2", "value2")]);
client->Warp.Header.add("key", "value");
client->Warp.Header.remove("key");

Events

onProgress

client->Warp.Event.onProgress(_event => {
  Js.Console.log("We are making progress!")
});

onLoad

The datatype of the response is based on the currently set ResponseType (option(string) by default).

client->Warp.Event.onLoad(response => {
  switch (response) {
  | Belt.Result.Ok(Some(data)) => Js.Console.log(data)
  | Belt.Result.Ok(None) => Js.Console.info("Response was empty")
  | Belt.Result.Error(message) => Js.Console.error(message)
  }
});

onLoadWithStatusCode

Same as onLoad but gets the requests statusCode as a second argument

client->Warp.Event.onLoadWithStatusCode((response, statusCode) => {
  switch (response) {
  | Belt.Result.Ok(Some(data)) => Js.Console.log2(data, statusCode)
  | Belt.Result.Ok(None) => Js.Console.info2("No Response!", statusCode)
  | Belt.Result.Error(message) => Js.Console.error2(message, statusCode)
  }
});

onAbort

client->Warp.Event.onAbort(() => {
  Js.Console.log("The request got aborted :(")
});

Response Types

If you want to change the ResponseType, you have to do it before the onLoad. If you set it afterwards, your onLoad will be removed (because it would assume a wrong type signature).

ResponseType PayloadType
Text option(string)
Json option(Js.Json.t)
Document option(Dom.document)
ArrayBuffer option(Js.Typed_array.ArrayBuffer.t)
client->Warp.ResponseType.setText; // default
client->Warp.ResponseType.setJson;
client->Warp.ResponseType.setDocument;
client->Warp.ResponseType.setArrayBuffer;

Sending a Request

client->Warp.send;

Cancelling Requests

Warp.send returns a function, with which you may cancel the current request. It has a signature of option(unit => unit), so you don't have to do anything when using it inside React.useEffect.

  /* React */
  React.useEffect(() => {
    Warp.Method.get("https://domain.com/")->Warp.send
  });
 
  /* Plain Reason */
  let maybeCancel = Warp.Method.get("https://domain.com/")->Warp.send;
  switch(maybeCancel) {
    | Some(cancel) => cancel();
    | None => ();
  };

Examples

Basic

Warp.Method.get("http://localhost:8081/")
->Warp.ResponseType.setJson
->Warp.QueryString.set([
    ("firstname", "Max"),
    ("lastname", "Mustermann"),
    ("username", "max"),
    ("email", "max@mustermann.de"),
  ])
->Warp.Header.add("authorization", "Bearer 123")
->Warp.Event.onLoad(response => {
    switch (response) {
    | Belt.Result.Ok(Some(data)) => Js.Console.log(data)
    | Belt.Result.Ok(None) => Js.Console.info("No Response!")
    | Belt.Result.Error(message) => Js.Console.error(message)
    }
  })
->Warp.send;

Sending JSON

let stringifiedJson =
  Js.Dict.fromList([
    ("query", Js.Json.string(operation.text)),
    ("variables", variables),
  ])
  ->Js.Json.object_
  ->Js.Json.stringify;
 
Warp.Method.post("http://localhost:8081/")
->Warp.ResponseType.setJson
->Warp.FormData.setJson(stringifiedJson)
->Warp.Header.add("authorization", "Bearer 123")
->Warp.Event.onLoad(response => {
    switch (response) {
    | Belt.Result.Ok(Some(data)) => Js.Console.log(data)
    | Belt.Result.Ok(None) => Js.Console.info("No Response!")
    | Belt.Result.Error(message) => Js.Console.error(message)
    }
  })
->Warp.send;

What state is it in?

  • Url
  • Methods
    • OPTIONS
    • GET
    • HEAD
    • POST
    • PUT
    • DELETE
    • TRACE
    • CONNECT
  • Headers
    • set
    • add
    • delete
  • Query Strings
    • set
    • add
    • delete
  • Form Data / Body
    • set
    • setJson
    • add
    • delete
  • Response Types
    • ArrayBuffer Js.Typed_array.ArrayBuffer.t
    • Blob
    • Document Dom.document
    • Json Js.Json.t
    • Text string
  • Events
    • onLoad
    • onLoadWithStatusCode
    • onProgress
    • onAbort
  • Settings
    • async
    • timeout
    • withCredentials
    • auth (username / password)
    • overrideMimeType
  • send
  • abort
  • upload
  • tests

Credits

Request - Simplified HTTP client for inspiration

@hgiraud on Discord had some nice suggestions regarding the API

Install

npm i @space-labs/warp

DownloadsWeekly Downloads

3

Version

1.0.0

License

MIT

Unpacked Size

30.3 kB

Total Files

27

Last publish

Collaborators

  • avatar