v5.0.0

[htunnicliff]

Summary

• Rewrote APIs to use latest openapi-fetch types.
• Added useImmutable and useMutate hooks.
• Broke apart createHooks into separate builder functions.
• Added support for optional fetch option arguments.
• Wrote comprehensive tests for both runtime behavior and type checking.
• Wrote brand-new README documentation detailing new APIs.

Breaking Changes

• Removed CommonJS support (now ESM-only).
• Removed global configuration function.
• Replaced createHooks with separate builder functions.
• Replaced matchKeyComparator with useMutate.
• Renamed and refactored RequestTypes → TypesForRequest.
• Fixed internal types that broke from breaking changes in openapi-fetch.

Migration from v4

Imports

Replace createHooks calls with createQueryHook, createInfiniteHook, and createImmutableHook as needed.

import createClient from "openapi-fetch";
-import { createHooks } from "swr-openapi";
+import { createQueryHook, createInfiniteHook } from "swr-openapi";

const client = createClient(/* */);

-const { 
-  use: useSandwich, 
-  useInfinite: useSandwichInfinite 
-} = createHooks(client, "sandwich-api");
+export const useSandwich = createQueryHook(client, "sandwich-api");
+export const useSandwichInfinite = createInfiniteHook(client, "sandwich-api");

Fetch Options

For requests made that don't have required fetch options (like a path parameter), feel free to remove empty init arguments like this, as they are no longer required!

-const { data } = useQuery('/some/path', {});
+const { data } = useQuery('/some/path');

Key Matchers

Remove applySwrOpenApiConfiguration and define a useMutate hook using createMutateHook:

import createClient from "openapi-fetch";
import { isMatch } from "lodash";
-import { applySwrOpenApiConfiguration, createHooks } from "swr-openapi";
+import { createMutateHook } from "swr-openapi";

const client = createClient(/* */);

-applySwrOpenApiConfiguration({ matchKeyComparator: isMatch });

-export { matchKey } = createHooks(client, "unique-prefix");
+export const useMutate = createMutateHook(
+  client,
+  prefix,
+  isMatch
+);

To replace matchKey in consumers, call useMutate and invoke the callback like this:

-import { useSWRConfig } from "swr";
-import { matchKey } from "./api-clients";
+import { useMutate } from "./api-clients";  

function MyComponent() {
  // ...

-  const { mutate } = useSWRConfig();
+  const mutate = useMutate();

  const save = async () => {
    // ...
    await mutate(
-     matchKey("/some/path", { params: { query: { some: "item" } } }),
+     ["/some/path", { params: { query: { some: "item" } } }],
      { some: "data" },
    );
  };

  // ...
}

ESM in Next.js

If using Next.js in a non-ESM project, add swr-openapi to the transpilePackages array in your Next.js config file. This should take care of transpilation automatically, as well as transforming in Jest (if you use next/jest).

[prescottprue]

How would types be generated without this? Is it really optional? I guess it could be used through CLI and not installed?

[htunnicliff]

That is right. This library isn't in charge of type generation, which is why I add it as an optional peer. I might even be able to remove it altogether, but I'd need to double check.

[htunnicliff]

After digging deeper, I think leaving in openapi-typescript as an optional peer dependency makes sense. Even though swr-openapi does not require it, the types it uses are expected to have been generated by openapi-typescript@7.

[prescottprue]

Maybe worth adding a description to the function commands and a @see which links to the SWR docs for this

[prescottprue]

Is infinite maybe worth putting it it's own slash path the same way SWR does? I ask because it seems like part of their v1 release did this with intention

Maybe not necessary just a thought since it is what they did

[htunnicliff]

I actually spent quite a while on trying to implement that, but ESM-only tree-shaking was much simpler to rely on. There are some strange hacks going on in swr (look in swr/dist/infinite) that support their bundling, and I couldn't get it to work in consumers even when copying their methodology.

[htunnicliff]

At the very least, if a consumer doesn't end up using the infinite hooks, they should be tree-shaken at build time.

[prescottprue]

May be worth linking to the useSWRImmutable docs here with a @see

[prescottprue]

Doesn't isMatch return true for partial object matches since it is just a check for object values? Then wouldn't that cause a query with one parameter being the same value, but not having the other values to show as the same key?

If that it the goal it may be worth clarifying that here with this example with something like "updates queries even if not all parameters provided"

[htunnicliff]

That is definitely the intent. I leave the comparator as customizable though, so the library doesn't actually require _.isMatch.

[prescottprue]

Generally looking good - just a few questions and callouts of where it might be nice to add clarity + links to comments