ya-fetch
> Super light-weight wrapper around `fetch`
- [x] Only 904 B when minified & gziped
- [x] Based on [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) & [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController)
- [x] Custom [instance](#create) with options (`headers`, `error` handlers, ...)
- [x] Exposed response body [methods](#returns-response-promise) (`.json`, `.blob`, ...)
- [x] First-class [JSON support](#send--receive-json) (automatic serialization, content type headers)
- [x] [Search params](#params-urlsearchparams--object--string) serialization
- [x] Global [timeouts](#timeout-number)
- [x] [Works in a browser](#-import-in-a-browser) without a bundler
- [x] Written in TypeScript
- [x] Pure ESM module
- [x] Zero deps
## 📦 Install
```sh
$ npm install --save ya-fetch
```
## 🌎 Import in a browser
```html
```
For readable version import from `https://esm.sh/ya-fetch/esm/index.js?raw`.
[🔗 Playground on CodePen](https://codepen.io/exah/pen/gOKRYjW?editors=0012).
## ⬇️ Jump to
- [📖 API](#-api)
- [🔧 Options](#-options)
- [🔥 Migration from v1 → v2](#-migration-from-v1--v2)
## 👀 Examples
### Import module
```ts
import * as YF from 'ya-fetch' // or from 'https://esm.sh/ya-fetch' in browsers
```
### Create an instance
```ts
const api = YF.create({ resource: 'https://jsonplaceholder.typicode.com' })
```
#### Related
- [`create`](#create)
- [`instance`](#returns-instance)
- [`options.resource`](#resource-string)
### Send & receive JSON
```ts
await api.post('/posts', { json: { title: 'New Post' } }).json()
```
Same code with native fetch
```ts
fetch('http://example.com/posts', {
method: 'POST',
headers: {
'content-type': 'application/json',
accept: 'application/json',
},
body: JSON.stringify({ title: 'New Post' }),
}).then((res) => {
if (res.ok) {
return res.json()
}
throw new Error('Request failed')
})
```
Same code with native fetch
```ts
fetch('http://example.com/posts?id=1').then((res) => {
if (res.ok) {
return res.json()
}
throw new Error('Request failed')
})
```
Same code with native fetch
```js
const controller = new AbortController()
setTimeout(() => {
controller.abort()
}, 300)
fetch('http://example.com/posts', {
signal: controller.signal,
headers: {
accept: 'application/json',
},
})
.then((res) => {
if (res.ok) {
return res.json()
}
throw new Error('Request failed')
})
.catch((error) => {
if (error.name === 'AbortError') {
// do something
}
})
```
post
patch
put
delete
head
```ts
function requestMethod(resource?: string, options?: Options): ResponsePromise
```
Same as [`get`](#getbrpostbrpatchbrputbrdeletebrhead), [`post`](<(#getbrpostbrpatchbrputbrdeletebrhead)>), [`patch`](<(#getbrpostbrpatchbrputbrdeletebrhead)>), [`put`](#getbrpostbrpatchbrputbrdeletebrhead), [`delete`](#getbrpostbrpatchbrputbrdeletebrhead), or [`head`](#getbrpostbrpatchbrputbrdeletebrhead) function exported from the module, but with preset [options](#-options).
#### extend
```ts
function extend(options?: Options): Instance
```
Take an instance and extend it with additional options, the [`headers`](#headers-headersinit) and [`params`](#params-urlsearchparams--object--string) will be merged with values provided in parent instance, the [`resource`](#resource-string) will concatenated to the parent value.
```js
const instance = YF.create({
resource: 'https://jsonplaceholder.typicode.com',
headers: { 'X-Custom-Header': 'Foo' },
})
// will have combined `resource` and merged `headers`
const extended = instance.extend({
resource: '/posts'
headers: { 'X-Something-Else': 'Bar' },
})
// will send request to: 'https://jsonplaceholder.typicode.com/posts/1'
await extended.post('/1', { json: { title: 'Hello' } })
```
##### Related
- [Create an instance](#create-an-instance)
- [Extend an instance](#extend-an-instance)
- [`create`](#create)
- [`post`](#getbrpostbrpatchbrputbrdeletebrhead)
- [`options.resource`](#resource-string)
- [`options.headers`](#headers-headersinit)
### get
post
patch
put
delete
head
```ts
function requestMethod(resource?: string, options?: Options): ResponsePromise
```
Calls `fetch` with preset request method and options:
```ts
await YF.get('https://jsonplaceholder.typicode.com/posts').json()
// → [{ id: 0, title: 'Hello' }, ...]
```
The same functions are returned after [creating an instance](#create) with preset options:
```ts
const instance = YF.create({ resource: 'https://jsonplaceholder.typicode.com' })
await instance.get('/posts').json()
// → [{ id: 0, title: 'Hello' }, ...]
```
#### Related
- [Create and instance](#create-an-instance)
- [Send & receive JSON](#send--receive-json)
- [`create`](#create)
- [`options.resource`](#resource-string)
- [`response.json`](#json)
#### Returns response promise
```ts
interface ResponsePromise extends Promise {
json(): Promise
text(): Promise
blob(): Promise
arrayBuffer(): Promise
formData(): Promise
void(): Promise
}
```
`ResponsePromise` is a promise based object with exposed body methods:
#### json
```ts
function json(): Promise
```
Sets `Accept: 'application/json'` in `headers` and parses the `body` as JSON:
```ts
interface Post {
id: number
title: string
content: string
}
const post = await instance.get('/posts').json()
```
Same code with native fetch
```ts
interface Post {
id: number
title: string
content: string
}
const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
headers: { Accept: 'application/json' },
})
if (response.ok) {
const post: Post[] = await response.json()
}
```
Same code with native fetch
```ts
const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
headers: { Accept: 'text/*' },
method: 'DELETE',
})
if (response.ok) {
await response.text() // → 'OK'
}
```
Same code with native fetch
```ts
const body = new FormData()
body.set('title', 'Hello world')
body.set('content', '🌎')
const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
headers: { Accept: 'multipart/form-data' },
method: 'POST',
body,
})
if (response.ok) {
const data = await response.formData()
data.get('id') // → 1
}
```
Same code with native fetch
```ts
const response = await fetch(
'https://upload.wikimedia.org/wikipedia/commons/c/c8/Example.ogg'
)
if (response.ok) {
const data = await response.arrayBuffer()
const context = new AudioContext()
const source = new AudioBufferSourceNode(context)
source.buffer = await context.decodeAudioData(buffer)
source.connect(context.destination)
source.start()
}
```
Same code with native fetch
```ts
const response = await fetch('https://placekitten.com/200')
if (response.ok) {
const blob = await response.blob()
const image = new Image()
image.src = URL.createObjectURL(blob)
document.body.append(image)
}
```
Same code with native fetch
```ts
const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ title: 'Hello' }),
})
if (response.ok) {
// do something
}
```