Configure vitepress

Author: htunnicliff

README.md

@@ -13,46 +13,48 @@
   </a>
 </p>
 
-## Setup
+## Introduction
 
-```sh
-npm install swr-openapi swr openapi-fetch
-```
-
-Follow [openapi-typescript](https://openapi-ts.dev/) directions to generate TypeScript definitions for each service being used.
-
-Here is an example of types being generated for a service via the command line:
-
-```sh
-npx openapi-typescript "https://sandwiches.example/openapi/json" --output ./types/sandwich-schema.ts
-```
+swr-openapi is a type-safe wrapper around [`swr`](https://swr.vercel.app).
 
-## Basic Usage
+It works by using [openapi-fetch](https://openapi-ts.dev/openapi-fetch) and [openapi-typescript](https://openapi-ts.dev/introduction) so you get all the following features:
 
-Initialize an [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) client and create any desired hooks.
+- ✅ No typos in URLs or params.
+- ✅ All parameters, request bodies, and responses are type-checked and 100% match your schema
+- ✅ No manual typing of your API
+- ✅ Eliminates `any` types that hide bugs
+- ✅ Also eliminates `as` type overrides that can also hide bugs
 
-```ts
-// sandwich-api.ts
+```tsx [src/my-component.ts]
 import createClient from "openapi-fetch";
 import { createQueryHook } from "swr-openapi";
-import type { paths as SandwichPaths } from "./types/sandwich-schema";
+import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
 
-const client = createClient<SandwichPaths>(/* ... */);
+const client = createClient<paths>({
+  baseUrl: "https://myapi.dev/v1/",
+});
 
-const useSandwiches = createQueryHook(client, "sandwich-api");
+const useQuery = createQueryHook(client, "my-api");
 
-const { data, error, isLoading, isValidating, mutate } = useSandwiches(
-  "/sandwich/{id}", // <- Fully typed paths!
-  {
-    params: {
-      path: {
-        id: "123", // <- Fully typed params!
+function MyComponent() {
+  const { data, error, isLoading, isValidating, mutate } = useQuery(
+    "/blogposts/{post_id}",
+    {
+      params: {
+        path: { post_id: "123" },
       },
     },
-  },
-);
+  );
+
+  if (isLoading || !data) return "Loading...";
+
+  if (error) return `An error occured: ${error.message}`;
+
+  return <div>{data.title}</div>;
+}
+
 ```
 
 ## 📓 Docs
 
-[View Docs](https://openapi-ts.dev/swr-openapi)
+[View Docs](https://htunnicliff.github.io/swr-openapi)

docs/.vitepress/config.ts

@@ -4,25 +4,60 @@ import { defineConfig } from 'vitepress'
 export default defineConfig({
   title: "SWR OpenAPI",
   description: "Bindings for SWR and OpenAPI schemas",
+  cleanUrls: true,
   themeConfig: {
+    outline: "deep",
     // https://vitepress.dev/reference/default-theme-config
     nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Examples', link: '/markdown-examples' }
+      { text: 'Home', link: '/', },
+      { text: 'Getting Started', link: '/getting-started' },
+      { text: 'API Reference', link: '/api/hook-builders' }
     ],
-
     sidebar: [
       {
-        text: 'Examples',
+        text: "Getting Started",
+        items: [
+          {text: "Introduction", link: "/getting-started"},
+          {text: "Setup", link: "/getting-started#setup"},
+          {text: "Basic Usage", link: "/getting-started#basic-usage"}
+        ],
+      },
+      {
+        text: "API Reference",
+        base: '/api',
         items: [
-          { text: 'Markdown Examples', link: '/markdown-examples' },
-          { text: 'Runtime API Examples', link: '/api-examples' }
+          {
+            text: 'Hook Builders',
+            link: '/hook-builders'
+          },
+          {
+            text: 'useImmutable',
+            link: '/use-immutable'
+          },
+          {
+            text: 'useInfinite',
+            link: '/use-infinite'
+          },
+          {
+            text: 'useMutate',
+            link: '/use-mutate'
+          },
+          {
+            text: 'useQuery',
+            link: '/use-query'
+          },
+
         ]
-      }
+      },
     ],
-
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
-    ]
+      { icon: 'github', link: 'https://github.com/htunnicliff/swr-openapi' }
+    ],
+    footer: {
+      message: 'Released under the <a href="https://github.com/htunnicliff/swr-openapi/blob/main/LICENSE">MIT License</a>'
+    },
+    search: {
+      provider: "local",
+    }
   }
 })

docs/api-examples.md

@@ -0,0 +1,143 @@
+---
+title: Hook Builders
+---
+
+# {{ $frontmatter.title }}
+
+Hook builders initialize `useQuery`, `useImmutate`, `useInfinite`, and `useMutate`.
+
+Each builder function accepts an instance of a [fetch client](https://openapi-ts.dev/openapi-fetch/api) and a prefix unique to that client.
+
+
+::: tip
+
+Prefixes ensure that `swr` will avoid caching requests from different APIs when requests happen to match (e.g. `GET /health` for "API A" and `GET /health` for "API B").
+
+:::
+
+```ts
+import createClient from "openapi-fetch";
+import { isMatch } from "lodash-es";
+
+import {
+  createQueryHook,
+  createImmutableHook,
+  createInfiniteHook,
+  createMutateHook,
+} from "swr-openapi";
+
+import type { paths } from "./my-openapi-3-schema"; // generated by openapi-typescript
+
+const client = createClient<paths>(/* ... */);
+const prefix = "my-api";
+
+export const useQuery = createQueryHook(client, prefix);
+export const useImmutable = createImmutableHook(client, prefix);
+export const useInfinite = createInfiniteHook(client, prefix);
+export const useMutate = createMutateHook(
+  client,
+  prefix,
+  isMatch, // Or any comparision function
+);
+```
+
+## API
+
+### Parameters
+
+Each builder hook accepts the same initial parameters:
+
+- `client`: A [fetch client](https://openapi-ts.dev/openapi-fetch/api).
+- `prefix`: A prefix unique to the fetch client.
+
+`createMutateHook` also accepts a third parameter:
+
+- [`compare`](#compare): A function to compare fetch options).
+
+### Returns
+
+- `createQueryHook` &rarr; [`useQuery`](./use-query.md)
+- `createImmutableHook` &rarr; [`useImmutable`](./use-immutable.md)
+- `createInfiniteHook` &rarr; [`useInfinite`](./use-infinite.md)
+- `createMutateHook` &rarr; [`useMutate`](./use-mutate.md)
+
+## `compare`
+
+When calling `createMutateHook`, a function must be provided with the following contract:
+
+```ts
+type Compare = (init: any, partialInit: object) => boolean;
+```
+
+This function is used to determine whether or not a cached request should be updated when `mutate` is called with fetch options.
+
+My personal recommendation is to use lodash's [`isMatch`][lodash-is-match]:
+
+> Performs a partial deep comparison between object and source to determine if object contains equivalent property values.
+
+```ts
+const useMutate = createMutateHook(client, "<unique-key>", isMatch);
+
+const mutate = useMutate();
+
+await mutate([
+  "/path",
+  {
+    params: {
+      query: {
+        version: "beta",
+      },
+    },
+  },
+]);
+
+// ✅ Would be updated
+useQuery("/path", {
+  params: {
+    query: {
+      version: "beta",
+    },
+  },
+});
+
+// ✅ Would be updated
+useQuery("/path", {
+  params: {
+    query: {
+      version: "beta",
+      other: true,
+      example: [1, 2, 3],
+    },
+  },
+});
+
+// ❌ Would not be updated
+useQuery("/path", {
+  params: {
+    query: {},
+  },
+});
+
+// ❌ Would not be updated
+useQuery("/path");
+
+// ❌ Would not be updated
+useQuery("/path", {
+  params: {
+    query: {
+      version: "alpha",
+    },
+  },
+});
+
+// ❌ Would not be updated
+useQuery("/path", {
+  params: {
+    query: {
+      different: "items",
+    },
+  },
+});
+```
+
+[lodash-is-match]: https://lodash.com/docs/4.17.15#isMatch

docs/api/hook-builders.md

@@ -0,0 +1,35 @@
+---
+title: useImmutable
+---
+
+# {{ $frontmatter.title }}
+
+This hook has the same contracts as [`useQuery`](./use-query.md). However, instead of wrapping [`useSWR`][swr-api], it wraps `useSWRImmutable`. This immutable hook [disables automatic revalidations][swr-disable-auto-revalidate] but is otherwise identical to `useSWR`.
+
+```ts
+import createClient from "openapi-fetch";
+import { createImmutableHook } from "swr-openapi";
+import type { paths } from "./my-schema";
+
+const useImmutable = createImmutableHook(client, "my-api");
+
+const { data, error, isLoading, isValidating, mutate } = useImmutable(
+  path,
+  init,
+  config,
+);
+```
+
+## API
+
+### Parameters
+
+Identical to `useQuery` [parameters](./use-query.md#parameters).
+
+### Returns
+
+Identical to `useQuery` [returns](./use-query.md#returns).
+
+
+[swr-disable-auto-revalidate]: https://swr.vercel.app/docs/revalidation.en-US#disable-automatic-revalidations
+[swr-api]: https://swr.vercel.app/docs/api