@ableco/overpass
v0.8.3
Published
Redux-based hooks-powered bridge between JSON:API endpoints and React components
Downloads
10
Keywords
Readme
Overpass
Redux-based hooks-powered bridge between JSON:API endpoints and React components.
Installation
Using npm
npm install @ableco/overpass
Using yarn
yarn add @ableco/overpass
Getting started
To map your application's JSON:API resources, define a resources
object using defineResources
:
import { defineResources } from "@ableco/overpass";
const resources = defineResources(({ resource }) => {
resource("categories");
resource("products");
resource("orders");
resource("items");
});
Then, wrap your app with an <OverpassProvider />
component. It will allow you to use Overpass across components in your application.
<OverpassProvider />
accepts a few props, as you will see later. Use the resources
prop to let Overpass know how to store your resources:
import { defineResources } from "@ableco/overpass";
const resources = defineResources(({ resource }) => {
resource("categories");
resource("products");
resource("orders");
resource("items");
});
<OverpassProvider
api={{
apiPrefix: "/api",
}}
resources={resources}
>
{/* your app */}
</OverpassProvider>
Usage
Fetching data
There are two ways to fetch data in Overpass. The first one is by fetching collections of resources, and the second one is by fetching single resources, known as entities.
Note: Overpass uses React hooks to work with the stored resources.
To fetch collections of entities, you can use useFetchCollection
. The result of calling useFetchCollection
is a function that can be used inside a useEffect
hook:
import { useFetchCollection } from "@ableco/overpass";
function CategoriesList() {
const fetchCategories = useFetchCollection("categories");
useEffect(() => {
fetchCategories();
}, []);
return <div>{/* your component */}</div>;
}
To fetch a single entity, you can use useFetchEntity
. Unlike useFetchCollection
, useFetchEntity
not only receives the entity's name but also a single entity's ID:
import { useFetchEntity } from "@ableco/overpass";
function Product({ id }) {
const fetchProduct = useFetchEntity("products", id);
useEffect(() => {
fetchProduct();
}, []);
return <div>{/* your component */}</div>;
}
Using fetched data
After data is fetched with useFetchCollection
or useFetchEntity
, you can work with stored entities by using useCollection
or useEntity
:
const categories = useCollection("categories");
const product = useEntity("products", id);
You can also filter collections or entities by a single attribute with useFilteredCollection
or useFilteredEntity
:
const categoryProducts = useFilteredCollection(
"products",
"categoryId",
categoryId,
);
const mainProduct = useFilteredEntity("products", "mainProduct", true);
Mutating remotely
Note: The following hooks will make changes in your backend's database.
Creating entities
To create an entity, Overpass provides a hook called useCreateEntity
.
The function returned by useCreateEntity
receives an object with the attributes for the entity to be created:
const createItem = useCreateEntity("items");
async function addProductToCart(selectedProductId) {
await createItem({ productId: selectedProductId });
}
Updating entities
useUpdateEntity
is an Overpass hook that receives two parameters, the resource's name and the ID of the entity to be updated.
The function returned by useUpdateEntity
also receives an object with the attributes for the entity to be updated:
const updateItem = useUpdateEntity("items", itemId);
async function updateCartItem(quantity) {
await updateItem({ quantity: quantity });
};
Deleting entities
useDeleteEntity
lets you delete an entity. The function returned by useDeleteEntity
receives the ID of the entity to be deleted:
const deleteItem = useDeleteEntity("items");
async function removeCartItem(itemId) {
await deleteItem(itemId);
};
Testing
Run the following command in a terminal:
npm run test
Or this other one if you are using yarn:
yarn test
Contributing
Contributions are welcome. Please check out the Contributing guide for the guidelines you need to follow.
Please read our Code of Conduct so that you can understand the kind of respectful behavior we expect from all participants.
License
Overpass is released under the MIT license. See LICENSE for the full license text.