@venizia/ignis-docs 0.0.1-1

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

@@ -0,0 +1,441 @@
+# Controllers
+
+Controllers handle HTTP requests and return responses - they're your API endpoints.
+
+> **Deep Dive:** See [Controllers Reference](../../references/base/controllers.md) for advanced patterns.
+
+## Creating a Controller
+
+Extend `BaseController` and use decorators to define routes:
+
+```typescript
+import { BaseController, controller, get, jsonResponse, z } from '@venizia/ignis';
+import { Context } from 'hono';
+
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+  constructor() {
+    // It's good practice to pass a scope for logging
+    super({ scope: UserController.name, path: '/users' });
+  }
+
+  @get({
+    configs: {
+      path: '/',
+      responses: jsonResponse({
+        description: 'A list of users',
+        schema: z.array(z.object({ id: z.string(), name: z.string() })),
+      }),
+    },
+  })
+  getAllUsers(c: Context) {
+    return c.json([{ id: '1', name: 'John Doe' }]);
+  }
+}
+```
+Notice that the `binding()` method is no longer needed when using decorators.
+
+## Controller Lifecycle
+
+Controllers have a simple and predictable lifecycle managed by the application.
+
+| Stage | Method | Description |
+| :--- | :--- | :--- |
+| **1. Instantiation** | `constructor(opts)` | The controller is created by the DI container. Dependencies are injected, and you call `super()` to initialize the internal Hono router. |
+| **2. Configuration**| `registerControllers` phase | The application automatically discovers and registers all routes defined with decorators (`@get`, `@post`, etc.) on your controller methods. If you have routes defined manually inside `binding()`, that method is also called during this phase. **Note:** If you exclusively use decorators for routing, the `binding()` method can be omitted from your controller. |
+
+## Defining Routes with Decorators (Recommended)
+
+The recommended way to define routes is by using decorators directly on the controller methods that handle them. This approach is more declarative, keeps your code organized, and provides **full type safety** for your request parameters, query, body, and even the response.
+
+:::tip Type Safety without Boilerplate
+For decorator-based routes, you do not need to explicitly annotate the return type with `TRouteResponse`. TypeScript will automatically infer and validate the return type against the OpenAPI response schema you define in your `configs`. This gives you full type safety with less code.
+:::
+
+### HTTP Method Decorators
+
+`Ignis` provides a decorator for each common HTTP method:
+
+-   `@get(opts)`
+-   `@post(opts)`
+-   `@put(opts)`
+-   `@patch(opts)`
+-   `@del(opts)`
+-   `@api(opts)` (a generic decorator where you specify the method in the `configs`)
+
+The `opts` object contains a `configs` property that defines the route's path, request validation, and OpenAPI response schemas.
+
+**Example using decorators with `ROUTE_CONFIGS` and full type inference:**
+
+For optimal organization and type safety, define your route configurations in a constant with `as const`. This allows TypeScript to precisely infer the types for your request data and expected responses within your handler methods.
+
+```typescript
+import { BaseController, controller, get, post, HTTP, jsonContent, jsonResponse, TRouteContext } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+
+// Define route configs as const for type inference
+const TEST_ROUTES = {
+  getData: {
+    method: HTTP.Methods.GET,
+    path: '/',
+    responses: jsonResponse({
+      description: 'A simple message',
+      schema: z.object({ message: z.string(), method: z.string() }),
+    }),
+  },
+  createItem: {
+    method: HTTP.Methods.POST,
+    path: '/',
+    request: {
+      body: jsonContent({
+        description: 'Request body for creating an item',
+        schema: z.object({ name: z.string(), value: z.number().int().positive() }),
+      }),
+    },
+    responses: jsonResponse({
+      description: 'Created item',
+      schema: z.object({ id: z.string(), name: z.string(), value: z.number() }),
+    }),
+  },
+} as const; // Crucial for strict type inference!
+
+@controller({ path: '/my-items' })
+export class MyItemsController extends BaseController {
+  constructor() {
+    super({ scope: MyItemsController.name, path: '/my-items' });
+  }
+
+  @get({ configs: TEST_ROUTES.getData })
+  getData(c: TRouteContext<typeof TEST_ROUTES.getData>) { // Return type is automatically inferred
+    // 'c' is fully typed here, including c.req.valid and c.json return type
+    return c.json({ message: 'Hello from decorator', method: 'GET' }, HTTP.ResultCodes.RS_2.Ok);
+  }
+
+  @post({ configs: TEST_ROUTES.createItem })
+  createItem(c: TRouteContext<typeof TEST_ROUTES.createItem>) { // Return type is automatically inferred
+    // c.req.valid('json') is automatically typed based on createItem.request.body.content['application/json'].schema
+    const body = c.req.valid('json');
+
+    // Return type is automatically validated against createItem.responses[200].content['application/json'].schema
+    return c.json(
+      {
+        id: 'some-uuid',
+        name: body.name,
+        value: body.value,
+      },
+      HTTP.ResultCodes.RS_2.Ok,
+    );
+  }
+}
+```
+
+## Manual Route Definition: An Alternative Approach
+
+While decorators are the recommended approach for most use cases, `Ignis` also provides a manual way to define routes within the controller's `binding()` method.
+
+### Decorator vs Manual: Quick Comparison
+
+| Aspect | Decorators (`@get`, `@post`) | Manual (`defineRoute`, `bindRoute`) |
+| :--- | :--- | :--- |
+| **Syntax** | Clean, declarative | More verbose |
+| **Organization** | Route config near the handler | Can be in separate files |
+| **Use Case** | Most standard CRUD endpoints | Dynamic route generation |
+| **Type Safety** | Full inference with `TRouteContext` | Full inference with `TRouteContext` |
+| **Readability** | High - easy to scan | Medium - requires scrolling |
+| **Best For** | 90% of use cases | Advanced scenarios |
+
+### When to Use Manual Route Definition
+
+Manual route definition is useful for:
+
+-   **Dynamically generating routes** based on configuration (e.g., loading routes from a database)
+-   **Organizing all routes** for a controller within a single method if you prefer centralized route declarations
+-   **Conditional route registration** (e.g., enabling/disabling routes based on feature flags)
+-   **Developers who prefer non-decorator syntax** (coming from Express/Fastify)
+
+When using this method, you will override the `binding()` method in your controller and use `this.defineRoute` or `this.bindRoute` to register your endpoints.
+
+### `defineRoute`
+
+Use this method for defining a single API endpoint with all its configurations and handler. It also benefits from type inference when used with `TRouteContext`.
+
+```typescript
+import { Authentication, HTTP, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+
+// ... inside the binding() method
+
+const GetUsersRoute = {
+  path: '/',
+  method: 'get',
+  authStrategies: [Authentication.STRATEGY_JWT],
+  responses: jsonResponse({
+    description: 'List of all users',
+    schema: z.array(z.object({ id: z.number(), name: z.string() })),
+  }),
+} as const;
+
+this.defineRoute({
+  configs: GetUsersRoute,
+  handler: (c: TRouteContext<typeof GetUsersRoute>) => { // Return type is automatically inferred
+    return c.json([{ id: 1, name: 'John Doe' }]);
+  },
+});
+```
+
+### `bindRoute`
+
+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';
+
+// ... inside the binding() method
+
+const GetUserByIdRoute = {
+  path: '/:id',
+  method: 'get',
+  responses: jsonResponse({
+    description: 'A single user',
+    schema: z.object({ id: z.string(), name: z.string() }),
+  }),
+} as const;
+
+this.bindRoute({
+  configs: GetUserByIdRoute,
+}).to({
+  handler: (c: TRouteContext<typeof GetUserByIdRoute>) => { // Return type is automatically inferred
+    const { id } = c.req.param();
+    return c.json({ id: id, name: 'John Doe' });
+  },
+});
+```
+
+## `ControllerFactory` for CRUD Operations
+
+For standard CRUD (Create, Read, Update, Delete) operations, `Ignis` provides a `ControllerFactory` that can generate a full-featured controller for any given entity. This significantly reduces boilerplate code.
+
+```typescript
+// src/controllers/configuration.controller.ts (Example from @examples/vert)
+import { Configuration } from '@/models';
+import { ConfigurationRepository } from '@/repositories';
+import {
+  BindingKeys,
+  BindingNamespaces,
+  controller,
+  ControllerFactory,
+  inject,
+} from '@venizia/ignis';
+
+const BASE_PATH = '/configurations';
+
+const _Controller = ControllerFactory.defineCrudController({
+  repository: { name: ConfigurationRepository.name },
+  controller: {
+    name: 'ConfigurationController',
+    basePath: BASE_PATH,
+    isStrict: true,
+  },
+  entity: () => Configuration, // Provide a resolver for your entity class
+});
+
+@controller({ path: BASE_PATH })
+export class ConfigurationController extends _Controller {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.REPOSITORY,
+        key: ConfigurationRepository.name,
+      }),
+    })
+    repository: ConfigurationRepository,
+  ) {
+    super(repository); // The generated controller expects the repository in its constructor
+  }
+}
+```
+The `ControllerFactory.defineCrudController` method automatically sets up the following routes based on your entity schema:
+
+| 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. |
+
+:::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.
+
+For a full list of customization options, see the [**Deep Dive: `ControllerFactory`**](../../references/base/controllers.md#controllerfactory) documentation.
+:::
+
+### `defineJSXRoute` (Server-Side Rendered HTML)
+
+Use this method for routes that render HTML pages using JSX components. This is perfect for building server-side rendered web applications.
+
+```typescript
+import { htmlResponse } from '@venizia/ignis';
+
+// ... inside the binding() method
+
+this.defineJSXRoute({
+  configs: {
+    path: '/',
+    method: 'get',
+    description: 'Home page',
+    responses: htmlResponse({
+      description: 'HTML home page',
+    }),
+  },
+  handler: (c) => {
+    const user = { name: 'John Doe' };
+    return c.html(<HomePage user={user} />);
+  },
+});
+```
+
+**Key Points:**
+- The handler **must** return `c.html()` with a JSX component
+- JSX routes automatically include HTML content-type in OpenAPI documentation
+- Views are typically organized in `src/views/` directory
+- Components can be reused across multiple pages
+
+**Example View Component:**
+
+```typescript
+// src/views/pages/home.page.tsx
+import type { FC } from '@venizia/ignis';
+import { MainLayout } from '../layouts/main.layout';
+
+interface HomePageProps {
+  user: { name: string };
+}
+
+export const HomePage: FC<HomePageProps> = ({ user }) => {
+  return (
+    <MainLayout title="Home">
+      <h1>Welcome, {user.name}!</h1>
+      <p>This page is rendered on the server using JSX.</p>
+    </MainLayout>
+  );
+};
+```
+
+**Example Layout Component:**
+
+```typescript
+// src/views/layouts/main.layout.tsx
+import type { FC, PropsWithChildren } from '@venizia/ignis';
+
+interface MainLayoutProps {
+  title: string;
+}
+
+export const MainLayout: FC<PropsWithChildren<MainLayoutProps>> = ({ title, children }) => {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>{title}</title>
+      </head>
+      <body>
+        <header>
+          <nav>
+            <a href="/">Home</a>
+            <a href="/about">About</a>
+          </nav>
+        </header>
+        <main>{children}</main>
+        <footer>
+          <p>© 2025 My App</p>
+        </footer>
+      </body>
+    </html>
+  );
+};
+```
+
+> **Note:** JSX support in `Ignis` uses Hono's built-in JSX runtime. Make sure your `tsconfig.json` includes the JSX configuration (this is already set up in the framework's base configuration).
+
+## Accessing Validated Request Data
+
+When you define Zod schemas in your route's `request` configuration (whether with decorators or manual definition), Hono's validation middleware automatically parses and validates the incoming data. You can access this validated data using `c.req.valid()`.
+
+```typescript
+import { z } from '@hono/zod-openapi';
+import { jsonContent, put } from '@venizia/ignis';
+
+// ... inside a controller class
+
+const UserSchema = z.object({ name: z.string(), email: z.string().email() });
+
+@put({
+  configs: {
+    path: '/:id',
+    method: 'put',
+    request: {
+      params: z.object({ id: z.string() }),
+      query: z.object({ notify: z.string().optional() }),
+      body: jsonContent({ schema: UserSchema }),
+    },
+    // ... responses
+  },
+})
+updateUser(c: Context) {
+  // Access validated data from the request
+  const { id } = c.req.valid('param');
+  const { notify } = c.req.valid('query');
+  const userUpdateData = c.req.valid('json'); // for body
+
+  console.log(`Updating user ${id} with data:`, userUpdateData);
+  if (notify) {
+    console.log('Notification is enabled.');
+  }
+
+  return c.json({ success: true, id, ...userUpdateData });
+}
+```
+
+Using `c.req.valid()` is the recommended way to access request data as it ensures that the data conforms to the schema you've defined. For even better type safety, you can use the `TRouteContext` utility type.
+
+```typescript
+import { z } from '@hono/zod-openapi';
+import { jsonContent, put, TRouteContext } from '@venizia/ignis';
+
+// ... inside a controller class
+
+const updateUserConfig = {
+  path: '/:id',
+  method: 'put',
+  request: {
+    params: z.object({ id: z.string() }),
+    query: z.object({ notify: z.string().optional() }),
+    body: jsonContent({
+      schema: z.object({ name: z.string(), email: z.string().email() }),
+    }),
+  },
+  // ... responses
+} as const; // Use 'as const' for strict type inference
+
+@put({ configs: updateUserConfig })
+updateUser(c: TRouteContext<typeof updateUserConfig>) {
+  // Access validated data from the request
+  const { id } = c.req.valid('param');
+  const { notify } = c.req.valid('query');
+  const userUpdateData = c.req.valid('json'); // for body
+
+  console.log(`Updating user ${id} with data:`, userUpdateData);
+  if (notify) {
+    console.log('Notification is enabled.');
+  }
+
+  return c.json({ success: true, id, ...userUpdateData });
+}
+```
+
+Using `TRouteContext` provides full type inference for `c.req.valid()`, so your editor will know that `id` is a string, `notify` is an optional string, and `userUpdateData` matches the body schema.

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

@@ -0,0 +1,160 @@
+# Dependency Injection
+
+Dependency Injection (DI) enables loosely coupled, testable code by automatically providing dependencies to classes.
+
+> **Deep Dive:** See [DI Reference](../../references/base/dependency-injection.md) for technical details on Container, Binding, and `@inject`.
+
+> **Standalone Package:** The core DI container is available as the standalone `@venizia/ignis-inversion` package for use outside the Ignis framework. See [Inversion Package Reference](../../references/src-details/inversion.md) for details.
+
+## Core Concepts
+
+| Concept | Description |
+| :--- | :--- |
+| **Container** | The central registry for all your application's services and dependencies. The `Application` class itself acts as the container. |
+| **Binding** | The process of registering a class or value with the container under a specific key (e.g., `'services.UserService'`). |
+| **Injection**| The process of requesting a dependency from the container using the `@inject` decorator. |
+
+### How It Works: The DI Flow
+
+```mermaid
+graph TD
+    A[1. Bind Resource] -- app.service(MyService) --> B(Container stores a Binding for 'services.MyService');
+    B -- triggers --> C[2. Instantiate Consumer];
+    C -- @inject({ key: 'services.MyService' }) --> D(Container reads injection metadata);
+    D -- finds binding --> E[3. Resolve & Inject];
+    E -- gets dependency --> F(Container creates/gets instance of MyService);
+    F -- injects into --> G(MyController instance is created with MyService);
+
+    subgraph Application Startup
+        A
+    end
+    subgraph On-Demand Instantiation
+        C
+    end
+    subgraph Container Internals
+        B
+        D
+        E
+        F
+    end
+    subgraph Result
+        G
+    end
+```
+
+## Binding Dependencies
+
+Before a dependency can be injected, it must be **bound** to the container. This is typically done in the `preConfigure` method of your `Application` class.
+
+### Standard Resource Binding
+
+The `Application` class provides helper methods for common resource types. These automatically create a binding with a conventional key.
+
+| Method | Example Key |
+| :--- | :--- |
+| `app.service(UserService)` | `services.UserService` |
+| `app.repository(UserRepository)` | `repositories.UserRepository` |
+| `app.dataSource(PostgresDataSource)` | `datasources.PostgresDataSource` |
+| `app.controller(UserController)` | `controllers.UserController` |
+| `app.component(MyComponent)` | `components.MyComponent` |
+
+### Custom Bindings
+
+For other values or more complex setups, use the `bind` method directly.
+
+```typescript
+// In your application class's preConfigure()
+this.bind<MyCustomClass>({ key: 'MyCustomClass' }).toClass(MyCustomClass);
+
+this.bind<string>({ key: 'API_KEY' }).toValue('my-secret-api-key');
+```
+
+### Binding Scopes
+
+You can control the lifecycle of your dependencies with scopes.
+
+-   **`TRANSIENT`** (default): A new instance is created every time the dependency is injected.
+-   **`SINGLETON`**: A single instance is created once and reused for all subsequent injections.
+
+```typescript
+this.bind({ key: 'services.MySingletonService' })
+  .toClass(MySingletonService)
+  .setScope(BindingScopes.SINGLETON); // Use SINGLETON for this service
+```
+
+## Injecting Dependencies
+
+`Ignis` provides the `@inject` decorator to request dependencies from the container.
+
+### Constructor Injection (Recommended)
+
+This makes dependencies explicit and ensures they are available right away.
+
+```typescript
+import { BaseController, controller, inject } from '@venizia/ignis';
+import { UserService } from '../services/user.service';
+
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+  constructor(
+    @inject({ key: 'services.UserService' })
+    private userService: UserService
+  ) {
+    super({ scope: UserController.name, path: '/users' });
+  }
+
+  // ... you can now use this.userService
+}
+```
+
+### Property Injection
+
+You can also inject dependencies directly as class properties.
+
+```typescript
+import { inject } from '@venizia/ignis';
+import { UserService } from '../services/user.service';
+
+export class UserComponent {
+  @inject({ key: 'services.UserService' })
+  private userService: UserService;
+  
+  // ...
+}
+```
+
+## Providers
+
+Providers are used for dependencies that require complex setup logic. A provider is a class that implements a `value()` method, which is responsible for creating and returning the dependency instance.
+
+### Creating a Custom Provider
+
+```typescript
+import { BaseProvider, inject, Container, IConfig } from '@venizia/ignis';
+import { ThirdPartyApiClient } from '../services/api-client.service';
+
+// Assume IConfig is a configuration object we've bound elsewhere
+@injectable() // Make the provider itself injectable
+export class ApiClientProvider extends BaseProvider<ThirdPartyApiClient> {
+  @inject({ key: 'configs.api' })
+  private apiConfig: IConfig;
+  
+  // The container calls this method to get the instance
+  value(container: Container): ThirdPartyApiClient {
+    const client = new ThirdPartyApiClient({
+      apiKey: this.apiConfig.apiKey,
+      baseUrl: this.apiConfig.baseUrl,
+    });
+    client.connect(); // Perform initial setup
+    return client;
+  }
+}
+```
+
+You would then bind this provider in your application:
+
+```typescript
+// In your application class
+this.bind<ThirdPartyApiClient>({ key: 'services.ApiClient' })
+  .toProvider(ApiClientProvider);
+```