@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/best-practices/performance-optimization.md

@@ -1,6 +1,6 @@
 # Performance Optimization
 
-Optimize your Ignis application for speed and scalability.
+Optimize your IGNIS application for speed and scalability.
 
 ## 1. Measure Performance
 
@@ -46,7 +46,7 @@ Prevent blocking the event loop with Worker Threads:
 
 ### Query Operators Reference
 
-Ignis supports extensive query operators for filtering:
+IGNIS supports extensive query operators for filtering:
 
 | Operator | Description | Example |
 |----------|-------------|---------|
@@ -68,7 +68,7 @@ Ignis supports extensive query operators for filtering:
 **Complex Filter Example:**
 
 ```typescript
-await repo.find({
+await repository.find({
   filter: {
     where: {
       and: [
@@ -87,22 +87,22 @@ await repo.find({
 
 ### JSON Path Filtering
 
-Filter by nested JSON/JSONB fields using PostgreSQL's `#>` operator:
+Filter and sort by nested JSON/JSONB fields using PostgreSQL path extraction:
 
 ```typescript
 // Order by nested JSON path
-await repo.find({
+await repository.find({
   filter: {
     order: ['metadata.nested[0].field ASC'],
   },
 });
 
-// The framework uses PostgreSQL #> operator for path extraction
-// metadata #> '{nested,0,field}'
+// Ordering uses the #> operator: metadata #> '{nested,0,field}'
+// Where clauses on JSON paths use #>> (text extraction)
 ```
 
 > [!TIP]
-> **Avoid Deep Nesting:** While Ignis supports deeply nested `include` filters, each level adds significant overhead to query construction and result mapping. We strongly recommend a **maximum of 2 levels** (e.g., `User -> Orders -> Items`). For more complex data fetching, consider separate queries.
+> **Avoid Deep Nesting:** While IGNIS supports deeply nested `include` filters, each level adds significant overhead to query construction and result mapping. We strongly recommend a **maximum of 2 levels** (e.g., `User -> Orders -> Items`). For more complex data fetching, consider separate queries.
 
 **Example:**
 ```typescript
@@ -132,11 +132,15 @@ Reduce database load with caching:
 
 **Example:**
 ```typescript
-// Cache expensive query results
-const cached = await redis.get('users:active');
+// Cache expensive query results (RedisHelper uses an options-object API)
+const cached = await redis.getObject<TUser[]>({ key: 'users:active' });
 if (!cached) {
-  const users = await userRepository.find({ where: { active: true } });
-  await redis.set('users:active', users, 300); // 5 min TTL
+  const users = await userRepository.find({ filter: { where: { active: true } } });
+  await redis.set({
+    key: 'users:active',
+    value: users,
+    options: { expiresIn: 5 * 60 * 1000 }, // 5 min TTL (milliseconds)
+  });
 }
 ```
 
@@ -203,14 +207,20 @@ Connection pooling significantly improves performance by reusing database connec
 
 ```typescript
 import { Pool } from 'pg';
-import { drizzle } from 'drizzle-orm/node-postgres';
-
-export class PostgresDataSource extends AbstractDataSource {
-  override connect(): void {
-    const pool = new Pool({
+import { datasource } from '@venizia/ignis';
+import { BasePostgresDataSource } from '@venizia/ignis/postgres';
+import { NodePostgresDriver } from '@venizia/ignis/postgres/node-postgres';
+
+// IDataSourceConfigs: your settings interface (host/port/user/password/database)
+@datasource({ driver: NodePostgresDriver })
+export class PostgresDataSource extends BasePostgresDataSource<IDataSourceConfigs> {
+  override configure(): void {
+    // Keep the pool on `this.client` - NodePostgresDriver above wires the driver and Drizzle
+    // connector from it lazily, on first getConnector()/beginTransaction()
+    this.client = new Pool({
       host: this.settings.host,
       port: this.settings.port,
-      user: this.settings.username,
+      user: this.settings.user,
       password: this.settings.password,
       database: this.settings.database,
 
@@ -221,8 +231,6 @@ export class PostgresDataSource extends AbstractDataSource {
       connectionTimeoutMillis: 5000, // Fail if can't connect in 5s
       maxUses: 7500,                // Close connection after 7500 queries
     });
-
-    this.connector = drizzle({ client: pool, schema: this.schema });
   }
 }
 ```
@@ -282,14 +290,14 @@ export const User = pgTable('User', {
 ### Avoid N+1 Queries
 
 ```typescript
-// ❌ BAD - N+1 queries
-const users = await userRepo.find({ filter: { limit: 100 } });
-for (const user of users.data) {
-  user.posts = await postRepo.find({ filter: { where: { authorId: user.id } } });
+// ❌ BAD - N+1 queries (find returns a plain array)
+const users = await userRepository.find({ filter: { limit: 100 } });
+for (const user of users) {
+  user.posts = await postRepository.find({ filter: { where: { authorId: user.id } } });
 }
 
 // ✅ GOOD - Single query with relations
-const users = await userRepo.find({
+const users = await userRepository.find({
   filter: {
     limit: 100,
     include: [{ relation: 'posts' }],
@@ -302,11 +310,11 @@ const users = await userRepo.find({
 ```typescript
 // ❌ BAD - Many individual inserts
 for (const item of items) {
-  await repo.create({ data: item });
+  await repository.create({ data: item });
 }
 
 // ✅ GOOD - Batch insert
-await repo.createMany({ data: items });
+await repository.createAll({ data: items });
 ```
 
 ## 9. Memory Management
@@ -315,7 +323,7 @@ await repo.createMany({ data: items });
 
 ```typescript
 // ❌ BAD - Load all records into memory
-const allUsers = await userRepo.find({ filter: { limit: 100000 } });
+const allUsers = await userRepository.find({ filter: { limit: 100000 } });
 
 // ✅ GOOD - Process in batches
 const batchSize = 1000;
@@ -323,15 +331,16 @@ let offset = 0;
 let hasMore = true;
 
 while (hasMore) {
-  const batch = await userRepo.find({
+  // find returns a plain array
+  const batch = await userRepository.find({
     filter: { limit: batchSize, offset },
   });
 
-  for (const user of batch.data) {
+  for (const user of batch) {
     await processUser(user);
   }
 
-  hasMore = batch.data.length === batchSize;
+  hasMore = batch.length === batchSize;
   offset += batchSize;
 }
 ```

package/content/best-practices/security-guidelines.md

@@ -1,6 +1,6 @@
 # Security Guidelines
 
-Critical security practices to protect your Ignis application.
+Critical security practices to protect your IGNIS application.
 
 ## 1. Secret Management
 
@@ -23,9 +23,27 @@ APP_ENV_POSTGRES_PASSWORD=database_password_here
 node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
 ```
 
+### Redaction at Log Time
+
+Never hard-coding a secret is not enough on its own -- an options object holding one still ends up in a log line the moment it is passed to `logger.info('...: %s', opts)`. `@venizia/ignis-helpers` provides two primitives for exactly this:
+
+| Function | Use For | Behavior |
+|----------|---------|----------|
+| `redactSecrets(value)` | Any object/array being logged | Recursively replaces every value whose key matches a secret-looking name (`password`, `token`, `apiKey`, `authorization`, HTTP header spellings like `x-api-key`/`cookie`/`proxy-authorization`, etc., case-insensitive) with `'[REDACTED]'` |
+| `redactUrlCredentials(url)` | A connection/broker URL string | Strips the password out of a URL's authority section (`mqtts://user:hunter2@broker:8883` becomes `mqtts://user:[REDACTED]@broker:8883`); a value that doesn't parse as a URL is returned unchanged |
+
+```typescript
+import { redactSecrets, redactUrlCredentials } from '@venizia/ignis-helpers';
+
+this.logger.info('[connect] Options: %s', redactSecrets(connectionOptions));
+this.logger.info('[connect] Broker: %s', redactUrlCredentials(brokerUrl));
+```
+
+These are the primitives the framework itself uses -- outbound HTTP request configs (`NodeFetcher`/`AxiosFetcher`, see [Network Helper](/extensions/helpers/network/)) and MQTT broker URLs (`MQTTClientHelper`, see [Queue Helper](/extensions/helpers/queue/)) are both redacted this way before they reach a log line.
+
 ## 2. Input Validation
 
-**Always validate incoming data** with Zod schemas. Ignis automatically rejects invalid requests.
+**Always validate incoming data** with Zod schemas. IGNIS automatically rejects invalid requests.
 
 ```typescript
 import { z } from '@hono/zod-openapi';
@@ -63,7 +81,7 @@ this.component(AuthenticateComponent);
 ```typescript
 const SecureRoute = {
   path: '/admin/users',
-  authStrategies: [Authentication.STRATEGY_JWT], // Requires JWT
+  authenticate: { strategies: [Authentication.STRATEGY_JWT] }, // Requires JWT
   // ...
 };
 ```
@@ -73,10 +91,10 @@ const SecureRoute = {
 **Access user in protected routes:**
 ```typescript
 import { Authentication, IJWTTokenPayload } from '@venizia/ignis';
-import { ApplicationError, getError } from '@venizia/ignis-helpers';
+import { getError } from '@venizia/ignis-helpers';
 
 const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload;
-if (!user.roles.includes('admin')) {
+if (!user.roles.some(role => role.identifier === 'admin')) {
     throw getError({ statusCode: 403, message: 'Forbidden' });
 }
 ```
@@ -92,7 +110,7 @@ Configure model properties that should **never be returned** through repository
     hiddenProperties: ['password', 'apiSecret', 'internalToken'],
   },
 })
-export class User extends BaseEntity<typeof User.schema> {
+export class User extends BasePostgresEntity<typeof User.schema> {
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
     email: text('email').notNull(),
@@ -113,7 +131,7 @@ export class User extends BaseEntity<typeof User.schema> {
 
 ```typescript
 // For authentication - access password via connector
-const connector = userRepo.getConnector();
+const connector = userRepository.getConnector();
 const [user] = await connector
   .select({ id: User.schema.id, password: User.schema.password })
   .from(User.schema)
@@ -227,14 +245,14 @@ Configure Cross-Origin Resource Sharing to control which domains can access your
 import { cors } from 'hono/cors';
 
 // Allow all origins (ONLY for development)
-this.server.use('*', cors());
+this.getServer().use('*', cors());
 ```
 
 **Production (Restrictive):**
 ```typescript
 import { cors } from 'hono/cors';
 
-this.server.use('/api/*', cors({
+this.getServer().use('/api/*', cors({
   origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
   allowMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
   allowHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
@@ -246,7 +264,7 @@ this.server.use('/api/*', cors({
 
 **Dynamic Origin Validation:**
 ```typescript
-this.server.use('/api/*', cors({
+this.getServer().use('/api/*', cors({
   origin: (origin) => {
     const allowedDomains = ['yourdomain.com', 'yourdomain.io'];
     try {
@@ -296,9 +314,10 @@ const rateLimiter = (opts: { windowMs: number; max: number }) => {
 };
 
 // Apply to sensitive endpoints
-this.server.use('/api/auth/login', rateLimiter({ windowMs: 15 * 60 * 1000, max: 5 }));
-this.server.use('/api/auth/register', rateLimiter({ windowMs: 60 * 60 * 1000, max: 10 }));
-this.server.use('/api/*', rateLimiter({ windowMs: 60 * 1000, max: 100 }));
+const server = this.getServer();
+server.use('/api/auth/login', rateLimiter({ windowMs: 15 * 60 * 1000, max: 5 }));
+server.use('/api/auth/register', rateLimiter({ windowMs: 60 * 60 * 1000, max: 10 }));
+server.use('/api/*', rateLimiter({ windowMs: 60 * 1000, max: 100 }));
 ```
 
 **Recommended Limits:**
@@ -313,16 +332,22 @@ this.server.use('/api/*', rateLimiter({ windowMs: 60 * 1000, max: 100 }));
 **Production Recommendation:** Use Redis-backed rate limiting for distributed deployments:
 
 ```typescript
-import { RedisHelper } from '@venizia/ignis-helpers';
+import { RedisSingleHelper } from '@venizia/ignis-helpers';
 
 // Rate limiter with Redis for multi-instance deployments
-const distributedRateLimiter = async (key: string, max: number, windowSec: number) => {
-  const redis = RedisHelper.getClient();
-  const current = await redis.incr(key);
+const redisHelper = new RedisSingleHelper({
+  name: 'rate-limiter',
+  host: process.env.APP_ENV_REDIS_HOST ?? 'localhost',
+  port: process.env.APP_ENV_REDIS_PORT ?? '6379',
+  password: process.env.APP_ENV_REDIS_PASSWORD,
+});
+
+const distributedRateLimiter = async (opts: { key: string; max: number; windowSeconds: number }) => {
+  const current = await redisHelper.incr({ key: opts.key });
   if (current === 1) {
-    await redis.expire(key, windowSec);
+    await redisHelper.expire({ key: opts.key, seconds: opts.windowSeconds });
   }
-  return current <= max;
+  return current <= opts.max;
 };
 ```
 
@@ -369,7 +394,7 @@ Add security headers to protect against common attacks:
 import { secureHeaders } from 'hono/secure-headers';
 
 // Add security headers to all responses
-this.server.use('*', secureHeaders({
+this.getServer().use('*', secureHeaders({
   // Prevent clickjacking
   xFrameOptions: 'DENY',
   // Prevent MIME type sniffing
@@ -396,13 +421,13 @@ Prevent denial of service through large payloads:
 import { bodyLimit } from 'hono/body-limit';
 
 // Limit request body size
-this.server.use('/api/*', bodyLimit({
+this.getServer().use('/api/*', bodyLimit({
   maxSize: 1024 * 1024, // 1MB for general API
   onError: (c) => c.json({ message: 'Request body too large' }, 413),
 }));
 
 // Allow larger uploads for file endpoints
-this.server.use('/api/upload/*', bodyLimit({
+this.getServer().use('/api/upload/*', bodyLimit({
   maxSize: 50 * 1024 * 1024, // 50MB for file uploads
 }));
 ```
@@ -413,13 +438,14 @@ Log security-relevant events for monitoring and forensics:
 
 ```typescript
 import { BaseService } from '@venizia/ignis';
+import { getError } from '@venizia/ignis-helpers';
 
 export class AuthService extends BaseService {
   async login(email: string, password: string, context: Context) {
     const ip = context.req.header('x-forwarded-for') ?? 'unknown';
     const userAgent = context.req.header('user-agent') ?? 'unknown';
 
-    const user = await this.userRepo.findByEmail(email);
+    const user = await this.userRepository.findByEmail(email);
 
     if (!user || !await this.verifyPassword(password, user.password)) {
       // Log failed attempt
@@ -444,6 +470,9 @@ export class AuthService extends BaseService {
 - Suspicious activity (rate limit hits, invalid tokens)
 - Admin actions
 
+> [!NOTE]
+> When logging a request or connection config that might carry credentials, wrap it in `redactSecrets()` (or `redactUrlCredentials()` for a URL) rather than logging it raw -- see [Redaction at Log Time](#redaction-at-log-time) above. This is what the framework's own outbound HTTP and MQTT logging already does automatically.
+
 ## Security Checklist
 
 Before deploying to production, verify:

package/content/best-practices/testing-strategies.md

@@ -1,6 +1,6 @@
 # Testing Strategies
 
-Comprehensive testing guide for Ignis applications using Bun's built-in test runner.
+Comprehensive testing guide for IGNIS applications using Bun's built-in test runner.
 
 ## Testing Philosophy
 
@@ -46,13 +46,16 @@ afterAll(async () => {
 
 **`test/helpers/test-database.ts`:**
 ```typescript
+import { sql } from 'drizzle-orm';
 import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
+import { PostgresDataSource } from '@/datasources';
 import * as schema from '@/models';
 
 export class TestDatabase {
   private static pool: Pool;
   private static db: ReturnType<typeof drizzle>;
+  private static dataSource: PostgresDataSource;
 
   static async initialize() {
     this.pool = new Pool({
@@ -63,12 +66,20 @@ export class TestDatabase {
       database: process.env.TEST_DB_NAME ?? 'ignis_test',
     });
     this.db = drizzle({ client: this.pool, schema });
+
+    // Application DataSource - repositories take a DataSource, not a raw Drizzle instance
+    this.dataSource = new PostgresDataSource();
+    await this.dataSource.configure();
   }
 
   static getDb() {
     return this.db;
   }
 
+  static getDataSource() {
+    return this.dataSource;
+  }
+
   static async truncateAll() {
     const tables = Object.keys(schema);
     for (const table of tables) {
@@ -116,19 +127,20 @@ import type { IUserRepository } from '@/repositories';
 
 describe('UserService', () => {
   let service: UserService;
-  let mockRepo: IUserRepository;
+  let mockRepository: IUserRepository;
 
   beforeEach(() => {
     // Create mock repository
-    mockRepo = {
-      findById: mock(() => Promise.resolve({ data: null })),
-      findOne: mock(() => Promise.resolve({ data: null })),
-      create: mock((opts) => Promise.resolve({ data: { id: 'new-id', ...opts.data }, count: 1 })),
-      updateById: mock(() => Promise.resolve({ data: null, count: 0 })),
+    // find/findOne/findById return the rows directly; create/updateById return { count, data }
+    mockRepository = {
+      findById: mock(() => Promise.resolve(null)),
+      findOne: mock(() => Promise.resolve(null)),
+      create: mock((opts) => Promise.resolve({ count: 1, data: { id: 'new-id', ...opts.data } })),
+      updateById: mock(() => Promise.resolve({ count: 0, data: null })),
     } as unknown as IUserRepository;
 
     // Inject mock
-    service = new UserService(mockRepo);
+    service = new UserService(mockRepository);
   });
 
   describe('createUser', () => {
@@ -142,13 +154,13 @@ describe('UserService', () => {
         email: 'test@example.com',
         name: 'Test User',
       });
-      expect(mockRepo.create).toHaveBeenCalledTimes(1);
+      expect(mockRepository.create).toHaveBeenCalledTimes(1);
     });
 
     it('should throw error for duplicate email', async () => {
-      mockRepo.findOne = mock(() => Promise.resolve({
-        data: { id: 'existing', email: 'test@example.com' },
-      }));
+      mockRepository.findOne = mock(() =>
+        Promise.resolve({ id: 'existing', email: 'test@example.com' }),
+      );
 
       await expect(
         service.createUser({ email: 'test@example.com', name: 'Test' })
@@ -160,7 +172,7 @@ describe('UserService', () => {
 
       await service.createUser(userData);
 
-      const createCall = (mockRepo.create as ReturnType<typeof mock>).mock.calls[0][0];
+      const createCall = (mockRepository.create as ReturnType<typeof mock>).mock.calls[0][0];
       expect(createCall.data.password).not.toBe('secret123');
       expect(createCall.data.password).toMatch(/^\$2[aby]?\$/); // bcrypt hash
     });
@@ -168,7 +180,7 @@ describe('UserService', () => {
 
   describe('updateUser', () => {
     it('should throw NotFound when user does not exist', async () => {
-      mockRepo.findById = mock(() => Promise.resolve({ data: null }));
+      mockRepository.findById = mock(() => Promise.resolve(null));
 
       await expect(
         service.updateUser('nonexistent', { name: 'New Name' })
@@ -176,17 +188,17 @@ describe('UserService', () => {
     });
 
     it('should only update provided fields', async () => {
-      mockRepo.findById = mock(() => Promise.resolve({
-        data: { id: '1', email: 'old@test.com', name: 'Old Name' },
-      }));
-      mockRepo.updateById = mock((opts) => Promise.resolve({
-        data: { ...opts.data, id: opts.id },
+      mockRepository.findById = mock(() =>
+        Promise.resolve({ id: '1', email: 'old@test.com', name: 'Old Name' }),
+      );
+      mockRepository.updateById = mock((opts) => Promise.resolve({
         count: 1,
+        data: { ...opts.data, id: opts.id },
       }));
 
       await service.updateUser('1', { name: 'New Name' });
 
-      const updateCall = (mockRepo.updateById as ReturnType<typeof mock>).mock.calls[0][0];
+      const updateCall = (mockRepository.updateById as ReturnType<typeof mock>).mock.calls[0][0];
       expect(updateCall.data).toEqual({ name: 'New Name' });
       expect(updateCall.data.email).toBeUndefined();
     });
@@ -206,11 +218,11 @@ import { TestDatabase } from '@test/helpers/test-database';
 import { User } from '@/models';
 
 describe('UserRepository', () => {
-  let repo: UserRepository;
+  let repository: UserRepository;
 
   beforeEach(async () => {
-    const db = TestDatabase.getDb();
-    repo = new UserRepository(db);
+    // Repositories take the application DataSource, not a raw Drizzle instance
+    repository = new UserRepository(TestDatabase.getDataSource());
   });
 
   afterEach(async () => {
@@ -219,7 +231,7 @@ describe('UserRepository', () => {
 
   describe('create', () => {
     it('should create a user and return with generated id', async () => {
-      const result = await repo.create({
+      const result = await repository.create({
         data: { email: 'test@example.com', name: 'Test User' },
       });
 
@@ -232,12 +244,12 @@ describe('UserRepository', () => {
     });
 
     it('should enforce unique email constraint', async () => {
-      await repo.create({
+      await repository.create({
         data: { email: 'test@example.com', name: 'First' },
       });
 
       await expect(
-        repo.create({ data: { email: 'test@example.com', name: 'Second' } })
+        repository.create({ data: { email: 'test@example.com', name: 'Second' } })
       ).rejects.toThrow(); // Unique constraint violation
     });
   });
@@ -245,7 +257,7 @@ describe('UserRepository', () => {
   describe('find', () => {
     beforeEach(async () => {
       // Seed test data
-      await repo.createMany({
+      await repository.createAll({
         data: [
           { email: 'alice@test.com', name: 'Alice', status: 'ACTIVE' },
           { email: 'bob@test.com', name: 'Bob', status: 'ACTIVE' },
@@ -255,31 +267,32 @@ describe('UserRepository', () => {
     });
 
     it('should filter by status', async () => {
-      const result = await repo.find({
+      // find() returns the rows directly (an array)
+      const users = await repository.find({
         filter: { where: { status: 'ACTIVE' } },
       });
 
-      expect(result.data).toHaveLength(2);
-      expect(result.data.map(u => u.name)).toContain('Alice');
-      expect(result.data.map(u => u.name)).toContain('Bob');
+      expect(users).toHaveLength(2);
+      expect(users.map(user => user.name)).toContain('Alice');
+      expect(users.map(user => user.name)).toContain('Bob');
     });
 
     it('should support pagination', async () => {
-      const page1 = await repo.find({
+      const page1 = await repository.find({
         filter: { limit: 2, offset: 0, order: ['name ASC'] },
       });
-      const page2 = await repo.find({
+      const page2 = await repository.find({
         filter: { limit: 2, offset: 2, order: ['name ASC'] },
       });
 
-      expect(page1.data).toHaveLength(2);
-      expect(page1.data[0].name).toBe('Alice');
-      expect(page2.data).toHaveLength(1);
-      expect(page2.data[0].name).toBe('Charlie');
+      expect(page1).toHaveLength(2);
+      expect(page1[0].name).toBe('Alice');
+      expect(page2).toHaveLength(1);
+      expect(page2[0].name).toBe('Charlie');
     });
 
     it('should support complex filters', async () => {
-      const result = await repo.find({
+      const users = await repository.find({
         filter: {
           where: {
             or: [
@@ -290,34 +303,35 @@ describe('UserRepository', () => {
         },
       });
 
-      expect(result.data).toHaveLength(2);
-      expect(result.data.map(u => u.name)).toContain('Alice');
-      expect(result.data.map(u => u.name)).toContain('Charlie');
+      expect(users).toHaveLength(2);
+      expect(users.map(user => user.name)).toContain('Alice');
+      expect(users.map(user => user.name)).toContain('Charlie');
     });
   });
 
   describe('relations', () => {
     it('should load related entities', async () => {
       // Assuming User has Posts relation
-      const user = await repo.create({
+      const created = await repository.create({
         data: { email: 'author@test.com', name: 'Author' },
       });
 
       // Create posts for the user
-      const postRepo = new PostRepository(TestDatabase.getDb());
-      await postRepo.createMany({
+      const postRepository = new PostRepository(TestDatabase.getDataSource());
+      await postRepository.createAll({
         data: [
-          { title: 'Post 1', authorId: user.data!.id },
-          { title: 'Post 2', authorId: user.data!.id },
+          { title: 'Post 1', authorId: created.data!.id },
+          { title: 'Post 2', authorId: created.data!.id },
         ],
       });
 
-      const result = await repo.findById({
-        id: user.data!.id,
+      // findById() returns the entity directly (or null)
+      const author = await repository.findById({
+        id: created.data!.id,
         filter: { include: [{ relation: 'posts' }] },
       });
 
-      expect(result.data?.posts).toHaveLength(2);
+      expect(author?.posts).toHaveLength(2);
     });
   });
 });
@@ -341,8 +355,8 @@ describe('UserController E2E', () => {
   beforeAll(async () => {
     await TestDatabase.initialize();
     app = new Application();
-    await app.boot();
-    client = testClient(app.server);
+    await app.initialize();
+    client = testClient(app.getServer());
   });
 
   afterEach(async () => {