@ableco/overpass

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.