@venizia/ignis-docs 0.0.3 → 0.0.4-0

package/wiki/references/base/repositories/index.md

@@ -0,0 +1,228 @@
+# Repositories Overview
+
+Repositories are the data access layer in Ignis - they provide type-safe CRUD operations for your database entities.
+
+**Files:** `packages/core/src/base/repositories/core/*.ts`
+
+
+## Quick Start
+
+If you're new to repositories, start here:
+
+```typescript
+import { DefaultCRUDRepository, repository } from '@venizia/ignis';
+import { Todo } from '@/models/todo.model';
+import { PostgresDataSource } from '@/datasources/postgres.datasource';
+
+@repository({ model: Todo, dataSource: PostgresDataSource })
+export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
+  // That's it! You get: find, findOne, create, updateById, deleteById, etc.
+}
+```
+
+
+## Repository Classes
+
+| Class | Capabilities | Use Case |
+|-------|--------------|----------|
+| **AbstractRepository** | Base class with properties | Extend for custom repositories |
+| **ReadableRepository** | Read-only operations | Views, external tables |
+| **PersistableRepository** | Read + Write operations | Rarely used directly |
+| **DefaultCRUDRepository** | Full CRUD operations | Standard data tables |
+
+**Most common:** Extend `DefaultCRUDRepository` for standard tables.
+
+
+## Available Methods
+
+### Read Operations
+| Method | Description | Example |
+|--------|-------------|---------|
+| `find(opts)` | Find multiple records | `repo.find({ filter: { where: { status: 'active' } } })` |
+| `findOne(opts)` | Find single record | `repo.findOne({ filter: { where: { email } } })` |
+| `findById(opts)` | Find by primary key | `repo.findById({ id: '123' })` |
+| `count(opts)` | Count matching records | `repo.count({ where: { status: 'active' } })` |
+| `existsWith(opts)` | Check if exists | `repo.existsWith({ where: { email } })` |
+
+### Write Operations
+| Method | Description | Example |
+|--------|-------------|---------|
+| `create(opts)` | Create single record | `repo.create({ data: { title: 'New' } })` |
+| `createAll(opts)` | Create multiple records | `repo.createAll({ data: [{ title: 'A' }, { title: 'B' }] })` |
+| `updateById(opts)` | Update by primary key | `repo.updateById({ id: '123', data: { title: 'Updated' } })` |
+| `updateAll(opts)` | Update matching records | `repo.updateAll({ where: { status: 'draft' }, data: { status: 'published' } })` |
+| `deleteById(opts)` | Delete by primary key | `repo.deleteById({ id: '123' })` |
+| `deleteAll(opts)` | Delete matching records | `repo.deleteAll({ where: { status: 'archived' } })` |
+
+
+## Documentation Sections
+
+This documentation is split into focused guides:
+
+### [Filter System](/references/base/filter-system/)
+Complete reference for querying data - operators, JSON filtering, array operators, default filters, and query patterns.
+
+```typescript
+// Preview
+await repo.find({
+  filter: {
+    where: {
+      status: 'active',
+      age: { gte: 18 },
+      'metadata.priority': { gte: 3 },
+      tags: { contains: ['featured'] }
+    },
+    order: ['createdAt DESC'],
+    limit: 20
+  }
+});
+```
+
+### [Relations & Includes](./relations.md)
+Fetch related data using `include` for eager loading and nested queries.
+
+```typescript
+// Preview
+await repo.find({
+  filter: {
+    include: [{
+      relation: 'posts',
+      scope: { where: { published: true } }
+    }]
+  }
+});
+```
+
+### [Advanced Features](./advanced.md)
+Transactions, hidden properties, default filter bypass, performance optimization, and type inference.
+
+```typescript
+// Preview
+const tx = await repo.beginTransaction();
+try {
+  await repo.create({ data, options: { transaction: tx } });
+  await tx.commit();
+} catch (e) {
+  await tx.rollback();
+}
+```
+
+### [Repository Mixins](./mixins.md)
+Composable mixins for repository features - `DefaultFilterMixin` and `FieldsVisibilityMixin`.
+
+
+## @repository Decorator
+
+**Both `model` AND `dataSource` are required** for schema auto-discovery:
+
+```typescript
+// ❌ WRONG - Missing dataSource
+@repository({ model: User })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+
+// ❌ WRONG - Missing model
+@repository({ dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+
+// ✅ CORRECT
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+```
+
+### Zero Boilerplate Pattern (Recommended)
+
+DataSource is auto-injected - no constructor needed:
+
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // Custom methods only - no boilerplate!
+
+  async findByEmail(opts: { email: string }) {
+    return this.findOne({ filter: { where: { email: opts.email } } });
+  }
+}
+```
+
+### Explicit @inject Pattern
+
+When you need constructor control:
+
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    dataSource: PostgresDataSource,
+  ) {
+    super(dataSource);
+  }
+}
+```
+
+
+## Safety Features
+
+### Empty Where Protection
+
+Prevents accidental mass updates/deletes:
+
+```typescript
+// ❌ Throws error - empty where without force flag
+await repo.deleteAll({ where: {} });
+
+// ✅ Explicitly allow with force flag (logs warning)
+await repo.deleteAll({ where: {}, options: { force: true } });
+```
+
+| Scenario | `force: false` (default) | `force: true` |
+|----------|-------------------------|---------------|
+| Empty `where` | Throws error | Logs warning, proceeds |
+| Valid `where` | Executes normally | Executes normally |
+
+
+## Quick Reference
+
+| Want to... | Code |
+|------------|------|
+| Find all active | `repo.find({ filter: { where: { status: 'active' } } })` |
+| Find by ID | `repo.findById({ id: '123' })` |
+| Find with relations | `repo.find({ filter: { include: [{ relation: 'posts' }] } })` |
+| Create one | `repo.create({ data: { name: 'John' } })` |
+| Update by ID | `repo.updateById({ id: '123', data: { name: 'Jane' } })` |
+| Delete by ID | `repo.deleteById({ id: '123' })` |
+| Count matching | `repo.count({ where: { status: 'active' } })` |
+| Check exists | `repo.existsWith({ where: { email: 'test@example.com' } })` |
+
+
+## Next Steps
+
+- **New to filtering?** Start with [Filter System](/references/base/filter-system/)
+- **Need related data?** See [Relations & Includes](./relations.md)
+- **Need transactions?** Go to [Advanced Features](./advanced.md)
+
+## See Also
+
+- **Related Concepts:**
+  - [Repositories Guide](/guides/core-concepts/persistent/repositories) - Creating repositories tutorial
+  - [Models](/guides/core-concepts/persistent/models) - Entity definitions used by repositories
+  - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
+  - [Services](/guides/core-concepts/persistent/services) - Use repositories for data access
+  - [Transactions](/guides/core-concepts/persistent/transactions) - Multi-operation consistency
+
+- **Repository Topics:**
+  - [Relations & Includes](./relations) - Loading related data
+  - [Advanced Features](./advanced) - JSON queries, performance tuning, transactions
+  - [Repository Mixins](./mixins) - Soft delete and auditing
+
+- **Filtering:**
+  - [Filter System Overview](/references/base/filter-system/) - Complete filtering guide
+  - [Filter Quick Reference](/references/base/filter-system/quick-reference) - All operators cheat sheet
+
+- **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/references/base/repositories/mixins.md

@@ -0,0 +1,331 @@
+---
+title: Repository Mixins
+description: Composable mixins for repository functionality
+difficulty: intermediate
+lastUpdated: 2026-01-02
+---
+
+# Repository Mixins <Badge type="tip" text="v0.0.5+" />
+
+Composable mixins that provide reusable functionality for repository classes.
+
+::: info Refactored in v0.0.5
+Repository mixins were extracted and refactored in v0.0.5 to provide better composition and reusability.
+:::
+
+**Files:** `packages/core/src/base/repositories/mixins/`
+
+
+## Overview
+
+Ignis uses the mixin pattern to compose repository features. This enables:
+
+- **Separation of concerns** - Each mixin handles one responsibility
+- **Reusability** - Mixins can be applied to different base classes
+- **Testability** - Individual features can be tested in isolation
+- **Flexibility** - Create custom repositories with only needed features
+
+
+## Available Mixins
+
+| Mixin | Responsibility |
+|-------|----------------|
+| `DefaultFilterMixin` | Automatic filter application from model settings |
+| `FieldsVisibilityMixin` | Hidden properties exclusion |
+
+
+## DefaultFilterMixin
+
+Provides automatic default filter application for all repository queries.
+
+**File:** `packages/core/src/base/repositories/mixins/default-filter.ts`
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `_defaultFilter` | `TFilter \| null \| undefined` | Cached default filter |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getDefaultFilter()` | `TFilter \| undefined` | Get default filter from model metadata |
+| `hasDefaultFilter()` | `boolean` | Check if model has a default filter configured |
+| `applyDefaultFilter(opts)` | `TFilter` | Merge default filter with user filter |
+
+### Usage
+
+```typescript
+import { DefaultFilterMixin } from '@venizia/ignis';
+import { BaseHelper } from '@venizia/ignis-helpers';
+
+class MyRepository extends DefaultFilterMixin(BaseHelper) {
+  // Required abstract implementations
+  abstract getEntity(): BaseEntity;
+  abstract get filterBuilder(): FilterBuilder;
+
+  // Now has access to:
+  // - getDefaultFilter()
+  // - hasDefaultFilter()
+  // - applyDefaultFilter()
+}
+```
+
+### applyDefaultFilter Options
+
+```typescript
+interface ApplyDefaultFilterOptions {
+  userFilter?: TFilter;        // User-provided filter
+  shouldSkipDefaultFilter?: boolean; // If true, bypass default filter
+}
+```
+
+### Implementation
+
+```typescript
+applyDefaultFilter<DataObject = any>(opts: {
+  userFilter?: TFilter<DataObject>;
+  shouldSkipDefaultFilter?: boolean;
+}): TFilter<DataObject> {
+  const { userFilter, shouldSkipDefaultFilter } = opts;
+
+  // Skip default filter if explicitly requested
+  if (shouldSkipDefaultFilter) {
+    return userFilter ?? {};
+  }
+
+  // Get default filter from model metadata
+  const defaultFilter = this.getDefaultFilter();
+
+  // No default filter configured - return user filter
+  if (!defaultFilter) {
+    return userFilter ?? {};
+  }
+
+  // Merge default filter with user filter
+  return this.filterBuilder.mergeFilter({ defaultFilter, userFilter });
+}
+```
+
+
+## FieldsVisibilityMixin
+
+Provides hidden properties management for SQL-level field exclusion.
+
+**File:** `packages/core/src/base/repositories/mixins/fields-visibility.ts`
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `_hiddenProperties` | `Set<string> \| null` | Cached hidden property names |
+| `_visibleProperties` | `Record<string, any> \| null \| undefined` | Cached visible columns |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get hiddenProperties` | `Set<string>` | Get hidden property names |
+| `set hiddenProperties` | `void` | Override hidden properties |
+| `getHiddenProperties()` | `Set<string>` | Get hidden properties from model metadata |
+| `hasHiddenProperties()` | `boolean` | Check if model has hidden properties |
+| `get visibleProperties` | `Record<string, any> \| undefined` | Get visible columns for Drizzle |
+| `set visibleProperties` | `void` | Override visible properties |
+| `getVisibleProperties()` | `Record<string, any> \| undefined` | Build visible columns object |
+
+### Usage
+
+```typescript
+import { FieldsVisibilityMixin } from '@venizia/ignis';
+import { BaseHelper } from '@venizia/ignis-helpers';
+
+class MyRepository extends FieldsVisibilityMixin(BaseHelper) {
+  // Required abstract implementation
+  abstract getEntity(): BaseEntity;
+
+  // Now has access to:
+  // - hiddenProperties (getter/setter)
+  // - visibleProperties (getter/setter)
+  // - getHiddenProperties()
+  // - hasHiddenProperties()
+  // - getVisibleProperties()
+}
+```
+
+### Visible Properties for Drizzle
+
+The `getVisibleProperties()` method returns a columns object for Drizzle's `select()` or `returning()`:
+
+```typescript
+// Model with hiddenProperties: ['password', 'apiKey']
+// Schema columns: { id, email, password, apiKey, createdAt }
+
+const visibleProps = this.getVisibleProperties();
+// Result: { id: column, email: column, createdAt: column }
+// (password and apiKey excluded)
+
+// Used in Drizzle queries
+await connector.select(visibleProps).from(schema);
+// SELECT id, email, created_at FROM users
+```
+
+
+## Mixin Composition
+
+The `AbstractRepository` composes multiple mixins:
+
+```typescript
+export abstract class AbstractRepository<...>
+  extends DefaultFilterMixin(FieldsVisibilityMixin(BaseHelper))
+  implements IPersistableRepository<...>
+{
+  // Inherits from both mixins:
+  // From DefaultFilterMixin:
+  //   - getDefaultFilter()
+  //   - hasDefaultFilter()
+  //   - applyDefaultFilter()
+  //
+  // From FieldsVisibilityMixin:
+  //   - hiddenProperties
+  //   - visibleProperties
+  //   - getHiddenProperties()
+  //   - hasHiddenProperties()
+  //   - getVisibleProperties()
+}
+```
+
+### Composition Order
+
+Mixins are applied right-to-left:
+
+```typescript
+// FieldsVisibilityMixin applied first (to BaseHelper)
+// DefaultFilterMixin applied second (to the result)
+DefaultFilterMixin(FieldsVisibilityMixin(BaseHelper))
+```
+
+
+## Creating Custom Mixins
+
+Follow the TypeScript mixin pattern:
+
+```typescript
+import { TMixinTarget } from '@venizia/ignis-helpers';
+
+export const AuditLogMixin = <T extends TMixinTarget<object>>(baseClass: T) => {
+  abstract class Mixed extends baseClass {
+    // Properties
+    private _auditEnabled: boolean = true;
+
+    // Abstract dependencies (if needed)
+    abstract getEntity(): BaseEntity;
+
+    // Public methods
+    enableAudit(): void {
+      this._auditEnabled = true;
+    }
+
+    disableAudit(): void {
+      this._auditEnabled = false;
+    }
+
+    isAuditEnabled(): boolean {
+      return this._auditEnabled;
+    }
+
+    logOperation(operation: string, data: any): void {
+      if (this._auditEnabled) {
+        console.log(`[${this.getEntity().name}] ${operation}:`, data);
+      }
+    }
+  }
+
+  return Mixed;
+};
+```
+
+### Using Custom Mixins
+
+```typescript
+// Compose with existing mixins
+class MyRepository extends AuditLogMixin(DefaultFilterMixin(BaseHelper)) {
+  getEntity() {
+    return this._entity;
+  }
+
+  get filterBuilder() {
+    return this._filterBuilder;
+  }
+}
+
+// Or create a composed base
+const AuditableRepository = AuditLogMixin(DefaultFilterMixin(FieldsVisibilityMixin(BaseHelper)));
+
+class ProductRepository extends AuditableRepository {
+  // Has all mixin functionality
+}
+```
+
+
+## Caching Behavior
+
+Both mixins use caching for performance:
+
+```typescript
+// DefaultFilterMixin caching
+// null = not computed yet
+// undefined = computed, no default filter
+// TFilter = computed, has default filter
+private _defaultFilter: TFilter | null | undefined = null;
+
+getDefaultFilter() {
+  if (this._defaultFilter !== null) {
+    return this._defaultFilter;  // Return cached value
+  }
+  // Compute and cache...
+}
+
+// FieldsVisibilityMixin caching
+// null = not computed yet
+// Set<string> = computed
+private _hiddenProperties: Set<string> | null = null;
+
+// null = not computed yet
+// undefined = computed, no hidden properties
+// Record<string, any> = computed, has hidden properties
+private _visibleProperties: Record<string, any> | null | undefined = null;
+```
+
+
+## Quick Reference
+
+| Mixin | Method | Purpose |
+|-------|--------|---------|
+| `DefaultFilterMixin` | `hasDefaultFilter()` | Check if default filter exists |
+| `DefaultFilterMixin` | `getDefaultFilter()` | Get raw default filter |
+| `DefaultFilterMixin` | `applyDefaultFilter()` | Merge filters |
+| `FieldsVisibilityMixin` | `hasHiddenProperties()` | Check if hidden props exist |
+| `FieldsVisibilityMixin` | `getHiddenProperties()` | Get hidden property names |
+| `FieldsVisibilityMixin` | `getVisibleProperties()` | Get Drizzle columns object |
+
+
+## Next Steps
+
+- [Default Filter](../filter-system/default-filter.md) - Full default filter documentation
+- [Advanced Features](./advanced.md) - Hidden properties usage
+- [Repository Overview](./index.md) - Repository basics
+
+## See Also
+
+- **Related Concepts:**
+  - [Repositories Overview](./index) - Core repository operations
+  - [Models](/guides/core-concepts/persistent/models) - Entity definitions
+
+- **Related Topics:**
+  - [Default Filter](../filter-system/default-filter) - Automatic filtering
+  - [Advanced Features](./advanced) - Hidden properties and transactions
+  - [Relations & Includes](./relations) - Loading related data
+
+- **Best Practices:**
+  - [Data Modeling](/best-practices/data-modeling) - Soft delete patterns