useDatx API

useInitialize

On the server side it is important to create an entirely new instance of Datx Client for each request. Otherwise, your response to a request might include sensitive cached query results from a previous request.

const client = useInitialize(() => new Client());

useClient

For accessing Client instance from the context. It's made mainly for internal usage.

const client = useClient();

useDatx

const expression: IGetManyExpression<typeof Todo> = {
  op: 'getMany',
  type: 'todos',
};

const config: DatxConfiguration<Todo, Array<Todo>> = {
  // datx config
  networkConfig: {
    headers: {
      'Accept-Language': 'en',
    }
  },
  // SWR config
  onSuccess: (data) => console.log(data.data[0].id),
}

const = useDatx(expression, config);

Second parameter of useDatx is for passing config options. It extends default SWR config prop with additional networkConfig property useful for passing custom headers.

Expression signature

Currently, we support 5 expressions for fetching resources getOne, getMany, getAll, getRelatedResource and getRelatedResources.

// fetch single resource by id
export interface IGetOneExpression<TModel extends JsonapiModelType = JsonapiModelType> {
  readonly op: 'getOne';
  readonly type: TModel['type'];
  id: string;
  queryParams?: IRequestOptions['queryParams'];
}

// fetch resource collection
export interface IGetManyExpression<TModel extends JsonapiModelType = JsonapiModelType> {
  readonly op: 'getMany';
  readonly type: TModel['type'];
  queryParams?: IRequestOptions['queryParams'];
}

// fetch all the pages of resource collection
export interface IGetAllExpression<TModel extends JsonapiModelType = JsonapiModelType> {
  readonly op: 'getAll';
  readonly type: TModel['type'];
  queryParams?: IRequestOptions['queryParams'];
  maxRequests?: number | undefined;
}

// fetch single related resource through the primary resource
export interface IGetRelatedResourceExpression<
  TModelType extends JsonapiModelType = JsonapiModelType,
> {
  readonly op: 'getRelatedResource';
  readonly type: TModelType['type'];
  readonly relation: string;
  id: string;
  queryParams?: IRequestOptions['queryParams'];
}

// fetch a collection of related resources through the primary resource
export interface IGetRelatedResourcesExpression<
  TModelType extends JsonapiModelType = JsonapiModelType,
> {
  readonly op: 'getRelatedResources';
  readonly type: TModelType['type'];
  readonly relation: string;
  id: string;
  queryParams?: IRequestOptions['queryParams'];
}

useDatxInfinite

For fetching paginated data. It uses useSWRInfinite internally so all the options from the documentation can be applied to useDatxInfinite.

const getPageExpression = (index: number, size = 10) => ({
  op: 'getMany',
  type: 'todos',
  queryParams: {
    custom: [
      { key: 'page[index]', value: String(index) },
      { key: 'page[size]', value: String(size) },
    ] as const,
  },
} as const satisfies IGetManyExpression<typeof Todo>);
// omit `satisfies IGetManyExpression<typeof Todo>` if you are using typescript < 4.9

const config: DatxInfiniteConfiguration<Todo> = {
  // datx config
  networkConfig: {
    headers: {
      'Accept-Language': 'en',
    }
  },
  // SWR config
  onSuccess: (data) => console.log(data[0].data[0].id),
}

const getKey = (pageIndex: number, previousPageData: CollectionResponse) => {
  if (previousPageData && previousPageData.data.length === 0) return null;

  return getPageExpression(pageIndex);
};

const { data: responses, error, size, setSize } = useDatxInfinite(getKey, config);

Second parameter of useDatxInfinite is for passing config options. It extends default SWRInfinite config prop with additional networkConfig property useful for passing custom headers.

Core expression should always be a getMany operation.

useMutation

A hook for remote mutations. This is a helper hook until this is merged to SWR core!

// ./src/queries/todo.ts

import { IGetManyExpression } from '@datx/swr';

import { Todo } from '../models/Todo';

export const querytodos: IGetManyExpression<typeof Todo> = {
  op: 'getMany',
  type: 'todos',
};

// ./src/mutations/todo.ts

import { getModelEndpointUrl, modelToJsonApi } from '@datx/jsonapi';
import { IClientInstance } from '@datx/swr';

import { Todo } from '../models/Todo';

export const createTodo = (client: IClientInstance, message: string | undefined) => {
  const model = new Todo({ message });
  const url = getModelEndpointUrl(model);
  const data = modelToJsonApi(model);

  return client.request<Todo, Array<Todo>>(url, 'POST', { data });
};

import { useMutation, useDatx } from '@datx/swr';

export const Todos: FC = () => {
  const { data, error, mutate } = useDatx(todosQuery);

  const [create, { status }] = useMutation(createTodo, {
    onSuccess: async () => {
      mutate();
    },
  });

  // ...
};

Utils

SWR Client

fetchQuery

Takes in an expression as an argument and returns a promise with the response. Useful on server side for fetching data before rendering.

const client = createClient();

const todo = await client.fetchQuery(todosQuery);

requestSingle and requestCollection

Same as request but with a bit more type safety.

const client = createClient();

const todo = await client.requestSingle('todos/1', 'GET', undefined); // returns SingleResponse
const todos = await client.requestCollection('todos', 'GET', undefined); // returns CollectionResponse

_ request should not be used with swr, and it will throw an error if used. _

hydrate

type Fallback = Record<string, IRawResponse>

const fallback = {
  '/api/v1/todos': rawResponse
}

<Hydrate fallback={fallback} />