docs: add migration notes for 0.89.0

Author: mrlubos

dev/openapi-ts.config.ts

@@ -107,11 +107,11 @@ export default defineConfig(() => {
           // indexFile: false,
           // lint: 'eslint',
           nameConflictResolver({ attempt, baseName }) {
-            console.log('resolving conflict for:', { attempt, baseName });
+            // console.log('resolving conflict for:', { attempt, baseName });
             return attempt === 0 ? baseName : `${baseName}_N${attempt + 1}`;
           },
           path: path.resolve(__dirname, '.gen'),
-          preferExportAll: true,
+          // preferExportAll: true,
           resolveModuleName: (moduleName) => {
             if (moduleName === 'valibot') {
               return 'valibot';
@@ -146,6 +146,14 @@ export default defineConfig(() => {
         },
         hooks: {
           events: {
+            // 'node:set:after': ({ node, plugin }) => {
+            //   if (node) {
+            //     console.log(`(${plugin.name}) set node:`, node.symbol);
+            //   }
+            // },
+            // 'node:set:before': ({ node, plugin }) => {
+            //   console.log(`(${plugin.name}) setting node:`, node?.symbol?.id);
+            // },
             // 'plugin:handler:after': ({ plugin }) => {
             //   console.log(`(${plugin.name}): handler finished`);
             // },
@@ -171,12 +179,6 @@ export default defineConfig(() => {
               //   );
               // }
             },
-            // 'symbol:setValue:after': ({ plugin, symbol }) => {
-            //   console.log(`(${plugin.name}) set value:`, symbol.id);
-            // },
-            // 'symbol:setValue:before': ({ plugin, symbol }) => {
-            //   console.log(`(${plugin.name}) setting value:`, symbol.id);
-            // },
           },
           operations: {
             getKind() {

docs/openapi-ts/configuration/output.md

@@ -108,9 +108,9 @@ export default {
 
 :::
 
-## Import File Extension
+## Module Extension
 
-You can customize the extension used for imported TypeScript files.
+You can customize the extension used for TypeScript modules.
 
 ::: code-group
 
@@ -258,6 +258,33 @@ export default {
 
 You can also prevent your output from being linted by adding your output path to the linter's ignore file.
 
+## Name Conflicts
+
+As your project grows, the chances of name conflicts increase. We use a simple conflict resolver that appends numeric suffixes to duplicate identifiers. If you prefer a different strategy, you can provide your own `nameConflictResolver` function.
+
+::: code-group
+
+```js [config]
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    nameConflictResolver({ attempt, baseName }) {
+      // [!code ++]
+      return attempt === 0 ? baseName : `${baseName}_N${attempt + 1}`; // [!code ++]
+    }, // [!code ++]
+    path: 'src/client',
+  },
+};
+```
+
+```ts [example]
+export type ChatCompletion = string;
+
+export type ChatCompletion_N2 = number;
+```
+
+:::
+
 ## TSConfig Path
 
 We use the [TSConfig file](https://www.typescriptlang.org/tsconfig/) to generate output matching your project's settings. By default, we attempt to find a TSConfig file starting from the location of the `@hey-api/openapi-ts` configuration file and traversing up.

docs/openapi-ts/migrating.md

@@ -7,6 +7,28 @@ 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.89.0
+
+### Prefer named exports
+
+This release changes the default for `index.ts` to prefer named exports. Named exports may lead to better IDE and bundler performance compared to asterisk (`*`) as your tooling doesn't have to inspect the underlying module to discover exports.
+
+While this change is merely cosmetic, you can set `output.preferExportAll` to `true` if you prefer to use the asterisk.
+
+```js
+export default {
+  input: 'hey-api/backend', // sign up at app.heyapi.dev
+  output: {
+    path: 'src/client',
+    preferExportAll: true, // [!code ++]
+  },
+};
+```
+
+### Removed `symbol:setValue:*` events
+
+These events have been removed in favor of `node:set:*` events.
+
 ## v0.88.0
 
 ### Removed `compiler` and `tsc` exports

docs/openapi-ts/output.md

@@ -111,9 +111,5 @@ export default {
 };
 ```
 
-::: warning
-Re-exporting additional files from index file may result in broken output due to naming conflicts.
-:::
-
 <!--@include: ../partials/examples.md-->
 <!--@include: ../partials/sponsors.md-->

packages/codegen-core/src/planner/planner.ts

@@ -384,10 +384,10 @@ export class Planner {
       const ok = kinds.every((kind) => canShareName(symbol.kind, kind));
       if (ok) break;
 
+      const language = symbol.node?.language || symbol.file?.language;
       const resolver =
-        (symbol.node?.language
-          ? this.project.nameConflictResolvers[symbol.node.language]
-          : undefined) ?? this.project.defaultNameConflictResolver;
+        (language ? this.project.nameConflictResolvers[language] : undefined) ??
+        this.project.defaultNameConflictResolver;
       const resolvedName = resolver({ attempt, baseName });
       if (!resolvedName) {
         throw new Error(`Unresolvable name conflict: ${symbol.toString()}`);

packages/openapi-ts-tests/sdks/__snapshots__/opencode/export-all/client.gen.ts

@@ -0,0 +1,16 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { type ClientOptions, type Config, createClient, createConfig } from './client';
+import type { ClientOptions as ClientOptions2 } from './types.gen';
+
+/**
+ * The `createClientConfig()` function will be called on client initialization
+ * and the returned object will become the client's initial configuration.
+ *
+ * You may want to initialize your client this way instead of calling
+ * `setConfig()`. This is useful for example if you're using Next.js
+ * to ensure your client always has the correct values.
+ */
+export type CreateClientConfig<T extends ClientOptions = ClientOptions2> = (override?: Config<ClientOptions & T>) => Config<Required<ClientOptions> & T>;
+
+export const client = createClient(createConfig<ClientOptions2>());