@npy/fetch 0.1.1 → 0.1.3

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/bun.lock

@@ -0,0 +1,68 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@npy/fetch",
+      "dependencies": {
+        "@fuman/io": "^0.0.19",
+        "@fuman/net": "^0.0.19",
+        "@fuman/node": "^0.0.19",
+        "@fuman/utils": "^0.0.19",
+        "bytes": "^3.1.2",
+        "generic-pool": "^3.9.0",
+      },
+      "devDependencies": {
+        "@biomejs/biome": "2.4.9",
+        "@types/bun": "latest",
+        "@types/bytes": "^3.1.5",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.4.9", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.9", "@biomejs/cli-darwin-x64": "2.4.9", "@biomejs/cli-linux-arm64": "2.4.9", "@biomejs/cli-linux-arm64-musl": "2.4.9", "@biomejs/cli-linux-x64": "2.4.9", "@biomejs/cli-linux-x64-musl": "2.4.9", "@biomejs/cli-win32-arm64": "2.4.9", "@biomejs/cli-win32-x64": "2.4.9" }, "bin": { "biome": "bin/biome" } }, "sha512-wvZW92FrwitTcacvCBT8xdAbfbxWfDLwjYMmU3djjqQTh7Ni4ZdiWIT/x5VcZ+RQuxiKzIOzi5D+dcyJDFZMsA=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.9", "", { "os": "darwin", "cpu": "arm64" }, "sha512-d5G8Gf2RpH5pYwiHLPA+UpG3G9TLQu4WM+VK6sfL7K68AmhcEQ9r+nkj/DvR/GYhYox6twsHUtmWWWIKfcfQQA=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.9", "", { "os": "darwin", "cpu": "x64" }, "sha512-LNCLNgqDMG7BLdc3a8aY/dwKPK7+R8/JXJoXjCvZh2gx8KseqBdFDKbhrr7HCWF8SzNhbTaALhTBoh/I6rf9lA=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.9", "", { "os": "linux", "cpu": "arm64" }, "sha512-4adnkAUi6K4C/emPRgYznMOcLlUqZdXWM6aIui4VP4LraE764g6Q4YguygnAUoxKjKIXIWPteKMgRbN0wsgwcg=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.9", "", { "os": "linux", "cpu": "arm64" }, "sha512-8RCww5xnPn2wpK4L/QDGDOW0dq80uVWfppPxHIUg6mOs9B6gRmqPp32h1Ls3T8GnW8Wo5A8u7vpTwz4fExN+sw=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.9", "", { "os": "linux", "cpu": "x64" }, "sha512-L10na7POF0Ks/cgLFNF1ZvIe+X4onLkTi5oP9hY+Rh60Q+7fWzKDDCeGyiHUFf1nGIa9dQOOUPGe2MyYg8nMSQ=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.9", "", { "os": "linux", "cpu": "x64" }, "sha512-5TD+WS9v5vzXKzjetF0hgoaNFHMcpQeBUwKKVi3JbG1e9UCrFuUK3Gt185fyTzvRdwYkJJEMqglRPjmesmVv4A=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.9", "", { "os": "win32", "cpu": "arm64" }, "sha512-aDZr0RBC3sMGJOU10BvG7eZIlWLK/i51HRIfScE2lVhfts2dQTreowLiJJd+UYg/tHKxS470IbzpuKmd0MiD6g=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.9", "", { "os": "win32", "cpu": "x64" }, "sha512-NS4g/2G9SoQ4ktKtz31pvyc/rmgzlcIDCGU/zWbmHJAqx6gcRj2gj5Q/guXhoWTzCUaQZDIqiCQXHS7BcGYc0w=="],
+
+    "@fuman/io": ["@fuman/io@0.0.19", "", { "dependencies": { "@fuman/utils": "^0.0.19" } }, "sha512-B+2n3GVa9PCYMJ9xfsdXUlUV9yXO4gKLYfxm815PeJ+MGOw5TbEp166drRmBq1AtxVnP0efy6Oz9rYpKVODgow=="],
+
+    "@fuman/net": ["@fuman/net@0.0.19", "", { "dependencies": { "@fuman/io": "^0.0.19", "@fuman/utils": "^0.0.19" } }, "sha512-yISM+JcZEWBpBYn0v2mUY/Zst4SsicTRaVTvRkVhMiZhgMzdXalfvRwRV/vsgwwL31bntwowCTDW4iilCJLbXg=="],
+
+    "@fuman/node": ["@fuman/node@0.0.19", "", { "dependencies": { "@fuman/io": "^0.0.19", "@fuman/net": "^0.0.19", "@fuman/utils": "^0.0.19" }, "peerDependencies": { "ws": "^8.18.1" }, "optionalPeers": ["ws"] }, "sha512-1VNTBb47yrN5BzuXiP4t6An7mDPklH5N+vUtkeL3XATK+xWbtlQsSsU244T7iqGurmDpYrLM9kIUjdMFm8OhDw=="],
+
+    "@fuman/utils": ["@fuman/utils@0.0.19", "", {}, "sha512-4qVrZ9AjKYztLJsNr1Tp7kL48b22dvVLN1iVW+Me8ZSQ0ILN0qknoxjsczVPReF7+GDWgknNxR2l6ggrA4SZyw=="],
+
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/bytes": ["@types/bytes@3.1.5", "", {}, "sha512-VgZkrJckypj85YxEsEavcMmmSOIzkUHqWmM4CCyia5dc54YwsXzJ5uT4fYxBQNEXx+oF1krlhgCbvfubXqZYsQ=="],
+
+    "@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
+
+    "generic-pool": ["generic-pool@3.9.0", "", {}, "sha512-hymDOu5B53XvN4QT9dBmZxPX4CWhBPPLguTZ9MMFeFa/Kg0xWVfylOVNlJji/E7yTZWFd/q9GO5TxDLq156D7g=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+  }
+}

package/examples/custom-proxy-client.ts

@@ -0,0 +1,32 @@
+import { ProxyDialer } from "../src/dialers/proxy";
+import { createFetch } from "../src/fetch";
+import { HttpClient } from "../src/http-client";
+
+const proxyUrl = process.env.HTTP_PROXY as string;
+
+const client = new HttpClient({
+    dialer: new ProxyDialer(proxyUrl),
+    poolMaxPerHost: 16,
+    poolMaxIdlePerHost: 4,
+    connect: {
+        keepAlive: true,
+        noDelay: true,
+    },
+});
+
+const fetch = createFetch(client);
+
+try {
+    const response = await fetch("https://httpbin.org/ip");
+
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    console.log("proxy:", proxyUrl);
+    console.log("origin seen by server:", data.origin);
+} finally {
+    await client.close();
+}

package/examples/http-client.ts

@@ -0,0 +1,47 @@
+import { HttpClient } from "../src/http-client";
+
+const client = new HttpClient({
+    poolMaxPerHost: 32,
+    poolMaxIdlePerHost: 8,
+    connect: {
+        keepAlive: true,
+        noDelay: true,
+    },
+    io: {
+        reader: {
+            highWaterMark: 16 * 1024,
+            maxHeaderSize: 64 * 1024,
+            maxLineSize: 64 * 1024,
+            maxBufferedBytes: 256 * 1024,
+            decompress: true,
+        },
+        writer: {
+            highWaterMark: 16 * 1024,
+            directWriteThreshold: 64 * 1024,
+            coalesceBodyMaxBytes: 64 * 1024,
+        },
+    },
+});
+
+try {
+    const response = await client.send({
+        url: "https://httpbin.org/anything",
+        method: "POST",
+        headers: new Headers({
+            "content-type": "application/json",
+            "x-example": "advanced-http-client",
+        }),
+        body: JSON.stringify({
+            source: "HttpClient.send",
+            features: ["pooling", "custom I/O", "raw Response access"],
+        }),
+    });
+
+    console.log("status:", response.status);
+    console.log("headers:", Object.fromEntries(response.headers.entries()));
+
+    const data = await response.json();
+    console.log("echoed json:", data.json);
+} finally {
+    await client.close();
+}

package/examples/proxy.ts

@@ -0,0 +1,16 @@
+import { fetch } from "../src/fetch";
+
+const proxyUrl = "http://V0rk3M:phA3fT@186.179.61.64:9183";
+
+const response = await fetch("https://httpbin.org/ip", { proxy: proxyUrl });
+
+if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+}
+
+const data = await response.json();
+
+console.log("proxy:", proxyUrl);
+console.log("origin seen by server:", data.origin);
+
+await fetch.close();

package/examples/simple.ts

@@ -0,0 +1,15 @@
+import { fetch } from "../src/fetch";
+
+const response = await fetch("https://httpbin.org/anything");
+
+if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+}
+
+const data = await response.json();
+
+console.log("status:", response.status);
+console.log("url:", data.url);
+console.log("headers sent:", data.headers);
+
+await fetch.close();

package/package.json

@@ -1,36 +1,47 @@
 {
     "name": "@npy/fetch",
     "type": "module",
-    "version": "0.1.1",
+    "version": "0.1.3",
     "license": "MIT",
-    "scripts": {},
+    "description": "HTTP/1.1 client built from raw TCP sockets with fetch-compatible primitives and proxy support.",
+    "sideEffects": false,
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "keywords": [
+        "fetch",
+        "http",
+        "http-client",
+        "proxy",
+        "socks",
+        "socks5",
+        "tcp",
+        "node",
+        "bun"
+    ],
+    "scripts": {
+        "bench": "node --import=tsx ./benchmarks/index.ts",
+        "bench:direct": "node --import=tsx ./benchmarks/direct.ts",
+        "bench:proxy": "node --import=tsx ./benchmarks/proxy.ts"
+    },
+    "devDependencies": {
+        "@types/bytes": "^3.1.5",
+        "axios": "^1.8.4",
+        "got": "^14.4.6",
+        "hpagent": "^1.2.0",
+        "http-proxy-agent": "^7.0.2",
+        "node-fetch": "^3.3.2",
+        "proxy-chain": "^2.7.1",
+        "undici": "^7.13.0",
+        "mitata": "^1.0.34"
+    },
     "dependencies": {
         "@fuman/io": "^0.0.19",
         "@fuman/net": "^0.0.19",
         "@fuman/node": "^0.0.19",
         "@fuman/utils": "^0.0.19",
-        "@npy/proxy-kit": "0.1.1",
+        "@npy/proxy-kit": "workspace:*",
         "bytes": "^3.1.2",
         "generic-pool": "^3.9.0"
-    },
-    "exports": {
-        ".": {
-            "import": {
-                "types": "./index.d.ts",
-                "default": "./index.js"
-            },
-            "require": {
-                "types": "./index.d.cts",
-                "default": "./index.cjs"
-            }
-        }
-    },
-    "sideEffects": false,
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/neeopy/npy.git"
-    },
-    "files": [
-        "**/*"
-    ]
-}
+    }
+}

package/src/_internal/consts.ts

@@ -0,0 +1,3 @@
+export const CRLF_BYTES = new Uint8Array([0x0d, 0x0a]);
+export const CRLF_STR = "\r\n";
+export const CRLF_LENGTH = 2;

package/src/_internal/decode-stream-error.ts

@@ -0,0 +1,16 @@
+/**
+ * Internal sentinel thrown when a decompression stream fails.
+ *
+ * Tagged at the source (inside createDecoder) so that error classifiers
+ * can use `instanceof` instead of heuristics on error messages or codes.
+ * Never exposed in the public API — callers receive ResponseDecodeError.
+ */
+export class DecodeStreamError extends Error {
+    readonly cause: unknown;
+
+    constructor(cause: unknown) {
+        super("Response decode failed", { cause });
+        this.name = "DecodeStreamError";
+        this.cause = cause;
+    }
+}