# SmartRequest Architecture Hints

## Core Features

- supports http
- supports https
- supports unix sockets on Node.js, Bun, and Deno
- supports formData
- supports file uploads
- supports best practice keepAlive
- dedicated functions for working with JSON request/response cycles
- written in TypeScript
- continuously updated
- supports Node.js, Bun, Deno, and browser environments with automatic runtime detection
- runtime-specific implementations using native APIs (Node http/https, Bun fetch, Deno fetch with HttpClient, browser fetch)
- used in modules like @push.rocks/smartproxy and @api.global/typedrequest

## Architecture Overview (as of v4.x with Bun and Deno support)

- The project has a multi-layer architecture with runtime abstraction
- Base layer (ts/core_base/) contains abstract classes and unified types
- Node.js implementation (ts/core_node/) uses native http/https modules with unix socket support
- Bun implementation (ts/core_bun/) uses Bun's native fetch with unix socket support via `unix` option
- Deno implementation (ts/core_deno/) uses Deno's fetch with unix socket support via HttpClient proxy
- Browser implementation (ts/core_fetch/) uses standard Fetch API for browser compatibility
- Core module (ts/core/) uses @push.rocks/smartenv to detect runtime and dynamically load appropriate implementation
- Client API (ts/client/) provides a fluent, chainable interface that works across all runtimes
- Runtime detection order: Deno → Bun → Node.js → Browser (following smartenv detection best practices)

## 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 Bun Module (ts/core_bun/)

- `request.ts`: Bun implementation using native fetch with unix socket support
  - Uses Bun's `unix` fetch option for unix socket connections
  - Supports both `unix` and `socketPath` options (converts socketPath to unix)
  - Handles URL parsing for `http://unix:/path/to/socket:/http/path` format
  - Throws errors for Node.js specific options (agent)
- `response.ts`: Bun-based CoreResponse implementation
  - `stream()` returns native web ReadableStream from response.body
  - `streamNode()` throws error (Bun uses web streams; users should use stream() instead)
- `types.ts`: Extends base types with IBunRequestOptions including `unix` option

### Core Deno Module (ts/core_deno/)

- `request.ts`: Deno implementation using fetch with HttpClient proxy for unix sockets
  - Creates and caches Deno.HttpClient instances per socket path
  - Supports both explicit `client` option and automatic client creation from `socketPath`
  - HttpClient cache prevents creating multiple clients for same socket
  - Provides `clearClientCache()` static method for cleanup
  - Throws errors for Node.js specific options (agent)
- `response.ts`: Deno-based CoreResponse implementation
  - `stream()` returns native web ReadableStream from response.body
  - `streamNode()` throws error (Deno uses web streams, not Node.js streams)
- `types.ts`: Extends base types with IDenoRequestOptions including `client` option

### 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> across all platforms
- In Node.js, converts native streams to web streams
- `streamNode()` availability by runtime:
  - **Node.js**: Returns native Node.js ReadableStream (only runtime that supports this)
  - **Bun**: Throws error (use web streams via stream() instead)
  - **Deno**: Throws error (Deno uses web streams only)
  - **Browser**: Throws error (browsers use web streams only)
- Consistent API across platforms with web streams as the common denominator
- Only Node.js provides native Node.js streams via streamNode()

### 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
- Test file naming conventions:
  - `test.node.ts` - Node.js only tests
  - `test.bun.ts` - Bun only tests
  - `test.deno.ts` - Deno only tests
  - `test.node+bun+deno.ts` - Server-side runtime tests (all three)
  - `test.browser.ts` or `test.chrome.ts` - Browser tests
- Unix socket tests check for Docker socket availability and skip if not present
- Browser tests run in headless Chromium via puppeteer