@venizia/ignis-docs 0.0.2 → 0.0.4-0

package/wiki/references/base/controllers.md

@@ -1,3 +1,9 @@
+---
+title: Controllers Reference
+description: Technical reference for controller classes and API endpoints
+difficulty: beginner
+---
+
 # Deep Dive: Controllers
 
 Technical reference for controller classes - the foundation for creating API endpoints in Ignis.
@@ -86,8 +92,8 @@ For convenience, `Ignis` provides decorator shortcuts for each HTTP method: Thes
 import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext, HTTP } from '@venizia/ignis';
 
 // Define route configs as const for full type inference
-const USER_ROUTES = {
-  listUsers: {
+const UserRoutes = {
+  LIST_USERS: {
     path: '/',
     method: 'get',
     responses: jsonResponse({
@@ -95,7 +101,7 @@ const USER_ROUTES = {
       schema: z.array(z.object({ id: z.string(), name: z.string() })),
     }),
   },
-  getUser: {
+  GET_USER: {
     path: '/:id',
     method: 'get',
     request: {
@@ -106,7 +112,7 @@ const USER_ROUTES = {
       schema: z.object({ id: z.string(), name: z.string() }),
     }),
   },
-  createUser: {
+  CREATE_USER: {
     path: '/',
     method: 'post',
     authStrategies: [Authentication.STRATEGY_JWT], // Secure this endpoint
@@ -123,26 +129,26 @@ const USER_ROUTES = {
 
 // ... inside a controller class
 
-  @get({ configs: USER_ROUTES.listUsers })
-  getAllUsers(c: TRouteContext<typeof USER_ROUTES.listUsers>) { // Return type is automatically inferred
+  @get({ configs: UserRoutes.LIST_USERS })
+  getAllUsers(c: TRouteContext<typeof UserRoutes.LIST_USERS>) { // Return type is automatically inferred
     return c.json([{ id: '1', name: 'John Doe' }], HTTP.ResultCodes.RS_2.Ok);
   }
 
-  @get({ configs: USER_ROUTES.getUser })
-  getUserById(c: TRouteContext<typeof USER_ROUTES.getUser>) { // Return type is automatically inferred
+  @get({ configs: UserRoutes.GET_USER })
+  getUserById(c: TRouteContext<typeof UserRoutes.GET_USER>) { // Return type is automatically inferred
     const { id } = c.req.valid('param'); // id is typed as string
     return c.json({ id, name: 'John Doe' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
-  @post({ configs: USER_ROUTES.createUser })
-  createUser(c: TRouteContext<typeof USER_ROUTES.createUser>) { // Return type is automatically inferred
+  @post({ configs: UserRoutes.CREATE_USER })
+  createUser(c: TRouteContext<typeof UserRoutes.CREATE_USER>) { // Return type is automatically inferred
     const { name } = c.req.valid('json'); // name is typed as string
     const newUser = { id: '2', name };
     return c.json(newUser, HTTP.ResultCodes.RS_2.Created); // Return type is validated
   }
 ```
 
-**Example using shared `ROUTE_CONFIGS`:**
+**Example using shared `RouteConfigs`:**
 
 For better organization, you can define all your route configurations in a constant and reference them in your decorators. This approach also allows you to get a typed context for your handler.
 
@@ -150,8 +156,8 @@ For better organization, you can define all your route configurations in a const
 import { api, BaseController, controller, TRouteContext, jsonContent, jsonResponse, HTTP } from '@venizia/ignis';
 import { z } from 'hono/zod-openapi';
 
-const HEALTH_CHECK_ROUTES = {
-  '/ping': {
+const RouteConfigs = {
+  PING: {
     method: HTTP.Methods.POST,
     path: '/ping',
     request: {
@@ -167,9 +173,9 @@ const HEALTH_CHECK_ROUTES = {
 
 @controller({ path: '/health' })
 export class HealthCheckController extends BaseController {
-  
-  @api({ configs: HEALTH_CHECK_ROUTES['/ping'] })
-  ping(c: TRouteContext<typeof HEALTH_CHECK_ROUTES['/ping']>) { // Return type is automatically inferred
+
+  @api({ configs: RouteConfigs.PING })
+  ping(c: TRouteContext<typeof RouteConfigs.PING>) { // Return type is automatically inferred
     const { message } = c.req.valid('json');
     return c.json({ pong: message }, HTTP.ResultCodes.RS_2.Ok);
   }
@@ -258,17 +264,17 @@ request: {
 The `defineRouteConfigs` function is a simple helper for creating a typed object containing multiple route configurations. This is particularly useful for organizing all of a controller's route definitions in a single, type-checked constant.
 
 ```typescript
-import { defineRouteConfigs, HTTP, jsonResponse, z } from '@venizia/ignis';
+import { defineRouteConfigs, HTTP, jsonResponse, jsonContent, z } from '@venizia/ignis';
 
-const ROUTE_CONFIGS = defineRouteConfigs({
-  '/': {
+const RouteConfigs = defineRouteConfigs({
+  ROOT: {
     method: HTTP.Methods.GET,
     path: '/',
     responses: jsonResponse({
       schema: z.object({ status: z.string() }),
     }),
   },
-  '/ping': {
+  PING: {
     method: HTTP.Methods.POST,
     path: '/ping',
     request: {
@@ -318,27 +324,94 @@ This factory method returns a `BaseController` class that is already set up with
 | `controller.readonly` | `boolean` | If `true`, only read operations (find, findOne, findById, count) are generated. Write operations are excluded. Defaults to `false`. |
 | `controller.isStrict` | `boolean` | If `true`, query parameters like `where` will be strictly validated. Defaults to `true`. |
 | `controller.defaultLimit`| `number` | The default limit for `find` operations. Defaults to `10`. |
-| `schema` | `object` | An optional object to override the default Zod schemas for specific CRUD endpoints. See schema options below. |
-| `doDeleteWithReturn` | `boolean` | If `true`, the `deleteById` and `deleteBy` endpoints will return the deleted record(s) in the response body. Defaults to `false`. |
+| `authStrategies` | `Array<TAuthStrategy>` | Auth strategies applied to all routes (unless overridden per-route). |
+| `routes` | `TRoutesConfig` | Per-route configuration combining schema and auth. See routes configuration below. |
 
-### Schema Override Options
+### Routes Configuration
 
-The `schema` option allows fine-grained control over request/response validation and OpenAPI documentation:
+The `routes` option provides a unified way to configure both schema overrides and authentication for each endpoint:
 
-| Schema Option | Description |
-| :--- | :--- |
-| `count` | Override response schema for count endpoint |
-| `find` | Override response schema for find endpoint |
-| `findOne` | Override response schema for findOne endpoint |
-| `findById` | Override response schema for findById endpoint |
-| `create` | Override response schema for create endpoint |
-| `createRequestBody` | Override request body schema for create endpoint |
-| `updateById` | Override response schema for updateById endpoint |
-| `updateByIdRequestBody` | Override request body schema for updateById endpoint |
-| `updateBy` | Override response schema for updateBy (bulk update) endpoint |
-| `updateByRequestBody` | Override request body schema for updateBy endpoint |
-| `deleteById` | Override response schema for deleteById endpoint |
-| `deleteBy` | Override response schema for deleteBy (bulk delete) endpoint |
+```typescript
+type TRouteAuthConfig =
+  | { skipAuth: true }
+  | { skipAuth?: false; authStrategies: Array<TAuthStrategy> };
+
+type TReadRouteConfig = TRouteAuthConfig & { schema?: z.ZodObject };
+type TWriteRouteConfig = TReadRouteConfig & { requestBody?: z.ZodObject };
+type TDeleteRouteConfig = TRouteAuthConfig & { schema?: z.ZodObject };
+```
+
+| Route | Type | Description |
+| :--- | :--- | :--- |
+| `count` | `TReadRouteConfig` | Config for count endpoint |
+| `find` | `TReadRouteConfig` | Config for find endpoint |
+| `findOne` | `TReadRouteConfig` | Config for findOne endpoint |
+| `findById` | `TReadRouteConfig` | Config for findById endpoint |
+| `create` | `TWriteRouteConfig` | Config for create endpoint (supports `requestBody`) |
+| `updateById` | `TWriteRouteConfig` | Config for updateById endpoint (supports `requestBody`) |
+| `updateBy` | `TWriteRouteConfig` | Config for updateBy endpoint (supports `requestBody`) |
+| `deleteById` | `TDeleteRouteConfig` | Config for deleteById endpoint |
+| `deleteBy` | `TDeleteRouteConfig` | Config for deleteBy endpoint |
+
+### Auth Resolution Priority
+
+When resolving authentication for a route, the following priority applies:
+
+1. **Endpoint `skipAuth: true`** → No auth (ignores controller `authStrategies`)
+2. **Endpoint `authStrategies`** → Override controller (empty array = no auth)
+3. **Controller `authStrategies`** → Default fallback
+
+### Authentication Examples
+
+```typescript
+// 1. JWT auth on ALL routes
+const UserController = ControllerFactory.defineCrudController({
+  entity: UserEntity,
+  repository: { name: 'UserRepository' },
+  controller: { name: 'UserController', basePath: '/users' },
+  authStrategies: ['jwt'],
+});
+
+// 2. JWT auth on all, but skip for public read endpoints
+const ProductController = ControllerFactory.defineCrudController({
+  entity: ProductEntity,
+  repository: { name: 'ProductRepository' },
+  controller: { name: 'ProductController', basePath: '/products' },
+  authStrategies: ['jwt'],
+  routes: {
+    find: { skipAuth: true },
+    findById: { skipAuth: true },
+    count: { skipAuth: true },
+  },
+});
+
+// 3. No controller auth, require JWT only for write operations
+const ArticleController = ControllerFactory.defineCrudController({
+  entity: ArticleEntity,
+  repository: { name: 'ArticleRepository' },
+  controller: { name: 'ArticleController', basePath: '/articles' },
+  routes: {
+    create: { authStrategies: ['jwt'] },
+    updateById: { authStrategies: ['jwt'] },
+    deleteById: { authStrategies: ['jwt'] },
+  },
+});
+
+// 4. Custom schema with auth configuration
+const OrderController = ControllerFactory.defineCrudController({
+  entity: OrderEntity,
+  repository: { name: 'OrderRepository' },
+  controller: { name: 'OrderController', basePath: '/orders' },
+  authStrategies: ['jwt'],
+  routes: {
+    find: { schema: CustomOrderListSchema, skipAuth: true },
+    create: {
+      schema: CustomOrderResponseSchema,
+      requestBody: CustomOrderCreateSchema,
+    },
+  },
+});
+```
 
 ### Example
 
@@ -385,3 +458,28 @@ export class ConfigurationController extends _ConfigurationController {
 ```
 
 By leveraging these structured configuration options and the `ControllerFactory`, you ensure that your API is not only functional but also well-documented, easy to validate, and rapidly deployable for standard CRUD operations.
+
+---
+
+## See Also
+
+- **Related References:**
+  - [Services](./services.md) - Business logic layer called by controllers
+  - [Repositories](./repositories/) - Data access layer for CRUD operations
+  - [Middlewares](./middlewares.md) - Request/response middleware
+  - [Application](./application.md) - Application setup and controller mounting
+  - [Dependency Injection](./dependency-injection.md) - DI patterns and injection
+
+- **Guides:**
+  - [Building Your First API](/guides/getting-started/first-api.md)
+  - [Controllers Guide](/guides/core-concepts/controllers.md)
+  - [Routing and Decorators](/guides/core-concepts/routing.md)
+
+- **Best Practices:**
+  - [API Design Patterns](/best-practices/architecture/api-design.md)
+  - [Error Handling](/best-practices/architecture/error-handling.md)
+  - [Request Validation](/best-practices/security/input-validation.md)
+
+- **External Resources:**
+  - [OpenAPI Specification](https://swagger.io/specification/)
+  - [HTTP Methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods)

package/wiki/references/base/datasources.md

@@ -1,3 +1,9 @@
+---
+title: DataSources Reference
+description: Technical reference for DataSource classes and database connections
+difficulty: intermediate
+---
+
 # Deep Dive: DataSources
 
 Technical reference for DataSource classes - managing database connections in Ignis.
@@ -8,15 +14,17 @@ Technical reference for DataSource classes - managing database connections in Ig
 
 | Class/Interface | Purpose | Key Members |
 |-----------------|---------|-------------|
-| **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `getSchema()`, `configure()` |
+| **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `getSchema()`, `configure()`, `beginTransaction()` |
 | **AbstractDataSource** | Base implementation with logging | Extends `BaseHelper` |
-| **BaseDataSource** | Concrete class to extend | Auto-discovery, driver from decorator |
+| **BaseDataSource** | Concrete class to extend | Auto-discovery, driver from decorator, transaction support |
+| **ITransaction** | Transaction object | `connector`, `isActive`, `commit()`, `rollback()` |
+| **IsolationLevels** | Isolation level constants | `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE` |
 
 ## `IDataSource` Interface
 
 Contract for all datasource classes in the framework.
 
-**File:** `packages/core/src/base/datasources/types.ts`
+**File:** `packages/core/src/base/datasources/common/types.ts`
 
 ### Properties & Methods
 
@@ -24,10 +32,14 @@ Contract for all datasource classes in the framework.
 |--------|------|-------------|
 | `name` | `string` | Datasource name |
 | `settings` | `object` | Configuration object |
-| `connector` | `TDatabaseConnector` | Database connector instance (e.g., Drizzle) |
-| `getSchema()` | Method | Returns combined Drizzle schema (auto-discovered or manual) |
+| `connector` | `TNodePostgresConnector` | Database connector instance (Drizzle) |
+| `schema` | `Schema` | Combined Drizzle schema (auto-discovered or manual) |
+| `getSchema()` | Method | Returns combined Drizzle schema |
+| `getSettings()` | Method | Returns connection settings |
+| `getConnector()` | Method | Returns the Drizzle connector |
 | `configure()` | Method | Initializes the `connector` |
 | `getConnectionString()` | Method | Returns connection string |
+| `beginTransaction(opts?)` | Method | Starts a new database transaction |
 
 ## `AbstractDataSource` & `BaseDataSource`
 
@@ -264,4 +276,95 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
 | `getConnector()` | Returns the Drizzle connector |
 | `hasDiscoverableModels()` | Returns `true` if there are models registered for this datasource |
 
+## Transaction Support
+
+DataSources provide built-in transaction management through the `beginTransaction()` method. This allows you to perform atomic operations across multiple repositories.
+
+### Transaction Types
+
+**File:** `packages/core/src/base/datasources/common/types.ts`
+
+| Type | Description |
+|------|-------------|
+| `ITransaction<Schema>` | Transaction object with `commit()`, `rollback()`, and `connector` |
+| `ITransactionOptions` | Options for starting a transaction (e.g., `isolationLevel`) |
+| `TIsolationLevel` | Union type: `'READ COMMITTED'` \| `'REPEATABLE READ'` \| `'SERIALIZABLE'` |
+| `IsolationLevels` | Static class with isolation level constants and validation |
+
+### ITransaction Interface
+
+```typescript
+interface ITransaction<Schema> {
+  connector: TNodePostgresTransactionConnector<Schema>;
+  isActive: boolean;
+  isolationLevel: TIsolationLevel;
+
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+```
+
+### Isolation Levels
+
+Use the `IsolationLevels` static class for type-safe isolation level constants:
+
+```typescript
+import { IsolationLevels } from '@venizia/ignis';
+
+// Available levels
+IsolationLevels.READ_COMMITTED   // Default - prevents dirty reads
+IsolationLevels.REPEATABLE_READ  // Consistent reads within transaction
+IsolationLevels.SERIALIZABLE     // Strictest isolation
+
+// Validation
+IsolationLevels.isValid('READ COMMITTED'); // true
+IsolationLevels.isValid('INVALID');        // false
+```
+
+### Usage Example
+
+```typescript
+// Start transaction from datasource or repository
+const tx = await dataSource.beginTransaction({
+  isolationLevel: IsolationLevels.SERIALIZABLE
+});
+
+try {
+  // Use tx.connector for operations
+  await tx.connector.insert(userTable).values({ name: 'Alice' });
+  await tx.connector.insert(profileTable).values({ userId: '...', bio: 'Hello' });
+
+  await tx.commit();
+} catch (error) {
+  await tx.rollback();
+  throw error;
+}
+```
+
+> **Note:** For most use cases, prefer using `repository.beginTransaction()` which provides a higher-level API. See [Repositories Reference](./repositories.md#transactions) for details.
+
 This architecture ensures that datasources are configured consistently and that the fully-initialized Drizzle connector, aware of all schemas and relations, is available to repositories for querying.
+
+## See Also
+
+- **Related Concepts:**
+  - [DataSources Guide](/guides/core-concepts/persistent/datasources) - Creating DataSources tutorial
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Using DataSources for database access
+  - [Models](/guides/core-concepts/persistent/models) - Entity schemas loaded by DataSource
+  - [Transactions](/guides/core-concepts/persistent/transactions) - Multi-operation database transactions
+
+- **References:**
+  - [Repositories API](/references/base/repositories/) - Data access layer
+  - [Environment Variables](/references/configuration/environment-variables) - Configuration management
+
+- **External Resources:**
+  - [Drizzle ORM Documentation](https://orm.drizzle.team/) - ORM configuration
+  - [node-postgres Documentation](https://node-postgres.com/) - Connection pooling guide
+
+- **Best Practices:**
+  - [Performance Optimization](/best-practices/performance-optimization) - Connection pool tuning
+  - [Security Guidelines](/best-practices/security-guidelines) - Database credential management
+
+- **Tutorials:**
+  - [Complete Installation](/guides/tutorials/complete-installation) - Database setup
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - DataSource configuration

package/wiki/references/base/dependency-injection.md

@@ -1,3 +1,9 @@
+---
+title: Dependency Injection Reference
+description: Technical reference for the DI system in IGNIS
+difficulty: advanced
+---
+
 # Deep Dive: Dependency Injection
 
 Technical reference for the DI system in Ignis - managing resource lifecycles and dependency resolution.
@@ -18,6 +24,15 @@ Technical reference for the DI system in Ignis - managing resource lifecycles an
 | **MetadataRegistry** | Stores decorator metadata | Singleton accessed via `getInstance()` |
 | **Boot System** | Automatic artifact discovery and binding | Integrates with Container via tags and bindings |
 
+## Prerequisites
+
+Before reading this document, you should understand:
+
+- [TypeScript Decorators](https://www.typescriptlang.org/docs/handbook/decorators.html) - How decorators work in TypeScript
+- [IGNIS Application basics](./application.md) - Application lifecycle and initialization
+- [Services](./services.md) and [Controllers](./controllers.md) - Basic understanding of IGNIS architecture
+- Inversion of Control (IoC) pattern - [Martin Fowler's article](https://martinfowler.com/articles/injection.html)
+
 ## `Container` Class
 
 Heart of the DI system - registry managing all application resources.
@@ -161,8 +176,8 @@ app.bind({ key: 'controllers.UserController' }).toClass(UserController);
 @injectable()
 class UserController {
   constructor(
-    @inject({ key: 'services.UserService' }) 
-    private userService: UserService  // Auto-injected!
+    @inject({ key: 'services.UserService' })
+    private _userService: UserService  // Auto-injected!
   ) {}
 }
 ```
@@ -174,4 +189,25 @@ class UserController {
 - **Extensible**: Custom booters integrate seamlessly via tags
 - **Type-safe**: Full TypeScript support throughout boot process
 
-> **Learn More:** See [Bootstrapping Concepts](/get-started/core-concepts/bootstrapping.md) and [Boot Package Reference](/references/src-details/boot.md)
+> **Learn More:** See [Bootstrapping Concepts](/guides/core-concepts/application/bootstrapping) and [Boot Package Reference](/references/src-details/boot.md)
+
+## See Also
+
+- **Related Concepts:**
+  - [Dependency Injection Guide](/guides/core-concepts/dependency-injection) - DI fundamentals tutorial
+  - [Application](/guides/core-concepts/application/) - Application extends Container
+  - [Controllers](/guides/core-concepts/controllers) - Use DI for injecting services
+  - [Services](/guides/core-concepts/services) - Use DI for injecting repositories
+  - [Providers](/references/base/providers) - Factory pattern for dynamic injection
+
+- **References:**
+  - [Inversion Helper](/references/helpers/inversion) - DI container utilities
+  - [Bootstrapping API](/references/base/bootstrapping) - Auto-discovery and DI
+  - [Glossary](/guides/reference/glossary#dependency-injection-di) - DI concepts explained
+
+- **Tutorials:**
+  - [Testing](/guides/tutorials/testing) - Unit testing with mocked dependencies
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - DI in practice
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns) - DI patterns and anti-patterns