@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/guides/core-concepts/persistent/models.md

@@ -0,0 +1,241 @@
+# Models
+
+Models define your data structure using Drizzle ORM schemas. A model is a single class with static properties for schema and relations.
+
+## Creating a Basic Model
+
+```typescript
+// src/models/entities/user.model.ts
+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> {
+  // Define schema as static property
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...extraUserColumns({ idType: 'string' }),
+  });
+
+  // Relations (empty array if none)
+  static override relations = () => [];
+}
+```
+
+**Key points:**
+
+- Schema is defined inline as `static override schema`
+- Relations are defined as `static override relations`
+- No constructor needed - BaseEntity auto-discovers from static properties
+- Type parameter uses `typeof User.schema` (self-referencing)
+
+## Creating a Model with Relations
+
+```typescript
+// src/models/entities/configuration.model.ts
+import {
+  BaseEntity,
+  generateDataTypeColumnDefs,
+  generateIdColumnDefs,
+  generateTzColumnDefs,
+  generateUserAuditColumnDefs,
+  model,
+  RelationTypes,
+  TRelationConfig,
+} from '@venizia/ignis';
+import { foreignKey, index, pgTable, text, unique } from 'drizzle-orm/pg-core';
+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' } }),
+      ...generateTzColumnDefs(),
+      ...generateDataTypeColumnDefs(),
+      ...generateUserAuditColumnDefs({
+        created: { dataType: 'string', columnName: 'created_by' },
+        modified: { dataType: 'string', columnName: 'modified_by' },
+      }),
+      code: text('code').notNull(),
+      description: text('description'),
+      group: text('group').notNull(),
+    },
+    def => [
+      unique('UQ_Configuration_code').on(def.code),
+      index('IDX_Configuration_group').on(def.group),
+      foreignKey({
+        columns: [def.createdBy],
+        foreignColumns: [User.schema.id], // Reference User.schema, not a separate variable
+        name: 'FK_Configuration_createdBy_User_id',
+      }),
+    ],
+  );
+
+  // Define relations using TRelationConfig array
+  static override relations = (): TRelationConfig[] => [
+    {
+      name: 'creator',
+      type: RelationTypes.ONE,
+      schema: User.schema,
+      metadata: {
+        fields: [Configuration.schema.createdBy],
+        references: [User.schema.id],
+      },
+    },
+    {
+      name: 'modifier',
+      type: RelationTypes.ONE,
+      schema: User.schema,
+      metadata: {
+        fields: [Configuration.schema.modifiedBy],
+        references: [User.schema.id],
+      },
+    },
+  ];
+}
+```
+
+**Key points:**
+
+- Relations use `TRelationConfig[]` format directly
+- Reference other models via `Model.schema` (e.g., `User.schema.id`)
+- Relation names (`creator`, `modifier`) are used in queries with `include`
+
+## Understanding Enrichers
+
+Enrichers are helper functions that generate common database columns automatically.
+
+**Without enrichers:**
+
+```typescript
+static override schema = pgTable('User', {
+  id: text('id').primaryKey().$defaultFn(() => crypto.randomUUID()),
+  status: text('status').notNull().default('ACTIVE'),
+  createdBy: text('created_by'),
+  modifiedBy: text('modified_by'),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  modifiedAt: timestamp('modified_at', { withTimezone: true }).notNull().defaultNow(),
+  // ... your fields
+});
+```
+
+**With enrichers:**
+
+```typescript
+static override schema = pgTable('User', {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),  // id (text with UUID default)
+  ...extraUserColumns({ idType: 'string' }),                 // status, audit fields, timestamps
+  // ... your fields
+});
+```
+
+### Available Enrichers
+
+| Enricher | Columns Added | Use Case |
+|----------|---------------|----------|
+| `generateIdColumnDefs()` | `id` (text or number) | Every table |
+| `generateTzColumnDefs()` | `createdAt`, `modifiedAt` | Track timestamps |
+| `generateUserAuditColumnDefs()` | `createdBy`, `modifiedBy` | Track who created/updated |
+| `generateDataTypeColumnDefs()` | `dataType`, `tValue`, `nValue`, etc. | Configuration tables |
+| `extraUserColumns()` | Combines audit + status + type | Full-featured entities |
+
+:::tip
+For a complete list of enrichers and options, see the [Schema Enrichers Reference](../../../references/base/models.md#schema-enrichers).
+:::
+
+## Hidden Properties
+
+Protect sensitive data by configuring properties that are **never returned** through repository queries. Hidden properties are excluded at the SQL level for maximum security and performance.
+
+```typescript
+import { BaseEntity, generateIdColumnDefs, model } from '@venizia/ignis';
+import { pgTable, text } from 'drizzle-orm/pg-core';
+
+@model({
+  type: 'entity',
+  settings: {
+    hiddenProperties: ['password', 'secret'],  // Never returned via repository
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    email: text('email').notNull(),
+    password: text('password'),  // Hidden from queries
+    secret: text('secret'),      // Hidden from queries
+  });
+}
+```
+
+**Behavior:**
+
+| Operation | Behavior |
+|-----------|----------|
+| `find()`, `findOne()`, `findById()` | Hidden excluded from SELECT |
+| `create()`, `updateById()`, `deleteById()` | Hidden excluded from RETURNING |
+| Where clause filtering | Hidden fields **can** be used in filters |
+| Direct connector query | Hidden fields **included** (bypasses repository) |
+
+When you need to access hidden data, use the connector directly:
+
+```typescript
+// Repository query - excludes hidden
+const user = await userRepo.findById({ id: '123' });
+// { id: '123', email: 'john@example.com' }
+
+// Connector query - includes all fields
+const connector = userRepo.getConnector();
+const [fullUser] = await connector
+  .select()
+  .from(User.schema)
+  .where(eq(User.schema.id, '123'));
+// { id: '123', email: 'john@example.com', password: '...', secret: '...' }
+```
+
+:::tip
+For complete hidden properties documentation, see the [Models Reference](../../../references/base/models.md#hidden-properties).
+:::
+
+## Model Template
+
+```typescript
+import { BaseEntity, generateIdColumnDefs, model, TRelationConfig } from '@venizia/ignis';
+import { pgTable, text } from 'drizzle-orm/pg-core';
+
+@model({ type: 'entity' })
+export class MyModel extends BaseEntity<typeof MyModel.schema> {
+  static override schema = pgTable('MyModel', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    name: text('name').notNull(),
+  });
+
+  static override relations = (): TRelationConfig[] => [];
+}
+```
+
+> **Deep Dive:** See [BaseEntity Reference](../../../references/base/models.md#baseentity-class) for advanced patterns.
+
+## See Also
+
+- **Related Concepts:**
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Data access layer using models
+  - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
+  - [Persistent Layer Overview](/guides/core-concepts/persistent/) - Architecture overview
+
+- **References:**
+  - [Models & Enrichers API](/references/base/models) - Complete API reference
+  - [Relations](/references/base/repositories/relations) - Defining model relationships
+  - [Filter System](/references/base/filter-system/) - Querying models
+
+- **External Resources:**
+  - [Drizzle ORM Documentation](https://orm.drizzle.team/) - Schema definition guide
+  - [PostgreSQL Data Types](https://www.postgresql.org/docs/current/datatype.html) - Column types reference
+
+- **Best Practices:**
+  - [Data Modeling](/best-practices/data-modeling) - Schema design patterns
+
+- **Tutorials:**
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Model examples
+  - [E-commerce API](/guides/tutorials/ecommerce-api) - Models with relations

package/wiki/guides/core-concepts/persistent/repositories.md

@@ -0,0 +1,219 @@
+# Repositories
+
+Repositories provide type-safe CRUD operations. Use `@repository` decorator with both `model` and `dataSource` for auto-discovery.
+
+## Pattern 1: Zero Boilerplate (Recommended)
+
+The simplest approach - everything is auto-resolved:
+
+```typescript
+// src/repositories/configuration.repository.ts
+import { Configuration } from '@/models/entities';
+import { PostgresDataSource } from '@/datasources/postgres.datasource';
+import { DefaultCRUDRepository, repository } from '@venizia/ignis';
+
+@repository({
+  model: Configuration,
+  dataSource: PostgresDataSource,
+})
+export class ConfigurationRepository extends DefaultCRUDRepository<typeof Configuration.schema> {
+  // No constructor needed!
+
+  async findByCode(opts: { code: string }) {
+    return this.findOne({ filter: { where: { code: opts.code } } });
+  }
+
+  async findByGroup(opts: { group: string }) {
+    return this.find({ filter: { where: { group: opts.group } } });
+  }
+}
+```
+
+## Pattern 2: Explicit @inject
+
+When you need constructor control (e.g., read-only repository or additional dependencies):
+
+```typescript
+// src/repositories/user.repository.ts
+import { User } from '@/models/entities';
+import { PostgresDataSource } from '@/datasources/postgres.datasource';
+import { inject, ReadableRepository, repository } from '@venizia/ignis';
+import { CacheService } from '@/services/cache.service';
+
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends ReadableRepository<typeof User.schema> {
+  constructor(
+    // First parameter MUST be DataSource injection
+    @inject({ key: 'datasources.PostgresDataSource' })
+    dataSource: PostgresDataSource, // Must be concrete type, not 'any'
+
+    // After first arg, you can inject any additional dependencies
+    @inject({ key: 'some.cache' })
+    private cache: SomeCache,
+  ) {
+    super(dataSource);
+  }
+
+  async findByRealm(opts: { realm: string }) {
+    // Use injected dependencies
+    const cached = await this.cache.get(`user:realm:${opts.realm}`);
+    if (cached) {
+      return cached;
+    }
+
+    return this.findOne({ filter: { where: { realm: opts.realm } } });
+  }
+}
+```
+
+> **Important:**
+> - First constructor parameter **MUST** be the DataSource injection
+> - After the first argument, you can inject any additional dependencies you need
+> - When `@inject` is at param index 0, auto-injection is skipped
+
+## Repository Types
+
+| Type | Description |
+|------|-------------|
+| `DefaultCRUDRepository` | Full read/write operations |
+| `ReadableRepository` | Read-only operations |
+| `PersistableRepository` | Write operations only |
+
+## Querying Data
+
+For advanced filtering with operators like `gt`, `lt`, `like`, `in`, `between`, and more, see [Filter System](../../../references/base/filter-system/).
+
+```typescript
+const repo = this.get<ConfigurationRepository>({ key: 'repositories.ConfigurationRepository' });
+
+// Find multiple records
+const configs = await repo.find({
+  filter: {
+    where: { group: 'SYSTEM' },
+    limit: 10,
+    order: ['createdAt DESC'],
+  }
+});
+
+// Find one record
+const config = await repo.findOne({
+  filter: { where: { code: 'APP_NAME' } }
+});
+
+// Select specific fields (array format)
+const configCodes = await repo.find({
+  filter: {
+    fields: ['id', 'code', 'group'],  // Only these fields returned
+    limit: 100,
+  }
+});
+
+// Order by JSON/JSONB nested fields
+const sorted = await repo.find({
+  filter: {
+    order: ['metadata.priority DESC', 'createdAt ASC'],
+  }
+});
+
+// Create a record
+const newConfig = await repo.create({
+  data: {
+    code: 'NEW_SETTING',
+    group: 'SYSTEM',
+    description: 'A new setting',
+  }
+});
+
+// Update by ID
+await repo.updateById({
+  id: 'uuid-here',
+  data: { description: 'Updated description' }
+});
+
+// Delete by ID
+await repo.deleteById({ id: 'uuid-here' });
+```
+
+## Querying with Relations
+
+Use `include` to fetch related data. The relation name must match what you defined in `static relations`:
+
+```typescript
+const configWithCreator = await repo.findOne({
+  filter: {
+    where: { code: 'APP_NAME' },
+    include: [{ relation: 'creator' }],
+  },
+});
+
+console.log('Created by:', configWithCreator.creator.name);
+```
+
+## Registering Repositories
+
+```typescript
+// src/application.ts
+export class Application extends BaseApplication {
+  preConfigure(): ValueOrPromise<void> {
+    this.dataSource(PostgresDataSource);
+    this.repository(UserRepository);
+    this.repository(ConfigurationRepository);
+  }
+}
+```
+
+## Repository Template
+
+```typescript
+import { DefaultCRUDRepository, repository } from '@venizia/ignis';
+import { MyModel } from '@/models/entities';
+import { PostgresDataSource } from '@/datasources/postgres.datasource';
+
+@repository({ model: MyModel, dataSource: PostgresDataSource })
+export class MyModelRepository extends DefaultCRUDRepository<typeof MyModel.schema> {}
+```
+
+## Advanced Topics
+
+### Performance: Core API Optimization
+
+Ignis automatically optimizes "flat" queries (no relations, no field selection) by using Drizzle's Core API. This provides **~15-20% faster** queries for simple reads.
+
+### Modular Persistence with Components
+
+Bundle related persistence resources into Components for better organization:
+
+```typescript
+export class UserManagementComponent extends BaseComponent {
+  override binding() {
+    this.application.dataSource(PostgresDataSource);
+    this.application.repository(UserRepository);
+    this.application.repository(ProfileRepository);
+  }
+}
+```
+
+> **Deep Dive:** See [Repository Reference](../../../references/base/repositories/) for filtering operators, relations, JSON path queries, and array operators.
+
+## See Also
+
+- **Related Concepts:**
+  - [Models](/guides/core-concepts/persistent/models) - Entity definitions used by repositories
+  - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
+  - [Services](/guides/core-concepts/services) - Use repositories for data access
+  - [Transactions](/guides/core-concepts/persistent/transactions) - Multi-operation consistency
+
+- **References:**
+  - [Repositories API](/references/base/repositories/) - Complete API reference
+  - [Filter System](/references/base/filter-system/) - Query operators and filtering
+  - [Relations & Includes](/references/base/repositories/relations) - Loading related data
+  - [Advanced Features](/references/base/repositories/advanced) - JSON queries, performance tuning
+  - [Repository Mixins](/references/base/repositories/mixins) - Soft delete and auditing
+
+- **Best Practices:**
+  - [Data Modeling](/best-practices/data-modeling) - Repository design patterns
+  - [Performance Optimization](/best-practices/performance-optimization) - Query optimization
+
+- **Tutorials:**
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Repository examples
+  - [E-commerce API](/guides/tutorials/ecommerce-api) - Advanced queries and relations

package/wiki/guides/core-concepts/persistent/transactions.md

@@ -0,0 +1,170 @@
+# Transactions
+
+Ignis supports explicit transaction objects that can be passed across multiple services and repositories, allowing for complex, multi-step business logic to be atomic.
+
+## Using Transactions
+
+To use transactions, start one from a repository or datasource, and then pass it to subsequent operations via the `options` parameter.
+
+```typescript
+// 1. Start a transaction
+const tx = await userRepo.beginTransaction({
+  isolationLevel: 'SERIALIZABLE' // Optional, defaults to 'READ COMMITTED'
+});
+
+try {
+  // 2. Pass transaction to operations
+  // Create user
+  const user = await userRepo.create({
+    data: userData,
+    options: { transaction: tx }
+  });
+
+  // Create profile (using same transaction)
+  await profileRepo.create({
+    data: { userId: user.id, ...profileData },
+    options: { transaction: tx }
+  });
+
+  // Call a service method (passing the transaction)
+  await orderService.createInitialOrder({ userId: user.id, transaction: tx });
+
+  // 3. Commit the transaction
+  await tx.commit();
+} catch (err) {
+  // 4. Rollback on error
+  await tx.rollback();
+  throw err;
+}
+```
+
+## Isolation Levels
+
+Ignis supports standard PostgreSQL isolation levels:
+
+| Level | Description | Use Case |
+|-------|-------------|----------|
+| `READ COMMITTED` | (Default) Queries see only data committed before the query began. | General use, prevents dirty reads. |
+| `REPEATABLE READ` | Queries see a snapshot as of the start of the transaction. | Reports, consistent reads across multiple queries. |
+| `SERIALIZABLE` | Strictest level. Emulates serial execution. | Financial transactions, critical data integrity. |
+
+## Best Practices
+
+1.  **Always use `try...catch...finally`**: Ensure `rollback()` is called on error to release the connection.
+2.  **Keep it short**: Long-running transactions hold database locks and connections.
+3.  **Pass explicit options**: When calling other services inside a transaction, ensure they accept and use the `transaction` option.
+
+```typescript
+// Service method supporting transactions
+async createInitialOrder(opts: { userId: string; transaction?: ITransaction }) {
+  return this.orderRepository.create({
+    data: { userId: opts.userId, status: 'PENDING' },
+    options: { transaction: opts.transaction } // Forward the transaction
+  });
+}
+```
+
+## Transaction Pattern with Services
+
+When building services that support transactions, follow this pattern:
+
+```typescript
+export class OrderService extends BaseService {
+  constructor(
+    @inject({ key: 'repositories.OrderRepository' })
+    private _orderRepository: OrderRepository,
+    @inject({ key: 'repositories.OrderItemRepository' })
+    private _orderItemRepository: OrderItemRepository,
+  ) {
+    super({ scope: OrderService.name });
+  }
+
+  async createOrderWithItems(opts: {
+    orderData: TOrderCreate;
+    items: TOrderItemCreate[];
+    transaction?: ITransaction;
+  }) {
+    const { orderData, items, transaction } = opts;
+
+    // Create order
+    const order = await this._orderRepository.create({
+      data: orderData,
+      options: { transaction },
+    });
+
+    // Create order items
+    for (const item of items) {
+      await this._orderItemRepository.create({
+        data: { ...item, orderId: order.id },
+        options: { transaction },
+      });
+    }
+
+    return order;
+  }
+}
+```
+
+## Using from Controllers
+
+```typescript
+@controller({ path: '/orders' })
+export class OrderController extends BaseController {
+  constructor(
+    @inject({ key: 'repositories.OrderRepository' })
+    private _orderRepository: OrderRepository,
+    @inject({ key: 'services.OrderService' })
+    private _orderService: OrderService,
+  ) {
+    super({ scope: OrderController.name, path: '/orders' });
+  }
+
+  @post({ configs: OrderRoutes.CREATE })
+  async createOrder(c: TRouteContext<typeof OrderRoutes.CREATE>) {
+    const body = c.req.valid('json');
+
+    const tx = await this._orderRepository.beginTransaction({
+      isolationLevel: 'SERIALIZABLE',
+    });
+
+    try {
+      const order = await this._orderService.createOrderWithItems({
+        orderData: body.order,
+        items: body.items,
+        transaction: tx,
+      });
+
+      await tx.commit();
+      return c.json(order, HTTP.ResultCodes.RS_2.Created);
+    } catch (err) {
+      await tx.rollback();
+      throw err;
+    }
+  }
+}
+```
+
+> **Deep Dive:** See [Repository Reference](../../../references/base/repositories/) for more transaction options and patterns.
+
+## See Also
+
+- **Related Concepts:**
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Provide transaction API
+  - [Services](/guides/core-concepts/services) - Orchestrate transactional operations
+  - [Controllers](/guides/core-concepts/controllers) - Initiate transactions from HTTP handlers
+  - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
+
+- **References:**
+  - [Repositories API](/references/base/repositories/) - Transaction methods and options
+  - [BaseDataSource API](/references/base/datasources) - Connection and transaction management
+
+- **External Resources:**
+  - [PostgreSQL Transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html) - Transaction fundamentals
+  - [Isolation Levels](https://www.postgresql.org/docs/current/transaction-iso.html) - Understanding isolation levels
+
+- **Best Practices:**
+  - [Data Modeling](/best-practices/data-modeling) - Transaction design patterns
+  - [Common Pitfalls](/best-practices/common-pitfalls) - Transaction anti-patterns
+
+- **Tutorials:**
+  - [E-commerce API](/guides/tutorials/ecommerce-api) - Order creation with transactions

package/wiki/{get-started → guides}/core-concepts/services.md

@@ -36,12 +36,15 @@ export class ConfigurationService extends BaseService {
     super({ scope: ConfigurationService.name });
   }
 
-  async createConfigurationForUser(userId: string, data: Partial<TConfiguration>): Promise<TConfiguration> {
+  async createConfigurationForUser(opts: {
+    userId: string;
+    data: Partial<TConfiguration>;
+  }): Promise<TConfiguration> {
     // Call another service logic
-    await this.loggingService.audit(`Creating config for user: ${userId}`);
+    await this.loggingService.audit({ message: `Creating config for user: ${opts.userId}` });
 
     // Business logic: Check if the user exists
-    const user = await this.userRepository.findById({ id: userId });
+    const user = await this.userRepository.findById({ id: opts.userId });
 // ...
 ```
 
@@ -80,3 +83,23 @@ This layered architecture makes your application:
 -   **More Organized:** Each layer has a clear and distinct responsibility.
 -   **Easier to Test:** You can test your business logic in isolation by providing mock repositories to your services, without needing a live database.
 -   **More Flexible:** You can change your database or data access implementation (e.g., switch from PostgreSQL to MySQL) by only changing the repository and datasource layer, with no changes to your business logic.
+
+## See Also
+
+- **Related Concepts:**
+  - [Controllers](/guides/core-concepts/controllers) - Call services to handle requests
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Data access layer used by services
+  - [Dependency Injection](/guides/core-concepts/dependency-injection) - Injecting dependencies into services
+
+- **References:**
+  - [BaseService API](/references/base/services) - Complete API reference
+  - [Providers](/references/base/providers) - Factory pattern for runtime instantiation
+  - [Logger Helper](/references/helpers/logger) - Logging in services
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns) - Service layer design
+  - [Testing](/guides/tutorials/testing) - Unit testing services
+
+- **Tutorials:**
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Service examples
+  - [E-commerce API](/guides/tutorials/ecommerce-api) - Complex business logic