DataClient

The DataClient is the central state management engine of the Archibald framework. Its primary role is to manage the lifecycle of asynchronous data (fetches and mutations), providing a robust caching layer and a reactive subscription system for components.

It serves as the bridge for data between the server (during SSR) and the client (during hydration), ensuring a consistent application state across environments.

import { DataClient } from '@archibald/core';

export default new DataClient(OPTIONS);

Options

Type: DataClientOptions

The DataClientOptions object has the following properties:

Name	Type	Default	Description
cache	`DataCache`	`new DataCache()`	Provide a custom `DataCache` instance for the fetch cache.
mutationCache	`DataCache`	`new DataCache()`	Provide a custom `DataCache` instance for the mutation cache.
fetchOptions	`FetchOptions`	`{}`	Global config for fetches.
mutateOptions	`MutateOptions`	`{}`	Global config for mutations.

Type: FetchOptions

The FetchOptions object has the following properties:

Name	Type	Default	Description
cacheCheckInterval	`number`	`60` seconds	Defines interval for checking if cache entries are still valid or not.
clearOnRefetch	`boolean`	`true`	Defines if a cache entry should be deleted before being refetched.
enabled	`boolean`	`true`	Defines if the data fetching hooks are active or not.
enableOnlyWhenAllKeysTruthy	`boolean`	`false`	If `true`, the data fetching hooks will only be executed when all keys resolve to `true`.
throwOnError	`boolean`	`false`	If `true`, the fetch will throw on an error.
error	`number`	`5` seconds	Defines how long an error is kept in the cache.
errorBoundary	`boolean`	`false`	If `true`, errors are rethrown during render so they can be caught by the closest error boundary.
force	`boolean`	`false`	Execute the action ignoring all other configs.
maxEntries	`{ soft: number; hard: number; }`	`{ soft: 50, hard: 80 }`	`hard` Defines the maximum amount of entries that can be kept in the cache. Old cache entries will be removed if this limit is reached. `soft` Only active when `cacheCheckInterval` is configured. A cache entry will be removed when it is expired and when the number of cache entries is bigger than soft limit.
poll	`number`	`0`	Reexecute the data fetching hooks in the provided time interval.
refetch	`number`	`5` minutes	Reexecute the action to update the cache entry. The cache entry has to be used at least 1x after the original call of `useFetch` hook in order to activate this behavior.
refetchAfterFocus	`boolean`	`false`	Reexecute the data fetching hooks on window focus.
refetchAfterHydrate	`boolean`	`false`	Reexecute the data fetching hooks after the component has been hydrated.
safeReturnFromMutate	`boolean`	`true`	Save the `mutate` function response under the same key in the cache as the original response from the `useFetch` hook. The same applies to usage of the `useMutation` hook.
ssr	`boolean`	`true`	If `false`, the action will only be executed on the client.
stale	`boolean`	`true`	If `true`, stale data (past its `refetch` window but not yet expired) is served from the cache while a refetch happens in the background.
suspense	`boolean`	`true`	If `true`, the data fetching hooks will use the `suspense` mode.
ttl	`number`	`15` minutes	Defines how long an entry should be kept in the cache. Use `-1` for endless caching.
initial	`boolean`	`false`	If `true`, it returns the initial `DataCache` value which is used for hydration.
enduring	`boolean`	`false`	If `true`, cache values are never being evicted.

In addition, the underlying cache accepts further CacheOptions members that can be passed through: silent (suppress publish events on cache writes, default true), structuralSharing (keep the previous object reference for deep-equal payloads so subscribers don't re-render on structurally identical data, default true) and touch (when false, a write updates only the entry's data and leaves its lifetime stamps untouched, default true).

Type: MutateOptions

The MutateOptions object has the following properties (see DataMutateOptions in @archibald/core):

Name	Type	Default	Description
ttl	`number`	`15` minutes	Defines how long a mutation result should be kept in the mutation cache. Use `-1` for endless caching.
error	`number`	`5` seconds	Defines how long an error is kept in the mutation cache.
suspense	`boolean`	`false`	Deprecated. Suspending on a mutation throws the mutation promise during render, which unmounts the form and loses its local state. Use a React transition or form action instead.
throwOnError	`boolean`	`false`	If `true`, the mutation method will throw on an error.
errorBoundary	`boolean`	`false`	If `true`, mutation errors are rethrown during render so they can be caught by the closest error boundary.
clearKeyAfterMutate	`boolean`	`false`	If `true`, the mutation cache entry is cleared after the mutation completes.
enabled	`boolean`	`true`	Defines if the mutation is active or not.
keepError	`boolean`	`false`	If `true`, a previous error is kept in the cache when a new mutation run starts.

Methods

The most important public methods of the DataClient:

invalidate(key, options?, params?) — Marks the cache entry (or all entries matching a RegExp) as invalid and re-executes the associated action.
get(key, options?) — Returns the cached data for a key.
set(key, value, options?) — Writes a value into the cache under the given key and notifies subscribers.
delete(key, silent?) — Removes the cache entry (or all entries matching a RegExp) from the cache.
expire(key, silent?) — Marks the cache entry (or all entries matching a RegExp) as expired without deleting it.
clearAll() — Clears the entire fetch and mutation cache.
startPoll(key, options?) / stopPoll(key?) — Starts or stops interval polling for a key (stopPoll() without a key stops all polls).
setOptions(options?, override?) / getOptions() — Updates or reads the global fetch options at runtime (setMutateOptions / getMutateOptions exist for mutations).

Options​

Methods​

Options

Methods