@sampathkumara/express-to-dart-endpoints-builder 1.0.0

package/CLAUDE.md

@@ -0,0 +1,304 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a modular npm package that provides an Express.js-to-Dart code generator. It automatically generates production-ready Dart API clients from Express.js route definitions with full JSDoc support, authentication handling, and type mapping.
+
+## Package Structure
+
+```
+express-to-dart-endpoints-builder/
+├── bin/
+│   └── cli.js                 # CLI entry point
+├── src/
+│   ├── index.js               # Main export & orchestration
+│   ├── config.js              # Configuration loading and validation
+│   ├── parser.js              # Route parsing and tree building
+│   ├── generator.js           # Dart code generation
+│   ├── typeMapper.js          # JS to Dart type mapping
+│   └── utils.js               # Utility functions
+├── package.json               # npm package metadata
+├── README.md                  # User-facing documentation
+└── CLAUDE.md                  # This file
+```
+
+## Quick Start Commands
+
+- **Generate Dart API client**: `npm run generate` or `express-to-dart`
+- **Initialize config**: `express-to-dart init`
+- **Show help**: `express-to-dart --help`
+
+## Architecture & Key Concepts
+
+### Module Organization
+
+**bin/cli.js** - Command-line interface
+- Parses CLI arguments and options
+- Routes to appropriate commands (`generate`, `init`, `help`)
+- Handles `--config`, `--help`, `--version` flags
+
+**src/index.js** - Main orchestration
+- Exports `generate()` function as primary API
+- Loads config, validates it, calls parser and generator
+- Returns structured result with success/error info
+
+**src/config.js** - Configuration management
+- `loadConfig()`: Loads from file or defaults
+- `validateConfig()`: Validates required settings
+- `createDefaultConfigFile()`: Generates template config
+- Includes sensible defaults for all options
+
+**src/parser.js** - Route parsing logic
+- `parseFile()`: Extracts routes and sub-routers from a single file
+- `buildRouteTree()`: Recursively builds complete route tree
+- Uses regex to find routes, extracts JSDoc, detects auth/permissions
+- Returns flat list of all routes with full paths
+
+**src/generator.js** - Dart code generation
+- `generateDartMethod()`: Creates Dart method for single route
+- `generateApiOptions()`: Creates ApiOptions class
+- `generateServerEndpoints()`: Creates ServerEndpoints class
+- `generateDartFile()`: Combines all into complete Dart file
+
+**src/typeMapper.js** - Type mapping
+- `mapType()`: Converts JS/JSDoc types to Dart types
+- `isFileReturnType()`: Detects file download responses
+- Handles basic types, arrays, maps, and custom types
+
+**src/utils.js** - Utility functions
+- `generateMethodName()`: Converts routes to camelCase method names
+- `extractNearestJsDoc()`: Finds JSDoc before routes
+- `parseJsDocLine()`: Parses individual JSDoc lines
+- `normalizePermission()`: Converts permission names
+- Helper validators and type checks
+
+### Core Generation Flow
+
+1. **Configuration Loading** (config.js):
+   - Loads from provided path, CWD, or defaults
+   - Validates required fields
+   - Merges user config with defaults
+
+2. **Route Discovery** (parser.js):
+   - Entry point is `routes/api.js`
+   - Uses regex to find all router definitions
+   - Extracts nearest JSDoc comment for each route
+   - Detects router-level authentication
+   - Recursively processes sub-routers via `router.use()`
+   - Handles array-based route definitions
+   - Returns flat tree of all routes with full paths
+
+3. **JSDoc Extraction** (parser.js, utils.js):
+   - Parses `@var {type} paramName` for parameters
+   - Parses `@returns {type}` for return types
+   - Parses `@deprecated` for deprecation
+   - Infers parameter location (path/query/body)
+   - Supports explicit location prefixes (req.body., req.query., req.params.)
+
+4. **Authentication & Permissions** (parser.js):
+   - Detects `router.use(authenticateToken)`
+   - Finds `PermissionsMiddleware([...])`
+   - Normalizes `NsUserPermissions.*` → `NsPermissions.*`
+   - Inherits auth/permissions down route tree
+
+5. **Type Mapping** (typeMapper.js):
+   - Basic types: string, number, boolean, int
+   - Special types: file, date, datetime
+   - Collections: string[], list<T>, array<T>, map<K, V>
+   - Custom types pass through unchanged
+
+6. **Code Generation** (generator.js):
+   - Creates Dart method for each route
+   - Handles path/query/body parameters
+   - Generates file upload/download code
+   - Includes permission checks
+   - Builds proper API call statements
+
+### Generated Output
+
+**ServerEndpoints.dart** contains:
+- Class with static methods for each API endpoint
+- Method names from paths: `/users/:id/posts` → `usersById_posts()`
+- Full JSDoc with source file reference
+- Auth & permission checks
+- Parameter marshalling (body, query, files)
+- Proper HTTP method calls with ApiOptions
+- File download progress callbacks
+
+**ApiOptions.dart** class:
+- `reFreshToken`: Force token refresh
+- `cancelToken`: Dio cancellation
+- `onReceiveProgress`/`onSendProgress`: Progress tracking
+- `enableRetry`: Auto-retry logic
+- `skipAuth`: Skip authentication
+- `maxRetries`: Retry count
+- `formData`: Custom FormData
+- `useServerFileName`: Download filename handling
+
+## Type System & JSDoc Conventions
+
+### Parameter Documentation
+
+All parameters must be documented with `@var` tags:
+
+```javascript
+/**
+ * Get user profile by ID
+ * @var {string} userId - The user ID (path parameter)
+ * @var {string} includeDetails - Include detailed information (query parameter)
+ * @var {object} metadata - Additional metadata object (body parameter)
+ */
+router.get('/users/:userId', ...)
+```
+
+The generator infers parameter location from:
+1. Explicit prefix: `req.body.`, `req.query.`, `req.params.`
+2. Path presence: `:paramName` in route → path param
+3. HTTP method: GET → query, POST/PUT/PATCH → body
+4. Fallback: assume body for non-GET requests
+
+### Return Type & File Downloads
+
+Indicate file responses with `@returns {file}`:
+
+```javascript
+/**
+ * Download user export
+ * @returns {file}
+ */
+router.get('/exports/users', ...)
+```
+
+This generates:
+- Extra `savePath` and `useServerFileName` parameters
+- Call to `Api.downloadFile()` instead of regular HTTP methods
+- Progress callback support via `ApiOptions.onReceiveProgress`
+
+### Deprecation
+
+Mark deprecated routes:
+
+```javascript
+/**
+ * Get legacy user data (deprecated)
+ * @deprecated Use getUser instead
+ */
+router.get('/legacy/users/:id', ...)
+```
+
+This adds Dart `@Deprecated()` annotation to generated method.
+
+## Code Patterns & Key Implementation Details
+
+### Route Tree Building (src/parser.js)
+
+The `buildRouteTree()` function recursively processes:
+1. Direct routes in current file: `router.get()`, `router.post()`, etc.
+2. Sub-routers mounted: `router.use(mountPath, routerVar)`
+3. Array-based definitions: `{path: '...', handler: varName}`
+
+Each route inherits from parents:
+- **Authentication**: Merged via OR (parent auth OR route auth = authenticated)
+- **Permissions**: Combined in array (parent permissions + route permissions)
+
+### Method Name Generation (src/utils.js)
+
+Routes → camelCase method names:
+- `/users` → `users()`
+- `/users/:id` → `usersById()`
+- `/api/users/:userId/posts` → `usersBy_userId_posts()`
+
+Algorithm:
+1. Strip leading `/`
+2. Split by `/`
+3. For each segment:
+   - Replace `:paramName` with `by_paramName`
+   - Convert to camelCase
+4. Join with underscores
+
+### Type Mapping (src/typeMapper.js)
+
+Handles:
+- Basic types via mapping table
+- Arrays: `string[]`, `list<T>`, `array<T>`
+- Maps: `map<K, V>` parsed and recursively mapped
+- Unknown types: pass through as-is
+
+### JSDoc Extraction (src/utils.js)
+
+Uses `extractNearestJsDoc()` to find the closest JSDoc before a route:
+1. Find all JSDoc blocks before the route definition
+2. Check only the last one (closest)
+3. Verify only whitespace between JSDoc and route
+4. Handle stacked JSDoc blocks (multiple comments)
+
+Then `parseJsDocLine()` parses each line for:
+- `@var {type} name [description]` → parameter
+- `@returns {type}` → return type
+- `@deprecated [message]` → deprecation mark
+
+### Middleware Section Isolation (src/parser.js)
+
+To correctly extract `PermissionsMiddleware`:
+1. Find route pattern match end (after closing quote of path)
+2. Find function body opening brace (`{`)
+3. Extract everything between these two positions
+4. Search for `PermissionsMiddleware([...])` only in this section
+5. Reduces false positives from handler code
+
+## Module Imports & Dependencies
+
+Internal module dependencies:
+- `config.js` → (no dependencies on other src modules)
+- `parser.js` → `typeMapper.js`, `utils.js`
+- `generator.js` → `utils.js`
+- `index.js` → `config.js`, `parser.js`, `generator.js`
+- `cli.js` → `index.js`, `config.js`
+
+External dependencies:
+- Node.js `fs`, `path` modules only
+- No external npm packages required
+
+## Debugging & Troubleshooting
+
+Console output during generation:
+- Config loading status
+- Route count found
+- Generation completion
+- Output file path
+- Warnings for invalid parameters
+
+Enable debugging:
+- Check console output for missing routes
+- Verify `api.js` exists and has routes
+- Inspect generated `.dart` file for correct formatting
+
+## Development Guidelines
+
+When modifying the code:
+1. Keep modules focused on single responsibility
+2. Update corresponding tests if adding features
+3. Maintain JSDoc comments in source code
+4. Preserve the modular structure (utils ← generator, parser)
+5. Add validation for config and parsed data
+
+### Adding New Features
+
+**New route type support**: Update regex in `parseFile()` in parser.js
+
+**New parameter type**: Add to type mapping table in typeMapper.js
+
+**New code generation pattern**: Add function to generator.js, call from generateDartFile()
+
+**New config option**: Add to DEFAULT_CONFIG in config.js and validate in validateConfig()
+
+**New CLI command**: Add to main() function in bin/cli.js, implement logic in src/
+
+## Performance Considerations
+
+- Generation is O(files × routes) - linear with codebase size
+- Regex scanning is efficient for typical route files
+- No caching between runs (stateless for each generation)
+- Sub-router recursion depth depends on nesting (typically 2-3 levels)

package/MIGRATION.md

@@ -0,0 +1,335 @@
+# Migration Guide: From Standalone Scripts to NPM Package
+
+This document explains the transformation from the original standalone scripts to a professional npm package.
+
+## What Changed
+
+### Before (Original Structure)
+```
+express-to-dart-endpoints-builder/
+├── EndpointsToDartFull.js      # Main code generator (monolithic)
+├── endPoints.js                 # Legacy endpoints class generator
+└── endpoints-to-dart.config.json # Configuration file
+```
+
+**Usage:**
+```bash
+node EndpointsToDartFull.js
+# or
+node endPoints.js
+```
+
+### After (NPM Package Structure)
+```
+express-to-dart-endpoints-builder/
+├── bin/
+│   └── cli.js                   # CLI entry point
+├── src/
+│   ├── index.js                 # Main API export
+│   ├── config.js                # Configuration management
+│   ├── parser.js                # Route parsing logic
+│   ├── generator.js             # Dart code generation
+│   ├── typeMapper.js            # Type mapping utilities
+│   └── utils.js                 # Helper functions
+├── examples/
+│   ├── example-routes.js        # Route examples
+│   ├── example-config.json      # Config example
+│   ├── example-usage.dart       # Dart usage examples
+│   ├── example-programmatic.js  # Node.js API examples
+│   └── README.md                # Examples guide
+├── package.json                 # NPM package metadata
+├── README.md                    # User documentation
+└── CLAUDE.md                    # Developer documentation
+```
+
+**Usage:**
+```bash
+# CLI
+express-to-dart generate
+# or
+npm run generate
+
+# Programmatic
+const { generate } = require('express-to-dart-endpoints-builder');
+const result = generate();
+```
+
+## Key Improvements
+
+### 1. **Modular Architecture**
+- Single 700+ line file split into 6 focused modules
+- Each module has a single responsibility
+- Easy to understand, test, and maintain
+
+### 2. **Better Configuration**
+- Default configuration with sensible defaults
+- `express-to-dart init` command to scaffold config
+- `--config` flag to use custom config files
+- Configuration validation and helpful error messages
+
+### 3. **Professional CLI**
+- Standard command structure: `express-to-dart <command>`
+- Help, version, and init commands
+- Proper error handling and exit codes
+- Works globally after `npm install -g`
+
+### 4. **Better Error Handling**
+- Structured error messages
+- Return objects with success/error information
+- Helpful suggestions for common issues
+
+### 5. **Full Documentation**
+- Comprehensive README with examples
+- API documentation with type information
+- CLAUDE.md for future developer context
+- Multiple example files (routes, config, Dart, Node.js)
+
+### 6. **Backward Compatibility**
+- Original EndpointsToDartFull.js still works
+- Legacy endPoints.js still available
+- Default configuration format unchanged
+
+## Functionality Parity
+
+All original functionality is preserved:
+
+| Feature | Status |
+|---------|--------|
+| JSDoc parsing | ✓ Unchanged |
+| Type mapping | ✓ Unchanged |
+| Route discovery | ✓ Unchanged |
+| Authentication detection | ✓ Unchanged |
+| Permission extraction | ✓ Unchanged |
+| File upload/download handling | ✓ Unchanged |
+| Sub-router traversal | ✓ Unchanged |
+| Deprecation handling | ✓ Unchanged |
+| Dart code generation | ✓ Unchanged |
+
+## Migration Steps
+
+### For Existing Projects
+
+**Step 1: Update your workflow**
+
+Instead of:
+```bash
+node EndpointsToDartFull.js
+```
+
+Use:
+```bash
+npm run generate
+# or
+express-to-dart
+```
+
+**Step 2: Verify configuration**
+
+Your existing `endpoints-to-dart.config.json` works as-is. No changes needed!
+
+**Step 3: Review generated output**
+
+Generated Dart code is identical to before. No changes to your Dart code needed!
+
+### For New Projects
+
+**Step 1: Install**
+```bash
+npm install express-to-dart-endpoints-builder
+```
+
+**Step 2: Initialize**
+```bash
+express-to-dart init
+# Creates endpoints-to-dart.config.json
+```
+
+**Step 3: Configure**
+Edit `endpoints-to-dart.config.json` with your paths
+
+**Step 4: Generate**
+```bash
+npm run generate
+```
+
+## API Changes
+
+### CLI
+
+**Old:**
+```bash
+node EndpointsToDartFull.js      # Always generated
+node endPoints.js                 # Legacy class only
+```
+
+**New:**
+```bash
+express-to-dart                   # Default: generate
+express-to-dart generate          # Explicit generate
+express-to-dart init              # Initialize config
+express-to-dart --help            # Show help
+express-to-dart --version         # Show version
+express-to-dart generate --config ./config.json
+```
+
+### Programmatic API
+
+**Old:**
+```javascript
+// Had to require specific modules and call functions
+require('./EndpointsToDartFull.js');
+// or
+const { buildEndPointsClass } = require('./endPoints.js');
+```
+
+**New:**
+```javascript
+const { generate, loadConfig, validateConfig } =
+  require('express-to-dart-endpoints-builder');
+
+// Simple one-liner
+const result = generate();
+
+// Or with custom config
+const result = generate('./config.json');
+
+// With result object
+if (result.success) {
+  console.log(`Generated ${result.count} endpoints`);
+  console.log(`Saved to: ${result.outputPath}`);
+  result.routes.forEach(route => {
+    console.log(`${route.method} ${route.fullPath}`);
+  });
+}
+```
+
+## Configuration Changes
+
+No breaking changes! Your existing config file works as-is.
+
+**New optional fields:**
+```json
+{
+  "classNameEndpoints": "ServerEndpoints"  // Default class name (was hardcoded)
+}
+```
+
+**All existing fields still supported:**
+- `routesDir`
+- `outputDir`
+- `baseUrl`
+- `apiClassName`
+- `imports`
+- `includePatterns`
+- `excludePatterns`
+
+## File Structure Mapping
+
+| Original | New Location | Purpose |
+|----------|--------------|---------|
+| EndpointsToDartFull.js (main logic) | src/parser.js | Route parsing |
+| EndpointsToDartFull.js (types) | src/typeMapper.js | Type conversion |
+| EndpointsToDartFull.js (generation) | src/generator.js | Dart code generation |
+| EndpointsToDartFull.js (utils) | src/utils.js | Helper functions |
+| (new) | src/config.js | Config management |
+| (new) | src/index.js | Main export |
+| (new) | bin/cli.js | CLI interface |
+
+## Testing
+
+All functionality has been tested:
+
+✓ Type mapping (string, number, arrays, maps, custom types)
+✓ Method name generation (camelCase conversion)
+✓ Parameter validation and detection
+✓ JSDoc parsing and extraction
+✓ Configuration loading with defaults
+✓ CLI help and version commands
+✓ Error handling and reporting
+
+## Performance
+
+**No change in performance.** The refactored code:
+- Uses the same algorithms
+- Has the same time complexity: O(files × routes)
+- Maintains stateless generation
+- Supports sub-router recursion
+
+## Package.json Scripts
+
+```json
+{
+  "scripts": {
+    "start": "node bin/cli.js",
+    "generate": "node bin/cli.js generate",
+    "init": "node bin/cli.js init"
+  }
+}
+```
+
+**Usage:**
+```bash
+npm run generate    # Generate Dart code
+npm run init        # Create config template
+npm start           # Run CLI (shows help)
+```
+
+## Backward Compatibility
+
+The original files still exist and work:
+
+```bash
+# Still works
+node EndpointsToDartFull.js
+node endPoints.js
+```
+
+They have NOT been removed or modified, so existing scripts/workflows continue to function.
+
+## What's New
+
+### For Users
+
+1. **Easy installation**: `npm install -g express-to-dart-endpoints-builder`
+2. **Simple commands**: `express-to-dart generate`
+3. **Better error messages**: Clear guidance on fixing issues
+4. **Documentation**: Comprehensive README and examples
+5. **Configuration template**: `express-to-dart init` creates starter config
+
+### For Developers
+
+1. **Modular code**: Easy to understand, extend, and test
+2. **Clear separation**: Each module has one job
+3. **Developer docs**: CLAUDE.md explains architecture
+4. **Examples**: Multiple examples in examples/ directory
+5. **Better errors**: Helpful error objects with context
+
+## Deprecations
+
+None! All original features are supported.
+
+The original standalone scripts are still available but the new package is the recommended approach for:
+- New projects
+- Developers who want to use it as a Node.js module
+- CI/CD integration
+- Global CLI tool
+- Distribution via npm
+
+## Support
+
+- **README.md** - User-facing documentation
+- **CLAUDE.md** - Developer documentation
+- **examples/** - Code examples
+- **GitHub Issues** - Report bugs and request features
+
+## Questions?
+
+Refer to:
+1. **README.md** - Comprehensive user guide
+2. **examples/README.md** - Practical examples
+3. **CLAUDE.md** - Architecture and implementation
+4. **examples/example-programmatic.js** - Integration examples
+
+---
+
+**All original functionality preserved. All new features are additive. Zero breaking changes.**