Class CURL

CURL class - Represents a single HTTP request

Example

const { ConnPool, CURL } = import.meta.use('curl');

const pool = new ConnPool();
const curl = new CURL(pool);

// GET request
const res = await curl.setUrl('https://api.example.com/data')
                     .setHeaders({ 'Authorization': 'Bearer token' })
                     .perform();

// POST request
const postRes = await curl.setUrl('https://api.example.com/submit')
                        .setMethod('POST')
                        .setHeaders({ 'Content-Type': 'application/json' })
                        .setBody(JSON.stringify({ key: 'value' }))
                        .perform();

Constructors

constructor

new CURL(pool: ConnPool): CURL
Create new CURL instance
Parameters
- pool: ConnPool
  Connection pool (required)
Returns CURL

Methods

abort

abort(): void
Abort an in-flight asynchronous request.

Returns void

getHeaders

getHeaders(): string[]
Get the current request headers as an array of "Name: Value" strings.

Returns string[]

getInfo

getInfo(): RequestInfo
Get request statistics

Returns RequestInfo
RequestInfo Request statistics
getInfo(info: number): string | number | string[] | null
Get request statistics
Parameters
- info: number
Returns string | number | string[] | null
RequestInfo Request statistics

onData

onData(cb: (buf: ArrayBuffer) => boolean): void
Stream callback. Return true to abort reading.
Parameters
- cb: (buf: ArrayBuffer) => boolean
Returns void

onDebug

onDebug(
callback: ((type: number, data: ArrayBuffer) => void) | null | undefined,
): this
Observe libcurl debug events. Passing a function enables CURLOPT_VERBOSE internally but does not write verbose output to stderr. The data argument is raw bytes; HEADER_* events can be decoded as UTF-8, DATA_* and SSL_DATA_* may be binary.
Parameters
- callback: ((type: number, data: ArrayBuffer) => void) | null | undefined
Returns this

onHeader

onHeader(callback: HeaderCallback): this
Set header callback function
Parameters
- callback: HeaderCallback
  Header callback function
Returns this
Current CURL instance (supports chaining)

onHeadersComplete

onHeadersComplete(callback: (status: number, headers: string) => void): this
Set callback fired once when response headers are complete. Receives (status: number, headersRaw: string). Enables streaming: set this + onData to get body chunks before perform() resolves.
Parameters
- callback: (status: number, headers: string) => void
Returns this

onProgress

onProgress(callback: ProgressCallback): this
Set progress callback function
Parameters
- callback: ProgressCallback
  Progress callback function
Returns this
Current CURL instance (supports chaining)

pauseRecv

pauseRecv(): void
Pause receive stream

Returns void

perform

perform(): Promise<Response>
Execute HTTP request asynchronously

Returns Promise<Response>
Promise HTTP response

Throws
CURLException Throws on request failure

performSync

performSync(): Response
Execute HTTP request synchronously

Returns Response
Response HTTP response

Throws
CURLException Throws on request failure

reset

reset(): void
Reset CURL instance to initial state

Returns void

resumeRecv

resumeRecv(): void
Resume receive stream

Returns void

setAcceptEncoding

setAcceptEncoding(encoding?: string): this
Enable or set accepted compressed response encodings.
Parameters
- Optionalencoding: string
Returns this

setBasicAuth

setBasicAuth(username: string, password?: string): this
Set HTTP Basic authentication credentials.
Parameters
- username: string
- Optionalpassword: string
Returns this

setBearerToken

setBearerToken(token: string): this
Set bearer token authentication.
Parameters
- token: string
Returns this

setBody

setBody(body: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>): this
Set request body (for POST/PUT, etc.)
Parameters
- body: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>
  Request body string
Returns this
Current CURL instance (supports chaining)

setCABundle

setCABundle(path: string): this
Set CA certificate bundle path
Parameters
- path: string
  CA certificate file path
Returns this
Current CURL instance (supports chaining)

setConnectTimeout

setConnectTimeout(timeout: number): this
Set connection timeout (milliseconds)
Parameters
- timeout: number
  Connection timeout in milliseconds
Returns this
Current CURL instance (supports chaining)

setCookie

setCookie(cookie: string): this
Set cookie string
Parameters
- cookie: string
  Cookie string
Returns this
Current CURL instance (supports chaining)

setCookieFile

setCookieFile(path: string): this
Set cookie file path
Parameters
- path: string
  Cookie file path
Returns this
Current CURL instance (supports chaining)

setCookieJar

setCookieJar(path: string): this
Set cookie jar output path.
Parameters
- path: string
Returns this

setDNSServers

setDNSServers(servers: string): this
Set DNS server list (comma-separated)
Parameters
- servers: string
  DNS server list (e.g., "8.8.8.8,1.1.1.1")
Returns this
Current CURL instance (supports chaining)

setFollowRedirects

setFollowRedirects(follow: boolean): this
Set whether to follow redirects
Parameters
- follow: boolean
  Whether to follow redirects
Returns this
Current CURL instance (supports chaining)

setHeaders

setHeaders(headers: Record<string, string>): this
Set HTTP request headers
Parameters
- headers: Record<string, string>
  Headers object
Returns this
Current CURL instance (supports chaining)

setHTTPVersion

setHTTPVersion(version: "2" | "3" | "1.0" | "1.1" | "2.0" | "2TLS"): this
Set HTTP protocol version
Parameters
- version: "2" | "3" | "1.0" | "1.1" | "2.0" | "2TLS"
  HTTP version (1.0, 1.1, 2, 2TLS, 3)
Returns this
Current CURL instance (supports chaining)

setInterface

setInterface(interfaceName: string): this
Set network interface
Parameters
- interfaceName: string
  Network interface name or IP address
Returns this
Current CURL instance (supports chaining)

setKeepAlive

setKeepAlive(enabled: boolean, idle?: number, interval?: number): this
Enable TCP keepalive, optionally setting idle and interval seconds.
Parameters
- enabled: boolean
- Optionalidle: number
- Optionalinterval: number
Returns this

setLowSpeedLimit

setLowSpeedLimit(limit: number, time?: number): this
Abort transfers slower than limit bytes/sec for time seconds.
Parameters
- limit: number
- Optionaltime: number
Returns this

setMaxRedirects

setMaxRedirects(max: number): this
Set maximum redirect count
Parameters
- max: number
  Maximum redirects
Returns this
Current CURL instance (supports chaining)

setMethod

setMethod(method: string): this
Set HTTP method
Parameters
- method: string
  HTTP method (GET, POST, PUT, HEAD, DELETE, etc.)
Returns this
Current CURL instance (supports chaining)

setMimePost

setMimePost(parts: MimePart[]): this
Configure multipart/form-data POST parts.
Parameters
- parts: MimePart[]
Returns this

setOpt

setOpt(option: number, value: CurlOptionValue): this
Set a libcurl easy option by numeric id. Unsafe pointer options are rejected.
Parameters
- option: number
- value: CurlOptionValue
Returns this

setProxy

setProxy(
proxy: string,
type?: "http" | "https" | "socks4" | "socks4a" | "socks5" | "socks5h",
): this
Set proxy server
Parameters
- proxy: string
  Proxy server address (e.g., http://proxy.example.com:8080)
- Optionaltype: "http" | "https" | "socks4" | "socks4a" | "socks5" | "socks5h"
  Proxy type (http, https, socks4, socks5)
Returns this
Current CURL instance (supports chaining)

setRange

setRange(start: number, end?: number): this
Set request range (for resumable downloads)
Parameters
- start: number
  Start byte position
- Optionalend: number
  End byte position (optional, defaults to end of file)
Returns this
Current CURL instance (supports chaining)

setReferer

setReferer(referer: string): this
Set referer header
Parameters
- referer: string
  Referer value
Returns this
Current CURL instance (supports chaining)

setShare

setShare(share: Share): this
Attach a libcurl share handle for cookies, DNS, SSL sessions, and connections.
Parameters
- share: Share
Returns this

setSSLVerify

setSSLVerify(verifyPeer: boolean, verifyHost?: boolean): this
Set SSL/TLS verification
Parameters
- verifyPeer: boolean
  Whether to verify peer certificate
- OptionalverifyHost: boolean
  Whether to verify hostname (defaults to verifyPeer)
Returns this
Current CURL instance (supports chaining)

setStreamMode

setStreamMode(mode: boolean): void
Set streaming mode. Don't save body, trigger ondata instead
Parameters
- mode: boolean
  Streaming mode
Returns void

setTimeout

setTimeout(timeout: number): this
Set timeout (milliseconds)
Parameters
- timeout: number
  Timeout in milliseconds
Returns this
Current CURL instance (supports chaining)

setUploadData

setUploadData(
data: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>,
): this
Upload raw data using libcurl's read callback.
Parameters
- data: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>
Returns this

setUploadFile

setUploadFile(path: string): this
Upload a file path using libcurl's file reader.
Parameters
- path: string
Returns this

setUrl

setUrl(url: string): this
Set request URL
Parameters
- url: string
  Request URL
Returns this
Current CURL instance (supports chaining)

setUserAgent

setUserAgent(userAgent: string): this
Set user agent string
Parameters
- userAgent: string
  User agent string
Returns this
Current CURL instance (supports chaining)

setVerbose

setVerbose(verbose: boolean): this
Set whether to enable verbose output
Parameters
- verbose: boolean
  Whether to enable verbose output
Returns this
Current CURL instance (supports chaining)

Class CURL

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns CURL

Methods

abort

Returns void

getHeaders

Returns string[]

getInfo

Returns RequestInfo

Parameters

Returns string | number | string[] | null

onData

Parameters

Returns void

onDebug

Parameters

Returns this

onHeader

Parameters

Returns this

onHeadersComplete

Parameters

Returns this

onProgress

Parameters

Returns this

pauseRecv

Returns void

perform

Returns Promise<Response>

Throws

performSync

Returns Response

Throws

reset

Returns void

resumeRecv

Returns void

setAcceptEncoding

Parameters

Returns this

setBasicAuth

Parameters

Returns this

setBearerToken

Parameters

Returns this

setBody

Parameters

Returns this

setCABundle

Parameters

Returns this

setConnectTimeout

Parameters

Returns this

setCookie

Parameters

Returns this

setCookieFile

Parameters

Returns this

setCookieJar

Parameters

Returns this

setDNSServers

Parameters

Returns this

setFollowRedirects

Parameters

Returns this

setHeaders

Parameters