sync-request-curl

sync-request-curl

Make synchronous web requests similar to sync-request, but 20 times more quickly.

Leverages node-libcurl for performance as opposed to spawning child processes like sync-request.

This library was designed to run on NodeJS. It cannot be used in a browser.

• 1. Installation
• 2. Usage
  • 2.1. Method
  • 2.2. URL
  • 2.3. Options
  • 2.4. Response
• 3. License
• 4. Caveats

1. Installation

npm install sync-request-curl

2. Usage

request(method, url, options);

e.g.

import request from 'sync-request-curl';

const response = request(
  'GET',
  'https://comp1531forum.alwaysdata.net/echo/echo',
  {
    qs: { message: 'Hello, world!' }
  }
);

console.log(response.statusCode)
console.log(response.body.toString());

See sync-request for the original documentation.

Please note that this library only supports a subset of the original features, which are summarised below.

2.1. Method

HTTP method (of type HttpVerb)

e.g. PUT/POST/GET/DELETE.

2.2. URL

URL as a string

e.g. https://toohak.fly.dev

2.3. Options

Only the following subset of options is supported for the time being:

Option	Description	Example
qs	An object containing query string parameters which will be appended to the URL.	{ message: 'Hello, world!' }
headers	HTTP headers for the request.	{ token: 'abcdefg' }
json	Sets the body as a JSON representation of the value and automatically adds Content-type: application/json to the header.	{ email: '[e-mail]', password: 'comp1531' }
body	Body for POST and PUT requests. We recommended using json instead for JSON payloads, otherwise the Content-Type will need to be set manually.	JSON.stringify({ email: '[e-mail]', password: 'comp1531' })
timeout	Times out if no response is returned within the given number of milliseconds	2000
followRedirects	Defaults to true, but can be set to false to not follow any redirects (302) automatically	false
maxRedirects	Sets the maximum number of redirects to follow before throwing an Error. Defaults to NumberMAX_SAFE_INTEGER.	3

In src/types.ts, the following is defined:

export interface Options {
  headers?: IncomingHttpHeaders;
  qs?: {
    [key: string]: any;
  };
  json?: any;
  timeout?: number;
  body?: string | Buffer | NodeJS.ReadableStream;
  followRedirects?: boolean;
  maxRedirects?: number;
}

2.4. Response

• statusCode - a number representing the HTTP status code (e.g. 200, 400, 401, 403)
• headers - HTTP response headers
• body - a string or buffer - use body.toString() for common use cases in combination with JSON.parse()
• getBody - a function with an optional encoding argument that returns the body if encoding is undefined, otherwise body.toString(encoding). If the statusCode >= 300, an Error is thrown instead.
• url - the final URL with query string parameters appended and if any redirection occurred.

In src/types.ts, the following is defined:

export interface Response {
  statusCode: number;
  headers: IncomingHttpHeaders;
  body: string | Buffer;
  getBody: (encoding?: BufferEncoding) => string | Buffer; // simplified
  url: string;
}

3. License

MIT

4. Caveats

This library was developed mainly to improve performance with sending synchronous requests in NodeJS.

It was designed to work with UNIX-like systems for UNSW students enrolled in COMP1531 Software Engineering Fundamentals.

Tested to be working on Arch & Debian Linux. Since node-libcurl is the core of this module, it is likely also compatible with other operating systems such as MacOS and Windows.