Fast way to send synchronous web requests in NodeJS. API is a subset of sync-request. Leverages node-libcurl for high performance. Cannot be used in a browser.
npm install sync-request-curl
---
Make synchronous web requests similar to sync-request, but up to 20 times more quickly.
Leverages node-libcurl for performance instead of spawning child processes like sync-request.
Designed to run on NodeJS. It will not work in a browser.
---
- 1. Installation
- 2. Usage
- 2.1. Method
- 2.2. URL
- 2.3. Options
- 2.4. Response
- 2.5. Errors
- 3. License
- 4. Compatibility
- 4.1. Windows
- 4.2. MacOS
- 4.3. Linux
- 5. Caveats
``
npm install sync-request-curl
Please refer to the compatibility section for known issues and workarounds for Windows, MacOS and Linux.
> [!TIP]
> Starting from sync-request-curl@3.2.0, you can replace JSON.parse(res.body.toString()) with res.getJSON().
Try with Replit.
`typescript`
request(method, url, options);
Examples (click to view)
GET request without options
`typescript
import request from 'sync-request-curl';
const res = request('GET', 'https://comp1531namesages.alwaysdata.net');
console.log('Status Code:', res.statusCode);
const jsonBody = JSON.parse(res.body.toString());
console.log('Returned JSON object:', jsonBody);
`
GET request with query string parameters
`typescript
import request from 'sync-request-curl';
const res = request('GET', 'https://comp1531forum.alwaysdata.net/echo/echo', {
qs: { message: 'Hello, world!' },
});
console.log('Status Code:', res.statusCode);
const jsonBody = JSON.parse(res.body.toString());
console.log('Returned JSON object:', jsonBody);
`
POST request with headers and JSON payload
`typescript
import request from 'sync-request-curl';
const res = 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:', res.statusCode);
const jsonBody = JSON.parse(res.body.toString());
console.log('Returned JSON Object:', jsonBody);
`
POST request for file upload using multipart/form-data
`typescript
import request from 'sync-request-curl';
const res = request('POST', 'https://example.com/upload', {
formData: [
{
name: 'example-file',
file: './path/to/file.txt',
type: 'text/plain',
},
{
name: 'example-content',
contents: 'Example Content!',
},
],
});
console.log('Status Code:', res.statusCode);
`
Using a proxy URL (Note: replace with your own proxy details)
`javascript
import request from 'sync-request-curl';
const res = request('GET', 'https://ipinfo.io/json', {
setEasyOptions: (curl, options) => {
curl.setOpt(options.PROXY, 'http://your-proxy-url:port');
curl.setOpt(options.PROXYUSERPWD, 'proxyUsername:proxyPassword');
},
});
console.log('Status Code:', res.statusCode);
const jsonBody = JSON.parse(res.body.toString());
console.log(jsonBody);
`
HTTP method (of type HttpVerb)
- e.g. PUT/POST/GET/DELETE
Note that for the HEAD method, CURLOPT_NOBODY is set to true automatically by sync-request-curl.
URL as a string
- e.g. https://toohak.fly.dev
| Option | Description | Example | Default |
|---|---|---|---|
| qs | An object containing query string parameters which will be appended to the URL. |
| undefined |
| headers | HTTP headers for the request. |
| undefined |
| json | Sets the body as a JSON representation of the value and automatically adds Content-type: application/json to the header. | { | undefined |
| body | String body for PATCH, POST and PUT requests. We recommended using json instead for JSON payloads, otherwise the Content-Type will need to be set manually. |
| undefined |
| formData | Array of HttpPostField from node-libcurl, used for file uploads with multipart/form-data. |
| undefined |
| timeout | Times out if no response is returned within the given number of milliseconds. | 2000 | 0(no timeout) |
| followRedirects | Sets whether redirects (status code 302) should be followed automatically. | false | true |
| maxRedirects | Sets the maximum number of redirects to follow before throwing an Error. | 3 | -1(no limit) |
| insecure | Set to true to send insecure requests. This can be useful on Windows which may have SSL issues (Libcurl code 60). | true | false |
| setEasyOptions | Optional callback to set additional curl options for the Easy Interface. This has priority over existing options. |
| undefined |
In src/types.ts, the Options interface following is defined as:
`typescript
export interface Options {
headers?: IncomingHttpHeaders;
qs?: { [key: string]: any };
// You should only specify one of these.
// They are processed in the order listed below.
//
// When no json, body or formdata is provided, Content-Length = 0
// will be set in the headers.
json?: any;
body?: string | Buffer;
formData?: HttpPostField[];
timeout?: number;
followRedirects?: boolean;
maxRedirects?: number;
insecure?: boolean;
setEasyOptions?: SetEasyOptionCallback;
}
`
- statusCode - a number representing the HTTP status code (e.g. 200, 400, 401, 403)headers
- - HTTP response headers. The keys/properties of the object will always be in lowercase, e.g. "content-type" instead of "Content-Type"
- - the final URL used in the request after all redirections are followed and all query string parameters appendedbody
- - a string or buffer - for JSON responses, use JSON.parse(response.body.toString()) to get the returned data as an objectgetBody
- - 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 insteadgetJSON
- - a function that returns the body parsed as JSON. An Error is thrown if the body cannot be parsed.
In src/types.ts, the Response interface is defined as:
`typescript`
export interface Response {
statusCode: number;
headers: IncomingHttpHeaders;
url: string;
body: string | Buffer;
getBody: (encoding?: BufferEncoding) => string | Buffer; // simplified
getJSON:
}
When using the response.getBody() function, a generic Error object is thrown.
If there are issues with the request, a CurlError will be thrown. This will contain a non-zero code property that corresponds to a specific Libcurl Error from this documentation:
- https://curl.se/libcurl/c/libcurl-errors.html
A few common errors are:
1. CURLE_COULDNT_CONNECT (7)
- Failed to connect() to host or proxy.
- HINT: This means that the server could not be reached. For local development (e.g. in testing), ensure that your server has started successfully, or that it did not crash while handling a previous request
1. CURLE_URL_MALFORMAT (3)
- The URL was not properly formatted.
- HINT: The request was not successful because your input URL is invalid, e.g. missing domain, protocol or port. Try printing out your input URL, or if it is a GET request, access it directly in a browser
1. CURLE_PEER_FAILED_VERIFICATION (60)
- The remote server's SSL certificate or SSH fingerprint was deemed not OK. This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its previous value was 51
- HINT: See the Windows compatibility section for an explanation and potential workaround
It is possible to check the Curl code as follows:
Example (click to view)
`typescript
import { CurlError } from 'sync-request-curl/errors';
import request from 'sync-request-curl';
try {
request('GET', 'https://google.fake.url.com');
} catch (error) {
if (error instanceof CurlError) {
// outputs 6 (CURLE_COULDNT_RESOLVE_HOST)
console.log(error.code);
}
}
`
In src/errors.ts, the CurlError class is defined as:
`typescriptCurlError code must be between 1 and 99. Given: ${code}
export class CurlError extends Error {
// https://curl.se/libcurl/c/libcurl-errors.html
code: number;
constructor(code: number, message: string) {
super(message);
if (code < 1 || code > 99) {
throw new Error(
);
}
this.code = code;
Object.setPrototypeOf(this, CurlError.prototype);
}
}
Massachusetts Institute of Technology (MIT)
`
Copyright (c) 2023 Khiet Tam Nguyen
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the “Software”),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
`
For installation issues, be sure to review the Windows Build Requirements from node-libcurl's documentation.
In addition, your requests may unexpectedly fail with a Libcurl Error (code 60, CURLE_PEER_FAILED_VERIFICATION) when using NodeJS natively on Windows.
The reason is covered in the below resources:
- https://github.com/JCMais/node-libcurl/issues/301
- https://stackoverflow.com/a/34883260/22324694
One quick workaround is to set the insecure option to true when sending your requests. This is the same as setting the Libcurl Easy's equivalent SSL_VERIFYPEER to 0, or using curl in the command line with the -k or --insecure` option.
Alternatively, consider using Windows Subsystem for Linux (WSL).
The build for MacOS may fail during the installation process.
In most cases, this can be fixed by following these Github issues:
- https://github.com/JCMais/node-libcurl/issues/296
- https://github.com/JCMais/node-libcurl/issues/382
and carefully reviewing the MacOS Build Requirements from node-libcurl's documentation. Otherwise, we recommend uninstalling this library and installing sync-request.
In rare cases, the build for distributions such as Debian or Ubuntu may fail. This is attributed to missing dependencies such as Python or Libcurl. Below are some related issues:
- https://github.com/JCMais/node-libcurl/issues/374
- https://github.com/JCMais/node-libcurl/issues/376
Be sure to also check the Linux Build Requirements from node-libcurl's documentation.
See sync-request for the original documentation. Please note that sync-request-curl only supports a subset of the original features in sync-request and additional features through leveraging node-libcurl.
sync-request-curl was developed to improve performance with sending synchronous requests in NodeJS. It is also free from the sync-request bug which leaves an orphaned sync-rpc process, resulting in a leaked handle being detected in Jest.
sync-request-curl was designed to work with UNIX-like systems for UNSW students enrolled in COMP1531 Software Engineering Fundamentals. It has been tested on Alpine, Arch, Debian and Ubuntu Linux and is compatible with Windows/MacOS.
Please note that this library's primary goal is to simplify the learning of JavaScript for novice programmers, hence its synchronous nature. However, we recommend to always use an asynchronous alternative where possible.