@data-client/rest

TypeScript HTTP definitions

📖Read The Docs  |  🤖Agent Skills  |  🎮Todo Demo  |  🎮Github Demo

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	🛑
any		Query(Queryable)	memoized custom transforms	✅
	Lazy(Schema)	deferred denormalization	✅