@firekid/hurl 1.0.6 → 1.0.7

package/README.md

@@ -12,7 +12,7 @@ https://github.com/Firekid-is-him/hurl
 
 ## Purpose
 
-`hurl` solves the problems that `request` left behind when it was deprecated and that `axios` never fully addressed: no edge runtime support, a 35KB bundle, no built-in retry logic, no request deduplication, and no upload progress tracking. `hurl` ships all of these in under 3KB with zero runtime dependencies.
+`hurl` solves the problems that `request` left behind when it was deprecated and that `axios` never fully addressed: no edge runtime support, a 35KB bundle, no built-in retry logic, no request deduplication, and no upload progress tracking. `hurl` ships all of these in under 10KB with zero runtime dependencies.
 
 ## Core Concepts
 
@@ -93,6 +93,7 @@ type HurlRequestOptions = {
   onUploadProgress?: ProgressCallback
   onDownloadProgress?: ProgressCallback
   stream?: boolean
+  throwOnError?: boolean
   debug?: boolean
   requestId?: string
   deduplicate?: boolean
@@ -219,6 +220,17 @@ await hurl.get('/users', {
 })
 ```
 
+```ts
+import { clearCache, invalidateCache } from '@firekid/hurl'
+
+// Clear the entire cache
+clearCache()
+
+// Invalidate a single entry by URL or custom key
+invalidateCache('https://api.example.com/users')
+invalidateCache('all-users') // if you used a custom cache key
+```
+
 ## Request Deduplication
 
 When `deduplicate` is true and the same GET URL is called multiple times simultaneously, only one network request is made.
@@ -232,19 +244,35 @@ const [a, b] = await Promise.all([
 
 ## Proxy
 
+Native fetch does not support programmatic proxy configuration out of the box. Proxy support depends on your Node.js version:
+
+**Node.js 18** — install `undici@6` (v7 dropped Node 18 support), use `ProxyAgent`:
 ```ts
-await hurl.get('/users', {
-  proxy: { url: 'http://proxy.example.com:8080' }
-})
+// npm install undici@6
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+setGlobalDispatcher(new ProxyAgent('http://proxy.example.com:8080'))
+```
 
-await hurl.get('/users', {
-  proxy: {
-    url: 'socks5://proxy.example.com:1080',
-    auth: { username: 'user', password: 'pass' }
-  }
-})
+**Node.js 20** — `undici` is bundled with `ProxyAgent` support:
+```ts
+import { ProxyAgent, setGlobalDispatcher } from 'undici'
+setGlobalDispatcher(new ProxyAgent('http://proxy.example.com:8080'))
 ```
 
+**Node.js 22.3+** — supports `EnvHttpProxyAgent` which reads `HTTP_PROXY`/`HTTPS_PROXY` env vars automatically:
+```ts
+import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici'
+setGlobalDispatcher(new EnvHttpProxyAgent())
+// now set HTTP_PROXY=http://proxy.example.com:8080 in your env
+```
+
+**Node.js 24+** — native fetch respects env vars when `NODE_USE_ENV_PROXY=1` is set:
+```bash
+NODE_USE_ENV_PROXY=1 HTTP_PROXY=http://proxy.example.com:8080 node app.js
+```
+
+The `proxy` option in `HurlRequestOptions` is reserved for a future release where this will be handled automatically.
+
 ## Parallel Requests
 
 ```ts
@@ -271,6 +299,8 @@ const adminApi = api.extend({
 })
 ```
 
+`create()` produces a fully isolated instance — no shared defaults, interceptors, or state with the parent. `extend()` merges the provided defaults on top of the parent's and inherits all of the parent's interceptors.
+
 ## Debug Mode
 
 Logs the full request (method, url, headers, body, query, timeout, retry config) and response (status, timing, headers, data) to the console. Errors and retries are also logged.
@@ -283,6 +313,15 @@ await hurl.get('/users', { debug: true })
 
 `hurl` throws a `HurlError` on HTTP errors (4xx, 5xx), network failures, timeouts, aborts, and parse failures. It never resolves silently on bad status codes.
 
+If you want to handle 4xx/5xx responses without a try/catch, set `throwOnError: false` — the response resolves normally and you can check `res.status` yourself.
+
+```ts
+const res = await hurl.get('/users', { throwOnError: false })
+if (res.status === 404) {
+  console.log('not found')
+}
+```
+
 ```ts
 import hurl, { HurlError } from '@firekid/hurl'
 
@@ -373,10 +412,10 @@ Sends a request with the method specified in options. Defaults to GET. Returns `
 Runs an array of requests in parallel. Returns a promise that resolves when all requests complete. Equivalent to `Promise.all`.
 
 ### hurl.create(defaults?)
-Creates a new isolated instance with its own defaults, interceptors, and state. Does not share anything with the parent instance.
+Creates a new isolated instance with its own defaults, interceptors, and state. Does not inherit anything from the parent instance.
 
 ### hurl.extend(defaults?)
-Creates a new instance that inherits the current defaults and merges in the provided ones.
+Creates a new instance that inherits the current defaults, merges in the provided ones, and copies all parent interceptors (request, response, and error).
 
 ### hurl.defaults.set(defaults)
 Sets global defaults for the current instance. Merged into every request.
@@ -404,6 +443,15 @@ import { clearCache } from '@firekid/hurl'
 clearCache()
 ```
 
+### invalidateCache(key)
+Removes a single entry from the in-memory cache by URL or custom cache key.
+
+```ts
+import { invalidateCache } from '@firekid/hurl'
+invalidateCache('https://api.example.com/users')
+invalidateCache('all-users') // if you used a custom cache key
+```
+
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firekid/hurl",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Zero-dependency HTTP client for Node.js and edge runtimes. Built on fetch. The modern replacement for axios, request, got, node-fetch, and ky. Works on Cloudflare Workers, Vercel Edge, Deno, and Bun.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",