Quick Generate Operator

Quick Generate Operator is a command that rapidly creates operator implementations for your application, including CRUD handlers, middleware functions, service layer methods, and the associated boilerplate code required to wire them into your existing architecture. It analyzes your project's conventions, detects patterns in existing operators, and produces new ones that match the established coding style. The command is optimized for speed, generating complete, functional operator code in seconds rather than requiring manual scaffolding.

When to Use This Command

Run this command when...

• You need to add a new resource or entity to your application and want all the standard operator functions (create, read, update, delete, list) generated at once.
• Your project follows a consistent pattern for service layer methods and you want to replicate that pattern for a new domain object without writing boilerplate manually.
• You are building an API and need controller, service, and route operator stubs generated from a data model definition.
• A new feature requires middleware operators such as authentication checks, rate limiters, or validation handlers, and you want them scaffolded to match existing patterns.
• You want to quickly prototype operator logic that can be refined later, getting a working implementation into the codebase fast.

Consider alternatives when...

• You need to implement a complex operator with non-standard logic that does not follow existing patterns; manual implementation gives you more control over the design.
• The operator requires deep integration with external systems that need careful error handling and retry logic beyond what scaffolding can provide.
• Your project does not have established operator patterns for the generator to follow, meaning the output would be arbitrary rather than convention-aligned.

Quick Start

Copy
# operator-gen.config.yml
project_type: express_api        # express_api | nestjs | fastify | generic
convention_source: src/services/ # directory to scan for existing patterns
output:
  controller: src/controllers/
  service: src/services/
  routes: src/routes/
  types: src/types/
naming:
  style: camelCase
  suffix: Controller             # appended to controller class names

Example invocation:

Copy
quick-generate-operator "Product with fields: name, price, category, inStock"

Example output:

Operator Generation Complete
------------------------------
Entity:    Product
Pattern:   Matched against existing UserController/UserService

Files Created:
  src/types/product.ts            - Product interface and DTOs
  src/services/productService.ts  - CRUD service methods
  src/controllers/productController.ts - Request handlers
  src/routes/product.ts           - Express route definitions

Operations Generated:
  createProduct()     - Validation + service call + 201 response
  getProduct()        - ID lookup + 404 handling + 200 response
  listProducts()      - Pagination + filtering + 200 response
  updateProduct()     - Partial update + 404 handling + 200 response
  deleteProduct()     - Soft delete + 404 handling + 204 response

Middleware Applied:
  authMiddleware      - Applied to all routes (matched from existing)
  validateBody        - Applied to create/update routes

Next: Register routes in src/app.ts

Core Concepts

Concept	Purpose	Details
Operator	A function that performs a specific operation on a resource	Any handler, service method, or middleware function that encapsulates a discrete unit of business or infrastructure logic
Convention Detection	Matches existing codebase patterns automatically	Scans existing operator files to learn naming conventions, file organization, error handling patterns, and response formatting
Scaffold Template	Provides the structural skeleton for generated code	A parameterized code template that gets populated with entity-specific names, types, and validation rules
Layer Separation	Generates code across architectural boundaries	Produces matching files in controller, service, route, and type layers to maintain proper separation of concerns
Wiring Integration	Connects generated code to the application entry point	Identifies where new routes or services need to be registered and provides the exact import and registration code needed

          Quick Generate Operator Architecture
  +--------------------------------------------------------+
  |  INPUT SPECIFICATION                                   |
  |  Entity Name + Fields --> Parse Schema --> Validate     |
  +--------------------------------------------------------+
           |
           v
  +--------------------------------------------------------+
  |  CONVENTION SCANNER                                    |
  |  Read Existing Files --> Extract Patterns               |
  |  [naming] [structure] [error handling] [middleware]      |
  +--------------------------------------------------------+
           |
           v
  +--------------------------------------------------------+
  |  CODE GENERATOR                                        |
  |  Types --> Service --> Controller --> Routes             |
  |  Apply Patterns --> Format --> Write Files               |
  +--------------------------------------------------------+
           |
           v
  +--------------------------------------------------------+
  |  INTEGRATION GUIDE                                     |
  |  Import Statements --> Registration Code --> Next Steps  |
  +--------------------------------------------------------+

Configuration

Parameter	Type	Default	Description
project_type	string	auto-detect	Application framework pattern to follow: express_api, nestjs, fastify, or generic
convention_source	string	src/	Directory to scan for existing operator files to learn patterns and conventions from
operations	array	[create, read, update, delete, list]	Which CRUD operations to generate; omit any that are not needed for this entity
middleware	array	auto-detect	Middleware functions to apply to generated routes, auto-detected from existing route files
soft_delete	boolean	true	Whether delete operations use soft delete (marking records inactive) or hard delete (permanent removal)

Best Practices

1. Ensure your existing codebase has at least two consistent operator implementations before using convention detection. The generator learns patterns by comparing multiple existing files. With only one reference file, it cannot distinguish intentional patterns from incidental choices. Having two or more consistent implementations gives the scanner enough data to reliably extract conventions for naming, error handling, and response formatting.

2. Review generated validation logic against your actual business rules. The generator creates basic type validation (string, number, required/optional) from field definitions, but it cannot infer domain-specific constraints like "price must be positive" or "category must exist in the categories table." Add these business validations after generation to ensure the operator rejects invalid data appropriately.

3. Use the generated types as a contract between layers. The type definitions created for your entity serve as an interface contract between the controller, service, and data access layers. Resist the temptation to use any types or inline object shapes. When the entity evolves, update the type definitions first and let TypeScript's type checker guide the necessary changes across all layers.

4. Test generated operators with the test generation command for maximum efficiency. After generating operators, run the test generation command against the new files to quickly produce a matching test suite. This combination of commands produces fully tested, convention-aligned code in minutes rather than hours, making it ideal for rapid prototyping and feature development.

5. Keep generated boilerplate and custom business logic in separate sections. When adding custom logic to generated operator files, place it in clearly marked sections below the generated code. This makes it easy to regenerate the boilerplate later (when conventions change) without losing your custom additions. Some teams use comment markers like // CUSTOM LOGIC START to delineate the boundary.

Common Issues

Generated code does not compile because of missing imports. The generator resolves imports based on the project's existing import patterns, but if your project uses path aliases, barrel exports, or unconventional module resolution, the generated imports may not resolve. Check your tsconfig.json paths configuration and update the generated imports to match. Adding your path alias configuration to the operator config prevents this on future runs.

Generated middleware does not match the project's authentication setup. The convention scanner detects middleware by scanning existing route files, but custom authentication setups (OAuth, JWT with refresh tokens, API keys) may use patterns the scanner does not recognize. Manually specify the correct middleware functions in the configuration if auto-detection applies the wrong ones or misses them entirely.

Generated service methods assume a specific database or ORM that the project does not use. If the generator detects Prisma patterns in your codebase but you have recently migrated to Drizzle or raw SQL, the generated data access code will be incorrect. Update the convention source to point at recently updated files that reflect the current technology stack, ensuring the generator learns from current patterns rather than legacy ones.