@venizia/ignis-docs 0.0.7 → 0.0.8-0

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

@@ -29,150 +29,153 @@ Ignis uses the mixin pattern to compose repository features. This enables:
 
 | Mixin | Responsibility |
 |-------|----------------|
+| `FieldsVisibilityMixin` | Hidden properties exclusion at SQL level |
 | `DefaultFilterMixin` | Automatic filter application from model settings |
-| `FieldsVisibilityMixin` | Hidden properties exclusion |
 
 
-## DefaultFilterMixin
+## FieldsVisibilityMixin
 
-Provides automatic default filter application for all repository queries.
+Provides hidden properties management for SQL-level field exclusion. Reads `hiddenProperties` from `@model` metadata settings and builds a visible columns map for Drizzle's `select()` and `returning()` calls.
 
-**File:** `packages/core/src/base/repositories/mixins/default-filter.ts`
+**File:** `packages/core/src/base/repositories/mixins/fields-visibility.ts`
+
+### Abstract Requirements
+
+Classes using this mixin must implement:
+
+```typescript
+abstract getEntity(): BaseEntity<TTableSchemaWithId>;
+```
 
 ### Properties
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `_defaultFilter` | `TFilter \| null \| undefined` | Cached default filter |
+| `_hiddenProperties` | `Set<string> \| null` | Cached hidden property names (`null` = not yet computed) |
+| `_visibleProperties` | `Record<string, any> \| null \| undefined` | Cached visible columns (`null` = not yet computed, `undefined` = computed with no hidden props) |
 
 ### 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 |
+| `get hiddenProperties` | `Set<string>` | Getter that delegates to `getHiddenProperties()` |
+| `set hiddenProperties` | `void` | Override hidden properties set |
+| `getHiddenProperties()` | `Set<string>` | Get hidden properties from model metadata (cached) |
+| `hasHiddenProperties()` | `boolean` | Check if model has any hidden properties |
+| `get visibleProperties` | `Record<string, any> \| undefined` | Getter that delegates to `getVisibleProperties()` |
+| `set visibleProperties` | `void` | Override visible properties |
+| `getVisibleProperties()` | `Record<string, any> \| undefined` | Build visible columns object for Drizzle (cached). Returns `undefined` if no hidden props. |
 
 ### Usage
 
 ```typescript
-import { DefaultFilterMixin } from '@venizia/ignis';
+import { FieldsVisibilityMixin } from '@venizia/ignis';
 import { BaseHelper } from '@venizia/ignis-helpers';
 
-class MyRepository extends DefaultFilterMixin(BaseHelper) {
-  // Required abstract implementations
+class MyRepository extends FieldsVisibilityMixin(BaseHelper) {
+  // Required abstract implementation
   abstract getEntity(): BaseEntity;
-  abstract get filterBuilder(): FilterBuilder;
 
   // Now has access to:
-  // - getDefaultFilter()
-  // - hasDefaultFilter()
-  // - applyDefaultFilter()
+  // - hiddenProperties (getter/setter)
+  // - visibleProperties (getter/setter)
+  // - getHiddenProperties()
+  // - hasHiddenProperties()
+  // - getVisibleProperties()
 }
 ```
 
-### applyDefaultFilter Options
+### Visible Properties for Drizzle
+
+The `getVisibleProperties()` method returns a columns object for Drizzle's `select()` or `returning()`:
 
 ```typescript
-interface ApplyDefaultFilterOptions {
-  userFilter?: TFilter;        // User-provided filter
-  shouldSkipDefaultFilter?: boolean; // If true, bypass default filter
-}
+// 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
 ```
 
-### Implementation
+### How It Resolves Hidden Properties
 
-```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 ?? {};
-  }
+1. Checks the cache (`_hiddenProperties`). If not `null`, returns cached value.
+2. Looks up the entity name in `MetadataRegistry.getModelEntry()`.
+3. Reads `metadata.settings.hiddenProperties` (array of field names).
+4. Converts to a `Set<string>` and caches.
 
-  // Get default filter from model metadata
-  const defaultFilter = this.getDefaultFilter();
 
-  // No default filter configured - return user filter
-  if (!defaultFilter) {
-    return userFilter ?? {};
-  }
+## DefaultFilterMixin
 
-  // Merge default filter with user filter
-  return this.filterBuilder.mergeFilter({ defaultFilter, userFilter });
-}
-```
+Provides automatic default filter application for all repository queries. Reads `defaultFilter` from `@model` metadata settings and merges it with user-provided filters.
 
+**File:** `packages/core/src/base/repositories/mixins/default-filter.ts`
 
-## FieldsVisibilityMixin
+### Abstract Requirements
 
-Provides hidden properties management for SQL-level field exclusion.
+Classes using this mixin must implement:
 
-**File:** `packages/core/src/base/repositories/mixins/fields-visibility.ts`
+```typescript
+abstract getEntity(): BaseEntity<TTableSchemaWithId>;
+abstract get filterBuilder(): FilterBuilder;
+```
 
 ### Properties
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `_hiddenProperties` | `Set<string> \| null` | Cached hidden property names |
-| `_visibleProperties` | `Record<string, any> \| null \| undefined` | Cached visible columns |
+| `_defaultFilter` | `TFilter \| null \| undefined` | Cached default filter (`null` = not yet computed, `undefined` = computed with no default filter) |
 
 ### 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 |
+| `getDefaultFilter()` | `TFilter \| undefined` | Get default filter from model metadata (cached) |
+| `hasDefaultFilter()` | `boolean` | Check if model has a default filter configured |
+| `applyDefaultFilter(opts)` | `TFilter` | Merge default filter with user filter |
 
 ### Usage
 
 ```typescript
-import { FieldsVisibilityMixin } from '@venizia/ignis';
+import { DefaultFilterMixin } from '@venizia/ignis';
 import { BaseHelper } from '@venizia/ignis-helpers';
 
-class MyRepository extends FieldsVisibilityMixin(BaseHelper) {
-  // Required abstract implementation
+class MyRepository extends DefaultFilterMixin(BaseHelper) {
+  // Required abstract implementations
   abstract getEntity(): BaseEntity;
+  abstract get filterBuilder(): FilterBuilder;
 
   // Now has access to:
-  // - hiddenProperties (getter/setter)
-  // - visibleProperties (getter/setter)
-  // - getHiddenProperties()
-  // - hasHiddenProperties()
-  // - getVisibleProperties()
+  // - getDefaultFilter()
+  // - hasDefaultFilter()
+  // - applyDefaultFilter()
 }
 ```
 
-### Visible Properties for Drizzle
-
-The `getVisibleProperties()` method returns a columns object for Drizzle's `select()` or `returning()`:
+### applyDefaultFilter Options
 
 ```typescript
-// Model with hiddenProperties: ['password', 'apiKey']
-// Schema columns: { id, email, password, apiKey, createdAt }
+applyDefaultFilter<DataObject = any>(opts: {
+  userFilter?: TFilter<DataObject>;        // User-provided filter
+  shouldSkipDefaultFilter?: boolean;       // If true, bypass default filter
+}): TFilter<DataObject>
+```
 
-const visibleProps = this.getVisibleProperties();
-// Result: { id: column, email: column, createdAt: column }
-// (password and apiKey excluded)
+**Behavior:**
 
-// Used in Drizzle queries
-await connector.select(visibleProps).from(schema);
-// SELECT id, email, created_at FROM users
-```
+1. If `shouldSkipDefaultFilter` is `true`, returns the user filter as-is (or `{}` if none).
+2. If no default filter is configured, returns the user filter as-is (or `{}` if none).
+3. Otherwise, delegates to `filterBuilder.mergeFilter({ defaultFilter, userFilter })` which deep-merges `where` conditions and uses user values for other filter properties (`order`, `limit`, `offset`, `skip`, `fields`, `include`).
 
 
 ## Mixin Composition
 
-The `AbstractRepository` composes multiple mixins:
+The `AbstractRepository` composes both mixins:
 
 ```typescript
 export abstract class AbstractRepository<...>
@@ -180,17 +183,17 @@ export abstract class AbstractRepository<...>
   implements IPersistableRepository<...>
 {
   // Inherits from both mixins:
-  // From DefaultFilterMixin:
-  //   - getDefaultFilter()
-  //   - hasDefaultFilter()
-  //   - applyDefaultFilter()
-  //
   // From FieldsVisibilityMixin:
-  //   - hiddenProperties
-  //   - visibleProperties
+  //   - hiddenProperties (getter/setter)
+  //   - visibleProperties (getter/setter)
   //   - getHiddenProperties()
   //   - hasHiddenProperties()
   //   - getVisibleProperties()
+  //
+  // From DefaultFilterMixin:
+  //   - getDefaultFilter()
+  //   - hasDefaultFilter()
+  //   - applyDefaultFilter()
 }
 ```
 
@@ -207,7 +210,7 @@ DefaultFilterMixin(FieldsVisibilityMixin(BaseHelper))
 
 ## Creating Custom Mixins
 
-Follow the TypeScript mixin pattern:
+Follow the TypeScript mixin pattern using `TMixinTarget`:
 
 ```typescript
 import { TMixinTarget } from '@venizia/ignis-helpers';
@@ -269,44 +272,46 @@ class ProductRepository extends AuditableRepository {
 
 ## Caching Behavior
 
-Both mixins use caching for performance:
+Both mixins use a three-state caching pattern for performance:
 
 ```typescript
 // DefaultFilterMixin caching
 // null = not computed yet
-// undefined = computed, no default filter
+// undefined = computed, no default filter exists
 // TFilter = computed, has default filter
-private _defaultFilter: TFilter | null | undefined = null;
+_defaultFilter: TFilter | null | undefined = null;
 
 getDefaultFilter() {
   if (this._defaultFilter !== null) {
-    return this._defaultFilter;  // Return cached value
+    return this._defaultFilter;  // Return cached value (either TFilter or undefined)
   }
-  // Compute and cache...
+  // Compute from MetadataRegistry and cache...
 }
 
 // FieldsVisibilityMixin caching
 // null = not computed yet
-// Set<string> = computed
-private _hiddenProperties: Set<string> | null = null;
+// Set<string> = computed (may be empty)
+_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;
+// undefined = computed, no hidden properties exist
+// Record<string, any> = computed, has visible column map
+_visibleProperties: Record<string, any> | null | undefined = null;
 ```
 
+This ensures metadata lookups happen only once per repository instance, with subsequent calls returning the cached value.
+
 
 ## 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 |
+| `FieldsVisibilityMixin` | `getHiddenProperties()` | Get hidden property names as `Set<string>` |
+| `FieldsVisibilityMixin` | `getVisibleProperties()` | Get Drizzle columns object (excludes hidden) |
+| `DefaultFilterMixin` | `hasDefaultFilter()` | Check if default filter exists |
+| `DefaultFilterMixin` | `getDefaultFilter()` | Get raw default filter from model metadata |
+| `DefaultFilterMixin` | `applyDefaultFilter()` | Merge default filter with user filter |
 
 
 ## Next Steps

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

@@ -62,6 +62,9 @@ const post = await postRepo.findOne({
 });
 ```
 
+> [!NOTE]
+> When `include` is present in the filter, the repository uses the **Query API** (`connector.query`) instead of the Core API. This is handled automatically by the `canUseCoreAPI` check in `ReadableRepository`.
+
 
 ## Scoped Includes
 
@@ -138,6 +141,23 @@ const user = await userRepo.findOne({
 });
 ```
 
+### Skip Default Filter on Includes
+
+Each inclusion can independently bypass the related model's default filter:
+
+```typescript
+// Include soft-deleted posts that would normally be filtered out
+const user = await userRepo.findOne({
+  filter: {
+    where: { id: '123' },
+    include: [{
+      relation: 'posts',
+      shouldSkipDefaultFilter: true
+    }]
+  }
+});
+```
+
 
 ## Nested Includes
 
@@ -146,7 +166,7 @@ Include relations of relations (up to 2 levels recommended):
 ### Two-Level Nesting
 
 ```typescript
-// User → Posts → Comments
+// User -> Posts -> Comments
 const user = await userRepo.findOne({
   filter: {
     where: { id: '123' },
@@ -179,7 +199,7 @@ const user = await userRepo.findOne({
 ### Many-to-Many Through Junction
 
 ```typescript
-// Product → SaleChannelProduct (junction) → SaleChannel
+// Product -> SaleChannelProduct (junction) -> SaleChannel
 const product = await productRepo.findOne({
   filter: {
     where: { id: 'prod1' },
@@ -216,7 +236,26 @@ const product = await productRepo.findOne({
 
 ## Defining Relations
 
-Relations must be defined in your model before you can `include` them.
+Relations are defined using the `createRelations` helper and the `TRelationConfig` type. These use Drizzle ORM's relation system under the hood.
+
+### Relation Config Type
+
+```typescript
+type TRelationConfig = {
+  name: string;  // Relation name used in includes
+} & (
+  | {
+      type: 'one';   // one-to-one or many-to-one
+      schema: TTableSchemaWithId;
+      metadata: { fields, references, relationName? };
+    }
+  | {
+      type: 'many';  // one-to-many
+      schema: TTableSchemaWithId;
+      metadata: { relationName? };
+    }
+);
+```
 
 ### In Your Model
 
@@ -230,14 +269,14 @@ export const userTable = pgTable('User', {
   email: text('email').notNull(),
 });
 
-export const userRelations = createRelations({
+const userRelationsConfig = createRelations({
   source: userTable,
   relations: [
     {
-      type: 'hasMany',
-      model: () => Post,       // Target model
-      foreignKey: 'authorId',  // FK in Post table
-      name: 'posts',           // Relation name for includes
+      type: 'many',
+      schema: postTable,
+      name: 'posts',
+      metadata: { relationName: 'posts' },
     },
   ],
 });
@@ -245,45 +284,64 @@ export const userRelations = createRelations({
 @model({ type: 'entity' })
 export class User extends BaseEntity<typeof User.schema> {
   static override schema = userTable;
-  static override relations = () => userRelations.definitions;
+  static override relations = () => userRelationsConfig.definitions;
   static override TABLE_NAME = 'User';
 }
 ```
 
 ### Relation Types
 
-| Type | Description | Example |
-|------|-------------|---------|
-| `hasMany` | One-to-many | User has many Posts |
-| `hasOne` | One-to-one | User has one Profile |
-| `belongsTo` | Inverse of hasMany/hasOne | Post belongs to User |
+| Type | Drizzle Function | Description | Example |
+|------|------------------|-------------|---------|
+| `'one'` | `one()` | One-to-one or many-to-one | Post has one Author, User has one Profile |
+| `'many'` | `many()` | One-to-many | User has many Posts |
 
-### Example: Post Model
+> [!NOTE]
+> Unlike LoopBack 4's `hasMany`/`hasOne`/`belongsTo` terminology, Ignis uses Drizzle ORM's relation model which has only `one` and `many` types. A "belongsTo" relationship is expressed as `type: 'one'` with `fields` (local FK) and `references` (remote PK) in the metadata.
+
+### Example: Post Model with Both Types
 
 ```typescript
-export const postRelations = createRelations({
+const postRelationsConfig = createRelations({
   source: postTable,
   relations: [
     {
-      type: 'belongsTo',
-      model: () => User,
-      foreignKey: 'authorId',
+      type: 'one',
+      schema: userTable,
       name: 'author',
+      metadata: {
+        fields: [postTable.authorId],
+        references: [userTable.id],
+      },
     },
     {
-      type: 'hasMany',
-      model: () => Comment,
-      foreignKey: 'postId',
+      type: 'many',
+      schema: commentTable,
       name: 'comments',
+      metadata: { relationName: 'comments' },
     },
   ],
 });
 ```
 
+### createRelations Return Value
+
+`createRelations` returns an object with two properties:
+
+```typescript
+const result = createRelations({ source, relations });
+
+result.definitions;  // Record<string, TRelationConfig> - keyed by relation name
+result.relations;    // Drizzle relations() call result - pass to DataSource schema
+```
+
+- **`definitions`**: Used by `BaseEntity.relations` for include resolution at runtime.
+- **`relations`**: The actual Drizzle ORM relations definition, needed for DataSource schema registration.
+
 
 ## Auto-Resolution
 
-Relations are automatically resolved from the entity's static `relations` property. No need to pass them in the repository constructor:
+Relations are automatically resolved from the entity's static `relations` property via `MetadataRegistry`. The `FilterBuilder.resolveRelations()` method reads them when building include queries. No need to pass them in the repository constructor:
 
 ```typescript
 @repository({ model: User, dataSource: PostgresDataSource })
@@ -293,6 +351,27 @@ export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
 ```
 
 
+## Hidden Properties in Relations
+
+When building include queries, the `FilterBuilder.toInclude()` method automatically:
+
+1. Resolves hidden properties for each related model via `resolveHiddenProperties()`.
+2. Resolves the default filter for each related model via `resolveDefaultFilter()`.
+3. Merges the default filter with any user-provided `scope`.
+4. Excludes hidden columns from the nested query's `columns` selection.
+
+```typescript
+// User model has hiddenProperties: ['password']
+const post = await postRepo.findOne({
+  filter: {
+    include: [{ relation: 'author' }]
+  }
+});
+
+// post.author will NOT include password - excluded at SQL level
+```
+
+
 ## Type Safety with Generics
 
 For queries with `include`, use generic type overrides for full type safety:
@@ -343,6 +422,19 @@ product?.saleChannelProducts[0].saleChannel.name;
 ```
 
 
+## TInclusion Type Reference
+
+Each element in the `include` array has this shape:
+
+```typescript
+type TInclusion = {
+  relation: string;             // Name of the relation to include
+  scope?: TFilter;              // Optional nested filter (where, order, limit, fields, include)
+  shouldSkipDefaultFilter?: boolean;  // Skip the related model's default filter
+};
+```
+
+
 ## Common Patterns
 
 ### Find All with Count of Relations
@@ -382,21 +474,6 @@ async function getUser(id: string, includePosts: boolean) {
 }
 ```
 
-### Include with Hidden Properties
-
-Hidden properties (like `password`) are automatically excluded from included relations:
-
-```typescript
-// User model has hiddenProperties: ['password']
-const post = await postRepo.findOne({
-  filter: {
-    include: [{ relation: 'author' }]
-  }
-});
-
-// post.author will NOT include password
-```
-
 
 ## Error Handling
 
@@ -405,7 +482,7 @@ const post = await postRepo.findOne({
 If you try to include a relation that doesn't exist:
 
 ```typescript
-// Error: Relation 'nonExistent' not found in User relations
+// Error: [FilterBuilder][toInclude] Relation NOT FOUND | relation: 'nonExistent'
 await userRepo.find({
   filter: {
     include: [{ relation: 'nonExistent' }]
@@ -413,7 +490,15 @@ await userRepo.find({
 });
 ```
 
-**Fix:** Check your model's `relations` definition.
+**Fix:** Check your model's `relations` definition and ensure the relation name matches.
+
+### Invalid Include Format
+
+```typescript
+// Error: [FilterBuilder][toInclude] Invalid include format | include: ...
+```
+
+**Fix:** Ensure each include element has a `relation` string property.
 
 ### Schema Key Mismatch
 
@@ -431,6 +516,7 @@ in connector.query | Available keys: [Post, Comment]
 2. **Use `fields` in scope** - Only fetch needed columns
 3. **Use `limit` in scope** - Don't fetch unbounded related data
 4. **Consider separate queries** - For complex data needs, multiple simple queries often outperform one complex nested query
+5. **Use `shouldSkipDefaultFilter` sparingly** - Only when you explicitly need filtered-out records
 
 ```typescript
 // Instead of deep nesting, use separate queries
@@ -443,7 +529,7 @@ const posts = await postRepo.find({
 });
 const comments = await commentRepo.find({
   filter: {
-    where: { postId: { in: posts.map(p => p.id) } }
+    where: { postId: { inq: posts.map(p => p.id) } }
   }
 });
 ```
@@ -460,6 +546,7 @@ const comments = await commentRepo.find({
 | Limit included | `include: [{ relation: 'posts', scope: { limit: 5 } }]` |
 | Nested include | `include: [{ relation: 'posts', scope: { include: [{ relation: 'comments' }] } }]` |
 | Select fields | `include: [{ relation: 'posts', scope: { fields: ['id', 'title'] } }]` |
+| Skip default filter | `include: [{ relation: 'posts', shouldSkipDefaultFilter: true }]` |
 
 
 ## Next Steps
@@ -476,11 +563,8 @@ const comments = await commentRepo.find({
 
 - **Related Topics:**
   - [Advanced Features](./advanced) - Hidden properties, transactions
-  - [Repository Mixins](./mixins) - Soft delete and auditing
+  - [Repository Mixins](./mixins) - Default filter and fields visibility
   - [Filter System](/references/base/filter-system/) - Query operators
 
 - **External Resources:**
   - [Drizzle ORM Relations](https://orm.drizzle.team/docs/rqb#relations) - Relation definition guide
-
-- **Tutorials:**
-  - [E-commerce API](/guides/tutorials/ecommerce-api) - Relations in practice