A lightweight library for promise-based http requests with node.js
npm install rystThe example code in this README will be written in typescript.
request(). As the name entails, it will send an http-request to a server.This method takes three arguments:
* url, which can either be a URL instance or a string
* options, which will be covered in more detail shortly
* cb, a callback function which will be passed an IncomingMessage instance, just like in node's built-in package.
The method will return a ryst.Request, whose properties will also be covered later, but which contains all properties
of the http.ClientRequest-class from the http package.
options argument is very similar to the options that can be passed as the first parameter of https.request();URL-object passed as the first parameter:host*hostname*path*port*protocol*auth*In addition, it contains the following new properties:
* data, which can be passed a string, a buffer, or an object that will be encoded as JSON; this will be sent as the request's content.
* encoding, the text encoding of the message's content; by default utf-8.
* dataWriteCallback, a callback that is called when data is written to the request, being given an error as an argument if one occured. The same that would be passed to http.ClientRequest.prototype.write.
ryst.request(), except that the method is predetermined and can't be set in the options:ryst.get(), which sends a get requestryst.post(), which sends a post requestryst.head(), which sends a head request``typescript
import * as ryst from "ryst";
const req = ryst.post("https://some.server.com", {
headers: {
"Content-Type": "application/json"
},
data: {
property: "value",
anotherProperty: 2
}
});
`
object can be handled in two ways: either using Promises, or almost exactly like a http.ClientRequest. You can also use a mixture of both.$3
When using ryst.Request using Promises, the ryst.Request object itself can be treated like a promise returning a ryst.Response object.With this method, logging the html of the google homepage might look something like this:
`typescript
import * as ryst from "ryst";// Using normal promise functions
const req = ryst.get("https://www.google.com");
req.then(res => console.log(res.data));
// using async/await (only within asynchronous functions):
const res = await ryst.get("https://www.google.com");
console.log(res.data);
`$3
When using ryst.Request like a http.ClientRequest, response data is obtained by using event listeners. For conveniences sake,
ryst.Request emits an event that http.ClientRequest doesn't, which is the data event. It will be emitted exactly once when
the response data has been entirely recieved, and passed a ryst.Response object as a parameter, which will be explained in detail shortly.It is also possible to write headers and data to the request using
setHeader() and write() respectively, as well as other such methods
inherited from http.ClientRequest.Note that using this method, it is necessary to close the request manually using the
end() method.With this method, logging the html of the google homepage might look something like this:
`typescript
import * as ryst from "ryst";const req = ryst.get("https://www.google.com");
req.on("data", res => console.log(res.data))
req.end();
`$3
It is of course possible to mix the two methods, for example using write() to write content to the request or setHeader() to write
headers, and then using await to get the response. You can also use event listeners on requests while also treating them as a promise.
The only caveat here is that awaiting a request or calling then() on it has the same effect of calling end(); at that moment the request will be sent and it is no longer possible to alter it.As an example, you could set request headers this way instead of using the options parameter:
`typescript
const req = ryst.get("https://www.google.com");
req.setHeader("Accept", "text/html");
const res = await req;
console.log(res.data);
`The Response Object
The response object contains two properties; message, which is an instance of IncomingMessage, containing meta data for the response such as headers
and the status code, and data, which is the response data. It also has the json()` method, which automatically parses the data as json and returns