@npy/fetch 0.1.2 → 0.1.4

package/README.md

@@ -1,111 +1,204 @@
 # @npy/fetch
 
-an http/1.1 client built over raw tcp sockets with a fetch-compatible api, per-origin connection pooling, and first-class proxy support.
+An HTTP/1.1 client built on raw TCP sockets with a fetch-compatible API, per-origin connection pooling, and first-class proxy support.
 
 > [!NOTE]
-> node and bun only — does not work in the browser.
+> Node.js and Bun only — does not work in the browser.
+
+## Install
 
-## install
 ```sh
 bun add @npy/fetch
-# or
 npm install @npy/fetch
 ```
 
-## usage
+## Usage
+
+### Simple fetch
 
-### simple fetch
 ```ts
 import { fetch } from '@npy/fetch'
 
-const response = await fetch('https://httpbin.org/anything')
-const body = await response.json()
-console.log(body)
+const response = await fetch('https://httpbin.org/get')
+const data = await response.json()
+console.log(data)
 
-fetch.close()
+await fetch.close()
 ```
 
-### with http/s proxy
-```ts
-import { createFetch, HttpClient } from '@npy/fetch'
-import { ProxyDialer } from '@npy/fetch/dialers'
+### With proxy
 
-const fetch = createFetch(new HttpClient({
-    dialer: new ProxyDialer('http://user:pass@proxy.example.com:8080'),
-}))
+Pass a proxy URL directly to the fetch options:
 
-const response = await fetch('https://httpbin.org/ip')
+```ts
+import { fetch } from '@npy/fetch'
+
+const response = await fetch('https://httpbin.org/ip', {
+    proxy: 'http://user:password@proxy.example.com:8080'
+})
 console.log(await response.json())
 
-fetch.close()
+await fetch.close()
 ```
 
-### with socks proxy
+Supports HTTP, HTTPS, and SOCKS5 proxies:
+
 ```ts
-import { createFetch, HttpClient } from '@npy/fetch'
-import { ProxyDialer } from '@npy/fetch/dialers'
+// SOCKS5
+await fetch('https://example.com', {
+    proxy: 'socks5://user:password@proxy.example.com:1080'
+})
+```
 
-const fetch = createFetch(new HttpClient({
-    dialer: new ProxyDialer('socks5://user:pass@proxy.example.com:1080'),
-}))
+### POST request
 
-const response = await fetch('https://httpbin.org/ip')
+```ts
+import { fetch } from '@npy/fetch'
+
+const response = await fetch('https://httpbin.org/post', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ hello: 'world' })
+})
 console.log(await response.json())
 
-fetch.close()
+await fetch.close()
 ```
 
-### custom i/o options
+### Custom HTTP client
+
+For fine-grained control over connection pooling and I/O:
+
 ```ts
 import { HttpClient } from '@npy/fetch'
 
 const client = new HttpClient({
-    poolMaxPerHost: 10,
-    poolMaxIdlePerHost: 5,
-    poolIdleTimeout: 30_000,
+    poolMaxPerHost: 32,
+    poolMaxIdlePerHost: 8,
     connect: {
         keepAlive: true,
         noDelay: true,
-        timeout: 5_000,
     },
     io: {
         reader: {
             bufferSize: 32 * 1024,
-            highWaterMark: 16 * 1024,
-            maxHeaderSize: 16 * 1024,
-            maxBodySize: '10mb',
+            maxHeaderSize: 64 * 1024,
+            maxBodySize: '50mb',
             decompress: true,
         },
         writer: {
-            highWaterMark: 16 * 1024,
-            coalesceBodyMaxBytes: 64 * 1024,
+            writeBufferSize: 16 * 1024,
+            directWriteThreshold: 64 * 1024,
         },
     },
 })
 
-const response = await client.send({ url: 'https://httpbin.org/anything', method: 'GET' })
-console.log(await response.json())
+const response = await client.send({
+    url: 'https://httpbin.org/post',
+    method: 'POST',
+    headers: new Headers({ 'content-type': 'application/json' }),
+    body: JSON.stringify({ data: 'example' }),
+})
 
+console.log(await response.json())
 await client.close()
 ```
 
-### using `HttpClient` directly
-```ts
-import { HttpClient } from '@npy/fetch'
+### With ProxyDialer
 
-const client = new HttpClient()
+Use `ProxyDialer` for explicit proxy configuration with custom HTTP client:
 
-const response = await client.send({
-    url: 'https://httpbin.org/post',
-    method: 'POST',
-    headers: new Headers({ 'content-type': 'application/json' }),
-    body: JSON.stringify({ hello: 'world' }),
+```ts
+import { createFetch, HttpClient } from '@npy/fetch'
+import { ProxyDialer } from '@npy/fetch/dialers'
+
+const client = new HttpClient({
+    dialer: new ProxyDialer('http://user:password@proxy.example.com:8080'),
+    poolMaxPerHost: 16,
+    poolMaxIdlePerHost: 4,
 })
 
+const fetch = createFetch(client)
+const response = await fetch('https://httpbin.org/ip')
 console.log(await response.json())
+
 await client.close()
 ```
 
----
+Supports all proxy protocols:
+
+```ts
+// HTTP proxy
+new ProxyDialer('http://proxy.example.com:8080')
+
+// HTTPS proxy
+new ProxyDialer('https://proxy.example.com:8443')
+
+// SOCKS5 proxy
+new ProxyDialer('socks5://proxy.example.com:1080')
+
+// With authentication
+new ProxyDialer('socks5://user:password@proxy.example.com:1080')
+```
+
+## API
+
+### `fetch(input, init?)`
+
+Standard Fetch API with additional options:
+
+- `proxy?: string | ProxyInfo | null` — Proxy URL (http, https, socks5)
+- `client?: HttpClient` — Custom HTTP client instance
+
+### `HttpClient` options
+
+**Pool:**
+
+- `poolMaxPerHost` (default: `10`)
+- `poolMaxIdlePerHost` (default: `5`)
+- `poolIdleTimeout` (default: `30000` ms)
+
+**Connection:**
+
+- `connect.timeout` (default: `5000` ms)
+- `connect.keepAlive` (default: `true`)
+- `connect.noDelay` (default: `true`)
+
+**Reader:**
+
+- `io.reader.bufferSize` — Internal buffer size
+- `io.reader.readChunkSize` — Chunk read size
+- `io.reader.maxHeaderSize` — Maximum header size
+- `io.reader.maxBodySize` — Maximum body size
+- `io.reader.maxLineSize` — Maximum line size
+- `io.reader.maxBufferedBytes` — Max buffered before processing
+- `io.reader.decompress` (default: `true`) — Auto-decompress gzip/deflate
+
+**Writer:**
+
+- `io.writer.writeBufferSize` — Write buffer size
+- `io.writer.directWriteThreshold` — Direct write threshold
+- `io.writer.coalesceBodyMaxBytes` — Coalesce writes up to this size
+
+## Environment Variables
+
+The library respects standard proxy environment variables:
+
+- `HTTP_PROXY` — HTTP proxy URL
+- `HTTPS_PROXY` — HTTPS proxy URL
+- `SOCKS5_PROXY` — SOCKS5 proxy URL
+- `SOCKS_PROXY` — Alternative SOCKS proxy URL
+
+These are used when no explicit proxy is configured.
+
+## Limitations
+
+- **HTTP/1.1 only** — Does not support HTTP/2 or HTTP/3
+- **Node.js and Bun** — Browser environments are not supported
+- **Limited to standard HTTP methods** — GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
+
+## License
+
+MIT License © 2026 matheus fernandes
 
-based on [deno-simple-fetch](https://github.com/esroyo/deno-simple-fetch).
+Based on [deno-simple-fetch](https://github.com/esroyo/deno-simple-fetch).

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@npy/fetch",
     "type": "module",
-    "version": "0.1.2",
+    "version": "0.1.4",
     "description": "HTTP/1.1 client built from raw TCP sockets with fetch-compatible primitives and proxy support.",
     "license": "MIT",
     "keywords": [