@kubb/plugin-fetch 5.5.0-canary.20260924T110844 → 5.5.0

package/dist/index.d.ts

@@ -25,9 +25,8 @@ type Mode = 'tag' | 'flat';
 /**
  * Shape of the value a generated operation function resolves to.
  * - `'full'`: the complete `{ status, data, error, contentType, request, response }` result.
- * - `'data'`: the bare success body once `throwOnError` (on by default) narrows away the error
- *   branch, falling back to the full result when a call sets `throwOnError: false` and still
- *   needs `error` to discriminate a failed response.
+ * - `'data'`: the bare success body when `throwOnError` is true, or the full result when it is false
+ *   so callers can inspect `error`.
  */
 type ReturnTypeOption = 'full' | 'data';
 /**
@@ -71,13 +70,20 @@ type Options = OutputOptions & {
   /**
    * Apply a different options object to operations matching a pattern.
    */
-  override?: Array<Override<ResolvedOptions>>;
+  override?: Array<Override<Omit<ResolvedOptions, 'throwOnErrorDefault'>>>;
   /**
    * Base URL prepended to every request. When omitted, falls back to the adapter's server URL.
    * Values containing a `${...}` interpolation are emitted as template literals in the generated
    * client config, which keeps runtime environment reads dynamic.
    */
   baseURL?: string;
+  /**
+   * Default error behavior for generated operations and their client. Per-call `throwOnError`
+   * takes precedence.
+   *
+   * @default true
+   */
+  throwOnErrorDefault?: boolean;
   /**
    * Validate request and response bodies with schemas from `@kubb/plugin-zod`.
    *
@@ -160,9 +166,10 @@ type ResolvedOptions = {
   output: Output;
   exclude: Array<Exclude>;
   include: Array<Include> | undefined;
-  override: Array<Override<ResolvedOptions>>;
+  override: Array<Override<Omit<ResolvedOptions, 'throwOnErrorDefault'>>>;
   group: Group | null;
   baseURL: Options['baseURL'];
+  throwOnErrorDefault: boolean;
   validator: NonNullable<Options['validator']>;
   returnType: ReturnTypeOption;
   sdk: {

package/dist/index.js

@@ -5,6 +5,7 @@ import { createFunctionParameter, createFunctionParameters, functionPrinter, plu
 import { File, Function, jsxRenderer } from "kubb/jsx";
 import { Fragment, jsx, jsxs } from "kubb/jsx/jsx-runtime";
 import { pluginZodName } from "@kubb/plugin-zod";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region ../../internals/shared/src/params.ts
 /**
@@ -475,7 +476,7 @@ function buildResultType({ node, types, returnType }) {
 * `withUnwrap`, so the caller can `await` it directly or call `.unwrap()` for the bare success
 * body. With `returnType: 'data'` it instead routes the call through the runtime's `unwrapResult`,
 * which narrows the resolved value down to the bare success body the same way `RequestResult`
-* already does, keeping the `throwOnError` default in one place instead of restating it per call.
+* already does, using the plugin default when the call leaves `throwOnError` unset.
 *
 * Cast first, wrap second, for the `'full'` path. That order keeps `withUnwrap`'s generic inferred
 * as `RequestResult` instead of the runtime's own internal result type. Casting an `Unwrappable<A>`
@@ -485,10 +486,10 @@ function buildResultType({ node, types, returnType }) {
 * @example
 * `return withUnwrap(request({ method: 'POST', url: '/pet', ...config }) as Promise<RequestResult<AddPetResponses, ThrowOnError>>)`
 * @example
-* `return unwrapResult(request({ method: 'POST', url: '/pet', ...config }), config.throwOnError) as Promise<UnwrappedResult<AddPetResponses, ThrowOnError>>`
+* `return unwrapResult(request({ method: 'POST', url: '/pet', ...config }), config.throwOnError ?? false) as Promise<UnwrappedResult<AddPetResponses, ThrowOnError>>`
 */
-function buildReturnStatement({ node, types, callConfig, returnType }) {
-	if (returnType === "data") return `return unwrapResult(request(${callConfig}), config.throwOnError) as ${buildResultType({
+function buildReturnStatement({ node, types, callConfig, returnType, throwOnErrorDefault }) {
+	if (returnType === "data") return `return unwrapResult(request(${callConfig}), config.throwOnError ?? ${throwOnErrorDefault}) as ${buildResultType({
 		node,
 		types,
 		returnType
@@ -578,7 +579,7 @@ const declarationPrinter = functionPrinter({ mode: "declaration" });
 * per-operation input type has to be emitted. Both names come from `types`, which is `plugin-ts` or
 * `plugin-zod`'s inferred types (see `resolveOperationTypes`).
 */
-function buildGroupedOptionsSignature({ node, types, returnType }) {
+function buildGroupedOptionsSignature({ node, types, returnType, throwOnErrorDefault }) {
 	const optionsName = types.response.options(node);
 	const { isOptional } = getRequestGroupOptionality(node);
 	return {
@@ -592,7 +593,7 @@ function buildGroupedOptionsSignature({ node, types, returnType }) {
 			types,
 			returnType
 		}),
-		generics: ["ThrowOnError extends boolean = true"]
+		generics: [`ThrowOnError extends boolean = ${throwOnErrorDefault}`]
 	};
 }
 //#endregion
@@ -686,9 +687,10 @@ function buildValidatorHooks({ node, validator, zodResolver }) {
 /**
 * Builds the call config literal forwarded to the contract client, mirroring the shared `Operation`
 * component: `{ method, url, security?, validator?, ...config }`. The `...config` spread carries every
-* per-call field (including `throwOnError`), so the method stays a thin wrapper over the contract.
+* per-call field. The plugin's `throwOnError` fallback is applied after the spread so it also wins
+* over a client instance's runtime config when the call omits an override.
 */
-function buildCallConfig({ node, validator, zodResolver, security }) {
+function buildCallConfig({ node, validator, zodResolver, security, throwOnErrorDefault }) {
 	const validators = buildValidatorHooks({
 		node,
 		validator,
@@ -702,7 +704,8 @@ function buildCallConfig({ node, validator, zodResolver, security }) {
 		`url: '${node.path}'`,
 		securityLiteral ? `security: ${securityLiteral}` : null,
 		validatorLiteral,
-		"...config"
+		"...config",
+		`throwOnError: config.throwOnError ?? ${throwOnErrorDefault}`
 	].filter(Boolean).join(", ")} }`;
 }
 /**
@@ -712,12 +715,13 @@ function buildCallConfig({ node, validator, zodResolver, security }) {
 * instance client, so one operation can be routed to a different environment without a new
 * instance.
 */
-function buildSdkMethod({ node, name, types, zodResolver, validator, security, returnType }) {
+function buildSdkMethod({ node, name, types, zodResolver, validator, security, returnType, throwOnErrorDefault }) {
 	if (!ast.isHttpOperationNode(node)) return "";
 	const signature = buildGroupedOptionsSignature({
 		node,
 		types,
-		returnType
+		returnType,
+		throwOnErrorDefault
 	});
 	const returnStatement = buildReturnStatement({
 		node,
@@ -726,9 +730,11 @@ function buildSdkMethod({ node, name, types, zodResolver, validator, security, r
 			node,
 			validator,
 			zodResolver,
-			security
+			security,
+			throwOnErrorDefault
 		}),
-		returnType
+		returnType,
+		throwOnErrorDefault
 	});
 	const generics = signature.generics.length ? `<${signature.generics.join(", ")}>` : "";
 	const jsdoc = buildJSDoc(buildOperationComments(node, {
@@ -804,12 +810,13 @@ function buildStyles({ node }) {
 * type, signature, and call config are built with the AST factory, and only the jsx-renderer emits
 * the source.
 */
-function Operation({ name, node, types, zodResolver, validator, returnType, security, isExportable = true, isIndexable = true }) {
+function Operation({ name, node, types, zodResolver, validator, returnType, throwOnErrorDefault, security, isExportable = true, isIndexable = true }) {
 	if (!ast.isHttpOperationNode(node)) return null;
 	const signature = buildGroupedOptionsSignature({
 		node,
 		types,
-		returnType
+		returnType,
+		throwOnErrorDefault
 	});
 	const validators = buildValidatorHooks({
 		node,
@@ -839,7 +846,8 @@ function Operation({ name, node, types, zodResolver, validator, returnType, secu
 		validatorLiteral,
 		contentTypeLiteral,
 		responseTypeLiteral,
-		"...config"
+		"...config",
+		`throwOnError: config.throwOnError ?? ${throwOnErrorDefault}`
 	].filter(Boolean).join(", ")} }`;
 	const eventType = `SuccessOf<${types.response.responses(node)}>`;
 	const functionReturnType = eventStream ? `Promise<EventStreamResult<${eventType}>>` : signature.returnType;
@@ -847,7 +855,8 @@ function Operation({ name, node, types, zodResolver, validator, returnType, secu
 		node,
 		types,
 		callConfig,
-		returnType
+		returnType,
+		throwOnErrorDefault
 	});
 	return /* @__PURE__ */ jsx(File.Source, {
 		name,
@@ -880,7 +889,7 @@ function Operation({ name, node, types, zodResolver, validator, returnType, secu
 * instance: `const api = new PetClient({ baseURL }); api.getPetById(...)`. A per-call `client` option
 * still overrides the instance client for a one-off call.
 */
-function SdkClient({ name, isExportable = true, isIndexable = true, operations, validator, returnType, children }) {
+function SdkClient({ name, isExportable = true, isIndexable = true, operations, validator, returnType, throwOnErrorDefault, children }) {
 	const methods = operations.map(({ node, name: methodName, types, zodResolver, security }) => buildSdkMethod({
 		node,
 		name: methodName,
@@ -888,7 +897,8 @@ function SdkClient({ name, isExportable = true, isIndexable = true, operations,
 		zodResolver,
 		validator,
 		security,
-		returnType
+		returnType,
+		throwOnErrorDefault
 	}));
 	const classCode = `export class ${name} {\n${[
 		"  private readonly client: ClientInstance",
@@ -968,7 +978,7 @@ function createClientGenerator(name) {
 		operation(node, ctx) {
 			if (!ast.isHttpOperationNode(node)) return null;
 			const { config, driver, resolver, root } = ctx;
-			const { output, validator, returnType, group } = ctx.options;
+			const { output, validator, returnType, throwOnErrorDefault, group } = ctx.options;
 			const types = resolveOperationTypes(driver);
 			if (!types) {
 				ctx.warn(MISSING_OPERATION_TYPES_WARNING);
@@ -1071,6 +1081,7 @@ function createClientGenerator(name) {
 						zodResolver,
 						validator,
 						returnType,
+						throwOnErrorDefault,
 						security
 					})
 				]
@@ -1211,7 +1222,7 @@ function createSdkGenerator() {
 		renderer: jsxRenderer,
 		operations(nodes, ctx) {
 			const { config, resolver, root } = ctx;
-			const { output, group, validator, returnType, sdk } = ctx.options;
+			const { output, group, validator, returnType, throwOnErrorDefault, sdk } = ctx.options;
 			if (!sdk) return null;
 			const types = resolveOperationTypes(ctx.driver);
 			if (!types) {
@@ -1297,7 +1308,8 @@ function createSdkGenerator() {
 							name: className,
 							operations: ops,
 							validator,
-							returnType
+							returnType,
+							throwOnErrorDefault
 						})
 					]
 				}, file.path);
@@ -1383,6 +1395,27 @@ const resolverClient = createResolver({
 	}
 });
 //#endregion
+//#region ../../internals/client/src/runtimeTemplate.ts
+/** Apply the active TypeScript parser's import extension to a copied client runtime. */
+function runtimeTemplate(path, config) {
+	const parser = config.parsers.find((item) => item.extNames?.includes(".ts"));
+	const probe = ast.factory.createFile({
+		baseName: "probe.ts",
+		path: "probe.ts",
+		imports: [ast.factory.createImport({
+			name: ["KubbRuntimeImport"],
+			path: "/probeDependency.ts",
+			root: "/"
+		})],
+		sources: [ast.factory.createSource({
+			name: "probe",
+			nodes: [ast.factory.createText("KubbRuntimeImport")]
+		})]
+	});
+	const extension = parser?.parse(probe).match(/from ['"]\.\/probeDependency(\.[^'"]+)?['"]/)?.[1] ?? "";
+	return readFileSync(path, "utf8").replace(/(from ['"]\.\/(?:serializers|standardSchema))(?:\.ts|\.js)?(['"])/g, `$1${extension}$2`);
+}
+//#endregion
 //#region src/generators/clientGenerator.tsx
 /**
 * Built-in operation generator for `@kubb/plugin-fetch`. Emits one async function per OpenAPI
@@ -1434,7 +1467,7 @@ const pluginFetch = definePlugin((options) => {
 	const { output = {
 		path: "clients",
 		barrel: { type: "named" }
-	}, exclude = [], include, override = [], baseURL, validator = false, returnType = "full", group, sdk, resolver: userResolver } = options;
+	}, exclude = [], include, override = [], baseURL, throwOnErrorDefault = true, validator = false, returnType = "full", group, sdk, resolver: userResolver } = options;
 	const resolved = {
 		output,
 		exclude,
@@ -1442,6 +1475,7 @@ const pluginFetch = definePlugin((options) => {
 		override,
 		group: createGroupConfig(group),
 		baseURL,
+		throwOnErrorDefault,
 		validator,
 		returnType,
 		sdk: sdk ? {
@@ -1470,7 +1504,7 @@ const pluginFetch = definePlugin((options) => {
 			ctx.injectFile({
 				baseName: "client.ts",
 				path: path.resolve(root, ".kubb/client.ts"),
-				copy: fetchClientTemplatePath,
+				banner: runtimeTemplate(fetchClientTemplatePath, ctx.config),
 				footer: baseURLExpression ? `client.setConfig({ baseURL: ${baseURLExpression} })` : void 0
 			});
 			ctx.injectFile({