node-libcurl
Version:
The fastest http(s) client (and much more) for Node.js - Node.js bindings for libcurl
200 lines • 8.87 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 { MultiOptionName } from './generated/MultiOption';
import { CurlMultiCode, CurlCode } from './enum/CurlCode';
import { CurlPipe } from './enum/CurlPipe';
import { CurlPush } from './enum/CurlPush';
import { Http2PushFrameHeaders } from './types/Http2PushFrameHeaders';
import { Easy } from './Easy';
type SpecificOptions = 'PIPELINING';
/**
* Options for constructing a new Multi instance.
*
* @public
*/
export interface MultiOptions {
/**
* Enable libcurl's notification API for better performance.
*
* @remarks
* When enabled, this uses libcurl's notification callback system (available in libcurl >= 8.17.0)
* instead of polling for messages. This can improve performance by 50-100% for short transfers,
* especially when handling many connections.
*
* The notification API works by having libcurl call a callback when transfer events occur,
* eliminating the need to call `curl_multi_info_read()` after every operation.
*
* **Behavior:**
* - If `true` and libcurl >= 8.17.0 is available: Uses notification API
* - If `true` and libcurl < 8.17.0: Falls back to polling (no error, debug log only)
* - If `false` or not specified: Uses traditional polling approach
* - When compiled against libcurl < 8.17.0: Always falls back to polling
*
* **Defaults:**
* - `true` when compiled against libcurl >= 8.17.0
* - `false` when compiled against libcurl < 8.17.0
*
* @defaultValue `true` (if compiled with libcurl >= 8.17.0), `false` otherwise
*
* @see {@link https://curl.se/libcurl/c/curl_multi_notify_enable.html | curl_multi_notify_enable()}
* @see {@link https://curl.se/libcurl/c/CURLMOPT_NOTIFYFUNCTION.html | CURLMOPT_NOTIFYFUNCTION}
* @see {@link https://eissing.org/icing/posts/curl-notifications/ | Curl Notifications Blog Post}
*
* @since 5.0.0
*/
shouldUseNotificationsApi?: boolean;
}
/**
* `Multi` class that acts as an wrapper around the native libcurl multi handle.
* > [C++ source code](https://github.com/JCMais/node-libcurl/blob/master/src/Multi.cc)
*
* Using this class instead of just the {@link Easy | Easy} allows one to run requests asynchronously.
*
* For usage see [examples/04-multi.js](https://github.com/JCMais/node-libcurl/blob/master/examples/04-multi.js)
*
* The {@link Curl | Curl} class uses one of this internally to provide asynchronous usage of the library.
*
* @public
*/
declare class Multi {
/**
* Creates a new Multi instance.
*
* @param options - Optional configuration for the Multi instance
*
* @example
* ```typescript
* // Use default settings (notifications enabled if libcurl >= 8.17.0)
* const multi = new Multi()
*
* // Explicitly enable notifications (recommended for libcurl >= 8.17.0)
* const multiWithNotifications = new Multi({ shouldUseNotificationsApi: true })
*
* // Use traditional polling (compatible with all libcurl versions)
* const multiWithPolling = new Multi({ shouldUseNotificationsApi: false })
* ```
*/
constructor(options?: MultiOptions);
/**
* Sets the [`PIPELINING`](https://curl.haxx.se/libcurl/c/CURLMOPT_PIPELINING.html) option.
*
* Official libcurl documentation: [`curl_multi_setopt()`](http://curl.haxx.se/libcurl/c/curl_multi_setopt.html)
*/
setOpt(option: 'PIPELINING', value: CurlPipe): CurlMultiCode;
/**
* Sets the [`PUSHFUNCTION`](https://curl.haxx.se/libcurl/c/CURLMOPT_PUSHFUNCTION.html) option.
*
* @remarks
* You **must** not use the {@link Http2PushFrameHeaders | `Http2PushFrameHeaders`} object outside
* of this callback, doing so will try to use memory that libcurl has already
* freed and, in the best case scenario, will cause a segmentation fault.
*
* In case you have denied the push, you **must** also not use the `duplicatedHandle`
* outside of this callback, as libcurl would already have closed it and you would
* try to access memory that has been freed.
*
* Errors thrown inside this callback will have the same effect than returning `CurlPush.Deny`.
*
* Per a libcurl limitation, there is no direct way to cancel the connection from inside
* this callback, a possible workaround is to return an error
* from another callback, like the progress one.
*
* Official libcurl documentation: [`curl_multi_setopt()`](http://curl.haxx.se/libcurl/c/curl_multi_setopt.html)
*/
setOpt(option: 'PUSHFUNCTION', value: (parent: Easy, duplicatedHandle: Easy, pushFrameHeaders: Http2PushFrameHeaders) => CurlPush): CurlMultiCode;
/**
* Sets options on this instance.
*
* Use {@link Curl.option | `Curl.option`} for predefined constants.
*
* Official libcurl documentation: [`curl_multi_setopt()`](http://curl.haxx.se/libcurl/c/curl_multi_setopt.html)
*/
setOpt(option: Exclude<MultiOptionName, SpecificOptions>, value: number): CurlMultiCode;
/**
* Adds an {@link Easy | `Easy`} handle to be managed by this instance.
*
* The request will start right after calling this method.
*
* Official libcurl documentation: [`curl_multi_add_handle()`](http://curl.haxx.se/libcurl/c/curl_multi_add_handle.html)
*
* @deprecated This will be eventually removed in favor of just using {@link Multi.perform | `perform`} to add handles to the multi handle.
*
*/
addHandle(handle: Easy): CurlMultiCode;
/**
* Removes an {@link Easy | `Easy`} handle that was inside this instance.
*
* Official libcurl documentation: [`curl_multi_remove_handle()`](http://curl.haxx.se/libcurl/c/curl_multi_remove_handle.html)
*
* Notice, removing a handle that is being performed will result in the original promise returned by {@link Multi.perform | `perform`} being rejected.
*/
removeHandle(handle: Easy): CurlMultiCode;
/**
* Adds an {@link Easy | `Easy`} handle to this Multi instance and returns a promise
* that resolves when the request completes successfully, or rejects with a CurlError if it fails.
*
* This is the modern, promise-based alternative to using {@link Multi.addHandle | `addHandle`}
* with {@link Multi.onMessage | `onMessage`}.
*
* The returned promise will:
* - Resolve with the Easy handle when the request completes successfully
* - Reject with a CurlError (containing a `code` property with the CurlCode value) on failure
*
* @param handle - The Easy handle to perform the request with
* @returns A promise that resolves with the Easy handle or rejects with a CurlError
*
* @example
* ```ts
* const multi = new Multi()
* const easy = new Easy()
* easy.setOpt('URL', 'https://example.com')
*
* try {
* await multi.perform(easy)
* console.log('Request completed successfully')
* } catch (error) {
* console.error('Request failed with code:', error.code)
* }
* ```
*
* This does what [`curl_multi_add_handle()`](http://curl.haxx.se/libcurl/c/curl_multi_add_handle.html) does.
*/
perform(handle: Easy): Promise<Easy>;
/**
* Allow to provide a callback that will be called when there are
* new information about the handles inside this instance.
*
* This is basically an abstraction over [`curl_multi_info_read()`](http://curl.haxx.se/libcurl/c/curl_multi_info_read.html)
*
* Pass `null` to remove the current callback set.
*
* @deprecated This will be eventually removed in favor of just using {@link Multi.perform | `perform`} to add handles to the multi handle, instead
* of using {@link Multi.addHandle | `addHandle`}.
*/
onMessage(cb: ((error: Error, easyHandle: Easy, errorCode: CurlCode) => void) | null): this;
/**
* Returns the number of {@link Easy | 'Easy'} handles that are currently inside this instance
*/
getCount(): number;
/**
* Closes this multi handle.
*
* After the handle has been closed it must not be used again.
*
* This is basically the same than [`curl_multi_cleanup()`](http://curl.haxx.se/libcurl/c/curl_multi_cleanup.html)
*/
close(): void;
/**
* Returns a description for the given error code.
*
* Official libcurl documentation: [`curl_multi_strerror()`](http://curl.haxx.se/libcurl/c/curl_multi_strerror.html)
*/
strError(errorCode: CurlMultiCode): string;
}
export { Multi };
//# sourceMappingURL=Multi.d.ts.map