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

On MacOS, there may be an error in the installation process. In most cases can be fixed by following this GitHub issue.

2. Usage

request(method, url, options);

Examples (click to view)

GET request without options

import request from 'sync-request-curl';

const response = request('GET', 'https://comp1531quiz.alwaysdata.net');
console.log('Status Code:', response.statusCode);
const jsonBody = JSON.parse(response.body.toString());
console.log('Returned JSON object:', jsonBody);

GET request with query string parameters

import request from 'sync-request-curl';

const response = request(
  'GET',
  'https://comp1531forum.alwaysdata.net/echo/echo',
  {
    qs: { message: 'Hello, world!' },
  }
);
console.log('Status Code:', response.statusCode);
const jsonBody = JSON.parse(response.body.toString());
console.log('Returned JSON object:', jsonBody);

POST request with headers and JSON payload

import request from 'sync-request-curl';

const response = request(
  'POST',
  'https://comp1531quiz.alwaysdata.net/quiz/create',
  {
    headers: { lab08quizsecret: "bruno's fight club" },
    json: {
      quizTitle: 'New Quiz',
      quizSynopsis: 'Sync request curl example'
    },
  }
);
console.log('Status Code:', response.statusCode);
const jsonBody = JSON.parse(response.body.toString());
console.log('Returned JSON Object:', jsonBody);

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 statusCode >= 300, an Error is thrown instead.
• url - the final URL used in the request after all redirections and with the query string parameters appended.

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.