@tstdl/base 0.93.145 → 0.93.147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.93.145",
+  "version": "0.93.147",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"
@@ -152,8 +152,8 @@
     "type-fest": "^5.4"
   },
   "peerDependencies": {
-    "@aws-sdk/client-s3": "^3.999",
-    "@aws-sdk/s3-request-presigner": "^3.999",
+    "@aws-sdk/client-s3": "^3.1000",
+    "@aws-sdk/s3-request-presigner": "^3.1000",
     "@genkit-ai/google-genai": "^1.29",
     "@google-cloud/storage": "^7.19",
     "@toon-format/toon": "^2.1.0",

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.

package/testing/integration-setup.js

@@ -1,5 +1,6 @@
+/** biome-ignore-all lint/nursery/useExpect: helper file */
 import { sql } from 'drizzle-orm';
-import { afterAll } from 'vitest';
+import { afterAll, test } from 'vitest';
 import { configureApiServer } from '../api/server/index.js';
 import { configureAudit } from '../audit/index.js';
 import { AuthenticationApiClient } from '../authentication/client/api.client.js';
@@ -26,7 +27,8 @@ import { configureDefaultSignalsImplementation } from '../signals/implementation
 import { configurePostgresTaskQueue } from '../task-queue/postgres/index.js';
 import * as configParser from '../utils/config-parser.js';
 import { objectEntries } from '../utils/object/object.js';
-import { assertDefinedPass, isDefined, isNotNull, isString } from '../utils/type-guards.js';
+import { assertDefinedPass, isDefined, isNotNull, isNumber, isString, isUndefined } from '../utils/type-guards.js';
+import { resolveValueOrProvider } from '../utils/value-or-provider.js';
 /**
  * Standard setup for integration tests.
  */
@@ -167,16 +169,22 @@ export async function setupIntegrationTest(options = {}) {
     return { injector, database };
 }
 /**
- * Helper to run a migration safely with a database advisory lock to prevent race conditions.
+ * 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.
  */
-async function runMigrationSafely(database, migration) {
-    const lockId = 123456789; // Fixed lock ID for migrations
-    await database.execute(sql `SELECT pg_advisory_lock(${lockId})`);
-    try {
-        await migration();
+export function testInInjector(name, injector, fn, options) {
+    if (isUndefined(options) || isNumber(options)) {
+        test(name, async () => {
+            await runInInjectionContext(resolveValueOrProvider(injector), fn);
+        }, options);
     }
-    finally {
-        await database.execute(sql `SELECT pg_advisory_unlock(${lockId})`);
+    else {
+        test(name, options, async () => {
+            await runInInjectionContext(resolveValueOrProvider(injector), fn);
+        });
     }
 }
 /**
@@ -187,19 +195,15 @@ export async function truncateTables(database, schema, tables) {
     if (tables.length == 0) {
         return;
     }
-    const lockId = 987654321; // Different lock ID for table maintenance
-    await database.execute(sql `SELECT pg_advisory_lock(${lockId})`);
-    try {
+    const lockName = `tstdl:maintenance:${schema}`;
+    await runWithAdvisoryLock(database, lockName, async () => {
         // Using CASCADE to handle foreign keys automatically
         for (const table of tables) {
             const tableName = isString(table) ? table : getEntityTableName(table);
             const tableSchema = isString(table) ? schema : getEntitySchema(table, schema);
             await database.execute(sql `TRUNCATE TABLE ${sql.identifier(tableSchema)}.${sql.identifier(tableName)} CASCADE`);
         }
-    }
-    finally {
-        await database.execute(sql `SELECT pg_advisory_unlock(${lockId})`);
-    }
+    });
 }
 /**
  * Helper to delete data for a specific tenant from specific tables.
@@ -209,18 +213,15 @@ export async function clearTenantData(database, schema, tables, tenantId) {
     if (tables.length == 0) {
         return;
     }
-    const lockId = 987654321;
-    await database.execute(sql `SELECT pg_advisory_lock(${lockId})`);
-    try {
+    // Use a lock that is specific to both the schema AND the tenant
+    const lockName = `tstdl:maintenance:${schema ?? 'default'}:${tenantId}`;
+    await runWithAdvisoryLock(database, lockName, async () => {
         for (const table of tables) {
             const tableName = isString(table) ? table : getEntityTableName(table);
             const tableSchema = isString(table) ? assertDefinedPass(schema, 'Schema not provided') : getEntitySchema(table, schema);
             await database.execute(sql `DELETE FROM ${sql.identifier(tableSchema)}.${sql.identifier(tableName)} WHERE tenant_id = ${tenantId}`);
         }
-    }
-    finally {
-        await database.execute(sql `SELECT pg_advisory_unlock(${lockId})`);
-    }
+    });
 }
 /**
  * Helper to drop specific tables.
@@ -230,16 +231,42 @@ export async function dropTables(database, schema, tables) {
     if (tables.length == 0) {
         return;
     }
-    const lockId = 987654321;
-    await database.execute(sql `SELECT pg_advisory_lock(${lockId})`);
-    try {
+    const lockName = `tstdl:maintenance:${schema ?? 'default'}`;
+    await runWithAdvisoryLock(database, lockName, async () => {
         for (const table of tables) {
             const tableName = isString(table) ? table : getEntityTableName(table);
             const tableSchema = isString(table) ? assertDefinedPass(schema, 'Schema not provided') : getEntitySchema(table, schema);
             await database.execute(sql `DROP TABLE IF EXISTS ${sql.identifier(tableSchema)}.${sql.identifier(tableName)} CASCADE`);
         }
-    }
-    finally {
-        await database.execute(sql `SELECT pg_advisory_unlock(${lockId})`);
+    });
+}
+/**
+ * Helper to run a migration safely with a database advisory lock to prevent race conditions.
+ */
+async function runMigrationSafely(database, migration) {
+    const lockName = 'tstdl:migration';
+    await runWithAdvisoryLock(database, lockName, migration);
+}
+async function runWithAdvisoryLock(database, lockName, fn) {
+    // We use pg_try_advisory_lock in a loop with small random delays to avoid deadlocks
+    // which sometimes happen with pg_advisory_lock under very high parallelism in Vitest
+    const start = Date.now();
+    const timeout = 30000; // 30s timeout for maintenance tasks
+    while (true) {
+        const { rows: [result] } = await database.execute(sql `SELECT pg_try_advisory_lock(hashtext(${lockName})) as locked`);
+        if (result?.locked) {
+            try {
+                await fn();
+                return;
+            }
+            finally {
+                await database.execute(sql `SELECT pg_advisory_unlock(hashtext(${lockName}))`);
+            }
+        }
+        if (Date.now() - start > timeout) {
+            throw new Error(`Timeout while waiting for advisory lock: ${lockName}`);
+        }
+        // Small random delay between 10ms and 100ms
+        await new Promise((resolve) => setTimeout(resolve, 10 + Math.random() * 90));
     }
 }