Data hooks

useResource

The useResource hook fetches data from the API, saves it to the cache and then allows direct editing of those cached values through the controller it returns. It returns [List<T>, ListController<T>] or [T, ObjectController<T>] depending on whether the endpoint argument is a List or a BaseObject. It further takes an initialController argument which is expected to be a Partial<ListController<T>> or Partial<ObjectController<T>> respectively.

Example usage is as follows:

import { endpoints, useResource, useAwait } from "@bronscode/eidos";

function MyComponent({ userId }: { readonly userId: string }) {
	// makes a request to GET /users/{userId}/tasks
	const [tasks, resource] = useResource(endpoints.users[userId].tasks);
	// waits until the request returns before continuing the render
	useAwait(tasks);

	// This onClick will call PUT /users/{userId}/tasks with the new task as body
	// Also puts the new object in the cache and re-renders the component
	return <button onClick={() => resource.addObject({ title: "New task", description: "" })} />;
}

If we wish to alter the default values of limit, depth, page etc we can pass an initial controller object as second argument:

// Fetches the entire table including 1 layer of references and sorts them by description
const [tasks, resource] = useResource(endpoints.users[userId].tasks, {
	limit: Number.MAX_SAFE_INTEGER,
	depth: 1,
	sort: { value: "description", direction: "DESC" },
});

useSave

The useSave hook has the same structure as useResource except that any calls to addObject, setObject and deleteObject are not directly forwarded to the API. Instead, the changes are put into a local edit state and will only be propagated to the backend when the user clicks "Save" on the SaveBanner interface.

useCache

The useCache hook is used internally by the previous two hooks to fetch data from the cache. As all data hooks expect the resource to be defined, one needs to be sure that the data has already been put into the cache by another action when using this hook.

Example usage therefore is something like this:

import { endpoints, useResource, useAwait, useCache } from "@bronscode/eidos";

function Task({ userId, taskId }: { readonly userId: string; readonly taskId: string }) {
	const task = useCache(endpoints.users[userId].tasks[taskId]);

	return (
		<div className="Task">
			<h3>{task.title}</h3>
			<p>{task.description}</p>
		</div>
	);
}

function MyComponent({ userId }: { readonly userId: string }) {
	const [tasks, resource] = useResource(endpoints.users[userId].tasks);
	useAwait(tasks);

	return tasks.map((task) => <Task userId={userId} taskId={task.id} />);
}

useObjectState & useListState

These hooks can be used to create a local state that behaves like either an object or list resource. This is used for example in the editing dialog of the EditableTable.

The useObjectState takes an initialValue and returns the state along with an ObjectController.

The useListState takes an initialValues list and an optional initialController and returns the state along with a ListController.