@tstdl/base 0.93.145 → 0.93.146

package/orm/tests/repository-soft-delete.test.js

@@ -7,17 +7,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { Injector, runInInjectionContext } from '../../injector/index.js';
-import { StringProperty } from '../../schema/index.js';
 import { sql } from 'drizzle-orm';
 import { beforeAll, describe, expect, test } from 'vitest';
+import { StringProperty } from '../../schema/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
 import { Table } from '../decorators.js';
 import { Entity } from '../entity.js';
-import { configureOrm, Database } from '../server/index.js';
-import { injectRepository } from '../server/repository.js';
+import { getRepository } from '../server/index.js';
 describe('ORM Repository Soft Delete (Integration)', () => {
     let injector;
     let db;
+    let repository;
     const schema = 'test_orm_soft_delete';
     let SoftDeleteEntity = class SoftDeleteEntity extends Entity {
         name;
@@ -30,14 +30,10 @@ describe('ORM Repository Soft Delete (Integration)', () => {
         Table('soft_delete_entities', { schema })
     ], SoftDeleteEntity);
     beforeAll(async () => {
-        injector = new Injector('Test');
-        configureOrm({
-            repositoryConfig: { schema },
-            connection: {
-                host: '127.0.0.1', port: 5432, user: 'tstdl', password: 'wf7rq6glrk5jykne', database: 'tstdl',
-            }
-        });
-        db = injector.resolve(Database);
+        ({ injector, database: db } = await setupIntegrationTest({
+            orm: { schema },
+        }));
+        repository = injector.resolve(getRepository(SoftDeleteEntity));
         await db.execute(sql `CREATE SCHEMA IF NOT EXISTS ${sql.identifier(schema)}`);
         await db.execute(sql `DROP TABLE IF EXISTS ${sql.identifier(schema)}.${sql.identifier('soft_delete_entities')} CASCADE`);
         await db.execute(sql `
@@ -54,90 +50,69 @@ describe('ORM Repository Soft Delete (Integration)', () => {
     });
     test('should soft delete an entity by ID', async () => {
         await db.execute(sql `TRUNCATE TABLE ${sql.identifier(schema)}.${sql.identifier('soft_delete_entities')} CASCADE`);
-        await runInInjectionContext(injector, async () => {
-            const repository = injectRepository(SoftDeleteEntity);
-            const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
-            const deleted = await repository.delete(e1.id);
-            expect(deleted.id).toBe(e1.id);
-            expect(deleted.metadata.deleteTimestamp).toBeDefined();
-            expect(await repository.has(e1.id)).toBe(false);
-            expect(await repository.tryLoad(e1.id)).toBeUndefined();
-            expect(await repository.count()).toBe(0);
-            const allWithDeleted = await repository.loadAll({ withDeleted: true });
-            expect(allWithDeleted).toHaveLength(1);
-            expect(allWithDeleted[0].id).toBe(e1.id);
-        });
+        const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
+        const deleted = await repository.delete(e1.id);
+        expect(deleted.id).toBe(e1.id);
+        expect(deleted.metadata.deleteTimestamp).toBeDefined();
+        expect(await repository.has(e1.id)).toBe(false);
+        expect(await repository.tryLoad(e1.id)).toBeUndefined();
+        expect(await repository.count()).toBe(0);
+        const allWithDeleted = await repository.loadAll({ withDeleted: true });
+        expect(allWithDeleted).toHaveLength(1);
+        expect(allWithDeleted[0].id).toBe(e1.id);
     });
     test('should soft delete multiple entities by IDs', async () => {
         await db.execute(sql `TRUNCATE TABLE ${sql.identifier(schema)}.${sql.identifier('soft_delete_entities')} CASCADE`);
-        await runInInjectionContext(injector, async () => {
-            const repository = injectRepository(SoftDeleteEntity);
-            const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
-            const e2 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E2' }));
-            const deleted = await repository.deleteMany([e1.id, e2.id]);
-            expect(deleted).toHaveLength(2);
-            expect(await repository.count()).toBe(0);
-            expect(await repository.countByQuery({}, { withDeleted: true })).toBe(2);
-        });
+        const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
+        const e2 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E2' }));
+        const deleted = await repository.deleteMany([e1.id, e2.id]);
+        expect(deleted).toHaveLength(2);
+        expect(await repository.count()).toBe(0);
+        expect(await repository.countByQuery({}, { withDeleted: true })).toBe(2);
     });
     test('should soft delete entities by query', async () => {
         await db.execute(sql `TRUNCATE TABLE ${sql.identifier(schema)}.${sql.identifier('soft_delete_entities')} CASCADE`);
-        await runInInjectionContext(injector, async () => {
-            const repository = injectRepository(SoftDeleteEntity);
-            await repository.insertMany([
-                Object.assign(new SoftDeleteEntity(), { name: 'A' }),
-                Object.assign(new SoftDeleteEntity(), { name: 'B' }),
-                Object.assign(new SoftDeleteEntity(), { name: 'A' }),
-            ]);
-            const deleted = await repository.deleteManyByQuery({ name: 'A' });
-            expect(deleted).toHaveLength(2);
-            expect(await repository.count()).toBe(1);
-            expect(await repository.countByQuery({}, { withDeleted: true })).toBe(3);
-        });
+        await repository.insertMany([
+            Object.assign(new SoftDeleteEntity(), { name: 'A' }),
+            Object.assign(new SoftDeleteEntity(), { name: 'B' }),
+            Object.assign(new SoftDeleteEntity(), { name: 'A' }),
+        ]);
+        const deleted = await repository.deleteManyByQuery({ name: 'A' });
+        expect(deleted).toHaveLength(2);
+        expect(await repository.count()).toBe(1);
+        expect(await repository.countByQuery({}, { withDeleted: true })).toBe(3);
     });
     test('should not update soft-deleted entities by default', async () => {
         await db.execute(sql `TRUNCATE TABLE ${sql.identifier(schema)}.${sql.identifier('soft_delete_entities')} CASCADE`);
-        await runInInjectionContext(injector, async () => {
-            const repository = injectRepository(SoftDeleteEntity);
-            const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
-            await repository.delete(e1.id);
-            const updated = await repository.tryUpdate(e1.id, { name: 'Updated' });
-            expect(updated).toBeUndefined();
-            const loaded = await repository.tryLoad(e1.id, { withDeleted: true });
-            expect(loaded.name).toBe('E1');
-        });
+        const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
+        await repository.delete(e1.id);
+        const updated = await repository.tryUpdate(e1.id, { name: 'Updated' });
+        expect(updated).toBeUndefined();
+        const loaded = await repository.tryLoad(e1.id, { withDeleted: true });
+        expect(loaded.name).toBe('E1');
     });
     test('should support hard delete on soft-deleted entities', async () => {
         await db.execute(sql `TRUNCATE TABLE ${sql.identifier(schema)}.${sql.identifier('soft_delete_entities')} CASCADE`);
-        await runInInjectionContext(injector, async () => {
-            const repository = injectRepository(SoftDeleteEntity);
-            const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
-            await repository.delete(e1.id);
-            const hardDeleted = await repository.hardDelete(e1.id);
-            expect(hardDeleted.id).toBe(e1.id);
-            expect(await repository.countByQuery({}, { withDeleted: true })).toBe(0);
-        });
+        const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
+        await repository.delete(e1.id);
+        const hardDeleted = await repository.hardDelete(e1.id);
+        expect(hardDeleted.id).toBe(e1.id);
+        expect(await repository.countByQuery({}, { withDeleted: true })).toBe(0);
     });
     test('should ignore already soft-deleted entities when deleting again', async () => {
         await db.execute(sql `TRUNCATE TABLE ${sql.identifier(schema)}.${sql.identifier('soft_delete_entities')} CASCADE`);
-        await runInInjectionContext(injector, async () => {
-            const repository = injectRepository(SoftDeleteEntity);
-            const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
-            await repository.delete(e1.id);
-            const secondDelete = await repository.tryDelete(e1.id);
-            expect(secondDelete).toBeUndefined();
-        });
+        const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
+        await repository.delete(e1.id);
+        const secondDelete = await repository.tryDelete(e1.id);
+        expect(secondDelete).toBeUndefined();
     });
     test('should hard delete multiple entities by query (including soft-deleted)', async () => {
         await db.execute(sql `TRUNCATE TABLE ${sql.identifier(schema)}.${sql.identifier('soft_delete_entities')} CASCADE`);
-        await runInInjectionContext(injector, async () => {
-            const repository = injectRepository(SoftDeleteEntity);
-            const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
-            const e2 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E2' }));
-            await repository.delete(e1.id); // Soft delete E1
-            const hardDeleted = await repository.hardDeleteManyByQuery({});
-            expect(hardDeleted).toHaveLength(2); // Should hard delete both
-            expect(await repository.countByQuery({}, { withDeleted: true })).toBe(0);
-        });
+        const e1 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E1' }));
+        const e2 = await repository.insert(Object.assign(new SoftDeleteEntity(), { name: 'E2' }));
+        await repository.delete(e1.id); // Soft delete E1
+        const hardDeleted = await repository.hardDeleteManyByQuery({});
+        expect(hardDeleted).toHaveLength(2); // Should hard delete both
+        expect(await repository.countByQuery({}, { withDeleted: true })).toBe(0);
     });
 });

package/orm/tests/repository-types.test.js

@@ -9,16 +9,16 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { sql } from 'drizzle-orm';
 import { beforeAll, describe, expect, test } from 'vitest';
-import { Injector, runInInjectionContext } from '../../injector/index.js';
 import { Array, BooleanProperty, Integer, NumberProperty, string, StringProperty } from '../../schema/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
 import { Table } from '../decorators.js';
 import { Entity } from '../entity.js';
 import { JsonProperty, NumericDateProperty, TimestampProperty } from '../schemas/index.js';
-import { configureOrm, Database } from '../server/index.js';
-import { injectRepository } from '../server/repository.js';
+import { getRepository } from '../server/index.js';
 describe('ORM Repository Types (Integration)', () => {
     let injector;
     let db;
+    let repo;
     const schema = 'test_orm_types';
     let TypeEntity = class TypeEntity extends Entity {
         text;
@@ -66,14 +66,10 @@ describe('ORM Repository Types (Integration)', () => {
         Table('type_entities', { schema })
     ], TypeEntity);
     beforeAll(async () => {
-        injector = new Injector('Test');
-        configureOrm({
-            repositoryConfig: { schema },
-            connection: {
-                host: '127.0.0.1', port: 5432, user: 'tstdl', password: 'wf7rq6glrk5jykne', database: 'tstdl',
-            },
-        });
-        db = injector.resolve(Database);
+        ({ injector, database: db } = await setupIntegrationTest({
+            orm: { schema },
+        }));
+        repo = injector.resolve(getRepository(TypeEntity));
         await db.execute(sql `CREATE SCHEMA IF NOT EXISTS ${sql.identifier(schema)}`);
         await db.execute(sql `DROP TABLE IF EXISTS ${sql.identifier(schema)}.${sql.identifier('type_entities')} CASCADE`);
         await db.execute(sql `
@@ -96,123 +92,93 @@ describe('ORM Repository Types (Integration)', () => {
     `);
     });
     test('should persist and retrieve boolean values (true)', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const entity = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 't', int: 1, float: 1.1, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
-            }));
-            const loaded = await repo.load(entity.id);
-            expect(loaded.bool).toBe(true);
-        });
+        const entity = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 't', int: 1, float: 1.1, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
+        }));
+        const loaded = await repo.load(entity.id);
+        expect(loaded.bool).toBe(true);
     });
     test('should persist and retrieve boolean values (false)', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const entity = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'f', int: 1, float: 1.1, bool: false, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
-            }));
-            const loaded = await repo.load(entity.id);
-            expect(loaded.bool).toBe(false);
-        });
+        const entity = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'f', int: 1, float: 1.1, bool: false, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
+        }));
+        const loaded = await repo.load(entity.id);
+        expect(loaded.bool).toBe(false);
     });
     test('should persist and retrieve integer boundaries', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const maxInt = 2147483647;
-            const minInt = -2147483648;
-            const e1 = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'max', int: maxInt, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
-            }));
-            const l1 = await repo.load(e1.id);
-            expect(l1.int).toBe(maxInt);
-            const e2 = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'min', int: minInt, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
-            }));
-            const l2 = await repo.load(e2.id);
-            expect(l2.int).toBe(minInt);
-        });
+        const maxInt = 2147483647;
+        const minInt = -2147483648;
+        const e1 = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'max', int: maxInt, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
+        }));
+        const l1 = await repo.load(e1.id);
+        expect(l1.int).toBe(maxInt);
+        const e2 = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'min', int: minInt, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
+        }));
+        const l2 = await repo.load(e2.id);
+        expect(l2.int).toBe(minInt);
     });
     test('should persist and retrieve float precision', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const pi = 3.1415926535;
-            const entity = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'pi', int: 0, float: pi, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
-            }));
-            const loaded = await repo.load(entity.id);
-            expect(loaded.float).toBeCloseTo(pi);
-        });
+        const pi = 3.1415926535;
+        const entity = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'pi', int: 0, float: pi, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
+        }));
+        const loaded = await repo.load(entity.id);
+        expect(loaded.float).toBeCloseTo(pi);
     });
     test('should persist and retrieve numeric dates', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const today = 19723; // 2024-01-01
-            const entity = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'date', int: 0, float: 0, bool: true, numericDate: today, timestamp: new Date(), json: {}, tags: [],
-            }));
-            const loaded = await repo.load(entity.id);
-            expect(loaded.numericDate).toBe(today);
-        });
+        const today = 19723; // 2024-01-01
+        const entity = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'date', int: 0, float: 0, bool: true, numericDate: today, timestamp: new Date(), json: {}, tags: [],
+        }));
+        const loaded = await repo.load(entity.id);
+        expect(loaded.numericDate).toBe(today);
     });
     test('should persist and retrieve timestamps', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const now = new Date();
-            const entity = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'ts', int: 0, float: 0, bool: true, numericDate: 0, timestamp: now, json: {}, tags: [],
-            }));
-            const loaded = await repo.load(entity.id);
-            // Postgres stores microsecond precision, JS Date has millisecond.
-            // Drizzle custom type returns number (milliseconds).
-            // We accept a small difference due to precision loss or round-trip.
-            expect(typeof loaded.timestamp).toBe('number');
-            expect(Math.abs(loaded.timestamp - now.getTime())).toBeLessThan(2);
-        });
+        const now = new Date();
+        const entity = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'ts', int: 0, float: 0, bool: true, numericDate: 0, timestamp: now, json: {}, tags: [],
+        }));
+        const loaded = await repo.load(entity.id);
+        // Postgres stores microsecond precision, JS Date has millisecond.
+        // Drizzle custom type returns number (milliseconds).
+        // We accept a small difference due to precision loss or round-trip.
+        expect(typeof loaded.timestamp).toBe('number');
+        expect(Math.abs(loaded.timestamp - now.getTime())).toBeLessThan(2);
     });
     test('should persist and retrieve complex JSON', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const data = {
-                foo: 'bar',
-                nested: { a: 1, b: [true, false] },
-                nullVal: null,
-            };
-            const entity = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'json', int: 0, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: data, tags: [],
-            }));
-            const loaded = await repo.load(entity.id);
-            expect(loaded.json).toEqual(data);
-        });
+        const data = {
+            foo: 'bar',
+            nested: { a: 1, b: [true, false] },
+            nullVal: null,
+        };
+        const entity = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'json', int: 0, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: data, tags: [],
+        }));
+        const loaded = await repo.load(entity.id);
+        expect(loaded.json).toEqual(data);
     });
     test('should persist and retrieve arrays', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const tags = ['a', 'b', 'c'];
-            const entity = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'array', int: 0, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags,
-            }));
-            const loaded = await repo.load(entity.id);
-            expect(loaded.tags).toEqual(tags);
-        });
+        const tags = ['a', 'b', 'c'];
+        const entity = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'array', int: 0, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags,
+        }));
+        const loaded = await repo.load(entity.id);
+        expect(loaded.tags).toEqual(tags);
     });
     test('should persist and retrieve empty arrays', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            const entity = await repo.insert(Object.assign(new TypeEntity(), {
-                text: 'empty-array', int: 0, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
-            }));
-            const loaded = await repo.load(entity.id);
-            expect(loaded.tags).toEqual([]);
-        });
+        const entity = await repo.insert(Object.assign(new TypeEntity(), {
+            text: 'empty-array', int: 0, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
+        }));
+        const loaded = await repo.load(entity.id);
+        expect(loaded.tags).toEqual([]);
     });
     test('should fail on integer overflow', async () => {
-        await runInInjectionContext(injector, async () => {
-            const repo = injectRepository(TypeEntity);
-            // Max int is 2147483647
-            const overflow = 3000000000;
-            await expect(repo.insert(Object.assign(new TypeEntity(), {
-                text: 'overflow', int: overflow, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
-            }))).rejects.toThrow(); // Postgres should reject
-        });
+        // Max int is 2147483647
+        const overflow = 3000000000;
+        await expect(repo.insert(Object.assign(new TypeEntity(), {
+            text: 'overflow', int: overflow, float: 0, bool: true, numericDate: 0, timestamp: new Date(), json: {}, tags: [],
+        }))).rejects.toThrow(); // Postgres should reject
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.145",
+  "version": "0.93.146",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"

package/task-queue/tests/worker.test.js

@@ -1,7 +1,6 @@
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
 import { CancellationToken } from '../../cancellation/index.js';
-import { runInInjectionContext } from '../../injector/index.js';
-import { injectRepository } from '../../orm/server/index.js';
+import { getRepository } from '../../orm/server/index.js';
 import { TaskProcessResult, TaskQueueProvider, TaskStatus } from '../../task-queue/index.js';
 import { PostgresTask } from '../../task-queue/postgres/index.js';
 import { setupIntegrationTest } from '../../testing/index.js';
@@ -11,8 +10,10 @@ describe('Worker & Base Class Tests', () => {
     let queue;
     let token;
     let otherQueueName;
+    let taskRepository;
     beforeAll(async () => {
         ({ injector } = await setupIntegrationTest({ modules: { taskQueue: true } }));
+        taskRepository = injector.resolve(getRepository(PostgresTask));
         otherQueueName = `other-queue-${crypto.randomUUID()}`;
     });
     beforeEach(() => {
@@ -25,11 +26,10 @@ describe('Worker & Base Class Tests', () => {
     });
     afterEach(async () => {
         token.set();
-        const repository = runInInjectionContext(injector, () => injectRepository(PostgresTask));
         const namespace = queue.getTransactionalContextData().namespace;
         // Clear foreign keys
-        await repository.updateManyByQuery({ namespace }, { parentId: null });
-        await repository.updateManyByQuery({ namespace: otherQueueName }, { parentId: null });
+        await taskRepository.updateManyByQuery({ namespace }, { parentId: null });
+        await taskRepository.updateManyByQuery({ namespace: otherQueueName }, { parentId: null });
         await queue.clear();
         const queueProvider = injector.resolve(TaskQueueProvider);
         await queueProvider.get(otherQueueName).clear();

package/testing/README.md

@@ -80,11 +80,16 @@ The `setupIntegrationTest` utility (found in `source/testing/integration-setup.t
 4.  **Schema Isolation**: Automatically creates and uses PostgreSQL schemas for isolation.
 5.  **Modules**: Optional configuration for `taskQueue`, `authentication`, `objectStorage`, `notification`, etc.
 
-### Integration Test Example
+Integration tests typically require an injection context to resolve services and repositories. You can use the `testInInjector` (or `itInInjector`) helper to automatically wrap your test body.
+
+> [!IMPORTANT]
+> `testInInjector` is designed for test files where a **single injector** is shared across all tests (typically initialized in `beforeAll`). It accepts a `ValueOrProvider<Injector>`, allowing you to pass a getter function (e.g., `() => injector`) if the injector variable is initialized late.
+>
+> If your tests require a fresh injector per test case (e.g. `setupIntegrationTest` in `beforeEach`), you can still use `testInInjector` by passing a provider.
 
 ```typescript
-import { beforeAll, describe, expect, it } from 'vitest';
-import { setupIntegrationTest } from '#/testing/index.js';
+import { beforeAll, describe, expect } from 'vitest';
+import { setupIntegrationTest, testInInjector } from '#/testing/index.js';
 import { MyService } from '../my-service.js';
 
 describe('MyService Integration', () => {
@@ -98,19 +103,32 @@ describe('MyService Integration', () => {
     }));
   });
 
-  it('should process data through the database', async () => {
+  testInInjector('should process data through the database', injector, async () => {
     const service = injector.resolve(MyService);
     const result = await service.process();
     expect(result.success).toBe(true);
   });
+
+  // Using a provider function to defer resolution of the 'injector' variable when using `beforeEach` for injector setup
+  testInInjector('should process data through the database', () => injector, async () => { ... });
 });
 ```
 
 ## Best Practices & Guidelines
 
-### 1. Isolation
-
-- **Schemas**: Always use a unique PostgreSQL schema for your integration test suite via `orm: { schema: '...' }`.
+### 1. Isolation & Performance
+
+- **`beforeAll` vs `beforeEach`**:
+  - **Use `beforeAll` (Recommended)**: For most integration tests. It's significantly faster as it creates the schema and initializes the injector once.
+  - **Use `beforeEach`**: Use this only when:
+    - You need a completely clean Injector state for every test (e.g. if singletons are being mutated and cannot be reset).
+    - You are testing the initialization or disposal logic of your services.
+    - Each test requires a different module configuration in `setupIntegrationTest`.
+  - **Data Reset**:
+    - **`clearTenantData` (Best for Parallelism)**: If your tests use random `tenantId`s, use this in `afterEach` or `beforeEach`. It allows multiple tests within the same schema to run without interfering with each other's data.
+    - **`truncateTables` (Use with Caution)**: Only suitable if you are certain that no other tests are concurrently using the same database tables (even with different tenant IDs), as `TRUNCATE` affects the entire table and can cause flakiness in parallel environments.
+- **Unit vs. Integration**: Prefer integration tests over unit tests when reasonably possible to cover more code paths and reduce the need for extensive mocking.
+- **Parallelism**: Vitest runs test files in parallel. Always use unique resource names (e.g., using `crypto.randomUUID()`) to avoid flaky tests and cross-file interference.
 - **Resource Naming**: When testing shared infrastructure (Task Queues, S3 Buckets, Rate Limiters), append a random suffix or timestamp to the resource name (e.g., `const queueName = \`test-queue-${crypto.randomUUID()}\``).
 - **Cleanup**: Use `truncateTables` or `dropTables` in `beforeAll` or `beforeEach` to ensure a clean state.
 - **Tenant Data**: Use `clearTenantData` if your tests are multi-tenant and use random tenant IDs to avoid collisions when concurrently running tests.
@@ -124,24 +142,26 @@ describe('MyService Integration', () => {
   const mailServiceMock = { send: vi.fn() };
   injector.register(MailService, { useValue: mailServiceMock });
   ```
-- **Injection Context**: Any code that uses repositories or services relying on `inject()` outside of a class constructor/initializer **must** be wrapped in `runInInjectionContext(injector, async () => { ... })`.
+- **Injection Context**: Any code that uses repositories or services relying on `inject()` outside of a class constructor/initializer **must** be wrapped in an injection context.
+  - **Preferred**: Use `testInInjector` (or `itInInjector`) for the entire test body.
+  - **Alternative**: Use `runInInjectionContext(injector, async () => { ... })` for specific blocks within a test or hook.
 - **Mock Reset**: Always call `vi.clearAllMocks()` in `beforeEach` if using spys or mocks to ensure test independence.
 
 ### 3. Integration Test Patterns
 
 - **Schema Management**:
   - **Preferred**: Use the `modules` option in `setupIntegrationTest`. This automatically runs the necessary migrations for standard modules (e.g., `taskQueue`, `authentication`, `notification`).
-  - **Fallback**: Use Manual DDL via `database.execute(sql\`...\`)`**only** for test-specific entities (like local`@Table`classes defined inside your test file) that are not part of a standard module. Always call`dropTables` before creating them to ensure a fresh start.
+  - **Fallback**: Use Manual DDL via `database.execute(sql\`...\`)` **only** for test-specific entities (like local `@Table` classes defined inside your test file) that are not part of a standard module. Always call `dropTables` before creating them to ensure a fresh start.
+- **Repositories**: You can inject ad-hoc repositories inside an injection context:
+  ```typescript
+  const repo = injectRepository(MyEntity);
+  ```
 - **Background Workers**: When testing workers or loops, use a `CancellationToken` to stop them in `afterEach` or `afterAll`.
+- **Polling & Waiting**: When testing asynchronous background effects (like a task queue processing a task), avoid arbitrary `timeout()` calls if possible. Instead, use a polling loop or wait for a specific database state.
 - **Timeouts**: Use the `timeout(ms)` helper from `#/utils/timing.js` for tests involving refills, retries, or background processing. Prefer `vi.useFakeTimers()` only when real-time passage is too slow for the test suite.
 - **Logging**: Test should generally not output logs unless for active debugging. Use try-catch for expected errors and assert on the error message instead of relying on logs.
 
-### 4. Performance
-
-- Use `beforeAll` for heavy setup (like schema and table creation) and `beforeEach` for lightweight data resetting (truncation).
-- Prefer integration tests over unit tests when reasonably possible to cover more code paths and reduce the need for extensive mocking and stubbing.
-
-### 5. Coding Style
+### 4. Coding Style
 
 - **Explicit Types**: Use explicit return types for methods and functions.
 - **Async/Await**: Always use `async/await` for asynchronous code to improve readability and error handling.
@@ -149,9 +169,11 @@ describe('MyService Integration', () => {
 - **Avoid `any`**: Strive to use specific types or `unknown` if required to maintain type safety.
 - **Descriptive Names**: Use descriptive names for test files, cases and variables to improve readability.
 
-### 6. Common Helpers (from `source/testing/`)
+### 5. Common Helpers (from `source/testing/`)
 
 - `setupIntegrationTest(options)`: Main entry point for integration tests.
+- `testInInjector(name, injector, fn, options)`: Runs a test within an injection context.
+- `itInInjector`: Alias for `testInInjector`.
 - `truncateTables(database, schema, tables)`: Clears data from specified tables.
 - `dropTables(database, schema, tables)`: Drops specified tables.
 - `clearTenantData(database, schema, tables, tenantId)`: Deletes data for a specific tenant.

package/testing/integration-setup.d.ts

@@ -1,4 +1,6 @@
+/** biome-ignore-all lint/nursery/useExpect: helper file */
 import type { PoolConfig } from 'pg';
+import { type TestOptions } from 'vitest';
 import { type AuthenticationAncillaryService } from '../authentication/server/index.js';
 import { Injector } from '../injector/index.js';
 import { LogLevel } from '../logger/index.js';
@@ -6,6 +8,7 @@ import { type S3ObjectStorageProviderConfig } from '../object-storage/s3/index.j
 import type { EntityType } from '../orm/entity.js';
 import { Database } from '../orm/server/index.js';
 import type { Type } from '../types/index.js';
+import { type ValueOrProvider } from '../utils/value-or-provider.js';
 export type IntegrationTestOptions = {
     dbConfig?: Partial<PoolConfig>;
     orm?: {
@@ -43,6 +46,14 @@ export type TestContext = {
  * Standard setup for integration tests.
  */
 export declare function setupIntegrationTest(options?: IntegrationTestOptions): Promise<TestContext>;
+/**
+ * A wrapper for vitest's `test` that automatically runs the test function in the provided injector's context.
+ * @param name The name of the test.
+ * @param injector The injector to use for the context.
+ * @param fn The test function.
+ * @param options Vitest test options.
+ */
+export declare function testInInjector(name: string, injector: ValueOrProvider<Injector>, fn: () => any, options?: number | TestOptions): void;
 /**
  * Helper to truncate specific tables in a schema.
  * Useful in beforeEach() to reset state.