npm - @venizia/ignis-docs - Versions diffs - 0.0.1-1 → 0.0.1-10 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (173) hide show

package/wiki/get-started/best-practices/api-usage-examples.md CHANGED Viewed

@@ -52,6 +52,7 @@ import {
   get,
   post,
   TRouteContext,
+  HTTP,
 } from '@venizia/ignis';
 import { ROUTE_CONFIGS } from './definitions';
@@ -62,7 +63,7 @@ export class TestController extends BaseController {
   @get({ configs: ROUTE_CONFIGS['/4'] })
   getWithDecorator(context: TRouteContext<(typeof ROUTE_CONFIGS)['/4']>) {
     // context is fully typed!
-    return context.json({ message: 'Hello from decorator', method: 'GET' });
+    return context.json({ message: 'Hello from decorator', method: 'GET' }, HTTP.ResultCodes.RS_2.Ok);
   }
   @post({ configs: ROUTE_CONFIGS['/5'] })
@@ -71,11 +72,14 @@ export class TestController extends BaseController {
     const body = context.req.valid('json');
     // The response is validated against the schema
-    return context.json({
-      id: crypto.randomUUID(),
-      name: body.name,
-      age: body.age,
-    });
+    return context.json(
+      {
+        id: crypto.randomUUID(),
+        name: body.name,
+        age: body.age,
+      },
+      HTTP.ResultCodes.RS_2.Ok,
+    );
   }
 }
 ```
@@ -97,7 +101,7 @@ export class TestController extends BaseController {
     this.defineRoute({
       configs: ROUTE_CONFIGS['/1'],
       handler: context => {
-        return context.json({ message: 'Hello' });
+        return context.json({ message: 'Hello' }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
@@ -106,7 +110,7 @@ export class TestController extends BaseController {
       configs: ROUTE_CONFIGS['/3'],
     }).to({
       handler: context => {
-        return context.json({ message: 'Hello 3' });
+        return context.json({ message: 'Hello 3' }, HTTP.ResultCodes.RS_2.Ok);
       },
     });
   }
@@ -219,4 +223,46 @@ const deleted = await configurationRepository.deleteById({
   id: newRecord.data!.id,
   options: { shouldReturn: true }, // Option to return the deleted record
 });
+## 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.
+**Usage:**
+Use `defineJSXRoute` in your controller and `htmlResponse` for documentation.
+```typescript
+import { BaseController, controller, htmlResponse } from '@venizia/ignis';
+@controller({ path: '/pages' })
+export class PageController extends BaseController {
+  override binding(): void {
+    this.defineJSXRoute({
+      configs: {
+        method: 'get',
+        path: '/welcome',
+        description: 'Welcome Page',
+        responses: htmlResponse({ description: 'HTML Welcome Page' }),
+      },
+      handler: (c) => {
+        const title = 'Welcome to Ignis';
+        // Return JSX directly
+        return c.html(
+          <html>
+            <head><title>{title}</title></head>
+            <body>
+              <h1>{title}</h1>
+              <p>Server-side rendered content.</p>
+            </body>
+          </html>
+        );
+      },
+    });
+  }
+}
+```
 ```

package/wiki/get-started/best-practices/architectural-patterns.md CHANGED Viewed

@@ -103,7 +103,7 @@ export class ConfigurationController extends _Controller {
 ## 3. Component-Based Modularity
-Components bundle related features into self-contained, pluggable modules.
+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
@@ -126,4 +126,45 @@ export class Application extends BaseApplication {
   }
 }
 ```
-This architecture keeps the main `Application` class clean and focused on high-level assembly, while the details of each feature are neatly encapsulated within their respective components.
+This architecture keeps the main `Application` class clean and focused on high-level assembly, while the details of each feature are neatly encapsulated within their respective components.
+## 4. Custom Components
+You can encapsulate your own logic or third-party integrations (like Socket.IO, Redis, specific Cron jobs) into reusable Components.
+**Structure of a Component:**
+1.  Extend `BaseComponent`.
+2.  Define default `bindings` (optional configuration/options).
+3.  Implement `binding()` to register services, providers, or attach logic to the application.
+**Example (`SocketIOComponent`):**
+```typescript
+import { BaseComponent, inject, CoreBindings, Binding } from '@venizia/ignis';
+export class MySocketComponent extends BaseComponent {
+  constructor(
+    @inject({ key: CoreBindings.APPLICATION_INSTANCE }) private application: BaseApplication,
+  ) {
+    super({
+      scope: MySocketComponent.name,
+      // Automatically register bindings when component is loaded
+      initDefault: { enable: true, container: application },
+      bindings: {
+        // Define default configuration binding
+        'my.socket.options': Binding.bind({ key: 'my.socket.options' }).toValue({ port: 8080 }),
+      },
+    });
+  }
+  // The binding method is called during application startup (preConfigure)
+  override binding(): void {
+    const options = this.application.get({ key: 'my.socket.options' });
+    this.logger.info('Initializing Socket.IO with options: %j', options);
+    // Perform setup logic, register other services, etc.
+    // this.application.bind(...).toValue(...);
+  }
+}
+```

package/wiki/get-started/best-practices/code-style-standards.md CHANGED Viewed

@@ -120,3 +120,44 @@ Use the centralized TypeScript configs:
 - `skipLibCheck: true` - Faster compilation
 See [`@venizia/dev-configs` documentation](../../references/src-details/dev-configs.md) for full details.
+## Environment Variables Management
+Avoid using `process.env` directly in your business logic. Instead, use the `applicationEnvironment` helper and define your keys as constants. This ensures type safety and centralized management.
+**Define Keys (`src/common/environments.ts`):**
+```typescript
+export class EnvironmentKeys {
+  static readonly APP_ENV_STRIPE_KEY = 'APP_ENV_STRIPE_KEY';
+  static readonly APP_ENV_MAX_RETRIES = 'APP_ENV_MAX_RETRIES';
+}
+```
+**Usage:**
+```typescript
+import { applicationEnvironment } from '@venizia/ignis';
+import { EnvironmentKeys } from '@/common/environments';
+// Correct usage
+const stripeKey = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_STRIPE_KEY);
+const retries = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_MAX_RETRIES);
+```
+## Standardized Error Handling
+Use the `getError` helper and `HTTP` constants to throw consistent, formatted exceptions that the framework's error handler can process correctly.
+**Example:**
+```typescript
+import { getError, HTTP } from '@venizia/ignis';
+if (!record) {
+  throw getError({
+    statusCode: HTTP.ResultCodes.RS_4.NotFound,
+    message: 'Record not found',
+    // Optional details
+    details: { id: requestedId }
+  });
+}
+```

package/wiki/get-started/best-practices/common-pitfalls.md CHANGED Viewed

@@ -66,6 +66,8 @@ export class Application extends BaseApplication {
 -   **Bad:**
     ```typescript
+    import { ApplicationError, getError } from '@venizia/ignis';
     // In a Controller
     async createUser(c: Context) {
         const { name, email, companyName } = c.req.valid('json');
@@ -73,13 +75,13 @@ export class Application extends BaseApplication {
         // Complex logic inside the controller
         const existingUser = await this.userRepository.findByEmail(email);
         if (existingUser) {
-            throw new ApplicationError({ message: 'Email already exists' });
+            throw getError({ message: 'Email already exists' });
         }
         const company = await this.companyRepository.findOrCreate(companyName);
         const user = await this.userRepository.create({ name, email, companyId: company.id });
-        return c.json(user);
+        return c.json(user, HTTP.ResultCodes.RS_2.Ok);
     }
     ```
 -   **Good:**
@@ -89,7 +91,7 @@ export class Application extends BaseApplication {
         const userData = c.req.valid('json');
         // Delegate to the service
         const newUser = await this.userService.createUser(userData);
-        return c.json(newUser);
+        return c.json(newUser, HTTP.ResultCodes.RS_2.Ok);
     }
     // In UserService

package/wiki/get-started/best-practices/contribution-workflow.md CHANGED Viewed

@@ -32,13 +32,45 @@ feature/*, fix/*, docs/* (your work)
 git clone https://github.com/YOUR_USERNAME/ignis.git
 cd ignis
-# 3. Install dependencies
-bun install
+# 3. Install dependencies (this also runs force-update to fetch latest from NPM)
+make install
+# Or: bun install
 # 4. Add upstream remote
 git remote add upstream https://github.com/VENIZIA-AI/ignis.git
 ```
+## Makefile Commands
+The project uses a Makefile for common development tasks:
+| Command | Description |
+|---------|-------------|
+| `make install` | Install dependencies and force-update from NPM |
+| `make update` | Force update all packages from NPM registry |
+| `make build` | Rebuild all packages in correct order |
+| `make clean` | Clean build artifacts from all packages |
+| `make lint` | Lint all packages |
+| `make help` | Show all available commands |
+**Individual package builds:**
+```bash
+make core          # Build @venizia/ignis (after dependencies)
+make helpers       # Build @venizia/ignis-helpers
+make inversion     # Build @venizia/ignis-inversion
+make dev-configs   # Build @venizia/dev-configs
+make docs          # Build documentation
+```
+**Force update individual packages:**
+```bash
+make update-core
+make update-helpers
+make update-inversion
+make update-dev-configs
+make update-docs
+```
 ## 2. Development Workflow
 ### Step 1: Create Branch
@@ -92,11 +124,13 @@ git commit -m "chore: upgrade Hono to v4.0"
 ### Step 4: Validate
 ```bash
-# Lint and format
-bun run lint:fix
+# Lint and format (from root)
+make lint
+# Or: bun run lint:fix
-# Build TypeScript
-bun run build
+# Build all packages
+make build
+# Or: bun run build
 # Run tests
 bun run test

package/wiki/get-started/best-practices/data-modeling.md ADDED Viewed

@@ -0,0 +1,177 @@
+# Data Modeling
+Ignis streamlines data modeling with Drizzle ORM by providing powerful helpers and "enrichers" that reduce boilerplate code for common schema patterns.
+## 1. Base Entity
+All entity models should extend `BaseEntity`. This provides integration with the framework's repository layer and automatic schema generation support.
+The recommended pattern is to define the schema and relations as **static properties** on the class. This keeps the definition self-contained and enables powerful type inference.
+**Example (`src/models/entities/user.model.ts`):**
+```typescript
+import { BaseEntity, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
+import { pgTable } from 'drizzle-orm/pg-core';
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  // 1. Define schema as a static property
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...extraUserColumns({ idType: 'string' }),
+  });
+  // 2. Define relations as a static method (return empty array if none)
+  static override relations = () => [];
+}
+```
+## 2. Schema Enrichers
+Instead of manually defining common columns like primary keys, timestamps, or audit fields in every table, use Ignis "enrichers".
+**Available Enrichers:**
+| Enricher | Description | Columns Added |
+|----------|-------------|---------------|
+| `generateIdColumnDefs` | Adds a Primary Key | `id` (string/UUID or number/Serial) |
+| `generateTzColumnDefs` | Adds timestamps | `createdAt`, `modifiedAt` (auto-updating) |
+| `generateUserAuditColumnDefs` | Adds audit fields | `createdBy`, `modifiedBy` |
+| `generateDataTypeColumnDefs` | Adds generic value fields | `nValue` (number), `tValue` (text), `jValue` (json), etc. |
+| `extraUserColumns` | Comprehensive user fields | Combines audit, timestamps, status, and type fields |
+**Usage Example:**
+```typescript
+import {
+  generateIdColumnDefs,
+  generateTzColumnDefs,
+  generateUserAuditColumnDefs,
+} from '@venizia/ignis';
+import { pgTable, text } from 'drizzle-orm/pg-core';
+export const configurationTable = pgTable(
+  'Configuration',
+  {
+    // 1. Auto-generate UUID Primary Key
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    // 2. Auto-generate createdAt / modifiedAt
+    ...generateTzColumnDefs(),
+    // 3. Auto-generate createdBy / modifiedBy
+    ...generateUserAuditColumnDefs({
+      created: { dataType: 'string', columnName: 'created_by' },
+      modified: { dataType: 'string', columnName: 'modified_by' },
+    }),
+    // 4. Your custom columns
+    code: text('code').notNull(),
+    description: text('description'),
+    group: text('group').notNull(),
+  },
+  (table) => [
+    // Define indexes/constraints here
+    unique('UQ_code').on(table.code),
+  ]
+);
+```
+## 3. Defining Relations
+Relations are defined using the `TRelationConfig` structure within the static `relations` method of your model.
+**Example (`src/models/entities/configuration.model.ts`):**
+```typescript
+import {
+  BaseEntity,
+  model,
+  RelationTypes,
+  TRelationConfig,
+} from '@venizia/ignis';
+import { User } from './user.model';
+@model({ type: 'entity' })
+export class Configuration extends BaseEntity<typeof Configuration.schema> {
+  // ... schema definition ...
+  // Define relations
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'creator',
+      type: RelationTypes.ONE,
+      schema: User.schema,
+      metadata: {
+        fields: [Configuration.schema.createdBy],
+        references: [User.schema.id],
+      },
+    },
+  ];
+}
+```
+## 4. Repositories and Auto-Discovery
+Ignis simplifies the connection between models, repositories, and datasources.
+### DataSource Auto-Discovery
+DataSources automatically discover their schema from the repositories that bind to them. You **do not** need to manually register schemas in the DataSource constructor.
+```typescript
+// src/datasources/postgres.datasource.ts
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: { /* connection config */ },
+      // NO schema property needed - auto-discovered!
+    });
+  }
+  override configure(): ValueOrPromise<void> {
+    // This method automatically collects all schemas from bound repositories
+    const schema = this.getSchema();
+    this.connector = drizzle({ client: new Pool(this.settings), schema });
+  }
+}
+```
+### Repository Binding
+Repositories use the `@repository` decorator to bind a **Model** to a **DataSource**. This binding is what powers the auto-discovery mechanism.
+**Pattern 1: Zero Boilerplate (Recommended)**
+For most repositories, you don't need a constructor. The DataSource is automatically injected.
+```typescript
+@repository({ model: Configuration, dataSource: PostgresDataSource })
+export class ConfigurationRepository extends DefaultCRUDRepository<typeof Configuration.schema> {
+  // No constructor needed!
+}
+```
+**Pattern 2: Explicit Injection (Advanced)**
+If you need to perform custom initialization or inject additional dependencies, you can define a constructor. **Important:** The first parameter must be the DataSource.
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends ReadableRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    dataSource: PostgresDataSource,
+  ) {
+    super(dataSource);
+  }
+  // Custom methods
+  async findByRealm(realm: string) {
+    return this.findOne({ filter: { where: { realm } } });
+  }
+}
+```

package/wiki/get-started/best-practices/security-guidelines.md CHANGED Viewed

@@ -72,9 +72,11 @@ const SecureRoute = {
 **Access user in protected routes:**
 ```typescript
+import { Authentication, IJWTTokenPayload, ApplicationError, getError } from '@venizia/ignis';
 const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload;
 if (!user.roles.includes('admin')) {
-    throw new ApplicationError({ statusCode: 403, message: 'Forbidden' });
+    throw getError({ statusCode: 403, message: 'Forbidden' });
 }
 ```