Route Sphere

Sync query parameters with a MobX store and React Router.

This was originally developed in VocaDB/vocadb#965 as a part of VocaDB.

Live demo

See VocaDB’s search page.

Requirements

Installation

yarn add @vocadb/route-sphere or npm i @vocadb/route-sphere

How it works

There are three custom hooks, depending on the use case: useStoreWithUpdateResults, useStoreWithPagination and useStoreWithRouteParams. These hooks are defined as below:

const useStoreWithUpdateResults = <TRouteParams>(store: StoreWithUpdateResults<TRouteParams>): void;
const useStoreWithPagination = <TRouteParams>(store: StoreWithPagination<TRouteParams>): void;
const useStoreWithRouteParams = <TRouteParams>(store: StoreWithRouteParams<TRouteParams>): void;

The useStoreWithUpdateResults hook

The useStoreWithUpdateResults updates search results whenever the routeParams property changes. The StoreWithUpdateResult interface is defined as below:

interface StoreWithUpdateResults<TRouteParams> extends StoreWithRouteParams<TRouteParams> {
	readonly clearResultsByQueryKeys: (keyof TRouteParams)[];
	/** Called when search results should be cleared. */
	onClearResults?: () => void;
	updateResults(clearResults: boolean): Promise<void>;
}

The useStoreWithUpdateResults hook determines if search results should be cleared by comparing the current and previous values. If that’s the case, the onClearResults callback is called.

Examples

The useStoreWithPagination hook

The useStoreWithPagination hook is a helper hook that is composed of the useStoreWithUpdateResults and useStoreWithRouteParams hooks. The StoreWithPagination interface is defined as below:

interface StoreWithPagination<TRouteParams> extends StoreWithUpdateResults<TRouteParams> {
	/** Called when search results should be cleared. */
	onClearResults(): void;
}

Examples

The useStoreWithRouteParams hook

The useStoreWithRouteParams hook updates a store that implements the StoreWithRouteParams interface when a route changes, and vice versa. The StoreWithRouteParams interface is defined as below:

interface StoreWithRouteParams<TRouteParams> {
	/** Whether currently processing popstate. This is to prevent adding the previous state to history. */
	popState: boolean;
	routeParams: TRouteParams;
	validateRouteParams(data: any): data is TRouteParams;
}

The popState property is set by the useStoreWithRouteParams hook to prevent adding the previous state to history.

The validateRouteParams function validates route params and should return true if and only if the passed data is valid. Validation happens every time location (not URL) changes, which means, when the page is first loaded, when the back/forward buttons on the browser are clicked, and when the page is navigated to a new location programmatically by using the useNavigate hook. Note that the <Link> component uses the useNavigate hook internally.

The routeParams property gets and sets the state of the store.

Reactions should be independent: Does your code rely on some other reaction having to run first? If that is the case, you probably either violated the first rule, or the new reaction you are about to create should be merged into the one it is depending upon. MobX does not guarantee the order in which reactions will be run.

Source: Running side effects with reactions · MobX

How to generate schema

We use JSON schema to validate route params. Use typescript-json-schema project/directory/tsconfig.json TYPE to generate schema from a TypeScript type. For more information, see YousefED/typescript-json-schema.

Examples

References

GitHub

View Github