Farfetched Data Fetching Library

Farfetched is currently in a feature freeze phase (since v0.12) to focus on stability and performance. The project aims to reach version 1.0 by the end of 2024, with new versions released every 2-3 months.

Upcoming Breaking Changes (v0.14)

Be prepared for the following removals in version 0.14:

• Removal of attachOperation.
• Removal of the concurrency field in createJsonQuery and createJsonMutation.

Planned Changes (v0.x - Pre-1.0)

Before the 1.0 release, the following improvements are planned:

• Standardized behavior specification for operators applied to single operations.
• Merging of contract and validate fields across all built-in factories.
• Developer Experience (DX) improvements for the update operator.

Future Features (v1.x - Post-1.0)

Post-1.0 development will focus on:

• API schema-based code generation.
• Native support for GraphQL and REST APIs.
• Support for Server-Sent Events (SSE) and Web Sockets.

In Farfetched, a Contract is a simple object used to validate remote data before it is used in your application. This follows the principle that frontend applications should never trust remote data blindly.

A Contract must implement two properties:

• isData: A function that takes any data and returns true if the data is valid, or false otherwise. If using TypeScript, this function should be a type predicate to allow for type narrowing.
• getErrorMessages: A function that takes the invalid data and returns an array of strings describing why the validation failed. This is only called if isData returns false.

By attaching a Contract to a factory (like createQuery), Farfetched will automatically validate the response and treat it as a success or failure based on the contract's result.

import { type Contract } from '@farfetched/core';

const numberContract: Contract<unknown, number> = {
  isData: (data): data is number => typeof data === 'number',
  getErrorMessages: (data) => {
    return [`Expected number, got ${typeof data}`];
  },
};

The filter option in the retry operator allows you to control when a retry should occur. You can use it to:

1. Retry only specific errors: Use error guards like isHttpErrorCode(code) from @farfetched/core.
2. Retry based on external state: Use a Sourced value (like an Effector Store or a boolean) to enable/disable retries based on application state (e.g., if a specific route is open).
3. Combine conditions: Use a function to check both the error type and the external state.

In Farfetched, a Sourced field can be a static value, a Store, a function, or a combination of these.

import { isHttpErrorCode } from '@farfetched/core';

// 1. Retry only 500 errors
retry(characterQuery, {
  times: 5,
  delay: 500,
  filter: isHttpErrorCode(500),
});

// 2. Retry only if a specific route is open (using Atomic Router example)
retry(characterQuery, {
  times: 5,
  delay: 500,
  filter: characterRoute.$isOpened,
});

// 3. Combine: Retry only 500 errors AND if the route is open
retry(characterQuery, {
  times: 5,
  delay: 500,
  filter: {
    source: characterRoute.$isOpened,
    fn: ({ error, params }, isCharacterRouteOpened) => 
      isCharacterRouteOpened && isHttpErrorCode(500)({ error }),
  },
});