Introduce request.fetchOptions feature to createJson* methods

Author: AlexandrHoroshih

.changeset/wise-adults-doubt.md

@@ -0,0 +1,5 @@
+---
+'@farfetched/core': minor
+---
+
+Introduce `request.fetchOptions` feature to createJson\* methods

apps/website/docs/api/factories/create_json_mutation.md

@@ -20,6 +20,7 @@ Config fields:
     - `omit` — do not include credentials
     - `same-origin` — include credentials only if the request URL is the same origin
     - `include` — include credentials on all requests
+  - `fetchOptions?`: <Badge type="tip" text="since v0.14.3" /> _Object or [Store](https://effector.dev/docs/api/effector/Store) with Object_, additional [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) 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 `fetchOptions`, the top-level value takes precedence.
 
 - `response`: declarative rules to handle response from the API.
   - `contract`: [_Contract_](/api/primitives/contract) allows you to validate the response and decide how your application should treat it — as a success response or as a failed one.

apps/website/docs/api/factories/create_json_query.md

@@ -22,6 +22,7 @@ Config fields:
     - `omit` — do not include credentials
     - `same-origin` — include credentials only if the request URL is the same origin
     - `include` — include credentials on all requests
+  - `fetchOptions?`: <Badge type="tip" text="since v0.14.3" /> _Object or [Store](https://effector.dev/docs/api/effector/Store) with Object_, additional [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request#options) 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 `fetchOptions`, the top-level value takes precedence.
 
 - `response`: declarative rules to handle response from the API.
   - `contract`: [_Contract_](/api/primitives/contract) allows you to validate the response and decide how your application should treat it — as a success response or as a failed one.

packages/core/src/fetch/__tests__/api.request.fetchOptions.test.ts

@@ -0,0 +1,199 @@
+import { allSettled, createStore, fork } from 'effector';
+import { describe, test, expect, vi } from 'vitest';
+
+import { createApiRequest, type FetchOptions } from '../api';
+import { fetchFx } from '../fetch';
+
+describe('fetch/api.request.fetchOptions', () => {
+  // Does not matter
+  const mapBody = () => 'any body';
+  const url = 'https://api.salo.com';
+  const method = 'GET';
+
+  // Does not matter
+  const response = {
+    extract: async <T>(v: T) => v,
+  };
+
+  test('pass static fetchOptions on creation to request', async () => {
+    const callApiFx = createApiRequest({
+      request: {
+        mapBody,
+        method,
+        url,
+        fetchOptions: {
+          mode: 'cors',
+          cache: 'no-cache',
+          referrerPolicy: 'no-referrer',
+        },
+      },
+      response,
+    });
+
+    const fetchMock = vi.fn().mockResolvedValue(new Response('test'));
+
+    const scope = fork({ handlers: [[fetchFx, fetchMock]] });
+
+    await allSettled(callApiFx, { scope, params: {} });
+
+    const request = fetchMock.mock.calls[0][0] as Request;
+    expect(request.mode).toEqual('cors');
+    expect(request.cache).toEqual('no-cache');
+    expect(request.referrerPolicy).toEqual('no-referrer');
+  });
+
+  test('pass reactive fetchOptions on creation to request', async () => {
+    const $fetchOptions = createStore<FetchOptions>({
+      mode: 'cors',
+      cache: 'no-cache',
+    });
+
+    const callApiFx = createApiRequest({
+      request: { mapBody, method, url, fetchOptions: $fetchOptions },
+      response,
+    });
+
+    const fetchMock = vi.fn().mockResolvedValue(new Response('test'));
+
+    const scope = fork({ handlers: [[fetchFx, fetchMock]] });
+
+    // with original value
+    await allSettled(callApiFx, { scope, params: {} });
+    let request = fetchMock.mock.calls[0][0] as Request;
+    expect(request.mode).toEqual('cors');
+    expect(request.cache).toEqual('no-cache');
+
+    // with new value
+    await allSettled($fetchOptions, {
+      scope,
+      params: { mode: 'no-cors', cache: 'force-cache' },
+    });
+    await allSettled(callApiFx, { scope, params: {} });
+    request = fetchMock.mock.calls[1][0] as Request;
+    expect(request.mode).toEqual('no-cors');
+    expect(request.cache).toEqual('force-cache');
+  });
+
+  test('top-level credentials takes precedence over fetchOptions.credentials', async () => {
+    const callApiFx = createApiRequest({
+      request: {
+        mapBody,
+        method,
+        url,
+        credentials: 'include',
+        fetchOptions: {
+          credentials: 'omit',
+          cache: 'no-cache',
+        },
+      },
+      response,
+    });
+
+    const fetchMock = vi.fn().mockResolvedValue(new Response('test'));
+
+    const scope = fork({ handlers: [[fetchFx, fetchMock]] });
+
+    await allSettled(callApiFx, { scope, params: {} });
+
+    const request = fetchMock.mock.calls[0][0] as Request;
+    // top-level credentials should win
+    expect(request.credentials).toEqual('include');
+    // other fetchOptions should still apply
+    expect(request.cache).toEqual('no-cache');
+  });
+
+  test('fetchOptions.credentials is used when top-level credentials is not set', async () => {
+    const callApiFx = createApiRequest({
+      request: {
+        mapBody,
+        method,
+        url,
+        fetchOptions: {
+          credentials: 'include',
+        },
+      },
+      response,
+    });
+
+    const fetchMock = vi.fn().mockResolvedValue(new Response('test'));
+
+    const scope = fork({ handlers: [[fetchFx, fetchMock]] });
+
+    await allSettled(callApiFx, { scope, params: {} });
+
+    const request = fetchMock.mock.calls[0][0] as Request;
+    expect(request.credentials).toEqual('include');
+  });
+
+  test('pass fetchOptions with keepalive option', async () => {
+    const callApiFx = createApiRequest({
+      request: {
+        mapBody,
+        method,
+        url,
+        fetchOptions: {
+          keepalive: true,
+        },
+      },
+      response,
+    });
+
+    const fetchMock = vi.fn().mockResolvedValue(new Response('test'));
+
+    const scope = fork({ handlers: [[fetchFx, fetchMock]] });
+
+    await allSettled(callApiFx, { scope, params: {} });
+
+    const request = fetchMock.mock.calls[0][0] as Request;
+    expect(request.keepalive).toEqual(true);
+  });
+
+  test('pass fetchOptions with redirect option', async () => {
+    const callApiFx = createApiRequest({
+      request: {
+        mapBody,
+        method,
+        url,
+        fetchOptions: {
+          redirect: 'manual',
+        },
+      },
+      response,
+    });
+
+    const fetchMock = vi.fn().mockResolvedValue(new Response('test'));
+
+    const scope = fork({ handlers: [[fetchFx, fetchMock]] });
+
+    await allSettled(callApiFx, { scope, params: {} });
+
+    const request = fetchMock.mock.calls[0][0] as Request;
+    expect(request.redirect).toEqual('manual');
+  });
+
+  test('pass fetchOptions with integrity option', async () => {
+    const integrityValue =
+      'sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC';
+
+    const callApiFx = createApiRequest({
+      request: {
+        mapBody,
+        method,
+        url,
+        fetchOptions: {
+          integrity: integrityValue,
+        },
+      },
+      response,
+    });
+
+    const fetchMock = vi.fn().mockResolvedValue(new Response('test'));
+
+    const scope = fork({ handlers: [[fetchFx, fetchMock]] });
+
+    await allSettled(callApiFx, { scope, params: {} });
+
+    const request = fetchMock.mock.calls[0][0] as Request;
+    expect(request.integrity).toEqual(integrityValue);
+  });
+});

packages/core/src/fetch/api.ts

@@ -33,6 +33,12 @@ export type HttpMethod =
 
 export type RequestBody = Blob | BufferSource | FormData | string;
 
+// Future-proof: automatically includes any new RequestInit fields from the browser
+export type FetchOptions = Omit<
+  RequestInit,
+  'method' | 'headers' | 'body' | 'signal'
+>;
+
 // These settings can be defined only statically
 export interface StaticOnlyRequestConfig<B> {
   method: StaticOrReactive<HttpMethod>;
@@ -43,6 +49,7 @@ export interface StaticOnlyRequestConfig<B> {
 export interface ExclusiveRequestConfigShared {
   url: string;
   credentials?: RequestCredentials;
+  fetchOptions?: FetchOptions;
   abortController?: AbortController;
 }
 
@@ -139,17 +146,23 @@ export function createApiRequest<
       query,
       headers,
       credentials,
+      fetchOptions,
       body,
       abortController,
     }) => {
       const mappedBody = body ? config.request.mapBody(body) : null;
 
       const request = new Request(formatUrl(url, query), {
+        ...fetchOptions,
         method,
         headers: formatHeaders(headers),
-        credentials,
         body: mappedBody,
         signal: abortController?.signal,
+        /**
+         * `credentials` is available both in `fetchOptions` and in the top-level config.
+         * The top-level config was introduced much earlier, so it takes precedence.
+         */
+        ...(credentials !== undefined ? { credentials } : {}),
       });
 
       const response = await requestFx(request).catch((cause: RequestError) => {
@@ -240,6 +253,7 @@ export function createApiRequest<
       query: normalizeStaticOrReactive(config.request.query),
       headers: normalizeStaticOrReactive(config.request.headers),
       credentials: normalizeStaticOrReactive(config.request.credentials),
+      fetchOptions: normalizeStaticOrReactive(config.request.fetchOptions),
       body: normalizeStaticOrReactive(config.request.body),
     },
     mapParams(dynamicConfig: ApiRequestParams, staticConfig) {
@@ -250,11 +264,16 @@ export function createApiRequest<
         // @ts-expect-error TS cannot infer type correctly, but there is always field in staticConfig or dynamicConfig
         dynamicConfig.url;
 
-      const credentials: RequestCredentials =
+      const credentials: RequestCredentials | undefined =
         staticConfig.credentials ??
         // @ts-expect-error TS cannot infer type correctly, but there is always field in staticConfig or dynamicConfig
         dynamicConfig.credentials;
 
+      const fetchOptions: FetchOptions | undefined =
+        staticConfig.fetchOptions ??
+        // @ts-expect-error TS cannot infer type correctly, but there is always field in staticConfig or dynamicConfig
+        dynamicConfig.fetchOptions;
+
       const body: B =
         staticConfig.body ??
         // @ts-expect-error TS cannot infer type correctly, but there is always field in staticConfig or dynamicConfig
@@ -276,6 +295,7 @@ export function createApiRequest<
         query,
         headers,
         credentials,
+        fetchOptions,
         body,
         abortController,
       };

packages/core/src/index.ts

@@ -68,7 +68,7 @@ export { type ValidationResult, type Validator } from './validation/type';
 export { type Json } from 'effector';
 export { type JsonObject } from './fetch/json';
 export { type FetchApiRecord } from './fetch/lib';
-export { type JsonApiRequestError } from './fetch/api';
+export { type JsonApiRequestError, type FetchOptions } from './fetch/api';
 export { fetchFx } from './fetch/fetch';
 
 // Exposed errors