smartrequest/readme.hints.md

SmartRequest Architecture Hints

Core Features

• supports http
• supports https
• supports unix socks
• supports formData
• supports file uploads
• supports best practice keepAlive
• dedicated functions for working with JSON request/response cycles
• written in TypeScript
• continuously updated
• uses node native http and https modules
• used in modules like @push.rocks/smartproxy and @api.global/typedrequest

Architecture Overview (as of latest refactoring)

• The project is now structured with a clean separation between core functionality and API layers
• Core module (ts/core/) contains the essential HTTP request logic using Node.js http/https modules
• Core always returns raw streams - no parsing or body collection happens in the core request function
• Modern API (ts/modern/) provides a fluent, chainable interface with fetch-like Response objects
• Legacy API is maintained through a thin adapter layer for backward compatibility

Key Components

Core Module (ts/core/)

• request.ts: Core HTTP/HTTPS request logic with unix socket support and keep-alive agents
  • coreRequest() always returns a raw Node.js IncomingMessage stream
  • No response parsing or body collection happens here
• response.ts: SmartResponse class providing fetch-like API
  • Methods like json(), text(), arrayBuffer() handle all parsing and body collection
  • Response body is streamed and collected only when these methods are called
  • Body can only be consumed once (throws error on second attempt)
• types.ts: Core TypeScript interfaces and types
• plugins.ts: Centralized dependencies

Modern API

• SmartRequestClient: Fluent API with method chaining
• Returns SmartResponse objects with fetch-like methods
• Supports pagination, retries, timeouts, and various response types

Binary Request Handling

• Binary requests are handled correctly when responseType: 'binary' is set
• Response body is kept as Buffer without string conversion
• No automatic transformations applied to binary data

Legacy Compatibility

• All legacy functions (getJson, postJson, etc.) are maintained through adapter.ts
• Legacy API returns IExtendedIncomingMessage for backward compatibility
• Modern API can be accessed alongside legacy API

Testing

• Use pnpm test to run all tests
• Modern API tests use the new SmartResponse methods (response.json(), response.text())
• Legacy API tests continue to use the body property directly