@data-client/rest

TypeScript HTTP definitions

RestEndpoint

Simplify TypeScript fetch functions with RestEndpoint

const getTodo = new RestEndpoint({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos/:id',
});

RestEndpoint infers path-to-regexp argument types, enabling enforcement of function calls

// signature requires id!
const todo = await getTodo({ id: 5 });

It automatically handles REST concepts like JSON serialization, consolidated error handling and more.

Resources

Simplify related CRUD endpoints with Resources

Resources are a collection of methods for a given data model.

Entities and Schemas declaratively define the data model. RestEndpoints are the methods on that data.

class Todo extends Entity {
  id = 0;
  userId = 0;
  title = '';
  completed = false;
}
const TodoResource = resource({
  urlPrefix: 'https://jsonplaceholder.typicode.com',
  path: '/todos/:id',
  searchParams: {} as { userId?: string | number },
  schema: Todo,
  paginationField: 'page',
});

One Resource defines seven endpoints:

// GET https://jsonplaceholder.typicode.com/todos/5
let todo5 = await TodoResource.get({ id: 5 });

// GET https://jsonplaceholder.typicode.com/todos
const todoList = await TodoResource.getList();

// GET https://jsonplaceholder.typicode.com/todos?userId=1
const userOneTodos = await TodoResource.getList({ userId: 1 });

// POST https://jsonplaceholder.typicode.com/todos
const newTodo = await TodoResource.getList.push({ title: 'my todo' });

// POST https://jsonplaceholder.typicode.com/todos?userId=1
const newUserOneTodo = await TodoResource.getList.push(
  { userId: 1 },
  { title: 'my todo' },
);

// GET https://jsonplaceholder.typicode.com/todos?userId=1&page=2
const nextPageOfTodos = await TodoResource.getList.getPage({
  userId: 1,
  page: 2,
});

// PUT https://jsonplaceholder.typicode.com/todos/5
todo5 = await TodoResource.update({ id: 5 }, { title: 'my todo' });

// PATCH https://jsonplaceholder.typicode.com/todos/5
todo5 = await TodoResource.partialUpdate({ id: 5 }, { title: 'my todo' });

// DELETE https://jsonplaceholder.typicode.com/todos/5
await TodoResource.delete({ id: 5 });

Free React Integration

No need for any custom hooks. All endpoints are 100% compatible with Reactive Data Client

Rendering

const todo = useSuspense(TodoResource.get, { id: 5 });
const todoList = useSuspense(TodoResource.getList);

Mutations

const ctrl = useController();
const updateTodo = data => ctrl.fetch(TodoResource.update, { id }, data);
const partialUpdateTodo = data =>
  ctrl.fetch(TodoResource.partialUpdate, { id }, data);
const addTodoToEnd = data => ctrl.fetch(TodoResource.getList.push, data);
const addTodoToBeginning = data =>
  ctrl.fetch(TodoResource.getList.unshift, data);
const deleteTodo = data => ctrl.fetch(TodoResource.delete, { id });

Programmatic queries

const queryRemainingTodos = new Query(
  TodoResource.getList.schema,
  entries => entries.filter(todo => !todo.completed).length,
);

const allRemainingTodos = useQuery(queryRemainingTodos);
const firstUserRemainingTodos = useQuery(queryRemainingTodos, { userId: 1 });

const groupTodoByUser = new Query(
  TodoResource.getList.schema,
  todos => Object.groupBy(todos, todo => todo.userId),
);
const todosByUser = useQuery(groupTodoByUser);

TypeScript requirements

TypeScript is optional, but will only work with 4.0 or above. 4.1 is needed for stronger types as it supports inferring argument types from the path templates.

Prior Art

• Backbone Model
• ImmutableJS Record

API

Networking definition

• Endpoints: RestEndpoint
• Resources: resource(), hookifyResource()

Data model

Data Type	Mutable	Schema	Description	Queryable
Object		Entity, EntityMixin	single unique object
		Union(Entity)	polymorphic objects (A | B)
		Object	statically known keys
		Invalidate(Entity)	delete an entity
List		Collection(Array)	growable lists
		Array	immutable lists
		All	list of all entities of a kind
Map		Collection(Values)	growable maps
		Values	immutable maps
Scalar		Scalar	lens-dependent entity fields
any		Query(Queryable)	memoized custom transforms
		Lazy(Schema)	deferred denormalization