90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# 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
|