[IDP-2107] Add React Query Plugin

[tjosepo]

Demo: https://stackblitz.com/edit/workleap-create-schemas-todo?file=src%2FApp.tsx

Description of changes

Adds a reactQueryPlugin() which auto-generates data-fetching hooks for React applications.

• For an overview of the plugin, from the perspective of a consumer, check: docs/src/tanstack-react-query.md
• Most of the logic is contained in the packages/create-schemas/src/plugins/react-query-plugin/react-query-plugin.ts and packages/create-schemas/src/json-schema.ts files.

Breakdown

The plugin works this way:

1. It reads the OpenAPI file.
2. For each endpoint:

1. Generate the interface of the body, response and error of the endpoint.
2. Generate the data fetching function, which uses the OpenAPI client. This function is internal and is hidden to consumers. It will be used by other functions.
3. Generate the QueryKey function for the endpoint.
4. Generate the useQuery, useSuspenseQuery and prefetchQuery function. Optionally generate the useMutation function if it's a POST, PUT, DELETE or PATCH method.

3. Generate the types from the component.schemas field, so they don't need to be imported from another file / plugin.

That's it. It's not very complex, but looks difficult because building ASTs is pretty complicated.

Breaking changes

None.

Additional checks

• Updated the documentation of the project to reflect the changes
• Added new tests that cover the code changes

[tjosepo]

We need to inline the SVG, otherwise fill="currentColor" won't work.

[tjosepo]

This export doesn't need to exist. The content of this file could be inlined into the generated code.

I made it an export because it helps keep the generated code lighter. If it turns out to be a bad idea, we can inline it.

[tjosepo]

A "load" hook was added to plugins because it didn't make sense for every plugin to implement their own loading behavior in their startBuild step.

A "load" hook is common in almost all bundlers.

[tjosepo]

A Symbol is used to create a method that isn't accessible by the consumer. This way, people can't use the client directly, as disscussed in our last meeting.

[PrincessMadMath]

Is there an other card to update the documentation, https://gsoft-inc.github.io/wl-openapi-typescript/ does not seems to mention hooks and there is no PR open on the doc repo.

[mahmoudmoravej]

I just focus a bit on usage for now. I will dig into it later. I copied the parts from your demo app:

    createTask(
      { body: { description } },
      {
        onSuccess() {
          queryClient.invalidateQueries({ queryKey: tasksGetAllQueryKey() });
          setDescription('');
        },
      }
    );

could we change it to:

    createTask(
      variables: { body: { description } },
      onSuccess() {
          setDescription('');
       },
      refetchQueries:[tasksGetAllQueryKey]
      }
    );

advantages:

• No need to load the queryClient
• Having the logic of refetching/invalidating previously loaded queries simple and in a configurable way (instead of coding)
• Keep the focus of onSuccess on the current form only.

Also having variables separately helps not relying on parameters order while we have an object-style 2nd parameter.

[mahmoudmoravej]

Good to generate better variable names:

• tasksGetAllQueryKey -> getAllTasksQueryKey
• tasksCreateQueryKey -> createTaskQueryKey

[mahmoudmoravej]

Question: Why do we need to have 2 different clients? Can we merge them to give a single purpose compoent?

    <TodoAPIClientProvider client={client}>
      <QueryClientProvider client={queryClient}>

[tjosepo]

Good to generate better variable names:

Variable names are generated from the Operation IDs, from the OpenAPI specifications.

/task:
    get:
      operationId: tasksGetAll
      summary: Get the list of all tasks
      responses:
        200:
          description: List of all tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'

This endpoint is named tasksGetAll, and will generate tasksGetAllQueryKey, useTasksGetAllQuery, etc.

If users want to change the name of a hook, they need to change the operation ID.

[tjosepo]

Question: Why do we need to have 2 different clients? Can we merge them to give a single purpose compoent?

TanStack Query Client doesn't do the network request, it just handles caching, calling the data fetching function, and updating the React states.

Our OpenAPI client is what makes the request. We need to pass in some options, like the baseURL, so it makes the request successfully.

We may want to use multiple "OpenAPI Client" per "Query Client" (Tanstack Query).

[tjosepo]

I just focus a bit on usage for now. I will dig into it later. I copied the parts from your demo app:

    createTask(
      { body: { description } },
      {
        onSuccess() {
          queryClient.invalidateQueries({ queryKey: tasksGetAllQueryKey() });
          setDescription('');
        },
      }
    );

could we change it to:

    createTask(
      variables: { body: { description } },
      onSuccess() {
          setDescription('');
       },
      refetchQueries:[tasksGetAllQueryKey]
      }
    );

advantages:

• No need to load the queryClient
• Having the logic of refetching/invalidating previously loaded queries simple and in a configurable way (instead of coding)
• Keep the focus of onSuccess on the current form only.

Also having variables separately helps not relying on parameters order while we have an object-style 2nd parameter.

The createTask function is the mutate function returned by TanStack Query's useMutation hook. This tool did not create it. It's from TanStack Query.

I don't think it's worth trying to wrap the mutate and mutateAsync functions with our own abstraction. It introduces non-standard abstractions and we don't own the underlying function, which makes the whole abstraction very brittle.

[tjosepo]

Using buffer because we can't always trust the Content-Length header, since it's not added by default on the Response object.