Gen - Single Source of Truth Code Generator


Gen is a comprehensive code generation system that serves as a single source of truth for application configuration. Define your entities once and automatically generate database schemas, API routes, and frontend components for multiple targets including Drizzle, Prisma, SQL, Convex, React, Vue, and more.

✨ Features

$3

- Single Source of Truth: Define entities with database schema, UI components, permissions, mutations, and validation in one place
- Type-Safe Throughout: Full TypeScript support from entity definition to generated code
- Component Registry: UI-framework-agnostic system supporting React, Vue, Svelte, and custom components

$3

- Database Support: Generate schemas for Drizzle ORM, Prisma, raw SQL (Postgres/MySQL/SQLite), and Convex
- API Generation: Create Express, Fastify, Hono, or Koa routes with validation, middleware, and OpenAPI specs
- Frontend Components: Generate React/Vue/Svelte components, forms, lists, and detail views

$3

- Role-Based Access: Different permissions per user role (read, write, create, update, delete, admin)
- Ownership Controls: Require ownership checks with configurable owner fields
- Organization Scoping: Scope access by organization with cross-org support
- Attribute-Based Access: Custom attribute checks with operators
- Temporal Permissions: Time-based and schedule-based access controls
- Field-Level Security: Per-field read/write permissions with data masking

$3

- Audited Operations: Full audit trail tracking who, when, and what changed

$3

- Type-Safe Errors: 100% type-safe error handling with no magic strings
- Flexible Paradigms: Supports both throwing exceptions AND returning Result types
- Extensible Registry: Register custom error classes while using sensible defaults
- Rich Error Catalog: 25+ predefined errors with recovery suggestions across 11 categories
- Framework Integration: Works with Express, Fastify, and custom error handling patterns
- Advanced Utilities: Retry logic, error boundaries, HTTP status mapping, and batch processing
- Rollback Support: Versioned mutations with rollback capabilities
- Lifecycle Hooks: Before/after create, update, delete hooks
- Input/Output Validation: StandardSchema-compatible validation
- Approval Workflows: Optional approval processes for sensitive operations

$3

- CLI Tool: Powerful command-line interface with dry-run, backup, and incremental generation
- Custom Generators: Extensible system for custom code generation
- Configuration System: Flexible configuration with smart defaults and overrides
- Advanced Error System: See Error System Documentation for comprehensive error handling
- Tagged Template System: Enhanced syntax highlighting with language-specific tagged templates (HTML, CSS, SQL, TypeScript, etc.)

🚀 Quick Start

$3

``bash
npm install -g @doeixd/gen


or


npm install --save-dev @doeixd/gen
`

$3

Create an entity definition file (e.g., entities.ts):

`typescript
import { createEntity, ComponentRegistry, validators, dbTypes } from '@doeixd/gen'

// Register your UI components (do this once)
ComponentRegistry.registerBulk({
TextField: MyUILib.TextField,
NumberField: MyUILib.NumberField,
EmailField: MyUILib.EmailField,
})

// Define a User entity
export const userEntity = createEntity({
id: 'user',
name: { singular: 'User', plural: 'Users' },
db: {
table: { name: 'users', primaryKey: ['id'] },
columns: {
id: { type: dbTypes.id() },
email: { type: dbTypes.string(255) },
name: { type: dbTypes.string(100) },
role: { type: dbTypes.enum(['user', 'admin', 'superadmin']) },
}
},
fields: {
id: { standardSchema: validators.uuid },
email: { standardSchema: validators.email },
name: { standardSchema: validators.stringMin(1) },
role: { standardSchema: validators.enum(['user', 'admin', 'superadmin']) },
},
permissions: {
create: { roles: ['admin'] },
read: { roles: ['user', 'admin'] },
update: { roles: ['admin'], ownership: { field: 'id' } },
delete: { roles: ['superadmin'] },
}
})
`

$3

`bash


Generate everything

@doeixd/gen --targets=database,api,frontend

Generate with custom config

@doeixd/gen --config=./gen-config.js --targets=database --dry-run

Generate specific database targets

@doeixd/gen --targets=drizzle,prisma,sql
`

📖 Entity System

The core of Gen is the Entity type, which combines all aspects of your data model:

`typescript
type Entity = {
// Identity & Metadata
id: string
name: NameConfig
version: number
createdAt: Date

// UI Components (actual function references!)
components?: {
display?: ComponentRef
input?: ComponentRef
loading?: ComponentRef
}

// Database Schema
db: {
table: DbTable
columns: { [K in keyof T]: DbColumn }
indexes?: DbIndex[]
constraints?: DbConstraint[]
}

// Field Configuration
fields: { [K in keyof T]: FieldMapping }

// Relationships
relationships?: RelationshipMapping[]

// Routes & Navigation
routes?: RoutesConfig

// Permissions
permissions?: EntityPermissions

// Mutations with Audit Trail
mutators?: Record>

// Lifecycle Hooks
hooks?: {
beforeCreate?: (data: Partial) => Promise
afterCreate?: (data: T) => Promise
// ... more hooks
}
}
`

$3

Use the createEntity() helper for sensible defaults:

`typescript
import { createEntity, dbTypes, validators } from '@doeixd/gen'

const productEntity = createEntity({
id: 'product',
name: { singular: 'Product', plural: 'Products' },
db: {
table: { name: 'products', primaryKey: ['id'] },
columns: {
id: dbTypes.id(),
name: dbTypes.string(255),
price: dbTypes.decimal(10, 2),
inStock: dbTypes.boolean(),
}
},
fields: {
name: { standardSchema: validators.stringMin(1) },
price: { standardSchema: validators.numberMin(0) },
inStock: { standardSchema: validators.boolean },
}
})
`

🎨 Code Generation

$3

Generate database schemas for multiple targets:

`bash


Generate Drizzle ORM schema

@doeixd/gen --targets=drizzle

Generate Prisma schema

@doeixd/gen --targets=prisma

Generate raw SQL migrations

@doeixd/gen --targets=sql

Generate Convex schema

@doeixd/gen --targets=convex
`

Generated Output:
`
📁 database/
├── drizzle/
│ └── users.ts
├── prisma/
│ └── users.prisma
├── migrations/
│ └── 001_users.sql
└── convex/
└── users.ts
`

$3

Create complete API routes with validation and middleware:

`bash


Generate Express routes

@doeixd/gen --targets=api --api-framework=express

Generate with OpenAPI specs

@doeixd/gen --targets=api --include-openapi
`

Generated Output:
`
📁 api/
├── routes/
│ └── users.ts
├── controllers/
│ └── users.controller.ts
├── middleware/
│ └── users.middleware.ts
├── validators/
│ └── users.validator.ts
└── types/
└── users.types.ts
`

$3

Generate UI components and routes:

`bash


Generate React components

@doeixd/gen --targets=frontend --frontend-framework=react

Generate with forms and tables

@doeixd/gen --targets=frontend --include-forms --include-tables
`

Generated Output:
`
📁 frontend/
├── components/
│ ├── UserList.tsx
│ ├── UserDetail.tsx
│ └── UserForm.tsx
├── forms/
│ └── UserForm.tsx
└── routes/
├── users/
│ ├── index.tsx
│ ├── create.tsx
│ └── [id]/
│ ├── view.tsx
│ └── edit.tsx
`

🏷️ Tagged Template System

Gen uses specialized tagged template functions for enhanced syntax highlighting and better developer experience when writing code generators.

$3

`typescript
import { html, css, sql, ts, gql, json, yaml, md } from '@doeixd/gen'

// HTML/JSX templates with proper highlighting
const componentTemplate = html

// CSS templates with highlighting
const stylesTemplate = css
.user-card {
border: 1px solid #ccc;
border-radius: 8px;
padding: 1rem;
}

.user-card h2 {
color: #333;
margin-bottom: 0.5rem;
}

// SQL templates with highlighting
const queryTemplate = sql
SELECT u.id, u.name, u.email, p.title as role
FROM users u
LEFT JOIN user_permissions p ON u.id = p.user_id
WHERE u.active = true
ORDER BY u.created_at DESC

// TypeScript templates with highlighting
const typeTemplate = ts
export interface User {
id: string
name: string
email: string
role: 'user' | 'admin' | 'superadmin'
createdAt: Date
}

export function validateUser(user: User): boolean {
return user.name.length > 0 && user.email.includes('@')
}

// GraphQL templates with highlighting
const graphqlTemplate = gql
query GetUsers($limit: Int, $offset: Int) {
users(limit: $limit, offset: $offset) {
id
name
email
role
createdAt
}
}

mutation UpdateUser($id: ID!, $input: UpdateUserInput!) {
updateUser(id: $id, input: $input) {
id
name
email
}
}

// JSON templates with highlighting
const configTemplate = json
{
"database": {
"host": "localhost",
"port": 5432,
"name": "myapp"
},
"features": {
"authentication": true,
"fileUploads": false
}
}

// YAML templates with highlighting
const dockerTemplate = yaml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
depends_on:
- db

db:
image: postgres:13
environment:
POSTGRES_DB: myapp

// Markdown templates with highlighting
const readmeTemplate = md
# My Project

This is a sample project generated with Gen.

## Features

- User authentication
- Role-based permissions
- CRUD operations
- Type-safe throughout

## Getting Started

\\\bash
npm install
npm run dev
\\\

`

$3

For dynamic language selection, use the code() function:

`typescript
import { code } from '@doeixd/gen'

// Generate code with specific language hints
const pythonCode = code('python')
def calculate_fibonacci(n):
if n <= 1:
return n
return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)

print(calculate_fibonacci(10))

const rustCode = code('rust')
fn main() {
println!("Hello, world!");
let x = 42;
println!("The answer is: {}", x);
}

`

$3

`typescript
import { conditional, map } from '@doeixd/gen'

// Conditional template inclusion
const formTemplate = html

${conditional(showPassword, )}
Login

// Mapping arrays to template content
const listTemplate = html

${map(items, (item) =>
• ${item.name} - $${item.price}
)}


`

$3

For the best syntax highlighting experience, install the Tagged Template Syntax Highlighting extension:

- Extension ID: schoero.tagged-template-syntax-highlighting
- Install: ext install schoero.tagged-template-syntax-highlighting

This extension recognizes the tagged template functions and provides proper syntax highlighting for the embedded content in each template type.

🛤️ Advanced Generators

Gen provides specialized generators for different frameworks and use cases:

$3

Generate RESTful API routes similar to Ruby on Rails:

`bash
@doeixd/gen generate --targets=rails
`

Features:
- RESTful routes (index, show, create, update, destroy)
- Middleware support
- Validation integration
- Error handling
- TypeScript types

$3

Generate Next.js 13+ App Router API routes:

`bash
@doeixd/gen generate --targets=nextjs
`

Features:
- App Router compatible (app/api/ structure)
- Pagination, filtering, and sorting
- Zod validation integration
- TypeScript throughout
- Server-side rendering support

$3

Generate OpenAPI 3.0 specifications for API documentation:

`bash
@doeixd/gen generate --targets=openapi
`

Features:
- Complete OpenAPI 3.0 spec
- Automatic schema generation
- Authentication support
- Pagination metadata
- Interactive API docs (with Swagger UI)

$3

Generate comprehensive test suites:

`bash
@doeixd/gen generate --targets=tests
`

Generates:
- Unit tests (service layer)
- Integration tests (API endpoints)
- E2E tests (Playwright)
- Test data factories (Faker.js)
- Mock utilities

$3

Generate deployment configurations for various platforms:

`bash
@doeixd/gen generate --targets=deployment
`

Generates:
- Docker Compose files
- Dockerfiles
- CI/CD pipelines (GitHub Actions)
- Environment configurations
- Nginx configurations
- Kubernetes manifests

🔌 Plugin System

Gen supports a powerful plugin architecture that allows you to extend functionality with custom generators, commands, and integrations.

$3

`bash


Install a plugin

@doeixd/gen plugin install @doeixd/gen-plugin-react

Install globally

@doeixd/gen plugin install --global @doeixd/gen-plugin-database

List installed plugins

@doeixd/gen plugin list
`

$3

`bash


Create a new plugin

@doeixd/gen plugin create my-plugin --template=generator

Create a command plugin

@doeixd/gen plugin create my-command --template=command
`

$3

`typescript
// plugin/index.ts
export default {
name: 'my-plugin',
version: '1.0.0',
generators: {
myGenerator: async (args) => {
// Custom generation logic
}
},
commands: {
myCommand: createCommand('my-command')
.description('My custom command')
.action(() => {
// Command logic
})
}
}
`

🖥️ CLI Usage

$3

`bash
@doeixd/gen init [project-name] # Initialize a new project
@doeixd/gen generate [targets...] # Generate code from entities
@doeixd/gen plugin # Manage plugins
@doeixd/gen config # Manage configuration
@doeixd/gen --help # Show help
@doeixd/gen --version # Show version
`

$3

`bash


Initialize a new project

@doeixd/gen init my-project
@doeixd/gen init --template=convex

Generate all targets

@doeixd/gen generate

Generate specific targets

@doeixd/gen generate --targets=database,api,frontend

Generate Convex-specific code

@doeixd/gen generate --targets=convex,crud,forms

Generate Rails-style routes

@doeixd/gen generate --targets=rails

Generate Next.js API routes

@doeixd/gen generate --targets=nextjs

Generate OpenAPI documentation

@doeixd/gen generate --targets=openapi

Generate deployment configs

@doeixd/gen generate --targets=deployment

Dry run (preview changes)

@doeixd/gen generate --dry-run

Backup existing files

@doeixd/gen generate --backup

Incremental generation (skip existing)

@doeixd/gen generate --incremental

Verbose logging

@doeixd/gen --verbose
`

$3

`bash


Database targets

@doeixd/gen --targets=drizzle,prisma,sql,convex

API targets

@doeixd/gen --targets=express,fastify,hono,koa

Frontend targets

@doeixd/gen --targets=react,vue,svelte

New comprehensive targets

@doeixd/gen --targets=crud # Complete CRUD routes with TanStack Router
@doeixd/gen --targets=convex # Convex functions (queries & mutations)
@doeixd/gen --targets=forms # TanStack Form components
`

$3

`bash


Use custom config file

@doeixd/gen --config=./my-config.js

Use custom generator script

@doeixd/gen --generatorScript=./custom-generators.js

Specify output paths

@doeixd/gen --output=./generated

Generate only specific tables

@doeixd/gen --tables=users,products

Force overwrite without prompts

@doeixd/gen --force
`

$3

`bash


API-specific options

@doeixd/gen --api-framework=express --api-base-path=/api/v2 --include-openapi

Database-specific options

@doeixd/gen --db-targets=drizzle,prisma --include-migrations

Frontend-specific options

@doeixd/gen --frontend-framework=react --include-forms --include-tables

Testing options

@doeixd/gen --include-unit-tests --include-integration-tests --test-framework=vitest
`

⚙️ Configuration

$3

Create custom generator scripts to extend or replace built-in generators:

`javascript
// custom-generators.js
export async function generateDatabase(entities, config) {
// Your custom database generation logic
return ok(undefined)
}

export async function generateAPI(entities, config) {
// Your custom API generation logic
return ok(undefined)
}

export async function generateFrontend(entities, config) {
// Your custom frontend generation logic
return ok(undefined)
}
`

$3

Customize field behavior with smart defaults and overrides:

`typescript
// field-mappings.config.ts
export const fieldNamePatterns = {
email: {
inputComponent: 'EmailField',
validation: validators.email,
},
price: {
inputComponent: 'CurrencyField',
validation: validators.numberMin(0),
},
}

export const tableFieldOverrides = {
products: {
description: {
inputComponent: 'RichTextEditor',
displayComponent: 'MarkdownViewer',
},
},
}
`

📚 API Reference

$3

`typescript
import {
// Entity creation
createEntity,
createRelationship,

// Component system
ComponentRegistry,

// Database types
dbTypes,

// Validators
validators,
createValidator,

// Permission system
PermissionEngine,

// Mutation system
MutatorFactory,

// Utilities
resolveFieldConfig,
entityToTypeScript,
entityToJsonSchema,
} from 'gen'
`

$3

- Entity - Complete entity definition
- FieldMapping - Field configuration with components and validation
- PermissionConfig - Permission rules and checks
- EntityMutator - Mutation functions with audit trail
- DbColumnType - Database column type abstraction

💡 Examples

$3

`typescript
import { createEntity, dbTypes, validators } from 'gen'

export const productEntity = createEntity({
id: 'product',
name: { singular: 'Product', plural: 'Products' },
db: {
table: { name: 'products', primaryKey: ['id'] },
columns: {
id: dbTypes.id(),
name: dbTypes.string(255),
description: dbTypes.text(),
price: dbTypes.decimal(10, 2),
category: dbTypes.string(100),
inStock: dbTypes.boolean(),
createdAt: dbTypes.timestamp(),
}
},
fields: {
name: { standardSchema: validators.stringMin(1) },
description: { standardSchema: validators.stringMin(10) },
price: { standardSchema: validators.numberMin(0) },
category: { standardSchema: validators.stringMin(1) },
inStock: { standardSchema: validators.boolean },
},
relationships: [{
name: 'category',
localEntity: 'product',
foreignEntity: 'category',
relationType: 'many-to-one',
db: {
foreignKey: {
localColumn: 'categoryId',
foreignColumn: 'id',
}
}
}],
permissions: {
create: { roles: ['admin', 'manager'] },
update: { roles: ['admin'], ownership: { field: 'createdBy' } },
delete: { roles: ['admin'] },
}
})
`

$3

`typescript
export const userEntity = createEntity({
id: 'user',
name: { singular: 'User', plural: 'Users' },
db: {
table: { name: 'users', primaryKey: ['id'] },
columns: {
id: dbTypes.id(),
email: dbTypes.string(255).unique(),
name: dbTypes.string(100),
role: dbTypes.enum(['user', 'admin', 'superadmin']),
organizationId: dbTypes.uuid(),
createdAt: dbTypes.timestamp(),
}
},
fields: {
email: { standardSchema: validators.email },
name: { standardSchema: validators.stringMin(1) },
role: { standardSchema: validators.enum(['user', 'admin', 'superadmin']) },
},
permissions: {
read: { organization: { field: 'organizationId' } },
update: { ownership: { field: 'id' } },
delete: { roles: ['superadmin'] },
},
mutators: {
changeRole: {
inputSchema: validators.object({
userId: validators.string,
newRole: validators.enum(['user', 'admin', 'superadmin'])
}),
permissions: { roles: ['admin'] },
execute: async ({ userId, newRole }) => {
// Custom mutation logic with audit trail
}
}
}
})
`

🤝 Contributing

$3

`bash


Clone the repository

git clone https://github.com/doeixd/gen.git
cd gen

Install dependencies

npm install

Build the project

npm run build

Run tests

npm test

Development mode

npm run dev
`

$3

`
src/
├── cli/ # Command-line interface
├── generators/ # Code generation logic
│ ├── database.ts # Database schema generation
│ ├── api.ts # API route generation
│ └── frontend.ts # Frontend component generation
├── components.ts # Component registry system
├── database.ts # Database type abstractions
├── entity.ts # Core Entity type definition
├── permissions.ts # Permission system
├── mutations.ts # Mutation system with audit trail
├── validators.ts # StandardSchema validators
└── utils/ # Utility functions
`

$3

1. Database Targets: Add new database support in src/database.ts
2. UI Frameworks: Extend component registry in src/components.ts
3. Generators: Create new generators in src/generators/
4. Validators: Add new validators in src/validators.ts

$3

`bash


Run all tests

npm test

Run specific test file

npm test -- src/entity.test.ts

Type checking

npm run type-check

Build verification

npm run build
``

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Built with ❤️ using TypeScript, Zod for validation, and Neverthrow for error handling.

---

Gen - Define once, generate everywhere. Simplify full-stack development with type-safe, maintainable code generation.