Merge pull request #2664 from hey-api/feat/registry

🪧 Symbol API partie deux

Author: mrlubos

.changeset/beige-rocks-remain.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix(plugin): every plugin extends Plugin.Hooks interface

.changeset/eleven-beans-sort.md

@@ -0,0 +1,9 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix(renderer): group and sort imported modules
+
+### TypeScript renderer
+
+We ship a dedicated TypeScript renderer for `.ts` files. This release improves the renderer's ability to group and sort imported modules, resulting in a more polished output.

.changeset/healthy-experts-grow.md

@@ -0,0 +1,33 @@
+---
+'@hey-api/openapi-ts': patch
+---
+
+fix(config): add `output.fileName` option
+
+## File Name
+
+You can customize the naming and casing pattern for files using the `fileName` option.
+
+```js
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    fileName: '{{name}}',
+    path: 'src/client',
+  },
+};
+```
+
+By default, we append every file name with a `.gen` suffix to highlight it's automatically generated. You can customize or disable this suffix using the `fileName.suffix` option.
+
+```js
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    fileName: {
+      suffix: '.gen',
+    },
+    path: 'src/client',
+  },
+};
+```

.changeset/selfish-hornets-beg.md

@@ -0,0 +1,5 @@
+---
+'@hey-api/codegen-core': minor
+---
+
+feat: Symbol API

.changeset/two-buses-dance.md

@@ -0,0 +1,15 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+feat: Symbol API
+
+### Symbol API
+
+This release improves the Symbol API, which adds the capability to place symbols in arbitrary files. We preserved the previous output structure for all plugins except Angular.
+
+You can preserve the previous Angular output by writing your own [placement function](https://heyapi.dev/openapi-ts/configuration/parser#hooks-symbols).
+
+### Removed `output` plugin option
+
+Due to the Symbol API release, this option has been removed from the Plugin API.

docs/.vitepress/config/en.ts

@@ -258,7 +258,7 @@ export default defineConfig({
             text: 'Custom',
           },
         ],
-        text: 'Guides and Concepts',
+        text: 'Plugins',
       },
       {
         items: [

docs/openapi-ts/configuration/output.md

@@ -34,6 +34,78 @@ export default {
 
 :::
 
+## File Name
+
+You can customize the naming and casing pattern for files using the `fileName` option.
+
+::: code-group
+
+```js [default]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    fileName: '{{name}}', // [!code ++]
+    path: 'src/client',
+  },
+};
+```
+
+```js [snake_case]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    fileName: {
+      case: 'snake_case', // [!code ++]
+    },
+    path: 'src/client',
+  },
+};
+```
+
+:::
+
+By default, we append every file name with a `.gen` suffix to highlight it's automatically generated. You can customize or disable this suffix using the `fileName.suffix` option.
+
+::: code-group
+
+```js [default]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    fileName: {
+      suffix: '.gen', // [!code ++]
+    },
+    path: 'src/client',
+  },
+};
+```
+
+```js [off]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    fileName: {
+      suffix: null, // [!code ++]
+    },
+    path: 'src/client',
+  },
+};
+```
+
+```js [custom]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    fileName: {
+      suffix: '.generated', // [!code ++]
+    },
+    path: 'src/client',
+  },
+};
+```
+
+:::
+
 ## Format
 
 To format your output folder contents, set `output.format` to a valid formatter.

docs/openapi-ts/configuration/parser.md

@@ -460,7 +460,36 @@ export default {
 
 ## Hooks
 
-Hooks affect runtime behavior but aren’t tied to any single plugin. They can be configured globally via `parser.hooks` or per plugin through the `~hooks` property.
+Hooks affect runtime behavior but aren’t tied to any single plugin. They can be configured globally via `hooks` or per plugin through the `~hooks` property.
+
+::: code-group
+
+```js [parser]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  parser: {
+    hooks: {}, // configure global hooks here // [!code ++]
+  },
+};
+```
+
+```js [plugin]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  plugins: [
+    {
+      name: '@tanstack/react-query',
+      '~hooks': {}, // configure plugin hooks here // [!code ++]
+    },
+  ],
+};
+```
+
+:::
+
+We always use the first hook that returns a value. If a hook returns no value, we fall back to less specific hooks until one does.
 
 ### Operations {#hooks-operations}
 
@@ -478,12 +507,12 @@ By default, DELETE, PATCH, POST, and PUT operations are classified as `mutation`
 
 Imagine your API has a POST `/search` endpoint that accepts a large payload. By default, it's classified as a `mutation`, but in practice it behaves like a `query`, and your [state management](/openapi-ts/state-management) plugin should generate query hooks.
 
-You can fix this by classifying the operation as `query` in a matcher. If a matcher returns no value, we fall back to less specific matchers until one does.
+You can achieve this by classifying the operation as `query` in a matcher.
 
 ::: code-group
 
 <!-- prettier-ignore-start -->
-```js [parser]
+```js [isQuery]
 export default {
   input: 'hey-api/backend', // sign up at app.heyapi.dev
   output: 'src/client',
@@ -502,29 +531,56 @@ export default {
 ```
 <!-- prettier-ignore-end -->
 <!-- prettier-ignore-start -->
-```js [plugin]
+```js [getKind]
 export default {
   input: 'hey-api/backend', // sign up at app.heyapi.dev
   output: 'src/client',
-  plugins: [
-    {
-      name: '@tanstack/react-query',
-      '~hooks': {
-        operations: {
-          getKind: (op) => {
-            if (op.method === 'post' && op.path === '/search') { // [!code ++]
-              return ['query']; // [!code ++]
-            } // [!code ++]
-          },
+  parser: {
+    hooks: {
+      operations: {
+        getKind: (op) => {
+          if (op.method === 'post' && op.path === '/search') { // [!code ++]
+            return ['query']; // [!code ++]
+          } // [!code ++]
         },
       },
     },
-  ],
+  },
 };
 ```
 <!-- prettier-ignore-end -->
 
 :::
 
+### Symbols {#hooks-symbols}
+
+Each symbol can have a placement function deciding its output location.
+
+#### Example: Alphabetic sort
+
+While we work on a better example, let's imagine a world where it's desirable to place every symbol in a file named after its initial letter. For example, a function named `Foo` should end up in the file `f.ts`.
+
+You can achieve this by using the symbol's name.
+
+<!-- prettier-ignore-start -->
+```js [getKind]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: 'src/client',
+  parser: {
+    hooks: {
+      symbols: {
+        getFilePath: (symbol) => {
+          if (symbol.name) { // [!code ++]
+            return symbol.name[0]?.toLowerCase(); // [!code ++]
+          } // [!code ++]
+        },
+      },
+    },
+  },
+};
+```
+<!-- prettier-ignore-end -->
+
 <!--@include: ../../partials/examples.md-->
 <!--@include: ../../partials/sponsors.md-->

docs/openapi-ts/get-started.md

@@ -21,7 +21,7 @@ Launch demo
 
 - runs in CLI, Node.js 18+, or npx
 - works with OpenAPI 2.0, 3.0, and 3.1
-- customizable types and SDKs
+- core plugins for types, SDKs, and schemas
 - clients for your runtime (Fetch API, Angular, Axios, Next.js, Nuxt, etc.)
 - plugin ecosystem to reduce third-party boilerplate
 - custom plugins and custom clients

docs/openapi-ts/migrating.md

@@ -7,6 +7,22 @@ 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.84.0
+
+### Symbol API
+
+This release improves the Symbol API, which adds the capability to place symbols in arbitrary files. We preserved the previous output structure for all plugins except Angular.
+
+You can preserve the previous Angular output by writing your own [placement function](/openapi-ts/configuration/parser#hooks-symbols).
+
+### TypeScript renderer
+
+We ship a dedicated TypeScript renderer for `.ts` files. This release improves the renderer's ability to group and sort imported modules, resulting in a more polished output.
+
+### Removed `output` plugin option
+
+Due to the Symbol API release, this option has been removed from the Plugin API.
+
 ## v0.83.0
 
 ### Symbol API