npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ableco/overpass

v0.8.3

Published

Redux-based hooks-powered bridge between JSON:API endpoints and React components

Downloads

10

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.