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>

• 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:
    • ({ result, params }) => mapped
    • { source: Store, fn: (data, { result, params }) => mapped }

• concurrency?: concurrency settings for the Query

  • strategy?: available values:
    • TAKE_EVERY execute every request
    • TAKE_FIRST skip all requests if there is a pending one
    • TAKE_LATEST (default value) cancel all pending requests and execute the latest one
  • abort?: Event after calling which all in-flight requests will be aborted

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 { runtypeContract } from '@farfetched/runtypes';
import { useUnit } from 'effector-vue/composition';
import { Record, String, Array } from 'runtypes';

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

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>