Resource

Resources are a collection of RestEndpoints that operate on a common data by sharing a schema

Usage

resources/Todo.ts
export class Todo extends Entity {
  id = '';
  title = '';
  completed = false;

  static key = 'Todo';
}

const TodoResource = resource({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos/:id',
  schema: Todo,
});

Resources start with 6 Endpoints
const todo = useSuspense(TodoResource.get, { id: '5' });
const todos = useSuspense(TodoResource.getList);
controller.fetch(TodoResource.getList.push, {
  title: 'finish installing reactive data client',
});
controller.fetch(
  TodoResource.update,
  { id: '5' },
  { ...todo, completed: true },
);
controller.fetch(
  TodoResource.partialUpdate,
  { id: '5' },
  { completed: true },
);
controller.fetch(TodoResource.delete, { id: '5' });

Arguments

{
  path: string;
  schema: Schema;
  urlPrefix?: string;
  body?: any;
  searchParams?: any;
  paginationField?: string;
  optimistic?: boolean;
  Endpoint?: typeof RestEndpoint;
  Collection?: typeof Collection;
} & EndpointExtraOptions

path

Passed to RestEndpoint.path for single item .

Create (getList.push/getList.unshift) and getList remove the last argument.

const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
});

// GET /react/posts/abc
PostResource.get({ group: 'react', id: 'abc' });
// GET /react/posts
PostResource.getList({ group: 'react' });

schema

Passed to RestEndpoint.schema representing a single item. This is usually an Entity or Union.

getList uses an Array Collection of the schema.
delete uses a Invalidate of the schema.

paginationField

If specified, will add Resource.getList.getPage method on the Resource.

optimistic

true makes all mutation endpoints optimistic, making UI updates immediate, even before fetch completion.

Endpoint

Class used to construct the members.

import { RestEndpoint } from '@data-client/rest';

export default class AuthdEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  async getRequestInit(body: any): Promise<RequestInit> {
    return {
      ...(await super.getRequestInit(body)),
      credentials: 'same-origin',
    };
  }
}
const TodoResource = resource({
  path: '/todos/:id',
  schema: Todo,
  Endpoint: AuthdEndpoint,
});

Collection

Collection Class used to construct getList schema.

import { schema, resource } from '@data-client/rest';

class MyCollection<
  S extends any[] | PolymorphicInterface = any,
  Parent extends any[] = [urlParams: any, body?: any],
> extends schema.Collection<S, Parent> {
  // getList.push should add to Collections regardless of its 'orderBy' argument
  // in other words: `orderBy` is a non-filtering argument - it does not influence which results are returned
  nonFilterArgumentKeys(key: string) {
    return key === 'orderBy';
  }
}
const TodoResource = resource({
  path: '/todos/:id',
  searchParams: {} as { userId?: string; orderBy?: string } | undefined,
  schema: Todo,
  Collection: MyCollection,
});

EndpointExtraOptions

dataExpiryLength, errorExpiryLength, errorPolicy, invalidIfStale, pollFrequency

Members

These provide the standard CRUD endpointss common in REST APIs. Feel free to customize or add new endpoints based to match your API.

const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
  paginationField: 'page',
});

Name	Method	Args	Schema
get	GET	`[{group: string; id: string}]`	Post
getList	GET	`[{group: string; author?: string}]`	Collection([Post])
getList.push	POST	`[{group: string; author?: string}, Partial<Post>]`	Collection([Post]).push
getList.unshift	POST	`[{group: string; author?: string}, Partial<Post>]`	Collection([Post]).unshift
getList.getPage	GET	`[{group: string; author?: string; page: string}]`	Collection([Post]).addWith
update	PUT	`[{group: string; id: string }, Partial<Post>]`	Post
partialUpdate	PATCH	`[{group: string; id: string }, Partial<Post>]`	Post
delete	DELETE	`[{group: string; id: string }]`	Invalidate(Post)

get

Retrieve a singular entity.

Post

Resource

import Post from './Post';
export const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
});

▶Request

import { PostResource } from './Resource';
PostResource.get({
  group: 'react',
  id: '1',
});

Request

GET /react/posts/1
Content-Type: application/json

Response200

{
  "id": "1",
  "group": "react",
  "title": "this post",
  "author": "clara"
}

Field	Value
method	'GET'
path	path
schema	schema

Commonly used with useSuspense(), Controller.invalidate, Controller.expireAll

getList

Retrieve a list of entities.

Post

Resource

import Post from './Post';
export const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
});

▶Request

import { PostResource } from './Resource';
PostResource.getList({
  group: 'react',
  author: 'clara',
});

Request

GET /react/posts?author=clara
Content-Type: application/json

Response200

[
  {
    "id": "1",
    "group": "react",
    "title": "this post",
    "author": "clara"
  }
]

Field	Value
method	'GET'
path	removeLastArg(path)
searchParams	searchParams
paginationField	paginationField
schema	new schema.Collection([schema])

resource({ path: '/:first/:second' }).getList.path === '/:first';
resource({ path: '/:first' }).getList.path === '/';

Commonly used with useSuspense(), Controller.invalidate, Controller.expireAll

getList.push

RestEndpoint.push creates a new entity and pushes it to the end of getList. Use getList.unshift to place at the beginning instead.

Post

Resource

import Post from './Post';
export const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
});

▶Request

import { PostResource } from './Resource';
PostResource.getList.push(
  { group: 'react', author: 'clara' },
  { title: 'winning' },
);

Request

POST /react/posts?author=clara
Content-Type: application/json
Body: {"title":"winning"}

Response201

{
  "id": "2",
  "group": "react",
  "title": "winning",
  "author": "clara"
}

Field	Value
method	'POST'
path	removeLastArg(path)
searchParams	searchParams
body	body
schema	getList.schema.push

Commonly used with Controller.fetch

getList.unshift

RestEndpoint.unshift creates a new entity and pushes it to the beginning of getList.

Post

Resource

import Post from './Post';
export const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
});

▶Request

import { PostResource } from './Resource';
PostResource.getList.unshift(
  { group: 'react', author: 'clara' },
  { title: 'winning' },
);

Request

POST /react/posts?author=clara
Content-Type: application/json
Body: {"title":"winning"}

Response201

{
  "id": "2",
  "group": "react",
  "title": "winning",
  "author": "clara"
}

Field	Value
method	'POST'
path	removeLastArg(path)
searchParams	searchParams
body	body
schema	getList.schema.unshift

Commonly used with Controller.fetch

getList.getPage

RestEndpoint.getPage retrieves another page appending to getList ensuring there are no duplicates.

This member is only available when paginationField is specified.

Post

Resource

import Post from './Post';
export const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
  paginationField: 'page',
});

▶Request

import { PostResource } from './Resource';
PostResource.getList.getPage({
  group: 'react',
  author: 'clara',
  page: 2,
});

Request

GET /react/posts?author=clara&page=2
Content-Type: application/json

Response200

[
  {
    "id": "5",
    "group": "react",
    "title": "second page",
    "author": "clara"
  }
]

Field	Value
method	'GET'
path	removeLastArg(path)
searchParams	searchParams
paginationField	paginationField
schema	getList.schema.addWith

args: PathToArgs(shortenPath(path)) & searchParams & \{ [paginationField]: string | number \}

Commonly used with Controller.fetch

update

Update an entity.

Post

Resource

import Post from './Post';
export const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
});

▶Request

import { PostResource } from './Resource';
PostResource.update(
  { group: 'react', id: '1' },
  { title: 'updated title', author: 'clara' },
);

Request

PUT /react/posts/1
Content-Type: application/json
Body: {"title":"updated title","author":"clara"}

Response200

{
  "id": "1",
  "group": "react",
  "title": "updated title",
  "author": "clara"
}

Field	Value
method	'PUT'
path	path
body	body
schema	schema

Commonly used with Controller.fetch

partialUpdate

Update some subset of fields of an entity.

Post

Resource

import Post from './Post';
export const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
});

▶Request

import { PostResource } from './Resource';
PostResource.partialUpdate(
  { group: 'react', id: '1' },
  { title: 'updated title' },
);

Request

PATCH /react/posts/1
Content-Type: application/json
Body: {"title":"updated title"}

Response200

{
  "id": "1",
  "group": "react",
  "title": "updated title",
  "author": "clara"
}

Field	Value
method	'PATCH'
path	path
body	body
schema	schema

Commonly used with Controller.fetch

delete

Deletes an entity.

Post

Resource

import Post from './Post';
export const PostResource = resource({
  schema: Post,
  path: '/:group/posts/:id',
  searchParams: {} as { author?: string },
});

▶Request

import { PostResource } from './Resource';
PostResource.delete({ group: 'react', id: '1' });

Request

DELETE /react/posts/1
Content-Type: application/json

Response200

{
  "id": "1"
}

Field	Value
method	'DELETE'
path	path
schema	new schema.Invalidate(schema)
process	`(value, params) { return value && Object.keys(value).length ? value : params; },`

Commonly used with Controller.fetch

Response

{ "id": "xyz" }

Response should either be the pk as a string (like 'xyz'). Or an object with the members needed to compute Entity.pk (like {id: 'xyz'}).

If no response is provided, the process implementation will attempt to use the url parameters sent as an object to compute the Entity.pk. This enables the default implementation to still work with no response, so long as standard arguments are used.

This allows schema.Invalidate to remove the entity from the entity table

extend()

resource builds a great starting point, but often endpoints need to be further customized.

extend() is polymorphic with three forms:

Batch extension of known members

export const CommentResource = resource({
  path: '/repos/:owner/:repo/issues/comments/:id',
  schema: Comment,
}).extend({
  getList: { path: '/repos/:owner/:repo/issues/:number/comments' },
  update: { body: { body: '' } },
});

Adding new members

export const UserResource = createGithubResource({
  path: '/users/:login',
  schema: User,
}).extend('current', {
  path: '/user',
  schema: User,
});

Function form (to get BaseResource/super)

export const IssueResource= resource({
  path: '/repos/:owner/:repo/issues/:number',
  schema: Issue,
  pollFrequency: 60000,
  searchParams: {} as IssueFilters | undefined,
}).extend(BaseResource => ({
  search: BaseResource.getList.extend({
    path: '/search/issues\\?q=:q?%20repo\\::owner/:repo&page=:page?',
    schema: {
      results: {
        incompleteResults: false,
        items: BaseIssueResource.getList.schema.results,
        totalCount: 0,
      },
      link: '',
    },
  })
)});

Github CommentResource

More Demos

Function Inheritance Patterns

To reuse code related to Resource definitions, you can create your own function that calls resource(). This has similar effects as class-based inheritance, with the added benefit of allowing for complete typing overrides.

import {
  resource,
  RestEndpoint,
  type EndpointExtraOptions,
  type RestGenerics,
  type ResourceGenerics,
  type ResourceOptions,
} from '@data-client/rest';

export class AuthdEndpoint<
  O extends RestGenerics = any,
> extends RestEndpoint<O> {
  urlPrefix = process.env.API_SERVER ?? 'http://localhost:8000';

  async getRequestInit(body: any): Promise<RequestInit> {
    return {
      ...(await super.getRequestInit(body)),
      credentials: 'same-origin',
    };
  }
}

export function myResource<O extends ResourceGenerics = any>({
  schema,
  Endpoint = AuthdEndpoint,
  ...extraOptions
}: Readonly<O> & ResourceOptions) {
  return resource({
    Endpoint,
    schema,
    ...extraOptions,
  }).extend({
    getList: {
      schema: {
        results: new schema.Collection([schema]),
        total: 0,
        limit: 0,
        skip: 0,
      },
    },
  });
}

Github Example

More Demos

Usage​

Arguments​

path​

schema​

urlPrefix​

searchParams​

body​

paginationField​

optimistic​

Endpoint​

Collection​

EndpointExtraOptions​

Members​

get​

getList​

getList.push​

getList.unshift​

getList.getPage​

update​

partialUpdate​

delete​

Response​

extend()​

Batch extension of known members​

Adding new members​

Function form (to get BaseResource/super)​

Github CommentResource​

Function Inheritance Patterns​

Github Example​

Usage

Arguments

path

schema

urlPrefix

searchParams

body

paginationField

optimistic

Endpoint

Collection

EndpointExtraOptions

Members

get

getList

getList.push

getList.unshift

getList.getPage

update

partialUpdate

delete

Response

extend()

Batch extension of known members

Adding new members

Function form (to get BaseResource/super)

Github CommentResource

Function Inheritance Patterns

Github Example