simpleFetch

Minimal, audit-friendly fetch utility with predictable engine fallback.

@renpwn/simplefetch is a core network utility designed to fetch raw data only —
without parsing, storage, logging, auto-install, or hidden side-effects.

✨ Features

• ✅ Minimal & predictable
• ✅ Multiple fetch engines
• ✅ Auto fallback mode
• ✅ Optional retry & timeout
• ✅ Abort / cancel support
• ✅ Observability hook
• ✅ Structured error system
• ✅ TypeScript typings included
• ❌ No auto-install dependency
• ❌ No logging
• ❌ No file system write
• ❌ No domain logic
• ❌ No hidden side-effects

📦 Installation

npm i @renpwn/simplefetch

Optional engines

# Cookie / session support (native fetch)
npm i tough-cookie

# Cookie / session support (axios)
npm i axios-cookiejar-support tough-cookie

# JavaScript-rendered pages
npm i puppeteer

🚀 Basic Usage

import { simpleFetch } from "@renpwn/simplefetch"

const html = await simpleFetch("https://example.com")
console.log(html)

⚙️ Engines & Node.js Compatibility

| Engine | Description | Dependency | Minimum Node.js | |------|------------|------------|-----------------| | native | Node.js built-in fetch (Undici) | none | ≥ 18 | | nativeCookie | Native fetch with cookie / session support | tough-cookie | ≥ 18 | | axios | Axios HTTP client | axios | ≥ 14 | | axiosCookie | Axios with cookie / session support | axios-cookiejar-support, tough-cookie | ≥ 14 | | puppeteer | JavaScript-rendered pages | puppeteer | ≥ 16 |

🔁 Engine Modes

Explicit engine

await simpleFetch(url, { engine: "axios" })

• No fallback
• Missing dependency → throws error
• Unsupported runtime → throws error

Auto mode (default)

await simpleFetch(url)

Fallback order:

native → nativeCookie → axios → axiosCookie → puppeteer

Behavior:

• Missing dependency → skipped
• First success → returned
• All fail → error thrown

🔄 Retry Policy

| Mode | Default retry | |------|---------------| | Explicit engine | 0 | | Auto mode | 1 per engine |

await simpleFetch(url, { retries: 2 })

Retry applies only to runtime errors, not to missing dependencies or invalid config.

⏱ Timeout (Optional)

await simpleFetch(url, { timeout: 15000 })

If not set, engine default timeout is used.

📤 Output Modes

| Output | Return type | |------|-------------| | text (default) | string | | json | object | | buffer | Buffer | | stream | ReadableStream |

Example:

const data = await simpleFetch(url, { output: "json" })

🛑 Abort / Cancel

const controller = new AbortController()

simpleFetch(url, {
  signal: controller.signal
})

controller.abort()

Useful for batch jobs, CLI tools, and long-running requests.

🔍 Observability Hook

simpleFetch(url, {
  onAttempt({ engine, attempt }) {
    console.log(engine, attempt)
  }
})

Called every time an engine is attempted.

❌ Error Handling

Return contract

• ✅ Success → returns data
• ❌ Error → throws error

No:

• { success: true }
• null
• silent failure
• internal logging

Error Types

import {
  EngineNotAvailableError,
  InvalidEngineError,
  AllEnginesFailedError
} from "@renpwn/simplefetch"

🧠 Design Principles

• Single responsibility
• Fail fast
• No side-effects
• No magic behavior
• User owns logging & persistence

🧩 Recommended Architecture

simplefetch  → fetch raw data
processor    → parse / transform
writer       → save / export

📘 TypeScript Support

Type definitions are included (index.d.ts).
No build step required.

🛡 Production & CI Safe

• No auto-install
• No console output
• No file write
• No environment mutation

Safe for:

• Production servers
• CI pipelines
• CLI tools
• Libraries

📄 License

MIT © renpwn - Ardy Rendra R

🙌 Support the Author

If this project helps you or saves you time, your support is greatly appreciated 🙏

⭐ Star the repo

📺 Content & Community

🛒 Marketplace & Social Commerce

☕ Personal Support