···11+---
22+'@hey-api/openapi-ts': minor
33+---
44+55+feat(parser): add Hooks API
66+77+### Added Hooks API
88+99+This release adds the [Hooks API](https://heyapi.dev/openapi-ts/configuration/parser#hooks), giving you granular control over which operations generate queries and mutations. As a result, we tightened the previous behavior and POST operations no longer generate queries by default. To preserve the old behavior, add a custom matcher.
1010+1111+```js
1212+export default {
1313+ input: 'hey-api/backend', // sign up at app.heyapi.dev
1414+ output: 'src/client',
1515+ parser: {
1616+ hooks: {
1717+ operations: {
1818+ isQuery: (op) => (op.method === 'post' ? true : undefined),
1919+ },
2020+ },
2121+ },
2222+};
2323+```
···7788While we try to avoid breaking changes, sometimes it's unavoidable in order to offer you the latest features. This page lists changes that require updates to your code. If you run into a problem with migration, please [open an issue](https://github.com/hey-api/openapi-ts/issues).
991010+## v0.82.0
1111+1212+### Added Hooks API
1313+1414+This release adds the [Hooks API](/openapi-ts/configuration/parser#hooks), giving you granular control over which operations generate queries and mutations. As a result, we tightened the previous behavior and POST operations no longer generate queries by default. To preserve the old behavior, add a custom matcher.
1515+1616+```js
1717+export default {
1818+ input: 'hey-api/backend', // sign up at app.heyapi.dev
1919+ output: 'src/client',
2020+ parser: {
2121+ hooks: {
2222+ operations: {
2323+ isQuery: (op) => (op.method === 'post' ? true : undefined), // [!code ++]
2424+ },
2525+ },
2626+ },
2727+};
2828+```
2929+1030## v0.81.0
11311232### Server-Sent Events (SSE)
+2-2
docs/openapi-ts/plugins.md
···20202121These plugins help reduce boilerplate associated with third-party dependencies. Hey API natively supports the most popular packages. Please open an issue on [GitHub](https://github.com/hey-api/openapi-ts/issues) if you'd like us to support your favorite package.
22222323+- [`@angular/common`](/openapi-ts/plugins/angular)
2424+- [`@pinia/colada`](/openapi-ts/plugins/pinia-colada)
2325- [`@tanstack/angular-query-experimental`](/openapi-ts/plugins/tanstack-query)
2426- [`@tanstack/react-query`](/openapi-ts/plugins/tanstack-query)
2527- [`@tanstack/solid-query`](/openapi-ts/plugins/tanstack-query)
2628- [`@tanstack/svelte-query`](/openapi-ts/plugins/tanstack-query)
2729- [`@tanstack/vue-query`](/openapi-ts/plugins/tanstack-query)
2828-- [`@angular/common`](/openapi-ts/plugins/angular)
2930- [`fastify`](/openapi-ts/plugins/fastify)
3031- [`valibot`](/openapi-ts/plugins/valibot)
3132- [`zod`](/openapi-ts/plugins/zod)
···4748- [MSW](/openapi-ts/plugins/msw) <span data-soon>Soon</span>
4849- [Nest](/openapi-ts/plugins/nest) <span data-soon>Soon</span>
4950- [Nock](/openapi-ts/plugins/nock) <span data-soon>Soon</span>
5050-- [Pinia Colada](/openapi-ts/plugins/pinia-colada) <span data-soon>Soon</span>
5151- [Superstruct](/openapi-ts/plugins/superstruct) <span data-soon>Soon</span>
5252- [Supertest](/openapi-ts/plugins/supertest) <span data-soon>Soon</span>
5353- [SWR](/openapi-ts/plugins/swr) <span data-soon>Soon</span>
+210-7
docs/openapi-ts/plugins/pinia-colada.md
···11---
22-title: Pinia Colada
33-description: Pinia Colada plugin for Hey API. Compatible with all our features.
22+title: Pinia Colada v0 Plugin
33+description: Generate Pinia Colada v0 functions and query keys from OpenAPI with the Pinia Colada plugin for openapi-ts. Fully compatible with validators, transformers, and all core features.
44---
5566<script setup lang="ts">
77-import FeatureStatus from '@components/FeatureStatus.vue';
77+import AuthorsList from '@components/AuthorsList.vue';
88+import Heading from '@components/Heading.vue';
99+import VersionLabel from '@components/VersionLabel.vue';
1010+import { joshHemphill, sebastiaanWouters } from '@data/people.js';
811</script>
9121010-# Pinia Colada <span data-soon>soon</span>
1313+<Heading>
1414+ <h1>Pinia Colada<span class="sr-only"> v0</span></h1>
1515+ <VersionLabel value="v0" />
1616+</Heading>
1717+1818+### About
1919+2020+[Pinia Colada](https://pinia-colada.esm.dev) is the perfect companion to Pinia to handle async state management in your Vue applications.
2121+2222+The Pinia Colada plugin for Hey API generates functions and query keys from your OpenAPI spec, fully compatible with SDKs, transformers, and all core features.
2323+2424+### Collaborators
2525+2626+<AuthorsList :people="[joshHemphill, sebastiaanWouters]" />
2727+2828+## Features
2929+3030+- Pinia Colada v0 support
3131+- seamless integration with `@hey-api/openapi-ts` ecosystem
3232+- create query keys following the best practices
3333+- type-safe query options and mutation options
3434+- minimal learning curve thanks to extending the underlying technology
3535+3636+## Installation
3737+3838+In your [configuration](/openapi-ts/get-started), add `@pinia/colada` to your plugins and you'll be ready to generate Pinia Colada artifacts. :tada:
3939+4040+```js
4141+export default {
4242+ input: 'hey-api/backend', // sign up at app.heyapi.dev
4343+ output: 'src/client',
4444+ plugins: [
4545+ // ...other plugins
4646+ '@pinia/colada', // [!code ++]
4747+ ],
4848+};
4949+```
5050+5151+## Output
5252+5353+The Pinia Colada plugin will generate the following artifacts, depending on the input specification.
5454+5555+## Queries
5656+5757+Queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations). The generated query functions follow the naming convention of SDK functions and by default append `Query`, e.g. `getPetByIdQuery()`.
5858+5959+::: code-group
6060+6161+```ts [example]
6262+const { data, error } = useQuery({
6363+ ...getPetByIdQuery({
6464+ path: {
6565+ petId: 1,
6666+ },
6767+ }),
6868+});
6969+```
7070+7171+```js [config]
7272+export default {
7373+ input: 'hey-api/backend', // sign up at app.heyapi.dev
7474+ output: 'src/client',
7575+ plugins: [
7676+ // ...other plugins
7777+ {
7878+ name: '@pinia/colada',
7979+ queryOptions: true, // [!code ++]
8080+ },
8181+ ],
8282+};
8383+```
8484+8585+:::
8686+8787+You can customize the naming and casing pattern for `queryOptions` functions using the `.name` and `.case` options.
8888+8989+### Meta
9090+9191+You can use the `meta` field to attach arbitrary information to a query. To generate metadata for `queryOptions`, provide a function to the `.meta` option.
9292+9393+::: code-group
9494+9595+```ts [example]
9696+queryOptions({
9797+ // ...other fields
9898+ meta: {
9999+ id: 'getPetById',
100100+ },
101101+});
102102+```
103103+104104+```js [config]
105105+export default {
106106+ input: 'hey-api/backend', // sign up at app.heyapi.dev
107107+ output: 'src/client',
108108+ plugins: [
109109+ // ...other plugins
110110+ {
111111+ name: '@pinia/colada',
112112+ queryOptions: {
113113+ meta: (operation) => ({ id: operation.id }), // [!code ++]
114114+ },
115115+ },
116116+ ],
117117+};
118118+```
111191212-<FeatureStatus issueNumber=1242 name="Pinia Colada" />
120120+:::
121121+122122+## Query Keys
123123+124124+Query keys contain normalized SDK function parameters and additional metadata.
131251414-### About
126126+::: code-group
151271616-[Pinia Colada](https://pinia-colada.esm.dev) is the data fetching layer for Pinia.
128128+```ts [example]
129129+const queryKey = [
130130+ {
131131+ _id: 'getPetById',
132132+ baseUrl: 'https://app.heyapi.dev',
133133+ path: {
134134+ petId: 1,
135135+ },
136136+ },
137137+];
138138+```
17139140140+```js [config]
141141+export default {
142142+ input: 'hey-api/backend', // sign up at app.heyapi.dev
143143+ output: 'src/client',
144144+ plugins: [
145145+ // ...other plugins
146146+ {
147147+ name: '@pinia/colada',
148148+ queryKeys: true, // [!code ++]
149149+ },
150150+ ],
151151+};
152152+```
153153+154154+:::
155155+156156+### Accessing Query Keys
157157+158158+If you have access to the result of query options function, you can get the query key from the `queryKey` field.
159159+160160+::: code-group
161161+162162+```ts [example]
163163+const { queryKey } = getPetByIdOptions({
164164+ path: {
165165+ petId: 1,
166166+ },
167167+});
168168+```
169169+170170+```js [config]
171171+export default {
172172+ input: 'hey-api/backend', // sign up at app.heyapi.dev
173173+ output: 'src/client',
174174+ plugins: [
175175+ // ...other plugins
176176+ {
177177+ name: '@pinia/colada',
178178+ queryOptions: true, // [!code ++]
179179+ },
180180+ ],
181181+};
182182+```
183183+184184+:::
185185+186186+Alternatively, you can access the same query key by calling query key functions. The generated query key functions follow the naming convention of SDK functions and by default append `QueryKey`, e.g. `getPetByIdQueryKey()`.
187187+188188+::: code-group
189189+190190+```ts [example]
191191+const queryKey = getPetByIdQueryKey({
192192+ path: {
193193+ petId: 1,
194194+ },
195195+});
196196+```
197197+198198+```js [config]
199199+export default {
200200+ input: 'hey-api/backend', // sign up at app.heyapi.dev
201201+ output: 'src/client',
202202+ plugins: [
203203+ // ...other plugins
204204+ {
205205+ name: '@pinia/colada',
206206+ queryKeys: true, // [!code ++]
207207+ },
208208+ ],
209209+};
210210+```
211211+212212+:::
213213+214214+You can customize the naming and casing pattern for `queryKeys` functions using the `.name` and `.case` options.
215215+216216+## API
217217+218218+You can view the complete list of options in the [UserConfig](https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/@pinia/colada/types.d.ts) interface.
219219+220220+<!--@include: ../../partials/examples.md-->
18221<!--@include: ../../partials/sponsors.md-->
+3-3
docs/openapi-ts/plugins/tanstack-query.md
···104104105105## Queries
106106107107-Queries are generated from GET and POST endpoints. The generated query functions follow the naming convention of SDK functions and by default append `Options`, e.g. `getPetByIdOptions()`.
107107+Queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations). The generated query functions follow the naming convention of SDK functions and by default append `Options`, e.g. `getPetByIdOptions()`.
108108109109::: code-group
110110···302302303303## Infinite Queries
304304305305-Infinite queries are generated from GET and POST endpoints if we detect a [pagination](/openapi-ts/configuration/parser#pagination) parameter. The generated infinite query functions follow the naming convention of SDK functions and by default append `InfiniteOptions`, e.g. `getFooInfiniteOptions()`.
305305+Infinite queries are generated from [query operations](/openapi-ts/configuration/parser#hooks-query-operations) if we detect a [pagination](/openapi-ts/configuration/parser#pagination) parameter. The generated infinite query functions follow the naming convention of SDK functions and by default append `InfiniteOptions`, e.g. `getFooInfiniteOptions()`.
306306307307::: code-group
308308···504504505505## Mutations
506506507507-Mutations are generated from DELETE, PATCH, POST, and PUT endpoints. The generated mutation functions follow the naming convention of SDK functions and by default append `Mutation`, e.g. `addPetMutation()`.
507507+Mutations are generated from [mutation operations](/openapi-ts/configuration/parser#hooks-mutation-operations). The generated mutation functions follow the naming convention of SDK functions and by default append `Mutation`, e.g. `addPetMutation()`.
508508509509::: code-group
510510
+1-1
docs/openapi-ts/state-management.md
···11111212Hey API natively supports the following state managers.
13131414+- [Pinia Colada](/openapi-ts/plugins/pinia-colada)
1415- [TanStack Query](/openapi-ts/plugins/tanstack-query)
1515-- [Pinia Colada](/openapi-ts/plugins/pinia-colada) <span data-soon>Soon</span>
1616- [SWR](/openapi-ts/plugins/swr) <span data-soon>Soon</span>
1717- [Zustand](/openapi-ts/plugins/zustand) <span data-soon>Soon</span>
1818
···1717 name: '@hey-api/typescript'
1818 },
1919 {
2020- // Enable auto-detection of query vs mutation based on HTTP method
2121- autoDetectHttpMethod: true,
2222-2323- // Set to true to organize by tags
2424- // Export all tag files from index
2520 exportFromIndex: true,
2626-2727- // Group generated files by OpenAPI tags for better organization
2828- groupByTag: true,
2929-3030- name: '@pinia/colada',
3131- // Override specific operations if needed
3232- operationTypes: {
3333- // Example overrides (uncomment to use):
3434- // 'getPetById': 'both', // Generate both query and mutation
3535- // 'updatePet': 'query', // Force mutation to be a query
3636- }
2121+ name: '@pinia/colada'
3722 }
3823 ]
3924})
···11// This file is auto-generated by @hey-api/openapi-ts
22-export * from './@pinia/colada/pet.gen'
33-export * from './@pinia/colada/store.gen'
44-export * from './@pinia/colada/user.gen'
22+export * from './@pinia/colada.gen'
53export * from './sdk.gen'
64export * from './types.gen'