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?: since v0.7 String, available values:
    • omit — do not include credentials
    • same-origin — include credentials only if the request URL is the same origin
    • include — include credentials on all requests

• 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