@qualisero/openapi-endpoint 0.11.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # Vue OpenAPI Query
 
-[![npm version](https://badge.fury.io/js/@qualisero%2Fopenapi-endpoint.svg?refresh=1763619312)](https://badge.fury.io/js/@qualisero%2Fopenapi-endpoint)
+[![npm version](https://badge.fury.io/js/@qualisero%2Fopenapi-endpoint.svg?refresh=1763799820)](https://badge.fury.io/js/@qualisero%2Fopenapi-endpoint)
 [![CI](https://github.com/qualisero/openapi-endpoint/workflows/CI/badge.svg)](https://github.com/qualisero/openapi-endpoint/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@qualisero/openapi-endpoint)](https://bundlephobia.com/package/@qualisero/openapi-endpoint)
@@ -139,8 +139,6 @@ const userPetsQuery = api.useQuery(
 - **Automatic refetch**: Changes to query params trigger automatic refetch via TanStack Query's key mechanism
 - **Backward compatible**: Works alongside existing `axiosOptions.params`
 
-For detailed examples, see [Reactive Query Parameters Guide](./REACTIVE_QUERY_PARAMS.md).
-
 ### Automatic Operation Type Detection with `api.useEndpoint`
 
 The `api.useEndpoint` method automatically detects whether an operation is a query (GET/HEAD/OPTIONS) or mutation (POST/PUT/PATCH/DELETE) based on the HTTP method defined in your OpenAPI specification:

package/dist/cli.js

@@ -53,6 +53,153 @@ async function generateTypes(openapiContent, outputDir) {
         }
     }
 }
+/**
+ * Converts a snake_case string to PascalCase.
+ * Works with strings that have no underscores (just capitalizes them).
+ *
+ * @param str - The snake_case string (e.g., 'give_treats' or 'pets')
+ * @returns PascalCase string (e.g., 'GiveTreats' or 'Pets')
+ */
+function snakeToPascalCase(str) {
+    return str
+        .split('_')
+        .filter((part) => part.length > 0)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+        .join('');
+}
+/**
+ * Generates an operationId based on the HTTP method and path.
+ * Uses heuristics to create meaningful operation names.
+ *
+ * @param pathUrl - The OpenAPI path (e.g., '/pets/{petId}')
+ * @param method - The HTTP method (e.g., 'get', 'post')
+ * @param prefixToStrip - Optional prefix to strip from path (e.g., '/api')
+ * @returns A generated operationId (e.g., 'getPet', 'listPets', 'createPet')
+ */
+function generateOperationId(pathUrl, method, prefixToStrip = '', existingIds) {
+    const methodLower = method.toLowerCase();
+    // Strip prefix if provided and path starts with it
+    let effectivePath = pathUrl;
+    if (prefixToStrip && pathUrl.startsWith(prefixToStrip)) {
+        effectivePath = pathUrl.substring(prefixToStrip.length);
+    }
+    // Remove leading/trailing slashes, replace slashes and periods with underscores
+    // Filter out path parameters (e.g., {petId})
+    // split by '/' or '.'
+    const pathSegments = effectivePath.split(/[/.]/);
+    const isParam = (segment) => segment.startsWith('{') && segment.endsWith('}');
+    const entityName = snakeToPascalCase(pathSegments
+        .filter((s) => !isParam(s))
+        .join('_')
+        .replace(/[^a-zA-Z0-9]/g, '_'));
+    // A collection is when there is a trailing slash
+    const isCollection = pathUrl.endsWith('/');
+    // Determine prefix based on method and whether it's a collection or single resource
+    let prefix = '';
+    switch (methodLower) {
+        case 'get':
+            // GET on file extension -> get, GET on collection -> list, GET on resource -> get
+            prefix = isCollection ? 'list' : 'get';
+            break;
+        case 'post':
+            prefix = isCollection ? 'create' : 'post';
+            break;
+        case 'put':
+        case 'patch':
+            prefix = 'update';
+            break;
+        case 'delete':
+            prefix = 'delete';
+            break;
+        case 'head':
+            prefix = 'head';
+            break;
+        case 'options':
+            prefix = 'options';
+            break;
+        case 'trace':
+            prefix = 'trace';
+            break;
+        default:
+            prefix = methodLower;
+    }
+    // Combine prefix and entity name
+    let generatedId = prefix + entityName;
+    // Handle collisions by appending path segments
+    if (existingIds.has(generatedId)) {
+        console.log(`⚠️  Collision detected: '${generatedId}' already used`);
+        // add parameters from the last to the first until not colliding
+        const params = pathSegments
+            .filter(isParam)
+            .map((s) => snakeToPascalCase(s.replace(/[{}]/g, '').replace(/[.:-]/g, '_')));
+        while (params.length > 0) {
+            generatedId += params.pop();
+            if (!existingIds.has(generatedId)) {
+                console.log(`   ➜ Resolved collision with: '${generatedId}'`);
+                break;
+            }
+        }
+        if (existingIds.has(generatedId)) {
+            // If still colliding, append a counter
+            let counter = 2;
+            let uniqueId = `${generatedId}${counter}`;
+            while (existingIds.has(uniqueId)) {
+                counter++;
+                uniqueId = `${generatedId}${counter}`;
+            }
+            generatedId = uniqueId;
+            console.log(`   ➜ Resolved collision with counter: '${generatedId}'`);
+        }
+    }
+    return generatedId;
+}
+/**
+ * Adds operationId to operations that don't have one.
+ * Modifies the OpenAPI spec in place.
+ * Handles collisions by appending disambiguating segments.
+ *
+ * @param openApiSpec - The OpenAPI specification object
+ * @param prefixToStrip - Optional prefix to strip from paths (defaults to '/api')
+ */
+function addMissingOperationIds(openApiSpec, prefixToStrip = '/api') {
+    if (!openApiSpec.paths) {
+        return;
+    }
+    // Log the prefix that will be stripped
+    if (prefixToStrip) {
+        console.log(`🔍 Path prefix '${prefixToStrip}' will be stripped from operation IDs`);
+    }
+    // Track used operationIds to detect collisions
+    const usedOperationIds = new Set();
+    // First pass: collect existing operationIds
+    Object.entries(openApiSpec.paths).forEach(([_, pathItem]) => {
+        Object.entries(pathItem).forEach(([method, op]) => {
+            const httpMethods = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'trace'];
+            if (!httpMethods.includes(method.toLowerCase())) {
+                return;
+            }
+            if (op.operationId) {
+                usedOperationIds.add(op.operationId);
+            }
+        });
+    });
+    // Second pass: generate operationIds for missing ones
+    Object.entries(openApiSpec.paths).forEach(([pathUrl, pathItem]) => {
+        Object.entries(pathItem).forEach(([method, op]) => {
+            const httpMethods = ['get', 'post', 'put', 'delete', 'patch', 'options', 'head', 'trace'];
+            if (!httpMethods.includes(method.toLowerCase())) {
+                return;
+            }
+            if (!op.operationId) {
+                // Generate operationId with prefix stripped
+                let generatedId = generateOperationId(pathUrl, method, prefixToStrip, usedOperationIds);
+                op.operationId = generatedId;
+                usedOperationIds.add(generatedId);
+                console.log(`🏷️  Generated operationId '${generatedId}' for ${method.toUpperCase()} ${pathUrl}`);
+            }
+        });
+    });
+}
 function parseOperationsFromSpec(openapiContent) {
     const openApiSpec = JSON.parse(openapiContent);
     if (!openApiSpec.paths) {
@@ -174,7 +321,11 @@ async function main() {
             console.log(`📁 Created output directory: ${outputDir}`);
         }
         // Fetch OpenAPI spec content
-        const openapiContent = await fetchOpenAPISpec(openapiInput);
+        let openapiContent = await fetchOpenAPISpec(openapiInput);
+        // Parse spec and add missing operationIds
+        const openApiSpec = JSON.parse(openapiContent);
+        addMissingOperationIds(openApiSpec);
+        openapiContent = JSON.stringify(openApiSpec, null, 2);
         // Generate both files
         await Promise.all([generateTypes(openapiContent, outputDir), generateApiOperations(openapiContent, outputDir)]);
         console.log('🎉 Code generation completed successfully!');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qualisero/openapi-endpoint",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/qualisero/openapi-endpoint.git"
@@ -57,7 +57,8 @@
   "peerDependencies": {
     "@tanstack/vue-query": ">=5.90",
     "axios": ">=1.12",
-    "vue": ">=3.3"
+    "vue": ">=3.3",
+    "openapi-typescript": "^7.9.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.37.0",
@@ -72,7 +73,6 @@
     "gh-pages": "^6.3.0",
     "globals": "^16.4.0",
     "jsdom": "^27.0.0",
-    "openapi-typescript": "^7.9.1",
     "prettier": "^3.6.2",
     "typedoc": "^0.28.14",
     "typescript": "^5.9.2",