Echo CRUD Factory

> Production-grade CLI code generator for Node.js backend modules with strict conventions and mandatory Swagger documentation


Overview

Echo CRUD Factory is an enterprise-ready CLI tool that generates consistent, opinionated, production-ready CRUD modules for Node.js backends. It enforces strict naming conventions, provides mandatory Swagger documentation, and supports multiple ORMs and databases.

Features

✅ Schema-Driven Generation - Single JSON schema as source of truth
✅ Strict Naming Conventions - Enforced snake_case, kebab-case, PascalCase
✅ Mandatory Swagger/OpenAPI 3.x - Complete API documentation for every endpoint
✅ Multi-ORM Support - Sequelize, TypeORM, Prisma
✅ Multi-Database Support - MySQL, PostgreSQL, SQLite, MariaDB, MSSQL
✅ Yup Validation - 1:1 mapping to Yup API with strict validation
✅ Express-First - Framework-agnostic but optimized for Express
✅ Deterministic Output - Same input always produces same output
✅ Rollback on Failure - Automatic cleanup if generation fails
✅ Dry-Run Mode - Preview files before writing

Requirements

- Node.js: v22.0.0 or higher
- npm: v9.0.0 or higher

Installation

$3

Install as a dev dependency in your project:

``bash
npm install --save-dev echo-crud-factory
`

Important: With local installation, you must use npx prefix for all commands:

`bash
npx echo-crud-factory generate --entity=User --fields=./schema.json
`

Quick Start

$3

`bash
npx echo-crud-factory init --interactive
`

This creates a .echocrudfactoryrc file with your preferences:

`json
{
"orm": "sequelize",
"database": "mysql",
"apiCase": "snake_case",
"dbCase": "snake_case",
"withService": true,
"withRepository": false,
"withSoftDelete": true,
"withPagination": true,
"withTimestamps": true,
"swaggerEnabled": true
}
`

$3

Create user-schema.json:

`json
[
{
"column_name": "id",
"type": "primary"
},
{
"column_name": "first_name",
"type": "string",
"mandatory": true,
"validations": ["min:3", "max:50", "regex:/^[a-zA-Z\\s]+$/"]
},
{
"column_name": "email",
"type": "string",
"mandatory": true,
"unique": true,
"validations": ["email"]
},
{
"column_name": "age",
"type": "integer",
"validations": ["min:18", "max:120"]
},
{
"column_name": "status",
"type": "enum",
"enum_values": ["active", "inactive", "suspended"],
"default_value": "active"
}
]
`

$3

`bash
npx echo-crud-factory generate --entity=User --fields=./user-schema.json
`

$3

`
src/
├── controllers/
│ └── user.controller.js
├── models/
│ └── user.model.js
├── routes/
│ └── user.routes.js
├── validators/
│ └── user.validator.js
└── swagger/
└── user.swagger.js

db/
└── migrations/
└── 20260113185550-create-users.js
`

CLI Commands

$3

Generate CRUD module for an entity.

`bash
npx echo-crud-factory generate --entity=User --fields=./schema.json [options]
`

Options:
- --entity - Entity name in PascalCase (required)
- --table - Table name in snake_case (optional, auto-generated)
- --fields - Path to JSON schema file (required)
- --dry-run - Preview files without writing
- --force - Overwrite existing files
- --verbose - Enable verbose logging

Examples:

`bash


Basic generation

npx echo-crud-factory generate --entity=User --fields=./user-schema.json

Custom table name

npx echo-crud-factory generate --entity=User --table=app_users --fields=./schema.json

Dry run (preview only)

npx echo-crud-factory generate --entity=Product --fields=./schema.json --dry-run

Force overwrite

npx echo-crud-factory generate --entity=Order --fields=./schema.json --force
`

$3

Initialize Echo CRUD Factory configuration.

`bash
npx echo-crud-factory init [--interactive]
`

Options:
- --interactive - Interactive configuration setup

$3

Validate schema file.

`bash
npx echo-crud-factory check --fields=./schema.json
`

$3

Check system dependencies and configuration.

`bash
npx echo-crud-factory doctor
`

$3

View or update configuration.

`bash


Show current configuration

npx echo-crud-factory config --show

Update configuration

npx echo-crud-factory config --set orm=typeorm
npx echo-crud-factory config --set withService=false
`

Schema File Specification

$3

`typescript
{
"column_name": string, // snake_case (required)
"type": ColumnType, // (required)
"mandatory": boolean, // (optional)
"unique": boolean, // (optional)
"default_value": any, // (optional)
"validations": string[], // (optional)
"enum_values": string[], // (required for enum type)
"length": number, // (optional, for string)
"precision": number, // (optional, for float)
"scale": number, // (optional, for float)
"foreign_key": { // (optional)
"table": string,
"column": string,
"on_delete": string,
"on_update": string
},
"index": boolean // (optional)
}
`

$3

- primary - Primary key (BIGINT, auto-increment)
- string - VARCHAR
- text - TEXT
- integer - INTEGER
- bigint - BIGINT
- float - FLOAT/DECIMAL
- boolean - BOOLEAN
- date - DATE/DATETIME
- enum - ENUM (requires enum_values)
- json - JSON

$3

All validation rules map 1:1 to Yup API:

- required - Field is required
- email - Valid email format
- url - Valid URL format
- uuid - Valid UUID format
- min:N - Minimum length/value
- max:N - Maximum length/value
- length:N - Exact length
- matches:/pattern/ or regex:/pattern/ - Regex pattern
- oneOf:val1,val2 - One of specified values
- positive - Positive number
- negative - Negative number
- integer - Integer number
- lessThan:N - Less than value
- moreThan:N - More than value

Example:

`json
{
"column_name": "username",
"type": "string",
"mandatory": true,
"validations": [
"min:3",
"max:20",
"regex:/^[a-zA-Z0-9_]+$/"
]
}
`

Naming Conventions (Strictly Enforced)

| Layer | Convention | Example |
|-------|------------|---------|
| Entity (input) | PascalCase | User, ProductCategory |
| API request/response | snake_case | first_name, created_at |
| DTOs | snake_case | user_id, order_total |
| Yup schemas | snake_case | email, phone_number |
| Database columns | snake_case | first_name, created_at |
| Database tables | snake_case (plural) | users, product_categories |
| Files & folders | kebab-case | user.controller.js, product-category.routes.js |

Any violation will fail generation with a descriptive error.

Generated Code Structure

$3

Express-compatible controllers with:
- Async/await
- Centralized error handling
- snake_case DTOs
- CRUD methods: create, list, get_by_id, update, delete/soft_delete

$3

ORM models with:
- snake_case columns
- Primary key: id (BIGINT)
- Timestamps: created_at, updated_at, deleted_at
- Proper data types and constraints

$3

RESTful endpoints:
- POST /api/users - Create
- GET /api/users - List with pagination
- GET /api/users/:id - Get by ID
- PUT /api/users/:id - Update
- DELETE /api/users/:id - Delete
- POST /api/users/:id/restore - Restore (if soft delete enabled)

$3

Yup validation schemas:
- Create schema (mandatory fields required)
- Update schema (all fields optional)
- Query schema (for filtering)
- Pagination schema

$3

OpenAPI 3.x documentation:
- Complete request/response schemas
- All parameters documented
- Success and error responses
- Tags for organization

$3

Database migrations:
- Timestamp-based naming
- Up/down migrations
- Indexes and constraints
- Foreign keys

Configuration Options

$3

`json
{
"orm": "sequelize", // sequelize | typeorm | prisma
"database": "mysql", // mysql | postgresql | sqlite | mariadb | mssql
"apiCase": "snake_case", // Always snake_case (enforced)
"dbCase": "snake_case", // Always snake_case (enforced)
"withService": true, // Generate service layer
"withRepository": false, // Generate repository layer
"withSoftDelete": true, // Enable soft delete
"withPagination": true, // Enable pagination
"withTimestamps": true, // Add created_at, updated_at
"swaggerEnabled": true // Always true (mandatory)
}
`

Supported ORMs

$3

`bash
npm install sequelize mysql2
`

$3

`bash
npm install typeorm reflect-metadata mysql2
`

$3

`bash
npm install @prisma/client
npm install -D prisma
`

Integration Example

$3

`javascript
import express from 'express';
import userRoutes from './routes/user.routes.js';
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const app = express();

app.use(express.json());

// Routes
app.use('/api/users', userRoutes);

// Swagger
const swaggerOptions = {
definition: {
openapi: '3.0.0',
info: {
title: 'API Documentation',
version: '1.0.0',
},
},
apis: ['./src/routes/.js', './src/swagger/.js'],
};

const swaggerSpec = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

app.listen(3000, () => {
console.log('Server running on port 3000');
});
`

Best Practices

1. Always use schema files - Don't manually write CRUD code
2. Validate schemas - Run echo-crud-factory check before generating
3. Use dry-run - Preview files with --dry-run flag
4. Version control schemas - Keep schema files in git
5. Review generated code - Always review before committing
6. Run migrations - Don't forget to run database migrations
7. Test endpoints - Use generated Swagger docs for testing

Troubleshooting

$3

`
✗ Node.js v22 or higher is required
`

Solution: Upgrade Node.js to v22 or higher.

$3

`
✗ Column name "firstName" must be in snake_case format
`

Solution: Use snake_case for all column names: first_name.

$3

`
✗ File already exists: src/controllers/user.controller.js
`

Solution: Use --force flag to overwrite or manually delete the file.

$3

`
✗ Required dependency not found: sequelize
`

Solution: Install required dependencies:
`bash
npm install sequelize mysql2
``

Roadmap

- [ ] TypeORM model generator
- [ ] Prisma schema generator
- [ ] Service layer generator
- [ ] Repository layer generator
- [ ] Test file generator
- [ ] OpenAPI to Postman export
- [ ] Custom template support
- [ ] Plugin system
- [ ] GraphQL support

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © Master Builder Team

---

Built with ❤️ for backend developers who value consistency and quality.