@venizia/ignis-docs 0.0.1-1 → 0.0.1-10

package/wiki/get-started/building-a-crud-api.md

@@ -134,12 +134,10 @@ export type TTodo = TTableObject<TTodoSchema>;
 
 // 4. Create the Entity class, decorated with @model
 @model({ type: 'entity' })
-export class Todo extends BaseEntity<TTodoSchema> {
-  static readonly TABLE_NAME = 'Todo';
-
-  constructor() {
-    super({ name: Todo.TABLE_NAME, schema: todoTable });
-  }
+export class Todo extends BaseEntity<typeof Todo.schema> {
+  static override schema = todoTable;
+  static override relations = () => todoRelations.definitions;
+  static override TABLE_NAME = 'Todo';
 }
 ```
 
@@ -203,7 +201,6 @@ Create `src/datasources/postgres.datasource.ts`:
 
 ```typescript
 // src/datasources/postgres.datasource.ts
-import { Todo, todoRelations, todoTable } from '@/models/todo.model';
 import {
   BaseDataSource,
   datasource,
@@ -214,61 +211,61 @@ import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
-  connection: {
-    host?: string;
-    port?: number;
-    user?: string;
-    password?: string;
-    database?: string;
-  };
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
 }
 
-@datasource()
+/**
+ * PostgresDataSource with auto-discovery support.
+ *
+ * How it works:
+ * 1. @repository decorator binds model to datasource
+ * 2. When configure() is called, getSchema() auto-discovers all bound models
+ * 3. Drizzle is initialized with the auto-discovered schema
+ */
+@datasource({ driver: 'node-postgres' })
 export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
-      driver: 'node-postgres',
+      // Driver is read from @datasource decorator - no need to pass here!
       config: {
-        connection: {
-          host: process.env.APP_ENV_POSTGRES_HOST,
-          port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
-          user: process.env.APP_ENV_POSTGRES_USERNAME,
-          password: process.env.APP_ENV_POSTGRES_PASSWORD,
-          database: process.env.APP_ENV_POSTGRES_DATABASE,
-        },
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'todo_db',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
       },
-      // Register all your models and their relations here
-      schema: Object.assign(
-        {},
-        { [Todo.TABLE_NAME]: todoTable },
-        todoRelations.relations,
-      ),
+      // NO schema property - auto-discovered from @repository bindings!
     });
   }
 
   override configure(): ValueOrPromise<void> {
-    this.connector = drizzle({
-      client: new Pool(this.settings.connection),
-      schema: this.schema,
-    });
-  }
-
-  override async connect(): Promise<TNodePostgresConnector | undefined> {
-    await (this.connector.client as Pool).connect();
-    return this.connector;
-  }
-
-  override async disconnect(): Promise<void> {
-    await (this.connector.client as Pool).end();
+    // getSchema() auto-discovers models from @repository bindings
+    const schema = this.getSchema();
+
+    // Log discovered schema for debugging
+    const schemaKeys = Object.keys(schema);
+    this.logger.debug(
+      '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
+      schemaKeys.length,
+      schemaKeys,
+    );
+
+    const client = new Pool(this.settings);
+    this.connector = drizzle({ client, schema });
   }
 }
 ```
 
 **Key Points:**
-- Registers `todoTable` and `todoRelations` in the schema
+- Schema is auto-discovered from `@repository` decorators - no manual registration needed
+- Uses `getSchema()` for lazy schema resolution (resolves when all models are loaded)
 - Uses environment variables for connection config
-- Implements connection lifecycle methods
+- Implements connection lifecycle methods (`connect()`, `disconnect()`)
 
 > **Deep Dive:** See [DataSources Reference](../references/base/datasources.md) for advanced configuration and multiple database support.
 
@@ -280,26 +277,15 @@ Create `src/repositories/todo.repository.ts`:
 
 ```typescript
 // src/repositories/todo.repository.ts
-import { Todo, todoRelations, TTodoSchema } from '@/models/todo.model';
-import {
-  DefaultCRUDRepository,
-  IDataSource,
-  inject,
-  repository,
-} from '@venizia/ignis';
-
-@repository()
-export class TodoRepository extends DefaultCRUDRepository<TTodoSchema> {
-  constructor(
-    @inject({ key: 'datasources.PostgresDataSource' })
-    dataSource: IDataSource,
-  ) {
-    super({
-      dataSource,
-      entityClass: Todo,
-      relations: todoRelations.definitions,
-    });
-  }
+import { Todo } from '@/models/todo.model';
+import { PostgresDataSource } from '@/datasources/postgres.datasource';
+import { DefaultCRUDRepository, repository } from '@venizia/ignis';
+
+// Both 'model' and 'dataSource' are required for schema auto-discovery
+@repository({ model: Todo, dataSource: PostgresDataSource })
+export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
+  // No constructor needed! DataSource and relations are auto-resolved
+  // from the @repository decorator and entity's static properties
 }
 ```
 
@@ -358,15 +344,15 @@ export class TodoController extends _Controller {
 **Auto-generated Endpoints:**
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/todos` | List all todos |
-| GET | `/todos/:id` | Get todo by ID |
-| GET | `/todos/find-one` | Find one todo by filter |
-| GET | `/todos/count` | Count todos |
-| POST | `/todos` | Create todo |
-| PATCH | `/todos/:id` | Update todo by ID |
-| PATCH | `/todos` | Update multiple todos |
-| DELETE | `/todos/:id` | Delete todo by ID |
-| DELETE | `/todos` | Delete multiple todos |
+| GET | `/todos` | List all todos (find) |
+| GET | `/todos/:id` | Get todo by ID (findById) |
+| GET | `/todos/find-one` | Find one todo by filter (findOne) |
+| GET | `/todos/count` | Count todos (count) |
+| POST | `/todos` | Create todo (create) |
+| PATCH | `/todos/:id` | Update todo by ID (updateById) |
+| PATCH | `/todos` | Update multiple todos by filter (updateBy) |
+| DELETE | `/todos/:id` | Delete todo by ID (deleteById) |
+| DELETE | `/todos` | Delete multiple todos by filter (deleteBy) |
 
 > **Deep Dive:** See [ControllerFactory Reference](../references/base/controllers.md#controllerfactory) for customization options.
 
@@ -639,8 +625,7 @@ Now that you've built the Todo API, try building a **User** feature on your own!
 
 **Challenge checklist:**
 - [ ] Create `src/models/user.model.ts`
-- [ ] Update `PostgresDataSource` to include User schema
-- [ ] Create `src/repositories/user.repository.ts`
+- [ ] Create `src/repositories/user.repository.ts` (this auto-registers User with PostgresDataSource)
 - [ ] Create `src/controllers/user.controller.ts`
 - [ ] Register repository and controller in `application.ts`
 - [ ] Run migration: `bun run migrate:dev`
@@ -660,7 +645,7 @@ For complex validation or business rules, create a Service layer:
 
 ```typescript
 // src/services/todo.service.ts
-import { BaseService, inject } from '@venizia/ignis';
+import { BaseService, inject, getError } from '@venizia/ignis';
 import { TodoRepository } from '@/repositories/todo.repository';
 
 export class TodoService extends BaseService {
@@ -674,7 +659,7 @@ export class TodoService extends BaseService {
   async createTodo(data: any) {
     // Business logic validation
     if (data.title.length < 3) {
-      throw new Error('Title too short');
+      throw getError({ message: 'Title too short' });
     }
 
     // Check for duplicates
@@ -682,7 +667,7 @@ export class TodoService extends BaseService {
       filter: { where: { title: data.title } },
     });
     if (existing) {
-      throw new Error('Todo already exists');
+      throw getError({ message: 'Todo already exists' });
     }
 
     return this.todoRepository.create({ data });

package/wiki/get-started/core-concepts/components.md

@@ -1,6 +1,6 @@
 # Components
 
-Components are reusable, pluggable modules that encapsulate features like authentication, logging, or API documentation.
+Components are reusable, pluggable modules that encapsulate a group of related features. A component acts as a powerful container for various resources—including providers, services, controllers, repositories, and even entire mini-applications—making it easy to share and integrate complex functionality across projects.
 
 > **Deep Dive:** See [Components Reference](../../references/base/components.md) for technical details.
 
@@ -8,9 +8,11 @@ Components are reusable, pluggable modules that encapsulate features like authen
 
 A component is a class that extends `BaseComponent` and is responsible for:
 
-- **Binding Dependencies**: Registering services, controllers, providers, or other resources with the application's dependency injection container.
+- **Binding Dependencies**: Registering services, controllers, repositories, providers, or other resources with the application's dependency injection container.
 - **Configuring Features**: Setting up middlewares, initializing services, or performing any other setup required for the feature to work.
 
+A single component can bundle everything needed for a specific domain—for example, an "AuthComponent" might include multiple services for token management, repositories for user data, and controllers for login/signup endpoints, essentially functioning as a plug-and-play mini-application.
+
 `Ignis` comes with several built-in components, which you can explore in the [**Components Reference**](../../references/components/) section:
 
 - **`AuthenticateComponent`**: Sets up JWT-based authentication.

package/wiki/get-started/core-concepts/controllers.md

@@ -9,7 +9,7 @@ Controllers handle HTTP requests and return responses - they're your API endpoin
 Extend `BaseController` and use decorators to define routes:
 
 ```typescript
-import { BaseController, controller, get, jsonResponse, z } from '@venizia/ignis';
+import { BaseController, controller, get, jsonResponse, z, HTTP } from '@venizia/ignis';
 import { Context } from 'hono';
 
 @controller({ path: '/users' })
@@ -29,7 +29,7 @@ export class UserController extends BaseController {
     },
   })
   getAllUsers(c: Context) {
-    return c.json([{ id: '1', name: 'John Doe' }]);
+    return c.json([{ id: '1', name: 'John Doe' }], HTTP.ResultCodes.RS_2.Ok);
   }
 }
 ```
@@ -177,7 +177,7 @@ const GetUsersRoute = {
 this.defineRoute({
   configs: GetUsersRoute,
   handler: (c: TRouteContext<typeof GetUsersRoute>) => { // Return type is automatically inferred
-    return c.json([{ id: 1, name: 'John Doe' }]);
+    return c.json([{ id: 1, name: 'John Doe' }], HTTP.ResultCodes.RS_2.Ok);
   },
 });
 ```
@@ -187,7 +187,7 @@ this.defineRoute({
 This method offers a fluent API for defining routes, similar to `defineRoute`, but structured for chaining. It also benefits from `TRouteContext` for type safety.
 
 ```typescript
-import { jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { jsonResponse, z, TRouteContext, HTTP } from '@venizia/ignis';
 
 // ... inside the binding() method
 
@@ -205,7 +205,7 @@ this.bindRoute({
 }).to({
   handler: (c: TRouteContext<typeof GetUserByIdRoute>) => { // Return type is automatically inferred
     const { id } = c.req.param();
-    return c.json({ id: id, name: 'John Doe' });
+    return c.json({ id: id, name: 'John Doe' }, HTTP.ResultCodes.RS_2.Ok);
   },
 });
 ```
@@ -255,17 +255,17 @@ export class ConfigurationController extends _Controller {
 ```
 The `ControllerFactory.defineCrudController` method automatically sets up the following routes based on your entity schema:
 
-| Name | Method | Path | Description |
+| Route Name | Method | Path | Description |
 | :--- | :--- | :--- | :--- |
 | `count` | `GET` | `/count` | Get the number of records matching a filter. |
 | `find` | `GET` | `/` | Retrieve all records matching a filter. |
 | `findById` | `GET` | `/:id` | Retrieve a single record by its ID. |
 | `findOne` | `GET` | `/find-one` | Retrieve a single record matching a filter. |
 | `create` | `POST` | `/` | Create a new record. |
-| `updateById` | `PATCH` | `/:id` | Update a record by its ID. |
-| `updateAll` | `PATCH` | `/` | Update multiple records matching a filter. |
-| `deleteById` | `DELETE` | `/:id` | Delete a record by its ID. |
-| `deleteAll` | `DELETE` | `/` | Delete multiple records matching a filter. |
+| `updateById` | `PATCH` | `/:id` | Update a single record by its ID. |
+| `updateBy` | `PATCH` | `/` | Update multiple records matching a `where` filter. |
+| `deleteById` | `DELETE` | `/:id` | Delete a single record by its ID. |
+| `deleteBy` | `DELETE` | `/` | Delete multiple records matching a `where` filter. |
 
 :::info Customization
 The `ControllerFactory` is highly customizable. You can override the Zod schemas for any of the generated routes to add, remove, or modify fields for request validation and response shapes. You can also configure other behaviors, like making delete operations return the deleted records.
@@ -368,7 +368,7 @@ When you define Zod schemas in your route's `request` configuration (whether wit
 
 ```typescript
 import { z } from '@hono/zod-openapi';
-import { jsonContent, put } from '@venizia/ignis';
+import { jsonContent, put, HTTP } from '@venizia/ignis';
 
 // ... inside a controller class
 
@@ -397,7 +397,7 @@ updateUser(c: Context) {
     console.log('Notification is enabled.');
   }
 
-  return c.json({ success: true, id, ...userUpdateData });
+  return c.json({ success: true, id, ...userUpdateData }, HTTP.ResultCodes.RS_2.Ok);
 }
 ```
 
@@ -405,7 +405,7 @@ Using `c.req.valid()` is the recommended way to access request data as it ensure
 
 ```typescript
 import { z } from '@hono/zod-openapi';
-import { jsonContent, put, TRouteContext } from '@venizia/ignis';
+import { jsonContent, put, TRouteContext, HTTP } from '@venizia/ignis';
 
 // ... inside a controller class
 
@@ -434,7 +434,7 @@ updateUser(c: TRouteContext<typeof updateUserConfig>) {
     console.log('Notification is enabled.');
   }
 
-  return c.json({ success: true, id, ...userUpdateData });
+  return c.json({ success: true, id, ...userUpdateData }, HTTP.ResultCodes.RS_2.Ok);
 }
 ```
 

package/wiki/get-started/core-concepts/dependency-injection.md

@@ -50,7 +50,7 @@ Before a dependency can be injected, it must be **bound** to the container. This
 
 The `Application` class provides helper methods for common resource types. These automatically create a binding with a conventional key.
 
-| Method | Example Key |
+| Method | Default Key |
 | :--- | :--- |
 | `app.service(UserService)` | `services.UserService` |
 | `app.repository(UserRepository)` | `repositories.UserRepository` |
@@ -58,6 +58,18 @@ The `Application` class provides helper methods for common resource types. These
 | `app.controller(UserController)` | `controllers.UserController` |
 | `app.component(MyComponent)` | `components.MyComponent` |
 
+All these methods accept an optional second parameter to customize the binding key:
+
+```typescript
+// Default binding (key: 'controllers.UserController')
+app.controller(UserController);
+
+// Custom binding key
+app.controller(UserController, {
+  binding: { namespace: 'controllers', key: 'CustomUserController' }
+});
+```
+
 ### Custom Bindings
 
 For other values or more complex setups, use the `bind` method directly.