Devour JSON-API Client

Common errors

• Error: Resource 'comments' not defined in Devour's model directory.

  cause Attempting to interact with a JSON:API resource type (e.g., 'comments') that has not been defined using `jsonApi.define('comments', { ... })` in your client initialization.
  fix Define the missing resource model: `jsonApi.define('comments', { comment: '', post: { jsonApi: 'belongsTo', type: 'posts' } })` or ensure `disableErrorsForMissingResourceDefinitions` is set to `true` if you wish to suppress these errors.

• Failed to fetch

  cause This generic network error usually indicates that the client could not connect to the `apiUrl` specified, either due to incorrect URL, CORS issues, network problems, or the API server being down.
  fix Verify the `apiUrl` is correct and accessible. Check your browser's console for CORS errors. Ensure your API server is running and reachable from the client's environment.

• Response code 401 (Unauthorized)

  cause The API endpoint requires authentication, and the request was sent without proper authorization headers (e.g., bearer token, basic auth).
  fix Pass the necessary authentication details to the `JsonApi` constructor: `new JsonApi({ apiUrl: '...', bearer: 'YOUR_TOKEN' })` or `new JsonApi({ apiUrl: '...', auth: { username: 'user', password: 'pass' } })`.

Warnings

• gotcha Enabling `disableErrorsForMissingResourceDefinitions` can mask issues where your API returns resources not explicitly defined in your client-side models, leading to unexpected data handling or UI errors.
  Fix: Only use `disableErrorsForMissingResourceDefinitions: true` if you have a robust strategy for handling undefined resources. Otherwise, ensure all expected JSON:API resource types are defined using `jsonApi.define()`.
• gotcha By default, Devour Client uses the `pluralize` package for converting singular model names (e.g., 'post') to plural API endpoints (e.g., '/posts'). Inconsistent pluralization between your client and API can lead to 404 errors. If your API uses different pluralization rules or singular resource paths, you must configure or disable this behavior.
  Fix: Pass `pluralize: false` to the `JsonApi` constructor to disable, or provide a custom pluralization function: `new JsonApi({apiUrl: '...', pluralize: myCustomPluralizeFunc})`.
• gotcha The `resetBuilderOnCall` option defaults to `true`, which clears the query builder stack after each `get`, `post`, `patch`, or `destroy` call. If you intend to chain multiple operations or reuse parts of a builder for subsequent requests without re-initializing, you might get unexpected results.
  Fix: If you need to maintain builder state across calls, set `resetBuilderOnCall: false` in the `JsonApi` constructor options. Be mindful of managing the builder state manually if you disable this.
• breaking Devour Client's GitHub repository indicates 'Known Vulnerabilities' through Snyk. While specific CVEs are not detailed in the provided information, developers should be aware that dependencies or the client itself may have had or currently have security issues.
  Fix: Regularly check the Snyk badge or run `npm audit` and `snyk test` on your project dependencies. Update `devour-client` to the latest version to ensure you have security patches for any known vulnerabilities.

Install

• npm install devour-client npm
• yarn add devour-client yarn
• pnpm add devour-client pnpm

Imports

• JsonApi
  wrong:

  const JsonApi = require('devour-client')

  correct:

  import JsonApi from 'devour-client'

  Devour Client is primarily consumed as an ES module, though CommonJS usage might work in older Node environments, ESM is the recommended and modern approach.
• JsonApi
  wrong:

  const jsonApi = new JsonApi()

  correct:

  const jsonApi = new JsonApi({ apiUrl: 'http://your-api-here.com' })

  The `apiUrl` option is mandatory for instantiating the client to specify the API endpoint.

Quickstart

This quickstart initializes Devour Client, defines two JSON:API models ('post' and 'comment'), and demonstrates common CRUD operations (findAll, find, create, update, destroy) and arbitrary requests against a hypothetical API endpoint.

import JsonApi from 'devour-client'

// Bootstrap the client with your API endpoint
const jsonApi = new JsonApi({apiUrl:'http://your-api-here.com'})

// Define a model schema matching your JSON:API resources
jsonApi.define('post', {
  title: '',
  content: '',
  tags: [],
  comments: {
    jsonApi: 'hasMany',
    type: 'comments'
  }
})

jsonApi.define('comment', {
  comment: '',
  post: {
    jsonApi: 'belongsTo',
    type: 'posts'
  }
})

async function runExample() {
  try {
    // Fetch all posts with pagination
    const postsPage2 = await jsonApi.findAll('post', {page: {number: 2}});
    console.log('Posts on page 2:', postsPage2.data.map(p => p.title));

    // Fetch a single post by ID
    const post = await jsonApi.find('post', '5');
    console.log('Post 5:', post.data.title);

    // Create a new post
    const newPost = await jsonApi.create('post', {
      title: 'Hello from Devour!',
      content: 'This is some content for a new post.',
      tags: ['devour', 'jsonapi']
    });
    console.log('Created post:', newPost.data.title);

    // Update an existing post
    const updatedPost = await jsonApi.update('post', {
      id: newPost.data.id,
      title: 'Updated title',
      content: 'New content for the updated post',
      tags: ['devour', 'update']
    });
    console.log('Updated post:', updatedPost.data.title);

    // Delete a post
    await jsonApi.destroy('post', updatedPost.data.id);
    console.log('Deleted post:', updatedPost.data.id);

    // Make an arbitrary request
    const customRequest = await jsonApi.request('http://your-api-here.com/some-custom-endpoint', 'GET', { queryParam: 'value' });
    console.log('Custom request result:', customRequest);

  } catch (error) {
    console.error('API Error:', error.errors || error.message);
  }
}

runExample();