fetchja 1.4.0 → 2.0.0

package/readme.md

@@ -1,45 +1,333 @@
 # Fetchja
 
-Welcome to **Fetchja**, the ultimate JavaScript library designed to make your JSON:API interactions seamless and intuitive. Inspired by the renowned [Kitsu](https://github.com/wopian/kitsu) library, Fetchja leverages the native Fetch API, ensuring a lightweight and efficient experience.
+**A tiny, modern, zero-dependency JSON:API client built on the native Fetch API.**
 
-## Why Fetchja?
+Fetchja helps you talk to a [JSON:API](https://jsonapi.org) server. It uses the browser's own `fetch`, so it stays small and fast. You write plain objects, and Fetchja turns them into JSON:API requests. The server answers, and Fetchja turns the answer back into plain objects — with relationships already filled in. It was inspired by [Kitsu](https://github.com/wopian/kitsu), but it has **no dependencies**.
+
+```js
+import Fetchja from 'fetchja'
+
+const api = new Fetchja({
+  baseURL: 'https://api.example.com'
+})
+
+const { data } = await api.get('articles')
+```
+
+## Contents
 
-- ⚡️ **Lightweight and Fast**: Built on the native Fetch API, Fetchja ensures minimal overhead and maximum performance.
-- 🎨 **Intuitive Design**: Easy-to-understand methods and configurations make Fetchja accessible for developers of all levels.
-- 💪 **Flexible and Customizable**: Tailor Fetchja to your needs with customizable headers, query parameters, and resource cases.
+- [Why Fetchja?](#why-fetchja)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Options](#options)
+- [Methods](#methods)
+- [Relationships and included data](#relationships-and-included-data)
+- [Query parameters](#query-parameters)
+- [Make your own query formatter](#make-your-own-query-formatter)
+- [Custom fetch](#custom-fetch)
+- [Errors](#errors)
+- [Retry on error](#retry-on-error)
+- [Use with TanStack Query](#use-with-tanstack-query)
+- [TypeScript](#typescript)
+- [Plurals](#plurals)
+
+## Why Fetchja?
 
-## Installation
+- ⚡️ **No dependencies.** It only uses the built-in `fetch`. Nothing extra to download. About 5 KB when minified.
+- 🧩 **Typed.** It is written in TypeScript and ships its own types. You get autocomplete out of the box.
+- 🔄 **Less boilerplate.** You send and read plain objects. Fetchja does the JSON:API parts for you.
+- 🪶 **Modern and small.** ESM only, `async`/`await`, no base class to extend.
+- 🛡️ **Safe.** It guards against prototype pollution when it reads a response.
+- 🎛️ **Flexible.** Set your own headers, query format, name case, plurals, `fetch`, and error handling.
 
-To get started with Fetchja, simply install it via `npm` along with the `pluralize` library:
+## Install
 
 ```bash
-$ npm install fetchja pluralize
+npm install fetchja
 ```
 
-## Getting Started
+You don't need any other package. Fetchja needs a place where `fetch` exists: Node 18+, Deno, Bun, or any modern browser.
 
-Here's a quick example to get you up and running with Fetchja:
+## Quick start
 
-```javascript
+```js
 import Fetchja from 'fetchja'
 
 const api = new Fetchja({
   baseURL: 'https://api.example.com'
-});
+})
+
+// GET /articles
+const { data, meta } = await api.get('articles')
+
+// GET /articles/1
+const { data: article } = await api.get('articles/1')
+
+console.log(article)
+// { type: 'articles', id: '1', title: 'Hello world', ... }
+```
+
+## Options
+
+You set everything when you create the client:
+
+```js
+const api = new Fetchja({ /* options */ })
+```
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `baseURL` | `string` | — | The start of every URL. You need it (or pass one per request). |
+| `headers` | `Record<string, string>` | JSON:API headers | Headers added to every request. The JSON:API `Accept` and `Content-Type` are set for you. |
+| `fetch` | `typeof fetch` | global `fetch` | Your own fetch function (for example, one that adds a token). |
+| `queryFormatter` | `(params) => string \| URLSearchParams` | built-in | Turns the `params` object into a query string. |
+| `resourceCase` | `'camel' \| 'kebab' \| 'snake' \| 'none'` | `'none'` | How the resource name in the URL is written. |
+| `typeCase` | `'camel' \| 'kebab' \| 'snake' \| 'none'` | `'camel'` | How `type` names are written when you send data. |
+| `pluralize` | `boolean \| ((word) => string)` | `true` (built-in) | Make resource names plural. Use `false` to turn it off, or pass your own function. |
+| `onResponseError` | `(response) => Response \| void` | — | Runs when a request fails, before Fetchja throws. You can retry here. |
+
+## Methods
+
+| Method | Alias | How to call it | HTTP |
+| --- | --- | --- | --- |
+| `get` | `fetch` | `get(model, options?)` | `GET` |
+| `post` | `create` | `post(model, body, options?)` | `POST` |
+| `patch` | `update` | `patch(model, body, options?)` | `PATCH` |
+| `delete` | `remove` | `delete(model, id, options?)` | `DELETE` |
+
+Pick the name you like. `api.get` and `api.fetch` do the same thing. So do `create`/`post`, `update`/`patch`, and `remove`/`delete`.
+
+```js
+// Read a list
+const { data } = await api.get('articles')
+
+// Read one
+const { data } = await api.get('articles/1')
+
+// Create
+await api.create('article', { title: 'Hello world' })
+
+// Update (put the id in the body)
+await api.update('article', { id: '1', title: 'New title' })
+
+// Delete
+await api.remove('article', '1') // DELETE /articles/1 (no body)
+```
+
+Every call gives you back the data plus a few extra fields:
+
+```js
+const response = await api.get('articles/1')
+
+response.data        // your data (an object, or an array for a list)
+response.meta        // the JSON:API `meta`, if the server sent it
+response.status      // 200
+response.statusText  // 'OK'
+response.headers     // the response headers, as a plain object
+```
+
+## Relationships and included data
+
+To send a relationship, put an object (or a list of objects) with a `type` and an `id` inside your data. Fetchja moves it to the right place and adds the full resource to `included` for you:
+
+```js
+await api.create('article', {
+  title: 'Hello world',
+  author: { type: 'people', id: '9' },
+  tags: [
+    { type: 'tags', id: '1' },
+    { type: 'tags', id: '2' }
+  ]
+})
+```
+
+When you read data back, Fetchja takes the resources from `included` and puts them right inside your data. So you can read a relationship like a normal nested object:
+
+```js
+const { data } = await api.get('articles/1', {
+  params: { include: 'author' }
+})
+
+console.log(data.author.name) // comes from `included`
+```
+
+## Query parameters
+
+Pass a `params` object. Fetchja turns nested objects and arrays into JSON:API-style query strings:
+
+```js
+const { data, meta } = await api.get('articles', {
+  params: {
+    include: ['author', 'comments'],
+    fields: { articles: 'title,body' },
+    filter: { published: true },
+    sort: '-createdAt',
+    page: { number: 1, size: 10 }
+  }
+})
+```
+
+This becomes:
+
+```
+/articles?include[]=author&include[]=comments&fields[articles]=title,body&filter[published]=true&sort=-createdAt&page[number]=1&page[size]=10
+```
+
+## Make your own query formatter
+
+Some servers want a different format. For example, they may want `include=author,comments` (one key, values joined by commas) instead of `include[]=...`. You can pass your own function:
+
+```js
+import Fetchja from 'fetchja'
+
+function commaQueryFormatter (params) {
+  const search = new URLSearchParams()
+
+  for (const key in params) {
+    const value = params[key]
+
+    search.append(
+      key,
+      Array.isArray(value) ? value.join(',') : String(value)
+    )
+  }
+
+  return search
+}
+
+const api = new Fetchja({
+  baseURL: 'https://api.example.com',
+  queryFormatter: commaQueryFormatter
+})
+
+await api.get('articles', { params: { include: ['author', 'comments'] } })
+// -> /articles?include=author,comments
+```
+
+Your function takes the `params` object and returns a string or a `URLSearchParams`.
+
+## Custom fetch
+
+You can swap in your own fetch function. This is handy for tokens, timeouts, or logging:
+
+```js
+const api = new Fetchja({
+  baseURL: 'https://api.example.com',
+  fetch: (url, init) => myCustomFetch(url, init)
+})
+```
+
+## Errors
+
+When a request fails, Fetchja throws a `FetchjaError`. It holds the HTTP status and the JSON:API `errors` list:
+
+```js
+import Fetchja, { FetchjaError } from 'fetchja'
 
 try {
-  const response = await api.get('/posts')
-  console.log(response)
+  await api.get('articles/999')
 } catch (error) {
-  console.error(error)
+  if (error instanceof FetchjaError) {
+    console.log(error.status)     // 404
+    console.log(error.statusText) // 'Not Found'
+    console.log(error.errors)     // [{ status: '404', detail: 'Not found' }]
+    console.log(error.response)   // the raw Response
+  }
+}
+```
+
+## Retry on error
+
+`onResponseError` runs when the server sends a failing response, before Fetchja throws. The response also gets a `replayRequest()` method. It sends the same request again. This is great for refreshing a token and trying once more:
+
+```js
+const api = new Fetchja({
+  baseURL: 'https://api.example.com',
+  headers: { Authorization: `Bearer ${getToken()}` },
+  onResponseError: async (response) => {
+    if (response.status === 401) {
+      api.headers.Authorization = `Bearer ${await refreshToken()}`
+
+      return response.replayRequest() // try again with the new token
+    }
+  }
+})
+```
+
+Return a `Response` (like the one from `replayRequest()`) to keep going. Return nothing, and Fetchja throws the `FetchjaError`.
+
+## Use with TanStack Query
+
+Fetchja works well with [TanStack Query](https://tanstack.com/query). Because Fetchja throws on a failing request, TanStack Query sees the error and handles it for you.
+
+Reading data:
+
+```js
+import { useQuery } from '@tanstack/react-query'
+import Fetchja from 'fetchja'
+
+const api = new Fetchja({ baseURL: 'https://api.example.com' })
+
+function useArticles () {
+  return useQuery({
+    queryKey: ['articles'],
+    queryFn: () => api.get('articles')
+  })
+}
+```
+
+Creating data:
+
+```js
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+function useCreateArticle () {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (article) => api.create('article', article),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['articles'] })
+    }
+  })
+}
+```
+
+## TypeScript
+
+Fetchja is written in TypeScript and brings its own types. You don't need an extra `@types` package.
+
+```ts
+import Fetchja, { type FetchjaOptions, FetchjaError } from 'fetchja'
+
+const options: FetchjaOptions = {
+  baseURL: 'https://api.example.com',
+  resourceCase: 'kebab'
 }
+
+const api = new Fetchja(options)
+```
+
+## Plurals
+
+By default, Fetchja makes resource names plural with a small built-in helper. It knows the common English rules (and `status` becomes `statuses`, not `statu`). It is also safe to run twice: `articles` stays `articles`.
+
+For tricky words (like `person` → `people`), pass a bigger library such as [`pluralize`](https://www.npmjs.com/package/pluralize):
+
+```js
+import pluralize from 'pluralize'
+
+const api = new Fetchja({
+  baseURL: 'https://api.example.com',
+  pluralize
+})
 ```
 
-### Using a custom fetch function.
+Or turn it off and use the exact names you write:
 
-```javascript
+```js
 const api = new Fetchja({
   baseURL: 'https://api.example.com',
-  fetchFunction: (url, options) => myCustomFetch(url.href, options)
+  pluralize: false
 })
 ```

package/src/index.js

@@ -1,243 +0,0 @@
-import pluralize from 'pluralize'
-
-import { deserialize } from './utils/deserialize.js'
-import { serialize } from './utils/serialize.js'
-
-import { errorParser } from './utils/error-parser.js'
-import { queryFormatter } from './utils/query-formatter.js'
-import { splitModel } from './utils/split-model.js'
-
-import { camelCase } from './utils/camel-case.js'
-import { kebabCase } from './utils/kebab-case.js'
-import { snakeCase } from './utils/snake-case.js'
-
-const jsonType = 'application/vnd.api+json'
-
-/**
- * Options for Fetchja.
- * 
- * @typedef {Object} FetchjaOptions
- * @property {string} baseURL The base URL for all requests.
- * @property {Function} fetchFunction A custom fetch function to use in request.
- * @property {Object} headers The headers to include in all requests.
- * @property {Function} queryFormatter A function to format query parameters.
- * @property {string} resourceCase The case to use for resource names.
- * @property {boolean} pluralize Pluralize resource names.
- */
-
-/**
- * Fetchja is a simple wrapper around the Fetch API.
- * 
- * @class Fetchja
- * @param {FetchjaOptions} [options] Options for Fetchja.
- */
-export default class Fetchja {
-  constructor (options = {
-    headers: {}
-  }) {
-    this.baseURL = options.baseURL
-
-    // Headers
-    this.headers = {
-      Accept: jsonType,
-      'Content-Type': jsonType,
-      ...options.headers
-    }
-
-    // Fetch Function
-    this.fetchFunction = options.fetchFunction
-
-    // Query
-    this.queryFormatter = typeof options.queryFormatter === 'function'
-      ? options.queryFormatter
-      : object => queryFormatter(object)
-
-    // Camel Case Types
-    this.camelCaseTypes = options.camelCaseTypes === false
-      ? string => string
-      : camelCase
-
-    // Resource Case
-    const cases = {
-      camel: camelCase,
-      kebab: kebabCase,
-      snake: snakeCase,
-
-      default: string => string
-    }
-
-    this.resourceCase = cases[options.resourceCase] || cases.default
-    
-    // Pluralise
-    this.pluralize = options.pluralize === false
-      ? string => string
-      : pluralize
-
-    // Interceptors
-    this.onResponseError = error => error
-
-    // Alias
-    this.fetch = this.get
-    this.update = this.patch
-    this.create = this.post
-    this.remove = this.delete
-  }
-
-  #splitModel (model) {
-    return splitModel(model, {
-      resourceCase: this.resourceCase,
-      pluralize: this.pluralize
-    })
-  }
-
-  async request (options = {
-    method: 'GET',
-    headers: {}
-  }) {
-    const baseURL = this.baseURL || options.baseURL
-
-    const url = new URL(
-      options.url.startsWith('/') ? options.url.slice(1) : options.url,
-      baseURL.endsWith('/') ? baseURL : baseURL + '/'
-    )
-
-    // Params
-    if (options.params) {
-      url.search = this.queryFormatter(options.params)
-    }
-
-    // Body
-    if (options.body) {
-      options.body = serialize(options.type, options.body, {
-        camelCaseTypes: this.camelCaseTypes,
-        pluralTypes: this.pluralize
-      })
-    }
-
-    // Request
-    const makeRequest = () => {
-      // Headers
-      const headers = new Headers({
-        ...this.headers,
-        ...options.headers
-      })
-
-      // Fetch
-      const fetchOptions = {
-        method: options.method,
-        body: options.body,
-        headers
-      }
-
-      if (typeof this.fetchFunction === 'function') {
-        return this.fetchFunction(url, fetchOptions)
-      }
-
-      return fetch(url, fetchOptions)
-    }
-
-    try {
-      let response = await makeRequest()
-
-      if (!response.ok) {
-        response.replayRequest = makeRequest
-
-        const replayedResponse = await this.onResponseError(response)
-
-        if (replayedResponse instanceof Response) {
-          response = replayedResponse
-        }
-
-        if (!response.ok) {
-          throw new Error(response.statusText)
-        }
-      }
-
-      // Response Headers
-      const responseHeaders = {}
-
-      for (const [key, value] of response.headers.entries()) {
-        responseHeaders[key] = value
-      }
-
-      const contentType = responseHeaders['content-type']
-
-      // Response Data
-      const data = contentType && contentType.includes(jsonType)
-        ? await response.json()
-        : {}
-
-      // Return
-      return {
-        ...(data.errors ? data : deserialize(data)),
-
-        status: response.status,
-        statusText: response.statusText,
-        headers: responseHeaders
-      }
-    } catch (error) {
-      throw error
-    }
-  }
-
-  get (model, options = { method: 'GET' }) {
-    try {
-      options.url = model.split('/')
-        .map(part => this.resourceCase(part))
-        .filter(Boolean)
-        .join('/')
-
-      return this.request(options)
-    } catch (error) {
-      throw errorParser(error)
-    }
-  }
-
-  patch (model, body, options = { method: 'PATCH' }) {
-    try {
-      const [type, url] = this.#splitModel(model)
-
-      return this.request({
-        url: body?.id ? `${url}/${body.id}` : url,
-        body,
-        type,
-
-        ...options
-      })
-    } catch (error) {
-      throw errorParser(error)
-    }
-  }
-
-  post (model, body, options = { method: 'POST' }) {
-    try {
-      const [type, url] = this.#splitModel(model)
-
-      return this.request({
-        url,
-        body,
-        type,
-
-        ...options
-      })
-    } catch (error) {
-      throw errorParser(error)
-    }
-  }
-
-  delete (model, id, options = { method: 'DELETE' }) {
-    try {
-      const [type, url] = this.#splitModel(model)
-
-      return this.request({
-        url: `${url}/${id}`,
-        body: { id },
-        type,
-
-        ...options
-      })
-    } catch (error) {
-      throw errorParser(error)
-    }
-  }
-}

package/src/utils/camel-case.js

@@ -1,12 +0,0 @@
-/**
- * Convert a string from snake_case and kebab-case to camelCase.
- *
- * @param {string} input The string to convert.
- * @returns {string} The converted string.
- */
-export function camelCase (input) {
-  return input
-    .toLowerCase()
-    .replace(/[-_](.)/g, (_, char) => char.toUpperCase())
-    .replace(/^(.)/, (char) => char.toLowerCase())
-}

package/src/utils/deattribute.js

@@ -1,28 +0,0 @@
-/**
- * Deattribute JSON:API data.
- *
- * @param {Object|Object[]} data The JSON:API data to deattribute.
- * @returns {Object} The deattributed data.
- */
-export function deattribute (data) {
-  if (Array.isArray(data)) {
-    return data.map(deattribute)
-  }
-
-  const output = {
-    type: data.type,
-    id: data.id
-  }
-
-  for (const key in data.attributes) {
-    output[key] = data.attributes[key]
-  }
-
-  for (const key in data.relationships) {
-    if (data.relationships[key].data) {
-      output[key] = data.relationships[key].data
-    }
-  }
-
-  return output
-}