Update

.github/workflows/build.yml

@@ -0,0 +1,37 @@
+# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Build & test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: lts/*
+          cache: yarn
+
+      - run: yarn install --pure-lockfile
+      - run: yarn typecheck
+      - run: yarn test
+      - run: yarn build
+
+      - name: Build docs
+        run: cd docs && yarn && yarn build
+
+      - name: Deploy
+        if: "contains('refs/heads/main', github.ref)"
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build

.gitignore

@@ -2,4 +2,7 @@
 .DS_Store?
 node_modules/
 example/graphql-env.d.ts
-.env
+.env
+docs/node_modules/
+.docusaurus
+dist/

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```console
+$ yarn
+```
+
+### Local Development
+
+```console
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```console
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve("@docusaurus/core/lib/babel/preset")],
+};

docs/docs/client.md

@@ -0,0 +1,20 @@
+---
+title: Client
+sidebar_label: Client
+---
+
+## Perform a query
+
+```ts
+client.query(query, variables).tap((result) => {
+  console.log(result);
+});
+```
+
+## Perform a mutation
+
+```ts
+client.commitMutation(mutation, variables).tap((result) => {
+  console.log(result);
+});
+```

docs/docs/getting-started.md

@@ -0,0 +1,57 @@
+---
+title: Getting started
+sidebar_label: Getting started
+---
+
+# Getting started
+
+**GraphQL Client** is a simple GraphQL client for React applications. It's focused on giving a good, typesafe experience when working on your codebase.
+
+## 1. Install
+
+```console
+$ yarn add @swan-io/graphql-client
+```
+
+or
+
+```console
+$ npm install @swan-io/graphql-client
+```
+
+## 2. Create your client
+
+```ts title="src/index.tsx"
+import { Client, ClientContext } from "@swan-io/graphql-client";
+import { App } from "./App";
+import { createRoot } from "react-dom/client";
+
+// highlight-start
+const client = new Client({
+  url: "/api",
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
+// highlight-end
+
+export const Root = () => {
+  return (
+    // highlight-start
+    <ClientContext.Provider value={client}>
+      // highlight-end
+      <App />
+      // highlight-start
+    </ClientContext.Provider>
+    // highlight-end
+  );
+};
+
+const root = document.querySelector("#app");
+
+if (root != null) {
+  createRoot(root).render(<Root />);
+}
+```
+
+And you're ready to go!

docs/docs/pagination.md

@@ -0,0 +1,20 @@
+---
+title: Pagination
+sidebar_label: Pagination
+---
+
+## useForwardPagination(connection)
+
+Aggregates the connection data (with `after`).
+
+```ts
+const users = useForwardPagination(usersConnection);
+```
+
+## useBackwardPagination(connection)
+
+Aggregates the connection data (with `before`).
+
+```ts
+const users = useBackwardPagination(usersConnection);
+```

docs/docs/use-mutation.md

@@ -0,0 +1,76 @@
+---
+title: useMutation
+sidebar_label: useMutation
+---
+
+## useMutation(mutation)
+
+### Params
+
+- `mutation`: your mutation document node
+
+### Returns
+
+This hook returns a tuple you can extract like a `useState`:
+
+```ts
+const [commitMutation, mutationData] = useMutation(...)
+```
+
+- `commitMutation(variables)`: function commit the mutation, returns a `Future<Result<Data, ClientError>>`
+- `mutationData` (`AsyncData<Result<Data, ClientError>>`): the mutation data
+
+## Example
+
+```ts
+import { useMutation } from "@swan-io/graphql-client";
+// ...
+
+const updateUsernameMutation = graphql(`
+  mutation UpdateUsername($userId: ID!, $username: String!) {
+    updateUsername(id: $userId, username: $username) {
+      ... on UpdateUsernameSuccessPayload {
+        user {
+          id
+          username
+          avatar
+        }
+      }
+      ... on InvalidUsernameRejection {
+        message
+      }
+    }
+  }
+`);
+
+type Props = {
+  userId: string;
+};
+
+const UserPage = ({ userId }: Props) => {
+  const [updateUsername, usernameUpdate] = useMutation(updateUsernameMutation);
+  const [username, setUsername] = useState("");
+
+  // ...
+  const onSubmit = (event) => {
+    event.preventDefault();
+    updateUsername({ userId, username });
+  };
+
+  const isLoading = usernameUpdate.isLoading();
+
+  return (
+    <form onSubmit={onSubmit}>
+      <input
+        value={username}
+        readOnly={isLoading}
+        onChange={(event) => setUsername(event.target.value)}
+      />
+
+      <button type="submit" readOnly={isLoading}>
+        Submit
+      </button>
+    </form>
+  );
+};
+```

docs/docs/use-query.md

@@ -0,0 +1,61 @@
+---
+title: useQuery
+sidebar_label: useQuery
+---
+
+## useQuery(query, variables, config?)
+
+### Params
+
+- `query`: your query document node
+- `variables`: your query variables
+- `config` (optional)
+  - `suspense`: use React Suspense (default: `false`)
+
+### Returns
+
+This hook returns a tuple you can extract like a `useState`:
+
+```ts
+const [data, {isLoading, refresh, reload}] = useQuery(...)
+```
+
+- `data` (`AsyncData<Result<Data, ClientError>>`): the GraphQL response
+- `isLoading` (`boolean`): if the query is fetching
+- `refresh()`: refresh the query in the background, keeping current data on screen
+- `reload()`: reload the query (full reload, showing a full loading state)
+
+## Example
+
+```ts
+import { useQuery } from "@swan-io/graphql-client";
+// ...
+
+const userPageQuery = graphql(`
+  query UserPage($userId: ID!) {
+    user(id: $userId) {
+      id
+      username
+      avatar
+    }
+  }
+`);
+
+type Props = {
+  userId: string;
+};
+
+const UserPage = ({ userId }: Props) => {
+  const [user] = useQuery(userPageQuery, { userId });
+
+  return user.match({
+    NotAsked: () => null,
+    Loading: () => <LoadingIndicator />,
+    Done: (result) =>
+      result.match({
+        Error: (error) => <ErrorIndicator error={error} />,
+        Ok: (user) => <UserDetails user={user} />,
+      }),
+  });
+};
+```