fetchium

API reference for the main fetchium package — a data-fetching and query layer built on Signalium's reactive primitives.

import {
  Query,
  QueryAdapter,
  fetchQuery,
  queryKeyForClass,
  Mutation,
  getMutation,
  mutationKeyForClass,
  Entity,
  QueryClient,
  NetworkManager,
  NoOpNetworkManager,
  GcManager,
  NoOpGcManager,
  t,
  registerFormat,
  draft,
  QueryClientContext,
  NetworkManagerContext,
} from 'fetchium';

// REST adapter (JSON REST APIs)
import { RESTQuery, RESTMutation, RESTQueryAdapter } from 'fetchium/rest';

Classes

Query (abstract)

Base class for all query definitions. Extend this to define custom data-fetching logic.

Static properties

Static properties

Instance properties

Methods

RESTQuery extends Query

Convenience base class for REST/JSON queries. Handles URL construction, search params, body serialization, and pagination.

Instance properties

getIdentityKey() default

Returns "${method}:${path}".

Optional method overrides

Example

class GetUser extends RESTQuery {
  params = { id: t.string };

  path = `/api/users/${this.params.id}`;

  result = {
    id: t.id,
    name: t.string,
    email: t.string,
  };
}

Entity

Base class for entity definitions. Entities are normalized, identity-stable proxy objects managed by the QueryClient.

Static properties

Optional instance methods

Example

class User extends Entity {
  static cache = { gcTime: 10 };

  __typename = t.typename('User');
  id = t.id;

  name = t.string;
  email = t.optional(t.string);
}

Mutation (abstract)

Base class for mutation definitions.

Static properties

Instance properties

Methods

RESTMutation extends Mutation

Convenience base class for REST/JSON mutations.

Instance properties

getIdentityKey() default

Returns "${method}:${path}".

Optional method overrides

QueryClient

Central coordinator for queries, mutations, entity storage, caching, and garbage collection.

Constructor

new QueryClient(config: QueryClientConfig)

Every config key, including keys this table does not list, also reaches query and mutation code as this.context, so you can pass your own services through the config. The names in the table are reserved: a value under one of them is read as that option, so do not reuse them for your own context values.

Methods

prefetch and retain

Both take a lease: the queries stay active (fetched, subscribed, exempt from GC) without a component reading them. A reader that mounts while the lease is held joins the active query, so it starts no request of its own and renders the data on its first render if it has arrived. Both return an idempotent release function. Releasing never interrupts other readers; once the last one goes, the query deactivates and its gcTime starts as usual. Calling release while a fetch is in flight, with no reader, aborts that fetch. A ttl is an upper bound: the lease goes when it runs out even if the fetch is still in flight (offline, or a topic never fulfilled), which aborts the fetch unless a reader has joined it. Call retain and prefetch from event handlers or effects, not from inside a reactive computation; called from one, they warn in development and keep only the leases from the computation's latest run.

prefetch is for the moment a user commits to a navigation, such as a tap. Call it in the handler, before navigating:

function onPressToken(id: string) {
  queryClient.prefetch(GetTokenDetail, { id }, { ttl: 5_000 });
  router.push(`/token/${id}`);
}

With a synchronous store, a cached result is applied inside the call. A fresh one makes no request, and a stale one is refetched, as on any activation.

retain keeps a set of queries warm, for example the queries of a screen that is hidden but likely to come back. fn runs immediately, with the client as QueryClientContext, and again when what it reads changes. It holds a query when it reads one of the query's fields, or when it returns the query's promise or an array of them:

const release = queryClient.retain(() => [
  fetchQuery(GetPortfolio),
  fetchQuery(GetPrices, { ids }),
]);
// when the surface is gone for good:
release();

Without a ttl, a retain lease lasts until release is called.

QueryAdapter (abstract)

Base class for transport adapters. An adapter handles sending queries and mutations for all query/mutation classes that declare it via static adapter. Register adapters with QueryClient at construction time.

Methods

Properties

Protected properties

Example

import { QueryAdapter } from 'fetchium';
import type { Query } from 'fetchium';

class GraphQLAdapter extends QueryAdapter {
  async send(ctx: Query, signal: AbortSignal): Promise<unknown> {
    const q = ctx as GraphQLQuery;
    const response = await fetch('/graphql', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query: q.query, variables: q.variables }),
      signal,
    });
    const json = await response.json();
    if (json.errors?.length) throw new Error(json.errors[0].message);
    return json.data;
  }
}

new QueryClient({
  store,
  adapters: [new GraphQLAdapter()],
});

RESTQueryAdapter extends QueryAdapter

Transport adapter for RESTQuery and RESTMutation. Handles URL construction, JSON serialization, search params, pagination, and baseUrl resolution.

Import from fetchium/rest.

Constructor

new RESTQueryAdapter(options?: RESTQueryAdapterOptions)

NetworkManager

Signal-based network connectivity tracker. Automatically detects browser online/offline events.

Constructor

new NetworkManager(initialStatus?: boolean)

Properties and methods

NoOpNetworkManager

SSR-safe no-op implementation of NetworkManager. Always reports isOnline = true.

GcManager

Bucket-based in-memory garbage collection. Each unique gcTime gets its own interval with two rotating sets. Minimum eviction delay is approximately gcTime; maximum is approximately 2 * gcTime.

Constructor

new GcManager(
  onEvict: (key: number, type: GcKeyType) => void,
  multiplier?: number,
)

Methods

NoOpGcManager

No-op garbage collection manager. All methods are no-ops.

Functions

fetchQuery

function fetchQuery<T extends Query>(
  QueryClass: new () => T,
  params?: ExtractQueryParams<T>,
): QueryPromise<T>;

Fetches a query reactively. Must be called within a reactive context where QueryClientContext is provided. Returns a QueryPromise (a ReactivePromise) that resolves to the query result.

Returns: QueryPromise<T> — a reactive promise with .value, .isPending, .isResolved, .isRejected, .error.

getMutation

function getMutation<T extends Mutation>(
  MutationClass: new () => T,
): ReactiveTask<ExtractType<T['result']>, [ExtractType<T['params']>]>;

Returns a ReactiveTask for executing a mutation. Must be called within a reactive context where QueryClientContext is provided.

Returns: ReactiveTask — call .run(params) to execute the mutation.

queryKeyForClass

function queryKeyForClass(cls: new () => Query, params: unknown): number;

Computes the numeric cache key for a query class and params combination. Useful for cache invalidation or inspection.

mutationKeyForClass

function mutationKeyForClass(cls: new () => Mutation): string;

Returns the string identity key for a mutation class. Derived from the mutation's getIdentityKey().

registerFormat

function registerFormat<Input extends Mask.STRING | Mask.NUMBER, T>(
  name: string,
  type: Input,
  parse: (value: Input extends Mask.STRING ? string : number) => T,
  serialize: (value: T) => Input extends Mask.STRING ? string : number,
  options?: { eager?: boolean },
): void;

Registers a custom format for use with t.format(name). Built-in formats include 'date' and 'date-time'.

To add TypeScript types for custom formats, use module augmentation:

declare global {
  namespace SignaliumQuery {
    interface FormatRegistry {
      'my-format': MyType;
    }
  }
}

draft

function draft<T>(value: T): Draft<T>;

Deep clones an entity or object, returning a plain mutable copy. The draft is not an entity proxy and can be freely modified before being passed to a mutation.

Returns: Draft<T> — a recursively mutable deep clone.

The t Type DSL

The t object provides a declarative type definition DSL for describing query parameters, results, and entity shapes.

Primitive types

Composite types

Modifiers

Constants and enums

Formats

Result parsing

Live data

LiveArrayOptions<E>

LiveValueOptions<V, E>

Contexts

Types

Query types

QueryConfigOptions properties

Mutation types

Network types

NetworkMode values

Retry types

Utility types

Store types