initTLS() / destroyTLS()
Load the native library before the first request, and release it when you're done.
import { initTLS, destroyTLS } from "node-tls-client";
await initTLS();
// ... requests ...
await destroyTLS();initTLS(options?)
initTLS(options?: InitTLSOptions): Promise<void>Finds the native tls-client shared library for your platform, downloading it on first use, and loads it. Await it once before any request.
- Download location:
os.tmpdir(), orlibraryDir. The file is named after this package's version (e.g.tls-client-2.2.0-linux-amd64.so), so upgrading the package downloads it once more. - Failure: if the download fails but an older cached binary exists, that binary is used with a warning. Otherwise it rejects with a
TlsClientError; the process keeps running and you can callinitTLS()again. - Calling it again while initialized does nothing and warns that the new options are ignored. To change options, call
destroyTLS()first.
See Installation for platform support and installing the binary ahead of time.
InitTLSOptions
| Field | Type | Description |
|---|---|---|
binary? | NativeBinary | Which tls-client shared library to download:
- "upstream" (default): bogdanfinn/tls-client's official release.
Each request holds a libuv threadpool thread while it runs, so
requests in parallel are capped at UV_THREADPOOL_SIZE.
- "node-tls-client": our build of tls-client
(github.com/Sahil1337/tls-client), made from upstream's newest version
tag, which adds a completion queue: requests hold no thread, so every
request you start runs at once, like node-fetch. Memory grows with
requests in flight (roughly 50 KB each); to limit it, cap requests in
flight in your own code, as you would with node-fetch. This works on
the main thread; in a worker thread each request holds a threadpool
thread, as with "upstream", and a warning says so. Falls back to
"upstream", with a warning, when our release has no binary for this
platform or can't be downloaded.
The library is loaded once per process: after destroyTLS(), a
different binary takes effect only when the process restarts. |
concurrency? | number | Maximum number of native calls in flight at once (admission depth) — NOT
parallelism. Only for the "upstream" binary; node-tls-client's binary
runs every request at once, like node-fetch, and ignores it with a
warning. Real parallelism is the libuv threadpool, UV_THREADPOOL_SIZE
(this library sets it to cores×2 at import time when unset, except for
an ES module entry file on Node 20,
22.0–22.17 and 24.0–24.2, where you must set it in the environment; libuv
caps it at 1024; set UV_THREADPOOL_SIZE=4 to keep Node's default).
Default: that threadpool size. Values above it only queue, and every
in-flight call reserves ~256 KiB in koffi (committed memory on Windows).
Clamped to koffi's reported max_async_calls (4096 on koffi ≥ 2.15). |
libraryDir? | string | Directory the native shared library is downloaded to and loaded from;
relative paths resolve against the current working directory, and the
directory is created when missing. Default: os.tmpdir(). The file is
named after this package's version, so an upgrade downloads once and a
directory can be shared by several versions or processes. The library is
loaded once per process: after destroyTLS(), a different libraryDir
takes effect only when the process restarts. |
concurrency caps how many requests are in flight. Real parallelism comes from UV_THREADPOOL_SIZE; see Concurrency.
destroyTLS()
destroyTLS(): Promise<void>Stops accepting new requests, waits for in-flight ones to finish (each bounded by its own timeout), then clears every native session. Requests made afterwards reject with Client not initialized. Call initTLS() first. You can call initTLS() again afterwards.
Call it at shutdown so the process can exit cleanly. It rejects if the library was never initialized.
Native bindings
TlsNativeLibrary is the type of the promise-returning native bindings. You don't need it to use the library; it's exported for code that stubs the native layer in tests. IClient is its deprecated alias from 2.1.0.