@venizia/ignis-docs 0.0.2 → 0.0.4-0

package/wiki/{get-started/best-practices → best-practices}/common-pitfalls.md

@@ -125,14 +125,119 @@ APP_ENV_POSTGRES_DATABASE=db
 
 ## 5. Not Using `as const` for Route Definitions
 
-**Pitfall:** When using the decorator-based routing with a shared `ROUTE_CONFIGS` object, you forget to add `as const` to the object definition. TypeScript will infer the types too broadly, and you will lose the benefits of type-safe contexts (`TRouteContext`).
+**Pitfall:** When using the decorator-based routing with a shared `RouteConfigs` object, you forget to add `as const` to the object definition. TypeScript will infer the types too broadly, and you will lose the benefits of type-safe contexts (`TRouteContext`).
 
 **Solution:** Always use `as const` when exporting a shared route configuration object.
 
 **Example (`src/controllers/test/definitions.ts`):**
 ```typescript
-export const ROUTE_CONFIGS = {
-  // ... your route definitions
+export const RouteConfigs = {
+  GET_USERS: { /* ... */ },
+  GET_USER_BY_ID: { /* ... */ },
 } as const; // <-- This is crucial!
 ```
-This ensures that `TRouteContext<typeof ROUTE_CONFIGS['/path']>` has the precise types for request body, params, and response.
+This ensures that `TRouteContext<typeof RouteConfigs.GET_USERS>` has the precise types for request body, params, and response.
+
+## 6. Bulk Operations Without WHERE Clause
+
+**Problem:** Attempting to update or delete all records without an explicit `where` condition.
+
+**Solution:** Ignis prevents accidental bulk data destruction. You must either provide a `where` condition or explicitly set `force: true`.
+
+```typescript
+// ❌ BAD - Will throw error
+await userRepository.updateBy({
+  data: { status: 'INACTIVE' },
+  where: {},  // Empty where = targets ALL records
+});
+// Error: [updateBy] DENY to perform updateBy | Empty where condition
+
+// ✅ GOOD - Explicit where condition
+await userRepository.updateBy({
+  data: { status: 'INACTIVE' },
+  where: { lastLoginAt: { lt: new Date('2024-01-01') } },
+});
+
+// ✅ GOOD - Intentionally affect all records with force flag
+await userRepository.updateBy({
+  data: { status: 'INACTIVE' },
+  where: {},
+  options: { force: true },  // Explicitly allow empty where
+});
+```
+
+> [!WARNING]
+> The `force: true` flag bypasses the safety check. Only use when you intentionally want to affect ALL records in the table.
+
+## 7. Schema Key Mismatch
+
+**Problem:** Entity name doesn't match the table name registered in the DataSource's schema.
+
+**Error Message:**
+```
+[UserRepository] Schema key mismatch | Entity name 'User' not found in connector.query | Available keys: [Configuration, Post]
+```
+
+**Solution:** Ensure your entity class name matches the table name in `pgTable()`:
+
+```typescript
+// ❌ BAD - Class name 'User' doesn't match table name 'users'
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('users', { /* ... */ });  // Lowercase 'users'
+}
+
+// ✅ GOOD - Class name matches table name
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', { /* ... */ });  // Matches class name
+}
+```
+
+**Why this matters:** The framework uses `entity.name` (class name) to look up the query interface in `connector.query`. If they don't match, the repository can't find its table.
+
+## 8. Validation Error Response Structure
+
+**Problem:** Client receives validation errors but doesn't know how to parse them.
+
+**Solution:** Understand the Zod validation error response format:
+
+```json
+{
+  "statusCode": 422,
+  "message": "ValidationError",
+  "requestId": "abc123",
+  "details": {
+    "cause": [
+      {
+        "path": "email",
+        "message": "Invalid email",
+        "code": "invalid_string",
+        "expected": "email",
+        "received": "string"
+      },
+      {
+        "path": "age",
+        "message": "Expected number, received string",
+        "code": "invalid_type",
+        "expected": "number",
+        "received": "string"
+      }
+    ]
+  }
+}
+```
+
+**Client-side handling:**
+```typescript
+try {
+  await api.post('/users', data);
+} catch (error) {
+  if (error.response?.status === 422) {
+    const errors = error.response.data.details.cause;
+    errors.forEach(err => {
+      console.log(`Field '${err.path}': ${err.message}`);
+    });
+  }
+}
+```

package/wiki/{get-started/best-practices → best-practices}/contribution-workflow.md

@@ -40,6 +40,32 @@ make install
 git remote add upstream https://github.com/VENIZIA-AI/ignis.git
 ```
 
+## Package Build Order
+
+Ignis is a monorepo with interdependent packages. Understanding the dependency chain is critical for development:
+
+```
+dev-configs → inversion → helpers → boot → core
+     ↓            ↓           ↓        ↓      ↓
+  @venizia/   @venizia/   @venizia/  @venizia/  @venizia/
+  dev-configs ignis-      ignis-     ignis-     ignis
+              inversion   helpers    boot       (core)
+```
+
+**Dependency meanings:**
+| Package | Depends On | Purpose |
+|---------|------------|---------|
+| `dev-configs` | - | Shared ESLint, TypeScript configs |
+| `inversion` | dev-configs | IoC container, DI primitives |
+| `helpers` | inversion | Utilities, loggers, crypto |
+| `boot` | helpers | Application bootstrapping |
+| `core` | boot | Full framework (controllers, repos, etc.) |
+
+**Why this matters:**
+- If you modify `helpers`, you must rebuild `boot` and `core`
+- If you modify `inversion`, you must rebuild `helpers`, `boot`, and `core`
+- The Makefile handles this automatically with dependencies
+
 ## Makefile Commands
 
 The project uses a Makefile for common development tasks:
@@ -53,14 +79,15 @@ The project uses a Makefile for common development tasks:
 | `make lint` | Lint all packages |
 | `make help` | Show all available commands |
 
-**Individual package builds:**
+**Individual package builds** (dependencies are automatically resolved):
 ```bash
-make core          # Build @venizia/ignis (after dependencies)
-make boot          # Build @venizia/ignis-boot
-make helpers       # Build @venizia/ignis-helpers
-make inversion     # Build @venizia/ignis-inversion
-make dev-configs   # Build @venizia/dev-configs
-make docs          # Build documentation
+make core          # Build @venizia/ignis (builds dev-configs → inversion → helpers → boot → core)
+make boot          # Build @venizia/ignis-boot (builds dev-configs → inversion → helpers → boot)
+make helpers       # Build @venizia/ignis-helpers (builds dev-configs → inversion → helpers)
+make inversion     # Build @venizia/ignis-inversion (builds dev-configs → inversion)
+make dev-configs   # Build @venizia/dev-configs only
+make docs          # Build VitePress documentation (independent)
+make docs-mcp      # Build MCP documentation server
 ```
 
 **Force update individual packages:**

package/wiki/best-practices/data-modeling.md

@@ -0,0 +1,376 @@
+# 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` (text, number, or big-number) |
+| `generatePrincipalColumnDefs` | Adds polymorphic relation fields | `{discriminator}Id`, `{discriminator}Type` |
+| `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 text Primary Key with UUID default
+    ...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),
+  ]
+);
+```
+
+### ID Type Options
+
+The `generateIdColumnDefs` enricher supports multiple ID strategies:
+
+| Data Type | PostgreSQL Type | JavaScript Type | Use Case |
+|-----------|-----------------|-----------------|----------|
+| `string` | `TEXT` | `string` | UUIDs, custom IDs, distributed systems |
+| `number` | `INTEGER GENERATED ALWAYS AS IDENTITY` | `number` | Auto-increment, simple sequences |
+| `big-number` (mode: `number`) | `BIGINT GENERATED ALWAYS AS IDENTITY` | `number` | Large sequences (up to 2^53) |
+| `big-number` (mode: `bigint`) | `BIGINT GENERATED ALWAYS AS IDENTITY` | `bigint` | Very large sequences (up to 2^64) |
+
+**Examples:**
+
+```typescript
+// String ID with default UUID generator
+...generateIdColumnDefs({ id: { dataType: 'string' } })
+// Result: id TEXT PRIMARY KEY DEFAULT crypto.randomUUID()
+
+// String ID with custom generator (e.g., nanoid, ulid)
+import { nanoid } from 'nanoid';
+...generateIdColumnDefs({ id: { dataType: 'string', generator: () => nanoid() } })
+
+// Auto-increment integer
+...generateIdColumnDefs({ id: { dataType: 'number' } })
+// Result: id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY
+
+// Big integer for large datasets (JavaScript number - up to 2^53)
+...generateIdColumnDefs({ id: { dataType: 'big-number', numberMode: 'number' } })
+
+// Big integer with native BigInt (up to 2^64)
+...generateIdColumnDefs({ id: { dataType: 'big-number', numberMode: 'bigint' } })
+
+// With sequence options
+...generateIdColumnDefs({
+  id: {
+    dataType: 'number',
+    sequenceOptions: { startWith: 1000, increment: 1 },
+  },
+})
+```
+
+### Principal Enricher (Polymorphic Relations)
+
+Use `generatePrincipalColumnDefs` when a record can belong to different entity types (polymorphic relationship).
+
+**Use Case:** A `Comment` can belong to either a `Post` or a `Product`.
+
+```typescript
+import { generateIdColumnDefs, generatePrincipalColumnDefs } from '@venizia/ignis';
+import { pgTable, text } from 'drizzle-orm/pg-core';
+
+export const commentTable = pgTable('Comment', {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+
+  // Polymorphic relation: commentable can be Post or Product
+  ...generatePrincipalColumnDefs({
+    discriminator: 'commentable',      // Field prefix
+    polymorphicIdType: 'string',       // ID type of related entities
+    defaultPolymorphic: 'Post',        // Default type
+  }),
+
+  content: text('content').notNull(),
+});
+
+// Generated columns:
+// - commentableId: TEXT NOT NULL
+// - commentableType: TEXT DEFAULT 'Post'
+```
+
+**Querying polymorphic relations:**
+```typescript
+// Find all comments on a specific post
+const comments = await commentRepo.find({
+  filter: {
+    where: {
+      commentableType: 'Post',
+      commentableId: postId,
+    },
+  },
+});
+
+// Find all comments on a product
+const productComments = await commentRepo.find({
+  filter: {
+    where: {
+      commentableType: 'Product',
+      commentableId: productId,
+    },
+  },
+});
+```
+
+## 3. Defining Relations
+
+Relations are defined using the `TRelationConfig` structure within the static `relations` method of your model.
+
+### Relation Types
+
+| Type | Constant | Description | Example |
+|------|----------|-------------|---------|
+| One-to-One | `RelationTypes.ONE` | Single related record | User → Profile |
+| One-to-Many | `RelationTypes.MANY` | Multiple related records | User → Posts |
+
+### Basic Relations
+
+**One-to-One (belongsTo):**
+```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> {
+  static override schema = pgTable('Configuration', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    createdBy: text('created_by'),
+    // ...
+  });
+
+  // Define relations
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'creator',               // Relation name used in include
+      type: RelationTypes.ONE,       // One Configuration → One User
+      schema: User.schema,           // Related entity's schema
+      metadata: {
+        fields: [Configuration.schema.createdBy],  // Foreign key
+        references: [User.schema.id],              // Primary key
+      },
+    },
+  ];
+}
+```
+
+**One-to-Many (hasMany):**
+```typescript
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    name: text('name').notNull(),
+  });
+
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'posts',                 // User.posts
+      type: RelationTypes.MANY,      // One User → Many Posts
+      schema: Post.schema,
+      metadata: {
+        fields: [User.schema.id],
+        references: [Post.schema.authorId],
+      },
+    },
+    {
+      name: 'comments',              // User.comments
+      type: RelationTypes.MANY,
+      schema: Comment.schema,
+      metadata: {
+        fields: [User.schema.id],
+        references: [Comment.schema.userId],
+      },
+    },
+  ];
+}
+```
+
+### Using Relations in Queries
+
+```typescript
+// Eager load single relation
+const configs = await configRepo.find({
+  filter: {
+    include: [{ relation: 'creator' }],
+  },
+});
+// Result: [{ id, code, ..., creator: { id, name, email } }]
+
+// Eager load multiple relations
+const users = await userRepo.find({
+  filter: {
+    include: [
+      { relation: 'posts' },
+      { relation: 'comments' },
+    ],
+  },
+});
+
+// Nested relations (up to 2 levels recommended)
+const users = await userRepo.find({
+  filter: {
+    include: [{
+      relation: 'posts',
+      scope: {
+        include: [{ relation: 'comments' }],
+      },
+    }],
+  },
+});
+```
+
+> [!TIP]
+> Avoid deeply nested includes (more than 2 levels). Each level adds query complexity. For complex data fetching, consider separate queries.
+
+## 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 } } });
+  }
+}
+```
+
+## 5. Hidden Properties
+
+Protect sensitive data by configuring properties that are excluded at the SQL level. Hidden properties are **never returned** through repository queries.
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    hiddenProperties: ['password', 'secret'],
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    email: text('email').notNull(),
+    password: text('password'),  // Never returned via repository
+    secret: text('secret'),      // Never returned via repository
+  });
+}
+```
+
+**Key points:**
+
+- Hidden properties are excluded from SELECT, INSERT RETURNING, UPDATE RETURNING, DELETE RETURNING
+- You can still **filter by** hidden properties in where clauses
+- Hidden properties are **recursively excluded** from included relations
+- Use the connector directly when you need to access hidden data (e.g., password verification)
+
+> **Reference:** See [Hidden Properties](../references/base/models.md#hidden-properties) for complete documentation.