uncreate

uncreate

Minimal, type-safe REST client using JS proxies.

ℹ️ If you like this package, upvote this feature to be part of unjs/ofetch Much appreciated.

Features

• 🌁 Lightweight, only 36 loc
• 🦾 Strongly typed
• 📚 Supports chain and bracket syntax
  • api.nested.users(1).get()
  • or api.nested.users["1"].get()
• 🪵 Use other HTTP methods, like .post()

uncreate uses ofetch for data fetching under the hood. Thus, every option available for ofetch is usable with uncreate as well!

Installation

Run the following command to add uncreate to your project.

pnpm install uncreate # or npm or yarn

Usage

import { createClient } from 'uncreate'

// The base URL default is `/`
const api = createClient()

uncreate inherits ofetch's options. Refer to the documentation for a complete list of options.

import { createClient } from 'uncreate'

// Set a custom base URL as needed
const api = createClient({
  baseURL: 'https://jsonplaceholder.typicode.com',
})

Path Segment Chaining

Chain single path segments or path ids by a dot. You can even type the response of your request!

// GET request to <baseURL>/users
const users = await api.users.get<UserResponse>()

// For GET request you can add search params
// <baseURL>/users?search=john
const users = await api.users.get<UserResponse>({ search: 'john' })

To include dynamic API path segments, you have two options:

// Typed GET request to <baseURL>/users/1
const userId = 1
// … using the chain syntax:
const user = await api.users(userId).get<UserResponse>()
// … or the bracket syntax:
const user = await api.users[`${userId}`].get<UserResponse>()

HTTP Request Methods

Add the appropriate method to the end of your API call. The following methods are supported:

• get()
• post()
• put()
• delete()
• patch()

Payload Requests

For HTTP request methods supporting a payload, add it to the method call:

// POST request to <baseURL>/users
const response = await api.users.post({ name: 'foo' })

Default Options For $fetch

import { createClient } from 'uncreate'

const api = createClient({
  baseURL: 'https://jsonplaceholder.typicode.com',
  async onRequestError({ request, options, error }) {
    console.log('[fetch request error]', request, error)
  },
  async onResponseError({ request, options, error }) {
    console.log('[fetch response error]', request, error)
  },
})

Override Default Options

You can add/overwrite $fetch options on a method-level:

const response = await api.users.get({
  headers: {
    'Cache-Control': 'no-cache',
  },
})

Credits

• Ilya Komsa for his REST API generator.
• David Wells for his GitHub API using proxies.

License

MIT License © 2022 Johann Schopplich