npm package: @oasa/amplify-query
Description: Fetching, caching and updating asynchronous data with Amplify
Author: Richard Pecha
Latest version: 0.0.40

# @oasa/amplify-query

> AWS Amplify react hooks. The easiest way to fetch and update data from AWS AppSync GraphQL API.
>
[![NPM](https://img.shields.io/npm/v/@oasa/amplify-query.svg)](https://www.npmjs.com/package/@oasa/amplify-query) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)

## Install

```bash
npm install --save @oasa/amplify-query
```

[comment]: <> (Or)

[comment]: <> (```bash)

[comment]: <> (yarn add @oasa/amplify-query)

[comment]: <> (```)

You need to also have `react` and `aws-amplify` installed.

## Usage

### useQuery

```javascript
const {
  data: Array<mixed>,
  loading: string,
  error: string,
  fetchMore: function
} = useQuery(query {}, options: { variables: {[key: string]: any }}, queryData: Array<string>)
```


`query` - The first argument is a GraphQL query READ operation, the second is a CREATE subscription operation, the third is an UPDATE subscription operation and the fourth is a DELETE subscription operation.

`option` - An object containing all the variables that your request should fulfill.

`queryData` - An array of GraphQL operation names in the READ, CREATE, UPDATE, DELETE sequence.

`data` — The returned data array.

`loading` - Loading indicator.

`error` - Error.

`fetchMore` - Often in your application there will be some views in which you need to display a list that contains too much data so that it can either be retrieved or displayed immediately. Pagination is the most common solution to this problem, and the useQuery hook has built-in functionality that makes it pretty simple. The easiest way to do pagination is to use the fetchMore function, which is included in the result object returned by the useQuery hook. This basically allows you to make a new GraphQL query and combine the result with the original result.

### Simple example
```tsx
import React, { useState } from "react";
import { useQuery } from "@oasa/amplify-query";
import {
  CompaniesByCreatedAtQuery,
  EntityType,
  ModelSortDirection,
  Company
} from "src/API";
import { companiesByCreatedAt } from "src/graphql/queries";

export const Companies = () => {
  const { loading, data, error, refetch } =
    useQuery<ListCompaniesQuery>(listCompanies)

  if (loading) {
    return <div>Loading...</div>
  }

  if (error) {
    return <div>Error! {error}</div>
  }

  return (
    <div>
      {data?.listCompanies?.items((item: Company, index: number) => {
        <div key={index}>{item?.name}</div>
      })}
    </div>
  );
}
```

### useMutation

```javascript
const [
  mutate: Promise<{}>,
{
  loading: string,
  error: string
}
] = useMutation(mutation {})
```

`mutate` - Mutation function

`loading` - Loading indicator.

`error` - Error.


`mutation` - Mutation.

### Simple example

```tsx

import { useForm } from "react-hook-form";
import {
  CreateEmailNewsletterInput,
  CreateEmailNewsletterMutation,
} from "src/API";
import { useMemo } from "react";
import { createEmailNewsletter } from "src/graphql/mutations";
import { useMutation } from "@oasa/amplify-query";

export const Newsletter = () => {

  const [registerNewsletter] = useMutation<
    CreateEmailNewsletterInput,
    CreateEmailNewsletterMutation
    >(createEmailNewsletter);

  const {
    register,
    handleSubmit,
    formState: { isSubmitting },
  } = useForm<CreateEmailNewsletterInput>({
    defaultValues: useMemo(() => {
      return {
        email: "",
      };
    }, []),
  });

  const onSubmit = handleSubmit(async (data: CreateEmailNewsletterInput) => {
    await registerNewsletter({
      input: data,
    });
  });

  return (
    <form onSubmit={onSubmit}>
        <input
          type="text"
          {...register("email", { required: true })}
        />
        <button type={"submit"}>submit</button>
    </form>
  );
}
```


### useSubscription

```javascript
const {
  data: Array<mixed>,
  loading: string,
  error: string,
} = useQuery(subscription {}, variables: {}, options: { withOwner: boolean, authMode: string, onSubscriptionData: function })
```


`subscription` - Amplify subscription.

`variables` - An object containing all the variables.

`options` - An object containing all the options - withOwner, authMode, onSubscriptionData.

`data` — The returned data array.

`loading` - Loading indicator.

`error` - Error.


### Simple example
```tsx
import React, { useState } from "react";
import { useQuery } from "@oasa/amplify-query";
import {
  CompaniesByCreatedAtQuery,
  EntityType,
  ModelSortDirection,
  Company
} from "src/API";
import { companiesByCreatedAt } from "src/graphql/queries";

export const CompanyProfile = () => {

  const {data, loading, error} = useSubscription(
    onUpdateCompany,
    {},
    {
      withOwner: true,
      authMode: "AMAZON_COGNITO_USER_POOLS",
      onSubscriptionData: (data: OnUpdateCompanySubscription) => {
        console.log(data);
      },
    }
  );

  if (loading) {
    return <div>Loading...</div>
  }

  if (error) {
    return <div>Error! {error}</div>
  }

  return (
    <div>
      {data?.onUpdateCompany?.name}
    </div>
  );
}
```

## Contributors

Thanks goes to these wonderful people:

<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- prettier-ignore -->
<table cellspacing="0" cellpadding="1"><tr><td><a href="https://github.com/pecha.richard"><img src="https://avatars.githubusercontent.com/u/76245185?v=4" width="100px;" height="100px;" alt="Richard Pecha"/><br /><sub><b>Richard Pecha</b></sub></a><br /><a href="https://github.com/OASA-ai/amplify-query/commits?author=pecha.richard" title="Code">💻</a> <a href="https://github.com/OASA-ai/amplify-query/commits?author=pecha.richard" title="Tests">⚠️</a></td></tr></table>
<!-- ALL-CONTRIBUTORS-LIST:END -->

This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!

## License

MIT © [Richard Pecha](https://github.com/Richard Pecha)