ucg

v1.2.1

Published

15 days ago

Universal CRUD Generator - Database-first code generation tool with Settings page, ORM selection, and advanced filtering

0High
0Medium
0Low

sachin-j

crud generator orm prisma sequelize mongoose postgresql cli nodejs

UCG (Universal CRUD Generator)

A powerful, database-first CRUD generator for Node.js applications. UCG provides an interactive CLI and web dashboard to generate models, controllers, services, and API endpoints for your database tables with comprehensive Swagger/OpenAPI documentation.

🚀 Features

Database-First Approach: Introspect existing databases to generate code
Multiple Database Support: PostgreSQL, MySQL, SQLite, MongoDB
Multiple ORM Support: Prisma, Sequelize, Mongoose adapters
TypeScript & JavaScript: Choose your preferred language during setup
Comprehensive Swagger Documentation: Auto-generated OpenAPI specs with examples
Web Dashboard: Interactive UI for code generation served from node_modules
CLI Tools: ucg init and ucg quick-setup commands
Pluggable Architecture: Easy to add new databases and ORMs
Modern UI: Clean, responsive dashboard with preview capabilities
No File Pollution: Everything served from the plugin, minimal host project changes

📦 Installation & Downloads

Latest Release

npm install ucg@latest

Beta Version (Recommended)

Get the latest features and improvements with comprehensive Swagger documentation:

npm install ucg@beta

Development Version

npm install [email protected]

Download Summary

| Version | Features | Database Support | TypeScript | Swagger Docs | | -------------- | -------------------------------------------------- | ---------------------------------- | ---------- | ------------ | | 1.2.1-beta.1 | 🔥 Latest - TypeScript CRUD fix + Complete Swagger | PostgreSQL, MySQL, SQLite, MongoDB | ✅ Full | ✅ Complete | | 1.2.1-beta.7 | Complete Swagger documentation | PostgreSQL, MySQL, SQLite, MongoDB | ❌ | ✅ Complete | | 1.2.1-beta.6 | Previous beta | PostgreSQL, MySQL, SQLite, MongoDB | ❌ | ⚠️ Basic | | 1.2.0 | Stable release | PostgreSQL, MySQL, SQLite, MongoDB | ❌ | ❌ Limited |

NPM Distribution Tags

latest - Stable release
beta - Beta releases with new features
alpha - Development releases

🎯 Quick Start

Option 1: Add to Existing Project

# Install in your existing Node.js project
npm install ucg

# Initialize UCG (adds routes to your app.js/server.js)
npx ucg init

# Start your application and visit /ucg/setup
npm start

Option 2: Create New Project

# Create a new project with UCG pre-configured
npx ucg quick-setup

# Follow the prompts, then:
cd your-project-name
npm install
npm start

# Visit http://localhost:3000/ucg/setup

🛠️ Usage

CLI Commands

`ucg init`

Adds UCG to an existing Node.js project by mounting the router.

npx ucg init [--json]  # --json for machine-readable output

`ucg quick-setup`

Creates a new Node.js project with UCG pre-configured.

npx ucg quick-setup [--json]

Dashboard URLs

After running ucg init or ucg quick-setup, these URLs will be available:

/ucg/setup - First-time configuration wizard
/ucg/login - Dashboard login
/ucg/dashboard - Main dashboard with table overview
/ucg/generate/model - Model generator
/ucg/generate/crud - CRUD generator
/ucg/api-docs - Auto-generated API documentation

🗄️ Database Support

UCG supports multiple databases with comprehensive adapters:

PostgreSQL ✅

Prisma: Full introspection, model generation, CRUD operations, Swagger docs
Sequelize: Table structure detection, model/controller generation, Swagger docs
Mongoose: Mock adapter (demonstrates architecture)

MySQL ✅

Prisma: Full introspection, model generation, CRUD operations, Swagger docs
Sequelize: Table structure detection, model/controller generation
TypeORM: Coming soon

SQLite ✅

Prisma: Full introspection, model generation, CRUD operations, Swagger docs
Sequelize: Table structure detection, model/controller generation
Better-SQLite3: Coming soon

MongoDB ✅

Prisma: Full document introspection, schema generation, CRUD operations, Swagger docs
Mongoose: Native MongoDB adapter with full ODM support
Native Driver: Coming soon

Database Features Comparison

| Database | Introspection | CRUD Generation | Swagger Docs | Relationships | Migrations | | ---------- | ------------- | --------------- | ------------ | ------------- | ---------- | | PostgreSQL | ✅ | ✅ | ✅ | ✅ | ✅ | | MySQL | ✅ | ✅ | ✅ | ✅ | ✅ | | SQLite | ✅ | ✅ | ✅ | ✅ | ✅ | | MongoDB | ✅ | ✅ | ✅ | ✅ | ⚠️ |

Connection Examples

PostgreSQL

{
  "database": "postgresql",
  "orm": "prisma",
  "credentials": {
    "host": "localhost",
    "port": 5432,
    "database": "myapp",
    "user": "postgres",
    "password": "password"
  }
}

MySQL

{
  "database": "mysql",
  "orm": "prisma",
  "credentials": {
    "host": "localhost",
    "port": 3306,
    "database": "myapp",
    "user": "root",
    "password": "password"
  }
}

SQLite

{
  "database": "sqlite",
  "orm": "prisma",
  "credentials": {
    "database": "./data/app.db"
  }
}

MongoDB

{
  "database": "mongodb",
  "orm": "prisma",
  "credentials": {
    "host": "localhost",
    "port": 27017,
    "database": "myapp",
    "user": "admin",
    "password": "password"
  }
}

Extensible Architecture

The database-first folder structure makes it easy to add new databases:

src/databases/
├── postgresql/          # PostgreSQL adapters
│   ├── prisma/         # Prisma adapter
│   ├── sequelize/      # Sequelize adapter
│   └── mongoose/       # Mock adapter
├── mysql/              # MySQL adapters
│   ├── prisma/         # Prisma adapter
│   └── sequelize/      # Sequelize adapter
├── sqlite/             # SQLite adapters
│   ├── prisma/         # Prisma adapter
│   └── sequelize/      # Sequelize adapter
└── mongodb/            # MongoDB adapters
    ├── prisma/         # Prisma adapter
    └── mongoose/       # Mongoose adapter

🎨 Generated Code Structure

UCG generates clean, production-ready code:

your-project/
├── src/
│   ├── controllers/     # Express controllers with full CRUD
│   ├── services/        # Business logic layer
│   ├── routes/          # Express routes with middleware
│   ├── models/          # ORM models (Prisma/Sequelize/etc)
│   ├── validation/      # Input validation middleware
│   └── tests/           # Unit tests for generated code

🔧 Configuration

UCG stores its configuration in node_modules/ucg/.ucg/config.json - no files are created in your project root.

Example Configuration

{
  "database": "postgresql",
  "orm": "prisma",
  "credentials": {
    "host": "localhost",
    "port": 5432,
    "database": "myapp",
    "user": "postgres",
    "tablePrefix": "app_"
  },
  "user": {
    "email": "[email protected]"
  }
}

🚦 API Generation & Swagger Documentation

Generated Endpoints

For each model, UCG generates RESTful endpoints with comprehensive Swagger documentation:

GET    /models          # List with pagination (clean - no filter examples)
GET    /models/:id      # Get by ID
POST   /models          # Create new (with request/response examples)
PUT    /models/:id      # Update (with request/response examples)
DELETE /models/:id      # Delete (with response examples)

Swagger Documentation Features

UCG generates comprehensive OpenAPI 3.0 specifications with:

✅ Clean GET Operations

Pagination parameters only
No cluttered filter examples
Clear response schemas

✅ Rich POST/PUT/DELETE Operations

Detailed request body examples
Response examples for all status codes
Error handling documentation

✅ Complete Component Schemas

Model definitions with examples
Error response schemas
Pagination metadata schemas

✅ Database-Specific Adaptations

MongoDB: ObjectId format handling
PostgreSQL/MySQL/SQLite: Integer ID autoincrement
All databases: Consistent schema patterns

Example Generated Swagger

# Clean GET endpoint (no examples)
/users:
  get:
    summary: Get all users
    parameters:
      - name: page
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
    responses:
      '200':
        description: Users retrieved successfully

# Rich POST endpoint (with examples)
/users:
  post:
    summary: Create a new user
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserCreate'
          example:
            name: "John Doe"
            email: "[email protected]"
            age: 30
    responses:
      '201':
        description: User created successfully
        content:
          application/json:
            example:
              id: 1
              name: "John Doe"
              email: "[email protected]"
              age: 30
              createdAt: "2024-01-01T00:00:00Z"

API Features

Pagination: Built-in pagination support with metadata
Validation: Input validation middleware with error responses
Relationships: Foreign key relationships populated automatically
Error Handling: Consistent error responses across all endpoints
Status Codes: Proper HTTP status codes (200, 201, 400, 404, 500)
Content Types: JSON request/response handling

📘 TypeScript Support

UCG now supports TypeScript code generation! Choose your preferred language during setup and UCG will generate fully typed code.

Language Selection

During setup (CLI or Web Dashboard), you'll be prompted to select:

JavaScript - Traditional ES6+ JavaScript
TypeScript - Fully typed TypeScript with interfaces

Generated TypeScript Files

When TypeScript is selected, UCG generates:

// user.controller.ts
import { Request, Response } from "express";
import { UserService } from "../services/user.service";

export class UserController {
  private userService: UserService;

  constructor() {
    this.userService = new UserService();
  }

  async getAll(req: Request, res: Response): Promise<void> {
    // Type-safe implementation
  }
}

// user.service.ts
import { PrismaClient, User } from "@prisma/client";

export class UserService {
  private prisma: PrismaClient;

  constructor() {
    this.prisma = new PrismaClient();
  }

  async findAll(page: number = 1, limit: number = 10): Promise<User[]> {
    // Type-safe queries
  }
}

TypeScript Features

✅ Full Type Safety: All generated code uses proper TypeScript types
✅ Express Types: Request, Response, and middleware types
✅ ORM Types: Prisma Client types, Sequelize model types
✅ Interface Definitions: Custom interfaces for DTOs and responses
✅ Generics Support: Type-safe generic implementations
✅ Auto-Configuration: Automatic tsconfig.json generation
✅ Dependency Management: Auto-installs TypeScript and @types packages

TypeScript Configuration

UCG automatically creates a tsconfig.json when TypeScript is selected:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Switching Languages

You can switch between JavaScript and TypeScript at any time:

Via Web Dashboard: Go to Settings → Language Selection
Via CLI: Run npx ucg init again and choose a different language
Manual: Update .ucg/config.json and set "language": "typescript" or "language": "javascript"

TypeScript + Swagger

TypeScript code generation works seamlessly with Swagger documentation:

All types are properly documented in OpenAPI schemas
Request/response examples include TypeScript interfaces
Type-safe API endpoints with full documentation

Running TypeScript Projects

TypeScript files (.ts) cannot be directly executed by Node.js. You have several options:

Option 1: Using ts-node (Recommended for Development)

# Install ts-node
npm install --save-dev ts-node @types/node

# Run your server
npx ts-node server.js

# Or add to package.json scripts:
{
  "scripts": {
    "dev": "ts-node server.js",
    "start": "node dist/server.js"
  }
}

Option 2: Using tsx (Fastest)

# Install tsx (faster than ts-node)
npm install --save-dev tsx

# Run your server
npx tsx server.js

# Or add to package.json:
{
  "scripts": {
    "dev": "tsx server.js",
    "start": "tsx server.js"
  }
}

Option 3: Compile to JavaScript

# Compile TypeScript
npx tsc

# Run compiled JavaScript
node dist/server.js

# Add build script to package.json:
{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "tsc --watch"
  }
}

Troubleshooting TypeScript

Error: Cannot find module './src/routes/xxx.routes.js'

This means UCG generated .ts files, but your code is trying to require .js files.

Solution 1: Regenerate Index Route

# Update UCG to latest version
npm update ucg

# Delete old index file
rm src/routes/index.js

# Regenerate any CRUD (this will create correct index.ts)
# Visit /ucg/generate/crud and regenerate

Solution 2: Use ts-node or tsx

npm install --save-dev tsx
npx tsx server.js

Mixing TypeScript Routes with JavaScript Server

If you have a JavaScript server.js but TypeScript routes:

// server.js (JavaScript)
const express = require("express");
const app = express();

// Use require.resolve to handle .ts files with ts-node
if (require.resolve("./src/routes/index.ts")) {
  const routes = require("./src/routes/index.ts");
  app.use("/api", routes.default || routes);
}

// Then run with: npx ts-node server.js

Or convert your server to TypeScript:

// server.ts (TypeScript)
import express from "express";
import routes from "./src/routes/index";

const app = express();
app.use("/api", routes);

// Run with: npx tsx server.ts

TypeScript Best Practices

Always use a TypeScript runner (ts-node, tsx) or compile before running
Keep tsconfig.json in sync with your project structure
Install type definitions for all dependencies: npm install --save-dev @types/express @types/node
Use ESM imports in TypeScript for better type support
Compile for production to avoid runtime overhead

🧪 Testing & Validation

Testing the UCG Package

# Test the plugin itself
npm test

# Test Swagger documentation templates
node test-swagger-documentation.js

# Test with real databases
node real-database-test.js

# Test SQLite with rich data
node sqlite-focus-test.js

Testing Generated Code

UCG generates unit tests for all generated code:

# Test generated code in your project
npm test  # Run tests for generated models/controllers

Validation Features

UCG includes comprehensive validation testing:

✅ Template Validation

All 6 database adapter templates validated
Swagger documentation completeness checked
HTTP method coverage verified

✅ Database Testing

Real database connection testing
CRUD operation validation
Relationship handling verification

✅ Integration Testing

Dashboard functionality
API endpoint generation
Swagger UI integration

Package Testing Workflow

Before publishing, test the package:

# Create tarball
npm pack

# Install in test project
cd /path/to/test-project
npm install /path/to/ucg-1.2.1-beta.7.tgz

# Test functionality
npx ucg init
# Visit /ucg/setup and test dashboard
# Generate models and test API endpoints

Docker Testing

Test with multiple databases using Docker:

# PostgreSQL
docker run --name test-postgres -e POSTGRES_PASSWORD=password -p 5432:5432 -d postgres:15

# MySQL
docker run --name test-mysql -e MYSQL_ROOT_PASSWORD=password -p 3306:3306 -d mysql:8

# MongoDB
docker run --name test-mongo -p 27017:27017 -d mongo:7

🎯 Development

Project Structure

ucg/
├── package.json
├── bin/ucg                    # CLI entry point
├── src/
│   ├── index.js              # Main exports
│   ├── server.js             # Standalone server (dev)
│   ├── cli/                  # CLI implementations
│   │   ├── init.js
│   │   └── quick-setup.js
│   ├── databases/            # Database-first adapters
│   │   └── postgresql/
│   │       ├── prisma/       # Prisma adapter
│   │       ├── sequelize/    # Sequelize adapter
│   │       └── mongoose/     # Mongoose adapter
│   ├── ui/                   # Web dashboard
│   │   ├── routes/           # Express routes
│   │   ├── views/            # Handlebars templates
│   │   └── static/           # CSS/JS assets
│   ├── lib/                  # Utilities
│   │   ├── config.js         # Configuration management
│   │   └── utils.js          # Helper functions
│   └── tests/                # Unit tests
├── .ucg-config.example.json  # Example configuration
└── README.md

Running in Development

# Clone and setup
git clone <repo>
cd ucg
npm install

# Run development server
npm run dev

# Run tests
npm test

# Lint code
npm run lint

🔒 Security

Password Hashing: User passwords hashed with bcrypt
Configuration Security: Database credentials stored in plugin directory
Input Validation: All generated endpoints include validation
No Secrets: No hardcoded secrets in the repository

📚 API Reference

CLI Integration

When you run ucg init, it adds these lines to your app:

// CommonJS
const ucg = require("ucg");
app.use("/ucg", ucg.router);

// ES Modules
import ucg from "ucg";
app.use("/ucg", ucg.router);

Programmatic Usage

const { router } = require("ucg");
const configManager = require("ucg/src/lib/config");
const utils = require("ucg/src/lib/utils");

// Mount UCG in your app
app.use("/admin/ucg", router);

// Access configuration
const config = await configManager.getConfig();

// Use utilities
const modelName = utils.tableNameToModelName("user_profiles");

🛣️ Roadmap & Changelog

Current Version (1.2.1-beta.7) - Latest Beta ✨

✅ Complete Swagger Documentation: Comprehensive OpenAPI specs for all database adapters
✅ Clean GET Operations: No cluttered filter examples, pagination params only
✅ Rich POST/PUT/DELETE: Detailed request/response examples for all mutations
✅ Multi-Database Support: PostgreSQL, MySQL, SQLite, MongoDB with full CRUD
✅ Database-Specific Handling: ObjectId for MongoDB, integer IDs for SQL databases
✅ Template Validation: All 6 adapters pass comprehensive testing
✅ Real Database Testing: Validated with Docker containers and rich test data

Previous Versions

1.2.1-beta.6

✅ Multi-database support foundation
✅ Basic Swagger documentation
⚠️ Limited API examples

1.2.0 - Stable Release

✅ PostgreSQL + Prisma/Sequelize support
✅ Web dashboard with modern UI
✅ Model and CRUD generation
✅ CLI tools (init, quick-setup)
❌ Limited Swagger documentation

Upcoming Features

Next Release (1.2.2)

Enhanced UI: Code editor with syntax highlighting
Bulk Operations: Generate multiple models at once
Custom Templates: User-defined code templates
Migration Tools: Database schema migration support

Future Enhancements (1.3.0+)

More ORMs: TypeORM, Knex.js, DrizzleORM
GraphQL Generation: Auto-generated GraphQL schemas and resolvers
API Versioning: Support for multiple API versions
Advanced Relationships: Many-to-many, polymorphic relationships
Performance: Query optimization and caching
Testing: Generated test suites with coverage reports

UI/UX Improvements

Dark Mode: Theme switching capability
Mobile Responsive: Full mobile dashboard support
Real-time Preview: Live code preview as you configure
Diff Viewer: Compare generated code changes
Export/Import: Configuration backup and restore

Breaking Changes

1.2.0 → 1.2.1: Configuration format updated for multi-database support
1.1.x → 1.2.0: Dashboard routes restructured, CLI commands updated

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Start

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone and setup
git clone https://github.com/your-repo/ucg.git
cd ucg
npm install

# Run development server
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Test Swagger documentation
node test-swagger-documentation.js

# Test with real databases
node real-database-test.js

Adding New Database Support

Create Database Folder

src/databases/your-database/
├── prisma/           # Prisma adapter
├── sequelize/        # Sequelize adapter
└── your-orm/         # Your ORM adapter

Implement Required Interface Each adapter must implement:

// Database connection and introspection
async introspectTables(connectionConfig)
async testConnection(connectionConfig)

// Code generation
async generateModelCode(table, options)
async generateCRUD(model, options)

// Swagger documentation
generateSwaggerComponents(model)
generateSwaggerPaths(model)

Add Swagger Documentation
- Component schemas with examples
- Clean GET operations (no filter examples)
- Rich POST/PUT/DELETE operations with examples
- Database-specific ID handling (ObjectId vs integer)

Create Tests

// Add to test-swagger-documentation.js
// Add real database test cases
// Validate generated code works

Adding New ORM Support

Create ORM Adapter Folder

src/databases/database-name/your-orm/
├── index.js          # Main adapter
├── introspection.js  # Database introspection
├── generator.js      # Code generation
└── templates/        # Code templates
    ├── model.js
    ├── controller.js
    ├── service.js
    └── routes.js

Follow Template Patterns
- Study existing adapters (Prisma, Sequelize)
- Use consistent naming conventions
- Include comprehensive Swagger documentation
- Handle relationships properly

Testing Guidelines

Write tests for new database adapters
Test with real databases using Docker
Validate Swagger docs are complete and correct
Check generated code compiles and works
Follow existing patterns for consistency

Code Style

Use ES6+ features
Follow existing patterns
Add JSDoc comments for public functions
Use meaningful variable names
Keep functions small and focused

Documentation

Update README.md for new features
Add JSDoc comments for new functions
Include examples in pull requests
Update roadmap if adding major features

📄 License

MIT License - see LICENSE file for details.

🙋‍♂️ Support & Resources