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<Uint8Array>
- 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