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)

Methods

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

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 DiscriminatedReactivePromise) 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