hana-developer-cli-tool-example utility-module-development.instructions.md

Utility Module Development Guidelines

Use this guide when creating or modifying JavaScript utility files in the utils/ directory (excluding utils/database/ which has separate instructions).

Scope and Purpose

This guide applies to shared utility modules in utils/ that provide common functionality across CLI commands, routes, and other components. Key modules include:

• base.js / base-lite.js - Core functionality and database connections
• connections.js - Connection parameter resolution
• locale.js - Locale detection and normalization
• sqlInjection.js - SQL injection prevention
• commandSuggestions.js - Command suggestion system
• config-loader.js - Configuration file loading
• massConvert.js, massExport.js, etc. - Bulk operation utilities
• dbInspect.js - Database schema inspection
• doc-linker.js - Documentation cross-linking
• versionCheck.js - Version validation

Critical Principles

1. Type Safety: Use @ts-check and JSDoc annotations for type information
2. Lazy Loading: Defer expensive imports until needed to optimize startup time
3. Internationalization: All user-facing strings must use bundle.getText()
4. Error Handling: Provide clear, actionable error messages with context
5. Debug Support: Use base.debug() for diagnostic logging
6. Caching: Implement intelligent caching for expensive operations
7. Pure Functions: Prefer stateless functions with predictable behavior
8. Configuration: Support configuration overrides from config files

File Structure Template

/*eslint-env node, es6 */
// @ts-check

/**
 * @module moduleName - Brief description of module purpose
 */

// Standard imports
import * as base from "./base.js"
import * as fs from 'fs'
import * as path from 'path'

// Module-level state (minimize)
const cache = new Map()

/**
 * Main function documentation
 * @param {string} param1 - Description
 * @param {number} [param2] - Optional parameter
 * @returns {Promise<ReturnType>} Description of return value
 */
export async function mainFunction(param1, param2) {
    base.debug(base.bundle.getText("debug.call", ["mainFunction"]))
    
    try {
        // Implementation
        return result
    } catch (error) {
        throw new Error(base.bundle.getText("error.specificError", [param1]))
    }
}