@povio/openapi-codegen-cli 2.0.8-rc.9 → 3.0.0-rc.2

package/README.md

@@ -76,6 +76,7 @@ yarn openapi-codegen generate --config my-config.ts
   --splitByTags                       Organize output into separate folders based on OpenAPI operation tags (default: true)
   --defaultTag                        (Requires `--splitByTags`) Default tag for shared code across multiple tags (default: 'Common')
 
+  --includeTags                       Comma-separated list of tags to include in generation
   --excludeTags                       Comma-separated list of tags to exclude from generation
   --excludePathRegex                  Exclude operations whose paths match the given regular expression
   --excludeRedundantZodSchemas        Exclude any redundant Zod schemas (default: true)
@@ -91,7 +92,12 @@ yarn openapi-codegen generate --config my-config.ts
   --axiosRequestConfig                Include Axios request config parameters in query hooks (default: false)
   --infiniteQueries                   Generate infinite queries for paginated API endpoints (default: false)
   --mutationEffects                   Add mutation effects options to mutation hooks (default: true)
-  --workspaceContext                  Allow generated hooks to resolve path/ACL params from OpenApiWorkspaceContext (default: false)
+  --mutationScope                     Serialize mutations for the same path-param resource via TanStack scope.id (default: false).
+                                      In config files also accepts { include: string[] } or { exclude: string[] } to opt specific
+                                      operations in/out of scoping. Use "Tag/operationId" format for precision (e.g. "EmployeeSettings/update")
+                                      or just "operationId" to match across all tags. Cannot specify both include and exclude.
+  --mutationDefaultOnError            Use OpenApiQueryConfig.onError as the default onError for mutation hooks (default: false)
+  --workspaceContext                  Comma-separated list of path/ACL params that generated hooks may resolve from OpenApiWorkspaceContext
   --inlineEndpoints                   Inline endpoint implementations into generated query files (default: false)
   --inlineEndpointsExcludeModules     Comma-separated modules/tags to keep as separate API files while inlineEndpoints=true
   --modelsOnly                        Generate only model files (default: false)
@@ -115,6 +121,7 @@ yarn openapi-codegen generate --config my-config.ts
   --splitByTags                       Organize output into separate folders based on OpenAPI operation tags (default: true)
   --defaultTag                        (Requires `--splitByTags`) Default tag for shared code across multiple tags (default: 'Common')
 
+  --includeTags                       Comma-separated list of tags to include in generation
   --excludeTags                       Comma-separated list of tags to exclude from generation
   --excludePathRegex                  Exclude operations whose paths match the given regular expression
   --excludeRedundantZodSchemas        Exclude any redundant Zod schemas (default: true)
@@ -192,20 +199,36 @@ const config: OpenAPICodegenConfig = {
 export default config;
 ```
 
+### Default mutation errors
+
+Set `mutationDefaultOnError: true` in codegen config (or pass `--mutationDefaultOnError`) to let generated mutation hooks fall back to `OpenApiQueryConfig.Provider` when a mutation call does not define its own `onError`.
+
+```tsx
+import { ErrorHandler, OpenApiQueryConfig } from "@povio/openapi-codegen-cli";
+
+<OpenApiQueryConfig.Provider
+  onError={(error) => {
+    errorToast({ text: ErrorHandler.getErrorMessage(error) });
+  }}
+>
+  <App />
+</OpenApiQueryConfig.Provider>;
+```
+
 ### OpenApiWorkspaceContext (Path + ACL defaults)
 
-Enable `workspaceContext: true` in codegen config (or pass `--workspaceContext`) and wrap your app subtree with `OpenApiWorkspaceContext.Provider` if generated hooks frequently repeat workspace-scoped params (for example `officeId`).
+Set `workspaceContext` to a list of param names in codegen config (or pass `--workspaceContext officeId,projectId`) and wrap your app subtree with `OpenApiWorkspaceContext.Provider` if generated hooks frequently repeat workspace-scoped params.
 
 ```tsx
 import { OpenApiWorkspaceContext } from "@povio/openapi-codegen-cli";
-// openapi-codegen.config.ts -> { workspaceContext: true }
+// openapi-codegen.config.ts -> { workspaceContext: ["officeId", "projectId"] }
 
 <OpenApiWorkspaceContext.Provider values={{ officeId: "office_123" }}>
   <MyWorkspacePages />
 </OpenApiWorkspaceContext.Provider>;
 ```
 
-Generated query/mutation hooks can then omit matching path/ACL params and resolve them from `OpenApiWorkspaceContext`.
+Generated query/mutation hooks can then omit only those matching path/ACL params and resolve them from `OpenApiWorkspaceContext`. Params not listed in `workspaceContext` remain explicit and required.
 
 ### Generation Modes
 
@@ -242,12 +265,17 @@ export default defineConfig({
       output: "./src/data",
       inlineEndpoints: true,
       incremental: true,
+      formatGeneratedFile: async ({ fileName, content }) => {
+        void fileName;
+        return content;
+      },
     }),
   ],
 });
 ```
 
 The plugin runs on both `vite serve` and `vite build`, and watches local OpenAPI files in dev mode.
+If you provide `formatGeneratedFile`, the plugin formats each generated file in memory before comparing and writing it, which helps avoid unnecessary HMR when the formatted output is unchanged.
 
 ### Enums
 

package/dist/acl.d.mts

@@ -1,3 +1,4 @@
+import { r as ErrorHandler } from "./error-handling-CvW_FecB.mjs";
 import * as react from "react";
 import { PropsWithChildren } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
@@ -45,4 +46,14 @@ declare const Can: <TAppAbilities extends AppAbilities = AppAbilities>({
   ...props
 }: CanProps<TAppAbilities>) => react_jsx_runtime0.JSX.Element;
 //#endregion
-export { AbilityContext, type AppAbilities, type AppAbility, Can, createAclGuard };
+//#region src/lib/acl/useAclCheck.d.ts
+interface UseAclCheckProps {
+  errorHandler?: ErrorHandler<never>;
+}
+declare function useAclCheck<TAppAbilities extends AppAbilities = AppAbilities>({
+  errorHandler
+}?: UseAclCheckProps): {
+  checkAcl: (appAbility: TAppAbilities) => void;
+};
+//#endregion
+export { AbilityContext, type AppAbilities, type AppAbility, Can, createAclGuard, useAclCheck };

package/dist/acl.mjs

@@ -1,5 +1,6 @@
-import { n as OpenApiRouter, t as AuthContext } from "./auth.context-DKjzWiaA.mjs";
-import { createContext, useEffect, useState } from "react";
+import { r as SharedErrorHandler } from "./error-handling-DkPY7Asf.mjs";
+import { n as OpenApiRouter, t as AuthContext } from "./auth.context-Bu5KW2sI.mjs";
+import { createContext, useCallback, useEffect, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 import { AbilityBuilder, createMongoAbility } from "@casl/ability";
 import { unpackRules } from "@casl/ability/extra";
@@ -60,4 +61,14 @@ const Can = ({ use, ...props }) => {
 };
 
 //#endregion
-export { AbilityContext, Can, createAclGuard };
+//#region src/lib/acl/useAclCheck.ts
+function useAclCheck({ errorHandler } = {}) {
+	const ability = AbilityContext.useAbility();
+	return { checkAcl: useCallback((appAbility) => {
+		const [action, subject] = appAbility;
+		if (!ability.can(action, subject)) (errorHandler ?? SharedErrorHandler).rethrowError(/* @__PURE__ */ new Error("ACL check failed"));
+	}, [ability, errorHandler]) };
+}
+
+//#endregion
+export { AbilityContext, Can, createAclGuard, useAclCheck };

package/dist/{config-Cu_GYfai.d.mts → config-C1ME3Ay4.d.mts}

@@ -1,4 +1,4 @@
-import { t as GenerateOptions } from "./options-DBz5YE3s.mjs";
+import { t as GenerateOptions } from "./options-BPAjzilp.mjs";
 
 //#region src/generators/types/config.d.ts
 type OpenAPICodegenConfig = Partial<GenerateOptions>;

package/dist/error-handling-CvW_FecB.d.mts

@@ -0,0 +1,38 @@
+import { TFunction } from "i18next";
+
+//#region src/lib/rest/error-handling.d.ts
+type GeneralErrorCodes = "DATA_VALIDATION_ERROR" | "NETWORK_ERROR" | "CANCELED_ERROR" | "INTERNAL_ERROR" | "UNKNOWN_ERROR";
+declare class ApplicationException<CodeT> extends Error {
+  code: CodeT;
+  serverMessage: string | null;
+  constructor(message: string, code: CodeT, serverMessage: string | null);
+}
+interface ErrorEntry<CodeT> {
+  code: CodeT;
+  condition?: (error: unknown) => boolean;
+  getMessage: (t: TFunction<string, undefined>, error: unknown) => string;
+}
+interface ErrorHandlerOptions<CodeT extends string> {
+  entries: ErrorEntry<CodeT>[];
+  t?: TFunction<string, undefined>;
+  onRethrowError?: (error: unknown, exception: ApplicationException<CodeT | GeneralErrorCodes>) => void;
+}
+declare class ErrorHandler<CodeT extends string> {
+  entries: ErrorEntry<CodeT | GeneralErrorCodes>[];
+  private t;
+  private onRethrowError?;
+  constructor({
+    entries,
+    t,
+    onRethrowError
+  }: ErrorHandlerOptions<CodeT>);
+  private matchesEntry;
+  setTranslateFunction(t: TFunction<string, undefined>): void;
+  rethrowError(error: unknown): ApplicationException<CodeT | GeneralErrorCodes>;
+  getError(error: unknown): ApplicationException<CodeT | GeneralErrorCodes> | null;
+  getErrorCode(error: unknown): CodeT | GeneralErrorCodes | null;
+  static getErrorMessage(error: unknown, fallbackToUnknown?: boolean): string | null;
+}
+declare const SharedErrorHandler: ErrorHandler<never>;
+//#endregion
+export { GeneralErrorCodes as a, ErrorHandlerOptions as i, ErrorEntry as n, SharedErrorHandler as o, ErrorHandler as r, ApplicationException as t };

package/dist/error-handling-DkPY7Asf.mjs

@@ -0,0 +1,187 @@
+import { isAxiosError, isCancel } from "axios";
+import { z } from "zod";
+import i18next from "i18next";
+
+//#region src/lib/assets/locales/en/translation.json
+var translation_default$1 = { openapi: { "sharedErrors": {
+	"dataValidation": "An error occurred while validating the data",
+	"internalError": "An internal error occurred. This is most likely a bug on our end. Please try again later.",
+	"networkError": "A network error occurred. Are you connected to the internet?",
+	"canceledError": "The request was canceled.",
+	"unknownError": "An unknown error occurred. Please try again later.",
+	"unknownErrorWithCode": "An unknown error occurred. Error code: \"{{code}}\""
+} } };
+
+//#endregion
+//#region src/lib/assets/locales/sl/translation.json
+var translation_default = { openapi: { "sharedErrors": {
+	"dataValidation": "Pri preverjanju podatkov je prišlo do napake",
+	"internalError": "Prišlo je do notranje napake.",
+	"networkError": "Prišlo je do napake v omrežju.",
+	"canceledError": "Zahteva je bila preklicana.",
+	"unknownError": "Prišlo je do neznane napake.",
+	"unknownErrorWithCode": "Prišlo je do neznane napake. Koda napake: \"{{code}}\""
+} } };
+
+//#endregion
+//#region src/lib/config/i18n.ts
+const ns = "openapi";
+const resources = {
+	en: { [ns]: translation_default$1 },
+	sl: { [ns]: translation_default }
+};
+const defaultLanguage = "en";
+const i18n = i18next.createInstance();
+i18n.init({
+	compatibilityJSON: "v4",
+	lng: defaultLanguage,
+	fallbackLng: defaultLanguage,
+	resources,
+	ns: Object.keys(resources.en),
+	defaultNS: ns,
+	interpolation: { escapeValue: false }
+});
+const defaultT = i18n.t.bind(i18n);
+
+//#endregion
+//#region src/lib/rest/rest.utils.ts
+let RestUtils;
+(function(_RestUtils) {
+	_RestUtils.extractServerResponseCode = (e) => {
+		if (e instanceof z.ZodError) return "validation-exception";
+		if (!isAxiosError(e)) return null;
+		if (!e.response) return null;
+		const data = e.response.data;
+		if (typeof data?.code === "string") return data.code;
+		return null;
+	};
+	_RestUtils.doesServerErrorMessageContain = (e, text) => {
+		const message = extractServerErrorMessage(e);
+		if (message === null || message === void 0) return false;
+		return message.toLowerCase().includes(text.toLowerCase());
+	};
+	const extractServerErrorMessage = _RestUtils.extractServerErrorMessage = (e) => {
+		if (e instanceof z.ZodError) return e.message;
+		if (!isAxiosError(e)) return null;
+		if (!e.response) return null;
+		const data = e.response.data;
+		if (typeof data?.message === "string") return data.message;
+		return null;
+	};
+	_RestUtils.extractContentDispositionFilename = (headers) => {
+		const contentDisposition = headers["content-disposition"];
+		return contentDisposition ? /filename=["']?([^"';]+)/i.exec(contentDisposition)?.[1] : void 0;
+	};
+})(RestUtils || (RestUtils = {}));
+
+//#endregion
+//#region src/lib/rest/error-handling.ts
+var ApplicationException = class extends Error {
+	code;
+	serverMessage = null;
+	constructor(message, code, serverMessage) {
+		super(message);
+		this.code = code;
+		this.serverMessage = serverMessage;
+	}
+};
+var ErrorHandler = class {
+	entries = [];
+	t;
+	onRethrowError;
+	constructor({ entries, t = defaultT, onRethrowError }) {
+		this.t = t;
+		this.onRethrowError = onRethrowError;
+		const dataValidationError = {
+			code: "DATA_VALIDATION_ERROR",
+			condition: (e) => {
+				return e instanceof z.ZodError;
+			},
+			getMessage: () => this.t("openapi.sharedErrors.dataValidation")
+		};
+		const internalError = {
+			code: "INTERNAL_ERROR",
+			condition: (e) => {
+				if (isAxiosError(e)) return e.response?.status != null && e.response.status >= 500 && e.response.status < 600;
+				return false;
+			},
+			getMessage: () => this.t("openapi.sharedErrors.internalError")
+		};
+		const networkError = {
+			code: "NETWORK_ERROR",
+			condition: (e) => {
+				if (isAxiosError(e)) return e.code === "ERR_NETWORK";
+				return false;
+			},
+			getMessage: () => this.t("openapi.sharedErrors.networkError")
+		};
+		const canceledError = {
+			code: "CANCELED_ERROR",
+			condition: (e) => {
+				if (isCancel(e)) return true;
+				if (isAxiosError(e) && e.code === "ECONNABORTED") return true;
+				return false;
+			},
+			getMessage: () => this.t("openapi.sharedErrors.canceledError")
+		};
+		const unknownError = {
+			code: "UNKNOWN_ERROR",
+			condition: () => true,
+			getMessage: (_, e) => {
+				const code = RestUtils.extractServerResponseCode(e);
+				const serverMessage = RestUtils.extractServerErrorMessage(e);
+				if (code) {
+					let message = `Unknown error, message from server: ${code}`;
+					if (serverMessage) message += ` ${serverMessage}`;
+					return message;
+				}
+				return this.t("openapi.sharedErrors.unknownError");
+			}
+		};
+		this.entries = [
+			...entries,
+			dataValidationError,
+			internalError,
+			networkError,
+			canceledError,
+			unknownError
+		];
+	}
+	matchesEntry(error, entry, code) {
+		if (entry.condition) return entry.condition(error);
+		return code === entry.code;
+	}
+	setTranslateFunction(t) {
+		this.t = t;
+	}
+	rethrowError(error) {
+		const code = RestUtils.extractServerResponseCode(error);
+		const errorEntry = this.entries.find((entry) => this.matchesEntry(error, entry, code));
+		const serverMessage = RestUtils.extractServerErrorMessage(error);
+		const exception = new ApplicationException(errorEntry.getMessage(this.t, error), errorEntry.code, serverMessage);
+		this.onRethrowError?.(error, exception);
+		throw exception;
+	}
+	getError(error) {
+		if (error instanceof ApplicationException) return error;
+		return null;
+	}
+	getErrorCode(error) {
+		if (error instanceof ApplicationException) return error.code;
+		return null;
+	}
+	static getErrorMessage(error, fallbackToUnknown = true) {
+		if (typeof error === "string") return error;
+		if (error instanceof Error) return error.message;
+		if (error instanceof ApplicationException) {
+			if (error.serverMessage != null) return error.serverMessage;
+			return error.message;
+		}
+		if (fallbackToUnknown) return defaultT("openapi.sharedErrors.unknownError");
+		return null;
+	}
+};
+const SharedErrorHandler = new ErrorHandler({ entries: [] });
+
+//#endregion
+export { ns as a, RestUtils as i, ErrorHandler as n, resources as o, SharedErrorHandler as r, ApplicationException as t };

package/dist/generate.runner-BsNMtOTd.mjs

@@ -0,0 +1,90 @@
+import { S as Profiler, h as deepMerge, i as writeGenerateFileData, p as DEFAULT_GENERATE_OPTIONS, r as removeStaleGeneratedFiles, t as generateCodeFromOpenAPIDoc } from "./generateCodeFromOpenAPIDoc-CbBWYEZG.mjs";
+import path from "path";
+import SwaggerParser from "@apidevtools/swagger-parser";
+
+//#region src/generators/core/resolveConfig.ts
+function resolveConfig({ fileConfig = {}, params: { includeTags, excludeTags, inlineEndpointsExcludeModules, workspaceContext, ...options } }) {
+	const resolvedConfig = deepMerge(DEFAULT_GENERATE_OPTIONS, fileConfig ?? {}, {
+		...options,
+		includeTags: includeTags?.split(","),
+		excludeTags: excludeTags?.split(","),
+		inlineEndpointsExcludeModules: inlineEndpointsExcludeModules?.split(","),
+		workspaceContext: workspaceContext?.split(",")
+	});
+	resolvedConfig.checkAcl = resolvedConfig.acl && resolvedConfig.checkAcl;
+	resolvedConfig.workspaceContext = Array.from(new Set((resolvedConfig.workspaceContext ?? []).map((value) => value.trim()).filter(Boolean)));
+	return resolvedConfig;
+}
+
+//#endregion
+//#region src/generators/run/generate.runner.ts
+async function runGenerate({ fileConfig, params, formatGeneratedFile, profiler = new Profiler(process.env.OPENAPI_CODEGEN_PROFILE === "1") }) {
+	const config = profiler.runSync("config.resolve", () => resolveConfig({
+		fileConfig,
+		params: params ?? {}
+	}));
+	const openApiDoc = await getOpenApiDoc(config.input, profiler);
+	const filesData = profiler.runSync("generate.total", () => generateCodeFromOpenAPIDoc(openApiDoc, config, profiler));
+	if (config.clearOutput) profiler.runSync("files.removeStaleGenerated", () => {
+		removeStaleGeneratedFiles({
+			output: config.output,
+			filesData,
+			options: config
+		});
+	});
+	await profiler.runAsync("files.write", async () => {
+		await writeGenerateFileData(filesData, { formatGeneratedFile });
+	});
+	return {
+		skipped: false,
+		config,
+		stats: getGenerateStats(filesData, config)
+	};
+}
+async function getOpenApiDoc(input, profiler) {
+	const parsedDoc = await profiler.runAsync("openapi.parse", async () => await SwaggerParser.parse(input));
+	if (!profiler.runSync("openapi.detectExternalRefs", () => hasExternalRef(parsedDoc))) return parsedDoc;
+	return await profiler.runAsync("openapi.bundle", async () => await SwaggerParser.bundle(input));
+}
+function hasExternalRef(value) {
+	const stack = [value];
+	const visited = /* @__PURE__ */ new Set();
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (!current || typeof current !== "object") continue;
+		if (visited.has(current)) continue;
+		visited.add(current);
+		if ("$ref" in current && typeof current.$ref === "string" && !current.$ref.startsWith("#/")) return true;
+		for (const nested of Object.values(current)) if (nested && typeof nested === "object") stack.push(nested);
+	}
+	return false;
+}
+function getGenerateStats(filesData, config) {
+	const generatedFilesCount = filesData.length;
+	if (generatedFilesCount === 0) return {
+		generatedFilesCount,
+		generatedModulesCount: 0
+	};
+	if (!config.splitByTags) return {
+		generatedFilesCount,
+		generatedModulesCount: 1
+	};
+	const moduleSuffixes = new Set(Object.values(config.configs).map((generateConfig) => generateConfig.outputFileNameSuffix).filter(Boolean));
+	const modules = /* @__PURE__ */ new Set();
+	for (const file of filesData) {
+		const segments = path.relative(config.output, file.fileName).split(path.sep).filter(Boolean);
+		if (segments.length < 2) continue;
+		const moduleName = segments[0];
+		const fileName = segments[segments.length - 1];
+		if (!fileName.startsWith(`${moduleName}.`)) continue;
+		const suffix = fileName.slice(moduleName.length + 1).replace(/\.tsx?$/, "");
+		if (moduleSuffixes.has(suffix)) modules.add(moduleName);
+	}
+	return {
+		generatedFilesCount,
+		generatedModulesCount: modules.size
+	};
+}
+
+//#endregion
+export { resolveConfig as n, runGenerate as t };