npm package: @renpwn/simplefetch
Description: Minimal, audit-friendly fetch utility with auto engine fallback (native, axios, cookie, puppeteer)
Author: renpwn
Latest version: 0.0.2

# simpleFetch

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

[![NPM](https://img.shields.io/npm/v/@renpwn/simplefetch)](https://www.npmjs.com/package/@renpwn/simplefetch)
[![Downloads](https://img.shields.io/npm/dm/@renpwn/simplefetch)](https://www.npmjs.com/package/@renpwn/simplefetch)
[![License](https://img.shields.io/npm/l/@renpwn/simplefetch)](LICENSE)

`@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

```bash
npm i @renpwn/simplefetch
```

### Optional engines

```bash
# 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

```js
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

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

- No fallback
- Missing dependency → **throws error**
- Unsupported runtime → **throws error**

---

### Auto mode (default)

```js
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 |

```js
await simpleFetch(url, { retries: 2 })
```

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

---

## ⏱ Timeout (Optional)

```js
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:

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

---

## 🛑 Abort / Cancel

```js
const controller = new AbortController()

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

controller.abort()
```

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

---

## 🔍 Observability Hook

```js
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

```js
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
[![GitHub Stars](https://img.shields.io/github/stars/renpwn/simpleFetch?style=flat&logo=github&color=gray)](https://github.com/renpwn/simpleFetch)

### 📺 Content & Community
[![YouTube](https://img.shields.io/badge/YouTube-Subscribe-FF0000?style=flat&logo=youtube&logoColor=white)](https://youtube.com/@renpwn)

### 🛒 Marketplace & Social Commerce
[![TikTok](https://img.shields.io/badge/TikTok-Account%20%26%20Shop-25F4EE?style=flat&logo=tiktok&logoColor=black)](https://www.tiktok.com/@renpwn)
[![Shopee](https://img.shields.io/badge/Shopee-Store-EE4D2D?style=flat&logo=shopee&logoColor=white)](https://shopee.co.id/renpwn)
[![Tokopedia](https://img.shields.io/badge/Tokopedia-Store-03AC0E?style=flat&logo=tokopedia&logoColor=white)](https://www.tokopedia.com/renpwn)

### ☕ Personal Support
[![PayPal](https://img.shields.io/badge/PayPal-Donate-0070BA?style=flat&logo=paypal&logoColor=white)](https://paypal.me/ArdyRendra)
[![Saweria](https://img.shields.io/badge/Saweria-Support-FFB000?style=flat)](https://saweria.co/renpwn)
[![Trakteer](https://img.shields.io/badge/Trakteer-Support-FF6F00?style=flat)](https://trakteer.id/renpwn)