createJsonQuery

Formulae

createJsonQuery(config)

Config fields:

• params?: parameters for the Query

  • You can declare Query parameters by call declareParams function.
  • If not passed, Query will be created without parameters.

• initialData?: initial data of the Query, will be passed to the $data store as an initial value

• request: declarative rules to formulate request to the API.

  • method: String
  • url: Sourced string
  • body: Sourced Json, any value which can be serialized to JSON and parsed back without loses by JavaScript native module JSON. For example, { a: 1, b: 2 }. Note that body cannot be used in GET and HEAD requests.
  • query?: Sourced object, keys of the object must be String and values must be String or Array<String> or (since v0.8) Sourced String containing ready-to-use query string
  • headers?: Sourced object, keys of the object must be String and values must be String or Array<String>
  • credentials?: deprecated String, available values. Deprecated: use fetch.credentials instead.
    • omit — do not include credentials
    • same-origin — include credentials only if the request URL is the same origin
    • include — include credentials on all requests
  • fetch?: since v0.14.3 Object or Store with Object, additional RequestInit options to pass to the underlying fetch request. This allows configuring options like mode, cache, redirect, referrerPolicy, integrity, keepalive, etc. If credentials is specified both at the top level and in fetch, the top-level value takes precedence.

• response: declarative rules to handle response from the API.

  • contract: Contract allows you to validate the response and decide how your application should treat it — as a success response or as a failed one.

  • validate?: Validator allows you to dynamically validate received data.

  • mapData?: optional mapper for the response data, available overloads:

    • (res) => mapped
    • { source: Store, fn: (data, res) => mapped }

    res object contains:

    • result: parsed and validated response data
    • params: params which were passed to the Query
    • headers: since v0.13 raw response headers

  • mapError?: since v0.14 optional mapper for the error data, available overloads:

    • (err) => mapped
    • { source: Store, fn: (err, data) => mapped }

    err object contains:

    • error: the error that occurred (can be HttpError, NetworkError, InvalidDataError, or PreparationError)
    • params: params which were passed to the Query
    • headers: raw response headers (available for HTTP errors and contract/validation errors, not available for network errors)

Showcases

• Real-world showcase with SolidJS around JSON API
• Real-world showcase with React around JSON API
• Real-world showcase with Forest around JSON API

Live demo

You can play around with the factory in the live demo below 👇

<script setup>
import { createJsonQuery } from '@farfetched/core';
import { obj, str, arr } from '@withease/contracts';
import { useUnit } from 'effector-vue/composition';

const randomQuotesQuery = createJsonQuery({
  initialData: [],
  request: {
    method: 'GET',
    url: ({ amount }) =>
      `https://api.breakingbadquotes.xyz/v1/quotes/${amount}`,
  },
  response: {
    /*
     * We use @withease/contracts to validate response,
     * but you can replace it with other library, see 👇
     * https://ff.effector.dev/tutorial/contracts.html#third-party-solutions
     */
    contract: arr(
      obj({
        author: str,
        quote: str,
      })
    ),
  },
});

const { pending, data } = useUnit(randomQuotesQuery);

function handleClick() {
  randomQuotesQuery.start({ amount: 10 });
}
</script>

<template>
  <button @click="handleClick()">Load</button>
  <p v-if="pending">Loading...</p>
  <div v-else>
    <p>Random quores</p>
    <ul>
      <li v-for="quote in data" :key="quote.quote">
        {{ quote.quote }} - {{ quote.author }}
      </li>
    </ul>
  </div>
</template>

Open Sandbox