@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/{wiki → content}/references/base/repositories/relations.md

@@ -9,7 +9,7 @@ Fetch related data using `include` for eager loading. This guide covers one-to-o
 
 ```typescript
 // Fetch user with their posts
-const user = await userRepo.findOne({
+const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
     include: [{ relation: 'posts' }]
@@ -31,7 +31,7 @@ const user = await userRepo.findOne({
 
 ```typescript
 // Fetch post with its author
-const post = await postRepo.findOne({
+const post = await postRepository.findOne({
   filter: {
     where: { id: 'p1' },
     include: [{ relation: 'author' }]
@@ -51,7 +51,7 @@ const post = await postRepo.findOne({
 
 ```typescript
 // Fetch post with author AND comments
-const post = await postRepo.findOne({
+const post = await postRepository.findOne({
   filter: {
     where: { id: 'p1' },
     include: [
@@ -74,7 +74,7 @@ Apply filters, ordering, and limits to included relations using `scope`:
 
 ```typescript
 // User with only published posts
-const user = await userRepo.findOne({
+const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
     include: [{
@@ -91,7 +91,7 @@ const user = await userRepo.findOne({
 
 ```typescript
 // User with posts ordered by date
-const user = await userRepo.findOne({
+const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
     include: [{
@@ -108,7 +108,7 @@ const user = await userRepo.findOne({
 
 ```typescript
 // User with their 5 most recent posts
-const user = await userRepo.findOne({
+const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
     include: [{
@@ -125,7 +125,7 @@ const user = await userRepo.findOne({
 ### Combined Scope Options
 
 ```typescript
-const user = await userRepo.findOne({
+const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
     include: [{
@@ -147,7 +147,7 @@ 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({
+const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
     include: [{
@@ -167,7 +167,7 @@ Include relations of relations (up to 2 levels recommended):
 
 ```typescript
 // User -> Posts -> Comments
-const user = await userRepo.findOne({
+const user = await userRepository.findOne({
   filter: {
     where: { id: '123' },
     include: [{
@@ -200,7 +200,7 @@ const user = await userRepo.findOne({
 
 ```typescript
 // Product -> SaleChannelProduct (junction) -> SaleChannel
-const product = await productRepo.findOne({
+const product = await productRepository.findOne({
   filter: {
     where: { id: 'prod1' },
     include: [{
@@ -236,7 +236,7 @@ const product = await productRepo.findOne({
 
 ## Defining Relations
 
-Relations are defined using the `createRelations` helper and the `TRelationConfig` type. These use Drizzle ORM's relation system under the hood.
+Relations are declared on the model as a static `relations` resolver returning an array of `TRelationConfig`. The framework translates them to Drizzle ORM relations internally during schema discovery.
 
 ### Relation Config Type
 
@@ -261,34 +261,32 @@ type TRelationConfig = {
 
 ```typescript
 // src/models/user.model.ts
-import { createRelations } from '@venizia/ignis';
+import { model, RelationTypes } from '@venizia/ignis';
+import { BasePostgresEntity, TRelationConfig } from '@venizia/ignis/postgres';
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import { Post } from './post.model';
 
-export const userTable = pgTable('User', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  email: text('email').notNull(),
-});
+@model({ type: 'entity' })
+export class User extends BasePostgresEntity<typeof User.schema> {
+  static override schema = pgTable('User', {
+    id: text('id').primaryKey(),
+    name: text('name').notNull(),
+    email: text('email').notNull(),
+  });
 
-const userRelationsConfig = createRelations({
-  source: userTable,
-  relations: [
+  static override relations = (): TRelationConfig[] => [
     {
-      type: 'many',
-      schema: postTable,
       name: 'posts',
+      type: RelationTypes.MANY,
+      schema: Post.schema,
       metadata: { relationName: 'posts' },
     },
-  ],
-});
-
-@model({ type: 'entity' })
-export class User extends BaseEntity<typeof User.schema> {
-  static override schema = userTable;
-  static override relations = () => userRelationsConfig.definitions;
-  static override TABLE_NAME = 'User';
+  ];
 }
 ```
 
+The resolver form (`() => [...]`) defers evaluation until all `@model` classes are registered, avoiding circular-import ordering issues between related models.
+
 ### Relation Types
 
 | Type | Drizzle Function | Description | Example |
@@ -297,46 +295,38 @@ export class User extends BaseEntity<typeof User.schema> {
 | `'many'` | `many()` | One-to-many | User has many Posts |
 
 > [!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.
+> 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
-const postRelationsConfig = createRelations({
-  source: postTable,
-  relations: [
+@model({ type: 'entity' })
+export class Post extends BasePostgresEntity<typeof Post.schema> {
+  static override schema = postTable;
+
+  static override relations = (): TRelationConfig[] => [
     {
-      type: 'one',
-      schema: userTable,
       name: 'author',
+      type: RelationTypes.ONE,
+      schema: User.schema,
       metadata: {
-        fields: [postTable.authorId],
-        references: [userTable.id],
+        fields: [Post.schema.authorId],
+        references: [User.schema.id],
       },
     },
     {
-      type: 'many',
-      schema: commentTable,
       name: 'comments',
+      type: RelationTypes.MANY,
+      schema: Comment.schema,
       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
-```
+### How Configs Become Drizzle Relations
 
-- **`definitions`**: Used by `BaseEntity.relations` for include resolution at runtime.
-- **`relations`**: The actual Drizzle ORM relations definition, needed for DataSource schema registration.
+During schema discovery, `MetadataRegistry` resolves each model's `relations` array and passes it to the `createRelations` helper (`packages/core/src/connectors/postgres/repositories/operators/relation.ts`), which builds the actual Drizzle `relations()` definition registered on the DataSource schema. You do not call `createRelations` yourself in application code.
 
 
 ## Auto-Resolution
@@ -362,7 +352,7 @@ When building include queries, the `FilterBuilder.toInclude()` method automatica
 
 ```typescript
 // User model has hiddenProperties: ['password']
-const post = await postRepo.findOne({
+const post = await postRepository.findOne({
   filter: {
     include: [{ relation: 'author' }]
   }
@@ -383,7 +373,7 @@ type UserWithPosts = User & {
 };
 
 // Use generic override
-const user = await userRepo.findOne<UserWithPosts>({
+const user = await userRepository.findOne<UserWithPosts>({
   filter: {
     where: { id: '123' },
     include: [{ relation: 'posts' }]
@@ -405,7 +395,7 @@ type ProductWithChannels = Product & {
   })[];
 };
 
-const product = await productRepo.findOne<ProductWithChannels>({
+const product = await productRepository.findOne<ProductWithChannels>({
   filter: {
     where: { id: 'prod1' },
     include: [{
@@ -441,7 +431,7 @@ type TInclusion = {
 
 ```typescript
 // Get users with post count
-const users = await userRepo.find({
+const users = await userRepository.find({
   filter: {
     include: [{
       relation: 'posts',
@@ -465,7 +455,7 @@ async function getUser(id: string, includePosts: boolean) {
     ? [{ relation: 'posts' }]
     : [];
 
-  return userRepo.findOne({
+  return userRepository.findOne({
     filter: {
       where: { id },
       include
@@ -483,7 +473,7 @@ If you try to include a relation that doesn't exist:
 
 ```typescript
 // Error: [FilterBuilder][toInclude] Relation NOT FOUND | relation: 'nonExistent'
-await userRepo.find({
+await userRepository.find({
   filter: {
     include: [{ relation: 'nonExistent' }]
   }
@@ -520,14 +510,14 @@ in connector.query | Available keys: [Post, Comment]
 
 ```typescript
 // Instead of deep nesting, use separate queries
-const user = await userRepo.findById({ id: '123' });
-const posts = await postRepo.find({
+const user = await userRepository.findById({ id: '123' });
+const posts = await postRepository.find({
   filter: {
     where: { authorId: '123' },
     limit: 10
   }
 });
-const comments = await commentRepo.find({
+const comments = await commentRepository.find({
   filter: {
     where: { postId: { inq: posts.map(p => p.id) } }
   }
@@ -563,7 +553,7 @@ const comments = await commentRepo.find({
 
 - **Related Topics:**
   - [Advanced Features](./advanced) - Hidden properties, transactions
-  - [Repository Mixins](./mixins) - Default filter and fields visibility
+  - [Repository Mixins (Removed)](./mixins) - Where default-filter and fields-visibility behavior lives now
   - [Filter System](/references/base/filter-system/) - Query operators
 
 - **External Resources:**

package/{wiki → content}/references/base/repositories/soft-deletable.md

@@ -8,7 +8,7 @@ difficulty: intermediate
 
 A repository that overrides delete operations to set a `deletedAt` timestamp instead of physically removing records. Extends `DefaultCRUDRepository` with restore capabilities.
 
-**File:** `packages/core/src/base/repositories/core/soft-deletable.ts`
+**File:** `packages/core/src/connectors/postgres/repositories/core/soft-deletable.ts` (PostgreSQL connector - soft delete via `deletedAt` is a Drizzle/SQL-specific pattern, not part of the engine-neutral `AbstractRepository`)
 
 
 ## Setup
@@ -70,17 +70,17 @@ All delete methods set `deletedAt = new Date()` instead of removing the row. The
 
 ```typescript
 // Soft delete - sets deletedAt timestamp
-const result = await repo.deleteById({ id: '123' });
+const result = await repository.deleteById({ id: '123' });
 // { count: 1, data: { id: '123', name: 'Electronics', deletedAt: '2026-03-06T...' } }
 
 // Without returning data
-const result = await repo.deleteById({
+const result = await repository.deleteById({
   id: '123',
   options: { shouldReturn: false },
 });
 
 // Hard delete - physically removes the row
-const result = await repo.deleteById({
+const result = await repository.deleteById({
   id: '123',
   options: { shouldHardDelete: true },
 });
@@ -90,13 +90,13 @@ const result = await repo.deleteById({
 
 ```typescript
 // Soft delete all matching records
-const result = await repo.deleteAll({
+const result = await repository.deleteAll({
   where: { status: 'archived' },
   options: { force: true },
 });
 
 // Hard delete all matching records
-const result = await repo.deleteAll({
+const result = await repository.deleteAll({
   where: { status: 'archived' },
   options: { shouldHardDelete: true, force: true },
 });
@@ -106,12 +106,12 @@ const result = await repo.deleteAll({
 
 ```typescript
 // Soft delete by where condition (alias for deleteAll)
-const result = await repo.deleteBy({
+const result = await repository.deleteBy({
   where: { name: 'Obsolete' },
 });
 
 // Hard delete by where condition
-const result = await repo.deleteBy({
+const result = await repository.deleteBy({
   where: { name: 'Obsolete' },
   options: { shouldHardDelete: true },
 });
@@ -125,11 +125,11 @@ Restore methods set `deletedAt = null` and automatically use `shouldSkipDefaultF
 ### restoreById
 
 ```typescript
-const result = await repo.restoreById({ id: '123' });
+const result = await repository.restoreById({ id: '123' });
 // { count: 1, data: { id: '123', name: 'Electronics', deletedAt: null } }
 
 // Without returning data
-const result = await repo.restoreById({
+const result = await repository.restoreById({
   id: '123',
   options: { shouldReturn: false },
 });
@@ -139,13 +139,13 @@ const result = await repo.restoreById({
 
 ```typescript
 // Restore all soft-deleted records (requires force for empty where)
-const result = await repo.restoreAll({
+const result = await repository.restoreAll({
   where: {},
   options: { force: true },
 });
 
 // Restore matching records
-const result = await repo.restoreAll({
+const result = await repository.restoreAll({
   where: { name: 'Electronics' },
 });
 ```
@@ -154,7 +154,7 @@ const result = await repo.restoreAll({
 
 ```typescript
 // Alias for restoreAll
-const result = await repo.restoreBy({
+const result = await repository.restoreBy({
   where: { status: 'archived' },
 });
 ```
@@ -168,10 +168,10 @@ const result = await repo.restoreBy({
 
 ```typescript
 // Returns null if not found (default)
-const category = await repo.findById({ id: '123' });
+const category = await repository.findById({ id: '123' });
 
 // Throws 404 if not found
-const category = await repo.findById({
+const category = await repository.findById({
   id: '123',
   options: { isStrict: true },
 });
@@ -226,8 +226,8 @@ All other read operations (`find`, `findOne`, `count`, `existsWith`) work as nor
 ```typescript
 const tx = await this.dataSource.beginTransaction();
 try {
-  await this.categoryRepo.deleteById({ id: '123', options: { transaction: tx } });
-  await this.auditRepo.create({
+  await this.categoryRepository.deleteById({ id: '123', options: { transaction: tx } });
+  await this.auditRepository.create({
     data: { action: 'soft_delete', entityId: '123' },
     options: { transaction: tx },
   });
@@ -259,11 +259,12 @@ If your schema does not have a `deletedAt` column, you will get a TypeScript com
 ## Class Hierarchy
 
 ```
-AbstractRepository
-  -> ReadableRepository
-    -> PersistableRepository
-      -> DefaultCRUDRepository
-        -> SoftDeletableRepository   <-- you are here
+AbstractRepository (engine-neutral, src/base)
+  -> PostgresBaseRepository (connectors/postgres)
+    -> ReadableRepository
+      -> PersistableRepository
+        -> DefaultCRUDRepository
+          -> SoftDeletableRepository   <-- you are here
 ```
 
 
@@ -271,19 +272,19 @@ AbstractRepository
 
 | Want to... | Code |
 |------------|------|
-| Soft delete by ID | `repo.deleteById({ id })` |
-| Hard delete by ID | `repo.deleteById({ id, options: { shouldHardDelete: true } })` |
-| Soft delete by condition | `repo.deleteAll({ where, options: { force: true } })` |
-| Restore by ID | `repo.restoreById({ id })` |
-| Restore by condition | `repo.restoreAll({ where })` |
-| Find including deleted | `repo.find({ filter, options: { shouldSkipDefaultFilter: true } })` |
-| Strict findById (404) | `repo.findById({ id, options: { isStrict: true } })` |
+| Soft delete by ID | `repository.deleteById({ id })` |
+| Hard delete by ID | `repository.deleteById({ id, options: { shouldHardDelete: true } })` |
+| Soft delete by condition | `repository.deleteAll({ where, options: { force: true } })` |
+| Restore by ID | `repository.restoreById({ id })` |
+| Restore by condition | `repository.restoreAll({ where })` |
+| Find including deleted | `repository.find({ filter, options: { shouldSkipDefaultFilter: true } })` |
+| Strict findById (404) | `repository.findById({ id, options: { isStrict: true } })` |
 
 
 ## Next Steps
 
 - [Advanced Features](./advanced.md) - Transactions, hidden properties
-- [Repository Mixins](./mixins.md) - Default filter and fields visibility
+- [Repository Mixins (Removed)](./mixins.md) - Where default-filter and fields-visibility behavior lives now
 - [Repository Overview](./index.md) - Repository basics
 
 ## See Also