@stackql/provider-utils 0.1.0

package/src/docgen/resource/examples/exec-example.js

@@ -0,0 +1,121 @@
+// src/docgen/resource/examples/exec-example.js
+import { 
+    getSqlMethodsWithOrderedFields, 
+} from '../../helpers.js';
+
+export function createExecExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+    const execMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'exec');
+    
+    // if there are no exec methods, return empty content
+    if (Object.keys(execMethods).length === 0) {
+        return '';
+    }
+    
+    let content = '\n\n## Lifecycle Methods\n\n';
+    
+    // Create tab structure with values array
+    content += '<Tabs\n    defaultValue="' + Object.keys(execMethods)[0] + '"\n    values={[\n';
+    
+    // Add each method as a tab option
+    Object.keys(execMethods).forEach((methodName, index, arr) => {
+        content += '        { label: \'' + methodName + '\', value: \'' + methodName + '\' }';
+        content += index < arr.length - 1 ? ',\n' : '\n';
+    });
+    
+    content += '    ]}\n>\n';
+    
+    // Create each method tab content
+    Object.entries(execMethods).forEach(([methodName, methodDetails]) => {
+        content += '<TabItem value="' + methodName + '">\n\n';
+        
+        // Add method description
+        content += methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
+        
+        // Create SQL example
+        content += '\n\n```sql\nEXEC ' + providerName + '.' + serviceName + '.' + resourceName + '.' + methodName + ' \n';
+        
+        // Add required and optional parameters with @ prefix
+        const requiredParams = Object.keys(methodDetails.requiredParams || {});
+        const optionalParams = Object.keys(methodDetails.optionalParams || {});
+        
+        // Add parameters
+        let hasParams = false;
+        
+        // Add required parameters
+        requiredParams.forEach((param, index) => {
+            content += '@' + param + '=\'{{ ' + param + ' }}\' --required';
+            hasParams = true;
+            
+            if (index < requiredParams.length - 1 || optionalParams.length > 0) {
+                content += ', \n';
+            }
+        });
+        
+        // Add optional parameters
+        optionalParams.forEach((param, index) => {
+            const paramDetails = methodDetails.optionalParams[param];
+            const isBoolean = paramDetails.type === 'boolean';
+            
+            content += '@' + param + '=';
+            
+            if (isBoolean) {
+                content += '{{ ' + param + ' }}';
+            } else {
+                content += '\'{{ ' + param + ' }}\'';
+            }
+            
+            hasParams = true;
+            
+            if (index < optionalParams.length - 1) {
+                content += ', \n';
+            }
+        });
+        
+        // Add request body if present
+        if (methodDetails.requestBody && methodDetails.requestBody.properties && 
+            Object.keys(methodDetails.requestBody.properties).length > 0) {
+            
+            if (hasParams) {
+                content += ' \n';
+            }
+            
+            content += '@@json=\n\'{\n';
+            
+            // Format request body properties as JSON
+            // Filter out read-only properties based on OpenAPI readOnly flag
+            const bodyProps = Object.entries(methodDetails.requestBody.properties)
+                .filter(([_, propDetails]) => propDetails.readOnly !== true)
+                .map(([propName]) => propName);
+            
+            bodyProps.forEach((prop, index) => {
+                const propDetails = methodDetails.requestBody.properties[prop];
+                const isString = propDetails.type !== 'number' && 
+                                propDetails.type !== 'integer' && 
+                                propDetails.type !== 'boolean';
+                
+                content += '"' + prop + '": ';
+                
+                if (isString) {
+                    content += '"{{ ' + prop + ' }}"';
+                } else {
+                    content += '{{ ' + prop + ' }}';
+                }
+                
+                if (index < bodyProps.length - 1) {
+                    content += ', \n';
+                } else {
+                    content += '\n';
+                }
+            });
+            
+            content += '}\'';
+        }
+        
+        content += ';\n```\n</TabItem>\n';
+    });
+    
+    // Close tabs
+    content += '</Tabs>\n';
+    
+    return content;
+}

package/src/docgen/resource/examples/insert-example.js

@@ -0,0 +1,211 @@
+// src/docgen/resource/examples/insert-example.js
+import { 
+    getSqlMethodsWithOrderedFields, 
+} from '../../helpers.js';
+
+export function createInsertExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+    const insertMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'insert');
+
+    // if there are no insert methods, return empty content
+    if (Object.keys(insertMethods).length === 0) {
+        return '';
+    }
+
+    let content = '\n\n## `INSERT` examples\n\n';
+
+    // Create tab structure with values array
+    content += '<Tabs\n    defaultValue="' + Object.keys(insertMethods)[0] + '"\n    values={[\n';
+    
+    // Add each method as a tab option
+    Object.keys(insertMethods).forEach((methodName, index) => {
+        content += '        { label: \'' + methodName + '\', value: \'' + methodName + '\' }';
+        if (index < Object.keys(insertMethods).length - 1 || true) { // Always add comma for manifest tab
+            content += ',\n';
+        }
+    });
+    
+    // Add manifest tab
+    content += '        { label: \'Manifest\', value: \'manifest\' }\n';
+    content += '    ]}\n>\n';
+    
+    // Create each method tab content
+    Object.entries(insertMethods).forEach(([methodName, methodDetails]) => {
+        content += '<TabItem value="' + methodName + '">\n\n';
+        content += methodDetails.opDescription || 'No description available.';
+        
+        // Create SQL example
+        content += '\n\n```sql\nINSERT INTO ' + providerName + '.' + serviceName + '.' + resourceName + ' (\n';
+        
+        // Add requestBody fields prefixed with data__ (excluding read-only props)
+        const reqBodyProps = methodDetails.requestBody?.properties 
+            ? Object.entries(methodDetails.requestBody.properties)
+                .filter(([_, propDetails]) => propDetails.readOnly !== true)
+                .map(([propName]) => propName)
+            : [];
+
+        const requiredBodyProps = methodDetails.requestBody?.required ? methodDetails.requestBody.required : [];
+            
+        const dataProps = reqBodyProps.map(prop => 'data__' + prop);
+        
+        // Combine data props with params
+        const requiredParams = Object.keys(methodDetails.requiredParams || {});
+        const optionalParams = Object.keys(methodDetails.optionalParams || {});
+        const allFields = [...dataProps, ...requiredParams, ...optionalParams];
+        
+        // Add fields to INSERT
+        content += allFields.join(',\n');
+        
+        // Start SELECT statement
+        content += '\n)\nSELECT \n';
+        
+        // Add values placeholders
+        const valueLines = allFields.map(field => {
+            const isDataField = field.startsWith('data__');
+            const paramName = isDataField ? field.substring(6) : field;
+            
+            // Check for required body props
+            let isRequiredBodyParam = false;
+            if(isDataField){
+                if (requiredBodyProps.includes(paramName)) {
+                    isRequiredBodyParam = true;
+                }
+            }
+
+            // Check if it's a number or boolean type
+            let isNumber = false;
+            let isBoolean = false;
+            
+            if (isDataField && methodDetails.requestBody?.properties?.[paramName]) {
+                const propType = methodDetails.requestBody.properties[paramName].type;
+                isNumber = propType === 'number' || propType === 'integer';
+                isBoolean = propType === 'boolean';
+            }
+            
+            if (isNumber || isBoolean) {
+                return '{{ ' + paramName + ' }}' + (isRequiredBodyParam ? ' --required' : '');
+            } else {
+                return '\'{{ ' + paramName + ' }}\'' + (isRequiredBodyParam ? ' --required' : '');
+            }
+        });
+        
+        content += valueLines.join(',\n');
+
+        // returning clause if properties exist
+        if (methodDetails.properties && Object.keys(methodDetails.properties).length > 0) {
+            content += '\nRETURNING\n';
+            const keys = Object.keys(methodDetails.properties);
+            keys.forEach((key, index) => {
+                if (index === keys.length - 1) {
+                    // For the last item, don't add a newline after it
+                    content += `${key}`;
+                } else {
+                    content += `${key},\n`;
+                }
+            });
+        }
+
+        content += '\n;\n```\n</TabItem>\n';
+    });
+
+    
+// {
+//     "code": {
+//         "type": "string",
+//         "description": " (example: 000123)"
+//     },
+//     "createdOn": {
+//         "type": "integer (int64)",
+//         "description": "Timestamp that specifies when the statement execution started.‌ The timestamp is expressed in milliseconds since the epoch.‌"
+//     },
+//     "data": {
+//         "type": "array",
+//         "description": "Result set data."
+//     },
+// }
+
+    // Create manifest tab
+    content += '<TabItem value="manifest">\n\n';
+    content += '```yaml\n# Description fields are for documentation purposes\n- name: ' + resourceName + '\n  props:\n';
+    
+    // Collect all unique params and request body props across all methods
+    const allParams = {};
+    const allRequestBodyProps = {};
+    
+    Object.values(insertMethods).forEach(method => {
+        // Add required params
+        Object.entries(method.requiredParams || {}).forEach(([name, details]) => {
+            allParams[name] = { ...details, required: true };
+        });
+        
+        // Add optional params
+        Object.entries(method.optionalParams || {}).forEach(([name, details]) => {
+            if (!allParams[name]) {
+                allParams[name] = { ...details, required: false };
+            }
+        });
+        
+        // Add request body props (excluding read-only props)
+        if (method.requestBody && method.requestBody.properties) {
+            Object.entries(method.requestBody.properties)
+                .filter(([_, propDetails]) => propDetails.readOnly !== true)
+                .forEach(([name, details]) => {
+                    allRequestBodyProps[name] = details;
+                });
+        }
+    });
+    
+    // Add required params first
+    Object.entries(allParams)
+        .filter(([_, details]) => details.required)
+        .forEach(([name, details]) => {
+            const type = details.type || 'string';
+            content += '    - name: ' + name + '\n';
+            content += '      value: ' + type + '\n';
+            content += '      description: Required parameter for the ' + resourceName + ' resource.\n';
+        });
+    
+    // Add request body props
+    Object.entries(allRequestBodyProps).forEach(([name, details]) => {
+        const type = details.type || 'string';
+        const description = details.description || '';
+        content += '    - name: ' + name + '\n';
+        content += '      value: ' + type + '\n';
+        
+        if (description) {
+            // Format multi-line descriptions
+            const wrappedDesc = description.replace(/(.{1,80})(\\s+|$)/g, '$1\n        ');
+            content += '      description: >\n        ' + wrappedDesc + '\n';
+        }
+        
+        // Add enum values if available
+        if (details.enum) {
+            content += '      valid_values: [\'' + details.enum.join('\', \'') + '\']\n';
+        }
+        
+        // Add default value if available
+        if (details.default !== undefined) {
+            content += '      default: ' + details.default + '\n';
+        }
+    });
+    
+    // Add optional params last
+    Object.entries(allParams)
+        .filter(([_, details]) => !details.required)
+        .forEach(([name, details]) => {
+            const type = details.type || 'string';
+            const description = details.description || '';
+            content += '    - name: ' + name + '\n';
+            content += '      value: ' + type + '\n';
+            
+            if (description) {
+                content += '      description: ' + description + '\n';
+            }
+        });
+    
+    content += '```\n</TabItem>\n';
+    
+    // Close tabs
+    content += '</Tabs>\n';
+    
+    return content;
+}

package/src/docgen/resource/examples/select-example.js

@@ -0,0 +1,73 @@
+// src/docgen/resource/examples/select-example.js
+import { 
+    getSqlMethodsWithOrderedFields, 
+} from '../../helpers.js';
+
+export function createSelectExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+    const selectMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'select');
+    
+    // if there are no select methods, return empty content
+    if (Object.keys(selectMethods).length === 0) {
+        return '';
+    }
+    
+    let content = '\n\n## `SELECT` examples\n\n';
+    
+    // Create tab structure with values array
+    content += '<Tabs\n    defaultValue="' + Object.keys(selectMethods)[0] + '"\n    values={[\n';
+    
+    // Add each method as a tab option
+    Object.keys(selectMethods).forEach((methodName, index, arr) => {
+        content += '        { label: \'' + methodName + '\', value: \'' + methodName + '\' }';
+        content += index < arr.length - 1 ? ',\n' : '\n';
+    });
+    
+    content += '    ]}\n>\n';
+    
+    // Create each tab content
+    Object.entries(selectMethods).forEach(([methodName, methodDetails]) => {
+        content += '<TabItem value="' + methodName + '">\n\n';
+        content += methodDetails.opDescription || 'No description available.';
+        
+        // Create SQL example
+        content += '\n\n```sql\nSELECT\n';
+        
+        // Add fields
+        const fieldNames = Object.keys(methodDetails.properties || {});
+        if (fieldNames.length > 0) {
+            content += fieldNames.join(',\n');
+        } else {
+            content += '*';
+        }
+        
+        // Add FROM clause
+        content += '\nFROM ' + providerName + '.' + serviceName + '.' + resourceName;
+        
+        // Add WHERE clause with parameters
+        const requiredParams = Object.keys(methodDetails.requiredParams || {});
+        const optionalParams = Object.keys(methodDetails.optionalParams || {});
+        
+        if (requiredParams.length > 0 || optionalParams.length > 0) {
+            content += '\nWHERE ';
+            
+            // Add required parameters
+            requiredParams.forEach((param, index) => {
+                content += param + ' = \'{{ ' + param + ' }}\' -- required';
+                content += index < requiredParams.length - 1 || optionalParams.length > 0 ? '\nAND ' : '';
+            });
+            
+            // Add optional parameters
+            optionalParams.forEach((param, index) => {
+                content += param + ' = \'{{ ' + param + ' }}\'';
+                content += index < optionalParams.length - 1 ? '\nAND ' : '';
+            });
+        }
+        
+        content += ';\n```\n</TabItem>\n';
+    });
+    
+    // Close tabs
+    content += '</Tabs>\n';
+    
+    return content;
+}

package/src/docgen/resource/examples/update-example.js

@@ -0,0 +1,154 @@
+// src/docgen/resource/examples/update-example.js
+import { 
+    getSqlMethodsWithOrderedFields, 
+} from '../../helpers.js';
+
+export function createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, isReplace = false) {
+    const updateMethods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, isReplace ? 'replace' : 'update');
+    
+    // if there are no update methods, return empty content
+    if (Object.keys(updateMethods).length === 0) {
+        return '';
+    }
+    
+    let content = '';
+    if (isReplace) {
+        content += '\n\n## `REPLACE` examples\n\n';
+    } else {
+        content += '\n\n## `UPDATE` examples\n\n';
+    }
+    
+    // Create tab structure with values array
+    content += '<Tabs\n    defaultValue="' + Object.keys(updateMethods)[0] + '"\n    values={[\n';
+    
+    // Add each method as a tab option
+    Object.keys(updateMethods).forEach((methodName, index, arr) => {
+        content += '        { label: \'' + methodName + '\', value: \'' + methodName + '\' }';
+        content += index < arr.length - 1 ? ',\n' : '\n';
+    });
+    
+    content += '    ]}\n>\n';
+    
+    // Create each method tab content
+    Object.entries(updateMethods).forEach(([methodName, methodDetails]) => {
+        content += '<TabItem value="' + methodName + '">\n\n';
+        
+        // Add method description
+        content += methodDetails.opDescription || methodDetails.respDescription || 'No description available.';
+        
+        // Create SQL example
+        content += '\n\n```sql\n';
+        content += (isReplace ? 'REPLACE ' : 'UPDATE ') + providerName + '.' + serviceName + '.' + resourceName;
+        
+        // Add SET clause with requestBody fields (excluding read-only props)
+        content += '\nSET \n';
+        
+        // Get request body fields (excluding read-only props)
+        const reqBodyProps = methodDetails.requestBody?.properties 
+            ? Object.entries(methodDetails.requestBody.properties)
+                .filter(([_, propDetails]) => propDetails.readOnly !== true)
+                .map(([propName]) => propName)
+            : [];
+        
+        // Add data__ prefixed fields to SET clause
+        if (reqBodyProps.length > 0) {
+            const setLines = reqBodyProps.map(prop => {
+                const propDetails = methodDetails.requestBody.properties[prop];
+                const isNumber = propDetails.type === 'number' || propDetails.type === 'integer';
+                const isBoolean = propDetails.type === 'boolean';
+                
+                if (isNumber || isBoolean) {
+                    return 'data__' + prop + ' = {{ ' + prop + ' }}';
+                } else {
+                    return 'data__' + prop + ' = \'{{ ' + prop + ' }}\'';
+                }
+            });
+            
+            content += setLines.join(',\n');
+        } else {
+            content += '-- No updatable properties';
+        }
+        
+        // Add WHERE clause with parameters
+        const requiredParams = Object.keys(methodDetails.requiredParams || {});
+        const optionalParams = Object.keys(methodDetails.optionalParams || {});
+        
+        // Get required body props (excluding read-only props)
+        const requiredBodyProps = methodDetails.requestBody?.required 
+            ? methodDetails.requestBody.required.filter(prop => 
+                methodDetails.requestBody.properties[prop] && 
+                methodDetails.requestBody.properties[prop].readOnly !== true)
+            : [];
+        
+        content += '\nWHERE \n';
+        
+        // Add required parameters
+        let clauseCount = 0;
+        
+        // Add required query/path/header params
+        requiredParams.forEach(param => {
+            if (clauseCount > 0) content += '\nAND ';
+            content += param + ' = \'{{ ' + param + ' }}\' --required';
+            clauseCount++;
+        });
+        
+        // Add required body params (only non-readonly ones)
+        requiredBodyProps.forEach(prop => {
+            if (clauseCount > 0) content += '\nAND ';
+            
+            const propDetails = methodDetails.requestBody.properties[prop];
+            const isBoolean = propDetails.type === 'boolean';
+            
+            if (isBoolean) {
+                content += 'data__' + prop + ' = {{ ' + prop + ' }} --required';
+            } else {
+                content += 'data__' + prop + ' = \'{{ ' + prop + ' }}\' --required';
+            }
+            
+            clauseCount++;
+        });
+        
+        // Add optional parameters
+        optionalParams.forEach(param => {
+            if (clauseCount > 0) content += '\nAND ';
+            
+            // For boolean parameters, we can add a comment about their default value
+            const paramDetails = methodDetails.optionalParams[param];
+            const isBoolean = paramDetails.type === 'boolean';
+            const defaultValue = paramDetails.default;
+            
+            if (isBoolean) {
+                content += param + ' = {{ ' + param + '}}';
+            } else {
+                content += param + ' = \'{{ ' + param + '}}\'';
+            }
+            
+            if (isBoolean && defaultValue !== undefined) {
+                content += ' -- default: ' + defaultValue;
+            }
+            
+            clauseCount++;
+        });
+        
+        // returning clause if properties exist
+        if (methodDetails.properties && Object.keys(methodDetails.properties).length > 0) {
+            content += '\nRETURNING\n';
+            const keys = Object.keys(methodDetails.properties);
+            keys.forEach((key, index) => {
+                if (index === keys.length - 1) {
+                    // For the last item, don't add a newline after it
+                    content += `${key}`;
+                } else {
+                    content += `${key},\n`;
+                }
+            });
+        }
+
+        content += ';\n```\n</TabItem>\n';
+    });
+    
+    // Close tabs
+    content += '</Tabs>\n';
+    
+    return content;
+}

package/src/docgen/resource/examples.js

@@ -0,0 +1,31 @@
+// src/docgen/resource/examples.js
+
+import { createSelectExamples } from './examples/select-example.js';
+import { createInsertExamples } from './examples/insert-example.js';
+import { createUpdateExamples } from './examples/update-example.js';
+import { createDeleteExamples } from './examples/delete-example.js';
+import { createExecExamples } from './examples/exec-example.js';
+
+export function createExamplesSection(providerName, serviceName, resourceName, resourceData, dereferencedAPI) {
+    let content = '';
+    
+    // Add SELECT examples
+    content += createSelectExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI);
+
+    // Add INSERT examples
+    content += createInsertExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI);
+    
+    // Add UPDATE examples
+    content += createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, false);
+    
+    // Add REPLACE examples
+    content += createUpdateExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI, true);
+
+    // Add DELETE examples
+    content += createDeleteExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI);
+
+    // Add EXEC examples
+    content += createExecExamples(providerName, serviceName, resourceName, resourceData, dereferencedAPI);    
+
+    return content;
+}

package/src/docgen/resource/fields.js

@@ -0,0 +1,82 @@
+// src/docgen/resource/fields.js
+import { 
+    getSqlMethodsWithOrderedFields, 
+} from '../helpers.js';
+
+const mdCodeAnchor = "`";
+
+export function createFieldsSection(resourceData, dereferencedAPI) {
+    let content = '## Fields\n\n';
+
+    content += 'The following fields are returned by `SELECT` queries:\n\n';
+
+    // Use the reusable function to get methods with ordered fields
+    const methods = getSqlMethodsWithOrderedFields(resourceData, dereferencedAPI, 'select');
+    
+    if (Object.keys(methods).length > 0) {
+        // Create the tabs and markdown content
+        const methodNames = Object.keys(methods);
+        
+        // Create the tab values array for the Tabs component
+        const tabValues = methodNames.map(methodName => {
+            return `{ label: '${methodName}', value: '${methodName}' }`;
+        }).join(',\n        ');
+        
+        // Start building the Tabs component
+        content += `<Tabs
+    defaultValue="${methodNames[0]}"
+    values={[
+        ${tabValues}
+    ]}
+>\n`;
+        
+        // Create the TabItems with table content
+        for (const methodName of methodNames) {
+            const methodData = methods[methodName];
+            
+            // Start the TabItem
+            content += `<TabItem value="${methodName}">\n\n`;
+            
+            // Add the method description if available
+            if (methodData.respDescription) {
+                content += `${methodData.respDescription}\n\n`;
+            }
+            
+            // Add the table header
+            content += `<table>
+<thead>
+    <tr>
+    <th>Name</th>
+    <th>Datatype</th>
+    <th>Description</th>
+    </tr>
+</thead>
+<tbody>`;            
+
+            // Add each property as a row in the table
+            for (const [propName, propData] of Object.entries(methodData.properties)) {
+                content += `\n<tr>
+    <td><CopyableCode code="${propName}" /></td>
+    <td><code>${propData.type}</code></td>
+    <td>${propData.description}</td>
+</tr>`;
+            }
+            
+            content += `\n</tbody>
+</table>
+`;
+
+            // Close the TabItem
+            content += `</TabItem>\n`;
+        }
+        
+        // Close the Tabs component
+        content += `</Tabs>\n`;
+    } else {
+        // no fields
+        content += `${mdCodeAnchor}SELECT${mdCodeAnchor} not supported for this resource, use ${mdCodeAnchor}SHOW METHODS${mdCodeAnchor} to view available operations for the resource.\n\n`;
+    }
+
+    return content;
+}
+