Update README

Author: htunnicliff

README.md

@@ -16,91 +16,223 @@
 ## Installation
 
 ```sh
-npm install swr openapi-fetch swr-openapi
-npm install --save-dev openapi-typescript
+npm install swr-openapi swr openapi-fetch
+npm install --save-dev openapi-typescript typescript
 ```
 
 ## Setup
 
-For each Open API schema you want to use, run the following command to transform each schema into TypeScript types:
+Follow [openapi-typescript](https://openapi-ts.pages.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
 ```
 
-Once you have types for your API saved, create an API client:
+Then, create an [openapi-fetch](https://openapi-ts.pages.dev/openapi-fetch/) client and initialize [swr](https://swr.vercel.app/) hooks for the API:
 
+<!-- prettier-ignore -->
 ```ts
 // sandwich-api.ts
-import type * as SandwichSchema from "./types/sandwich-schema";
+import { createClient } from "openapi-fetch";
+import { createHooks } from "swr-openapi";
+import type * as SandwichesSchema from "./types/sandwich-schema";
 
-export const sandwichAPI = createClient<SandwichSchema.paths>({
+export const sandwichesApi = createClient<SandwichesSchema.paths>({
   baseUrl: "https://sandwiches.example",
 });
+
+export const {
+  use: useSandwiches,
+  useInfinite: useSandwichesInfinite,
+} = createHooks<SandwichesSchema.paths>(sandwichesApi, "sandwich-api");
+```
+
+## Usage
+
+```tsx
+import { useSandwiches } from "./sandwich-api";
+
+export function MySandwiches() {
+  // Fetch a single sandwich (uses useSWR)
+  const { data: sandwiches } = useSandwiches("/sandwiches/{sandwichId}", {
+    params: {
+      path: {
+        sandwichId: "sandwich-123",
+      },
+    },
+  });
+
+  // Fetch multiple pages of sandwiches (uses useSWRInfinite)
+  const {
+    data: pages,
+    size,
+    setSize,
+  } = useSandwichesInfinite("/sandwiches", (index, previous) => {
+    if (!previous.hasMore) {
+      return null;
+    }
+
+    return {
+      params: {
+        query: {
+          limit: 25,
+          offset: 25 * index,
+        },
+      },
+    };
+  });
+}
 ```
 
-Now, initialize a hook factory for that API:
+## API Reference
 
+### `createHooks<Paths>(api, keyPrefix)`
+
+- Parameters:
+  - `<Paths>`: An OpenAPI schema paths object generated by openapi-typescript.
+  - `api`: An openapi-fetch client.
+  - `keyPrefix`: A string to differentiate this API from others. This helps avoid swr cache collisions when using multiple APIs that may have identical paths.
+- Returns:
+  - [`use`](#usepath-options-swrconfig): A wrapper over [`useSWR`][swr-api] bound to the given api.
+  - [`useInfinite`](#useinfinitepath-getoptionsfn-swrconfig): A wrapper over [`useSWRInfinite`][swr-infinite-api] bound to the given api.
+
+Depending on your project preferences, there are different ways to export the return value of `createHooks`. Here are two examples:
+
+<details>
+<summary><b>Option 1: Destructure the return value and rename the destructured properties</b></summary>
+
+<!-- prettier-ignore -->
 ```ts
 // sandwich-api.ts
-import { makeHookFactory } from "swr-openapi";
-import type * as SandwichSchema from "./types/sandwich-schema";
+export const {
+  use: useSandwiches,
+  useInfinite: useSandwichesInfinite
+} = createHooks<SandwichesSchema.paths>(sandwichesApi, "sandwich-api");
+```
 
-export const sandwichAPI = createClient<SandwichSchema.paths>({
-  baseUrl: "https://sandwiches.example",
-});
+```ts
+// some-component.tsx
+import { useSandwiches } from "./sandwich-api";
 
-// 👇👇👇
-const makeHook = makeHookFactory<SandwichSchema.paths>(sandwichAPI);
+export function SomeComponent() {
+  const { data, error, isLoading } = useSandwiches("/sandwiches/{sandwichId}", {
+    params: {
+      path: {
+        sandwichId: "sandwich-123",
+      },
+    },
+  });
+}
 ```
 
-> **Info**
-> When working with multiple APIs, you can customize the name of each hook factory to suite your application:
->
-> ```ts
-> const fooAPI = createClient(...);
-> const makeFooHook = makeHookFactory(fooAPI);
->
-> const barAPI = createClient(...);
-> const makeBarHook = makeHookFactory(barAPI);
-> ```
+</details>
 
-With setup now out of the way, you can define the actual hooks used by your application:
+<details>
+<summary><b>Option 2: Don't destructure the return value</b></summary>
 
 ```ts
 // sandwich-api.ts
-import { makeHookFactory } from "swr-openapi";
-import type * as SandwichSchema from "./types/sandwich-schema";
+export const sandwiches = createHooks<SandwichesSchema.paths>(
+  sandwichesApi,
+  "sandwich-api",
+);
+```
 
-export const sandwichAPI = createClient<SandwichSchema.paths>({
-  baseUrl: "https://sandwiches.example",
-});
+```ts
+// some-component.tsx
+import { sandwiches } from "./sandwich-api";
+
+export function SomeComponent() {
+  const { data, error, isLoading } = sandwiches.use(
+    "/sandwiches/{sandwichId}",
+    {
+      params: {
+        path: {
+          sandwichId: "sandwich-123",
+        },
+      },
+    },
+  );
+}
+```
 
-const makeHook = makeHookFactory<SandwichSchema.paths>(sandwichAPI);
+</details>
 
-// 👇👇👇
-export const useSandwichesForUser = makeHook("/user/{userId}/sandwiches");
-export const useSandwiches = makeHook("/sandwiches");
-```
+### `use(path, options, swrConfig)`
 
-Now, you can call the hooks elsewhere in your application:
+```ts
+function use(
+  path: Path,
+  options: Options | null,
+  swrConfig?: Config,
+): SWRResponse;
+```
 
-```tsx
-import { useSandwiches, useSandwichesForUser } from "./sandwich-api";
+- Parameters:
+  - `path`: The GET endpoint to request.
+  - `options`: Either
+    1. An openapi-fetch [`FetchOptions`](https://openapi-ts.pages.dev/openapi-fetch/api#fetch-options) object for the given path.
+    2. `null` to support [conditional fetching](https://swr.vercel.app/docs/conditional-fetching).
+  - `swrConfig` (optional): [Configuration options](https://swr.vercel.app/docs/api#options) for `useSWR`.
+- Returns:
+  - A [`useSWR` response](https://swr.vercel.app/docs/api#return-values).
 
-export function UserSandwiches() {
-  const { data: sandwiches } = useSandwiches({
+```ts
+const { data, error, isLoading, mutate, revalidate } = use(
+  "/sandwiches/{sandwichId}",
+  {
     params: {
-      query: { limit: 10 },
+      path: {
+        sandwichId: "sandwich-123",
+      },
     },
-  });
+  },
+);
+```
+
+### `useInfinite(path, getOptionsFn, swrConfig)`
+
+```ts
+function useInfinite(
+  path: Path,
+  getOptionsFn: SWRInfiniteKeyLoader<Data, Options | null>,
+  swrConfig?: Config,
+): SWRInfiniteResponse;
+```
+
+- Parameters:
+  - `path`: The GET endpoint to request.
+  - `getOptionsFn`: An swr [`getKey` function](https://swr.vercel.app/docs/pagination#parameters) that accepts the index and the previous page data, returning either an openapi-fetch [`FetchOptions`](https://openapi-ts.pages.dev/openapi-fetch/api#fetch-options) object for loading the next page or `null`, once there are no more pages.
+  - `swrConfig` (optional): [Configuration options](https://swr.vercel.app/docs/pagination#parameters) for `useSWRInfinite`.
+- Returns:
+  - A [`useSWRInfinite` response](https://swr.vercel.app/docs/pagination#return-values).
 
-  const { data: userSandwiches } = useSandwichesForUser({
+```ts
+const {
+  data: sandwichPages,
+  error,
+  isLoading,
+  isValidating,
+  mutate,
+  size,
+  setSize,
+} = useInfinite("/sandwiches", (index, previousPage) => {
+  if (!previousPage.hasMore) {
+    return null;
+  }
+
+  return {
     params: {
-      path: { userId: "user-123" },
+      query: {
+        limit: 25,
+        offset: 25 * index,
+      },
     },
-  });
-
-  // ...
-}
+  };
+});
 ```
+
+[swr-api]: https://swr.vercel.app/docs/api
+[swr-infinite-api]: https://swr.vercel.app/docs/pagination#useswrinfinite