@bepalo/spine 1.4.13 → 1.5.15

package/dist/router.js

@@ -26,7 +26,7 @@ var __asyncValues = (this && this.__asyncValues) || function (o) {
     function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
     function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
 };
-var _Router_instances, _Router_config, _Router_routes, _Router_processPath, _Router_getRouteEntries, _Router_InitEntries, _Router_initRoutes;
+var _Router_instances, _Router_config, _Router_routes, _Router_generateUniqueOperationId, _Router_processPath, _Router_getRouteEntries, _Router_InitEntries, _Router_initRoutes;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.translateRouteFilePath = exports.Router = exports.HANDLER_TYPES = exports.HTTP_METHODS_UPPER = exports.CRUD_METHODS = exports.HTTP_METHODS = exports.REGISTER_PATH_REGEX = exports.PATH_PART_REGEX = void 0;
 const status_ts_1 = require("./status.js");
@@ -465,19 +465,172 @@ class Router {
             }
         });
     }
-    generateOpenAPI(info) {
-        const { title = "API", version = "1.0.0", description, servers = [{ url: "/", description: "Current server" }], security, components: globalComponents, } = info !== null && info !== void 0 ? info : {};
+    /**
+     * Generates an OpenAPI 3.0.0 specification document from the registered routes.
+     *
+     * This method scans all registered routes and builds a comprehensive OpenAPI specification
+     * that can be used with Swagger UI, Redoc, or any OpenAPI-compatible tooling.
+     *
+     * @param info - Configuration for the OpenAPI document
+     * @param info.title - API title (defaults to "API")
+     * @param info.version - API version (defaults to "1.0.0")
+     * @param info.description - API description
+     * @param info.servers - Array of server URLs and descriptions
+     * @param info.security - Global security requirements
+     * @param info.components - Reusable components (schemas, securitySchemes, parameters, responses, examples)
+     * @param info.termsOfService - URL to terms of service
+     * @param info.contact - Contact information for the API
+     * @param info.license - License information
+     * @param info.tags - Global tags for grouping operations
+     * @param info.externalDocs - External documentation reference
+     *
+     * @param options - Generation options
+     * @param {Map<HttpMethodUpper,number>} options.sortMethodPriorityMap - Map method to priority for the default sorter.
+     * @param {1|-1|undefined} options.sortPathnameOrder - Enable and define the pathname sort order for the default sorter.
+     * @param {1|-1|undefined} options.sortMethodOrder - Enable and define the method sort order for the default sorter.
+     * @param {1|-1|undefined} options.sortTagsOrder - Enable and define the tags sort order for the default sorter.
+     * @param options.pick - Filter function to selectively include routes
+     *   - Receives one `GenerateOpenAPISortParam` parameter: `{ method, path, parts, tags }`
+     *   - Return true to include, false to exclude
+     * @param options.routeSorter - Custom route sorter.
+     *   - Recieves two `GenerateOpenAPISortParam` parameters: `{ method, path, parts, tags }`
+     *   - Return -1, 0, 1
+     * @param options.includeOperationId - Whether to generate operationId for each operation (default: true)
+     * @param options.autoTag - Automatically tag operations based on path (default: true)
+     *   - When `true`, uses the first path segment as the tag
+     *   - When a function, allows custom tag generation
+     * @param options.commonParameters - Parameters to apply to all operations
+     * @param options.autoSummary - Generate summary from path when not provided (default: true)
+     * @param options.cleanOperationId - Remove special characters from operation IDs (default: true)
+  
+     * @returns {Promise<GeneratedOpenApi>} A promise that resolves to the complete OpenAPI 3.0.0 specification
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const openapi = await router.generateOpenAPI({
+     *   title: "My API",
+     *   version: "2.0.0",
+     *   description: "My awesome API",
+     * });
+     *
+     * // With custom options
+     * const openapi = await router.generateOpenAPI(
+     *   { title: "My API", version: "1.0.0" },
+     *   {
+     *     pick: ({ tags, path, parts, method }) => {
+     *       return path.startsWith('/api');
+     *     },
+     *     autoTag: ({ path }) => {
+     *       const parts = path.split('/').filter(p => p && p !== "*");
+     *       return parts.length > 0 ? [parts[0]] : ['default'];
+     *     },
+     *     commonParameters: [
+     *       {
+     *         name: 'X-Request-ID',
+     *         in: 'header',
+     *         schema: { type: 'string' },
+     *         description: 'Request ID for tracing'
+     *       }
+     *     ]
+     *   }
+     * );
+     *
+     * // Write to file
+     * await Deno.writeTextFile('./openapi.json', JSON.stringify(openapi, null, 2));
+     * ```
+     *
+     * @remarks
+     * - Routes with `openApi: false` in their definition are excluded from generation
+     * - Super glob routes (`/**`) are automatically excluded
+     * - Unnamed glob routes (`/*`) are named by their index like so 'glob1'
+     * - Connect HTTP method is not supported
+     * - Tags are only included if they are actually used by at least one operation
+     * - Response schemas are only included when explicitly provided
+     * - Path parameters are automatically extracted from route definitions and forced to `required: true`
+     * - Operation IDs are guaranteed to be unique with collision detection
+     *
+     * @see {@link GenerateOpenApiInfo} for complete info options
+     * @see {@link GenerateOpenAPIOptions} for complete generation options
+     * @see {@link GeneratedOpenApi} for the return type structure
+     */
+    generateOpenAPI(info, options) {
+        var _a;
+        const { title = "API", version = "1.0.0", description, servers = [{ url: "/", description: "Current server" }], security, components: globalComponents, termsOfService, contact, license, tags: globalTags, externalDocs, } = info !== null && info !== void 0 ? info : Object.create(null);
+        const sortMethodPriorityMap = (_a = options === null || options === void 0 ? void 0 : options.sortMethodPriorityMap) !== null && _a !== void 0 ? _a : types_ts_1.SORT_METHOD_PRIORITY_INDEX;
+        const sortPathnameOrder = (options === null || options === void 0 ? void 0 : options.sortPathnameOrder) && options.sortPathnameOrder < 0 ? -1 : 1;
+        const sortMethodOrder = (options === null || options === void 0 ? void 0 : options.sortMethodOrder) && options.sortMethodOrder < 0 ? -1 : 1;
+        const sortTagsOrder = (options === null || options === void 0 ? void 0 : options.sortTagsOrder) && options.sortTagsOrder < 0 ? -1 : 1;
+        const { pick, includeOperationId = true, autoTag = true, commonParameters = [], autoSummary = true, cleanOperationId = true, routeSorter = (a, b) => {
+            // sort by tags
+            if ((options === null || options === void 0 ? void 0 : options.sortTagsOrder) != null) {
+                const minTagsLen = Math.min(a.tags.length, b.tags.length);
+                for (let i = 0; i < minTagsLen; i++) {
+                    const comp = sortTagsOrder * a.tags[i].localeCompare(b.tags[i]);
+                    if (comp !== 0) {
+                        return comp;
+                    }
+                }
+                if (minTagsLen === 0 && a.tags.length !== b.tags.length) {
+                    const comp = sortTagsOrder * (a.tags.length < b.tags.length ? -1 : 1);
+                    if (comp !== 0) {
+                        return comp;
+                    }
+                }
+            }
+            // sort by pathname parts
+            if ((options === null || options === void 0 ? void 0 : options.sortPathnameOrder) != null) {
+                const minLen = Math.min(a.parts.length, b.parts.length);
+                for (let i = 0; i < minLen; i++) {
+                    let comp = sortPathnameOrder * a.parts[i].localeCompare(b.parts[i]);
+                    if (comp !== 0) {
+                        return comp;
+                    }
+                }
+                if (a.parts.length != b.parts.length) {
+                    const comp = sortPathnameOrder * (a.parts.length < b.parts.length ? -1 : 1);
+                    if (comp !== 0) {
+                        return comp;
+                    }
+                }
+            }
+            // sort by methods
+            if ((options === null || options === void 0 ? void 0 : options.sortMethodOrder) != null) {
+                if (a.method !== b.method) {
+                    const ma = sortMethodPriorityMap.get(a.method);
+                    const mb = sortMethodPriorityMap.get(b.method);
+                    return ma === mb
+                        ? sortMethodOrder * a.method.localeCompare(b.method)
+                        : sortMethodOrder * (ma - mb);
+                }
+            }
+            return 0;
+        }, } = options !== null && options !== void 0 ? options : Object.create(null);
         return new Promise((resolve) => {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             const handlers = __classPrivateFieldGet(this, _Router_routes, "f").handler;
             const paths = {};
             const schemas = {};
             const securitySchemes = {};
+            const parameters = {};
+            const responses = {};
+            const examples = {};
+            const usedTags = new Set();
+            const usedOperationIds = new Set();
+            const warnings = [];
             // Group routes by path
-            const routeGroups = new Map();
+            const routeGroupsSorter = [];
+            const routeGroups = Object.create(null);
             // Collect all routes
             for (const method of Object.keys(handlers)) {
-                const methodHandlers = handlers[method];
+                const methodUpper = method.toUpperCase();
+                // Check if method is supported by OpenAPI
+                if (methodUpper === "CONNECT") {
+                    continue;
+                }
+                const methodHandlers = handlers[methodUpper];
+                if (!methodHandlers)
+                    continue;
                 for (const entries of [
                     methodHandlers.entries,
                     methodHandlers.globs,
@@ -489,96 +642,144 @@ class Router {
                         for (const [, entry] of bucket) {
                             if (entry == null)
                                 continue;
-                            // Skip super glob routes for OpenAPI (they're catch-alls)
-                            if (entry.path.endsWith("/**")) {
+                            // Check openApi first
+                            if (entry.openApi === false)
+                                continue;
+                            // Skip super glob routes
+                            if (entry.path.endsWith("/**"))
                                 continue;
+                            let tags = (_a = entry.openApi) === null || _a === void 0 ? void 0 : _a.tags;
+                            // Auto-tag based on path if no explicit tags and autoTag is enabled
+                            if (autoTag && !tags) {
+                                const pathParts = entry.pathParts.filter((p) => p && p !== "*");
+                                if (pathParts.length > 0) {
+                                    if (typeof autoTag === "function") {
+                                        tags = autoTag(entry);
+                                    }
+                                    else {
+                                        const tag = pathParts[0] || "default";
+                                        tags = [tag];
+                                    }
+                                }
                             }
-                            let pathMethods = routeGroups.get(entry.openApiPath);
-                            if (!pathMethods) {
-                                pathMethods = new Map();
-                                routeGroups.set(entry.openApiPath, pathMethods);
+                            const sortEntry = Object.freeze({
+                                method: methodUpper,
+                                path: entry.path,
+                                parts: Object.freeze([...entry.pathParts]),
+                                tags: entry.openApi && Array.isArray(tags) && tags.length > 0
+                                    ? Object.freeze([...tags].sort())
+                                    : Object.freeze([]),
+                            });
+                            // Apply pick filter
+                            if (typeof pick === "function" && !pick(sortEntry)) {
+                                continue;
                             }
-                            pathMethods.set(method, entry);
+                            routeGroupsSorter.push([sortEntry, { entry, tags }]);
                         }
                     }
                 }
             }
+            // Sort route groups
+            routeGroupsSorter.sort(([a], [b]) => routeSorter(a, b));
+            for (const [{ method, path, parts }, { entry, tags },] of routeGroupsSorter) {
+                let pathMethods = routeGroups[entry.openApiPath];
+                if (!pathMethods) {
+                    pathMethods = Object.create(null);
+                    routeGroups[entry.openApiPath] = pathMethods;
+                }
+                if (pathMethods[method] != null) {
+                    console.warn(`Duplicate method found in ${entry.openApiPath}.${method}`);
+                }
+                pathMethods[method] = { entry, tags };
+                // Track all tags used by this operation
+                if (tags) {
+                    for (const tag of tags) {
+                        usedTags.add(tag);
+                    }
+                }
+            }
             // Build paths
-            for (const [pathname, methods] of routeGroups) {
+            for (const pathname of Object.keys(routeGroups)) {
+                const methods = routeGroups[pathname];
                 const pathItem = {};
                 paths[pathname] = pathItem;
-                for (const [method, entry] of methods) {
-                    const openApi = (_a = entry.openApi) !== null && _a !== void 0 ? _a : {};
+                for (const method of Object.keys(methods)) {
+                    const { entry, tags } = methods[method];
+                    const openApi = entry.openApi || {};
                     const methodLower = method.toLowerCase();
-                    // Build parameters - only include path params that are actually in the path
-                    // console.log(entry);
+                    // Auto-summary from path - use the last meaningful part
+                    let summary = openApi.summary;
+                    if (autoSummary && !summary) {
+                        const pathParts = pathname
+                            .split("/")
+                            .filter((p, idx) => p && entry.pathParts[idx] !== "*");
+                        // Find the last non-parameter part or use the last part
+                        let resource = pathParts[pathParts.length - 1] || pathParts[0] || "root";
+                        // Remove OpenAPI parameter syntax for summary
+                        resource = resource.replace(/[{}]/g, "");
+                        const action = method.toLowerCase();
+                        summary = `${action} ${resource}`;
+                    }
+                    // Build parameters - router-derived path parameters MUST be required: true
+                    const entryParams = [];
+                    let globIdx = 0;
+                    for (let i = 1; i < entry.pathParts.length; i++) {
+                        const part = entry.pathParts[i];
+                        if (part === "*") {
+                            const foundParam = (_b = entry.params) === null || _b === void 0 ? void 0 : _b.find(([idx, paramId]) => idx === i);
+                            entryParams.push([
+                                i,
+                                foundParam ? foundParam[1] : `glob${++globIdx}`,
+                            ]);
+                        }
+                    }
                     const pathParams = [];
-                    if (entry.params != null) {
-                        for (const [idx, paramId] of entry.params) {
-                            // if(entry.pathParts[idx])
-                            console.log([idx, paramId, entry.pathParts[idx]]);
-                            pathParams.push({
+                    if (entryParams.length > 0) {
+                        for (const [idx, paramId] of entryParams) {
+                            // Start with the router-derived parameter
+                            const baseParam = {
                                 name: paramId,
                                 in: "path",
                                 required: true,
                                 schema: { type: "string" },
-                            });
+                            };
+                            // Check if user defined this parameter
+                            const userParam = ((_c = openApi.parameters) !== null && _c !== void 0 ? _c : []).find((p) => p.name === paramId && p.in === "path");
+                            if (userParam) {
+                                // Merge user metadata while preserving required: true
+                                pathParams.push(Object.assign(Object.assign(Object.assign({}, baseParam), userParam), { required: true, in: "path" }));
+                            }
+                            else {
+                                pathParams.push(baseParam);
+                            }
                         }
                     }
-                    // Combine with user-defined parameters
-                    const userParams = (_b = openApi.parameters) !== null && _b !== void 0 ? _b : [];
-                    const allParams = [...userParams, ...pathParams];
+                    // Get user-defined parameters (non-path params)
+                    const userParams = ((_d = openApi.parameters) !== null && _d !== void 0 ? _d : []).filter((p) => p.in !== "path");
+                    // Combine: common parameters + user params + path params
+                    // Path params come last so they take precedence for required: true
+                    const allParams = [...commonParameters, ...userParams, ...pathParams];
                     // Remove duplicates (by name + in combination)
                     const paramSet = new Set();
-                    const parameters = [];
+                    const finalParams = [];
                     for (const param of allParams) {
                         const key = `${param.name}:${param.in}`;
                         if (!paramSet.has(key)) {
                             paramSet.add(key);
-                            parameters.push(param);
+                            finalParams.push(param);
                         }
                     }
                     // Build request body
                     const requestBody = openApi.requestBody;
-                    // Build responses
-                    const responses = {};
+                    // Build responses - only use provided responses, no inference
+                    const responseObj = {};
                     if (openApi.responses) {
-                        Object.assign(responses, openApi.responses);
+                        Object.assign(responseObj, openApi.responses);
                     }
                     else {
-                        // Infer responses from HTTP method
-                        if (method !== "DELETE" && method !== "HEAD") {
-                            responses["200"] = {
-                                description: "Successful response",
-                                content: {
-                                    "application/json": {
-                                        schema: {
-                                            type: "object",
-                                            properties: {
-                                                data: { type: "object" },
-                                                message: { type: "string" },
-                                            },
-                                        },
-                                    },
-                                },
-                            };
-                        }
-                        else if (method === "DELETE") {
-                            responses["204"] = {
-                                description: "Resource deleted successfully",
-                            };
-                        }
-                        // Add common error responses
-                        if ((_c = entry.params) === null || _c === void 0 ? void 0 : _c.length) {
-                            responses["404"] = {
-                                description: "Resource not found",
-                            };
-                        }
-                        responses["400"] = {
-                            description: "Bad request",
-                        };
-                        responses["500"] = {
-                            description: "Internal server error",
+                        // Minimal default response - just a description
+                        responseObj["200"] = {
+                            description: "Successful response",
                         };
                     }
                     // Build security
@@ -586,16 +787,25 @@ class Router {
                     if (!operationSecurity && security) {
                         operationSecurity = security;
                     }
-                    // Generate clean operation ID
-                    const operationId = openApi.operationId || generateOperationId(method, pathname);
+                    // Generate operation ID with uniqueness guarantee
+                    let operationId = openApi.operationId;
+                    if (operationId) {
+                        if (usedOperationIds.has(operationId)) {
+                            console.warn(`Duplicate OpenApi operationId '${operationId}' in  ${entry.openApiPath}.${method}`);
+                        }
+                        usedOperationIds.add(operationId);
+                    }
+                    else if (includeOperationId) {
+                        operationId = __classPrivateFieldGet(this, _Router_instances, "m", _Router_generateUniqueOperationId).call(this, method, pathname, cleanOperationId, usedOperationIds);
+                    }
                     // Build operation object
                     const operation = {
-                        summary: openApi.summary,
+                        summary: summary,
                         description: openApi.description,
-                        tags: openApi.tags,
-                        parameters: parameters.length > 0 ? parameters : undefined,
+                        tags: tags,
+                        parameters: finalParams.length > 0 ? finalParams : undefined,
                         requestBody,
-                        responses,
+                        responses: responseObj,
                         security: operationSecurity,
                         operationId,
                     };
@@ -604,33 +814,86 @@ class Router {
                     pathItem[methodLower] = cleanedOperation;
                 }
             }
-            // Merge global components with any collected schemas
+            // Build components
             const components = {};
+            // Merge global and collected schemas
             if (globalComponents === null || globalComponents === void 0 ? void 0 : globalComponents.schemas) {
                 Object.assign(schemas, globalComponents.schemas);
             }
             if (Object.keys(schemas).length > 0) {
                 components.schemas = schemas;
             }
+            // Merge global and collected security schemes
             if (globalComponents === null || globalComponents === void 0 ? void 0 : globalComponents.securitySchemes) {
                 Object.assign(securitySchemes, globalComponents.securitySchemes);
             }
             if (Object.keys(securitySchemes).length > 0) {
                 components.securitySchemes = securitySchemes;
             }
+            // Add global parameters
+            if (globalComponents === null || globalComponents === void 0 ? void 0 : globalComponents.parameters) {
+                Object.assign(parameters, globalComponents.parameters);
+            }
+            if (Object.keys(parameters).length > 0) {
+                components.parameters = parameters;
+            }
+            // Add global responses
+            if (globalComponents === null || globalComponents === void 0 ? void 0 : globalComponents.responses) {
+                Object.assign(responses, globalComponents.responses);
+            }
+            if (Object.keys(responses).length > 0) {
+                components.responses = responses;
+            }
+            // Add global examples
+            if (globalComponents === null || globalComponents === void 0 ? void 0 : globalComponents.examples) {
+                Object.assign(examples, globalComponents.examples);
+            }
+            if (Object.keys(examples).length > 0) {
+                components.examples = examples;
+            }
+            // Build final result
             const result = {
                 openapi: "3.0.0",
-                info: Object.assign({ title,
-                    version }, (description && { description })),
+                info: Object.assign(Object.assign(Object.assign(Object.assign({ title,
+                    version }, (description && { description })), (termsOfService && { termsOfService })), (contact && { contact })), (license && { license })),
                 servers,
                 paths,
             };
+            // Add tags - ONLY include tags that are actually used by operations
+            const allTags = [];
+            // Start with global tags that are actually used
+            if (globalTags) {
+                for (const tag of globalTags) {
+                    if (usedTags.has(tag.name)) {
+                        allTags.push(tag);
+                    }
+                }
+            }
+            // Add auto-generated tags that aren't already in global tags
+            for (const tag of usedTags) {
+                if (!allTags.some((t) => t.name === tag)) {
+                    allTags.push({ name: tag });
+                }
+            }
+            if (allTags.length > 0) {
+                result.tags = allTags;
+            }
+            // Add external docs
+            if (externalDocs) {
+                result.externalDocs = externalDocs;
+            }
+            // Add components
             if (Object.keys(components).length > 0) {
                 result.components = components;
             }
+            // Add security
             if (security && security.length > 0) {
                 result.security = security;
             }
+            // Log warnings if any
+            if (warnings.length > 0 && typeof console !== "undefined") {
+                console.warn("OpenAPI Generation Warnings:", warnings.join("\n  "));
+            }
             resolve(result);
         });
     }
@@ -1049,16 +1312,24 @@ class Router {
             const { params, paths } = processedPaths;
             const paramsMap = params ? new Map(params) : undefined;
             for (const path of paths) {
-                const standardPath = params
-                    ? path
-                        .split("/")
-                        .map((p, idx) => (p === "*" ? `:${paramsMap === null || paramsMap === void 0 ? void 0 : paramsMap.get(idx)}` : p))
+                const parts = path.split("/", __classPrivateFieldGet(this, _Router_config, "f").maxPath + 1);
+                const containsParams = params || parts.some((p) => p === "*");
+                const standardPath = containsParams
+                    ? parts
+                        .map((p, idx) => p === "*"
+                        ? (paramsMap === null || paramsMap === void 0 ? void 0 : paramsMap.has(idx))
+                            ? `:${paramsMap.get(idx)}`
+                            : "*"
+                        : p)
                         .join("/")
                     : path;
-                const openApiPath = params
+                let globIdx = 0;
+                const openApiPath = containsParams
                     ? path
                         .split("/")
-                        .map((p, idx) => (p === "*" ? `{${paramsMap === null || paramsMap === void 0 ? void 0 : paramsMap.get(idx)}}` : p))
+                        .map((p, idx) => p === "*"
+                        ? `{${(paramsMap === null || paramsMap === void 0 ? void 0 : paramsMap.get(idx)) || `glob${++globIdx}`}}`
+                        : p)
                         .join("/")
                     : path;
                 const upperMethod = method.toUpperCase();
@@ -1069,7 +1340,6 @@ class Router {
                 if (!exports.REGISTER_PATH_REGEX.test(path)) {
                     throw new types_ts_1.RouterError(`Invalid path for (${method} ${originalPath} -> ${path})`);
                 }
-                const parts = path.split("/", __classPrivateFieldGet(this, _Router_config, "f").maxPath + 1);
                 if (parts.length - 1 > __classPrivateFieldGet(this, _Router_config, "f").maxPath) {
                     throw new types_ts_1.RouterError(`Path parts length limit exceeded ${__classPrivateFieldGet(this, _Router_config, "f").maxPath}`);
                 }
@@ -1098,7 +1368,8 @@ class Router {
                     if (!overwrite &&
                         superGlobEntries &&
                         superGlobEntries.has(basePath)) {
-                        throw new types_ts_1.RouterError(`SuperGlob route already set for (${method} ${originalPath} -> ${path})`);
+                        const superGlobEntry = superGlobEntries.get(basePath);
+                        throw new types_ts_1.RouterError(`SuperGlob route collision for (${method} ${originalPath} -> ${path} with ${superGlobEntry.originalPath} at ${superGlobEntry.pathParts.join("/")})`);
                     }
                     if (superGlobEntries == null) {
                         superGlobEntries = new Map();
@@ -1111,7 +1382,8 @@ class Router {
                     let globEntries = routes.globs[parts.length];
                     if (globEntries) {
                         if (!overwrite && globEntries && globEntries.has(path)) {
-                            throw new types_ts_1.RouterError(`Glob route already set for (${method} ${originalPath} -> ${path})`);
+                            const globEntry = globEntries.get(path);
+                            throw new types_ts_1.RouterError(`Glob route collision for (${method} ${originalPath} -> ${path} with ${globEntry.originalPath} at ${globEntry.pathParts.join("/")})`);
                         }
                         // check for collision
                         for (const globEntry of globEntries.values()) {
@@ -1181,7 +1453,18 @@ class Router {
     }
 }
 exports.Router = Router;
-_Router_config = new WeakMap(), _Router_routes = new WeakMap(), _Router_instances = new WeakSet(), _Router_processPath = function _Router_processPath(path) {
+_Router_config = new WeakMap(), _Router_routes = new WeakMap(), _Router_instances = new WeakSet(), _Router_generateUniqueOperationId = function _Router_generateUniqueOperationId(method, path, clean, usedIds) {
+    let baseId = generateOperationId(method, path, clean);
+    let operationId = baseId;
+    let counter = 1;
+    // Ensure uniqueness
+    while (usedIds.has(operationId)) {
+        operationId = `${baseId}${counter}`;
+        counter++;
+    }
+    usedIds.add(operationId);
+    return operationId;
+}, _Router_processPath = function _Router_processPath(path) {
     const processedPaths = {
         paths: [""],
     };
@@ -1502,17 +1785,29 @@ const translateRouteFilePath = (pathname, maxPath = 64) => {
     return parts.join("/");
 };
 exports.translateRouteFilePath = translateRouteFilePath;
-const generateOperationId = (method, path) => {
-    // Remove all special characters and format properly
-    const cleanPath = path
-        .replace(/[{}]/g, "")
-        .replace(/\*/g, "")
-        .replace(/[^a-zA-Z0-9\/]/g, "")
+const generateOperationId = (method, path, clean = true) => {
+    // Clean path
+    let cleanPath = path
         .split("/")
         .filter(Boolean)
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .map((part) => {
+        // Remove braces and special chars
+        let cleaned = part
+            .replace(/[{}]/g, "")
+            .replace(/[\-\.@]/g, (m) => m === "-" ? "_" : m === "." ? "__" : "_at_");
+        if (clean) {
+            // Remove other special chars
+            cleaned = cleaned.replace(/[^a-zA-Z0-9_]/g, "");
+        }
+        // Convert to PascalCase
+        return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+    })
         .join("");
-    return `${method.toLowerCase()}${cleanPath}`;
+    if (!cleanPath) {
+        cleanPath = "Root";
+    }
+    const methodPrefix = method.toLowerCase();
+    return `${methodPrefix}${cleanPath}`;
 };
 exports.default = Router;
 //# sourceMappingURL=router.js.map