chore: add migration notes

Author: mrlubos

.changeset/long-keys-refuse.md

@@ -0,0 +1,20 @@
+---
+'@hey-api/openapi-ts': minor
+---
+
+feat: added `client.baseUrl` option
+
+### Added `client.baseUrl` option
+
+You can use this option to configure the default base URL for the generated client. By default, we will attempt to resolve the first defined server or infer the base URL from the input path. If you'd like to preserve the previous behavior, set `baseUrl` to `false`.
+
+```js
+export default {
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [{
+    baseUrl: false, // [!code ++]
+    name: '@hey-api/client-fetch',
+  }],
+};
+```

.changeset/unlucky-moles-dance.md

@@ -1,8 +1,18 @@
 ---
-'@hey-api/client-axios': patch
-'@hey-api/client-fetch': patch
-'@hey-api/client-next': patch
-'@hey-api/client-nuxt': patch
+'@hey-api/client-axios': minor
+'@hey-api/client-fetch': minor
+'@hey-api/client-next': minor
+'@hey-api/client-nuxt': minor
+'@hey-api/openapi-ts': minor
 ---
 
 fix: make createConfig, CreateClientConfig, and Config accept ClientOptions generic
+
+### Added `ClientOptions` interface
+
+The `Config` interface now accepts an optional generic extending `ClientOptions` instead of `boolean` type `ThrowOnError`.
+
+```ts
+type Foo = Config<false> // [!code --]
+type Foo = Config<{ throwOnError: false }> // [!code ++]
+```

docs/openapi-ts/clients/axios.md

@@ -106,7 +106,7 @@ In our custom file, we need to export a `createClientConfig()` method. This func
 ::: code-group
 
 ```ts [hey-api.ts]
-import type { CreateClientConfig } from '@hey-api/client-axios';
+import type { CreateClientConfig } from './client/client.gen';
 
 export const createClientConfig: CreateClientConfig = (config) => ({
   ...config,

docs/openapi-ts/clients/fetch.md

@@ -106,7 +106,7 @@ In our custom file, we need to export a `createClientConfig()` method. This func
 ::: code-group
 
 ```ts [hey-api.ts]
-import type { CreateClientConfig } from '@hey-api/client-fetch';
+import type { CreateClientConfig } from './client/client.gen';
 
 export const createClientConfig: CreateClientConfig = (config) => ({
   ...config,

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

@@ -102,7 +102,7 @@ In our custom file, we need to export a `createClientConfig()` method. This func
 ::: code-group
 
 ```ts [hey-api.ts]
-import type { CreateClientConfig } from '@hey-api/client-next';
+import type { CreateClientConfig } from './client/client.gen';
 
 export const createClientConfig: CreateClientConfig = (config) => ({
   ...config,

docs/openapi-ts/clients/nuxt.md

@@ -102,7 +102,7 @@ In our custom file, we need to export a `createClientConfig()` method. This func
 ::: code-group
 
 ```ts [hey-api.ts]
-import type { CreateClientConfig } from '@hey-api/client-nuxt';
+import type { CreateClientConfig } from './client/client.gen';
 
 export const createClientConfig: CreateClientConfig = (config) => ({
   ...config,

docs/openapi-ts/migrating.md

@@ -27,6 +27,34 @@ This config option is deprecated and will be removed in favor of [clients](./cli
 
 This config option is deprecated and will be removed.
 
+## v0.64.0
+
+### Added `ClientOptions` interface
+
+The `Config` interface now accepts an optional generic extending `ClientOptions` instead of `boolean` type `ThrowOnError`.
+
+```ts
+type Foo = Config<false>; // [!code --]
+type Foo = Config<{ throwOnError: false }>; // [!code ++]
+```
+
+### Added `client.baseUrl` option
+
+You can use this option to configure the default base URL for the generated client. By default, we will attempt to resolve the first defined server or infer the base URL from the input path. If you'd like to preserve the previous behavior, set `baseUrl` to `false`.
+
+```js
+export default {
+  input: 'path/to/openapi.json',
+  output: 'src/client',
+  plugins: [
+    {
+      baseUrl: false, // [!code ++]
+      name: '@hey-api/client-fetch',
+    },
+  ],
+};
+```
+
 ## v0.63.0
 
 ### Client plugins

examples/openapi-ts-next/src/client/client.gen.ts

@@ -1,7 +1,28 @@
 // This file is auto-generated by @hey-api/openapi-ts
 
-import { createClient, createConfig } from '@hey-api/client-next';
+import {
+  type ClientOptions as DefaultClientOptions,
+  type Config,
+  createClient,
+  createConfig,
+} from '@hey-api/client-next';
 
 import { createClientConfig } from '../hey-api';
+import type { ClientOptions } from './types.gen';
 
-export const client = createClient(createClientConfig(createConfig()));
+/**
+ * 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 DefaultClientOptions = ClientOptions> =
+  (
+    override?: Config<DefaultClientOptions & T>,
+  ) => Config<Required<DefaultClientOptions> & T>;
+
+export const client = createClient(
+  createClientConfig(createConfig<ClientOptions>()),
+);

examples/openapi-ts-next/src/client/types.gen.ts

@@ -561,3 +561,7 @@ export type UpdateUserResponses = {
    */
   default: unknown;
 };
+
+export type ClientOptions = {
+  baseUrl: `${string}://${string}/v3` | (string & {});
+};

examples/openapi-ts-next/src/hey-api.ts

@@ -1,4 +1,4 @@
-import type { CreateClientConfig } from '@hey-api/client-next';
+import type { CreateClientConfig } from './client/client.gen';
 
 export const createClientConfig: CreateClientConfig = (config) => ({
   ...config,

packages/openapi-ts/src/openApi/3.0.x/parser/index.ts

@@ -13,6 +13,7 @@ import { parseOperation } from './operation';
 import { parametersArrayToObject, parseParameter } from './parameter';
 import { parseRequestBody } from './requestBody';
 import { parseSchema } from './schema';
+import { parseServers } from './server';
 
 export const parseV3_0_X = (context: IR.Context<OpenApiV3_0_X>) => {
   const operationIds = new Map<string, string>();
@@ -99,9 +100,7 @@ export const parseV3_0_X = (context: IR.Context<OpenApiV3_0_X>) => {
     }
   }
 
-  if (context.spec.servers) {
-    context.ir.servers = context.spec.servers;
-  }
+  parseServers({ context });
 
   for (const path in context.spec.paths) {
     const pathItem = context.spec.paths[path as keyof PathsObject]!;

packages/openapi-ts/src/openApi/3.0.x/parser/server.ts

@@ -0,0 +1,26 @@
+import type { IR } from '../../../ir/types';
+import { parseUrl } from '../../../utils/url';
+
+export const parseServers = ({ context }: { context: IR.Context }) => {
+  if (context.spec.servers) {
+    context.ir.servers = context.spec.servers;
+    return;
+  }
+
+  if (typeof context.config.input.path === 'string') {
+    const url = parseUrl(context.config.input.path);
+    context.ir.servers = [
+      {
+        url: `${url.protocol ? `${url.protocol}://` : ''}${url.host}${url.port ? `:${url.port}` : ''}`,
+      },
+    ];
+  }
+
+  if (!context.ir.servers) {
+    context.ir.servers = [
+      {
+        url: '/',
+      },
+    ];
+  }
+};

packages/openapi-ts/src/openApi/3.1.x/parser/index.ts

@@ -13,6 +13,7 @@ import { parseOperation } from './operation';
 import { parametersArrayToObject, parseParameter } from './parameter';
 import { parseRequestBody } from './requestBody';
 import { parseSchema } from './schema';
+import { parseServers } from './server';
 
 export const parseV3_1_X = (context: IR.Context<OpenApiV3_1_X>) => {
   const operationIds = new Map<string, string>();
@@ -99,9 +100,7 @@ export const parseV3_1_X = (context: IR.Context<OpenApiV3_1_X>) => {
     }
   }
 
-  if (context.spec.servers) {
-    context.ir.servers = context.spec.servers;
-  }
+  parseServers({ context });
 
   for (const path in context.spec.paths) {
     const pathItem = context.spec.paths[path as keyof PathsObject]!;

packages/openapi-ts/src/openApi/3.1.x/parser/server.ts

@@ -0,0 +1,26 @@
+import type { IR } from '../../../ir/types';
+import { parseUrl } from '../../../utils/url';
+
+export const parseServers = ({ context }: { context: IR.Context }) => {
+  if (context.spec.servers) {
+    context.ir.servers = context.spec.servers;
+    return;
+  }
+
+  if (typeof context.config.input.path === 'string') {
+    const url = parseUrl(context.config.input.path);
+    context.ir.servers = [
+      {
+        url: `${url.protocol ? `${url.protocol}://` : ''}${url.host}${url.port ? `:${url.port}` : ''}`,
+      },
+    ];
+  }
+
+  if (!context.ir.servers) {
+    context.ir.servers = [
+      {
+        url: '/',
+      },
+    ];
+  }
+};

packages/openapi-ts/src/plugins/@hey-api/typescript/clientOptions.ts

@@ -53,16 +53,14 @@ export const createClientOptions = ({
     serverToBaseUrlType({ server }),
   );
 
-  if (!('strictBaseUrl' in client && client.strictBaseUrl)) {
-    if (servers.length) {
-      types.push(
-        compiler.typeIntersectionNode({
-          types: [stringType, ts.factory.createTypeLiteralNode([])],
-        }),
-      );
-    } else {
-      types.push(stringType);
-    }
+  if (!servers.length) {
+    types.push(stringType);
+  } else if (!('strictBaseUrl' in client && client.strictBaseUrl)) {
+    types.push(
+      compiler.typeIntersectionNode({
+        types: [stringType, ts.factory.createTypeLiteralNode([])],
+      }),
+    );
   }
 
   const typeClientOptions = compiler.typeAliasDeclaration({

packages/openapi-ts/test/__snapshots__/3.0.x/additional-properties-false/types.gen.ts

@@ -13,5 +13,5 @@ export type Baz = Foo & {
 };
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/additional-properties-true/types.gen.ts

@@ -15,5 +15,5 @@ export type Baz = Foo & {
 };
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/additional-properties-undefined/types.gen.ts

@@ -7,5 +7,5 @@ export type Foo = {
 };
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/array-items-one-of-length-1/types.gen.ts

@@ -7,5 +7,5 @@ export type Foo = {
 export type Bar = string;
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/body-response-text-plain/types.gen.ts

@@ -17,5 +17,5 @@ export type PostFooResponses = {
 export type PostFooResponse = PostFooResponses[keyof PostFooResponses];
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/case-PascalCase/types.gen.ts

@@ -85,5 +85,5 @@ export type GetFooResponses = {
 export type GetFooResponse = GetFooResponses[keyof GetFooResponses];
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/case-camelCase/types.gen.ts

@@ -85,5 +85,5 @@ export type getFooResponses = {
 export type getFooResponse = getFooResponses[keyof getFooResponses];
 
 export type clientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/case-snake_case/types.gen.ts

@@ -85,5 +85,5 @@ export type get_foo_responses = {
 export type get_foo_response = get_foo_responses[keyof get_foo_responses];
 
 export type client_options = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/case/types.gen.ts

@@ -85,5 +85,5 @@ export type GetFoo_Responses = {
 export type GetFoo_Response = GetFoo_Responses[keyof GetFoo_Responses];
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/components-request-bodies/types.gen.ts

@@ -25,5 +25,5 @@ export type PostFooResponses = {
 };
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/content-binary/types.gen.ts

@@ -27,5 +27,5 @@ export type GetBarResponses = {
 export type GetBarResponse = GetBarResponses[keyof GetBarResponses];
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/discriminator-all-of/types.gen.ts

@@ -45,5 +45,5 @@ export type QuxMapped = FooMapped & {
 };
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/discriminator-any-of/types.gen.ts

@@ -24,5 +24,5 @@ export type Quuz = ({
 } & Baz);
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/discriminator-one-of/types.gen.ts

@@ -24,5 +24,5 @@ export type Quuz = ({
 } & Baz);
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };

packages/openapi-ts/test/__snapshots__/3.0.x/enum-escape/types.gen.ts

@@ -7,5 +7,5 @@ export type Foo = {
 export type Bar = "foo'bar" | 'foo"bar';
 
 export type ClientOptions = {
-    baseUrl: string;
+    baseUrl: `${string}://${string}` | (string & {});
 };