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
• supports both Node.js and browser environments
• used in modules like @push.rocks/smartproxy and @api.global/typedrequest

Architecture Overview (as of v3.0.0 major refactoring)

• The project now has a multi-layer architecture with platform abstraction
• Base layer (ts/core_base/) contains abstract classes and unified types
• Node.js implementation (ts/core_node/) uses native http/https modules
• Fetch implementation (ts/core_fetch/) uses Fetch API for browser compatibility
• Core module (ts/core/) dynamically selects the appropriate implementation based on environment
• Client API (ts/client/) provides a fluent, chainable interface
• Legacy API has been completely removed in v3.0.0

Key Components

Core Base Module (ts/core_base/)

• request.ts: Abstract CoreRequest class defining the request interface
• response.ts: Abstract CoreResponse class with fetch-like API
  • Defines stream() method that always returns web-style ReadableStream
  • Body can only be consumed once (throws error on second attempt)
• types.ts: Unified TypeScript interfaces and types
  • Single ICoreRequestOptions interface for all implementations
  • Implementations handle unsupported options by throwing errors

Core Node Module (ts/core_node/)

• request.ts: Node.js implementation using http/https modules
  • Supports unix socket connections and keep-alive agents
  • Converts Node.js specific options from unified interface
• response.ts: Node.js CoreResponse implementation
  • stream() method converts Node.js stream to web ReadableStream
  • streamNode() method returns native Node.js stream
  • Methods like json(), text(), arrayBuffer() handle parsing

Core Fetch Module (ts/core_fetch/)

• request.ts: Fetch API implementation for browsers
  • Throws errors for Node.js specific options (agent, socketPath)
  • Native support for CORS, credentials, and other browser features
• response.ts: Fetch-based CoreResponse implementation
  • stream() returns native web ReadableStream from response.body
  • streamNode() throws error explaining it's not available in browser

Core Module (ts/core/)

• Dynamically loads appropriate implementation based on environment
• Uses @push.rocks/smartenv for environment detection
• Exports unified types from core_base

Client API (ts/client/)

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

Stream Handling

• stream() method always returns web-style ReadableStream
• In Node.js, converts native streams to web streams
• streamNode() available only in Node.js environment for native streams
• Consistent API across platforms while preserving platform-specific capabilities

Binary Request Handling

• Binary requests handled through ArrayBuffer API
• Response body kept as Buffer/ArrayBuffer without string conversion
• No automatic transformations applied to binary data

Testing

• Use pnpm test to run all tests
• Tests use @git.zone/tstest/tapbundle for assertions
• Separate test files for Node.js (test.node.ts) and browser (test.browser.ts)
• Browser tests run in headless Chromium via puppeteer