A high-performance Node.js wrapper for bogdanfinn/tls-client using Koffi bindings and worker thread pools.
Now with TypeScript Support.
- ⚡ Multi-threaded request handling via Piscina worker pools
- 🔄 Automatic session management and cookie handling
- 🛡️ Latest TLS fingerprint support (Chrome 146, Brave 146, Firefox 148, Safari iOS 26, etc.)
- 🔄 Built-in retry mechanism for failed requests
- 📚 Full TypeScript support and proper JSDocs for ESM and CJS support
- 🔌 Automatic TLS library download and management
npm install tlsclientwrapper
# or
pnpm add tlsclientwrapperpnpm blocks dependency build scripts by default. If koffi's native binding is missing after install, run
pnpm approve-buildsand allowkoffi.
TlsClientWrapper uses a two-tier architecture:
- ModuleClient: Manages the worker pool and TLS library | Important: Piscana seems to share the pools by default, meaning creating multiple ones wont change anything.
- SessionClient: Handles individual TLS sessions and requests
ModuleClient (Worker Pool)
├─ SessionClient 1
├─ SessionClient 2
└─ SessionClient N
Now TypeScript, ESM and CJS are supported.
import{ModuleClient,SessionClient}from'tlsclientwrapper';// 1. Create the worker pool managerconstmoduleClient=newModuleClient();// 2. Create a session for making requestsconstsession=newSessionClient(moduleClient);// 3. Make requestsconstresponse=awaitsession.get('https://example.com');// 4. Clean upawaitsession.destroySession();awaitmoduleClient.terminate();constmoduleClient=newModuleClient({maxThreads: 8,// Optimize thread count (more Threads = more concurrent Requests, test whats the best for you)});// Create multiple sessions for different purposesconstloginSession=newSessionClient(moduleClient,{defaultHeaders: {'User-Agent': 'Chrome/146.0.0.0'},});constapiSession=newSessionClient(moduleClient,{defaultHeaders: {Authorization: 'Bearer token'},});// Use sessions concurrentlyawaitPromise.all([loginSession.post('https://example.com/login',credentials),apiSession.get('https://example.com/api/data'),]);// Clean upawaitloginSession.destroySession();awaitapiSession.destroySession();awaitmoduleClient.terminate();constsession=newSessionClient(moduleClient,{// TLS ConfigurationtlsClientIdentifier: 'chrome_146',// Retry ConfigurationretryIsEnabled: true,retryMaxCount: 3,retryStatusCodes: [429,503,504],// Network ConfigurationtimeoutSeconds: 30,proxyUrl: 'http://proxy:8080',// Default Headers & CookiesdefaultHeaders: {'User-Agent': 'Custom/1.0',},defaultCookies: [{domain: 'example.com',name: 'session',value: 'xyz',},],});constmoduleClient=newModuleClient();constsession=newSessionClient(moduleClient);// Process multiple URLs efficientlyconsturls=Array.from({length: 100},(_,i)=>`https://api.example.com/item/${i}`);// Batch requests with concurrency controlconstbatchSize=10;for(leti=0;i<urls.length;i+=batchSize){constbatch=urls.slice(i,i+batchSize);constresponses=awaitPromise.all(batch.map((url)=>session.get(url)));console.log(`Processed batch ${i/batchSize+1}`);}awaitsession.destroySession();awaitmoduleClient.terminate();constmoduleClient=newModuleClient();// Monitor worker pool performancesetInterval(()=>{conststats=moduleClient.getPoolStats();console.log(stats);},5000);constsession=newSessionClient(moduleClient,{withDebug: true,// Enable debug logging});// ... your requests ...For detailed API documentation and type information, explore the source code or use an editor with TypeScript Intellisense support. All public classes and methods are fully typed and documented for easy discovery.
This wrapper requires:
- Node.js 20.x or later
- Platform supported by Koffi (Windows, macOS, Linux)
- x64, arm64, or compatible architecture
Special thanks to:
- @bogdanfinn for the TLS client
- The Koffi team for the FFI bindings