knorry

The most lightweight pure esm browser only http client you could get 🚀

Why?

• 🌳 Tree Shakable
• 🗒️ Type Definitions
• 🏭 Supports most features
• ❌ Doesn't throw errors on requests with non 200 code
• 🪶 As lightweight as possible
• ⚡ Pure ESM
• 📦 Optimized for bundlers
• 🤝 Promise based
• ➡️ Automatically parses JSON
• 👨‍💻 Splendid developer experience
• 🚀 Extremely good compatibility (~98.4%)

Installation

With a module bundler:

npm i -D knorry

No additional configuration required

CDN & Node

Using a CDN (Not recommended):

const knorry = (await import('https://cdn.jsdelivr.net/npm/knorry@latest')).default

This method is not recommended because it performs additional requests and doesn't support tree shaking, so even if you only used the get method the bundle stays complete

When using node (Not recommended):

npm i knorry xmlhttprequest form-data urlsearchparams

const { defineKnorryOptions } = await import('knorry')
const { XMLHttpRequest } = require('xmlhttprequest')
global.FormData = require('form-data')
global.Blob = class Blob {}
global.URLSearchParams = require('urlsearchparams')
defineKnorryOptions({
    XHRClass: XMLHttpRequest
})

This method is not recommended because it doesn't supports all features and you aren't in need of a lightweight client in nodejs. Use a more robust client like axios instead

Usage

First, import all methods you need:

import { get, post } from 'knorry'

Now you can make requests like this:

const res = await get('example-api.com')
console.log(res.$plain())
// res -> String { 'response', $res: ... }

Alternatively you could use the default export:

import knorry from 'knorry'
knorry('POST', 'example.com', {
    key: 'value'
}, {
    headers: {
        myHeader: '12345'
    }
})

Docs

If you want to see a full documentation take a look at this

Some things to keep in mind when using knorry

Easy mode

By default knorry will use easy mode, which you can disable like this:

import { defineKnorryOptions, get } from 'knorry'
defineKnorryOptions({
    easyMode: false
})

// Or temporarily disable it for one request
await get('example.com', {
    easyMode: false
})

Easy mode will not directly return the response, but rather return the data containing the full response on the $res property. This will work using the constructor of a primitive type like String:

await get('example-api.com') // -> String {'response', $res: ...}
await get('example-api.com', { easyMode: false }) // -> {data: 'response', ...}

It is implemented like this because it's much cleaner to write:

<!-- Svelte file for demonstration -->
<script>
import { get } from 'knorry'
</script>
<main>
Hello, {await get('/whoami')}
</main>

than having to wrap every request in parentheses:

<!-- Svelte file for demonstration -->
<script>
import { get, defineKnorryOptions } from 'knorry'
defineKnorryOptions({
    easyMode: false
})
</script>
<main>
Hello, {(await get('/whoami')).data}
</main>

However this has some flaws, like equality & type checking. Here are some instructions teaching you what works and what doesn't:

import { get } from 'knorry'

// 💩
await get('/whoami') === 'username'
typeof await get('/whoami') === 'string'
!!await get('/returns-false') // -> true

// 👌
await get('/whoami') == 'username'
await get('/whoami') instanceof String
!!(await get('/returns-false')).$plain() // -> false

If you are working on an enterprise project, you should disable easyMode by default.