Merge pull request #2284 from hey-api/fix/typescript-name

fix(typescript): add name option

Author: mrlubos

.changeset/silent-donkeys-itch.md

@@ -0,0 +1,7 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+### Removed `typescript+namespace` enums mode
+
+Due to a simpler TypeScript plugin implementation, the `typescript+namespace` enums mode is no longer necessary. This mode was used in the past to group inline enums under the same namespace. With the latest changes, this behavior is no longer supported. You can either choose to ignore inline enums (default), or use the `enums` transform (added in v0.78.0) to convert them into reusable components which will get exported as usual.

docs/openapi-ts/clients/axios.md

@@ -222,5 +222,9 @@ client.setConfig({
 
 You can use any of the approaches mentioned in [Configuration](#configuration), depending on how granular you want your custom instance to be.
 
+## Config API
+
+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/@hey-api/client-axios/types.d.ts) interface.
+
 <!--@include: ../../examples.md-->
 <!--@include: ../../sponsors.md-->

docs/openapi-ts/clients/fetch.md

@@ -299,5 +299,9 @@ client.setConfig({
 
 You can use any of the approaches mentioned in [Configuration](#configuration), depending on how granular you want your custom method to be.
 
+## Config API
+
+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/@hey-api/client-fetch/types.d.ts) interface.
+
 <!--@include: ../../examples.md-->
 <!--@include: ../../sponsors.md-->

docs/openapi-ts/clients/next-js.md

@@ -286,5 +286,9 @@ client.setConfig({
 
 You can use any of the approaches mentioned in [Configuration](#configuration), depending on how granular you want your custom method to be.
 
+## Config API
+
+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/@hey-api/client-next/types.d.ts) interface.
+
 <!--@include: ../../examples.md-->
 <!--@include: ../../sponsors.md-->

docs/openapi-ts/clients/nuxt.md

@@ -248,5 +248,9 @@ client.setConfig({
 
 You can use any of the approaches mentioned in [Configuration](#configuration), depending on how granular you want your custom method to be.
 
+## Config API
+
+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/@hey-api/client-nuxt/types.d.ts) interface.
+
 <!--@include: ../../examples.md-->
 <!--@include: ../../sponsors.md-->

docs/openapi-ts/migrating.md

@@ -7,6 +7,12 @@ description: Migrating to @hey-api/openapi-ts.
 
 While 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).
 
+## v0.79.0
+
+### Removed `typescript+namespace` enums mode
+
+Due to a simpler TypeScript plugin implementation, the `typescript+namespace` enums mode is no longer necessary. This mode was used in the past to group inline enums under the same namespace. With the latest changes, this behavior is no longer supported. You can either choose to ignore inline enums (default), or use the `enums` transform (added in v0.78.0) to convert them into reusable components which will get exported as usual.
+
 ## v0.78.0
 
 ### Added `parser` options

docs/openapi-ts/output/json-schema.md

@@ -96,5 +96,9 @@ if (userInput.length > maxInputLength) {
 }
 ```
 
+## Config API
+
+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/@hey-api/schemas/types.d.ts) interface.
+
 <!--@include: ../../examples.md-->
 <!--@include: ../../sponsors.md-->

docs/openapi-ts/output/sdk.md

@@ -224,5 +224,9 @@ export default {
 
 Learn more about available validators on the [Validators](/openapi-ts/validators) page.
 
+## Config API
+
+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/@hey-api/sdk/types.d.ts) interface.
+
 <!--@include: ../../examples.md-->
 <!--@include: ../../sponsors.md-->

docs/openapi-ts/output/typescript.md

@@ -7,67 +7,89 @@ description: Learn about files generated with @hey-api/openapi-ts.
 
 TypeScript interfaces are located in the `types.gen.ts` file. This is the only file that does not impact your bundle size and runtime performance. It will get discarded during build time, unless you configured to emit runtime [enums](#enums).
 
-This file contains three different categories of interfaces created from your input:
+## Installation
 
-- reusable components
-- operation request, response, and error data
-- enums
+In your [configuration](/openapi-ts/get-started), add `@hey-api/typescript` to your plugins and you'll be ready to generate TypeScript artifacts. :tada:
 
-Depending on your input and configuration, some of these categories might be missing or differ in your output (and that's okay!).
+```js
+export default {
+  input: 'https://get.heyapi.dev/hey-api/backend',
+  output: 'src/client',
+  plugins: [
+    // ...other plugins
+    '@hey-api/typescript', // [!code ++]
+  ],
+};
+```
 
-::: code-group
+:::tip
+The `@hey-api/typescript` plugin might be implicitly added to your `plugins` if another plugin depends on it.
+:::
 
-```ts [types.gen.ts]
-export type Pet = {
-  id?: number;
-  name: string;
-};
+## Output
+
+The TypeScript plugin will generate the following artifacts, depending on the input specification.
+
+## Requests
 
+A single request type is generated for each endpoint. It may contain a request body, parameters, and headers.
+
+```ts
 export type AddPetData = {
-  body: Pet;
+  body: {
+    id?: number;
+    name: string;
+  };
+  path?: never;
+  query?: never;
+  url: '/pets';
 };
-
-export type AddPetResponse = Pet;
 ```
 
-:::
+You can customize the naming and casing pattern for `requests` schemas using the `.name` and `.case` options.
 
-Every generated interface inside `types.gen.ts` is exported. You can import individual exports in your application and use them as necessary.
+## Responses
 
-## Configuration
+A single type is generated for all endpoint's responses.
 
-You can modify the contents of `types.gen.ts` by configuring the `@hey-api/typescript` plugin. Note that you must specify the default plugins to preserve the default output.
+```ts
+export type AddPetResponses = {
+  200: {
+    id?: number;
+    name: string;
+  };
+};
 
-```js
-import { defaultPlugins } from '@hey-api/openapi-ts';
+export type AddPetResponse = AddPetResponses[keyof AddPetResponses];
+```
 
-export default {
-  input: 'https://get.heyapi.dev/hey-api/backend',
-  output: 'src/client',
-  plugins: [
-    ...defaultPlugins,
-    {
-      name: '@hey-api/typescript',
-      // ...custom options // [!code ++]
-    },
-  ],
+You can customize the naming and casing pattern for `responses` schemas using the `.name` and `.case` options.
+
+## Definitions
+
+A type is generated for every reusable definition from your input.
+
+```ts
+export type Pet = {
+  id?: number;
+  name: string;
 };
 ```
 
+You can customize the naming and casing pattern for `definitions` schemas using the `.name` and `.case` options.
+
 ## Enums
 
-By default, `@hey-api/openapi-ts` will only emit enums as types. You may want to generate runtime artifacts. A good use case is iterating through possible field values without manually typing arrays. To emit runtime enums, set `enums` to a valid option.
+By default, `@hey-api/typescript` will emit enums only as types. You may want to generate runtime artifacts. A good use case is iterating through possible field values without manually typing arrays. To emit runtime enums, set `enums` to a valid option.
 
 ::: code-group
 
 ```js [disabled]
-import { defaultPlugins } from '@hey-api/openapi-ts';
-
 export default {
   input: 'https://get.heyapi.dev/hey-api/backend',
   output: 'src/client',
   plugins: [
-    ...defaultPlugins,
+    // ...other plugins
     {
       enums: false, // default // [!code ++]
       name: '@hey-api/typescript',
@@ -77,13 +99,11 @@ export default {
 ```
 
 ```js [javascript]
-import { defaultPlugins } from '@hey-api/openapi-ts';
-
 export default {
   input: 'https://get.heyapi.dev/hey-api/backend',
   output: 'src/client',
   plugins: [
-    ...defaultPlugins,
+    // ...other plugins
     {
       enums: 'javascript', // [!code ++]
       name: '@hey-api/typescript',
@@ -93,13 +113,11 @@ export default {
 ```
 
 ```js [typescript]
-import { defaultPlugins } from '@hey-api/openapi-ts';
-
 export default {
   input: 'https://get.heyapi.dev/hey-api/backend',
   output: 'src/client',
   plugins: [
-    ...defaultPlugins,
+    // ...other plugins
     {
       enums: 'typescript', // [!code ++]
       name: '@hey-api/typescript',
@@ -112,5 +130,9 @@ export default {
 
 We recommend exporting enums as plain JavaScript objects. [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html) are not a type-level extension of JavaScript and pose [typing challenges](https://dev.to/ivanzm123/dont-use-enums-in-typescript-they-are-very-dangerous-57bh).
 
+## Config API
+
+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/@hey-api/typescript/types.d.ts) interface.
+
 <!--@include: ../../examples.md-->
 <!--@include: ../../sponsors.md-->

docs/openapi-ts/plugins/custom.md

@@ -33,7 +33,7 @@ export type { MyPlugin } from './types';
 ```ts [types.d.ts]
 import type { DefinePlugin } from '@hey-api/openapi-ts';
 
-export type Config = {
+export type UserConfig = {
   /**
    * Plugin name. Must be unique.
    */
@@ -52,7 +52,7 @@ export type Config = {
   myOption?: boolean;
 };
 
-export type MyPlugin = DefinePlugin<Config>;
+export type MyPlugin = DefinePlugin<UserConfig>;
 ```
 
 :::