node-libcurl
Version:
The fastest http(s) client (and much more) for Node.js - Node.js bindings for libcurl
252 lines • 9.69 kB
TypeScript
/**
* Copyright (c) Jonathan Cardoso Machado. All Rights Reserved.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
import './moduleSetup';
import { Readable } from 'stream';
import { CurlOptionValueType } from './generated/CurlOption';
import { HeaderInfo } from './parseHeaders';
import { CurlyMimePart } from './CurlyMimeTypes';
/**
* Object the curly call resolves to.
*
* @public
*/
export interface CurlyResult<ResultData = any> {
/**
* Data will be the body of the requested URL
*/
data: ResultData;
/**
* Parsed headers
*
* See {@link HeaderInfo}
*/
headers: HeaderInfo[];
/**
* HTTP Status code for the last request
*/
statusCode: number;
}
declare const methods: readonly ["acl", "bind", "checkout", "connect", "copy", "delete", "get", "head", "link", "lock", "m-search", "merge", "mkactivity", "mkcalendar", "mkcol", "move", "notify", "options", "patch", "post", "propfind", "proppatch", "purge", "put", "rebind", "report", "search", "source", "subscribe", "trace", "unbind", "unlink", "unlock", "unsubscribe"];
type HttpMethod = (typeof methods)[number];
export type CurlyResponseBodyParser = (data: Buffer, header: HeaderInfo[]) => any;
export type CurlyResponseBodyParsersProperty = {
[key: string]: CurlyResponseBodyParser;
};
/**
* These are the options accepted by the {@link CurlyFunction | `CurlyFunction`} API.
*
* Most libcurl options are accepted as their specific name, like `PROXY_CAPATH`, or as a camel
* case version of that name, like `proxyCaPath`.
*
* Options specific to the `curly` API are prefixed with `curly`, like `curlyBaseUrl`.
*
* For quick navigation use the sidebar.
*/
export interface CurlyOptions extends CurlOptionValueType {
/**
* Set this to a callback function that should be used as the progress callback.
*
* This is the only reliable way to set the progress callback.
*
* @remarks
*
* This basically calls one of the following methods, depending on if any of the streams feature is being used or not:
* - If using streams: {@link Curl.setStreamProgressCallback | `Curl#setStreamProgressCallback`}
* - else: {@link Curl.setProgressCallback | `Curl#setProgressCallback`}
*/
curlyProgressCallback?: CurlOptionValueType['xferInfoFunction'];
/**
* If set to a function this will always be called
* for all requests, ignoring other response body parsers.
*
* This can also be set to `false`, which will disable the response parsing and will make
* the raw `Buffer` of the response to be returned.
*/
curlyResponseBodyParser?: CurlyResponseBodyParser | false;
/**
* Add more response body parsers, or overwrite existing ones.
*
* This object is merged with the {@link CurlyFunction.defaultResponseBodyParsers | `curly.defaultResponseBodyParsers`}
*/
curlyResponseBodyParsers?: CurlyResponseBodyParsersProperty;
/**
* If set, this value will always prefix the `URL` of the request.
*
* No special handling is done, so make sure you set the url correctly later on.
*/
curlyBaseUrl?: string;
/**
* If `true`, `curly` will lower case all headers before returning then.
*
* By default this is `false`.
*/
curlyLowerCaseHeaders?: boolean;
/**
* If `true`, `curly` will return the response data as a stream.
*
* The `curly` call will resolve as soon as the stream is available.
*
* When using this option, if an error is thrown in the internal {@link Curl | `Curl`} instance
* after the `curly` call has been resolved (it resolves as soon as the stream is available)
* it will cause the `error` event to be emitted on the stream itself, this way it's possible
* to handle these too, if necessary. The error object will inherit from the {@link CurlError | `CurlError`} class.
*
* Calling `destroy()` on the stream will always cause the `Curl` instance to emit the error event.
* Even if an error argument was not supplied to `stream.destroy()`.
*
* By default this is `false`.
*
* @remarks
*
* Make sure your libcurl version is greater than or equal 7.69.1.
* Versions older than that one are not reliable for streams usage.
*
* This basically enables the {@link CurlFeature.StreamResponse | `CurlFeature.StreamResponse`} feature
* flag in the internal {@link Curl | `Curl`} instance.
*/
curlyStreamResponse?: boolean;
/**
* This will set the `highWaterMark` option in the response stream, if `curlyStreamResponse` is `true`.
*
* @remarks
*
* This basically calls {@link Curl.setStreamResponseHighWaterMark | `Curl#setStreamResponseHighWaterMark`}
* method in the internal {@link Curl | `Curl`} instance.
*/
curlyStreamResponseHighWaterMark?: number;
/**
* If set, the contents of this stream will be uploaded to the server.
*
* Keep in mind that if you set this option you **SHOULD** not set
* `progressFunction` or `xferInfoFunction`, as these are used internally.
*
* If you need to set a progress callback, use the `curlyProgressCallback` option.
*
* If the stream set here is destroyed before libcurl finishes uploading it, the error
* `Curl upload stream was unexpectedly destroyed` (Code `42`) will be emitted in the
* internal {@link Curl | `Curl`} instance, and so will cause the curly call to be rejected with that error.
*
* If the stream was destroyed with a specific error, this error will be passed instead.
*
* By default this is not set.
*
* @remarks
*
* Make sure your libcurl version is greater than or equal 7.69.1.
* Versions older than that one are not reliable for streams usage.
*
* This basically calls {@link Curl.setUploadStream | `Curl#setUploadStream`}
* method in the internal {@link Curl | `Curl`} instance.
*/
curlyStreamUpload?: Readable | null;
/**
* Array of MIME parts to upload as multipart/form-data.
*
* This will automatically build a {@link CurlMime} structure internally and set
* it using the `MIMEPOST` option. For stream-based parts, the unpause callback
* is automatically generated, so you don't need to provide it.
*
* @remarks
*
* Requires libcurl 7.56.0 or later.
*
* @example
* Basic multipart upload:
* ```typescript
* await curly.post('https://httpbin.org/post', {
* curlyMimePost: [
* { type: 'data', name: 'username', data: 'john_doe' },
* { type: 'file', name: 'avatar', file: '/path/to/image.png', mimeType: 'image/png' }
* ]
* })
* ```
*
* @example
* With streams:
* ```typescript
* import { createReadStream } from 'fs'
*
* await curly.post('https://httpbin.org/post', {
* curlyMimePost: [
* { type: 'data', name: 'field', data: 'value' },
* {
* type: 'stream',
* name: 'document',
* stream: createReadStream('/path/to/file.txt'),
* size: 12345
* }
* ]
* })
* ```
*
* See {@link Easy.setMimePost | `Easy.setMimePost`} for more details.
*/
curlyMimePost?: CurlyMimePart[];
}
export interface CurlyHttpMethodCall {
/**
* **EXPERIMENTAL** This API can change between minor releases
*
* Async wrapper around the Curl class.
*
* The `curly.<field>` being used will be the HTTP verb sent.
*
* @typeParam ResultData You can use this to specify the type of the `data` property returned from this call.
*/
<ResultData = any>(url: string, options?: CurlyOptions): Promise<CurlyResult<ResultData>>;
}
type HttpMethodCalls = Record<HttpMethod, CurlyHttpMethodCall>;
/** @expand */
export interface CurlyFunction extends HttpMethodCalls {
/**
* **EXPERIMENTAL** This API can change between minor releases
*
* Async wrapper around the Curl class.
*
* It's also possible to request using a specific http verb
* directly by using `curl.<http-verb>(url: string, options?: CurlyOptions)`, like:
*
* ```js
* curly.get('https://www.google.com')
* ```
* @typeParam ResultData You can use this to specify the type of the `data` property returned from this call.
*/
<ResultData = any>(url: string, options?: CurlyOptions): Promise<CurlyResult<ResultData>>;
/**
* **EXPERIMENTAL** This API can change between minor releases
*
* This returns a new `curly` with the specified options set by default.
*/
create: (defaultOptions?: CurlyOptions) => CurlyFunction;
/**
* These are the default response body parsers to be used.
*
* By default there are parsers for the following:
*
* - application/json
* - text/*
* - *
*/
defaultResponseBodyParsers: CurlyResponseBodyParsersProperty;
/**
* Set the object pool limit for Curl instances.
*
* When set to 0 (default), pooling is disabled and Curl instances are created/destroyed on each request.
* When set to a positive number, that many Curl instances will be pre-created and reused.
*
* @param limit - Number of Curl instances to keep in the pool. 0 disables pooling.
*/
setObjectPoolLimit: (limit: number) => void;
}
/**
* Curly function
*
* @public
*/
export declare const curly: CurlyFunction;
export {};
//# sourceMappingURL=curly.d.ts.map