igniter-patterns

Igniter.js Controller & API Development Standards (Optimized for LLMs)

This guide provides a COMPLETE, ACCURATE, and MANDATORY reference for creating controllers and actions in Igniter.js. It incorporates established architectural patterns, coding best practices, and lessons learned from real-world implementations, ensuring strict adherence for all future development.

🚨 CRITICAL ARCHITECTURAL PRINCIPLES

1. Separation of Concerns (SoC)

• Controllers: Responsible only for handling HTTP requests, validating input, orchestrating business logic (via procedures/repositories), and constructing HTTP responses.
• Procedures: Responsible for extending the request context, injecting dependencies (like repositories), handling cross-cutting concerns (e.g., authentication, logging), and pre-processing requests.
• Repositories: Responsible only for direct data access operations (e.g., Prisma calls). They abstract the database layer from the business logic.
• Interfaces: Centralize all shared definitions (constants, Zod schemas, types, interfaces) for a given feature.

2. Type Safety & Documentation First

• End-to-End Type Safety: Leverage TypeScript and Zod to ensure type consistency from request body to database operations.
• Comprehensive TSDoc: All exposed components (controllers, actions, procedures, repositories, interfaces, schemas, types, constants) MUST be fully documented with TSDoc in English.

3. Immutability & Context Extension

• Context is Extended, Not Mutated: Procedures extend the Igniter context by returning an object, which is then shallow-merged. Direct mutation of the context object in procedures is forbidden.
• Special Case: next() for Post-Action Processing: The next() function in a procedure's handler should only be used if the procedure needs to capture and process the result of the subsequent action (e.g., for auditing, performance monitoring, or response modification). In such cases, await next() should be called, and the result should then be handled. Otherwise, procedures should either return an object to extend the context (e.g., { auth: { session: { user } } }) or void (implicitly or explicit return;) to simply allow the request to proceed without modifying the context.
• Default Behavior: Context Extension or Void Return: In all other scenarios, procedures should either return an object to extend the context (e.g., { auth: { session: { user } } }) or void (implicitly or explicitly return;) to simply allow the request to proceed without modifying the context.
• Auth Procedure Context for Optional Authentication: When an authProcedure is configured with required: false (or if authentication fails but is not strictly required), it MUST explicitly return an object like { auth: { session: { user: null } } } to maintain consistent context typing, indicating that no authenticated user is present.