@venizia/ignis-docs 0.0.8 → 0.2.0

package/README.md

@@ -2,14 +2,14 @@
 
 # :fire: IGNIS - @venizia/ignis-docs
 
-**Documentation site and MCP server for the Ignis Framework**
+**Documentation site and MCP server for the IGNIS Framework**
 
 [![npm](https://img.shields.io/npm/v/@venizia/ignis-docs.svg?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@venizia/ignis-docs)
 [![License](https://img.shields.io/badge/License-MIT-3DA639.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-8B5CF6.svg?style=flat-square)](https://modelcontextprotocol.io/)
 
-VitePress-powered documentation site and an MCP server with 11 tools that gives AI assistants real-time access to Ignis knowledge -- search docs, browse source code, and verify dependencies.
+VitePress-powered documentation site and an MCP server with 11 tools that gives AI assistants real-time access to IGNIS knowledge -- search docs, browse source code, and verify dependencies.
 
 [Installation](#installation) • [MCP Setup](#mcp-server-setup) • [Available Tools](#available-mcp-tools) • [Online Docs](https://venizia-ai.github.io/ignis)
 
@@ -106,13 +106,13 @@ Add to your Claude Code MCP settings:
 | **listDocs** | List all available documentation pages |
 | **listCategories** | List documentation categories and their structure |
 | **getDocMetadata** | Get metadata (title, path, category) for a document |
-| **getPackageOverview** | Get an overview of a specific Ignis package |
+| **getPackageOverview** | Get an overview of a specific IGNIS package |
 
 ### GitHub Tools
 
 | Tool | Description |
 | --- | --- |
-| **searchCode** | Search the Ignis source code by keyword |
+| **searchCode** | Search the IGNIS source code by keyword |
 | **listProjectFiles** | List files in a specific directory of the repository |
 | **viewSourceFile** | View the contents of a source file |
 | **verifyDependencies** | Check dependency versions and compatibility |
@@ -140,7 +140,7 @@ bun run docs:preview
 wiki/
 ├── guides/              # Getting started, core concepts, tutorials
 ├── references/          # API documentation
-│   ├── base/            # BaseApplication, BaseController, BaseEntity, etc.
+│   ├── base/            # BaseApplication, BaseRestController, BaseEntity, etc.
 │   ├── components/      # HealthCheck, Swagger, Auth, Mail, SocketIO, etc.
 │   ├── helpers/         # Logger, Redis, Queue, Storage, Crypto, etc.
 │   └── utilities/       # Parse, Date, Promise, Performance utilities
@@ -184,9 +184,9 @@ bun run mcp:rebuild
 
 ## Related Links
 
-- [Ignis Framework](https://github.com/VENIZIA-AI/ignis) -- Main repository
+- [IGNIS Framework](https://github.com/VENIZIA-AI/ignis) -- Main repository
 - [Online Documentation](https://venizia-ai.github.io/ignis) -- Full documentation site
-- [MCP Server Guide](https://github.com/VENIZIA-AI/ignis/blob/main/packages/docs/wiki/get-started/mcp-docs-server.md) -- Detailed setup guide
+- [MCP Server Guide](https://github.com/VENIZIA-AI/ignis/blob/main/docs/wiki/content/guides/reference/mcp-docs-server.md) -- Detailed setup guide
 - [Model Context Protocol](https://modelcontextprotocol.io/) -- MCP specification
 
 ---

package/content/best-practices/api-usage-examples.md

@@ -1,6 +1,6 @@
 # API Usage Examples
 
-Practical examples for defining endpoints and working with data in Ignis applications.
+Practical examples for defining endpoints and working with data in IGNIS applications.
 
 ## Routing Patterns
 
@@ -28,7 +28,7 @@ export const RouteConfigs = {
   CREATE_ITEM: {
     method: HTTP.Methods.POST,
     path: '/items',
-    authStrategies: [Authentication.STRATEGY_JWT], // Secure this endpoint
+    authenticate: { strategies: [Authentication.STRATEGY_JWT] }, // Secure this endpoint
     request: {
       body: jsonContent({
         description: 'Request body for POST',
@@ -229,7 +229,7 @@ const deleted = await configurationRepository.deleteById({
 
 ## Server-Side Rendering (JSX)
 
-Ignis supports server-side rendering using Hono's JSX middleware. This is useful for returning HTML content, such as landing pages or simple admin views.
+IGNIS supports server-side rendering using Hono's JSX middleware. This is useful for returning HTML content, such as landing pages or simple admin views.
 
 **Usage:**
 
@@ -250,7 +250,7 @@ export class PageController extends BaseRestController {
         responses: htmlResponse({ description: 'HTML Welcome Page' }),
       },
       handler: (c) => {
-        const title = 'Welcome to Ignis';
+        const title = 'Welcome to IGNIS';
         
         // Return JSX directly
         return c.html(
@@ -378,18 +378,20 @@ export class UserService extends BaseService {
   }
 
   async getUserWithOrders(userId: string) {
+    // findById returns the record or null (no wrapper object)
     const user = await this.userRepository.findById({ id: userId });
-    if (!user.data) {
+    if (!user) {
       return null;
     }
 
+    // find returns a plain array
     const orders = await this.orderRepository.find({
       filter: { where: { userId } },
     });
 
     return {
-      ...user.data,
-      orders: orders.data,
+      ...user,
+      orders,
     };
   }
 
@@ -502,7 +504,7 @@ import { getError, HTTP } from '@venizia/ignis-helpers';
 
 // Basic error
 throw getError({ message: 'Something went wrong' });
-// Returns: { statusCode: 400, message: 'Something went wrong' }
+// Returns: { statusCode: 400, message: 'Something went wrong', messageCode: 'core.system_error' }
 
 // With status code
 throw getError({
@@ -514,7 +516,7 @@ throw getError({
 throw getError({
   statusCode: 404,
   message: 'User not found',
-  messageCode: 'USER_NOT_FOUND',
+  messageCode: 'core.user.not_found',
 });
 ```
 
@@ -527,14 +529,14 @@ async getUser(c: TRouteContext) {
 
   const user = await this.userRepository.findById({ id });
 
-  if (!user.data) {
+  if (!user) {
     throw getError({
       statusCode: 404,
       message: `User with ID '${id}' not found`,
     });
   }
 
-  return c.json(user.data, HTTP.ResultCodes.RS_2.Ok);
+  return c.json(user, HTTP.ResultCodes.RS_2.Ok);
 }
 ```
 
@@ -546,7 +548,7 @@ All errors are automatically formatted:
 {
   "statusCode": 404,
   "message": "User not found",
-  "messageCode": "USER_NOT_FOUND",
+  "messageCode": "core.user.not_found",
   "requestId": "abc123"
 }
 ```
@@ -592,3 +594,4 @@ async processOrder(c: Context) {
     });
   }
 }
+```

package/content/best-practices/architectural-patterns.md

@@ -1,10 +1,10 @@
 # Architectural Patterns
 
-Ignis promotes separation of concerns, dependency injection, and modularity for scalable, maintainable applications.
+IGNIS promotes separation of concerns, dependency injection, and modularity for scalable, maintainable applications.
 
 ## 1. Layered Architecture
 
-Each layer has a single responsibility. Ignis supports **two architectural approaches**:
+Each layer has a single responsibility. IGNIS supports **two architectural approaches**:
 
 ```mermaid
 graph TD
@@ -117,11 +117,11 @@ REST controllers extend `BaseRestController`, while gRPC controllers extend `Bas
 
 ## 3. Component-Based Modularity
 
-Components bundle a group of related, reusable, and pluggable features into self-contained modules. A single component can encapsulate multiple providers, services, controllers, and repositories, essentially functioning as a mini-application that can be easily "plugged in" to any Ignis project.
+Components bundle a group of related, reusable, and pluggable features into self-contained modules. A single component can encapsulate multiple providers, services, controllers, and repositories, essentially functioning as a mini-application that can be easily "plugged in" to any IGNIS project.
 
 **Built-in Components:**
 - `AuthenticateComponent` - JWT authentication
-- `SwaggerComponent` - OpenAPI documentation
+- `ApiReferenceComponent` - OpenAPI documentation
 - `HealthCheckComponent` - Health check endpoint
 - `RequestTrackerComponent` - Request logging
 
@@ -135,7 +135,7 @@ export class Application extends BaseApplication {
     // ...
     // Registering components plugs their functionality into the application.
     this.component(HealthCheckComponent);
-    this.component(SwaggerComponent);
+    this.component(ApiReferenceComponent);
     // ...
   }
 }
@@ -154,7 +154,7 @@ You can encapsulate your own logic or third-party integrations (like Socket.IO,
 **Example (`SocketIOComponent`):**
 
 ```typescript
-import { BaseComponent, inject, CoreBindings, Binding } from '@venizia/ignis';
+import { BaseApplication, BaseComponent, inject, CoreBindings, Binding } from '@venizia/ignis';
 
 export class MySocketComponent extends BaseComponent {
   constructor(
@@ -171,7 +171,7 @@ export class MySocketComponent extends BaseComponent {
     });
   }
 
-  // The binding method is called during application startup (preConfigure)
+  // The binding method is called when the application configures components (registerComponents)
   override binding(): void {
     const options = this.application.get({ key: 'my.socket.options' });
     
@@ -185,7 +185,7 @@ export class MySocketComponent extends BaseComponent {
 
 ## 5. Application Lifecycle Hooks
 
-Ignis applications follow a predictable startup sequence with hooks for customization:
+IGNIS applications follow a predictable startup sequence with hooks for customization:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -248,25 +248,25 @@ export class Application extends BaseApplication {
 
     // Components
     this.component(AuthenticateComponent);
-    this.component(SwaggerComponent);
+    this.component(ApiReferenceComponent);
   }
 
   // Called after all registrations complete
   async postConfigure(): Promise<void> {
     // Access registered services
-    const userRepo = this.get<UserRepository>({
+    const userRepository = this.get<UserRepository>({
       key: BindingKeys.build({
         namespace: BindingNamespaces.REPOSITORY,
         key: UserRepository.name,
       }),
     });
 
-    // Seed initial data
-    const adminExists = await userRepo.findOne({
+    // Seed initial data (findOne returns the record or null)
+    const adminExists = await userRepository.findOne({
       filter: { where: { role: 'admin' } },
     });
-    if (!adminExists.data) {
-      await userRepo.create({ data: { name: 'Admin', role: 'admin' } });
+    if (!adminExists) {
+      await userRepository.create({ data: { name: 'Admin', role: 'admin' } });
     }
   }
 
@@ -280,55 +280,40 @@ export class Application extends BaseApplication {
 > [!WARNING]
 > Do not register new datasources, components, or controllers in `postConfigure()`. They will not be automatically initialized. Use `preConfigure()` for all registrations.
 
-## 6. Mixin Pattern
+## 6. Registration Surface & Capability Interfaces
 
-Mixins enable class composition without deep inheritance hierarchies. Ignis uses mixins to add capabilities to the `BaseApplication` class.
+`BaseApplication` implements the full resource-registration surface directly - `service()`, `repository()`, `dataSource()`, `controller()`, `component()`, and `booter()`. Extend `BaseApplication` and call these methods straight from your lifecycle hooks; there is nothing to compose.
 
-**How Mixins Work:**
+**How registration works:**
 ```typescript
-// A mixin is a function that takes a class and returns an extended class
-const ServiceMixin = <T extends TMixinTarget<AbstractApplication>>(baseClass: T) => {
-  return class extends baseClass {
-    service<Base extends IService>(ctor: TClass<Base>): Binding<Base> {
-      return this.bind<Base>({
-        key: BindingKeys.build({
-          namespace: BindingNamespaces.SERVICE,
-          key: ctor.name,
-        }),
-      }).toClass(ctor);
-    }
-  };
-};
+// BaseApplication implements service() directly (no mixin composition):
+service<Base extends IService>(ctor: TClass<Base>): Binding<Base> {
+  return this.bind<Base>({
+    key: BindingKeys.build({
+      namespace: BindingNamespaces.SERVICE,
+      key: ctor.name,
+    }),
+  }).toClass(ctor);
+}
 ```
 
-**Available Mixins:**
+**Capability interfaces:**
 
-| Mixin | Methods Added | Purpose |
-|-------|---------------|---------|
-| `ServiceMixin` | `service()` | Register service classes |
-| `RepositoryMixin` | `repository()`, `dataSource()`, `registerDataSources()` | Register data layer |
-| `ControllerMixin` | `controller()` | Register HTTP controllers |
-| `ComponentMixin` | `component()` | Register modular components |
+Each registration capability is declared as a TypeScript interface that `IRestApplication` (and therefore `BaseApplication`) implements. Reference these when you type your own application contracts:
 
-**Composing Mixins:**
-```typescript
-// The framework composes mixins like this:
-class AbstractApplication extends ComponentMixin(
-  ControllerMixin(
-    ServiceMixin(
-      RepositoryMixin(BaseClass)
-    )
-  )
-) {
-  // Now has: service(), repository(), dataSource(), controller(), component()
-}
-```
+| Interface | Methods | Purpose |
+|-----------|---------|---------|
+| `IServiceMixin` | `service()` | Register service classes |
+| `IRepositoryMixin` | `repository()`, `dataSource()`, `registerDataSources()` | Register data layer |
+| `IComponentMixin` | `component()`, `registerComponents()` | Register modular components |
 
-**Why Mixins?**
-- Avoid "diamond inheritance" problems
-- Add capabilities selectively
-- Keep base classes focused
-- Enable code reuse across unrelated classes
+> [!NOTE]
+> Earlier releases also exported `ServiceMixin`, `RepositoryMixin`, and `ComponentMixin` as class-mixin **functions** you composed onto `AbstractApplication`. They duplicated `BaseApplication`'s own methods verbatim, drifted out of sync, and had no known consumers, so they were removed. The `IServiceMixin` / `IRepositoryMixin` / `IComponentMixin` **interfaces** remain - extend `BaseApplication` and call its registration methods directly.
+
+**Why direct methods over composed mixins?**
+- One implementation, no drift between a mixin and the base class
+- Registration is available the moment you extend `BaseApplication`
+- The interfaces still express each capability for typed contracts
 
 ## 7. Controller Factory Pattern
 
@@ -337,13 +322,13 @@ class AbstractApplication extends ComponentMixin(
 **Basic Usage:**
 ```typescript
 const _Controller = ControllerFactory.defineCrudController({
-  entity: () => User,
+  entity: () => User, // Entity class or resolver function
   repository: { name: UserRepository.name },
   controller: {
     name: 'UserController',
     basePath: '/users',
-    isStrict: true,      // Enable strict validation
-    defaultLimit: 50,    // Default pagination limit
+    // Default: { path: true, requestSchema: true }
+    isStrict: { path: true, requestSchema: true },
   },
 });
 
@@ -366,14 +351,14 @@ const _Controller = ControllerFactory.defineCrudController({
   controller: { name: 'UserController', basePath: '/users' },
 
   // Apply JWT to all routes by default
-  authStrategies: [Authentication.STRATEGY_JWT],
+  authenticate: { strategies: [Authentication.STRATEGY_JWT] },
 
   // Override per-route
   routes: {
     // Public read endpoints
-    find: { skipAuth: true },
-    findById: { skipAuth: true },
-    count: { skipAuth: true },
+    find: { authenticate: { skip: true } },
+    findById: { authenticate: { skip: true } },
+    count: { authenticate: { skip: true } },
 
     // Protected write endpoints (use controller-level auth)
     create: {},
@@ -393,22 +378,26 @@ const _Controller = ControllerFactory.defineCrudController({
   routes: {
     // Custom request body schema for create
     create: {
-      authStrategies: [Authentication.STRATEGY_JWT],
-      requestBody: z.object({
-        email: z.string().email(),
-        name: z.string().min(2),
-        // Exclude sensitive fields from client input
-      }),
+      authenticate: { strategies: [Authentication.STRATEGY_JWT] },
+      request: {
+        body: z.object({
+          email: z.string().email(),
+          name: z.string().min(2),
+          // Exclude sensitive fields from client input
+        }),
+      },
     },
 
     // Custom response schema
     find: {
-      skipAuth: true,
-      schema: z.array(z.object({
-        id: z.string(),
-        name: z.string(),
-        // Exclude internal fields from response
-      })),
+      authenticate: { skip: true },
+      response: {
+        schema: z.array(z.object({
+          id: z.string(),
+          name: z.string(),
+          // Exclude internal fields from response
+        })),
+      },
     },
   },
 });
@@ -420,10 +409,13 @@ const _Controller = ControllerFactory.defineCrudController({
 |-------|--------|------|-------------|
 | `count` | GET | `/count` | Count records matching filter |
 | `find` | GET | `/` | List records with filter |
-| `findById` | GET | `/:id` | Get single record |
+| `findById` | GET | `/{id}` | Get single record |
 | `findOne` | GET | `/find-one` | Get first matching record |
 | `create` | POST | `/` | Create new record |
-| `updateById` | PATCH | `/:id` | Update record by ID |
+| `updateById` | PATCH | `/{id}` | Update record by ID |
 | `updateBy` | PATCH | `/` | Bulk update by filter |
-| `deleteById` | DELETE | `/:id` | Delete by ID |
-| `deleteBy` | DELETE | `/` | Bulk delete by filter |
+| `deleteById` | DELETE | `/{id}` | Delete by ID |
+| `deleteBy` | DELETE | `/` | Bulk delete by filter |
+
+> [!TIP]
+> `TDataObject`/`TPersistObject` cannot be inferred from `entity` - pass them explicitly for typed handlers: `ControllerFactory.defineCrudController<TUserRecord>({ ... })`. Use `controller.enabledRoutes` to whitelist routes and `controller.readonly` to disable all write routes.